metis

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, 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, the abstractions are wrong — and 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. Core domain state gets a named, typed shape — a dataclass, struct, or union — while raw dicts and strings stay at the boundary, not in the core.
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. Parse, don't validate: at each trust boundary — parsing, persistence, external APIs — convert untrusted data once into a typed shape that cannot represent the invalid states, so downstream code never re-checks it. Past the boundary, assert internal invariants whose failure means a programming error: state transitions, function contracts, positive and negative space.
7. Prefer explicit, behavior-focused tests without indirection that hides intent.
8. Sanity-check the likely bottleneck first — network, disk, memory, then CPU. Prefer architecture changes over late micro-optimizations.
9. Design for the hardest real requirement first, then simplify downward. 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.
11. Define errors out of existence: when a contract choice can make a failure case impossible — an operation that is naturally idempotent, a range that clamps, a delete that succeeds when the target is already gone — prefer it over raising and forcing every caller to handle the case.
12. A side effect that crosses a boundary — a send, a charge, a write — needs a stable identity (idempotency key, dedupe token) that its owner atomically deduplicates, so retries and replays are safe.