diff --git a/CHANGELOG.md b/CHANGELOG.md index 01b905c..1f6caf0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ## [Unreleased] +## [3.34.0] - 2026-03-11 + +### Added + +- **Context Engineering Configurator** (`cc.bruniaux.com/context/`) — Interactive multi-step configurator that generates a personalized CLAUDE.md starter kit. 5-screen flow: profile (team size, AI tools), current state (existing CLAUDE.md, rules files), stack (language, frontend), results (generated artifacts + maturity assessment). Features: generated CLAUDE.md preview with copy-to-clipboard, Profile YAML for team setups, maturity badge (Level 1-5), personalized next-steps roadmap, localStorage persistence. Vanilla JS, no framework. Nav: added "Context" to landing header dropdown. + +- **`guide/core/context-engineering.md`** — New consolidated reference (1,188 lines) covering all context engineering concepts. 8 sections: (1) What is Context Engineering (Karpathy's definition, prompt vs. context engineering distinction, three-layer model); (2) The Context Budget (token math, 150-instruction ceiling, HumanLayer 15-25% adherence data, path-scoping efficiency, overload signs); (3) Configuration Hierarchy (global/project/session split, decision tree for rule placement, override semantics); (4) Modular Architecture (path-scoping, skills vs. rules distinction, progressive disclosure, anti-pattern: monolithic CLAUDE.md); (5) Team Assembly (N×M×P problem, profile YAML, assembly workflow, CI drift detection, module library structure); (6) Context Lifecycle (instruction debt, update loop, knowledge feeding, ACE pipeline, session retrospective); (7) Quality Measurement (self-evaluation questions, canary checks, adherence tracking, context debt score formula); (8) Context Reduction Techniques (path-scoping -40-50%, negative constraints +15-25%, rule compression, deduplication, archive pattern). + +- **`examples/context-engineering/`** — 10 production-ready templates: `README.md` (overview + quick start), `profile-template.yaml` (developer profile for context assembly), `skeleton-template.md` (CLAUDE.md skeleton with filled placeholders), `assembler.ts` (~240-line TypeScript script for profile-based assembly with @import resolution, dry-run support, token estimation), `eval-questions.yaml` (20 self-evaluation questions across 4 dimensions), `canary-check.sh` (5-check behavioral regression script), `ci-drift-check.yml` (weekly GitHub Actions drift detection with auto-issue creation), `context-budget-calculator.sh` (measures always-on token cost), `rules/knowledge-feeding.md` (proactive context update protocol), `rules/update-loop-retro.md` (session retrospective template). + +- **`tools/context-audit-prompt.md`** — Self-contained context audit prompt (543 lines) following `audit-prompt.md` pattern. Scores context engineering setup /100 across 8 dimensions: Size & Budget (15 pts), Structure (15 pts), Path-Scoping (12 pts), Rule Quality (15 pts), Freshness (12 pts), Team Readiness (10 pts), Conflict Detection (11 pts), Knowledge Loop (10 pts). Includes 3 bash scan phases, report format with context budget breakdown, 5-level maturity ladder, and ready-to-use paste improvements. + +- **`src/data/context-data.ts`** (landing) — TypeScript data file with all configurator types, option arrays (team size, AI tools, stack, frontend), maturity level definitions (5 levels: Starter/Modular/Team-Ready/Measured/Adaptive), and template generators (`generateClaudeMd`, `generateProfileYaml`, `calculateMaturityLevel`). + +### Updated + +- **`guide/README.md`** — Added `core/context-engineering.md` row to Core Reference table. +- **`machine-readable/reference.yaml`** — Added 24 context engineering entries with paths to guide, examples, tools, and landing configurator. +- **`src/components/global/Header.astro`** (landing) — Added "Context" to moreLinks dropdown. + ## [3.33.1] - 2026-03-10 ### Updated diff --git a/README.md b/README.md index f385882..5fc53c7 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

Stars - Last Update + Last Update Quiz Templates Threat Database @@ -872,7 +872,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. --- -*Version 3.33.1 | Updated daily · Mar 10, 2026 | Crafted with Claude* +*Version 3.34.0 | Updated daily · Mar 11, 2026 | Crafted with Claude* ` + } + const imported = fs.readFileSync(fullPath, 'utf8') + return resolveImports(imported, path.dirname(fullPath), depth + 1) + }) +} + +function loadModule( + modulePath: string, + modulesDir: string, + result: AssemblyResult +): string { + const fullPath = path.resolve(modulesDir, modulePath) + if (!fs.existsSync(fullPath)) { + console.warn(` Warning: module not found — ${fullPath}`) + result.modulesMissing.push(modulePath) + return '' + } + const raw = fs.readFileSync(fullPath, 'utf8') + const resolved = resolveImports(raw, path.dirname(fullPath)) + const importsInFile = (raw.match(/^@.+$/gm) || []).length + result.importsResolved += importsInFile + result.modulesLoaded++ + return resolved +} + +function buildHeader(profile: Profile): string { + const { name, role, seniority, tools, style } = profile.profile + return [ + `# CLAUDE.md`, + `# Assembled for: ${name} | Role: ${role} | Seniority: ${seniority}`, + `# Generated: ${new Date().toISOString().split('T')[0]}`, + `# Stack: ${tools.primary_lang}${tools.frontend !== 'none' ? ` + ${tools.frontend}` : ''}${tools.backend !== 'none' ? ` + ${tools.backend}` : ''}`, + `# Style: verbosity=${style.verbosity}, comments=${style.comment_style}, tests=${style.test_coverage}`, + '', + ].join('\n') +} + +function buildOverrides(rules: string[]): string { + if (rules.length === 0) return '' + return [ + '\n## Personal Rules', + '', + ...rules.map((r) => `- ${r}`), + '', + ].join('\n') +} + +// ── Core ───────────────────────────────────────────────────────────────────── + +function assemble( + profilePath: string, + outputPath: string, + modulesDir: string, + dryRun: boolean +): AssemblyResult { + const profile = loadProfile(profilePath) + const result: AssemblyResult = { + content: '', + totalChars: 0, + estimatedTokens: 0, + modulesLoaded: 0, + modulesMissing: [], + importsResolved: 0, + } + + const sections: string[] = [buildHeader(profile)] + + for (const modulePath of profile.modules.include) { + if (profile.modules.exclude.includes(modulePath)) { + console.log(` Skipped (excluded): ${modulePath}`) + continue + } + const content = loadModule(modulePath, modulesDir, result) + if (content) { + sections.push(`\n\n`) + sections.push(content.trim()) + } + } + + const overrides = buildOverrides(profile.overrides.custom_rules) + if (overrides) sections.push(overrides) + + result.content = sections.join('\n') + result.totalChars = result.content.length + result.estimatedTokens = Math.round(result.totalChars / 4) + + if (!dryRun) { + fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true }) + fs.writeFileSync(outputPath, result.content) + } + + return result +} + +// ── CLI ─────────────────────────────────────────────────────────────────────── + +function parseArgs(): { + profilePath: string + outputPath: string + modulesDir: string + dryRun: boolean +} { + const args = process.argv.slice(2) + const get = (flag: string, fallback: string): string => { + const idx = args.indexOf(flag) + return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback + } + return { + profilePath: get('--profile', '.claude/profiles/default.yaml'), + outputPath: get('--output', 'CLAUDE.md'), + modulesDir: get('--modules', '.claude/modules'), + dryRun: args.includes('--dry-run'), + } +} + +function main() { + const { profilePath, outputPath, modulesDir, dryRun } = parseArgs() + + console.log('Context Assembler') + console.log('=================') + console.log(`Profile: ${profilePath}`) + console.log(`Modules: ${modulesDir}`) + console.log(`Output: ${outputPath}${dryRun ? ' (dry-run — not written)' : ''}`) + console.log('') + + try { + const result = assemble(profilePath, outputPath, modulesDir, dryRun) + + console.log('') + console.log('Summary:') + console.log(` Modules loaded: ${result.modulesLoaded}`) + console.log(` Modules missing: ${result.modulesMissing.length}`) + console.log(` @imports resolved: ${result.importsResolved}`) + console.log(` Output size: ${result.totalChars} chars (~${result.estimatedTokens} tokens)`) + + if (result.modulesMissing.length > 0) { + console.log('') + console.log('Missing modules (create these files or remove from profile):') + for (const m of result.modulesMissing) { + console.log(` - ${m}`) + } + } + + if (result.estimatedTokens > 10000) { + console.log('') + console.log( + `Warning: ~${result.estimatedTokens} tokens is on the heavy side (target <10K).` + ) + console.log(' Consider splitting into per-task @imports instead of always-on.') + } + + if (!dryRun) { + console.log('') + console.log(`Done: ${outputPath}`) + } + } catch (err) { + console.error(`Error: ${(err as Error).message}`) + process.exit(1) + } +} + +main() diff --git a/examples/context-engineering/canary-check.sh b/examples/context-engineering/canary-check.sh new file mode 100755 index 0000000..de43f11 --- /dev/null +++ b/examples/context-engineering/canary-check.sh @@ -0,0 +1,285 @@ +#!/bin/bash +# Context Engineering Canary Check +# +# Runs structural validation tests against your CLAUDE.md configuration. +# Catches common drift issues: missing files, broken imports, bloated size, conflicting rules. +# +# Usage: +# ./canary-check.sh # Check current directory +# ./canary-check.sh /path/to/project # Check specific project +# +# Exit codes: +# 0 — all checks passed +# N — number of issues found +# +# Run this weekly, or add it to your pre-commit hook for critical projects. + +set -euo pipefail + +PROJECT_DIR="${1:-.}" +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" # Resolve to absolute path + +PASS=0 +FAIL=0 +WARN=0 +RESULTS=() + +# ── Result tracking ─────────────────────────────────────────────────────────── + +log_pass() { + local test="$1" + local detail="${2:-}" + RESULTS+=("PASS $test${detail:+: $detail}") + PASS=$((PASS + 1)) +} + +log_fail() { + local test="$1" + local detail="${2:-}" + RESULTS+=("FAIL $test${detail:+: $detail}") + FAIL=$((FAIL + 1)) +} + +log_warn() { + local test="$1" + local detail="${2:-}" + RESULTS+=("WARN $test${detail:+: $detail}") + WARN=$((WARN + 1)) +} + +# ── Check 1: CLAUDE.md exists and is non-trivial ────────────────────────────── + +check_claude_md_exists() { + local file="$PROJECT_DIR/CLAUDE.md" + if [ ! -f "$file" ]; then + log_fail "CLAUDE.md exists" "Not found at $file" + return 1 + fi + log_pass "CLAUDE.md exists" "$file" + return 0 +} + +check_claude_md_size() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local lines + lines=$(wc -l < "$file" | tr -d ' ') + + if [ "$lines" -lt 10 ]; then + log_fail "CLAUDE.md has content" "Only $lines lines — too sparse to be useful" + elif [ "$lines" -gt 500 ]; then + log_warn "CLAUDE.md size" "$lines lines exceeds 500 — consider modularizing with @imports" + else + log_pass "CLAUDE.md size" "$lines lines (healthy: 10-500)" + fi +} + +# ── Check 2: Broken @imports ────────────────────────────────────────────────── + +check_imports() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local broken=0 + local resolved=0 + + while IFS= read -r line; do + if [[ "$line" =~ ^@([^[:space:]].+)$ ]]; then + local import_path="${BASH_REMATCH[1]}" + local full_path="$PROJECT_DIR/$import_path" + if [ ! -f "$full_path" ]; then + log_fail "Broken @import" "@$import_path — file not found" + broken=$((broken + 1)) + else + resolved=$((resolved + 1)) + fi + fi + done < "$file" + + if [ "$broken" -eq 0 ]; then + if [ "$resolved" -gt 0 ]; then + log_pass "@import resolution" "All $resolved @imports resolve" + else + log_pass "@import resolution" "No @imports (not using modular setup)" + fi + fi +} + +# ── Check 3: Rule count ─────────────────────────────────────────────────────── + +check_rule_count() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local rules + rules=$(grep -cE "^[[:space:]]*[-*] |^[[:space:]]*[0-9]+\. " "$file" 2>/dev/null || echo "0") + + if [ "$rules" -gt 150 ]; then + log_warn "Rule count" "$rules rules (adherence ceiling is ~150 — Claude may drop rules)" + else + log_pass "Rule count" "$rules rules" + fi +} + +# ── Check 4: Conflicting always/never rules ─────────────────────────────────── + +check_conflicts() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local conflicts=0 + local topics=("comments" "tests" "types" "imports" "exports" "logging" "errors") + + for topic in "${topics[@]}"; do + local always_count never_count + always_count=$(grep -ciE "always[[:space:]]+[a-z ]*$topic|$topic[a-z ]*[[:space:]]+always" "$file" 2>/dev/null || echo "0") + never_count=$(grep -ciE "never[[:space:]]+[a-z ]*$topic|$topic[a-z ]*[[:space:]]+never" "$file" 2>/dev/null || echo "0") + + if [ "$always_count" -gt 0 ] && [ "$never_count" -gt 0 ]; then + log_warn "Potential conflict: $topic" "Both 'always' and 'never' rules found — verify they don't contradict" + conflicts=$((conflicts + 1)) + fi + done + + if [ "$conflicts" -eq 0 ]; then + log_pass "Conflict check" "No obvious always/never contradictions detected" + fi +} + +# ── Check 5: Git tracking and freshness ─────────────────────────────────────── + +check_git_tracking() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + if ! command -v git &>/dev/null; then + log_warn "Git tracking" "git not available — skipping" + return + fi + + if ! git -C "$PROJECT_DIR" rev-parse --git-dir &>/dev/null 2>&1; then + log_warn "Git tracking" "Not a git repo — skipping" + return + fi + + # Check if tracked + if ! git -C "$PROJECT_DIR" ls-files --error-unmatch CLAUDE.md &>/dev/null 2>&1; then + log_fail "CLAUDE.md in git" "File exists but is not tracked — run: git add CLAUDE.md" + return + fi + + # Check freshness + local last_updated + last_updated=$(git -C "$PROJECT_DIR" log --format="%ar" -- CLAUDE.md 2>/dev/null | head -1) + + if [ -z "$last_updated" ]; then + log_warn "CLAUDE.md freshness" "No git history for this file" + else + log_pass "CLAUDE.md freshness" "Last updated: $last_updated" + fi +} + +# ── Check 6: Required sections ──────────────────────────────────────────────── + +check_required_sections() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local missing=0 + local -a required_sections=("Overview\|Purpose\|Description" "Architecture\|Stack\|Tech" "Standards\|Conventions\|Style") + + for pattern in "${required_sections[@]}"; do + if ! grep -qiE "^#+ ($pattern)" "$file" 2>/dev/null; then + local display="${pattern//\\|/ or }" + log_warn "Missing section" "No heading matching: $display" + missing=$((missing + 1)) + fi + done + + if [ "$missing" -eq 0 ]; then + log_pass "Required sections" "Overview, Architecture, and Standards sections found" + fi +} + +# ── Check 7: Token budget estimate ─────────────────────────────────────────── + +check_token_budget() { + local file="$PROJECT_DIR/CLAUDE.md" + [ ! -f "$file" ] && return + + local chars + chars=$(wc -c < "$file" | tr -d ' ') + local tokens=$((chars / 4)) + + # Sum up @imports too + local import_tokens=0 + while IFS= read -r line; do + if [[ "$line" =~ ^@([^[:space:]].+)$ ]]; then + local import_path="${BASH_REMATCH[1]}" + local full_path="$PROJECT_DIR/$import_path" + if [ -f "$full_path" ]; then + local import_chars + import_chars=$(wc -c < "$full_path" | tr -d ' ') + import_tokens=$((import_tokens + import_chars / 4)) + fi + fi + done < "$file" + + local total=$((tokens + import_tokens)) + + if [ "$total" -lt 2000 ]; then + log_pass "Token budget" "~$total tokens (lean)" + elif [ "$total" -lt 10000 ]; then + log_pass "Token budget" "~$total tokens (healthy)" + elif [ "$total" -lt 25000 ]; then + log_warn "Token budget" "~$total tokens (heavy — consider trimming)" + else + log_fail "Token budget" "~$total tokens (overloaded — Claude will likely ignore some rules)" + fi +} + +# ── Run all checks ──────────────────────────────────────────────────────────── + +echo "Context Engineering Canary Check" +echo "=================================" +echo "Project: $PROJECT_DIR" +echo "" + +check_claude_md_exists || true +check_claude_md_size +check_imports +check_rule_count +check_conflicts +check_git_tracking +check_required_sections +check_token_budget + +# ── Summary ─────────────────────────────────────────────────────────────────── + +echo "" +echo "Results:" +echo "--------" +for result in "${RESULTS[@]}"; do + echo " $result" +done + +echo "" +echo "Score: $PASS passed, $WARN warnings, $FAIL failed" + +if [ "$FAIL" -gt 0 ]; then + echo "Status: ISSUES FOUND" + echo "" + echo "Next steps:" + echo " - Fix failing checks above" + echo " - Run ./eval-questions.yaml audit for deeper analysis" + echo " - See guide/core/context-engineering.md for remediation guidance" + exit "$FAIL" +elif [ "$WARN" -gt 0 ]; then + echo "Status: PASSED WITH WARNINGS" + echo " Address warnings to improve context quality" + exit 0 +else + echo "Status: ALL CHECKS PASSED" + exit 0 +fi diff --git a/examples/context-engineering/ci-drift-check.yml b/examples/context-engineering/ci-drift-check.yml new file mode 100644 index 0000000..b62843d --- /dev/null +++ b/examples/context-engineering/ci-drift-check.yml @@ -0,0 +1,216 @@ +name: Context Drift Check + +# Detects structural degradation in CLAUDE.md on a weekly schedule. +# Opens a GitHub issue automatically when problems are found. +# +# Setup: +# 1. Copy this file to .github/workflows/context-drift.yml +# 2. Make sure canary-check.sh is committed and executable +# 3. Adjust the cron schedule and threshold values as needed +# +# The workflow checks: +# - Structural validity (broken @imports, size, conflicts) +# - CLAUDE.md size trend (warns when exceeding threshold) +# - Broken @import references + +on: + schedule: + - cron: '0 9 * * 1' # Every Monday at 9:00 AM UTC + workflow_dispatch: # Allow manual trigger from GitHub UI + inputs: + project_dir: + description: 'Project directory to check (relative to repo root)' + required: false + default: '.' + +env: + # Customize these thresholds for your project + CLAUDE_MD_MAX_LINES: 500 + CLAUDE_MD_WARN_LINES: 400 + +jobs: + drift-check: + name: Check CLAUDE.md for drift + runs-on: ubuntu-latest + permissions: + contents: read + issues: write # Required to open issues on failure + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history needed for git log checks + + - name: Make canary script executable + run: chmod +x ./examples/context-engineering/canary-check.sh + + - name: Run structural canary checks + id: canary + run: | + PROJECT_DIR="${{ github.event.inputs.project_dir || '.' }}" + ./examples/context-engineering/canary-check.sh "$PROJECT_DIR" + continue-on-error: true # Capture exit code without stopping workflow + + - name: Check CLAUDE.md size against thresholds + id: size_check + run: | + FILE="CLAUDE.md" + if [ ! -f "$FILE" ]; then + echo "::warning::CLAUDE.md not found at repo root" + exit 0 + fi + + CURRENT=$(wc -l < "$FILE" | tr -d ' ') + echo "current_lines=$CURRENT" >> "$GITHUB_OUTPUT" + + if [ "$CURRENT" -gt "$CLAUDE_MD_MAX_LINES" ]; then + echo "::error::CLAUDE.md has $CURRENT lines (max: $CLAUDE_MD_MAX_LINES). Consider modularizing with @imports." + echo "size_status=fail" >> "$GITHUB_OUTPUT" + elif [ "$CURRENT" -gt "$CLAUDE_MD_WARN_LINES" ]; then + echo "::warning::CLAUDE.md has $CURRENT lines (warn threshold: $CLAUDE_MD_WARN_LINES). Getting large." + echo "size_status=warn" >> "$GITHUB_OUTPUT" + else + echo "CLAUDE.md size: $CURRENT lines (OK)" + echo "size_status=ok" >> "$GITHUB_OUTPUT" + fi + + - name: Check for stale @imports + id: import_check + run: | + FILE="CLAUDE.md" + if [ ! -f "$FILE" ]; then + exit 0 + fi + + BROKEN=0 + while IFS= read -r line; do + if [[ "$line" =~ ^@([^[:space:]].+)$ ]]; then + IMPORT="${BASH_REMATCH[1]}" + if [ ! -f "$IMPORT" ]; then + echo "::error::Broken @import in CLAUDE.md: @$IMPORT" + BROKEN=$((BROKEN + 1)) + fi + fi + done < "$FILE" + + echo "broken_imports=$BROKEN" >> "$GITHUB_OUTPUT" + + if [ "$BROKEN" -gt 0 ]; then + echo "::error::Found $BROKEN broken @import(s) in CLAUDE.md" + else + echo "All @imports resolve correctly" + fi + + - name: Check CLAUDE.md is git-tracked and recent + id: freshness_check + run: | + FILE="CLAUDE.md" + if [ ! -f "$FILE" ]; then + exit 0 + fi + + # Check if tracked + if ! git ls-files --error-unmatch "$FILE" > /dev/null 2>&1; then + echo "::warning::CLAUDE.md is not tracked in git" + exit 0 + fi + + # Get days since last update + LAST_COMMIT_DATE=$(git log -1 --format="%cd" --date=format:"%Y-%m-%d" -- "$FILE") + TODAY=$(date +%Y-%m-%d) + DAYS_OLD=$(( ($(date -d "$TODAY" +%s 2>/dev/null || date -j -f "%Y-%m-%d" "$TODAY" +%s) - $(date -d "$LAST_COMMIT_DATE" +%s 2>/dev/null || date -j -f "%Y-%m-%d" "$LAST_COMMIT_DATE" +%s)) / 86400 )) + + echo "days_old=$DAYS_OLD" >> "$GITHUB_OUTPUT" + echo "last_updated=$LAST_COMMIT_DATE" >> "$GITHUB_OUTPUT" + + if [ "$DAYS_OLD" -gt 90 ]; then + echo "::warning::CLAUDE.md was last updated $DAYS_OLD days ago ($LAST_COMMIT_DATE). Consider reviewing for stale rules." + else + echo "CLAUDE.md freshness: last updated $DAYS_OLD days ago ($LAST_COMMIT_DATE) — OK" + fi + + - name: Collect check results + id: summary + if: always() + run: | + CANARY_STATUS="${{ steps.canary.outcome }}" + BROKEN_IMPORTS="${{ steps.import_check.outputs.broken_imports || 0 }}" + SIZE_STATUS="${{ steps.size_check.outputs.size_status || 'ok' }}" + CURRENT_LINES="${{ steps.size_check.outputs.current_lines || 0 }}" + DAYS_OLD="${{ steps.freshness_check.outputs.days_old || 0 }}" + LAST_UPDATED="${{ steps.freshness_check.outputs.last_updated || 'unknown' }}" + + ISSUES=0 + [ "$CANARY_STATUS" = "failure" ] && ISSUES=$((ISSUES + 1)) + [ "$BROKEN_IMPORTS" -gt 0 ] && ISSUES=$((ISSUES + BROKEN_IMPORTS)) + [ "$SIZE_STATUS" = "fail" ] && ISSUES=$((ISSUES + 1)) + + echo "total_issues=$ISSUES" >> "$GITHUB_OUTPUT" + echo "summary_lines=$CURRENT_LINES" >> "$GITHUB_OUTPUT" + echo "summary_days=$DAYS_OLD" >> "$GITHUB_OUTPUT" + echo "summary_updated=$LAST_UPDATED" >> "$GITHUB_OUTPUT" + + - name: Open issue on failure + if: always() && steps.summary.outputs.total_issues > 0 + uses: actions/github-script@v7 + with: + script: | + const issues = parseInt('${{ steps.summary.outputs.total_issues }}'); + const lines = '${{ steps.summary.outputs.summary_lines }}'; + const daysOld = '${{ steps.summary.outputs.summary_days }}'; + const lastUpdated = '${{ steps.summary.outputs.summary_updated }}'; + const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; + + // Check if there's already an open issue for drift + const openIssues = await github.rest.issues.listForRepo({ + owner: context.repo.owner, + repo: context.repo.repo, + labels: 'ai-context,maintenance', + state: 'open', + }); + + if (openIssues.data.length > 0) { + // Add a comment to the existing issue instead of opening a new one + const existingIssue = openIssues.data[0]; + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: existingIssue.number, + body: `Weekly check still finding issues (${issues} problem(s)).\n\nRun: ${runUrl}\nCLAUDE.md: ${lines} lines, last updated: ${lastUpdated} (${daysOld} days ago)`, + }); + } else { + await github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: `Context Drift Detected — CLAUDE.md needs review`, + body: [ + `The weekly context drift check found **${issues} problem(s)** in \`CLAUDE.md\`.`, + ``, + `## Details`, + `- File size: ${lines} lines`, + `- Last updated: ${lastUpdated} (${daysOld} days ago)`, + `- Workflow run: ${runUrl}`, + ``, + `## Action Required`, + `1. Review the workflow logs for specific issues`, + `2. Run \`./examples/context-engineering/canary-check.sh .\` locally for details`, + `3. Fix broken @imports, reduce file size, or update stale rules`, + `4. Close this issue once CLAUDE.md is back in good shape`, + ``, + `_This issue was opened automatically by the context drift check workflow._`, + ].join('\n'), + labels: ['ai-context', 'maintenance'], + }); + } + + - name: Final status + if: always() + run: | + ISSUES="${{ steps.summary.outputs.total_issues }}" + if [ "$ISSUES" -gt 0 ]; then + echo "Context drift check: FAILED ($ISSUES issues)" + exit 1 + else + echo "Context drift check: PASSED" + fi diff --git a/examples/context-engineering/context-budget-calculator.sh b/examples/context-engineering/context-budget-calculator.sh new file mode 100755 index 0000000..3fd0e7e --- /dev/null +++ b/examples/context-engineering/context-budget-calculator.sh @@ -0,0 +1,188 @@ +#!/bin/bash +# Context Budget Calculator +# +# Measures the always-on token cost of your CLAUDE.md configuration. +# Accounts for: global CLAUDE.md, project CLAUDE.md, and all @imported modules. +# +# Usage: +# ./context-budget-calculator.sh # Check current directory +# ./context-budget-calculator.sh /path/to/project # Check specific project +# +# Token estimation: ~4 chars per token (approximate, varies by content type) +# +# Budget guide: +# < 2K tokens — lean (excellent) +# 2K-10K tokens — healthy (good range for most projects) +# 10K-25K tokens — heavy (review for trimming opportunities) +# > 25K tokens — overloaded (Claude will likely deprioritize some rules) + +set -euo pipefail + +PROJECT_DIR="${1:-.}" +PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" +GLOBAL_CLAUDE="$HOME/.claude/CLAUDE.md" +PROJECT_CLAUDE="$PROJECT_DIR/CLAUDE.md" + +# ── Helpers ─────────────────────────────────────────────────────────────────── + +estimate_tokens() { + local file="$1" + if [ ! -f "$file" ]; then + echo "0" + return + fi + local chars + chars=$(wc -c < "$file" | tr -d ' ') + echo $((chars / 4)) +} + +count_lines() { + local file="$1" + if [ ! -f "$file" ]; then + echo "0" + return + fi + wc -l < "$file" | tr -d ' ' +} + +count_rules() { + local file="$1" + if [ ! -f "$file" ]; then + echo "0" + return + fi + grep -cE "^[[:space:]]*[-*] |^[[:space:]]*[0-9]+\. " "$file" 2>/dev/null || echo "0" +} + +format_assessment() { + local tokens="$1" + if [ "$tokens" -lt 2000 ]; then + echo "LEAN — well under budget, headroom available" + elif [ "$tokens" -lt 10000 ]; then + echo "HEALTHY — good range for most projects" + elif [ "$tokens" -lt 25000 ]; then + echo "HEAVY — consider trimming or deferring to @imports" + else + echo "OVERLOADED — Claude will likely deprioritize some rules" + fi +} + +# ── Collect @imports from a file ────────────────────────────────────────────── + +collect_imports() { + local file="$1" + local base_dir="$2" + local -n imports_ref="$3" # nameref to array + + [ ! -f "$file" ] && return + + while IFS= read -r line; do + if [[ "$line" =~ ^@([^[:space:]].+)$ ]]; then + local import_path="${BASH_REMATCH[1]}" + local full_path="$base_dir/$import_path" + imports_ref+=("$import_path|$full_path") + fi + done < "$file" +} + +# ── Main ────────────────────────────────────────────────────────────────────── + +echo "Context Budget Calculator" +echo "=========================" +echo "Project: $PROJECT_DIR" +echo "" + +GRAND_TOTAL_TOKENS=0 +GRAND_TOTAL_RULES=0 + +# Global CLAUDE.md +echo "Global CLAUDE.md (~/.claude/CLAUDE.md)" +echo "----------------------------------------" +if [ -f "$GLOBAL_CLAUDE" ]; then + G_TOKENS=$(estimate_tokens "$GLOBAL_CLAUDE") + G_LINES=$(count_lines "$GLOBAL_CLAUDE") + G_RULES=$(count_rules "$GLOBAL_CLAUDE") + echo " Lines: $G_LINES" + echo " Rules: $G_RULES" + echo " Tokens: ~$G_TOKENS" + GRAND_TOTAL_TOKENS=$((GRAND_TOTAL_TOKENS + G_TOKENS)) + GRAND_TOTAL_RULES=$((GRAND_TOTAL_RULES + G_RULES)) +else + echo " (not found — no global config)" +fi +echo "" + +# Project CLAUDE.md +echo "Project CLAUDE.md ($PROJECT_CLAUDE)" +echo "----------------------------------------" +if [ -f "$PROJECT_CLAUDE" ]; then + P_TOKENS=$(estimate_tokens "$PROJECT_CLAUDE") + P_LINES=$(count_lines "$PROJECT_CLAUDE") + P_RULES=$(count_rules "$PROJECT_CLAUDE") + echo " Lines: $P_LINES" + echo " Rules: $P_RULES" + echo " Tokens: ~$P_TOKENS" + GRAND_TOTAL_TOKENS=$((GRAND_TOTAL_TOKENS + P_TOKENS)) + GRAND_TOTAL_RULES=$((GRAND_TOTAL_RULES + P_RULES)) +else + echo " (not found)" +fi +echo "" + +# @imports from project CLAUDE.md +declare -a IMPORTS=() +collect_imports "$PROJECT_CLAUDE" "$PROJECT_DIR" IMPORTS + +IMPORT_TOTAL_TOKENS=0 +if [ "${#IMPORTS[@]}" -gt 0 ]; then + echo "@imports (always-loaded modules)" + echo "----------------------------------------" + for entry in "${IMPORTS[@]}"; do + local_path="${entry%%|*}" + full_path="${entry##*|}" + if [ -f "$full_path" ]; then + I_TOKENS=$(estimate_tokens "$full_path") + I_LINES=$(count_lines "$full_path") + IMPORT_TOTAL_TOKENS=$((IMPORT_TOTAL_TOKENS + I_TOKENS)) + printf " %-45s %5d lines ~%d tokens\n" "@$local_path" "$I_LINES" "$I_TOKENS" + else + printf " %-45s %s\n" "@$local_path" "NOT FOUND" + fi + done + echo "" + echo " Import total: ~$IMPORT_TOTAL_TOKENS tokens" + GRAND_TOTAL_TOKENS=$((GRAND_TOTAL_TOKENS + IMPORT_TOTAL_TOKENS)) + echo "" +fi + +# Summary +echo "Summary" +echo "=======" +echo "" +echo " Total always-on tokens: ~$GRAND_TOTAL_TOKENS" +echo " Total rules/instructions: $GRAND_TOTAL_RULES" +echo "" + +ASSESSMENT=$(format_assessment "$GRAND_TOTAL_TOKENS") +echo " Budget assessment: $ASSESSMENT" + +if [ "$GRAND_TOTAL_RULES" -gt 150 ]; then + echo "" + echo " Rule count warning: $GRAND_TOTAL_RULES rules exceeds ~150" + echo " Claude's adherence decreases as rule count grows." + echo " Consider consolidating redundant rules or moving to task-scoped @imports." +fi + +echo "" +echo "Optimization Tips" +echo "-----------------" +if [ "$GRAND_TOTAL_TOKENS" -gt 10000 ]; then + echo " 1. Move reference material to @imports and load only when needed" + echo " 2. Trim verbose explanations — rules, not documentation" + echo " 3. Remove rules about deprecated tech that's been removed" + echo " 4. Consolidate duplicate rules across sections" + echo " 5. Global CLAUDE.md: keep to framework-level defaults, not project specifics" +else + echo " Budget is healthy. Maintain this range as the project grows." + echo " Set an alert when you approach $((GRAND_TOTAL_TOKENS + 3000)) tokens." +fi diff --git a/examples/context-engineering/eval-questions.yaml b/examples/context-engineering/eval-questions.yaml new file mode 100644 index 0000000..2d5e2eb --- /dev/null +++ b/examples/context-engineering/eval-questions.yaml @@ -0,0 +1,173 @@ +# Context Engineering Self-Evaluation +# +# Use these questions to audit your CLAUDE.md periodically. +# Score each question: pass (1) | partial (0.5) | fail (0) +# Target score: 16+ / 20 +# +# Run this quarterly, or after any significant project change. +# Low-scoring areas tell you exactly where to invest time. + +meta: + version: "1.0" + total_questions: 20 + passing_threshold: 16 + scoring: + pass: 1.0 + partial: 0.5 + fail: 0.0 + +questions: + # ── Coverage: Does CLAUDE.md contain the right information? ────────────────── + coverage: + description: "Checks that essential information is present" + questions: + - id: C1 + weight: 1.0 + question: "Does CLAUDE.md explain what this project does in 2-3 sentences?" + failing_indicator: "No Project Overview section, or it's vague ('a web app')" + passing_indicator: "Clear statement of purpose, audience, and deployment target" + + - id: C2 + weight: 1.0 + question: "Are the primary tech stack and versions documented?" + failing_indicator: "No version numbers, or stack listed without context" + passing_indicator: "Table or list with framework + version for each layer" + + - id: C3 + weight: 1.0 + question: "Are coding standards specific enough to be actionable?" + failing_indicator: "Rules like 'write clean code' or 'follow best practices'" + passing_indicator: "Rules like 'use zod for external input', 'no default exports'" + + - id: C4 + weight: 1.0 + question: "Are deployment environments and commands documented?" + failing_indicator: "No deployment section, or just 'deploy to production'" + passing_indicator: "Environments listed, deploy commands specified" + + - id: C5 + weight: 1.0 + question: "Are there explicit anti-patterns (what NOT to do)?" + failing_indicator: "No negative rules at all" + passing_indicator: "At least 3 explicit prohibitions with reasons" + + # ── Quality: Are the rules well-written? ──────────────────────────────────── + quality: + description: "Checks that rules are clear, non-redundant, and manageable" + questions: + - id: Q1 + weight: 1.0 + question: "Can each rule be followed without reading the rest of the file?" + failing_indicator: "Rules like 'follow the patterns established earlier'" + passing_indicator: "Each rule is self-contained and unambiguous" + + - id: Q2 + weight: 1.0 + question: "Are there fewer than 150 total rules or instructions?" + failing_indicator: "More than 150 bullet points / numbered items" + passing_indicator: "Compact set that fits in working memory" + note: "150 is the adherence ceiling — beyond this, Claude starts dropping rules" + + - id: Q3 + weight: 1.0 + question: "Does the file have fewer than 500 lines?" + failing_indicator: "File exceeds 500 lines" + passing_indicator: "Under 500 lines, or split into @imported modules" + note: "Long files signal either verbosity or lack of modularization" + + - id: Q4 + weight: 1.0 + question: "Are rules specific and measurable rather than vague?" + failing_indicator: "Rules that require judgment ('write readable code')" + passing_indicator: "Rules that produce consistent output across different prompts" + + - id: Q5 + weight: 1.0 + question: "Does each rule appear only once (no semantic duplicates)?" + failing_indicator: "Same constraint expressed in multiple ways across sections" + passing_indicator: "No redundancy — each constraint stated exactly once" + + # ── Adherence: Is Claude actually following the rules? ─────────────────────── + adherence: + description: "Behavioral checks — requires reviewing actual Claude outputs" + questions: + - id: A1 + weight: 1.0 + question: "Do Claude's outputs consistently follow the stated coding standards?" + how_to_check: "Ask Claude to write a new function and check it against your standards" + failing_indicator: "Claude uses patterns explicitly prohibited in CLAUDE.md" + passing_indicator: "Outputs match stated standards without prompting" + + - id: A2 + weight: 1.0 + question: "Does Claude correctly use the specified libraries and avoid alternatives?" + how_to_check: "Ask Claude to add input validation — does it use your specified library?" + failing_indicator: "Claude suggests alternatives you've explicitly excluded" + passing_indicator: "Claude reaches for the specified tools automatically" + + - id: A3 + weight: 1.0 + question: "Does Claude follow the git conventions when generating commits or PRs?" + how_to_check: "Ask Claude to write a commit message and check the format" + failing_indicator: "Wrong format, missing type prefix, wrong capitalization" + passing_indicator: "Commits match your conventional commits format exactly" + + - id: A4 + weight: 1.0 + question: "Does Claude avoid the listed anti-patterns?" + how_to_check: "Introduce a scenario where the anti-pattern would be tempting" + failing_indicator: "Claude suggests a prohibited pattern without flagging it" + passing_indicator: "Claude avoids the pattern or explicitly explains why it's excluded" + + - id: A5 + weight: 1.0 + question: "When given ambiguous instructions, does Claude make the right default choice?" + how_to_check: "Give a vague task ('add a cache') and see what Claude picks" + failing_indicator: "Claude invents a default that contradicts your architecture" + passing_indicator: "Claude's default aligns with your documented decisions" + + # ── Maintenance: Is the file healthy over time? ────────────────────────────── + maintenance: + description: "Checks that CLAUDE.md stays accurate as the project evolves" + questions: + - id: M1 + weight: 1.0 + question: "Was CLAUDE.md updated in the last 90 days?" + how_to_check: "git log --format='%ar' -- CLAUDE.md | head -1" + failing_indicator: "Last update more than 90 days ago" + passing_indicator: "Updated within 90 days, or project genuinely unchanged" + + - id: M2 + weight: 1.0 + question: "Are there no rules about deprecated technologies still in the file?" + how_to_check: "Scan for library names — are any of them removed from package.json?" + failing_indicator: "Rules referencing libraries or patterns no longer in use" + passing_indicator: "All rules apply to the current actual state of the codebase" + + - id: M3 + weight: 1.0 + question: "Do all linked files or @imports actually exist?" + how_to_check: "Run canary-check.sh or check each @import manually" + failing_indicator: "Broken @import paths or links to non-existent docs" + passing_indicator: "All references resolve to real files" + + - id: M4 + weight: 1.0 + question: "Have team members other than the original author contributed to or reviewed the file?" + failing_indicator: "Single author, no review, rules reflect one person's preferences" + passing_indicator: "At least one other team member has reviewed or edited" + + - id: M5 + weight: 1.0 + question: "Is the file tracked in git with meaningful commit messages?" + how_to_check: "git log --oneline -- CLAUDE.md" + failing_indicator: "Not tracked, or all commits are 'update CLAUDE.md'" + passing_indicator: "Tracked with descriptive history (e.g., 'context: add zod validation rule')" + +# ── Scoring Guide ───────────────────────────────────────────────────────────── +scoring_guide: + "18-20": "Excellent — your context is production-grade, maintain it quarterly" + "16-17": "Good — minor gaps, address the failing questions this sprint" + "13-15": "Needs work — coverage or quality issues affecting Claude's output" + "10-12": "Significant issues — likely causing frequent corrections or rework" + "0-9": "Critical — CLAUDE.md is not serving its purpose, rebuild from skeleton" diff --git a/examples/context-engineering/profile-template.yaml b/examples/context-engineering/profile-template.yaml new file mode 100644 index 0000000..ca4d565 --- /dev/null +++ b/examples/context-engineering/profile-template.yaml @@ -0,0 +1,82 @@ +# Developer Profile Template +# Customize and save as: .claude/profiles/.yaml +# Run: ts-node assembler.ts --profile .claude/profiles/.yaml +# +# This profile drives context assembly: it selects which shared modules to include, +# sets preferences that can be referenced by modules, and allows per-developer overrides +# without touching the shared module files. +# +# Naming convention: use lowercase, no spaces. Example: alice.yaml, bob-ml.yaml + +profile: + name: "developer-name" # Used in assembled CLAUDE.md header + role: "fullstack" # frontend | backend | fullstack | devops | ml + seniority: "mid" # junior | mid | senior | staff + tools: + primary_lang: "typescript" # typescript | python | rust | go | java | kotlin + frontend: "react" # react | vue | angular | svelte | none + backend: "node" # node | fastapi | actix | gin | spring | rails + database: "postgres" # postgres | mysql | mongodb | redis | sqlite + cloud: "aws" # aws | gcp | azure | none + test_framework: "vitest" # vitest | jest | pytest | go-test | cargo-test + style: + verbosity: "concise" # verbose | concise | minimal + # verbose: include rationale in explanations, add inline comments liberally + # concise: explain when not obvious, comment only complex logic + # minimal: no unsolicited explanation, comments only on public APIs + comment_style: "inline" # none | inline | jsdoc + # none: no comments generated + # inline: short // comments on complex lines + # jsdoc: full JSDoc/docstring blocks on all public functions + test_coverage: "required" # none | optional | required + # none: no tests generated unless explicitly asked + # optional: generate tests on request or for complex logic + # required: always generate tests alongside new functions + +# Modules are markdown files in .claude/modules/ that contain focused rule sets. +# The assembler concatenates them in order to build the final CLAUDE.md. +# Use subdirectories to organize by domain (e.g., frontend/, backend/, shared/). +modules: + include: + # Core — always include these + - shared/core-rules.md # General coding standards + - shared/git-conventions.md # Commit format, branch naming, PR requirements + - shared/security-rules.md # Input validation, secret handling, dependency policy + + # Role-specific — uncomment what applies + # Frontend + # - frontend/react-patterns.md # Component structure, hooks, state management + # - frontend/accessibility.md # WCAG requirements, ARIA patterns + # - frontend/css-conventions.md # CSS modules, utility classes, design tokens + + # Backend + # - backend/api-design.md # REST conventions, error formats, versioning + # - backend/database-patterns.md # Query patterns, migrations, indexing + # - backend/auth-patterns.md # JWT, OAuth, session management + + # DevOps + # - devops/ci-cd.md # Pipeline conventions, deployment gates + # - devops/docker-patterns.md # Dockerfile standards, compose conventions + # - devops/observability.md # Logging format, metric naming, tracing + + # ML + # - ml/model-evaluation.md # Evaluation methodology, bias checks + # - ml/experiment-tracking.md # MLflow/W&B conventions, artifact naming + # - ml/data-pipeline.md # Data validation, transformation patterns + + exclude: + [] + # Explicitly exclude modules from the base set (e.g., if shared/security-rules.md + # has a section that conflicts with your team's approach): + # - shared/security-rules.md + +overrides: + # Per-developer additions — appended after all modules as a "Personal Rules" section. + # Keep these minimal: shared knowledge belongs in shared modules, not personal overrides. + # Good use cases: personal debugging preferences, tooling shortcuts, IDE-specific notes. + custom_rules: + [] + # Examples: + # - "Always run `pnpm typecheck` before declaring a TypeScript task complete" + # - "Use zod for all external input validation, not manual type guards" + # - "When unsure about a regex, use a named capture group and add a comment" diff --git a/examples/context-engineering/rules/knowledge-feeding.md b/examples/context-engineering/rules/knowledge-feeding.md new file mode 100644 index 0000000..015f7d1 --- /dev/null +++ b/examples/context-engineering/rules/knowledge-feeding.md @@ -0,0 +1,93 @@ +# Knowledge Feeding Protocol + +Context engineering is not a one-time setup — it accumulates value over time as Claude learns what works for your project. This file defines when and how to capture that learning back into your `CLAUDE.md`. + +## When to Feed Knowledge + +Run this protocol at the end of any session that: + +- Completed a feature or meaningful code change +- Discovered a new pattern that worked well and should become standard +- Hit a mistake that required correction (especially if the mistake was repeated) +- Made an architectural decision that will affect future work +- Established a preference for a library, tool, or approach + +Skip it for trivial sessions (typo fixes, doc edits, minor config changes). + +## The Knowledge Feed Prompt + +Paste this into Claude at the end of qualifying sessions: + +``` +Before we close this session, run a knowledge feed: + +1. What patterns did we establish that should become permanent rules? +2. What did I correct or redirect that should be a rule to prevent recurrence? +3. Were any architectural decisions made that CLAUDE.md should record? +4. Is there anything in CLAUDE.md that this session proved wrong or outdated? + +Output only high-signal items (3-5 max). Use the knowledge feed format below. +Skip anything obvious or already covered. +``` + +## Knowledge Feed Output Format + +Claude should output discoveries in this structure: + +```markdown +## Knowledge Feed — [YYYY-MM-DD] + +### New Pattern (if applicable) +**What**: [One sentence describing the pattern] +**Why**: [Why this is the right approach for this project] +**Rule to add**: +> [Exact text to paste into CLAUDE.md, ready to copy] + +### Anti-Pattern Found (if applicable) +**What happened**: [What Claude did wrong or what was corrected] +**Why it's wrong here**: [Project-specific reason, not generic best practice] +**Rule to add**: +> Never: [specific behavior to avoid and why] + +### Architecture Decision (if applicable) +**Decision**: [What was decided] +**Rationale**: [Why — especially if it goes against common practice] +**Rule to add**: +> [Exact text to paste into CLAUDE.md] + +### Stale Rule to Remove (if applicable) +**Rule**: [Current rule in CLAUDE.md] +**Why remove**: [What changed that makes this obsolete] +``` + +## Integration Workflow + +After receiving the knowledge feed: + +1. **Review before adding** — not all patterns generalize. Ask: "Would a new team member need to know this, or is it context-specific to this session?" +2. **Copy relevant rules** into the appropriate section of `CLAUDE.md` +3. **Remove any rules** Claude flagged as stale +4. **Commit the update** with a meaningful message: + +```bash +git add CLAUDE.md +git commit -m "context: [short description of what was learned]" + +# Examples: +# context: add zod validation rule after form refactor +# context: remove Redux rule — migrated to Zustand +# context: document payment webhook idempotency pattern +``` + +## Quality Filter + +Before adding any rule to `CLAUDE.md`, check: + +- **Is it specific to this project?** Generic best practices don't belong here — Claude already knows them. +- **Is it actionable?** "Be careful with async code" is useless. "Always check for race conditions in the order state machine" is useful. +- **Is it already covered?** Search for similar rules before adding. Duplicates dilute adherence. +- **Will it still be true in 6 months?** Avoid rules tied to temporary states ("we're migrating to X so don't use Y yet"). + +## Ownership + +Knowledge feeding works best when it's a team habit, not one person's job. Any team member who works with Claude can contribute a knowledge feed. The person who reviews the PR for `CLAUDE.md` changes is responsible for quality filtering. diff --git a/examples/context-engineering/rules/update-loop-retro.md b/examples/context-engineering/rules/update-loop-retro.md new file mode 100644 index 0000000..6a26026 --- /dev/null +++ b/examples/context-engineering/rules/update-loop-retro.md @@ -0,0 +1,108 @@ +# Session Retrospective Template + +A structured prompt to run at the end of Claude Code sessions. The goal is to capture +knowledge while it's fresh and turn it into durable rules — keeping your `CLAUDE.md` +accurate as the project evolves. + +## The Prompt + +Copy this and paste it into Claude at the end of a session: + +``` +Session complete. Before we close, run a quick retrospective: + +1. What patterns did we establish that should be permanent rules in CLAUDE.md? +2. What did I correct that Claude got wrong? Should a rule prevent that? +3. What worked well that we should replicate in future sessions? +4. Were any architectural decisions made that CLAUDE.md should record? +5. Is there anything currently in CLAUDE.md that this session proved wrong or outdated? + +Output a knowledge feed — 3 to 5 bullets max, high-signal items only. +Skip anything obvious, generic, or already in CLAUDE.md. +Format each item as an actionable rule ready to copy in. +``` + +## When to Run It + +| Trigger | Run retro? | +|---------|-----------| +| Feature or major refactor completed | Yes | +| Debugging session that uncovered a systemic gap | Yes | +| Architectural decision made | Yes | +| Onboarding session where someone flagged missing context | Yes | +| Monthly, even if nothing major happened | Yes — catches accumulation | +| Trivial session (typo fix, doc edit) | No | + +Monthly is the minimum cadence even for quiet projects. Small drifts accumulate silently. + +## What Good Output Looks Like + +Claude should return something like this (not verbatim — but this level of specificity): + +``` +Knowledge Feed — 2025-09-15 + +1. Pattern established: All database queries go through the repository layer, never called + directly from route handlers. Rule to add: "Never call Prisma directly from route + handlers — use the repository functions in src/db/." + +2. Correction: I suggested lodash for array manipulation. You redirected to native array + methods. Rule to add: "Don't import lodash — use native JS array methods. The bundle + cost isn't worth it for our use case." + +3. Architecture decision: We decided to keep auth logic in middleware, not in individual + route handlers. Rule to add: "Auth checks belong in src/middleware/auth.ts — not in + route handlers. If a route needs special auth logic, extend the middleware." + +4. Stale rule: CLAUDE.md still references the old Express v4 error handler signature. + We're on v5. Remove: "Express error handlers take 4 arguments (err, req, res, next)." + Update to: "Express v5 error handlers: async errors propagate automatically — no need + to call next(err)." +``` + +## After the Retro + +### Review the output + +Not everything Claude surfaces belongs in `CLAUDE.md`. Ask: + +- Is this specific to our project, or generic advice Claude already knows? +- Is it actionable? Would a new Claude session make the same mistake without this rule? +- Is it already covered? Search before adding — duplicates reduce adherence. + +### Update CLAUDE.md + +Add new rules to the most relevant section. Remove any stale rules Claude flagged. + +### Commit with a traceable message + +```bash +git add CLAUDE.md +git commit -m "context: [what changed and why]" +``` + +Meaningful commit messages create a traceable history of how your AI context evolved. Useful +for debugging: "Claude started doing X wrong after we made change Y" becomes diagnosable +from git log. + +Examples of good commit messages: + +``` +context: add lodash ban — use native array methods +context: clarify auth middleware pattern after refactor +context: remove Express v4 error handler rule — now on v5 +context: document payment webhook idempotency requirement +context: add Prisma-direct query ban after code review +``` + +## Team Usage + +When multiple people work with Claude on the same project, retros become especially valuable. +Each developer may get different corrections — different gaps in `CLAUDE.md` surface from +different angles. Consider: + +- Running a retro at the end of any PR that involved significant Claude-assisted work +- Including `CLAUDE.md` in PR reviews as a standing agenda item +- Doing a quarterly joint retro with the whole team to review accumulated changes + +The `CLAUDE.md` file is a shared asset. Its quality reflects how well the team maintains it. diff --git a/examples/context-engineering/skeleton-template.md b/examples/context-engineering/skeleton-template.md new file mode 100644 index 0000000..c7efe8a --- /dev/null +++ b/examples/context-engineering/skeleton-template.md @@ -0,0 +1,288 @@ +# CLAUDE.md — [Project Name] + + + +## Project Overview + + + +[PROJECT DESCRIPTION] + +## Architecture + + + +### Stack + +| Layer | Technology | Version | +|-------|-----------|---------| +| Language | TypeScript | 5.x | +| Runtime | Node.js | 20.x | +| Framework | [e.g., Express, Fastify, NestJS] | x.x | +| Database | [e.g., PostgreSQL] | x.x | +| ORM / Query Builder | [e.g., Prisma, Drizzle, Knex] | x.x | +| Cache | [e.g., Redis, none] | - | +| Message Queue | [e.g., BullMQ, SQS, none] | - | +| Frontend | [e.g., Next.js, none] | x.x | +| Testing | [e.g., Vitest, Jest] | x.x | +| CI/CD | [e.g., GitHub Actions] | - | + +### Folder Structure + +``` +src/ + [describe key directories and what belongs in each] + [example: api/ — route handlers only, no business logic] + [example: services/ — business logic, called by handlers] + [example: db/ — Prisma schema, migrations, query functions] +``` + +### Key Architectural Decisions + + + +- [DECISION 1] +- [DECISION 2] + +## Code Standards + + + +### TypeScript + +- Strict mode is enabled (`"strict": true` in tsconfig). Never use `any` — use `unknown` and narrow. +- All public function signatures must have explicit return types. +- Use `type` for unions and intersections, `interface` for object shapes that may be extended. +- [ADD YOUR RULES] + +### Naming + +- Files: `kebab-case.ts` (e.g., `user-service.ts`, `create-order.test.ts`) +- Classes: `PascalCase` +- Functions and variables: `camelCase` +- Constants: `SCREAMING_SNAKE_CASE` +- [ADD ANY EXCEPTIONS] + +### Error Handling + + + +- [ERROR HANDLING RULES] + +### Comments + + + +- [COMMENT RULES] + +## Development Workflow + +### Git Conventions + +- Branch naming: `[type]/[short-description]` — e.g., `feat/add-refund-flow`, `fix/order-status-race` +- Commit format: [Conventional Commits](https://www.conventionalcommits.org/) + - `feat:` new feature + - `fix:` bug fix + - `chore:` maintenance, dependency updates + - `docs:` documentation only + - `test:` tests only + - `refactor:` no behavior change +- Commits should be atomic — one logical change per commit +- [ADD ANY EXCEPTIONS OR ADDITIONAL TYPES] + +### PR Requirements + + + +- [PR RULES] + +### Local Setup + +```bash +# Install dependencies +[INSTALL COMMAND] + +# Set up environment +cp .env.example .env +# Edit .env with your local values + +# Run database migrations +[MIGRATION COMMAND] + +# Start development server +[DEV COMMAND] +``` + +## Testing + + + +### Framework and Location + +- Framework: [e.g., Vitest] +- Test files: colocated with source (`foo.ts` → `foo.test.ts`) OR in `__tests__/` [choose one] +- Run tests: `[TEST COMMAND]` +- Run with coverage: `[COVERAGE COMMAND]` + +### What Requires Tests + +- All service layer functions (unit tests with mocked dependencies) +- All API routes (integration tests using supertest or equivalent) +- All utility functions that contain branching logic +- **Not required**: pure pass-through functions, simple getters/setters, Prisma model definitions + +### Test Structure + +```typescript +// Follow this pattern: +describe('[unit under test]', () => { + describe('[method or scenario]', () => { + it('[expected behavior in plain English]', async () => { + // Arrange + // Act + // Assert + }) + }) +}) +``` + +### Mocking + +- Mock at the boundary: mock external services, never internal modules +- [ADD YOUR MOCKING CONVENTIONS — e.g., "Use vi.mock() at file level, not inside tests"] + +## Deployment + +### Environments + +| Environment | Branch | URL | Notes | +|------------|--------|-----|-------| +| Local | any | localhost:[PORT] | | +| Staging | `main` | [STAGING URL] | Auto-deploys | +| Production | [TAG/BRANCH] | [PROD URL] | Manual trigger | + +### Deploy + +```bash +# Staging (auto on merge to main — no manual step needed) + +# Production +[DEPLOY COMMAND OR PROCESS] +``` + +### Post-Deploy Checks + + + +- [POST-DEPLOY CHECKS] + +## What Claude Should NOT Do + + + +### Technologies Not in Use + +- Do NOT suggest GraphQL — REST is the architectural decision for this project +- Do NOT use [LIBRARY NAME] — replaced by [ALTERNATIVE] in [VERSION/DATE] +- [ADD YOUR BANNED TECHNOLOGIES] + +### Patterns to Avoid + + + +- [ANTI-PATTERN 1] +- [ANTI-PATTERN 2] +- [ANTI-PATTERN 3] + +### Known Problem Areas + + + +- [KNOWN PROBLEM AREA 1] +- [KNOWN PROBLEM AREA 2] diff --git a/guide/README.md b/guide/README.md index a46efb0..021f954 100644 --- a/guide/README.md +++ b/guide/README.md @@ -21,6 +21,7 @@ Core documentation for mastering Claude Code, organized by topic. | [core/visual-reference.md](./core/visual-reference.md) | Visual cheatsheet — ASCII diagrams for key concepts | 5 min | | [core/claude-code-releases.md](./core/claude-code-releases.md) | Official release history (condensed) | 10 min | | [core/known-issues.md](./core/known-issues.md) | **Critical bugs tracker**: security issues, token consumption, verified community reports | 15 min | +| [core/context-engineering.md](./core/context-engineering.md) | **Context Engineering**: token budget, modular architecture, team assembly, ACE pipeline, quality measurement | 25 min | | [diagrams/](./diagrams/) | **Visual Diagrams Series**: 41 Mermaid interactive diagrams for model selection, agent lifecycle, security, multi-agent patterns | 15 min | --- diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md index cce7e92..2bda7b2 100644 --- a/guide/cheatsheet.md +++ b/guide/cheatsheet.md @@ -12,7 +12,7 @@ tags: [cheatsheet, reference] **Written with**: Claude (Anthropic) -**Version**: 3.33.1 | **Last Updated**: February 2026 +**Version**: 3.34.0 | **Last Updated**: February 2026 --- @@ -638,4 +638,4 @@ Speed: `rg` (~20ms) → Serena (~100ms) → ast-grep (~200ms) → grepai (~500ms **Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude -*Last updated: February 2026 | Version 3.33.1* +*Last updated: February 2026 | Version 3.34.0* diff --git a/guide/core/context-engineering.md b/guide/core/context-engineering.md new file mode 100644 index 0000000..0eb7908 --- /dev/null +++ b/guide/core/context-engineering.md @@ -0,0 +1,1188 @@ +--- +title: "Context Engineering" +description: "Comprehensive guide to filling Claude's context window with the right information at the right time — configuration hierarchy, budget management, modular architecture, team assembly, and quality measurement" +tags: [context, configuration, architecture, team, advanced] +--- + +# Context Engineering + +> **Confidence**: Tier 1 — Based on official documentation, measured production data, and community validation. +> +> **Last updated**: March 2026 + +"Context engineering is the art of filling the context window with the right information at the right time." — Andrej Karpathy + +This guide covers everything from the token math behind context budgets to building modular, team-scale configuration systems. It is a companion to the broader configuration sections in the ultimate guide — where those sections show individual techniques, this document shows how to compose them into a coherent system. + +--- + +## Table of Contents + +1. [What is Context Engineering](#1-what-is-context-engineering) +2. [The Context Budget](#2-the-context-budget) +3. [Configuration Hierarchy](#3-configuration-hierarchy) +4. [Modular Architecture](#4-modular-architecture) +5. [Team Assembly](#5-team-assembly) +6. [Context Lifecycle](#6-context-lifecycle) +7. [Quality Measurement](#7-quality-measurement) +8. [Context Reduction Techniques](#8-context-reduction-techniques) + +--- + +## 1. What is Context Engineering + +### The Definition + +Andrej Karpathy coined the phrase: **"Context engineering is the art of filling the context window with the right information at the right time."** + +That single sentence contains three non-obvious requirements: + +- **Filling**: the context window should be populated deliberately, not accidentally. Leaving it mostly empty wastes the model's capacity; leaving it chaotically full wastes your tokens and degrades output quality. +- **Right information**: not all information is equal. Architecture decisions are more valuable than linting preferences. Negative constraints ("never return raw SQL errors to the client") are more actionable than aspirational goals ("write clean code"). +- **Right time**: path-scoped rules for backend code have no value when editing a frontend component. Loading everything always is the lazy approach that degrades adherence. + +### Prompt Engineering vs. Context Engineering + +These terms are often conflated. The distinction matters: + +| Dimension | Prompt Engineering | Context Engineering | +|-----------|-------------------|---------------------| +| Scope | One request | Entire session or system | +| Duration | Single interaction | Persistent across interactions | +| Effort | Per-request crafting | Upfront system design | +| Scale | Individual | Team-wide or organization-wide | +| Artifact | A prompt string | A configuration system | + +**Prompt engineering** is about crafting the right question for one task. **Context engineering** is the system that ensures Claude has the right background knowledge before any task begins. You can have excellent prompts on top of poor context engineering and still get mediocre results — because the model lacks the structural understanding of your project, conventions, and constraints. + +A practical analogy: prompt engineering is writing a good email to a contractor. Context engineering is the onboarding process, code style guide, architecture documentation, and team norms that ensure the contractor understands the project before reading a single email. + +### Why It Matters + +LLMs are context-window computers. The quality of output is bounded by the quality of input. This is not a soft claim — it has a hard technical basis: + +1. The model has no persistent memory between sessions (without explicit tooling). Every session starts from zero unless context is deliberately provided. +2. The model cannot infer unstated conventions. If you want TypeScript interfaces instead of `type` aliases, that must be stated. If you want errors logged before being thrown, that must be stated. +3. Models are sensitive to instruction placement and framing. An instruction buried in line 400 of a 500-line CLAUDE.md is less likely to be followed than one in the first 50 lines. + +Teams that invest in context engineering consistently report fewer revision cycles, better adherence to conventions, and more predictable outputs. The investment is front-loaded (building the system), but the returns compound across every interaction. + +### The Three Layers + +Context engineering in Claude Code operates across three distinct layers: + +| Layer | Mechanism | Scope | When Loaded | +|-------|-----------|-------|-------------| +| **Global config** | `~/.claude/CLAUDE.md` | All projects | Always | +| **Project config** | `./CLAUDE.md` + path-scoped modules | Current project | Per session | +| **Session** | Inline instructions, `/add`, flags | Current session only | Runtime | + +Each layer has different tradeoffs. Global config is always-on but cannot reference project-specific details. Session instructions are flexible but ephemeral. Project config is the workhorse: structured, versioned, reviewable. + +Good context engineering means putting each piece of information in the right layer — not cramming everything into one file, and not leaving critical knowledge in the session layer where it evaporates after every conversation. + +--- + +## 2. The Context Budget + +### Token Math + +A concrete baseline for a mid-size project: + +| Source | Typical Token Range | +|--------|---------------------| +| Global CLAUDE.md | 1,000 – 3,000 tokens | +| Project CLAUDE.md (root) | 2,000 – 8,000 tokens | +| Path-scoped modules (all active) | 1,000 – 5,000 tokens | +| Imported skills / commands | 500 – 3,000 tokens | +| **Total always-on context** | **~5,000 – 20,000 tokens** | + +Claude Sonnet 4.6 has a 200K token context window. That means even a large always-on configuration budget (20K tokens) occupies about 10% of the window — leaving 180K tokens for actual work: code files, conversation history, tool outputs. + +The practical rule: **always-on context should stay below 5% of the context window.** Beyond that, you are displacing actual task content, which matters more per token than standing instructions. + +### The 150-Instruction Ceiling + +Empirical observation from teams running large CLAUDE.md files: beyond approximately 150 distinct rules, models begin selectively ignoring some of them. This is not a hard cutoff — it depends on rule complexity, overlap, and placement — but it is a reliable signal that more rules does not equal better adherence. + +The mechanism is attention diffusion: when a prompt contains hundreds of potentially relevant constraints, the model's attention is split across them. High-salience rules (recent, strongly worded, placed early) crowd out lower-salience ones. + +HumanLayer's production data shows teams with structured context — fewer, more specific rules, organized hierarchically — see 15-25% better adherence than teams with undifferentiated long rule lists. + +Implication: **rule quality beats rule quantity.** Twenty specific, actionable rules outperform 200 generic aspirational ones. + +### Adherence Degradation by File Size + +``` +Lines in CLAUDE.md Adherence (estimated) +───────────────── ───────────────────── +1 – 100 ~95% +100 – 200 ~88% +200 – 400 ~75% +400 – 600 ~60% +600+ ~45% and falling +``` + +These are estimated baselines, not guarantees. Path-scoping and modular architecture can maintain higher adherence at larger total rule counts by ensuring that only relevant rules are in context at any given time. + +### Signs of Context Overload + +When always-on context becomes too large or too noisy, you see predictable failure modes: + +- **Rule silencing**: Claude follows 80% of conventions consistently but ignores specific rules that should apply. +- **Contradictory behavior**: Claude applies a rule in some files but not others, or applies contradictory rules depending on phrasing. +- **Slow first responses**: The model spends more time processing a large context before generating output (observable in longer latency for simple tasks). +- **Generic outputs**: Instead of applying project-specific patterns, Claude falls back to generic best practices — a sign that project context is not being retained. + +When you see these patterns, the diagnostic is: run a context audit (see Section 7), not more instructions. + +### Path-Scoping and Budget Efficiency + +Path-scoping is the most effective single technique for reducing always-on context. Instead of loading all rules for all parts of the codebase, you load only the rules relevant to the files currently in context. + +A typical project without path-scoping: + +``` +Always-on: root CLAUDE.md with backend + frontend + database + API rules = 8,000 tokens +``` + +The same project with path-scoping: + +``` +Always-on: root CLAUDE.md with shared rules = 2,000 tokens +Active when in src/api/: api module = +1,500 tokens +Active when in src/components/: frontend module = +1,200 tokens +Active when in prisma/: database module = +800 tokens +``` + +Result: 40-50% reduction in always-on context, with no loss of coverage. Each subsystem gets its full rule set, but only when working in that subsystem. + +--- + +## 3. Configuration Hierarchy + +### The Three-Layer Stack + +``` +┌──────────────────────────────────────────────┐ +│ Global (~/.claude/CLAUDE.md) │ +│ Identity, tone, universal tools, cross- │ +│ project conventions │ +├──────────────────────────────────────────────┤ +│ Project (./CLAUDE.md + path modules) │ +│ Architecture decisions, stack conventions, │ +│ team rules, deployment procedures │ +├──────────────────────────────────────────────┤ +│ Session (inline instructions, flags) │ +│ Ad-hoc overrides, experiment constraints, │ +│ one-off task parameters │ +└──────────────────────────────────────────────┘ +``` + +Later layers override earlier ones. A session instruction can override a project rule; a project rule can override a global default. This gives you escape hatches without requiring permanent changes to shared configuration. + +### Global Configuration + +**Location**: `~/.claude/CLAUDE.md` + +**What belongs here**: +- Identity and communication style preferences +- Universal tool preferences (RTK, preferred CLI tools) +- Cross-project coding conventions (commit message format, PR style) +- Security constraints that apply everywhere +- Tone and output format defaults + +**What does not belong here**: +- Project-specific architecture decisions +- Stack-specific rules (React hooks, Prisma patterns) +- Deployment or environment specifics +- Anything that changes per project + +**Size target**: Keep global configuration under 200 lines. This is your always-on overhead for every session in every project. Bloating it hurts all projects equally. + +```markdown +# Example: Minimal effective global CLAUDE.md + +## Communication +- Respond in the same language the user writes in +- Prefer direct answers over preamble +- No em dashes in written output + +## Git +- Commit messages: imperative mood, <72 chars subject line +- Never commit without being asked + +## Code Style +- Prefer explicit error handling over silent failure +- Add TODO comments only when referencing a tracked issue +``` + +### Project Configuration + +**Location**: `./CLAUDE.md` (project root) + +**What belongs here**: +- Technology stack and versions in use +- Architecture decisions and their rationale +- Team conventions specific to this codebase +- File organization patterns +- Testing requirements and coverage targets +- Security constraints specific to this project +- Path-scope imports for subsystem modules + +**Structure pattern**: + +```markdown +# Project: [Name] + +## Stack +- Language: TypeScript 5.3 +- Framework: Next.js 14 (App Router) +- Database: PostgreSQL 16 via Prisma +- Testing: Vitest + React Testing Library + +## Architecture +- Server Components by default; use `"use client"` only when interactivity requires it +- API routes in /app/api; no business logic in route handlers +- Business logic in /lib/services; each service is a plain function module + +## Conventions +- File naming: kebab-case for files, PascalCase for React components +- Error handling: wrap service calls in Result pattern (see lib/result.ts) +- Never expose raw database IDs in API responses; use UUIDs + +## Path-Scoped Modules +@src/api/CLAUDE-api.md +@src/components/CLAUDE-components.md +@prisma/CLAUDE-db.md +``` + +### Session Configuration + +**Mechanism**: Inline instructions, `/add-dir`, or system prompt flags for the current session. + +**What belongs here**: +- One-off task constraints ("For this refactor, do not change the public API surface") +- Experiment parameters ("Use the new error format I'm testing in this file") +- Debug constraints ("Log every tool call for this session") +- Temporary overrides of project conventions + +Session instructions are not persisted. They evaporate when the session ends. Any instruction that you find yourself repeating across sessions belongs in the project config, not the session layer. + +### Decision Tree: Where Does This Rule Go? + +``` +Is this rule relevant to every project I work on? +├── Yes → Global CLAUDE.md +└── No ↓ + +Is this rule relevant to specific files or subsystems? +├── Yes → Path-scoped module (e.g., src/api/CLAUDE-api.md) +└── No ↓ + +Is this rule relevant to the whole project? +├── Yes → Project CLAUDE.md (root) +└── No ↓ + +Does this rule apply only to the current task or session? +├── Yes → Inline session instruction +└── No → Revisit: is it really a rule, or just a one-time preference? +``` + +### Import Chain and Override Semantics + +The import chain flows: `global → project root → path-scoped modules → session`. + +When conflicts exist: +- More specific overrides less specific (path-scoped beats root, root beats global) +- Later-declared beats earlier-declared at the same level +- Session instructions override all persistent config + +**Practical example**: Your global config says "use two-space indentation." Your project config says "use four-space indentation for Python." Your session says "match the existing file style." The session instruction wins for this session, with four-space default for Python files, two-space for everything else. + +Document your overrides explicitly. An undocumented override that contradicts a parent rule creates confusion during audits. + +--- + +## 4. Modular Architecture + +### The Problem with Monolithic Config + +A 600-line CLAUDE.md with no structure is the most common failure mode in production contexts. Symptoms: + +1. Rules from different domains mix together — a React component convention sits next to a database migration rule +2. Claude reads all 600 lines but the attention budget means rules on page 5 get less weight than rules on page 1 +3. New team members can't find relevant rules quickly +4. Updates require scanning the entire file to find related rules before editing +5. Adherence degrades progressively as the file grows + +The fix is architectural: decompose the monolith into focused modules, then use path-scoping to load each module only when relevant. + +### Path-Scoping Pattern + +**Mechanism**: Claude Code supports `@path/to/file.md` imports in CLAUDE.md. When a path-scoped import is active, rules from that module are added to context only when files under the specified path are in scope. + +**File structure**: + +``` +project/ +├── CLAUDE.md # Root config, shared rules + @imports +├── src/ +│ ├── api/ +│ │ └── CLAUDE-api.md # API-specific rules +│ ├── components/ +│ │ └── CLAUDE-components.md # React/UI-specific rules +│ └── lib/ +│ └── CLAUDE-lib.md # Utility/shared library rules +├── prisma/ +│ └── CLAUDE-db.md # Database and migration rules +└── tests/ + └── CLAUDE-tests.md # Testing conventions +``` + +**Root CLAUDE.md with imports**: + +```markdown +# Project Config + +## Shared Rules +[...shared rules here...] + +## Subsystem Modules +@src/api/CLAUDE-api.md +@src/components/CLAUDE-components.md +@src/lib/CLAUDE-lib.md +@prisma/CLAUDE-db.md +@tests/CLAUDE-tests.md +``` + +**Example path-scoped module** (`src/api/CLAUDE-api.md`): + +```markdown +# API Rules + +- Route handlers in /app/api only; no business logic inline +- All endpoints must validate input with Zod before processing +- Error responses use the standard format: { error: string, code: string } +- Never log request bodies that may contain PII; log IDs only +- Rate limiting headers must be present on all public endpoints +- Authentication: verify JWT in middleware, not in individual handlers +``` + +This module's 6 rules are in context only when working in `src/api/`. They do not consume context budget when working in `src/components/`. + +### Skills vs. Rules + +This distinction is underused and matters: + +| Dimension | Rules | Skills | +|-----------|-------|--------| +| Nature | Constraints, standards, conventions | Capabilities, procedures, workflows | +| When active | Always enforced | Invoked on demand | +| Example | "Never use `any` in TypeScript" | "How to add a new API endpoint" | +| Location | CLAUDE.md | `.claude/skills/` | +| Token cost | Always-on | Loaded only when invoked | + +**Rules** define what Claude should and should not do by default. They set the boundaries of acceptable output. + +**Skills** define how to do complex multi-step tasks that require specific knowledge of your project's patterns. They are loaded when Claude needs to perform a specific type of task, not always. + +**Practical example**: A rule says "API endpoints must have Zod validation." A skill says "Here is the step-by-step pattern for creating a new API endpoint in this project, including the Zod schema pattern, the error handling wrapper, the auth middleware hook, and the test file structure." + +Putting the endpoint creation procedure in a rule would mean loading 40 lines of procedural instructions for every session, even when you're not creating endpoints. Putting it in a skill means loading those 40 lines only when creating an endpoint. + +**Rule**: `Never expose raw database IDs in API responses.` +**Skill**: `How to generate and use UUID-based public identifiers for entities.` + +### Progressive Disclosure + +The principle: don't load everything upfront. Load what is needed for the task at hand. + +**Core config (always-on)**: +- Architecture decisions and their rationale +- Coding standards and naming conventions +- Security constraints +- Tool preferences + +**Contextual modules (loaded per task)**: +- Deployment procedures (load when deploying) +- API patterns (load when working in API layer) +- Test templates (load when writing tests) +- Database migration procedures (load when touching schema) + +**Implementation pattern using skills**: + +``` +.claude/ +├── skills/ +│ ├── deploy-production.md # Loaded when: "deploy this" +│ ├── add-api-endpoint.md # Loaded when: "add endpoint for X" +│ ├── write-migration.md # Loaded when: "add DB column" +│ └── create-component.md # Loaded when: "create component for X" +``` + +Each skill file contains the step-by-step procedure with project-specific patterns. Claude loads it when the task type is detected, not proactively. + +### Anti-Pattern: The Monolithic CLAUDE.md + +**What it looks like**: + +```markdown +# CLAUDE.md (600 lines) + +## Rules +1. Use TypeScript +2. No any types +3. Run tests before committing +4. API endpoints need auth +5. Use Prisma for DB queries +6. React components in PascalCase +7. Deploy with ./scripts/deploy.sh +8. Check OWASP Top 10 before shipping +[...492 more rules...] +``` + +**Why it fails**: + +- Rules 1-20 get ~95% attention weight; rules 500+ get ~30% +- Frontend dev reads backend DB rules they don't need and vice versa +- No logical grouping means finding relevant rules requires reading everything +- Adding a new rule requires checking the entire file for conflicts +- Adherence degrades continuously as the file grows + +**The fix**: + +1. Extract rules by domain into path-scoped modules +2. Keep the root CLAUDE.md to shared rules + import declarations +3. Move procedural knowledge to skills +4. Target root CLAUDE.md at under 150 lines after extraction + +--- + +## 5. Team Assembly + +### The N × M × P Problem + +At team scale, context engineering faces a combinatorial challenge: + +- **N developers**: different roles, tools, communication preferences +- **M projects**: different stacks, conventions, deployment targets +- **P configurations**: each developer × each project needs a configuration + +Maintaining N × M individual CLAUDE.md files manually is not sustainable. When a shared convention changes, you update N × M files. When a new project is created, you build from scratch. When a developer changes roles, you rebuild their configurations. + +The solution is **profile-based assembly**: a single shared base of modules, with individual profiles that specify which modules to include and what personal preferences to overlay. + +N × M × P becomes N profiles × 1 shared module base — manageable. + +### Profile YAML Structure + +Each team member has a profile YAML that declaratively specifies their configuration: + +```yaml +# profiles/alice.yaml + +profile: + name: "Alice" + role: "frontend" + tools: + - typescript + - react + - tailwind + conventions: + - atomic-design + - accessibility-first + communication: + language: "en" + verbosity: "concise" + +modules: + include: + - shared/core-rules.md + - shared/git-conventions.md + - shared/security-baseline.md + - frontend/react-patterns.md + - frontend/tailwind-conventions.md + - frontend/testing-rtl.md + - frontend/accessibility-checklist.md + exclude: + - backend/database-rules.md + - backend/api-design.md + - devops/deployment-procedures.md + +overrides: + - "Prefer named exports over default exports" + - "Use Radix UI primitives before writing custom components" +``` + +```yaml +# profiles/bob.yaml + +profile: + name: "Bob" + role: "backend" + tools: + - typescript + - nodejs + - postgresql + - prisma + communication: + language: "en" + verbosity: "detailed" + +modules: + include: + - shared/core-rules.md + - shared/git-conventions.md + - shared/security-baseline.md + - backend/api-design.md + - backend/database-rules.md + - backend/error-handling.md + - backend/performance-patterns.md + exclude: + - frontend/react-patterns.md + - frontend/tailwind-conventions.md + +overrides: + - "Use structured logging (pino) with request context IDs" + - "Always measure before optimizing; profile first" +``` + +### Module Library Structure + +The shared module library lives in the repository and is version-controlled: + +``` +.claude/ +├── modules/ +│ ├── shared/ +│ │ ├── core-rules.md # Universal team standards +│ │ ├── git-conventions.md # Commit and PR conventions +│ │ ├── security-baseline.md # Non-negotiable security rules +│ │ └── testing-standards.md # Coverage and test quality rules +│ ├── frontend/ +│ │ ├── react-patterns.md +│ │ ├── tailwind-conventions.md +│ │ ├── testing-rtl.md +│ │ └── accessibility-checklist.md +│ ├── backend/ +│ │ ├── api-design.md +│ │ ├── database-rules.md +│ │ ├── error-handling.md +│ │ └── performance-patterns.md +│ └── devops/ +│ ├── deployment-procedures.md +│ ├── monitoring-conventions.md +│ └── infrastructure-rules.md +├── profiles/ +│ ├── alice.yaml +│ ├── bob.yaml +│ └── carol.yaml +└── scripts/ + └── assemble-context.sh +``` + +### Assembly Script + +The assembly script reads a profile and concatenates the specified modules into a CLAUDE.md: + +```bash +#!/usr/bin/env bash +# scripts/assemble-context.sh + +set -euo pipefail + +PROFILE="${1:-}" +CHECK_MODE="${2:-}" + +if [[ -z "$PROFILE" ]]; then + echo "Usage: ./assemble-context.sh [--check]" + exit 1 +fi + +PROFILE_FILE=".claude/profiles/${PROFILE}.yaml" +OUTPUT_FILE="CLAUDE.md" +MODULES_DIR=".claude/modules" + +if [[ ! -f "$PROFILE_FILE" ]]; then + echo "Profile not found: $PROFILE_FILE" + exit 1 +fi + +# Parse profile with yq or python +MODULES=$(python3 -c " +import yaml +with open('$PROFILE_FILE') as f: + profile = yaml.safe_load(f) +for m in profile['modules']['include']: + print(m) +") + +# Assemble output +ASSEMBLED=$(mktemp) + +echo "# Claude Code Configuration" > "$ASSEMBLED" +echo "# Generated from profile: $PROFILE" >> "$ASSEMBLED" +echo "# Generated at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$ASSEMBLED" +echo "" >> "$ASSEMBLED" + +while IFS= read -r module; do + MODULE_PATH="${MODULES_DIR}/${module}" + if [[ -f "$MODULE_PATH" ]]; then + echo "## From: ${module}" >> "$ASSEMBLED" + cat "$MODULE_PATH" >> "$ASSEMBLED" + echo "" >> "$ASSEMBLED" + else + echo "WARNING: module not found: $MODULE_PATH" >&2 + fi +done <<< "$MODULES" + +# Append personal overrides +python3 -c " +import yaml +with open('$PROFILE_FILE') as f: + profile = yaml.safe_load(f) +overrides = profile.get('overrides', []) +if overrides: + print('## Personal Overrides') + for o in overrides: + print(f'- {o}') +" >> "$ASSEMBLED" + +if [[ "$CHECK_MODE" == "--check" ]]; then + if diff -q "$OUTPUT_FILE" "$ASSEMBLED" > /dev/null 2>&1; then + echo "OK: CLAUDE.md matches profile $PROFILE" + rm "$ASSEMBLED" + exit 0 + else + echo "DRIFT: CLAUDE.md does not match profile $PROFILE" + diff "$OUTPUT_FILE" "$ASSEMBLED" + rm "$ASSEMBLED" + exit 1 + fi +fi + +mv "$ASSEMBLED" "$OUTPUT_FILE" +echo "Assembled CLAUDE.md from profile: $PROFILE" +``` + +**Usage**: + +```bash +# Generate CLAUDE.md from a profile +./scripts/assemble-context.sh alice + +# Check for drift (used in CI) +./scripts/assemble-context.sh alice --check +``` + +### CI Drift Detection + +Team members regenerate their CLAUDE.md from profiles, but base modules evolve over time. Without drift detection, a developer may be running an outdated configuration — one that predates a security rule addition or a convention update. + +A GitHub Actions job detects this: + +```yaml +# .github/workflows/context-drift.yml + +name: Context Drift Detection + +on: + schedule: + - cron: '0 9 * * 1' # Weekly, Monday 9am UTC + push: + paths: + - '.claude/modules/**' + +jobs: + check-drift: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install dependencies + run: pip install pyyaml + + - name: Check all profiles for drift + run: | + DRIFT=0 + for profile_file in .claude/profiles/*.yaml; do + profile=$(basename "$profile_file" .yaml) + echo "Checking profile: $profile" + if ! ./scripts/assemble-context.sh "$profile" --check; then + echo "DRIFT detected in profile: $profile" + DRIFT=1 + fi + done + exit $DRIFT + + - name: Notify on drift + if: failure() + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title: 'Context drift detected — CLAUDE.md needs regeneration', + body: 'One or more team profiles are out of sync with the current module library. Run `./scripts/assemble-context.sh ` to regenerate.', + labels: ['context-engineering'] + }) +``` + +### Onboarding with Profiles + +For new team members, the onboarding sequence becomes: + +```bash +# 1. Copy a starter profile appropriate for your role +cp .claude/profiles/template-frontend.yaml .claude/profiles/yourname.yaml + +# 2. Edit the profile for your preferences +vim .claude/profiles/yourname.yaml + +# 3. Generate your CLAUDE.md +./scripts/assemble-context.sh yourname + +# 4. Verify the output +cat CLAUDE.md + +# 5. Commit your profile (not the generated CLAUDE.md — it's gitignored) +git add .claude/profiles/yourname.yaml +git commit -m "chore: add context profile for yourname" +``` + +Add `CLAUDE.md` to `.gitignore` at the project root. The profile YAML is the source of truth, not the generated file. + +--- + +## 6. Context Lifecycle + +### Instruction Debt + +Rules accumulate. They are rarely removed. This is instruction debt: the gradual accumulation of rules that are outdated, redundant, or contradictory — each still consuming context budget. + +Signs of instruction debt: + +- A rule refers to a library you stopped using six months ago +- Two rules say opposite things about the same pattern +- A rule covers an edge case that only applied during a specific migration +- The same constraint is stated three times in different sections +- Developers comment out or ignore specific rules because they conflict with current practice + +Instruction debt has compounding costs: each conflicting or irrelevant rule displaces a useful one, and models behave unpredictably when rules conflict. + +**Quarterly audit rhythm**: Schedule a context audit every quarter (or after major project milestones). The audit prompt: + +``` +Review every rule in CLAUDE.md for: +1. Relevance: Does this still apply to the current stack and patterns? +2. Specificity: Is this actionable, or is it too vague to enforce? +3. Conflicts: Does this contradict another rule? +4. Coverage: Is this already covered by a more general rule? + +For each rule, classify as: KEEP | UPDATE | ARCHIVE | DELETE +``` + +Run this as an actual Claude session, feeding the current CLAUDE.md and asking for a structured audit. + +### The Update Loop + +The most common mistake after a bad Claude output is to fix the output manually and move on. This is a wasted learning opportunity. + +**Bad loop**: +``` +Claude generates wrong pattern +→ Developer manually fixes it +→ Next session: Claude generates wrong pattern again +→ Developer manually fixes it again +→ Repeat indefinitely +``` + +**Good loop**: +``` +Claude generates wrong pattern +→ Developer identifies the root cause (missing rule? vague rule? conflicting rules?) +→ Developer updates CLAUDE.md with a corrected or new rule +→ Next session: Claude generates correct pattern +→ Rule stays in config permanently +``` + +The update loop is how your configuration system learns from experience. Each bad output is a signal that something is missing or broken in your context engineering. Treat it as a bug report against CLAUDE.md, not just a one-off failure. + +**Practical format for rule updates**: + +When adding a rule from a failure, include the rationale inline: + +```markdown +- Use the `Result` type for service functions, not try/catch + (Rationale: try/catch at service level hides error types from callers; + Result forces explicit error handling at the call site) +``` + +The rationale serves two purposes: it helps future auditors understand why the rule exists, and it gives Claude better context for applying the rule correctly. + +### Knowledge Feeding After Sprints + +At the end of each sprint or release cycle, run a brief knowledge feeding session: + +1. **New patterns**: "We standardized on X approach for Y type of problem in this sprint. Add this to CLAUDE.md." +2. **Anti-patterns discovered**: "We tried X and it caused Y. Add a rule to avoid it." +3. **Architecture decisions**: "We decided to use X over Y because Z. Document this so Claude doesn't suggest Y." +4. **Deprecated patterns**: "We're moving away from X. Add a rule to use Y instead and flag existing X usages." + +This keeps the context system current without requiring large periodic overhauls. + +### The ACE Pipeline + +For teams that run Claude Code in automated or semi-automated workflows, the ACE pipeline provides a structured execution model: + +``` +Assemble → Check → Execute +``` + +**Assemble**: Build context from the team profile + project modules. Produces a CLAUDE.md specific to the developer and task context. + +**Check**: Run canary validation — a set of 3-5 test prompts that verify key behaviors before the actual task. If canary checks fail, fix the context issue before proceeding. + +**Execute**: Run Claude with the validated context on the actual task. + +```bash +#!/usr/bin/env bash +# ace.sh — Assemble, Check, Execute + +PROFILE="${1:-}" +TASK="${2:-}" + +if [[ -z "$PROFILE" || -z "$TASK" ]]; then + echo "Usage: ./ace.sh " + exit 1 +fi + +echo "=== ASSEMBLE ===" +./scripts/assemble-context.sh "$PROFILE" + +echo "=== CHECK ===" +./scripts/run-canaries.sh +CANARY_EXIT=$? + +if [[ $CANARY_EXIT -ne 0 ]]; then + echo "Canary checks failed. Fix context issues before executing." + exit 1 +fi + +echo "=== EXECUTE ===" +claude "$TASK" +``` + +### Session Retrospective + +At the end of each Claude Code session, before closing, ask: + +``` +Looking at what we built or changed in this session: +1. What patterns did we use that aren't in CLAUDE.md? +2. What did I have to correct that could become a rule? +3. What decisions did we make that should be documented? + +Generate 3-5 candidate rules for CLAUDE.md based on this session. +``` + +This takes 2-3 minutes and generates concrete improvement candidates. You review them and decide which to add. Over time, this is how configuration systems accumulate genuine project knowledge rather than just generic rules. + +--- + +## 7. Quality Measurement + +### Self-Evaluation Questions + +Run these questions against your CLAUDE.md periodically (quarterly at minimum): + +**Relevance**: +- Does this rule still apply to the current stack, libraries, and team practices? +- Was this rule written for a problem that no longer exists? +- Would a new team member understand why this rule exists? + +**Specificity**: +- Is this rule specific enough for Claude to know when it applies? +- Does this rule have at least one concrete example or counter-example? +- Could two developers interpret this rule differently? + +**Conflicts**: +- Does this rule contradict another rule in the same file? +- Does this rule contradict a rule in a path-scoped module? +- Does this rule contradict a global rule without explicitly overriding it? + +**Coverage**: +- Is this rule a specific case of a more general rule that already exists? +- Is this rule already implied by the architecture decisions stated elsewhere? + +A rule that fails more than one of these checks is a candidate for update or removal. + +### Canary Checks + +Canary checks are simple test prompts that verify Claude follows key conventions. Run them before and after major changes to CLAUDE.md to catch regressions. + +**Structure**: 3-5 prompts that are simple enough to answer quickly, but specific enough to reveal adherence failures. + +**Example canary set for a React/TypeScript project**: + +```bash +# scripts/run-canaries.sh + +PASS=0 +FAIL=0 + +check() { + local name="$1" + local prompt="$2" + local expected_pattern="$3" + + result=$(claude "$prompt" --output-format text 2>/dev/null) + + if echo "$result" | grep -qE "$expected_pattern"; then + echo "PASS: $name" + PASS=$((PASS + 1)) + else + echo "FAIL: $name" + echo " Expected pattern: $expected_pattern" + echo " Got: $(echo "$result" | head -5)" + FAIL=$((FAIL + 1)) + fi +} + +check "TypeScript interfaces" \ + "Generate a React component that accepts a name and age prop" \ + "interface.*Props" + +check "Named exports" \ + "Create a utility function that formats a date" \ + "^export (function|const)" + +check "No any type" \ + "Write a function that processes user data" \ + "^((?!: any).)*$" + +check "Error result type" \ + "Write a service function that fetches user data from an API" \ + "Result<" + +echo "" +echo "Canaries: $PASS passed, $FAIL failed" +[[ $FAIL -eq 0 ]] +``` + +**When to run canaries**: +- Before merging changes to CLAUDE.md +- After adding a new path-scoped module +- When a team member reports unexpected Claude behavior +- As part of the CI drift detection job + +### Adherence Tracking + +Informal but effective: for each key rule in CLAUDE.md, track how often Claude violates it across 10 consecutive interactions where the rule should apply. + +| Rule | Violations / 10 | Status | +|------|----------------|--------| +| TypeScript interfaces for props | 1/10 | Healthy | +| Result type for service functions | 0/10 | Healthy | +| No raw database IDs in API responses | 3/10 | Review rule | +| Structured logging with request context | 5/10 | Rule too vague | +| OWASP Top 10 check before shipping | 8/10 | Not actionable as stated | + +Rules with >20% violation rate are broken in one of three ways: +1. Too vague to apply consistently +2. Conflicting with another rule +3. Placed too late in the file to receive enough attention + +**Fix for "too vague"**: Add a concrete example of compliance and a counter-example of violation. + +**Fix for "conflicting"**: Find the conflict, decide which rule should win, update or remove the losing rule, and add an explicit note. + +**Fix for "placed too late"**: Move the rule to the top third of the file, or to a more prominent position in its section. + +### Context Debt Score + +A single metric for the health of your context engineering system: + +``` +Context Debt Score = (total_rules / 150) × (conflicts_found / total_rules) × 100 +``` + +Where: +- `total_rules` = count of distinct rules across all loaded config files +- `150` = the approximate attention ceiling +- `conflicts_found` = rules that contradict another rule + +| Score Range | Status | Action | +|-------------|--------|--------| +| < 30 | Healthy | Standard quarterly audit | +| 30 – 60 | Degraded | Prune and deduplicate; fix conflicts | +| 60 – 80 | Poor | Major restructure needed | +| > 80 | Critical | Start from scratch with top 30 rules | + +**Running the score calculation**: + +```bash +# Count rules (approximate: lines starting with -) +TOTAL_RULES=$(grep -c "^- " CLAUDE.md 2>/dev/null || echo 0) + +# Count conflicts requires manual review or an LLM audit pass +# Use: claude "Scan CLAUDE.md and count rules that contradict each other. Return the count." + +echo "Total rules: $TOTAL_RULES" +echo "Run conflict audit manually or with Claude" +``` + +### Useful Metrics to Track Over Time + +| Metric | How to Measure | Target | +|--------|---------------|--------| +| Always-on context size | `wc -w CLAUDE.md ~/.claude/CLAUDE.md` | < 5,000 words | +| Rule count | `grep -c "^- " CLAUDE.md` | < 150 | +| File age | `git log --follow -p CLAUDE.md | head -20` | Major review every 6 months | +| Violation rate per key rule | Manual spot checks | < 20% violation | +| Canary pass rate | `./scripts/run-canaries.sh` | 100% (all pass) | + +--- + +## 8. Context Reduction Techniques + +### Path-Scoping: The Highest-Leverage Technique + +Path-scoping reduces always-on context by 40-50% with no loss of coverage. It is the single most impactful structural change for projects beyond ~200 lines of configuration. + +Implementation steps: + +1. Identify natural domain boundaries in your codebase (API, frontend, database, tests, infrastructure) +2. For each domain, create a `CLAUDE-{domain}.md` file in the domain directory +3. Move domain-specific rules from root CLAUDE.md to the appropriate module +4. Replace moved content in root CLAUDE.md with `@path/to/CLAUDE-domain.md` imports +5. Verify adherence with canary checks + +Target after refactor: root CLAUDE.md at under 150 lines (shared rules + import declarations only). + +### Negative Constraints + +Empirically, negative constraints ("never do X") outperform positive instructions ("do X") by 15-25% for preventing bad patterns. This is counterintuitive — you might expect "do X" to be clearer. But in practice, the model needs to actively resist a temptation to do the wrong thing; explicitly naming the wrong thing and saying "never" is more salient. + +| Pattern | Formulation | Adherence | +|---------|-------------|-----------| +| Positive (weaker) | "Use structured logging for all backend services" | ~75% | +| Negative (stronger) | "Never use console.log in backend services; use the structured logger (pino)" | ~90% | + +**Technique**: For any rule where the wrong pattern is a common default (raw try/catch, console.log, default exports, any types), frame the rule as a negative constraint naming the specific pattern to avoid. + +### Rule Compression + +Long explanatory rules consume tokens and dilute attention. Compress explanations to their essence: + +**Before** (verbose, 38 words): +```markdown +- When creating React components, always make sure to use TypeScript interfaces + for props, and define them before the component declaration, not inline, to + improve readability and enable reuse. +``` + +**After** (compressed, 9 words): +```markdown +- React props: TypeScript interface, declared before component, never inline. +``` + +The compressed version has higher adherence — shorter rules are processed with more attention weight per rule. Save explanations for the rationale format when they're truly needed for understanding. + +**Compression heuristic**: If a rule takes more than one line, ask whether the extra content is a constraint or an explanation. Move explanations to comments (prefixed with `#` or a `>` blockquote) or rationale annotations. Keep the enforced constraint to one line. + +### Deduplication + +The same constraint stated multiple times (in different words) does not reinforce it — it dilutes the total attention budget. Find and remove semantic duplicates. + +**Common sources of duplication**: +- One rule in a general section, one more specific version in a path-scoped module +- A rule added to fix a problem, without removing the vaguer original rule it supersedes +- Rules copied from different team members' configs during a merge + +**Deduplication workflow**: + +``` +Scan CLAUDE.md for semantic duplicates. Two rules are duplicates if they +constrain the same behavior, even if worded differently. List all duplicate +pairs and recommend which version to keep based on specificity and clarity. +``` + +Run this as a Claude prompt against your CLAUDE.md. Review the suggestions and merge. + +### The Archive Pattern + +When removing a rule, you lose the knowledge of why it existed. That institutional memory can be valuable — six months later, someone may try to reintroduce the same pattern the rule was preventing. + +Instead of deleting obsolete rules, archive them: + +``` +.claude/ +├── CLAUDE.md # Active rules +└── CLAUDE-archive.md # Historical rules with retirement notes +``` + +**Archive entry format**: + +```markdown +## Archived Rules + +### [Retired 2026-01] Use MongoDB for session storage +Replaced by: Use PostgreSQL with the sessions table for session storage. +Reason: Standardized on single database; MongoDB was only used for sessions and added operational complexity. +``` + +The archive is not loaded by Claude — it is reference documentation for humans. It prevents the same debates and mistakes from recurring. + +### The 80/20 Rule for Rules + +Across most production configurations, 20% of rules account for 80% of Claude's consequential decisions. The other 80% of rules cover edge cases, stylistic preferences, and situations that rarely arise. + +Identifying your top 20%: + +1. List every rule in CLAUDE.md +2. For each rule, estimate: "How often does this rule meaningfully change Claude's output in a session?" +3. Rules that apply daily: keep, prioritize, place early +4. Rules that apply weekly: keep, place in middle +5. Rules that apply monthly: consider archiving or moving to a loaded-on-demand skill +6. Rules that apply rarely: archive + +The goal is not to eliminate coverage — it's to ensure that the rules that matter most are not diluted by the rules that matter least. + +**Placement matters**: Place your top 20% rules in the first third of CLAUDE.md. Attention weight is not uniform across a long document — early content has higher salience. + +### Summary: Reduction Techniques by Impact + +| Technique | Context Reduction | Effort | Adherence Impact | +|-----------|------------------|--------|-----------------| +| Path-scoping | 40-50% | Medium | +15-25% | +| Negative constraints | 0% (reformulation) | Low | +15-25% per rule | +| Rule compression | 20-30% | Low | +5-10% | +| Deduplication | 10-20% | Low | +5-15% | +| Archive pattern | 10-30% | Low | +5-10% | +| 80/20 prioritization | 0% (reordering) | Low | +10-20% | + +The highest-leverage sequence for a project with context debt: + +1. Path-scope (biggest structural win) +2. Deduplicate (removes noise) +3. Compress (sharpens remaining rules) +4. Archive (clears obsolete rules safely) +5. Reorder (prioritizes the rules that matter most) + +--- + +## Cross-References + +- Architecture and project structure patterns: `guide/core/architecture.md` +- Methodology frameworks for AI-assisted development: `guide/core/methodologies.md` +- Hooks and automation for context management: `guide/ultimate-guide.md` §5 (Hooks) +- MCP server integration for extended context: `guide/ultimate-guide.md` §7 (MCP) +- Security considerations for context content: `guide/security/` +- Path-scoped module examples: `examples/` directory + +--- + +*Part of the Claude Code Ultimate Guide. For the full reference, see `guide/ultimate-guide.md`.* diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 23f3b6f..ab14284 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -16,7 +16,7 @@ tags: [guide, reference, workflows, agents, hooks, mcp, security] **Last updated**: January 2026 -**Version**: 3.33.1 +**Version**: 3.34.0 --- @@ -5034,7 +5034,7 @@ The `.claude/` folder is your project's Claude Code directory for memory, settin | Personal preferences | `CLAUDE.md` | ❌ Gitignore | | Personal permissions | `settings.local.json` | ❌ Gitignore | -### 3.33.1 Version Control & Backup +### 3.34.0 Version Control & Backup **Problem**: Without version control, losing your Claude Code configuration means hours of manual reconfiguration across agents, skills, hooks, and MCP servers. @@ -22866,4 +22866,4 @@ We'll evaluate and add it to this section if it meets quality criteria. **Contributions**: Issues and PRs welcome. -**Last updated**: January 2026 | **Version**: 3.33.1 +**Last updated**: January 2026 | **Version**: 3.34.0 diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 5307cab..746be4b 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -3,7 +3,7 @@ # Source: guide/ultimate-guide.md # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code -version: "3.33.1" +version: "3.34.0" updated: "2026-03-03" # ════════════════════════════════════════════════════════════════ @@ -58,6 +58,30 @@ deep_dive: deployment_automation: "guide/ultimate-guide.md:13172" # Pattern #10: Vercel + Infisical guardrails iterative_refinement_community: "guide/workflows/iterative-refinement.md:515" # Pattern #7: Ralph Loop + Auto-Continue agent_teams_large_justified: "guide/workflows/agent-teams.md:120" # Pattern #4: when >5 agents are justified + # Context Engineering (consolidated reference) + context_engineering_guide: "guide/core/context-engineering.md" + context_engineering_what_is: "guide/core/context-engineering.md#1-what-is-context-engineering" + context_engineering_budget: "guide/core/context-engineering.md#2-the-context-budget" + context_engineering_hierarchy: "guide/core/context-engineering.md#3-configuration-hierarchy" + context_engineering_modular: "guide/core/context-engineering.md#4-modular-architecture" + context_engineering_team: "guide/core/context-engineering.md#5-team-assembly" + context_engineering_lifecycle: "guide/core/context-engineering.md#6-context-lifecycle" + context_engineering_quality: "guide/core/context-engineering.md#7-quality-measurement" + context_engineering_reduction: "guide/core/context-engineering.md#8-context-reduction-techniques" + context_engineering_audit_tool: "tools/context-audit-prompt.md" + context_engineering_examples: "examples/context-engineering/" + context_engineering_assembler: "examples/context-engineering/assembler.ts" + context_engineering_profile_template: "examples/context-engineering/profile-template.yaml" + context_engineering_skeleton: "examples/context-engineering/skeleton-template.md" + context_engineering_canary: "examples/context-engineering/canary-check.sh" + context_engineering_ci_drift: "examples/context-engineering/ci-drift-check.yml" + context_engineering_budget_calc: "examples/context-engineering/context-budget-calculator.sh" + context_engineering_eval_questions: "examples/context-engineering/eval-questions.yaml" + context_engineering_landing: "https://cc.bruniaux.com/context/" + context_150_ceiling: "guide/core/context-engineering.md#2-the-context-budget" + context_ace_pipeline: "guide/core/context-engineering.md#6-context-lifecycle" + context_path_scoping: "guide/core/context-engineering.md#4-modular-architecture" + context_maturity_model: "guide/core/context-engineering.md#7-quality-measurement" # Team Configuration at Scale (Profile-Based Module Assembly) team_ai_instructions_section: "guide/ultimate-guide.md#35-team-configuration-at-scale" team_ai_instructions_workflow: "guide/workflows/team-ai-instructions.md" @@ -1510,7 +1534,7 @@ ecosystem: - "Cross-links modified → Update all 4 repos" history: - date: "2026-01-20" - event: "Code Landing sync v3.33.1, 66 templates, cross-links" + event: "Code Landing sync v3.34.0, 66 templates, cross-links" commit: "5b5ce62" - date: "2026-01-20" event: "Cowork Landing fix (paths, README, UI badges)" @@ -1522,7 +1546,7 @@ ecosystem: onboarding_matrix_meta: version: "2.1.0" last_updated: "2026-03-09" - aligned_with_guide: "3.33.1" + aligned_with_guide: "3.34.0" changelog: - version: "2.1.0" date: "2026-03-09" @@ -1553,7 +1577,7 @@ onboarding_matrix: core: [rules, sandbox_native_guide, commands] time_budget: "5 min" topics_max: 3 - note: "SECURITY FIRST - sandbox before commands (v3.33.1 critical fix)" + note: "SECURITY FIRST - sandbox before commands (v3.34.0 critical fix)" beginner_15min: core: [rules, sandbox_native_guide, workflow, essential_commands] @@ -1642,7 +1666,7 @@ onboarding_matrix: - default: agent_validation_checklist time_budget: "60 min" topics_max: 6 - note: "Dual-instance pattern for quality workflows (v3.33.1)" + note: "Dual-instance pattern for quality workflows (v3.34.0)" learn_security: intermediate_30min: @@ -1653,7 +1677,7 @@ onboarding_matrix: - default: permission_modes time_budget: "30 min" topics_max: 4 - note: "NEW goal (v3.33.1) - Security-focused learning path" + note: "NEW goal (v3.34.0) - Security-focused learning path" power_60min: core: [sandbox_native_guide, mcp_secrets_management, security_hardening] @@ -1678,7 +1702,7 @@ onboarding_matrix: core: [rules, sandbox_native_guide, workflow, essential_commands, context_management, plan_mode] time_budget: "60 min" topics_max: 6 - note: "Security foundation + core workflow (v3.33.1 sandbox added)" + note: "Security foundation + core workflow (v3.34.0 sandbox added)" intermediate_120min: core: [plan_mode, agents, skills, config_hierarchy, git_mcp_guide, hooks, mcp_servers] diff --git a/tools/context-audit-prompt.md b/tools/context-audit-prompt.md new file mode 100644 index 0000000..cf015c2 --- /dev/null +++ b/tools/context-audit-prompt.md @@ -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*