health

Claude Code Configuration Health Audit

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.

Output language: Detect from the conversation language or the CLAUDE.md ## Communication rule; present all findings in that language. Default to English if unclear.

Step 0: Assess project tier

Use this rubric to pick the audit tier before proceeding:

Tier	Signal	What's expected
Simple	<500 source files, 1 contributor, no CI	CLAUDE.md only; 0–1 skills; no rules/; hooks optional
Standard	500–5K files, small team or CI present	CLAUDE.md + 1–2 rules files; 2–4 skills; basic hooks
Complex	>5K files, multi-contributor, multi-language, active CI	Full 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.

Step 1: Collect all data (single bash block)

Run one block to collect everything. This keeps the entire data-gathering phase to a single confirmation prompt.

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

echo "=== TIER METRICS ==="
echo "source_files: $(find "$P" -type f \( -name "*.rs" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.lua" -o -name "*.swift" -o -name "*.rb" -o -name "*.java" -o -name "*.kt" -o -name "*.cs" -o -name "*.cpp" -o -name "*.c" \) -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 "$P/.github/workflows/"*.yaml 2>/dev/null | wc -l)"
echo "skills:        $(find "$P/.claude/skills" -name "SKILL.md" 2>/dev/null | grep -v '/health/SKILL.md' | wc -l)"
echo "claude_md_lines: $(wc -l < "$P/CLAUDE.md" 2>/dev/null)"

echo "=== CLAUDE.md (global) ===" ; cat ~/.claude/CLAUDE.md 2>/dev/null || echo "(none)"
echo "=== CLAUDE.md (local) ===" ; cat "$P/CLAUDE.md" 2>/dev/null || echo "(none)"
echo "=== settings.local.json ===" ; cat "$SETTINGS" 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
try:
    d=json.load(open('$SETTINGS'))
    s = d.get('mcpServers', d.get('enabledMcpjsonServers', {}))
    names = list(s.keys()) if isinstance(s, dict) else list(s)
    n = len(names)
    print(f'servers({n}):', ', '.join(names))
    est = n * 25 * 200  # ~200 tokens/tool, ~25 tools/server
    print(f'est_tokens: ~{est} ({round(est/2000)}% of 200K)')
except: print('(no MCP)')
" 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
echo "=== HANDOFF.md ===" ; cat "$P/HANDOFF.md" 2>/dev/null || echo "(none)"
echo "=== MEMORY.md ===" ; cat "$HOME/.claude/projects/-$(pwd | sed 's|/|-|g; s|^-||')/memory/MEMORY.md" 2>/dev/null | head -50 || echo "(none)"

echo "=== CONVERSATION FILES ==="
PROJECT_PATH=$(pwd | sed 's|/|-|g; s|^-||')
CONVO_DIR=~/.claude/projects/-${PROJECT_PATH}
ls -lhS "$CONVO_DIR"/*.jsonl 2>/dev/null | head -10

echo "=== CONVERSATION EXTRACT (up to 3 most recent, confidence improves with more files) ==="
FILES=$(ls -t "$CONVO_DIR"/*.jsonl 2>/dev/null | head -3)
if [ -n "$FILES" ]; then
  for F in $FILES; do
    echo "--- file: $F ---"
    cat "$F" | 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
  done
else
  echo "(no conversation files)"
fi

# --- Skill scan (inventory, security, frontmatter, provenance, full content) ---
# Exclude self by frontmatter name field -- stable across install paths
SELF_SKILL=$(grep -rl '^name: health$' "$P/.claude/skills" "$HOME/.claude/skills" 2>/dev/null | grep 'SKILL.md' | head -1)
[ -z "$SELF_SKILL" ] && SELF_SKILL="health/SKILL.md"

echo "=== SKILL INVENTORY ==="
for DIR in "$P/.claude/skills" "$HOME/.claude/skills"; do
  [ -d "$DIR" ] || continue
  find -L "$DIR" -name "SKILL.md" 2>/dev/null | grep -v "$SELF_SKILL" | while IFS= read -r f; do
    WORDS=$(wc -w < "$f" | tr -d ' ')
    IS_LINK="no"; LINK_TARGET=""
    SKILL_DIR=$(dirname "$f")
    if [ -L "$SKILL_DIR" ]; then
      IS_LINK="yes"; LINK_TARGET=$(readlink -f "$SKILL_DIR")
    fi
    echo "path=$f words=$WORDS symlink=$IS_LINK target=$LINK_TARGET"
  done
done

echo "=== SKILL SECURITY SCAN ==="
for DIR in "$P/.claude/skills" "$HOME/.claude/skills"; do
  [ -d "$DIR" ] || continue
  find -L "$DIR" -name "SKILL.md" 2>/dev/null | grep -v "$SELF_SKILL" | while IFS= read -r f; do
    echo "--- SCANNING: $f ---"
    # Split dangerous literals to avoid false positives in static security scanners
    _ev='eva''l'; _b64='base6''4'; _rmrf='rm\s+-rf'; _net='cu''rl|wget'
    # Prompt injection
    grep -inE 'ignore (previous|above|all) (instructions|prompts|rules)' "$f" && echo "[!] PROMPT_INJECTION: $f"
    grep -inE '(you are now|pretend you are|act as if|new persona)' "$f" && echo "[!] ROLE_HIJACK: $f"
    # Data exfiltration
    grep -inE "(${_net}).+(-X\s*POST|--data|-d\s).+https?://" "$f" && echo "[!] DATA_EXFIL: $f"
    grep -inE "${_b64}"'.*encode.*(secret|key|token)' "$f" && echo "[!] DATA_EXFIL_B64: $f"
    # Destructive commands
    grep -nE "${_rmrf}"'\s+[/~]' "$f" && echo "[!] DESTRUCTIVE: $f"
    grep -nE 'git push --force\s+origin\s+main' "$f" && echo "[!] DESTRUCTIVE_GIT: $f"
    grep -nE 'chmod\s+777' "$f" && echo "[!] DESTRUCTIVE_PERM: $f"
    # Hardcoded credentials
    grep -nE '(api_key|secret_key|api_secret|access_token)\s*[:=]\s*["'"'"'][A-Za-z0-9+/]{16,}' "$f" && echo "[!] HARDCODED_CRED: $f"
    # Obfuscation
    grep -nE "${_ev}"'\s*\$\(' "$f" && echo "[!] OBFUSCATION_EVAL: $f"
    grep -nE "${_b64}"'\s+-d' "$f" && echo "[!] OBFUSCATION_B64: $f"
    grep -nE '\\x[0-9a-fA-F]{2}' "$f" && echo "[!] OBFUSCATION_HEX: $f"
    # Safety override
    grep -inE '(override|bypass|disable)\s*(the\s+)?(safety|rules?|hooks?|guard|verification)' "$f" && echo "[!] SAFETY_OVERRIDE: $f"
  done
done

echo "=== SKILL FRONTMATTER ==="
for DIR in "$P/.claude/skills" "$HOME/.claude/skills"; do
  [ -d "$DIR" ] || continue
  find -L "$DIR" -name "SKILL.md" 2>/dev/null | grep -v "$SELF_SKILL" | while IFS= read -r f; do
    if head -1 "$f" | grep -q '^---'; then
      echo "frontmatter=yes path=$f"
      sed -n '2,/^---$/p' "$f" | head -10
    else
      echo "frontmatter=MISSING path=$f"
    fi
  done
done

echo "=== SKILL SYMLINK PROVENANCE ==="
for DIR in "$P/.claude/skills" "$HOME/.claude/skills"; do
  [ -d "$DIR" ] || continue
  find "$DIR" -maxdepth 1 -type l 2>/dev/null | while IFS= read -r link; do
    TARGET=$(readlink -f "$link")
    echo "link=$(basename "$link") target=$TARGET"
    if [ -d "$TARGET/.git" ]; then
      REMOTE=$(git -C "$TARGET" remote get-url origin 2>/dev/null || echo "unknown")
      COMMIT=$(git -C "$TARGET" rev-parse --short HEAD 2>/dev/null || echo "unknown")
      echo "  git_remote=$REMOTE commit=$COMMIT"
    fi
  done
done

echo "=== SKILL FULL CONTENT ==="
for DIR in "$P/.claude/skills" "$HOME/.claude/skills"; do
  [ -d "$DIR" ] || continue
  find -L "$DIR" -name "SKILL.md" 2>/dev/null | grep -v "$SELF_SKILL" | while IFS= read -r f; do
    echo "--- FULL: $f ---"
    cat "$f"
  done
done

Step 2: Launch two parallel diagnostic agents

Spin up two subagents in parallel using the Agent tool. Paste all relevant Step 1 output sections inline into each agent's prompt so they do not need to read any files. Fill in [project] and tier; use (no conversation history) if none.

Agent 1 — Context + Security Audit (no conversation needed)

Prompt:

All data is provided inline below. DO NOT use the Read tool or Bash tool to read any files.

[PASTE Step 1 output sections: CLAUDE.md (global), CLAUDE.md (local), rules/, skill descriptions, MCP, HANDOFF.md, MEMORY.md, SKILL INVENTORY, SKILL SECURITY SCAN, SKILL FRONTMATTER, SKILL SYMLINK PROVENANCE, SKILL FULL CONTENT]

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

## Part A: Context Layer

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 like Rust or 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 words and say WHEN to use.
- STANDARD+: Low-frequency skills should have disable-model-invocation: true.

Tier-adjusted MEMORY.md checks STANDARD+:
- Check if project has `.claude/projects/.../memory/MEMORY.md`
- Verify CLAUDE.md references MEMORY.md for architecture decisions
- Ensure key design decisions: data models, API contracts, major tradeoffs are documented there

Tier-adjusted AGENTS.md checks COMPLEX with multiple modules:
- Verify CLAUDE.md includes "AGENTS.md 使用指南" section
- Check that it explains WHEN to consult each AGENTS.md -- not just list links

MCP token cost check ALL tiers:
- Count MCP servers and estimate token overhead: ~200 tokens/tool, ~25 tools/server
- If estimated MCP tokens > 10% of 200K context (~20,000 tokens), flag as context pressure
- If >6 servers, flag as HIGH: likely exceeding 12.5% context overhead
- Check if any idle/rarely-used servers could be disconnected to reclaim context

Tier-adjusted HANDOFF.md check STANDARD+:
- Check if HANDOFF.md exists or if CLAUDE.md mentions handoff practice
- COMPLEX: Recommend HANDOFF.md pattern for cross-session continuity if not present

Verifiers layer STANDARD+:
- Check for test/lint scripts: package.json `scripts`, Makefile, Taskfile, or CI steps.
- Flag done-conditions in CLAUDE.md with no matching command in the project.

## Part B: Skill Security & Quality

Use the collected data from Step 1: SKILL INVENTORY, SKILL SECURITY SCAN, SKILL FRONTMATTER, SKILL SYMLINK PROVENANCE, SKILL FULL CONTENT. All data is already provided inline above.

CRITICAL DISTINCTION: Differentiate between a skill that DISCUSSES a security pattern (benign) vs. one that USES it (dangerous). Only flag the latter. Note FALSE POSITIVES explicitly.

🔴 Security checks:
1. Prompt injection: "ignore previous instructions", "you are now", "pretend you are", "new persona", "override system prompt"
2. Data exfiltration: HTTP POST via network tools with env vars, encoding secrets before transmission
3. Destructive commands: recursive force-delete on root paths, force-push to main, world-write chmod without confirmation
4. Hardcoded credentials: api_key/secret_key assignments with long alphanumeric strings
5. Obfuscation: shell evaluation of subshell output, decode piped to shell, hex escape sequences
6. Safety override: "override/bypass/disable" combined with "safety/rules/hooks/guard/verification"

🟡 Quality checks:
1. Missing or incomplete YAML frontmatter: no name, no description, no version
2. Description too broad: would match unrelated user requests
3. Content bloat: skill >5000 words
4. Broken file references: skill references files that do not exist
5. Subagent hygiene: Agent tool calls in skills that lack explicit tool restrictions, isolation mode, or output format constraint

🟢 Provenance checks:
1. Symlink source: git remote + commit for symlinked skills
2. Missing version in frontmatter
3. Unknown origin: non-symlink skills with no source attribution

Output: bullet points only, two sections:
[CONTEXT LAYER: CLAUDE.md issues | rules/ issues | skill description issues | MCP cost | verifiers gaps]
[SKILL SECURITY: 🔴 Critical | 🟡 Structural | 🟢 Provenance]

Agent 2 — Control + Behavior Audit (uses conversation evidence)

Prompt:

All data is provided inline below. DO NOT use the Read tool or Bash tool to read any files.

[PASTE Step 1 output sections: settings.local.json, CLAUDE.md (global), CLAUDE.md (local), hooks, allowedTools count, skill descriptions, CONVERSATION EXTRACT]

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

## Part A: Control + Verification Layer

Tier-adjusted hooks checks:
- SIMPLE: Hooks are optional. Only flag if a hook is broken -- like firing on wrong file types.
- STANDARD+: PostToolUse hooks expected for the primary languages of the project.
- COMPLEX: Hooks expected for all frequently-edited file types found in conversations.
- ALL tiers: If hooks exist, verify correct schema:
  - Each entry needs `matcher`: tool name regex like "Edit|Write", and a `hooks` array
  - Each hook in the array needs `type: "command"` and `command` field
  - File path available via `$CLAUDE_TOOL_INPUT_FILE_PATH` env var in commands
  - Flag hooks missing `matcher` -- would fire on ALL tool calls

allowedTools hygiene ALL tiers:
- Flag stale one-time commands: migrations, setup scripts, path-specific operations.
- Flag dangerous operations:
  - HIGH: sudo *, force-delete root paths, *>*
  - MEDIUM: brew uninstall, launchctl unload, xcode-select --reset
  - LOW -- cleanup needed: path-hardcoded commands, debug/test commands

MCP configuration STANDARD+:
- Check enabledMcpjsonServers count -- >6 may impact performance
- Check filesystem MCP has allowedDirectories configured

Prompt cache hygiene ALL tiers:
- Check CLAUDE.md or hooks for dynamic timestamps/dates injected into system-level context -- breaks prompt cache on every request
- Check if hooks or skills non-deterministically reorder tool definitions
- In conversation evidence, look for mid-session model switches like Opus→Haiku→Opus — flag as cache-breaking: switching model rebuilds entire cache and can be MORE expensive
- If model switching is detected, recommend: use subagents for different-model tasks instead of switching mid-session

Three-layer defense consistency STANDARD+:
- For each critical rule in CLAUDE.md NEVER/ALWAYS items, check if:
  1. CLAUDE.md declares the rule: intent layer
  2. A Skill teaches the method/workflow for that rule: knowledge layer
  3. A Hook enforces it deterministically: control layer
- Flag rules that only exist in one layer — single-layer rules are fragile:
  - CLAUDE.md-only rules: Claude may ignore them under context pressure
  - Hook-only rules: no flexibility for edge cases, no teaching
  - Skill-only rules: no enforcement, no always-on awareness
- Priority: focus on safety-critical rules: file protection, test requirements, deploy gates

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.

Subagents hygiene STANDARD+:
- Flag Agent tool calls in hooks that lack explicit tool restrictions or isolation mode.
- Flag subagent prompts in hooks with no output format constraint -- free-form output pollutes parent context.

## Part B: Behavior Pattern Audit

Data source: up to 3 recent conversation files. Confidence is limited -- only flag patterns with clear evidence. Mark each finding with [HIGH CONFIDENCE] if seen in multiple files, [LOW CONFIDENCE] if seen in only one file or inferred from partial data.

1. Rules violated: Find cases where CLAUDE.md says NEVER/ALWAYS but Claude did the opposite. Quote both the rule and the violation. Only flag if directly observed, not inferred.
2. Repeated corrections: Find cases where the user corrected Claude's behavior more than once on the same issue. Requires evidence in at least 2 conversations to flag as repeated.
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 that aren't in ~/.claude/CLAUDE.md.
5. Skill frequency STANDARD+: Only report frequency if skill invocations are directly visible in the conversation evidence. Do not infer monthly rates from fewer than 3 sessions -- mark as [INSUFFICIENT DATA] instead.
6. Anti-patterns: Only flag what is directly observable in the sample:
   - Claude declaring done without running verification
   - User re-explaining same context across sessions -- missing HANDOFF.md or memory
   - Long sessions over 20 turns without /compact or /clear

Output: bullet points only, two sections:
[CONTROL LAYER: hooks issues | allowedTools to remove | cache hygiene | three-layer gaps | verification gaps | subagents issues]
[BEHAVIOR: rules violated | repeated corrections | add to local CLAUDE.md | add to global CLAUDE.md | skill frequency | anti-patterns -- each finding tagged with confidence level]

Paste all relevant data inline into each agent; do not pass file paths or instruct agents to read files.

Step 3: Synthesize and present

Aggregate all agent outputs into a single report with these sections:

🔴 Critical -- fix now

Rules that were violated, missing verification definitions, dangerous allowedTools entries, MCP token overhead >12.5%, cache-breaking patterns in active use. Agent 1 security findings: prompt injection, data exfiltration, destructive commands, hardcoded credentials, obfuscation, safety overrides detected in skills.

🟡 Structural -- fix soon

CLAUDE.md content that belongs elsewhere, missing hooks for frequently-edited file types, skill descriptions that are too long, single-layer critical rules missing enforcement, mid-session model switching. Agent 1: test/lint scripts vs done-conditions. Agent 2: subagent permission/isolation gaps. Agent 1: missing frontmatter, overly broad descriptions, content bloat >5000 words, broken file references.

🟢 Incremental -- nice to have

New patterns to add, outdated items to remove, global vs local placement improvements, context hygiene habits, HANDOFF.md adoption. Agent 2 skill frequency findings: skills to tune auto-invoke strategy or retire. Agent 1 provenance findings: symlink source identification, missing version numbers, unknown-origin skills.

---

Non-goals

• Never auto-apply fixes without explicit confirmation.
• Never apply complex-tier checks to simple projects.
• Flag issues; do not replace architectural judgment.

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.