| 1 | # AGENTS.md |
| 2 | |
| 3 | Keep this file short and behavioral. |
| 4 | Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`. |
| 5 | |
| 6 | ## Development Principles |
| 7 | |
| 8 | - Minimizing concepts, duplication, and ceremony. |
| 9 | - Prefer a single stable contract with one real owner. |
| 10 | - Prefer local simplicity over premature or speculative abstraction. |
| 11 | - Add indirection only when it removes real coupling or protects a real boundary. |
| 12 | - Tests should protect real stable contracts and invariants, not drive the spec or exist only for regression prevention. |
| 13 | |
| 14 | ## Project Principles |
| 15 | |
| 16 | - When caller and callee are both local and no real boundary exists, change both directly; do not preserve local call shapes. |
| 17 | - If a field, method, wrapper, or abstraction has no clear, current use and does not protect a real boundary, remove it immediately. |
| 18 | - No wrapper functions or helpers unless they remove real coupling or protect a real boundary. |
| 19 | - Prefer direct code over layers, facades, and indirection. |
| 20 | - Prefer flattening and merging nearby responsibilities over splitting by default. |
| 21 | - Remove dead fields, methods, config, and stale state while touching nearby code. |
| 22 | - Do not duplicate normalization, validation, or defaulting logic; keep it in a single real owner. |
| 23 | - Keep shared stateless transforms in `utils/`; keep stateful and domain-shaped logic with the real owner. |
| 24 | - Keep stable shared contracts, constants, and public paths in `types/`, not in runtime or helpers. |
| 25 | - Resolve complexity in the lowest coherent owner and expose only the minimum surface upward. |
| 26 | - Shared runtime logic must live in one real owner and be reused, not mirrored. |
| 27 | |
| 28 | ## Verification |
| 29 | |
| 30 | - CI commands: `make vet`, `make lint`, `make test`, `make vuln`. |
| 31 | - `make tidy` is local maintenance, not a CI requirement. |
| 32 | - Run tests only when explicitly requested. |
| 33 | - If verification seems necessary, ask before running it. |