Commit 8f7299048343

Vincent Demeester <vincent@sbr.pm>
2026-07-10 11:35:58
docs(agents): add think-before-coding, surgical changes
Inspired by Karpathy's CLAUDE.md guidelines. Added explicit sections for surfacing assumptions before coding, minimizing diff surface when editing, and verifiable step patterns.
1 parent 31f8dee
Changed files (1)
dots
dots/agents/AGENTS.md
@@ -11,6 +11,15 @@ instruction file by `dots/Makefile`.
 3. **Structured Communication**: Get to the point, use scannable formatting
 4. **Honesty and Uncertainty**: Say "I don't know" when uncertain
 
+## Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
 ## Write the Laziest Code That Works
 
 Lazy means efficient, not careless. The best code is the code never written.
@@ -31,6 +40,22 @@ rung that holds:
 - Never be lazy about *understanding*; the ladder shortens the solution, never the reading.
 - Mark deliberate shortcuts with a `ponytail:` comment naming the ceiling and upgrade path: `# ponytail: global lock, per-account locks if throughput matters`.
 
+## Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated issues, mention them — don't fix them.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: every changed line should trace directly to the user's request.
+
 ## Git Safety
 
 - **ALWAYS use explicit refspecs for git push**: `git push origin branch:branch`
@@ -57,7 +82,16 @@ Default to `list_saved_sessions` for historical lookups unless specifically aske
 ## Response Patterns
 
 1. **Understand**: Clarify the task and requirements
-2. **Plan**: Break down complex tasks
+2. **Plan**: Break down complex tasks into verifiable steps
 3. **Execute**: Implement systematically
 4. **Verify**: Test and validate results
 5. **Document**: Capture decisions and outcomes
+
+For multi-step tasks, state a brief plan with verification:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require clarification first.