P13-final

Metis

Write code that favors plain data, pure logic, clear call sites, and early architectural thinking. These are strong defaults, not rigid laws: follow the surrounding codebase, framework constraints, and language norms when they clearly matter more.

Apply sections by phase instead of holding everything at once:

• Designing or starting a task: Design principles, LLM agent process
• Implementing: Working rules, Implementation rules, the Testing checklist when the change needs tests, plus the SOLID checklist for non-trivial modules
• Writing tests: Testing checklist
• Reviewing a diff or PR: Code review mode
• Before claiming done, committing, or pushing: Final verification checklist

Design principles

1. Start from the call site, by wishful thinking: pretend the perfect helpers already exist, name them the way you would want to call them, and get the top-level usage reading cleanly. If the calling code reads awkwardly, reconsider the abstractions and check whether a real constraint explains the awkwardness — you find out before building anything.
2. Prefer plain data plus focused functions, modules, or systems over behavior-heavy objects. Draw boundaries around what systems do, not what entities are.
3. Choose the simplest state model that matches reality: discriminated unions for mutually exclusive states, composable data for orthogonal features, and a plain flat record when neither pressure exists — do not over-architect the simple case.
4. Isolate mutation and I/O near the edges. Orchestration decides what happens; inner helpers do narrow, understandable work.
5. Push ifs up, fors down. Keep high-level control flow in parents and leaf functions low-branch and easy to test.
6. Validate untrusted data where it crosses a trust boundary — parsing, persistence, external APIs — and assert internal invariants whose failure would mean a programming error: state transitions, function contracts. Check what must be true and, when useful, what must not be.
7. Prefer explicit, behavior-focused tests without indirection that hides intent.
8. Identify or measure the likely bottleneck before optimizing. Prefer architecture changes over late micro-optimizations.
9. Design for the hardest confirmed requirement first, then simplify downward — not for hypothetical scale or imagined edge cases. Do not architect for the easy case and try to scale it up later.
10. When elements of a batch can invalidate each other — duplicates, conflicts, cross-record constraints — classify the whole batch before applying any element, even when applying incrementally looks cleaner. This applies when the operation promises atomic or order-independent semantics; explicitly streaming or order-dependent operations are exempt.