project-audit

project-audit

触发方式：/project-audit、audit project、review claude config、sdd diagnostic、project health check

---

对 Claude/SDD 配置进行只读诊断。流程： /project-audit → audit-report.md → /project-fix → /project-audit (verify)。这份 报告就是 /project-fix 的实现规范。核心流程：发现 → 评估 → 报告（流程稳定；规则会不断演进）。将报告保存到 [project_root]/.claude/audit-report.md。

同级参考文件——REPORT_TEMPLATE.md（输出格式）、SCORING.md （100 分的分配与解读）、PHASE_A_SCRIPT.md（发现脚本与架构）。

维度类别

类别	维度	分数影响
计分项	D1、D2、D3、D4、D6、D8	95 分
仅供参考	D9、D10、D11、D12、D13、D14	无

D5 和 D7 已移除。除非另有说明，仅供参考的维度不会影响分数。

兼容性策略——全局配置豁免

IS_GLOBAL_CONFIG=1 → 方法论仓库不是其自身部署的使用者。跳过项：

维度	检查项	全局配置时跳过
D1	技术栈 / package.json	跳过
D1	## Architecture 章节	跳过（在 README 中）
D1	技能注册表	始终跳过（原则 2——框架会自动发现）
D1	ai-context/ 路径引用	跳过
D2	记忆（ai-context/）	跳过该维度；计分时不适用
D4a	注册表与磁盘内容	跳过

原因：ai-context/ 由本仓库通过 /project-setup 部署到使用者项目中——审计方法论仓库是否包含该目录，属于范畴错误。 计分：D2 → 不适用；分母变为 70（基础分 95 − 25）。最终分数 = round(actual/70*100)。

---

流程

读取实际文件。不要臆测。系统地运行各维度检查。

阶段 A——发现

运行一次 PHASE_A_SCRIPT.md；记录 key=value 输出；运行脚本后的 “Legacy commands/ detection”。每次审计最多进行 3 次 Bash 调用。

阶段 B——逐维度评估

应用各维度检查。发现项需标明严重程度（CRITICAL/HIGH/MEDIUM/LOW/INFO），并可选包含 FIX_MANIFEST 条目。

维度 1 — CLAUDE.md

项目类型检测：IS_GLOBAL_CONFIG=1 → global-config。将根目录下的 CLAUDE.md 视为与 .claude/CLAUDE.md 等效。在报告中注明 Project Type。

检查项	严重性
存在 .claude/CLAUDE.md（global-config 时检查根目录）	CRITICAL
非空（>50 行）	CRITICAL
包含 Stack 部分（## Tech Stack 或 ## Stack）	CRITICAL
Stack 至少包含 3 项明确标注版本的技术	CRITICAL
Stack 与 package.json / pyproject.toml 相符	HIGH
包含 ## Architecture 部分	HIGH
包含 Skills 注册表	HIGH
包含不可违背规则部分	MEDIUM
包含 Plan Mode 部分	LOW
提及 SDD（/sdd-*）	HIGH
ai-context/ 路径引用正确	MEDIUM

根据 ADR-004，Stack 的严重性为 CRITICAL（所有引用技术的技能都会依赖它）。IS_GLOBAL_CONFIG=1 时的豁免项：参见“兼容性政策”。

Stack 比对：从 package.json / 等效文件中提取前 5–10 个依赖项， 并与 CLAUDE.md 比较。将差异报告为 declared X.Y, actual A.B。

模板路径验证：定位 ## Documentation Conventions 部分， 提取匹配 docs/templates/*.md 的路径，并验证每个路径对应的文件都存在。每个缺失文件 → MEDIUM + required_actions.medium，type: create_file。如果未找到 此类模式，则完全跳过。

---

维度 2 — 记忆（ai-context/）

当 IS_GLOBAL_CONFIG=1 时完全跳过 — 输出 INFO "D2 skipped — global-config repos do not use ai-context/"。D2 → N/A（从分母中排除 25 分）。参见兼容性政策。

对于标准项目：

文件	最少行数	备注
ai-context/stack.md	> 30
ai-context/architecture.md	> 40
ai-context/conventions.md	> 30
ai-context/known-issues.md	> 10	新项目可以简短
ai-context/changelog-ai.md	> 5	至少有一条记录

文件位置可以是 ai-context/ 或 docs/ai-context/。两处都要检查。

内容检查（对每个现存文件）：

• stack.md：前 5 个依赖项的版本与 package.json 相符。
• architecture.md：其中提到的目录确实存在于磁盘上。
• conventions.md：文档所述约定在 2–3 个真实示例文件中均有体现。
• known-issues.md：包含实际内容，而非 [To confirm] / [Empty] 占位内容。
• changelog-ai.md：至少包含一条 ## YYYY-MM-DD 记录。

占位短语检测——扫描内容中的以下短语（方括号内不区分大小写， 纯文本 TODO 区分大小写）：[To be filled]、[empty]、 [TBD]、[placeholder]、[To confirm]、[Empty]、纯大写的 TODO。 每次匹配 → HIGH "[filename] appears to contain unfilled placeholder content"。即使文件行数达标，也将其视为功能性空文件。 将其加入 required_actions.high，并设置 type: update_file。

stack.md 版本数量——统计匹配 x.y、x.y.z 或 vX 的行数。 少于 3 行 → MEDIUM "stack.md lists fewer than 3 technologies with concrete versions — minimum is 3"。如果 stack.md 不存在或已判定为占位文件，则跳过。

用户文档时效性（针对 ai-context/scenarios.md 和 ai-context/quick-reference.md）：

• 不存在 → LOW "[filename] missing — create via /project-onboard or manually"。
• 存在 → 在前 10 行中搜索 ^> Last verified: (\d{4}-\d{2}-\d{2})$。 缺失或格式错误 → LOW。超过 90 天 → LOW，并注明时长。所有发现均为 LOW， 不扣除 D2 分数。

---

维度 3 — SDD 编排器

3a. 全局 SDD 技能 — ~/.claude/skills/ 中必须存在 8 个阶段技能： sdd-explore、sdd-propose、sdd-spec、sdd-design、sdd-tasks、sdd-apply、 sdd-verify、sdd-archive。缺少任意一项 → 严重。

3b. Engram 可用性 — 调用 mem_context。可访问 → 记录信息日志。 无法访问 → HIGH "Engram not reachable — SDD artifacts will not persist"。

3c. CLAUDE.md 提及 SDD — 包含任意 /sdd-* → 若缺失则为 HIGH； 若未包含解释 SDD 流程的章节 → LOW。

3d. 孤立的变更 — mem_search(query: "sdd/", project: "{project}")， 筛选出 last_updated > 14 days ago 且没有 archive-report 的状态制品。列出它们。

3e. Hook 脚本是否存在 — 对每个存在的设置文件 （settings.json、.claude/settings.json、settings.local.json），定位 hooks 键并提取脚本路径。每个在磁盘上不存在的脚本 → HIGH + required_actions.high type: create_file。没有 hooks 键时跳过。

3f. 活跃变更冲突检测：

1. 在 engram 中搜索活跃变更（没有 archive-report）。获取每项变更的 design.md。
2. 定位 ## File Change Matrix 表格。提取 File 列。规范化： 转为小写 + 去除开头的 ./。
3. 如果有 design.md 的活跃变更少于 2 项，则跳过。
4. 求路径集合的交集。每个重叠项 → MEDIUM "Concurrent file modification conflict: [path] is targeted by both [change-A] and [change-B]"。添加到 violations[]，rule: "D3-active-changes-conflict"。

规范化仅处理转为小写和去除开头的 ./。其他格式不一致的情况不会被检测到。

---

维度 4 — 技能质量

4a. 注册表与磁盘（双向检查）：CLAUDE.md 中的每项技能都必须存在于磁盘上；磁盘上的每项技能也必须出现在 CLAUDE.md 中。双向报告不匹配项。

当 IS_GLOBAL_CONFIG=1 时跳过 4a（没有手动注册表；原则 2）。 输出 INFO "D4a skipped — harness auto-discovery, not a manual registry"。 4b 和 4c 仍适用。

4b. 最低内容要求——针对每个技能文件：

• 少于 30 行 → 可能是空壳文件。
• 根据格式检查结构（参见 docs/format-types.md）：
  1. 解析 YAML frontmatter，提取 format:。若不存在 → 按 procedural 处理。
  2. 未知值 → 输出 INFO，按 procedural 处理。

解析后的格式	必需章节	缺少时的问题（MEDIUM）
procedural	## Process	"procedural skill [name] missing ## Process section"
reference	至少包含 ## Patterns/## Critical Patterns 之一，且包含 ## Examples/## Code Examples 之一	"reference skill [name] missing (## Patterns or ## Critical Patterns) or (## Examples or ## Code Examples)"
anti-pattern	## Anti-patterns 或 ## Critical Patterns	"anti-pattern skill [name] missing ## Anti-patterns or ## Critical Patterns section"

所有格式中，缺少 **Triggers** 或 ## Rules → MEDIUM。reference/anti-pattern 缺少 ## Process 不算问题。

每项问题 → required_actions.medium、 type: skill_quality_action、 action_type: add_missing_section、 target: [skill path]、 missing_sections: ["[heading]"]。

4c. 相关技术技能覆盖率（计分 0–10 分）：

技术栈 → 技能映射：React 18+ → react-19、Next.js 14+ → nextjs-15、 TypeScript → typescript、Zustand → zustand-5、Tailwind → tailwind-4、 Zod → zod-4、Playwright → playwright、Prisma → prisma、 React Native / Expo → react-native、Go → go-testing。

覆盖率规则（技术技能本地化策略）：如果某项技能存在于项目本地的 .claude/skills/<name>/ 或全局的 ~/.claude/skills/<name>/，则视为“已覆盖”。技术技能应放在本地；只有元技能/编排技能才应放在全局。项目本地已有 zod-4，却因全局没有而扣分，是分类错误。

适用技能的覆盖率	分数
100% 已覆盖或无适用技能	10
≥ 75%	8
50–74%	5
25–49%	2
< 25%	0

“适用” = 项目使用该技术，且本地或全局存在匹配的技能。D4 最高：20 分（4a+4b = 10；4c = 10）。

---

维度 6 — 交叉引用完整性

Claude 配置中引用的所有内容都必须存在于磁盘上。

来源	目标
CLAUDE.md 中的 ## Documentation	.claude/docs/
CLAUDE.md 中的 Templates 章节	.claude/templates/
技能中的路径	/lib/、/domain/、pages/api/ 等
ai-context/architecture.md 中的目录	项目文件系统
命令中引用的技能	技能文件

每处失效的引用：来源文件、大致行号、缺失路径。

维度 8 — 测试与验证

8a. 已配置或可检测到测试运行器 → 缺失时为 HIGH。ai-context/ 中有测试策略文档 → 缺失时为 MEDIUM。

8b. 对 engram 中的每个 archive-report，验证是否存在 verify-report 且引用了工具执行结果。缺失 → HIGH。

8c. 对每个包含 tasks 的活动变更，验证任务计划是否包含验证标准。对每个包含 design 的活动变更，验证设计是否定义了测试方法。

---

维度 9 — 项目技能质量（仅供参考）

当 $LOCAL_SKILLS_DIR 不存在时跳过 — 输出 "No [value] directory found — Dimension 9 skipped"。不扣分。

全局配置循环检测：审计 global-config 仓库时，skills/ 下的每个子目录在 ~/.claude/skills/ 中都有对应目录（通过 install.sh 安装相同文件）。所有目录的处置方式均为 keep — 这是预期行为。

D9-2 重复项 — 对 $LOCAL_SKILLS_DIR 下的每个子目录： 若 ~/.claude/skills/<name>/ 存在，则处置方式为 move-to-global（若内容不同）或 delete（若内容相同）。全局目录不可读 → INFO，处置方式为 keep。

D9-3 结构完整性 — 应用 D4b 格式感知检查。缺少必需章节或缺少 SKILL.md → 处置方式为 update，操作为 add_missing_section。

D9-4 语言合规性 — 对围栏代码块之外的正文应用 D4e 启发式检查。非英文文本 → 处置方式为 update，操作为 flag_language_violation，严重性为 INFO（不扣分）。

D9-5 技术栈相关性 — 检查触发条件行和标题中的技术引用。若 ai-context/stack.md 和 package.json/pyproject.toml 中均未提及 → 处置方式为 update，操作为 flag_irrelevant，严重性为 INFO。没有技术栈来源 → 输出 "Stack relevance check skipped — no stack source found"。

---

维度 10 — 功能文档覆盖率（仅供参考）

未检测到任何功能时跳过。

由配置驱动 — 若项目的 config.yaml 包含 feature_docs: 键，则读取 convention（skill|markdown|mixed）、paths 和 feature_detection。

启发式回退 — 按以下顺序使用来源：

1. $LOCAL_SKILLS_DIR 中的非 SDD 技能（名称不以 sdd-、project-、memory-、skill- 开头）。
2. docs/features/ 或 docs/modules/ 中的 *.md 文件。
3. src/features/、src/modules/、app/ 中包含 README.md 的子目录。

始终排除：shared、utils、common、lib、types、hooks、components。排除后为空 → 输出 "No feature directories detected — Dimension 10 skipped"。

逐项功能检查：

• D10-a 覆盖率：按约定存在文档则为 PASS，否则为 FAIL。
• D10-b 结构：SKILL.md → 存在 frontmatter、**Triggers**、## Process 和 ## Rules 则为 PASS。其他 .md 文件 → 存在 H1 和 ≥1 个 H2 则为 PASS。
• D10-c 时效性：提取路径 /src/[^\s]+、/lib/[^\s]+、/app/[^\s]+。每个缺失路径 → 标记为过时。
• D10-d 注册表一致性：.claude/skills/ 中的 SKILL.md 未列入 CLAUDE.md 注册表 → INFO（不是警告）。

D10 发现项不得出现在 required_actions 或 skill_quality_actions 中。

---

维度 11 — 内部一致性（仅供参考）

仅使用 Read/Glob/Grep — 不使用 Bash。只有在 $LOCAL_SKILLS_DIR 和根目录 CLAUDE.md 均不存在时才跳过。

D11-a 数量一致性 — 通过 CLAIM_PATTERN = /(\d+)\s+(Dimensions?|Steps?|Rules?|Phases?|Checks?|Sub-checks?)/i 从标题和引用块行中提取数量声明。统计匹配的正文部分。数量不匹配 → INFO。不要匹配代码块中的内容。

D11-b 编号连续性 — 模式： /^#{2,3}\s+.*Step\s+(\d+)/im、Dimension\s+(\d+)、Phase\s+(\d+)、 /^#{2,4}\s+.*D(\d+)/m。对编号排序，检测缺漏和重复。至少需要 2 个成员。严重性为 INFO。

D11-c Frontmatter 与正文一致性 — 若 description 中包含数字声明，则使用 D11-a 逻辑验证。不匹配 → INFO。

所有 D11 发现项 → violations[]，严重性为 info，规则名称为 D11-count-consistency、D11-numbering-continuity、 D11-frontmatter-body。绝不出现在 required_actions 中。

---

维度 12 — ADR 覆盖情况（仅供参考）

启用条件：CLAUDE.md 包含字符串 docs/adr/。如果不存在 → 输出 INFO， 并跳过。

D12-1：ADR_README_EXISTS=0 → HIGH "CLAUDE.md references docs/adr/ but docs/adr/README.md is missing" + required_actions.high type: create_file。

D12-2：Glob docs/adr/NNN-*.md。没有匹配项 → INFO "docs/adr/ contains no ADR files yet"。对于每个 ADR：搜索 ## Status 标题或 frontmatter status: 字段。两者均不存在 → MEDIUM "ADR file [filename] is missing a valid status field" + required_actions.medium type: update_file。有效值： accepted、deprecated、superseded；允许自定义值，不验证其取值。

---

维度 13 — 规范覆盖情况（仅供参考）

启用条件：Engram 可访问，并且 mem_search(query: "sdd/") 返回规范 制品。

D13-1：对于每个 spec.md，提取类似路径的引用（包含 /，不含 空格，不在 URL 或围栏代码中）。检查 [project_root]/[path] 是否存在。 不存在 → INFO "Spec artifact references a path that no longer exists: [path]"。添加到 violations[]， rule: "D13-stale-path-reference"，severity: "info"， file: "engram spec artifact"。INFO 级发现不加入 required_actions。

---

维度 14 — 预算合规性（仅供参考）

每次审计都会运行。

1. 读取当前生效的 CLAUDE.md；统计字符数。按与 D1 相同的方式解析其路径： 存在 .claude/CLAUDE.md 时使用该文件，否则使用根目录的 CLAUDE.md（仅当 IS_GLOBAL_CONFIG=1 时，根目录才是规范位置）。两者均不存在 → INFO "No CLAUDE.md found — budget check skipped"，并停止。
2. 全局配置（install.sh 和 sync.sh 均存在）→ 20,000 字符预算； 否则 → 5,000。
3. 超出预算 → INFO "CLAUDE.md is [N] chars ([N-budget] over [budget] budget). Consider extracting content to skills (ADR-041)"。
4. 未超出 → INFO "CLAUDE.md budget OK: [N]/[budget] chars"。

发现项放在 ## Budget Compliance 部分。不影响评分。

---

报告

使用 REPORT_TEMPLATE.md 中的确切结构，保存到 [project_root]/.claude/audit-report.md。 评分分布及其解读见 SCORING.md。

---

规则

1. 始终读取真实文件。切勿假设内容。
2. 在具备读取工具的子 Agent 中运行。切勿在主上下文中运行。
3. 呈现报告前，始终先将其保存到 .claude/audit-report.md。
4. FIX_MANIFEST 必须是有效的 YAML。验证代码块能够解析。
5. 切勿修改任何内容。全程只读。
6. 如果无法读取某个文件，使用确切错误信息报告 ❌。不要假设文件不存在。
7. 完成后显示："Report saved in .claude/audit-report.md. To implement: /project-fix"。
8. 所有 Shell 探查都在 Phase A 中进行。每次运行最多调用 Bash 3 次。不得针对每个维度单独运行 ls/grep/wc -l/find。
9. 兼容性行为必须明确说明，不得隐含在某个维度中。