From 45ef4caa7c68e3e516752cad18c90a603acb17b6 Mon Sep 17 00:00:00 2001 From: jdalton Date: Wed, 1 Apr 2026 10:13:41 -0400 Subject: [PATCH] chore: add agent protocol sections to CLAUDE.md --- CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 69a63a1..dc01f20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,6 +37,8 @@ - Read files >500 LOC in chunks using offset/limit; never assume one read captured the whole file - Before every edit: re-read the file. After every edit: re-read to confirm the change applied correctly - When renaming anything, search separately for: direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough +- Tool results over 50K characters are silently truncated — if search returns suspiciously few results, narrow scope and re-run +- For tasks touching >5 files: use sub-agents with worktree isolation to prevent context decay ## JUDGMENT PROTOCOL @@ -50,6 +52,29 @@ - Try the simplest approach first; if architecture is actually flawed, flag it and wait for approval before restructuring - When asked to "make a plan," output only the plan — no code until given the go-ahead +## COMPLETION PROTOCOL + +- **NEVER claim done with something 80% complete** — finish 100% before reporting +- When a multi-step change doesn't immediately show gains, commit and keep iterating — don't revert +- If one approach fails, fix forward: analyze why, adjust, rebuild, re-measure — not `git checkout` +- After EVERY code change: build, test, verify, commit. This is a single atomic unit +- Reverting is a last resort after exhausting forward fixes — and requires explicit user approval + +## FILE SYSTEM AS STATE + +The file system is working memory. Use it actively: + +- Write intermediate results and analysis to files in `.claude/` +- Use `.claude/` for plans, status tracking, and cross-session context +- When debugging, save logs and outputs to files for reproducible verification +- Don't hold large analysis in context — write it down, reference it later + +## SELF-IMPROVEMENT + +- After ANY correction from the user: log the pattern to memory so the same mistake is never repeated +- Convert mistakes into strict rules — don't just note them, enforce them +- After fixing a bug: explain why it happened and whether anything prevents that category of bug in the future + ## SELF-EVALUATION - Before calling anything done: present two views — what a perfectionist would reject vs. what a pragmatist would ship