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.
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.