Claude Code Setup Audit

Systematic audit across 8 areas. Each scored 1-5. Total /40. Prioritized fixes.

See references/knowledge-base.md for detailed patterns. See scripts/audit.py for automated scanning.

Audit Workflow

Phase 1 -- Collect. Read these files in parallel. Missing files lower the score.

CLAUDE.md                              # Project instructions
.claude/settings.json                  # Project permissions
.claude/settings.local.json            # Local overrides (gitignored)
~/.claude/settings.json                # Global permissions
.mcp.json                              # MCP server declarations
.claude/commands/                      # Custom slash commands
~/.claude/commands/                    # Global slash commands
~/.claude/projects/*/memory/           # Memory files

Phase 2 -- Score. Evaluate each of the 8 areas below (1-5).

Phase 3 -- Present. Output the scorecard:

CLAUDE CODE SETUP AUDIT
=======================
| #  | Area                        | Score | Max | Status     |
|----|-----------------------------|-------|-----|------------|
| 1  | CLAUDE.md Quality           |   ?   |  5  |            |
| 2  | Permission Configuration    |   ?   |  5  |            |
| 3  | Slash Command Awareness     |   ?   |  5  |            |
| 4  | Multi-Agent Decomposition   |   ?   |  5  |            |
| 5  | MCP Ecosystem               |   ?   |  5  |            |
| 6  | Context Cost Management     |   ?   |  5  |            |
| 7  | Memory System Health        |   ?   |  5  |            |
| 8  | Operating Environment       |   ?   |  5  |            |
|----|-----------------------------|-------|-----|------------|
|    | TOTAL                       |   ?   | 40  |            |

Status: EXCELLENT (5), GOOD (4), ADEQUATE (3), NEEDS WORK (2), CRITICAL (1).

Phase 4 -- Fix. Present top 5 fixes sorted by impact, each with a concrete action.

Area 1: CLAUDE.md Quality

Check: File exists, under 200 lines (ideal: 150), contains decision rules not documentation, imperative voice, project-specific constraints, no secrets, no boilerplate restating defaults.

Score: 5 = under 150 lines, purely operational, no fluff. 4 = under 200, mostly operational. 3 = 200-300, mixed. 2 = over 300, mostly docs. 1 = missing or 500+.

Quality checklist:

[ ] Exists at project root
[ ] Under 200 lines
[ ] First 10 lines: stack, purpose, constraints
[ ] Contains "Never" / "Always" rules (opinionated)
[ ] Test/lint/build commands specified
[ ] Deploy workflow or target specified
[ ] No secrets or credentials
[ ] No generic advice restating model defaults
[ ] Project-specific conventions (naming, structure, patterns)
[ ] Updated within last 30 days

Area 2: Permission Configuration

Check: Three-layer model (global > project > local), no broad wildcards like Bash(*), MCP tools scoped, dangerous ops gated, settings.local.json gitignored.

Score: 5 = three-layer, scoped, MCP tuned, dangerous gated. 4 = two-layer, mostly scoped. 3 = single file, some wildcards. 2 = broad wildcards, ungated. 1 = none.

Recommended template (.claude/settings.json):

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git branch*)",
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(ls*)",
      "Bash(cat*)",
      "Bash(find*)",
      "Bash(grep*)",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(curl*|*bash*)",
      "Bash(wget*|*bash*)"
    ]
  }
}

Principles: Allow reads broadly, gate writes narrowly. Auto-allow read-only MCP tools. Require approval for MCP mutations. Never commit settings.local.json.

Area 3: Slash Command Awareness

Check: Does the user leverage built-in and custom commands?

Also check for custom commands in .claude/commands/ and ~/.claude/commands/.

Score: 5 = regular built-in use + custom commands. 4 = most built-ins, few custom. 3 = occasional /compact and /cost. 2 = aware but rarely uses. 1 = none.

Area 4: Multi-Agent Decomposition

Check: Decision tree or heuristic in CLAUDE.md? Documented subagent patterns? Large tasks decomposed or single sessions growing unbounded?

Decision tree to look for (or recommend):

Single focused task?       --> Single agent (default)
3+ independent problems?   --> Parallel agents (one per problem)
Written plan, indep tasks? --> Subagent-driven development
Full feature with TDD?     --> Agent teams (multi-agent pipeline)

Score: 5 = decision tree documented, proven patterns. 4 = some awareness, occasional parallel work. 3 = knows but defaults to single. 2 = no strategy. 1 = no awareness.

Area 5: MCP Ecosystem

Check: Server count in .mcp.json, duplicates, read tools auto-allowed, write tools gated, config committed vs local-only.

Score: 5 = 3+ servers, no dupes, scoped. 4 = 2-3, well-configured. 3 = 1-2, basic. 2 = configured but unused/broken. 1 = none.

Anti-patterns: Duplicate servers for same capability. All tools auto-allowed including destructive ops. Servers configured but never used. Missing servers for the project's stack.

Area 6: Context Cost Management

Check: /compact before bloat, memory files under 200 lines, /cost tracked, targeted file reads (offset/limit), proactive context management.

Score: 5 = regular /compact, lean memory, /cost tracking, targeted reads. 4 = occasional /compact, mostly lean. 3 = infrequent, some bloat. 2 = never compacts, large files, reads everything. 1 = no management, hits limits.

Quick wins: /compact at 50% context. Read specific line ranges. Keep CLAUDE.md under 200 lines (loaded every session). Archive stale memory files.

Area 7: Memory System Health

Check: Index under 200 lines, topic files under 200, stale entries archived, cross-references valid, organized by project not date.

Score: 5 = clean index, all under 200, stale archived, valid refs. 4 = good structure, minor stale. 3 = bloated index, some files over 200. 2 = disorganized, broken refs. 1 = no memory system.

Health check: Count lines per file. Flag over 200. Check for "complete" projects still in active index. Verify cross-ref links. Flag files untouched 90+ days.

Area 8: Operating Environment

Check: Model routing awareness, hooks configured, session save/resume, git/shell/ PATH correct, IDE integration.

Score: 5 = hooks, model routing, sessions managed, clean infra. 4 = some hooks, aware of models. 3 = no hooks, defaults, functional. 2 = infra issues, no sessions. 1 = significant problems every session.

Hook template (settings.json):

{
  "hooks": {
    "preCommit": [
      { "command": "npm run lint", "description": "Lint before commit" }
    ],
    "postTask": [
      { "command": "npm run test", "description": "Test after task" }
    ]
  }
}

Interpreting Results

Fix priority order: 1) Permission security. 2) CLAUDE.md quality. 3) Context cost. 4) Memory health. 5) MCP ecosystem. 6) Slash commands. 7) Multi-agent. 8) Operating environment.

Running the Audit

Manual: Follow Phases 1-4. Read configs, score, present scorecard, list fixes.

Automated: python scripts/audit.py --project-dir . -- checks file existence, line counts, permission patterns, MCP config, memory health. Outputs preliminary scorecard for the agent to refine with qualitative assessment.

Post-audit: Ask user which fixes to implement. Apply them directly. Re-score affected areas. Log results in memory for tracking over time.

Example Output

CLAUDE CODE SETUP AUDIT
=======================
| #  | Area                        | Score | Max | Status     |
|----|-----------------------------|-------|-----|------------|
| 1  | CLAUDE.md Quality           |   3   |  5  | ADEQUATE   |
| 2  | Permission Configuration    |   2   |  5  | NEEDS WORK |
| 3  | Slash Command Awareness     |   4   |  5  | GOOD       |
| 4  | Multi-Agent Decomposition   |   3   |  5  | ADEQUATE   |
| 5  | MCP Ecosystem               |   4   |  5  | GOOD       |
| 6  | Context Cost Management     |   2   |  5  | NEEDS WORK |
| 7  | Memory System Health        |   3   |  5  | ADEQUATE   |
| 8  | Operating Environment       |   3   |  5  | ADEQUATE   |
|----|-----------------------------|-------|-----|------------|
|    | TOTAL                       |  24   | 40  | ADEQUATE   |

Grade: 24 / 40

TOP 5 FIXES (by impact):

1. PERMISSION CONFIG: Using Bash(*) wildcard. Create .claude/settings.json
   with scoped rules. [Action: Apply template from Area 2]

2. CONTEXT COST: CLAUDE.md is 347 lines. Trim to under 150 by extracting
   docs into separate files. [Action: Restructure using Area 1 checklist]

3. MEMORY HEALTH: 3 files exceed 200 lines. Archive completed projects.
   [Action: Split large files, archive stale entries]

4. MULTI-AGENT: No decomposition strategy. Add decision tree to CLAUDE.md.
   [Action: Add decision tree from Area 4]

5. ENVIRONMENT: No hooks configured. Add lint and test hooks.
   [Action: Add hook config from Area 8 to settings.json]

References

• references/knowledge-base.md -- Detailed patterns, anti-patterns, configuration examples
• scripts/audit.py -- Automated scanning script for preliminary scoring
• examples/ -- Sample CLAUDE.md files, permission templates, memory structures