feat(context): Context Engineering Configurator + consolidated guide (v3.34.0)
New: interactive configurator at cc.bruniaux.com/context/ that generates a personalized CLAUDE.md starter kit based on team size, stack, and current setup. Multi-step flow (profile, current state, stack, results) with maturity scoring (Level 1-5), copy-to-clipboard artifacts, localStorage persistence. Guide content: - guide/core/context-engineering.md (1,188 lines, 8 sections): context budget, 150-instruction ceiling, modular architecture, team assembly, ACE pipeline, quality measurement, context reduction techniques - examples/context-engineering/ (10 templates): assembler.ts, profile-template.yaml, skeleton-template.md, canary-check.sh, ci-drift-check.yml, eval-questions.yaml, context-budget-calculator.sh, rules/knowledge-feeding.md, rules/update-loop-retro.md - tools/context-audit-prompt.md (543 lines): 8-dimension scoring /100 Navigation: guide/README.md, machine-readable/reference.yaml (24 new entries) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
318ba915de
commit
fe28f89574
19 changed files with 3545 additions and 15 deletions
20
CHANGELOG.md
20
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
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
<p align="center">
|
||||
<a href="https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/claude-code-ultimate-guide?style=for-the-badge" alt="Stars"/></a>
|
||||
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_10,_2026_·_v3.33.1-brightgreen?style=for-the-badge" alt="Last Update"/></a>
|
||||
<a href="./CHANGELOG.md"><img src="https://img.shields.io/badge/Updated-Mar_11,_2026_·_v3.34.0-brightgreen?style=for-the-badge" alt="Last Update"/></a>
|
||||
<a href="./quiz/"><img src="https://img.shields.io/badge/Quiz-271_questions-orange?style=for-the-badge" alt="Quiz"/></a>
|
||||
<a href="./examples/"><img src="https://img.shields.io/badge/Templates-204-green?style=for-the-badge" alt="Templates"/></a>
|
||||
<a href="./guide/security/security-hardening.md"><img src="https://img.shields.io/badge/🛡️_Threat_DB-15_vulnerabilities_·_655_malicious_skills-red?style=for-the-badge" alt="Threat Database"/></a>
|
||||
|
|
@ -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*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
3.33.1
|
||||
3.34.0
|
||||
|
|
|
|||
78
examples/context-engineering/README.md
Normal file
78
examples/context-engineering/README.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Context Engineering Templates
|
||||
|
||||
Context engineering is the practice of deliberately designing what information Claude receives at session start — treating your `CLAUDE.md` and supporting files as a production system, not a one-time setup. These templates give you everything to build, measure, and maintain that system.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `profile-template.yaml` | Developer profile for per-person context assembly |
|
||||
| `skeleton-template.md` | Annotated `CLAUDE.md` skeleton with section-by-section guidance |
|
||||
| `assembler.ts` | TypeScript script to build `CLAUDE.md` from profile + modules |
|
||||
| `eval-questions.yaml` | 20 self-evaluation questions to audit your `CLAUDE.md` |
|
||||
| `canary-check.sh` | Behavioral regression test script (structural validation) |
|
||||
| `ci-drift-check.yml` | GitHub Actions workflow for weekly context drift detection |
|
||||
| `context-budget-calculator.sh` | Measures always-on token cost of your context configuration |
|
||||
| `rules/knowledge-feeding.md` | Rule template for proactive context updates after sessions |
|
||||
| `rules/update-loop-retro.md` | Session retrospective template to capture learnings |
|
||||
|
||||
## Quick Start
|
||||
|
||||
**New project — get a working `CLAUDE.md` in 3 steps:**
|
||||
|
||||
```bash
|
||||
# 1. Copy the skeleton and fill in your project details
|
||||
cp examples/context-engineering/skeleton-template.md CLAUDE.md
|
||||
|
||||
# 2. Check your context budget (keep it under 10K tokens)
|
||||
bash examples/context-engineering/context-budget-calculator.sh .
|
||||
|
||||
# 3. Run canary checks to validate structure
|
||||
bash examples/context-engineering/canary-check.sh .
|
||||
```
|
||||
|
||||
**Existing project — audit and improve:**
|
||||
|
||||
```bash
|
||||
# Run the structural check
|
||||
bash examples/context-engineering/canary-check.sh .
|
||||
|
||||
# Then use eval-questions.yaml to score your CLAUDE.md manually
|
||||
# Target: 16+ / 20
|
||||
```
|
||||
|
||||
**Team setup — per-developer profiles:**
|
||||
|
||||
```bash
|
||||
# Install dependencies for the assembler
|
||||
npm install js-yaml @types/js-yaml ts-node typescript
|
||||
|
||||
# Copy the profile template and customize
|
||||
cp examples/context-engineering/profile-template.yaml .claude/profiles/yourname.yaml
|
||||
# Edit .claude/profiles/yourname.yaml with your stack and preferences
|
||||
|
||||
# Assemble your CLAUDE.md
|
||||
ts-node examples/context-engineering/assembler.ts \
|
||||
--profile .claude/profiles/yourname.yaml \
|
||||
--modules .claude/modules \
|
||||
--output CLAUDE.md
|
||||
```
|
||||
|
||||
**Ongoing maintenance:**
|
||||
|
||||
```bash
|
||||
# Weekly: run canary checks
|
||||
bash examples/context-engineering/canary-check.sh .
|
||||
|
||||
# After sessions: use the retro template
|
||||
# See rules/update-loop-retro.md
|
||||
|
||||
# Add the CI workflow for automated drift detection
|
||||
cp examples/context-engineering/ci-drift-check.yml .github/workflows/context-drift.yml
|
||||
```
|
||||
|
||||
## Guide Section
|
||||
|
||||
Full methodology and principles: `guide/core/context-engineering.md`
|
||||
|
||||
The templates here are the operational layer — the guide explains the reasoning behind each design decision.
|
||||
243
examples/context-engineering/assembler.ts
Normal file
243
examples/context-engineering/assembler.ts
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
#!/usr/bin/env ts-node
|
||||
/**
|
||||
* Context Assembler
|
||||
*
|
||||
* Assembles CLAUDE.md from a developer profile YAML + shared module markdown files.
|
||||
* Supports @import resolution, module exclusions, and per-developer overrides.
|
||||
*
|
||||
* Usage:
|
||||
* ts-node assembler.ts --profile .claude/profiles/alice.yaml --output CLAUDE.md
|
||||
* ts-node assembler.ts --profile .claude/profiles/alice.yaml --modules .claude/modules --output CLAUDE.md --dry-run
|
||||
*
|
||||
* Dependencies:
|
||||
* npm install js-yaml @types/js-yaml ts-node typescript
|
||||
*/
|
||||
|
||||
import fs from 'fs'
|
||||
import path from 'path'
|
||||
import yaml from 'js-yaml'
|
||||
|
||||
// ── Types ────────────────────────────────────────────────────────────────────
|
||||
|
||||
interface ProfileTools {
|
||||
primary_lang: string
|
||||
frontend?: string
|
||||
backend?: string
|
||||
database?: string
|
||||
cloud?: string
|
||||
test_framework?: string
|
||||
}
|
||||
|
||||
interface ProfileStyle {
|
||||
verbosity: 'verbose' | 'concise' | 'minimal'
|
||||
comment_style: 'none' | 'inline' | 'jsdoc'
|
||||
test_coverage: 'none' | 'optional' | 'required'
|
||||
}
|
||||
|
||||
interface Profile {
|
||||
profile: {
|
||||
name: string
|
||||
role: string
|
||||
seniority: string
|
||||
tools: ProfileTools
|
||||
style: ProfileStyle
|
||||
}
|
||||
modules: {
|
||||
include: string[]
|
||||
exclude: string[]
|
||||
}
|
||||
overrides: {
|
||||
custom_rules: string[]
|
||||
}
|
||||
}
|
||||
|
||||
interface AssemblyResult {
|
||||
content: string
|
||||
totalChars: number
|
||||
estimatedTokens: number
|
||||
modulesLoaded: number
|
||||
modulesMissing: string[]
|
||||
importsResolved: number
|
||||
}
|
||||
|
||||
// ── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
function loadProfile(profilePath: string): Profile {
|
||||
if (!fs.existsSync(profilePath)) {
|
||||
throw new Error(`Profile not found: ${profilePath}`)
|
||||
}
|
||||
const content = fs.readFileSync(profilePath, 'utf8')
|
||||
return yaml.load(content) as Profile
|
||||
}
|
||||
|
||||
function resolveImports(content: string, baseDir: string, depth = 0): string {
|
||||
if (depth > 5) {
|
||||
console.warn(' Warning: @import depth limit reached (5) — circular imports?')
|
||||
return content
|
||||
}
|
||||
return content.replace(/^@(.+)$/gm, (_, importPath) => {
|
||||
const fullPath = path.resolve(baseDir, importPath.trim())
|
||||
if (!fs.existsSync(fullPath)) {
|
||||
return `<!-- @import ${importPath} — FILE NOT FOUND -->`
|
||||
}
|
||||
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<!-- ── Module: ${modulePath} ── -->\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()
|
||||
285
examples/context-engineering/canary-check.sh
Executable file
285
examples/context-engineering/canary-check.sh
Executable file
|
|
@ -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
|
||||
216
examples/context-engineering/ci-drift-check.yml
Normal file
216
examples/context-engineering/ci-drift-check.yml
Normal file
|
|
@ -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
|
||||
188
examples/context-engineering/context-budget-calculator.sh
Executable file
188
examples/context-engineering/context-budget-calculator.sh
Executable file
|
|
@ -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
|
||||
173
examples/context-engineering/eval-questions.yaml
Normal file
173
examples/context-engineering/eval-questions.yaml
Normal file
|
|
@ -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"
|
||||
82
examples/context-engineering/profile-template.yaml
Normal file
82
examples/context-engineering/profile-template.yaml
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
# Developer Profile Template
|
||||
# Customize and save as: .claude/profiles/<your-name>.yaml
|
||||
# Run: ts-node assembler.ts --profile .claude/profiles/<your-name>.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"
|
||||
93
examples/context-engineering/rules/knowledge-feeding.md
Normal file
93
examples/context-engineering/rules/knowledge-feeding.md
Normal file
|
|
@ -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.
|
||||
108
examples/context-engineering/rules/update-loop-retro.md
Normal file
108
examples/context-engineering/rules/update-loop-retro.md
Normal file
|
|
@ -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.
|
||||
288
examples/context-engineering/skeleton-template.md
Normal file
288
examples/context-engineering/skeleton-template.md
Normal file
|
|
@ -0,0 +1,288 @@
|
|||
# CLAUDE.md — [Project Name]
|
||||
|
||||
<!--
|
||||
HOW TO USE THIS SKELETON
|
||||
|
||||
Fill in each section based on your project. Delete placeholder comments when done.
|
||||
Goal: give Claude enough context to make correct decisions without asking, while staying under 500 lines.
|
||||
|
||||
Key principles:
|
||||
- Specific beats vague: "Use zod for external input validation" beats "validate inputs"
|
||||
- Anti-patterns are as valuable as rules: tell Claude what NOT to do
|
||||
- Update after each significant session (see rules/update-loop-retro.md)
|
||||
- Run `canary-check.sh` weekly to catch drift
|
||||
-->
|
||||
|
||||
## Project Overview
|
||||
|
||||
<!--
|
||||
Write 2-3 sentences answering:
|
||||
- What does this project do?
|
||||
- Who uses it? (internal tool, public API, consumer app, etc.)
|
||||
- What's the primary language and deployment target?
|
||||
|
||||
Example:
|
||||
"A REST API that processes financial transactions for retail merchants, consumed by a Next.js
|
||||
dashboard and a React Native mobile app. Built with Node.js + TypeScript, deployed to AWS ECS.
|
||||
PCI-DSS compliance applies to all payment-adjacent code."
|
||||
-->
|
||||
|
||||
[PROJECT DESCRIPTION]
|
||||
|
||||
## Architecture
|
||||
|
||||
<!--
|
||||
Describe the shape of the system. Not a tutorial — just the decisions Claude needs to
|
||||
make correct assumptions. Diagrams are optional; prose is fine.
|
||||
|
||||
Cover:
|
||||
- Monolith or services? If services, how many and how do they communicate?
|
||||
- How is state managed (database, cache, event sourcing)?
|
||||
- Key data flow (request lifecycle, async patterns)
|
||||
- Folder structure if non-obvious
|
||||
-->
|
||||
|
||||
### 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
|
||||
|
||||
<!--
|
||||
Record the "why" behind non-obvious choices. This prevents Claude from suggesting
|
||||
alternatives that were already considered and rejected.
|
||||
|
||||
Example:
|
||||
- Repository pattern is NOT used — we use Prisma directly in services (decision: team
|
||||
familiarity, added abstraction not worth it at current scale)
|
||||
- Zod schemas are colocated with route handlers, not in a shared schemas/ directory
|
||||
-->
|
||||
|
||||
- [DECISION 1]
|
||||
- [DECISION 2]
|
||||
|
||||
## Code Standards
|
||||
|
||||
<!--
|
||||
Be specific. "Write clean code" is useless. "Use named exports only — no default exports" is actionable.
|
||||
Organize by language/domain if you have multiple.
|
||||
-->
|
||||
|
||||
### 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
|
||||
|
||||
<!--
|
||||
Undefined behavior here causes the most inconsistency. Be explicit.
|
||||
|
||||
Example:
|
||||
- All async functions must be wrapped in try/catch at the handler boundary
|
||||
- Errors propagate up as typed error objects, never raw strings
|
||||
- Use the AppError class in src/errors.ts — never throw plain Error objects in service layer
|
||||
-->
|
||||
|
||||
- [ERROR HANDLING RULES]
|
||||
|
||||
### Comments
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- Inline comments only on non-obvious logic (never explain what the code does, only why)
|
||||
- All exported functions must have a JSDoc block with @param and @returns
|
||||
- TODO comments are not allowed in production code — open an issue instead
|
||||
-->
|
||||
|
||||
- [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
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- All PRs require at least one reviewer
|
||||
- CI must be green before merge
|
||||
- PR description must include "Why" not just "What"
|
||||
- Link to issue or ticket in PR body
|
||||
-->
|
||||
|
||||
- [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
|
||||
|
||||
<!--
|
||||
Vague testing rules produce no tests. Specific rules produce correct tests.
|
||||
Tell Claude: what framework, what to test, how to structure tests, what coverage means here.
|
||||
-->
|
||||
|
||||
### 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
|
||||
|
||||
<!--
|
||||
Tell Claude what to verify after deploying so it can suggest this when relevant.
|
||||
|
||||
Example:
|
||||
- Check /health endpoint returns 200
|
||||
- Verify Sentry has no new errors in first 5 minutes
|
||||
- Confirm database migrations ran (check migration table)
|
||||
-->
|
||||
|
||||
- [POST-DEPLOY CHECKS]
|
||||
|
||||
## What Claude Should NOT Do
|
||||
|
||||
<!--
|
||||
This section is high-value. Anti-patterns prevent regressions and stop Claude from
|
||||
suggesting alternatives that were already rejected.
|
||||
|
||||
Be specific about the pattern AND why it's banned.
|
||||
-->
|
||||
|
||||
### 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
|
||||
|
||||
<!--
|
||||
Example:
|
||||
- Never use class components in React — functional components only
|
||||
- Never mutate request/response objects directly — use immutable patterns
|
||||
- Never use console.log in production code — use the logger at src/lib/logger.ts
|
||||
- Never hardcode environment-specific values — use process.env with validation in src/config.ts
|
||||
-->
|
||||
|
||||
- [ANTI-PATTERN 1]
|
||||
- [ANTI-PATTERN 2]
|
||||
- [ANTI-PATTERN 3]
|
||||
|
||||
### Known Problem Areas
|
||||
|
||||
<!--
|
||||
Patterns that caused production bugs or significant rework. Claude should be extra careful here.
|
||||
|
||||
Example:
|
||||
- The order state machine in src/orders/state.ts is complex — always read it fully before modifying
|
||||
- Payment webhooks are idempotent — every handler must check for duplicate event IDs
|
||||
-->
|
||||
|
||||
- [KNOWN PROBLEM AREA 1]
|
||||
- [KNOWN PROBLEM AREA 2]
|
||||
|
|
@ -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 |
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
|
|
|
|||
1188
guide/core/context-engineering.md
Normal file
1188
guide/core/context-engineering.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
543
tools/context-audit-prompt.md
Normal file
543
tools/context-audit-prompt.md
Normal file
|
|
@ -0,0 +1,543 @@
|
|||
# Audit Your Context Engineering Setup
|
||||
|
||||
> A self-contained prompt to measure and improve your Claude Code context architecture.
|
||||
|
||||
**Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)
|
||||
|
||||
**Reference**: [The Ultimate Claude Code Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. What This Does
|
||||
|
||||
This prompt instructs Claude to audit your context engineering setup by:
|
||||
|
||||
1. **Measuring** total always-on context size, CLAUDE.md length, and path-scoping ratio
|
||||
2. **Detecting** skills-to-rules balance, redundancy, and negative vs positive instructions
|
||||
3. **Flagging** staleness signals (last updated, broken imports, deprecated references)
|
||||
4. **Scoring** across 8 dimensions for a total of /100 with prioritized recommendations
|
||||
|
||||
**Performance**: Uses bash/grep for efficient scanning. Claude reads files only when specific content analysis is needed.
|
||||
|
||||
**Important**: Claude will NOT make any changes without your explicit approval.
|
||||
|
||||
---
|
||||
|
||||
## 2. Who This Is For
|
||||
|
||||
| Level | What You Get |
|
||||
|-------|-------------|
|
||||
| **Solo developer** | Find quick wins: trim bloat, add missing sections, fix stale imports |
|
||||
| **Small team (2-10)** | Identify consistency gaps and opportunities for profile-based assembly |
|
||||
| **Large team (10+)** | Systematic context architecture assessment with maturity scoring |
|
||||
|
||||
**Prerequisites**:
|
||||
- Claude Code installed and working
|
||||
- A project with at least a CLAUDE.md or `.claude/` directory
|
||||
- Bash shell (native on macOS/Linux, WSL on Windows)
|
||||
|
||||
**Time**: ~3-5 minutes
|
||||
|
||||
---
|
||||
|
||||
## 3. How to Use It
|
||||
|
||||
### Step 1: Copy the Prompt
|
||||
|
||||
Copy everything inside the code block in [Section 4](#4-the-prompt) below.
|
||||
|
||||
### Step 2: Run Claude Code
|
||||
|
||||
```bash
|
||||
cd your-project-directory
|
||||
claude
|
||||
```
|
||||
|
||||
### Step 3: Paste and Execute
|
||||
|
||||
Paste the prompt and press Enter. Claude will begin the audit.
|
||||
|
||||
### Step 4: Review Results
|
||||
|
||||
Claude will present findings, then ask for validation before making any changes.
|
||||
|
||||
### Platform Note
|
||||
|
||||
| Platform | Global Config Path |
|
||||
|----------|-------------------|
|
||||
| **macOS/Linux** | `~/.claude/` |
|
||||
| **Windows** | `%USERPROFILE%\.claude\` |
|
||||
|
||||
---
|
||||
|
||||
## 4. The Prompt
|
||||
|
||||
```markdown
|
||||
# Audit My Context Engineering Setup
|
||||
|
||||
## Context
|
||||
|
||||
Perform a comprehensive context engineering audit of my Claude Code configuration.
|
||||
Focus on context size, structure quality, freshness, and team scalability.
|
||||
|
||||
Reference: https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md
|
||||
|
||||
## Instructions
|
||||
|
||||
### Phase 1: Discovery (Bash Scan)
|
||||
|
||||
**IMPORTANT**: Use bash commands exclusively in this phase. Do NOT read files yet.
|
||||
|
||||
#### 1.1 Size & Structure Scan
|
||||
|
||||
```bash
|
||||
bash -c '
|
||||
echo "=== GLOBAL CLAUDE.MD ==="
|
||||
if [ -f ~/.claude/CLAUDE.md ]; then
|
||||
lines=$(wc -l < ~/.claude/CLAUDE.md | tr -d " ")
|
||||
chars=$(wc -c < ~/.claude/CLAUDE.md | tr -d " ")
|
||||
tokens=$(echo "scale=0; $chars / 4" | bc 2>/dev/null || echo "~$((chars/4))")
|
||||
echo "Lines: $lines"
|
||||
echo "Chars: $chars (~$tokens tokens)"
|
||||
echo "Imports: $(grep -c "^@" ~/.claude/CLAUDE.md 2>/dev/null || echo 0)"
|
||||
echo "Rules count: $(grep -cE "^[-*] |^\d+\. " ~/.claude/CLAUDE.md 2>/dev/null || echo 0)"
|
||||
echo "Last commit: $(cd ~/.claude && git log --format="%ar" -- CLAUDE.md 2>/dev/null | head -1 || echo "not tracked")"
|
||||
else
|
||||
echo "NOT FOUND"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "=== PROJECT CLAUDE.MD ==="
|
||||
for f in ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
if [ -f "$f" ]; then
|
||||
lines=$(wc -l < "$f" | tr -d " ")
|
||||
chars=$(wc -c < "$f" | tr -d " ")
|
||||
tokens=$(echo "scale=0; $chars / 4" | bc 2>/dev/null || echo "~$((chars/4))")
|
||||
echo "File: $f"
|
||||
echo "Lines: $lines"
|
||||
echo "Chars: $chars (~$tokens tokens)"
|
||||
echo "Imports: $(grep -c "^@" "$f" 2>/dev/null || echo 0)"
|
||||
echo "Rules count: $(grep -cE "^[-*] |^\d+\. " "$f" 2>/dev/null || echo 0)"
|
||||
echo "Last commit: $(git log --format="%ar" -- "$f" 2>/dev/null | head -1 || echo "not tracked")"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== IMPORTED FILES ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
while IFS= read -r line; do
|
||||
[[ "$line" =~ ^@ ]] || continue
|
||||
import_path="${line#@}"
|
||||
import_path="${import_path/ */}"
|
||||
resolved="${import_path/#\~/$HOME}"
|
||||
resolved="${resolved/#./$PWD}"
|
||||
if [ -f "$resolved" ]; then
|
||||
sz=$(wc -c < "$resolved" | tr -d " ")
|
||||
tk=$(echo "scale=0; $sz / 4" | bc 2>/dev/null || echo "$((sz/4))")
|
||||
echo " FOUND $line (~$tk tokens)"
|
||||
else
|
||||
echo " BROKEN $line (file not found)"
|
||||
fi
|
||||
done < "$f"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== RULES & MODULES ==="
|
||||
for d in ~/.claude ./.claude; do
|
||||
[ -d "$d" ] || continue
|
||||
for sub in rules skills commands agents hooks; do
|
||||
if [ -d "$d/$sub" ]; then
|
||||
count=$(find "$d/$sub" -maxdepth 1 -type f | wc -l | tr -d " ")
|
||||
total_chars=$(find "$d/$sub" -maxdepth 1 -type f -exec cat {} \; 2>/dev/null | wc -c | tr -d " ")
|
||||
tokens=$((total_chars / 4))
|
||||
echo " $d/$sub: $count files (~$tokens tokens)"
|
||||
fi
|
||||
done
|
||||
done
|
||||
'
|
||||
```
|
||||
|
||||
**Store the output** for evaluation.
|
||||
|
||||
#### 1.2 Quality Pattern Scan
|
||||
|
||||
```bash
|
||||
bash -c '
|
||||
echo "=== NEGATIVE VS POSITIVE INSTRUCTIONS ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
neg=$(grep -ciE "never|do not|dont|avoid|prohibited|forbidden|not allowed|do NOT" "$f" 2>/dev/null || echo 0)
|
||||
pos=$(grep -ciE "always|prefer|use|should|must|recommended|do this" "$f" 2>/dev/null || echo 0)
|
||||
echo "$f: negative=$neg positive=$pos"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== VAGUE INSTRUCTIONS (red flags) ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
echo "$f:"
|
||||
grep -inE "be careful|good practice|appropriately|as needed|when necessary|use your judgment|you should know|be smart" "$f" 2>/dev/null | head -5 || echo " none found"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== DUPLICATE SECTION HEADERS ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
dupes=$(grep -E "^#{1,3} " "$f" | sort | uniq -d)
|
||||
[ -n "$dupes" ] && echo "$f DUPLICATES: $dupes" || echo "$f: no duplicate headers"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== DEPRECATED REFERENCES ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
echo "$f:"
|
||||
grep -niE "claude-1|claude-2\.0|claude-3-haiku-|gpt-3\.5|text-davinci|codex|copilot X|cursor pro 1\." "$f" 2>/dev/null | head -5 || echo " none found"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== PATH SCOPING (modular setup) ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
scoped=$(grep -cE "^@.+\.(ts|tsx|js|jsx|py|rs|go|md)$|globs:|path:" "$f" 2>/dev/null || echo 0)
|
||||
echo "$f path-scoped entries: $scoped"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== SESSION & UPDATE PROTOCOL ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
has_update=$(grep -ciE "update|review|quarterly|maintenance|how to update|keep.*fresh" "$f" 2>/dev/null || echo 0)
|
||||
has_session=$(grep -ciE "session|retro|checkpoint|lesson learned|knowledge loop" "$f" 2>/dev/null || echo 0)
|
||||
echo "$f: update-protocol=$has_update session-retro=$has_session"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== TEAM/PROFILE READINESS ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
has_profile=$(grep -ciE "profile|role:|junior|senior|lead|persona|persona-" "$f" 2>/dev/null || echo 0)
|
||||
has_module=$(grep -cE "^@" "$f" 2>/dev/null || echo 0)
|
||||
echo "$f: profile-mentions=$has_profile module-imports=$has_module"
|
||||
done
|
||||
'
|
||||
```
|
||||
|
||||
**Store the output** for evaluation.
|
||||
|
||||
#### 1.3 Freshness & Conflict Scan
|
||||
|
||||
```bash
|
||||
bash -c '
|
||||
echo "=== GIT FRESHNESS ==="
|
||||
for path in ~/.claude ./; do
|
||||
if git -C "$path" rev-parse --git-dir &>/dev/null 2>&1; then
|
||||
echo "Repo at $path:"
|
||||
git -C "$path" log --format="%ar %s" -- CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -3 || echo " no commits for CLAUDE.md"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== CONFLICTING RULES PATTERNS ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
echo "$f:"
|
||||
# Look for contradictory patterns like "always X" near "never X"
|
||||
always_terms=$(grep -ioE "always [a-z ]+" "$f" 2>/dev/null | sed "s/always //i" | sort)
|
||||
never_terms=$(grep -ioE "never [a-z ]+" "$f" 2>/dev/null | sed "s/never //i" | sort)
|
||||
conflicts=$(comm -12 <(echo "$always_terms") <(echo "$never_terms") 2>/dev/null)
|
||||
[ -n "$conflicts" ] && echo " POTENTIAL CONFLICTS: $conflicts" || echo " no obvious contradictions"
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "=== OVERVIEW / ARCHITECTURE SECTION ==="
|
||||
for f in ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/CLAUDE.md; do
|
||||
[ -f "$f" ] || continue
|
||||
has_overview=$(grep -ciE "^## (overview|purpose|about|architecture|what this|context)" "$f" 2>/dev/null || echo 0)
|
||||
has_antip=$(grep -ciE "anti.pattern|bad example|do not do|wrong way|pitfall" "$f" 2>/dev/null || echo 0)
|
||||
has_hierarchy=$(grep -cE "^#{1,3} " "$f" 2>/dev/null || echo 0)
|
||||
echo "$f: has-overview=$has_overview anti-patterns=$has_antip section-count=$has_hierarchy"
|
||||
done
|
||||
'
|
||||
```
|
||||
|
||||
**Store the output** for evaluation.
|
||||
|
||||
### Phase 2: Evaluate Across 8 Dimensions
|
||||
|
||||
Use the scan outputs from Phase 1. Read specific file sections only if content examples are needed for the report.
|
||||
|
||||
#### Dimension 1: Size & Budget (15 pts)
|
||||
|
||||
Evaluate based on token estimates from Phase 1:
|
||||
|
||||
| Check | Points | Threshold |
|
||||
|-------|--------|-----------|
|
||||
| Total always-on context under 8K tokens | 5 | Sum of all CLAUDE.md + imports |
|
||||
| Rule count under 150 instructions | 5 | global + project combined |
|
||||
| No single file over 400 lines | 5 | flag if exceeded |
|
||||
|
||||
Deduct points proportionally if thresholds are exceeded. A file at 600 lines = 3/5 not 0.
|
||||
|
||||
#### Dimension 2: Structure (15 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| Has an overview/purpose section | 4 | h2 with "overview", "purpose", "about", "context" |
|
||||
| Has architecture or project-layout section | 3 | h2 with "architecture", "structure", "layout" |
|
||||
| Includes anti-patterns or bad examples | 4 | "anti-pattern", "do not", "pitfall" |
|
||||
| Section count indicates clear hierarchy | 4 | 3+ distinct h2 sections |
|
||||
|
||||
#### Dimension 3: Path-Scoping (12 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| Uses @imports for modular breakdown | 5 | at least 2 @import lines |
|
||||
| At least one path-specific or glob-scoped rule | 4 | globs: or file-specific section |
|
||||
| Not a monolithic file (all instructions in one block) | 3 | multiple files or sections |
|
||||
|
||||
#### Dimension 4: Rule Quality (15 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| Ratio positive:negative >= 2:1 | 5 | from negative/positive counts |
|
||||
| No vague instructions detected | 5 | zero "be careful", "as needed", etc. |
|
||||
| Rules are specific and actionable | 5 | judged from sample during report generation |
|
||||
|
||||
#### Dimension 5: Freshness (12 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| CLAUDE.md committed within past 6 months | 5 | git log output |
|
||||
| No deprecated tool/model references | 4 | deprecated scan output |
|
||||
| No broken @imports | 3 | BROKEN lines in import scan |
|
||||
|
||||
#### Dimension 6: Team Readiness (10 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| Has profile-based or role-based structure | 4 | profile mentions >= 1 |
|
||||
| Module imports enable selective assembly | 3 | module-imports >= 3 |
|
||||
| Documented update protocol for team | 3 | update-protocol >= 1 |
|
||||
|
||||
#### Dimension 7: Conflict Detection (11 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| No contradictory rules detected | 5 | no conflicts from scan |
|
||||
| No duplicate section headers | 3 | no duplicates found |
|
||||
| Session retro or knowledge loop pattern | 3 | session-retro >= 1 |
|
||||
|
||||
#### Dimension 8: Knowledge Loop (10 pts)
|
||||
|
||||
| Check | Points | Signal |
|
||||
|-------|--------|--------|
|
||||
| Has update/review protocol documented | 4 | update-protocol >= 1 |
|
||||
| Has session retro or lesson-learned pattern | 3 | session-retro >= 1 |
|
||||
| Context tracked in git (auditable changes) | 3 | git freshness scan shows commits |
|
||||
|
||||
#### Calculate Total Score
|
||||
|
||||
`Score = sum of earned points across all 8 dimensions`
|
||||
|
||||
### Phase 3: Generate Report
|
||||
|
||||
Structure your output exactly as:
|
||||
|
||||
---
|
||||
|
||||
## Context Engineering Audit
|
||||
|
||||
### Score: [XX]/100
|
||||
|
||||
| Dimension | Score | Notes |
|
||||
|-----------|-------|-------|
|
||||
| Size & Budget | X/15 | total ~X tokens, X rules |
|
||||
| Structure | X/15 | X sections, has/missing overview |
|
||||
| Path-Scoping | X/12 | X imports, monolithic/modular |
|
||||
| Rule Quality | X/15 | X% positive, X vague found |
|
||||
| Freshness | X/12 | last updated X, X broken imports |
|
||||
| Team Readiness | X/10 | X profiles, update protocol: yes/no |
|
||||
| Conflict Detection | X/11 | X contradictions, X duplicate headers |
|
||||
| Knowledge Loop | X/10 | git tracked: yes/no, retro: yes/no |
|
||||
|
||||
### Context Budget
|
||||
- Global CLAUDE.md: ~X tokens
|
||||
- Project CLAUDE.md: ~X tokens
|
||||
- @imports combined: ~X tokens
|
||||
- Total always-on: ~X tokens
|
||||
- Rule count: X/150 instructions
|
||||
|
||||
### Priority Issues (fix these first)
|
||||
1. [Issue] — [specific fix with example]
|
||||
2. [Issue] — [specific fix with example]
|
||||
3. [Issue] — [specific fix with example]
|
||||
|
||||
### Quick Wins (< 30 min each)
|
||||
- [Fix]: [what to do and where]
|
||||
- [Fix]: [what to do and where]
|
||||
- [Fix]: [what to do and where]
|
||||
|
||||
### Maturity Level
|
||||
[Choose one and explain why]
|
||||
|
||||
**Level 1 — Empty** (0-19): No structured context. Claude operates with zero project knowledge.
|
||||
**Level 2 — Basic** (20-39): CLAUDE.md exists but is monolithic, stale, or mostly vague rules.
|
||||
**Level 3 — Structured** (40-59): Clear sections and imports, but missing freshness or team patterns.
|
||||
**Level 4 — Optimized** (60-79): Modular, scoped, positive-first rules with a known update cadence.
|
||||
**Level 5 — Engineering-Grade** (80-100): Profile-aware, git-tracked, conflict-free, knowledge loop active.
|
||||
|
||||
### Ready-to-use Improvements
|
||||
|
||||
Provide 2-3 concrete text blocks that users can paste directly into their CLAUDE.md.
|
||||
Each block must address a Priority Issue identified above. Format:
|
||||
|
||||
**Improvement 1: [name]**
|
||||
File: `[path]` — add at [top/section X/end]
|
||||
```
|
||||
[exact text to paste]
|
||||
```
|
||||
|
||||
**Improvement 2: [name]**
|
||||
File: `[path]` — add at [top/section X/end]
|
||||
```
|
||||
[exact text to paste]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Await Validation
|
||||
|
||||
**CRITICAL**: Do NOT create or modify any files without explicit approval.
|
||||
|
||||
After presenting the report, ask:
|
||||
|
||||
"Which improvements would you like me to implement?
|
||||
|
||||
Options:
|
||||
- `all` — Apply all ready-to-use improvements
|
||||
- `1, 2` — Specific improvements by number
|
||||
- `priority` — Only Priority Issues fixes
|
||||
- `none` — Keep the report for reference only
|
||||
|
||||
Please specify your choice:"
|
||||
|
||||
Wait for explicit user response before taking any action.
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure your response exactly as:
|
||||
|
||||
1. **Score table** with dimension breakdown
|
||||
2. **Context Budget** summary
|
||||
3. **Priority Issues** (numbered, fix first)
|
||||
4. **Quick Wins** (bullet list, < 30 min each)
|
||||
5. **Maturity Level** with explanation
|
||||
6. **Ready-to-use Improvements** (paste-ready text blocks)
|
||||
7. **Validation Request** (ask before implementing)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. What to Expect
|
||||
|
||||
Here's an example of what the audit report looks like:
|
||||
|
||||
### Example Score Table
|
||||
|
||||
```
|
||||
## Context Engineering Audit
|
||||
|
||||
### Score: 52/100
|
||||
|
||||
| Dimension | Score | Notes |
|
||||
|-----------|-------|-------|
|
||||
| Size & Budget | 10/15 | ~6,200 tokens total, 182 rules (over limit) |
|
||||
| Structure | 9/15 | 4 sections, no anti-patterns section |
|
||||
| Path-Scoping | 4/12 | 1 import, monolithic project CLAUDE.md |
|
||||
| Rule Quality | 8/15 | 60% positive, 3 vague instructions found |
|
||||
| Freshness | 9/12 | last commit 4 months ago, 1 broken import |
|
||||
| Team Readiness | 3/10 | no profiles, no update protocol |
|
||||
| Conflict Detection | 6/11 | 1 "always/never" contradiction, no duplicate headers |
|
||||
| Knowledge Loop | 3/10 | not git tracked, no retro pattern |
|
||||
```
|
||||
|
||||
### Example Quick Wins
|
||||
|
||||
```
|
||||
Quick Wins (< 30 min each):
|
||||
- Fix broken import: @~/.claude/TONE.md not found — update path or remove
|
||||
- Add overview section: 2-line project description at top of CLAUDE.md
|
||||
- Trim rule count: merge 3 formatting rules into one compressed block
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Scoring Guide
|
||||
|
||||
| Score | Maturity | Recommended Action |
|
||||
|-------|----------|--------------------|
|
||||
| **80-100** | Level 5: Engineering-Grade | Maintain with quarterly review |
|
||||
| **60-79** | Level 4: Optimized | Address priority issues, reach 80 |
|
||||
| **40-59** | Level 3: Structured | Dedicate a session to improvement |
|
||||
| **20-39** | Level 2: Basic | Restructure recommended, use template |
|
||||
| **0-19** | Level 1: Empty | Start fresh with skeleton template |
|
||||
|
||||
---
|
||||
|
||||
## 7. Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|------|-----------|
|
||||
| **Always-on context** | Everything Claude loads before your first message: CLAUDE.md files plus all @imports |
|
||||
| **@import** | A line starting with `@` in CLAUDE.md that loads another file into context |
|
||||
| **Path-scoping** | Applying rules only to specific file types or directories, not globally |
|
||||
| **Rule quality** | Specificity and actionability of instructions — vague rules waste tokens and confuse Claude |
|
||||
| **Knowledge loop** | The practice of updating context files after sessions based on what worked and what didn't |
|
||||
| **Profile assembly** | Combining different context modules to create role-specific setups (junior, senior, reviewer) |
|
||||
| **Staleness signal** | Indicators that context is outdated: broken imports, deprecated model names, no git history |
|
||||
| **Conflict** | Two rules that contradict each other — Claude will pick one arbitrarily, usually the wrong one |
|
||||
| **Monolithic CLAUDE.md** | A single large file with all instructions, no imports, no modular breakdown |
|
||||
| **Maturity level** | A 1-5 scale measuring context engineering sophistication from empty to engineering-grade |
|
||||
|
||||
---
|
||||
|
||||
## 8. Common Issues
|
||||
|
||||
### "Token estimate seems off"
|
||||
|
||||
**Cause**: The estimate uses chars/4 as a rough proxy for GPT-style tokens. Claude's tokenizer may differ slightly.
|
||||
|
||||
**Fix**: Focus on relative numbers and thresholds rather than absolute token counts. The 8K always-on budget is a heuristic, not a hard limit.
|
||||
|
||||
### "Score is low but Claude seems to work fine"
|
||||
|
||||
**Cause**: Claude works without context engineering — the score reflects optimization, not basic functionality.
|
||||
|
||||
**Fix**: A low score means you're leaving productivity on the table. Each dimension gap adds cognitive overhead per session.
|
||||
|
||||
### "Broken import flagged but file exists"
|
||||
|
||||
**Cause**: Relative path resolution differs from Claude's actual working directory at startup.
|
||||
|
||||
**Fix**: Use absolute paths (`~/.claude/file.md`) for global imports. Use project-relative paths (`./docs/conventions.md`) for project imports.
|
||||
|
||||
### "Profile-readiness flagged but I'm solo"
|
||||
|
||||
**Cause**: The audit checks for team-scalability patterns regardless of team size.
|
||||
|
||||
**Fix**: Profile-based assembly still benefits solo developers when switching contexts (reviewing PRs vs writing features vs debugging). It is optional for solo use.
|
||||
|
||||
---
|
||||
|
||||
## 9. Related Resources
|
||||
|
||||
- [The Ultimate Claude Code Guide](../guide/ultimate-guide.md) - Full reference
|
||||
- [Audit Your Claude Code Setup](./audit-prompt.md) - Full configuration audit (agents, hooks, MCP, CI)
|
||||
- [Cheatsheet](../guide/cheatsheet.md) - Quick daily reference
|
||||
- [Claude Code Official Docs](https://docs.anthropic.com/en/docs/claude-code) - Anthropic documentation
|
||||
|
||||
---
|
||||
|
||||
*Last updated: March 2026 | Version 1.0*
|
||||
Loading…
Add table
Add a link
Reference in a new issue