chore: anti-overengineer: streamline principles and mandates in AGENTS.md
cognitive committed
Apr 3, 2026 at 07:37 UTC
5a0baa96498e7135d481e3a4fa53b0c0222619b1
1 file changed
+22
-23
AGENTS.md
+22
-23
@@ -3,31 +3,30 @@
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 stable contracts and invariants, not drive the spec.
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.
6
+## Principles
7
+
8
+- Minimize concepts, duplication, and ceremony.
9
+- One real owner per contract. No mirroring, no wrappers unless they remove real coupling.
10
+- Local simplicity over speculative abstraction. Add indirection only when it removes real coupling or protects a real boundary.
11
+- When caller and callee are both local with no real boundary, change both directly.
12
+- Remove dead code, fields, config, and stale state while touching nearby code.
13
+
14
+## Go Mandates
15
+
16
+- Validate on construction. `NewX` functions reject invalid state; callers never receive a half-built value.
17
+- Fail fast with clear errors. Wrap with context; surface the root cause.
18
+- Zero external dependencies unless the alternative is re-implementing a non-trivial, correctness-critical algorithm. Justify in the commit message.
19
+- Interfaces express behavior, not taxonomy. One or two methods. If an interface has no consumer, delete it.
20
+
21
+## Testing
22
+
23
+- A test exists to catch real bugs. If deleting the test would not let a bug reach production, delete the test.
24
+- Test contracts and boundaries: protocol compliance, error semantics, security invariants, integration across real I/O.
25
+- Do not test configuration shapes, constructor output fields, or struct assembly — the type system and constructors already guarantee those.
26
+- Do not test that a function returns exactly what you passed in.
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.
32
+- Run targeted tests after contract-touching or risky edits. Ask before running the full suite.