feat(context): Context Engineering Configurator + consolidated guide (v3.34.0)
New: interactive configurator at cc.bruniaux.com/context/ that generates a personalized CLAUDE.md starter kit based on team size, stack, and current setup. Multi-step flow (profile, current state, stack, results) with maturity scoring (Level 1-5), copy-to-clipboard artifacts, localStorage persistence. Guide content: - guide/core/context-engineering.md (1,188 lines, 8 sections): context budget, 150-instruction ceiling, modular architecture, team assembly, ACE pipeline, quality measurement, context reduction techniques - examples/context-engineering/ (10 templates): assembler.ts, profile-template.yaml, skeleton-template.md, canary-check.sh, ci-drift-check.yml, eval-questions.yaml, context-budget-calculator.sh, rules/knowledge-feeding.md, rules/update-loop-retro.md - tools/context-audit-prompt.md (543 lines): 8-dimension scoring /100 Navigation: guide/README.md, machine-readable/reference.yaml (24 new entries) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
318ba915de
commit
fe28f89574
19 changed files with 3545 additions and 15 deletions
543
tools/context-audit-prompt.md
Normal file
543
tools/context-audit-prompt.md
Normal file
|
|
@ -0,0 +1,543 @@
|
|||
# Audit Your Context Engineering Setup
|
||||
|
||||
> A self-contained prompt to measure and improve your Claude Code context architecture.
|
||||
|
||||
**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
|
||||
|
||||
**Reference**: [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 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](#4-the-prompt) below.
|
||||
|
||||
### Step 2: Run Claude Code
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
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
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
*Last updated: March 2026 | Version 1.0*
|
||||
Loading…
Add table
Add a link
Reference in a new issue