From 40aa7b46e274739f672ee5fff719979eaf047a32 Mon Sep 17 00:00:00 2001 From: jdalton Date: Wed, 1 Apr 2026 10:13:30 -0400 Subject: [PATCH] chore: add agent protocol sections to CLAUDE.md --- CLAUDE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index c91c27a7b..63a98d39c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -424,6 +424,29 @@ Socket CLI integrates with various third-party tools and services: - **Formatting**: Uses Oxfmt for code formatting with 2-space indentation - **Line length**: Target 80 character line width where practical +### 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 + +### Context Awareness +- 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 + --- ## Quality Standards