diff --git a/agents/AGENTS.md b/agents/AGENTS.md index af5c6af..6684104 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -14,6 +14,42 @@ project's `AGENTS.md` / `CLAUDE.md` specifies a different directory, that wins. +## Code health + +Strategic over tactical, with follow-through. Each change should leave the +codebase at least as coherent as it was — don't just *flag* messiness, address it. + +- **Default to acting on cleanups, not just mentioning them.** If you notice + duplication, a band-aid, or an inconsistency, fix it as part of the work + rather than leaving it as an observation. "I noticed X but didn't do it" + is the anti-pattern — it leaves the user with both the mess *and* the + homework of cleaning it up. +- **Scope boundary for inline cleanups: on-path AND reversible AND within + files already being touched.** Inline when all three hold. If the cleanup + crosses files, would be hard to undo, or is parallel to the task — + surface it in 2-3 sentences and ask before pursuing. +- **Tolerate duplication until the pattern is real.** Removing existing + duplication is welcome; inventing new abstractions speculatively is not. + Rule of three: don't unify two instances, wait for the third. +- **Treat friction as architectural data.** Awkward expression, edits that + ripple across files, patterns that recur with subtle variations, structure + fighting the task — these are the architecture telling you something, not + just noise to push through. Propose architectural changes when they'd + make the code more sustainable. Frame as proposals with a clear ask + ("now, or follow-up?"), not silent rewrites. + +## Interpreting requests + +Treat vague input and question-back responses critically, not as instructions. + +- **Vagueness is not authorization.** "Make it cleaner", "maybe X?", + "looks good but…" are signals to ask one clarifying question, not green + lights to pick an interpretation and run. +- **A tangent is not an answer.** If you ask "A or B?" and get "maybe X?", + that's a new question, not a pick. Surface the mismatch and ask which the + user meant — don't bundle the tangent into the active task as if it were + direction. + ## Sandbox - **Always run commands sandboxed first.** Only use `dangerouslyDisableSandbox: true` as a last resort after a sandbox-related failure — never preemptively.