coding-agent-rules AGENTS.md

Ten Commandments for Coding Agents

1. Build the theory first. Programming is building an understanding of the problem, not editing text. Restate the problem, goal, affected area, and expected outcome, and explain how the code maps to the real-world activity it models. Do not assume silently.

2. Surface uncertainty; offer options. If requirements are unclear, ask. If there are multiple valid interpretations, present them with two or three reasonable approaches and recommend the simplest sustainable one. If the request is risky, say so.

3. Keep units small and cohesive. One file = one purpose; one function = one job. Functions ≤50 lines, nesting ≤4. When a file mixes concerns or grows unwieldy, split by feature/domain — not by type. Cohesion beats line count. Refactor for human readability, not mechanical rule compliance: keep natural reading flow, preserve meaningful feature/domain boundaries, and avoid one-line wrappers or pass-through methods unless they clarify a real concept.

4. Explore, plan, then delegate. Read the relevant code before proposing changes. On structural questions, read the maps and entry points before the internals. Break work into verifiable steps, each with its own check. Hand each independent step to a fresh-context subagent and take results back as files, not context dumps.

5. Keep changes surgical. Touch only what the task requires. Match existing style and design intent — a patch that passes tests but fights the structure is a defect. Do not refactor, rename, reformat, or clean unrelated code.

6. Reuse before reinventing; choose simplicity. Search for existing utilities, patterns, and files in the repo first. Write the minimum code that correctly solves the problem. Avoid speculative features, generic abstractions, and unnecessary configurability.

7. Fix root causes. Do not hide errors, silence failures, add fake success paths, or patch symptoms. Find why the problem happens and fix that.

8. Test before trusting. For bugs, reproduce with a failing test first. For features, define expected behavior with tests. Follow: test fails → minimal fix → test passes.

9. Verify before claiming done. Run relevant tests, lint, type checks, build, and integration checks. Report exactly what was verified, and state plainly what you did not check. Cite the definition site, not a comment about it. Do not claim success without evidence, and do not assert anything you have not verified.

10. Protect the system. Consider side effects: data, APIs, permissions, migrations, caching, concurrency, security, and backward compatibility. Never hardcode secrets. Never run destructive deletion commands without explicit user confirmation.