health

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Configuration Health Audit

Claude Code 配置健康审计

Systematically audit the current project's Claude Code setup using the six-layer framework:
CLAUDE.md → rules → skills → hooks → subagents → verifiers
The goal is not just to find rule violations, but to diagnose which layer is misaligned and why — calibrated to the project's actual complexity.
使用六层框架系统审计当前项目的Claude Code配置:
CLAUDE.md → rules → skills → hooks → subagents → verifiers
目标不只是发现规则违反情况,还要诊断哪个层级配置错位以及错位原因——根据项目的实际复杂度校准审计标准

Step 0: Assess project tier

步骤0:评估项目等级

bash
P=$(pwd)
echo "source_files: $(find "$P" -type f \( -name "*.rs" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.lua" \) -not -path "*/.git/*" -not -path "*/node_modules/*" | wc -l)"
echo "contributors: $(git -C "$P" log --format='%ae' 2>/dev/null | sort -u | wc -l)"
echo "ci_workflows:  $(ls "$P/.github/workflows/"*.yml 2>/dev/null | wc -l)"
echo "skills:        $(ls "$P/.claude/skills/" 2>/dev/null | wc -l)"
echo "claude_md_lines: $(wc -l < "$P/CLAUDE.md" 2>/dev/null)"
Use this rubric to pick the audit tier before proceeding:
TierSignalWhat's expected
Simple<500 source files, 1 contributor, no CICLAUDE.md only; 0–1 skills; no rules/; hooks optional
Standard500–5K files, small team or CI presentCLAUDE.md + 1–2 rules files; 2–4 skills; basic hooks
Complex>5K files, multi-contributor, multi-language, active CIFull six-layer setup required
Apply the tier's standard throughout the audit. Do not flag missing layers that aren't required for the detected tier.
bash
P=$(pwd)
echo "source_files: $(find "$P" -type f \( -name "*.rs" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.lua" \) -not -path "*/.git/*" -not -path "*/node_modules/*" | wc -l)"
echo "contributors: $(git -C "$P" log --format='%ae' 2>/dev/null | sort -u | wc -l)"
echo "ci_workflows:  $(ls "$P/.github/workflows/"*.yml 2>/dev/null | wc -l)"
echo "skills:        $(ls "$P/.claude/skills/" 2>/dev/null | wc -l)"
echo "claude_md_lines: $(wc -l < "$P/CLAUDE.md" 2>/dev/null)"
在继续审计前,使用以下标准选择审计等级:
等级判断信号预期配置
简单源文件少于500个,仅1位贡献者,无CI仅需CLAUDE.md;0-1个skill;无需rules/;hooks可选
标准500-5000个文件,小型团队或已接入CICLAUDE.md + 1-2个规则文件;2-4个skill;基础hooks配置
复杂超过5000个文件,多贡献者,多语言,活跃CI需要完整的六层配置
整个审计过程都要适配对应等级的标准,不要标记当前等级不需要的缺失层级为问题。

Step 1: Collect configuration snapshot

步骤1:收集配置快照

bash
P=$(pwd)
SETTINGS="$P/.claude/settings.local.json"

echo "=== CLAUDE.md (global) ===" ; cat ~/.claude/CLAUDE.md
echo "=== CLAUDE.md (local) ===" ; cat "$P/CLAUDE.md" 2>/dev/null || echo "(none)"
echo "=== rules/ ===" ; find "$P/.claude/rules" -name "*.md" 2>/dev/null | while IFS= read -r f; do echo "--- $f ---"; cat "$f"; done
echo "=== skill descriptions ===" ; grep -r "^description:" "$P/.claude/skills" ~/.claude/skills 2>/dev/null
echo "=== hooks ===" ; python3 -c "import json,sys; d=json.load(open('$SETTINGS')); print(json.dumps(d.get('hooks',{}), indent=2))" 2>/dev/null
echo "=== MCP ===" ; python3 -c "import json; d=json.load(open('$SETTINGS')); print(d.get('enabledMcpjsonServers',[]))" 2>/dev/null
echo "=== allowedTools count ===" ; python3 -c "import json; d=json.load(open('$SETTINGS')); print(len(d.get('permissions',{}).get('allow',[])))" 2>/dev/null
bash
P=$(pwd)
SETTINGS="$P/.claude/settings.local.json"

echo "=== CLAUDE.md (全局) ===" ; cat ~/.claude/CLAUDE.md
echo "=== CLAUDE.md (项目本地) ===" ; cat "$P/CLAUDE.md" 2>/dev/null || echo "(无)"
echo "=== rules/ ===" ; find "$P/.claude/rules" -name "*.md" 2>/dev/null | while IFS= read -r f; do echo "--- $f ---"; cat "$f"; done
echo "=== skill 描述 ===" ; grep -r "^description:" "$P/.claude/skills" ~/.claude/skills 2>/dev/null
echo "=== hooks ===" ; python3 -c "import json,sys; d=json.load(open('$SETTINGS')); print(json.dumps(d.get('hooks',{}), indent=2))" 2>/dev/null
echo "=== MCP ===" ; python3 -c "import json; d=json.load(open('$SETTINGS')); print(d.get('enabledMcpjsonServers',[]))" 2>/dev/null
echo "=== allowedTools 数量 ===" ; python3 -c "import json; d=json.load(open('$SETTINGS')); print(len(d.get('permissions',{}).get('allow',[])))" 2>/dev/null

Step 2: Collect conversation evidence

步骤2:收集对话证据

Read conversation files directly — do NOT write to disk and pass paths to subagents (subagents cannot read
~/.claude/
paths). Instead, read content here and inline it into agent prompts in Step 3.
bash
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
直接读取对话文件——不要写入磁盘再把路径传给subagent(subagent无法读取
~/.claude/
路径)。而是在此处读取内容,在步骤3中直接嵌入到Agent提示词中。
bash
PROJECT_PATH=$(pwd | sed 's|/|-|g' | sed 's|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}

List the 15 most recent conversations with sizes

列出最近15个对话及其大小

ls -lhS "$CONVO_DIR"/*.jsonl 2>/dev/null | head -15

For each conversation file you want to include, use the Read tool (or jq via Bash) to extract its text content directly into a variable in your context. Assign files to agents B and C based on size:
- Large (>50KB): 1–2 per agent
- Medium (10–50KB): 3–5 per agent
- Small (<10KB): up to 10 per agent

Extract each file's content with:
```bash
cat <file>.jsonl | jq -r '
  if .type == "user" then "USER: " + ((.message.content // "") | if type == "array" then map(select(.type == "text") | .text) | join(" ") else . end)
  elif .type == "assistant" then
    "ASSISTANT: " + ((.message.content // []) | map(select(.type == "text") | .text) | join("\n"))
  else empty
  end
' 2>/dev/null | grep -v "^ASSISTANT: $" | head -300
Store the output in your context. You will paste it inline into the agent B and C prompts below.
ls -lhS "$CONVO_DIR"/*.jsonl 2>/dev/null | head -15

对于你想要纳入审计的每个对话文件,使用Read工具(或通过Bash调用jq)直接将其文本内容提取到上下文中的变量里。根据文件大小分配给Agent B和C:
- 大文件(>50KB):每个Agent分配1-2个
- 中等文件(10-50KB):每个Agent分配3-5个
- 小文件(<10KB):每个Agent最多分配10个

使用以下命令提取每个文件的内容:
```bash
cat <file>.jsonl | jq -r '
  if .type == "user" then "USER: " + ((.message.content // "") | if type == "array" then map(select(.type == "text") | .text) | join(" ") else . end)
  elif .type == "assistant" then
    "ASSISTANT: " + ((.message.content // []) | map(select(.type == "text") | .text) | join("\n"))
  else empty
  end
' 2>/dev/null | grep -v "^ASSISTANT: $" | head -300
将输出存储在你的上下文中,后续会直接嵌入到下方Agent B和C的提示词中。

Step 3: Launch parallel diagnostic agents

步骤3:启动并行诊断Agent

Spin up three focused subagents in parallel, each examining one diagnostic dimension:
同时启动三个专注的subagent,每个负责检查一个诊断维度:

Agent A — Context Layer Audit

Agent A — 上下文层审计

Prompt:
Read: ~/.claude/CLAUDE.md, [project]/CLAUDE.md, [project]/.claude/rules/**, [project]/.claude/skills/**/SKILL.md

This project is tier: [SIMPLE / STANDARD / COMPLEX] — apply only the checks appropriate for this tier.

Tier-adjusted CLAUDE.md checks:
- ALL tiers: Is CLAUDE.md short and executable? No prose, no background, no soft guidance.
- ALL tiers: Does it have build/test commands?
- STANDARD+: Is there a "Verification" section with per-task done-conditions?
- STANDARD+: Is there a "Compact Instructions" section?
- COMPLEX only: Is content that belongs in rules/ or skills already split out?

Tier-adjusted rules/ checks:
- SIMPLE: rules/ is NOT required — do not flag its absence.
- STANDARD+: Language-specific rules (e.g., Rust, Lua) should be in rules/ not CLAUDE.md.
- COMPLEX: Path-specific rules should be isolated; no rules in root CLAUDE.md.

Tier-adjusted skill checks:
- SIMPLE: 0–1 skills is fine. Do not flag absence of skills.
- ALL tiers: If skills exist, descriptions should be <12 tokens and say WHEN to use.
- STANDARD+: Low-frequency skills should have disable-model-invocation: true.

Output: bullet points only, state the detected tier at the top, grouped by: [CLAUDE.md issues] [rules/ issues] [skills description issues]
提示词:
读取:~/.claude/CLAUDE.md、[项目路径]/CLAUDE.md、[项目路径]/.claude/rules/**、[项目路径]/.claude/skills/**/SKILL.md

本项目等级为:[简单 / 标准 / 复杂]——仅执行适配该等级的检查。

适配等级的CLAUDE.md检查:
- 所有等级:CLAUDE.md是否简短可执行?无冗余描述、无背景介绍、无软性指导。
- 所有等级:是否包含构建/测试命令?
- 标准及以上等级:是否有包含各任务完成条件的「Verification」部分?
- 标准及以上等级:是否有「Compact Instructions」部分?
- 仅复杂等级:本该放在rules/或skills中的内容是否已经拆分出去?

适配等级的rules/检查:
- 简单等级:不需要rules/——不要标记缺失为问题。
- 标准及以上等级:语言特定规则(如Rust、Lua)应该放在rules/而非CLAUDE.md中。
- 复杂等级:路径特定规则应该隔离;根CLAUDE.md中不应存在规则。

适配等级的skill检查:
- 简单等级:0-1个skill即可,不要标记skill缺失为问题。
- 所有等级:如果存在skill,描述应少于12个token,且说明使用时机。
- 标准及以上等级:低频使用的skill应该配置disable-model-invocation: true。

输出:仅用要点列表,顶部说明检测到的项目等级,按以下分组:[CLAUDE.md问题] [rules/问题] [skill描述问题]

Agent B — Control + Verification Layer Audit

Agent B — 控制+验证层审计

Prompt:
Read: [project]/.claude/settings.local.json, [project]/CLAUDE.md, [project]/.claude/skills/**/SKILL.md

Conversation evidence (inline — no file reading needed):
[PASTE EXTRACTED CONVERSATION CONTENT HERE]

This project is tier: [SIMPLE / STANDARD / COMPLEX] — apply only the checks appropriate for this tier.

Tier-adjusted hooks checks:
- SIMPLE: Hooks are optional. Only flag if a hook is broken (e.g., fires on wrong file types).
- STANDARD+: PostToolUse hooks expected for the primary language(s) of the project.
- COMPLEX: Hooks expected for all frequently-edited file types found in conversations.
- ALL tiers: If hooks exist, verify pattern field is present to avoid firing on all edits.

allowedTools hygiene (ALL tiers):
- Flag stale one-time commands (migrations, setup scripts, path-specific operations).
- Flag dangerous operations (rm -rf, force-push, brew uninstall, launchctl unload).

Tier-adjusted verification checks:
- SIMPLE: No formal verification section required. Only flag if Claude declared done without running any check.
- STANDARD+: CLAUDE.md should have a Verification section with per-task done-conditions.
- COMPLEX: Each task type in conversations should map to a verification command or skill.

Output: bullet points only, state the detected tier at the top, grouped by: [hooks issues] [allowedTools to remove] [verification gaps]
提示词:
读取:[项目路径]/.claude/settings.local.json、[项目路径]/CLAUDE.md、[项目路径]/.claude/skills/**/SKILL.md

对话证据(已内嵌,无需读取文件):
[在此粘贴提取的对话内容]

本项目等级为:[简单 / 标准 / 复杂]——仅执行适配该等级的检查。

适配等级的hooks检查:
- 简单等级:Hooks是可选的,仅当hook损坏时标记问题(比如触发的文件类型错误)。
- 标准及以上等级:项目的主要编程语言应该配置PostToolUse hooks。
- 复杂等级:对话中出现的所有高频编辑文件类型都应该配置hooks。
- 所有等级:如果存在hooks,验证pattern字段已配置,避免在所有编辑操作时触发。

allowedTools卫生检查(所有等级):
- 标记过时的一次性命令(数据迁移、初始化脚本、路径特定操作)。
- 标记危险操作(rm -rf、force-push、brew uninstall、launchctl unload)。

适配等级的验证检查:
- 简单等级:不需要正式的验证部分,仅当Claude未运行任何检查就声明完成时标记问题。
- 标准及以上等级:CLAUDE.md应该有包含各任务完成条件的Verification部分。
- 复杂等级:对话中出现的每种任务类型都应该对应一个验证命令或skill。

输出:仅用要点列表,顶部说明检测到的项目等级,按以下分组:[hooks问题] [需要移除的allowedTools] [验证缺口]

Agent C — Behavior Pattern Audit

Agent C — 行为模式审计

Prompt:
Read: ~/.claude/CLAUDE.md, [project]/CLAUDE.md

Conversation evidence (inline — no file reading needed):
[PASTE EXTRACTED CONVERSATION CONTENT HERE]

Analyze actual behavior against stated rules:

1. Rules violated: Find cases where CLAUDE.md says NEVER/ALWAYS but Claude did the opposite. Quote both the rule and the violation.
2. Repeated corrections: Find cases where the user corrected Claude's behavior more than once on the same issue. These are candidates for stronger rules.
3. Missing local patterns: Find project-specific behaviors the user reinforced in conversation but that aren't in local CLAUDE.md.
4. Missing global patterns: Find behaviors that would apply to any project (not just this one) that aren't in ~/.claude/CLAUDE.md.
5. Anti-patterns present: Check for these specific anti-patterns:
   - CLAUDE.md used as wiki/documentation
   - Skills covering too many unrelated tasks
   - Claude declaring done without running verification
   - Subagents used without tool/permission constraints
   - User having to re-explain the same context across sessions

Output: bullet points only, grouped by: [rules violated] [repeated corrections] [add to local CLAUDE.md] [add to global CLAUDE.md] [anti-patterns]
Paste the extracted conversation content inline into agent B and C prompts. Do not pass file paths.
提示词:
读取:~/.claude/CLAUDE.md、[项目路径]/CLAUDE.md

对话证据(已内嵌,无需读取文件):
[在此粘贴提取的对话内容]

对照声明的规则分析实际行为:

1. 规则违反:查找CLAUDE.md声明了禁止/必须操作,但Claude执行了相反操作的情况,同时引用规则内容和违反情况。
2. 重复纠正:查找用户就同一问题多次纠正Claude行为的情况,这类问题适合补充为更强的规则。
3. 缺失本地模式:查找用户在对话中反复强调,但没有写入本地CLAUDE.md的项目特定行为要求。
4. 缺失全局模式:查找适用于所有项目(不仅是当前项目),但没有写入~/.claude/CLAUDE.md的行为要求。
5. 存在反模式:检查是否存在以下特定反模式:
   - CLAUDE.md被用作维基/文档
   - Skill覆盖了太多不相关的任务
   - Claude未运行验证就声明完成
   - 使用Subagent时没有配置工具/权限约束
   - 用户需要跨会话重复解释相同上下文

输出:仅用要点列表,按以下分组:[规则违反] [重复纠正] [需要添加到本地CLAUDE.md] [需要添加到全局CLAUDE.md] [反模式]
将提取的对话内容直接内嵌到Agent B和C的提示词中,不要传递文件路径。

Step 4: Synthesize and present

步骤4:汇总并呈现结果

Aggregate all agent outputs into a single report with these sections:
将所有Agent的输出汇总为一份报告,包含以下部分:

🔴 Critical (fix now)

🔴 严重问题(立即修复)

Rules that were violated, missing verification definitions, dangerous allowedTools entries.
违反的规则、缺失的验证定义、危险的allowedTools条目。

🟡 Structural (fix soon)

🟡 结构问题(尽快修复)

CLAUDE.md content that belongs elsewhere, missing hooks for frequently-edited file types, skill descriptions that are too long.
本该放在其他位置的CLAUDE.md内容、高频编辑文件类型缺失对应hooks、过长的skill描述。

🟢 Incremental (nice to have)

🟢 优化项(可选优化)

New patterns to add, outdated items to remove, global vs local placement improvements.

Stop condition: After presenting the report, ask:
"Should I draft the changes? I can handle each layer separately: global CLAUDE.md / local CLAUDE.md / hooks / skills."
Do not make any edits without explicit confirmation.
需要新增的模式、需要移除的过时条目、全局/本地配置的放置优化。

停止条件: 呈现报告后,询问:
"需要我起草修改方案吗?我可以分层级处理:全局CLAUDE.md / 本地CLAUDE.md / hooks / skills。"
没有明确确认的情况下不要进行任何编辑。