Skip to content

context-audit-prompt.md

Latest commit

 

History

History
544 lines (407 loc) · 19.3 KB

context-audit-prompt.md

File metadata and controls

544 lines (407 loc) · 19.3 KB
Raw

Audit Your Context Engineering Setup

A self-contained prompt to measure and improve your Claude Code context architecture.

Author: Florian BRUNIAUX | Founding Engineer @Méthode Aristote

Reference: The Ultimate Claude Code Guide

1. What This Does

This prompt instructs Claude to audit your context engineering setup by:

  1. Measuring total always-on context size, CLAUDE.md length, and path-scoping ratio
  2. Detecting skills-to-rules balance, redundancy, and negative vs positive instructions
  3. Flagging staleness signals (last updated, broken imports, deprecated references)
  4. Scoring across 8 dimensions for a total of /100 with prioritized recommendations

Performance: Uses bash/grep for efficient scanning. Claude reads files only when specific content analysis is needed.

Important: Claude will NOT make any changes without your explicit approval.

2. Who This Is For

Level What You Get
Solo developer Find quick wins: trim bloat, add missing sections, fix stale imports
Small team (2-10) Identify consistency gaps and opportunities for profile-based assembly
Large team (10+) Systematic context architecture assessment with maturity scoring

Prerequisites:

  • Claude Code installed and working
  • A project with at least a CLAUDE.md or .claude/ directory
  • Bash shell (native on macOS/Linux, WSL on Windows)

Time: ~3-5 minutes

3. How to Use It

Step 1: Copy the Prompt

Copy everything inside the code block in Section 4 below.

Step 2: Run Claude Code

cd your-project-directory
claude

Step 3: Paste and Execute

Paste the prompt and press Enter. Claude will begin the audit.

Step 4: Review Results

Claude will present findings, then ask for validation before making any changes.

Platform Note

Platform Global Config Path
macOS/Linux ~/.claude/
Windows %USERPROFILE%\.claude\

4. The Prompt

# Audit My Context Engineering Setup

## Context

Perform a comprehensive context engineering audit of my Claude Code configuration.
Focus on context size, structure quality, freshness, and team scalability.

Reference: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md

## Instructions

### Phase 1: Discovery (Bash Scan)

**IMPORTANT**: Use bash commands exclusively in this phase. Do NOT read files yet.

#### 1.1 Size & Structure Scan

```bash
bash -c '
echo "=== GLOBAL CLAUDE.MD ==="
if [ -f ~/.claude/CLAUDE.md ]; then
  lines=$(wc -l < ~/.claude/CLAUDE.md | tr -d " ")
  chars=$(wc -c < ~/.claude/CLAUDE.md | tr -d " ")
  tokens=$(echo "scale=0; $chars / 4" | bc 2>/dev/null || echo "~$((chars/4))")
  echo "Lines: $lines"
  echo "Chars: $chars (~$tokens tokens)"
  echo "Imports: $(grep -c "^@" ~/.claude/CLAUDE.md 2>/dev/null || echo 0)"
  echo "Rules count: $(grep -cE "^[-*] |^\d+\. " ~/.claude/CLAUDE.md 2>/dev/null || echo 0)"
  echo "Last commit: $(cd ~/.claude && git log --format="%ar" -- CLAUDE.md 2>/dev/null | head -1 || echo "not tracked")"
else
  echo "NOT FOUND"
fi

echo ""
echo "=== PROJECT CLAUDE.MD ==="
for f in ./CLAUDE.md ./.claude/CLAUDE.md; do
  if [ -f "$f" ]; then
    lines=$(wc -l < "$f" | tr -d " ")
    chars=$(wc -c < "$f" | tr -d " ")
    tokens=$(echo "scale=0; $chars / 4" | bc 2>/dev/null || echo "~$((chars/4))")
    echo "File: $f"
    echo "Lines: $lines"
    echo "Chars: $chars (~$tokens tokens)"
    echo "Imports: $(grep -c "^@" "$f" 2>/dev/null || echo 0)"
    echo "Rules count: $(grep -cE "^[-*] |^\d+\. " "$f" 2>/dev/null || echo 0)"
    echo "Last commit: $(git log --format="%ar" -- "$f" 2>/dev/null | head -1 || echo "not tracked")"
  fi
done

echo ""
echo "=== IMPORTED FILES ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  while IFS= read -r line; do
    [[ "$line" =~ ^@ ]] || continue
    import_path="${line#@}"
    import_path="${import_path/ */}"
    resolved="${import_path/#\~/$HOME}"
    resolved="${resolved/#./$PWD}"
    if [ -f "$resolved" ]; then
      sz=$(wc -c < "$resolved" | tr -d " ")
      tk=$(echo "scale=0; $sz / 4" | bc 2>/dev/null || echo "$((sz/4))")
      echo "  FOUND $line (~$tk tokens)"
    else
      echo "  BROKEN $line (file not found)"
    fi
  done < "$f"
done

echo ""
echo "=== RULES & MODULES ==="
for d in ~/.claude ./.claude; do
  [ -d "$d" ] || continue
  for sub in rules skills commands agents hooks; do
    if [ -d "$d/$sub" ]; then
      count=$(find "$d/$sub" -maxdepth 1 -type f | wc -l | tr -d " ")
      total_chars=$(find "$d/$sub" -maxdepth 1 -type f -exec cat {} \; 2>/dev/null | wc -c | tr -d " ")
      tokens=$((total_chars / 4))
      echo "  $d/$sub: $count files (~$tokens tokens)"
    fi
  done
done
'

Store the output for evaluation.

1.2 Quality Pattern Scan

bash -c '
echo "=== NEGATIVE VS POSITIVE INSTRUCTIONS ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  neg=$(grep -ciE "never|do not|dont|avoid|prohibited|forbidden|not allowed|do NOT" "$f" 2>/dev/null || echo 0)
  pos=$(grep -ciE "always|prefer|use|should|must|recommended|do this" "$f" 2>/dev/null || echo 0)
  echo "$f: negative=$neg positive=$pos"
done

echo ""
echo "=== VAGUE INSTRUCTIONS (red flags) ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  echo "$f:"
  grep -inE "be careful|good practice|appropriately|as needed|when necessary|use your judgment|you should know|be smart" "$f" 2>/dev/null | head -5 || echo "  none found"
done

echo ""
echo "=== DUPLICATE SECTION HEADERS ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  dupes=$(grep -E "^#{1,3} " "$f" | sort | uniq -d)
  [ -n "$dupes" ] && echo "$f DUPLICATES: $dupes" || echo "$f: no duplicate headers"
done

echo ""
echo "=== DEPRECATED REFERENCES ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  echo "$f:"
  grep -niE "claude-1|claude-2\.0|claude-3-haiku-|gpt-3\.5|text-davinci|codex|copilot X|cursor pro 1\." "$f" 2>/dev/null | head -5 || echo "  none found"
done

echo ""
echo "=== PATH SCOPING (modular setup) ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  scoped=$(grep -cE "^@.+\.(ts|tsx|js|jsx|py|rs|go|md)$|globs:|path:" "$f" 2>/dev/null || echo 0)
  echo "$f path-scoped entries: $scoped"
done

echo ""
echo "=== SESSION & UPDATE PROTOCOL ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  has_update=$(grep -ciE "update|review|quarterly|maintenance|how to update|keep.*fresh" "$f" 2>/dev/null || echo 0)
  has_session=$(grep -ciE "session|retro|checkpoint|lesson learned|knowledge loop" "$f" 2>/dev/null || echo 0)
  echo "$f: update-protocol=$has_update session-retro=$has_session"
done

echo ""
echo "=== TEAM/PROFILE READINESS ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  has_profile=$(grep -ciE "profile|role:|junior|senior|lead|persona|persona-" "$f" 2>/dev/null || echo 0)
  has_module=$(grep -cE "^@" "$f" 2>/dev/null || echo 0)
  echo "$f: profile-mentions=$has_profile module-imports=$has_module"
done
'

Store the output for evaluation.

1.3 Freshness & Conflict Scan

bash -c '
echo "=== GIT FRESHNESS ==="
for path in ~/.claude ./; do
  if git -C "$path" rev-parse --git-dir &>/dev/null 2>&1; then
    echo "Repo at $path:"
    git -C "$path" log --format="%ar %s" -- CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -3 || echo "  no commits for CLAUDE.md"
  fi
done

echo ""
echo "=== CONFLICTING RULES PATTERNS ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  echo "$f:"
  # Look for contradictory patterns like "always X" near "never X"
  always_terms=$(grep -ioE "always [a-z ]+" "$f" 2>/dev/null | sed "s/always //i" | sort)
  never_terms=$(grep -ioE "never [a-z ]+" "$f" 2>/dev/null | sed "s/never //i" | sort)
  conflicts=$(comm -12 <(echo "$always_terms") <(echo "$never_terms") 2>/dev/null)
  [ -n "$conflicts" ] && echo "  POTENTIAL CONFLICTS: $conflicts" || echo "  no obvious contradictions"
done

echo ""
echo "=== OVERVIEW / ARCHITECTURE SECTION ==="
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
  [ -f "$f" ] || continue
  has_overview=$(grep -ciE "^## (overview|purpose|about|architecture|what this|context)" "$f" 2>/dev/null || echo 0)
  has_antip=$(grep -ciE "anti.pattern|bad example|do not do|wrong way|pitfall" "$f" 2>/dev/null || echo 0)
  has_hierarchy=$(grep -cE "^#{1,3} " "$f" 2>/dev/null || echo 0)
  echo "$f: has-overview=$has_overview anti-patterns=$has_antip section-count=$has_hierarchy"
done
'

Store the output for evaluation.

Phase 2: Evaluate Across 8 Dimensions

Use the scan outputs from Phase 1. Read specific file sections only if content examples are needed for the report.

Dimension 1: Size & Budget (15 pts)

Evaluate based on token estimates from Phase 1:

Check Points Threshold
Total always-on context under 8K tokens 5 Sum of all CLAUDE.md + imports
Rule count under 150 instructions 5 global + project combined
No single file over 400 lines 5 flag if exceeded

Deduct points proportionally if thresholds are exceeded. A file at 600 lines = 3/5 not 0.

Dimension 2: Structure (15 pts)

Check Points Signal
Has an overview/purpose section 4 h2 with "overview", "purpose", "about", "context"
Has architecture or project-layout section 3 h2 with "architecture", "structure", "layout"
Includes anti-patterns or bad examples 4 "anti-pattern", "do not", "pitfall"
Section count indicates clear hierarchy 4 3+ distinct h2 sections

Dimension 3: Path-Scoping (12 pts)

Check Points Signal
Uses @imports for modular breakdown 5 at least 2 @import lines
At least one path-specific or glob-scoped rule 4 globs: or file-specific section
Not a monolithic file (all instructions in one block) 3 multiple files or sections

Dimension 4: Rule Quality (15 pts)

Check Points Signal
Ratio positive:negative >= 2:1 5 from negative/positive counts
No vague instructions detected 5 zero "be careful", "as needed", etc.
Rules are specific and actionable 5 judged from sample during report generation

Dimension 5: Freshness (12 pts)

Check Points Signal
CLAUDE.md committed within past 6 months 5 git log output
No deprecated tool/model references 4 deprecated scan output
No broken @imports 3 BROKEN lines in import scan

Dimension 6: Team Readiness (10 pts)

Check Points Signal
Has profile-based or role-based structure 4 profile mentions >= 1
Module imports enable selective assembly 3 module-imports >= 3
Documented update protocol for team 3 update-protocol >= 1

Dimension 7: Conflict Detection (11 pts)

Check Points Signal
No contradictory rules detected 5 no conflicts from scan
No duplicate section headers 3 no duplicates found
Session retro or knowledge loop pattern 3 session-retro >= 1

Dimension 8: Knowledge Loop (10 pts)

Check Points Signal
Has update/review protocol documented 4 update-protocol >= 1
Has session retro or lesson-learned pattern 3 session-retro >= 1
Context tracked in git (auditable changes) 3 git freshness scan shows commits

Calculate Total Score

Score = sum of earned points across all 8 dimensions

Phase 3: Generate Report

Structure your output exactly as:

Context Engineering Audit

Score: [XX]/100

Dimension Score Notes
Size & Budget X/15 total ~X tokens, X rules
Structure X/15 X sections, has/missing overview
Path-Scoping X/12 X imports, monolithic/modular
Rule Quality X/15 X% positive, X vague found
Freshness X/12 last updated X, X broken imports
Team Readiness X/10 X profiles, update protocol: yes/no
Conflict Detection X/11 X contradictions, X duplicate headers
Knowledge Loop X/10 git tracked: yes/no, retro: yes/no

Context Budget

  • Global CLAUDE.md: ~X tokens
  • Project CLAUDE.md: ~X tokens
  • @imports combined: ~X tokens
  • Total always-on: ~X tokens
  • Rule count: X/150 instructions

Priority Issues (fix these first)

  1. [Issue] — [specific fix with example]
  2. [Issue] — [specific fix with example]
  3. [Issue] — [specific fix with example]

Quick Wins (< 30 min each)

  • [Fix]: [what to do and where]
  • [Fix]: [what to do and where]
  • [Fix]: [what to do and where]

Maturity Level

[Choose one and explain why]

Level 1 — Empty (0-19): No structured context. Claude operates with zero project knowledge. Level 2 — Basic (20-39): CLAUDE.md exists but is monolithic, stale, or mostly vague rules. Level 3 — Structured (40-59): Clear sections and imports, but missing freshness or team patterns. Level 4 — Optimized (60-79): Modular, scoped, positive-first rules with a known update cadence. Level 5 — Engineering-Grade (80-100): Profile-aware, git-tracked, conflict-free, knowledge loop active.

Ready-to-use Improvements

Provide 2-3 concrete text blocks that users can paste directly into their CLAUDE.md. Each block must address a Priority Issue identified above. Format:

Improvement 1: [name] File: [path] — add at [top/section X/end]

[exact text to paste]

Improvement 2: [name] File: [path] — add at [top/section X/end]

[exact text to paste]

Phase 4: Await Validation

CRITICAL: Do NOT create or modify any files without explicit approval.

After presenting the report, ask:

"Which improvements would you like me to implement?

Options:

  • all — Apply all ready-to-use improvements
  • 1, 2 — Specific improvements by number
  • priority — Only Priority Issues fixes
  • none — Keep the report for reference only

Please specify your choice:"

Wait for explicit user response before taking any action.

Output Format

Structure your response exactly as:

  1. Score table with dimension breakdown
  2. Context Budget summary
  3. Priority Issues (numbered, fix first)
  4. Quick Wins (bullet list, < 30 min each)
  5. Maturity Level with explanation
  6. Ready-to-use Improvements (paste-ready text blocks)
  7. Validation Request (ask before implementing)

---

## 5. What to Expect

Here's an example of what the audit report looks like:

### Example Score Table

Context Engineering Audit

Score: 52/100

Dimension Score Notes
Size & Budget 10/15 ~6,200 tokens total, 182 rules (over limit)
Structure 9/15 4 sections, no anti-patterns section
Path-Scoping 4/12 1 import, monolithic project CLAUDE.md
Rule Quality 8/15 60% positive, 3 vague instructions found
Freshness 9/12 last commit 4 months ago, 1 broken import
Team Readiness 3/10 no profiles, no update protocol
Conflict Detection 6/11 1 "always/never" contradiction, no duplicate headers
Knowledge Loop 3/10 not git tracked, no retro pattern 

### Example Quick Wins

Quick Wins (< 30 min each):

  • Fix broken import: @~/.claude/TONE.md not found — update path or remove
  • Add overview section: 2-line project description at top of CLAUDE.md
  • Trim rule count: merge 3 formatting rules into one compressed block

---

## 6. Scoring Guide

| Score | Maturity | Recommended Action |
|-------|----------|--------------------|
| **80-100** | Level 5: Engineering-Grade | Maintain with quarterly review |
| **60-79** | Level 4: Optimized | Address priority issues, reach 80 |
| **40-59** | Level 3: Structured | Dedicate a session to improvement |
| **20-39** | Level 2: Basic | Restructure recommended, use template |
| **0-19** | Level 1: Empty | Start fresh with skeleton template |

---

## 7. Glossary

| Term | Definition |
|------|-----------|
| **Always-on context** | Everything Claude loads before your first message: CLAUDE.md files plus all @imports |
| **@import** | A line starting with `@` in CLAUDE.md that loads another file into context |
| **Path-scoping** | Applying rules only to specific file types or directories, not globally |
| **Rule quality** | Specificity and actionability of instructions — vague rules waste tokens and confuse Claude |
| **Knowledge loop** | The practice of updating context files after sessions based on what worked and what didn't |
| **Profile assembly** | Combining different context modules to create role-specific setups (junior, senior, reviewer) |
| **Staleness signal** | Indicators that context is outdated: broken imports, deprecated model names, no git history |
| **Conflict** | Two rules that contradict each other — Claude will pick one arbitrarily, usually the wrong one |
| **Monolithic CLAUDE.md** | A single large file with all instructions, no imports, no modular breakdown |
| **Maturity level** | A 1-5 scale measuring context engineering sophistication from empty to engineering-grade |

---

## 8. Common Issues

### "Token estimate seems off"

**Cause**: The estimate uses chars/4 as a rough proxy for GPT-style tokens. Claude's tokenizer may differ slightly.

**Fix**: Focus on relative numbers and thresholds rather than absolute token counts. The 8K always-on budget is a heuristic, not a hard limit.

### "Score is low but Claude seems to work fine"

**Cause**: Claude works without context engineering — the score reflects optimization, not basic functionality.

**Fix**: A low score means you're leaving productivity on the table. Each dimension gap adds cognitive overhead per session.

### "Broken import flagged but file exists"

**Cause**: Relative path resolution differs from Claude's actual working directory at startup.

**Fix**: Use absolute paths (`~/.claude/file.md`) for global imports. Use project-relative paths (`./docs/conventions.md`) for project imports.

### "Profile-readiness flagged but I'm solo"

**Cause**: The audit checks for team-scalability patterns regardless of team size.

**Fix**: Profile-based assembly still benefits solo developers when switching contexts (reviewing PRs vs writing features vs debugging). It is optional for solo use.

---

## 9. Related Resources

- [The Ultimate Claude Code Guide](../guide/ultimate-guide.md) - Full reference
- [Audit Your Claude Code Setup](./audit-prompt.md) - Full configuration audit (agents, hooks, MCP, CI)
- [Cheatsheet](../guide/cheatsheet.md) - Quick daily reference
- [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code) - Anthropic documentation
- [context-evaluator.ai](https://context-evaluator.ai) - Zero-install LLM-native audit for CLAUDE.md and AGENTS.md: 17 AI evaluators, automated `.patch` remediation. Complements this prompt with deeper rule-by-rule analysis and a different evaluation angle (LLM-as-judge vs bash heuristics).

---

*Last updated: April 2026 | Version 1.1*