| name | coding-standards |
| description | Enforce architecture-first coding standards. deep modules, orthogonality, seam placement, DRY, contracts, and interface-level testing. |
Coding Standards
Code according to these standards. Use the vocabulary in language.md — module, interface, depth, seam, adapter, leverage, locality — exactly. See deepening.md for deepening patterns and interface-design.md for interface exploration.
Core standards
1. Deep, not shallow
Make every module deep — high leverage behind a simple interface. Before writing code:
- What behaviour does the caller need? Minimise the interface to that.
- Run the deletion test: if you delete the module, does complexity vanish (pass-through) or reappear at N callers (earning its keep)?
- The interface is the test surface. Tests cross the same seam as callers.
- Use a directory to group multiple related files in 1 module
2. Orthogonality
Changes should be independent. Two concerns are orthogonal when modifying one requires no changes to the other.
- Isolate concepts so they change independently. If a single requirement change touches many files, orthogonality is broken.
- Separate what from how (validation from transformation from persistence).
- One responsibility per module. If you can't name it in one concept, it holds two.
3. Minimise coupling
Coupling is the enemy of orthogonality. Reduce it by:
- Putting seams where behaviour varies. Inject dependencies through seams.
- One adapter = hypothetical seam. Two adapters = real seam. Don't introduce a port unless something actually varies across it.
- Keep internal seams private. Don't expose implementation details through the interface.
4. DRY
Each piece of knowledge must have one representation. Duplication breeds inconsistency.
- Extract when the same logic, data shape, or invariant appears in two places.
- Prefer extraction that increases locality (change concentrates in one place).
- Don't extract just for extraction's sake — apply the deletion test.
5. Program deliberately
Every name and structure should carry meaning.
- Name things for the domain concept they represent, not the mechanism.
- If a name needs explanation, rename it. The name is the first and often only documentation.
- Don't assume — prove with tests.
6. Design by contract
Make invariants explicit. Fail fast.
- Validate inputs at seams. Bad data should not propagate.
- Use assertions for internal invariants that should never be violated.
- Document ordering, performance, and error modes as part of the interface.
7. Broken windows
Never ship sloppy code. Fix structural problems immediately or they multiply — refactor before building on messy foundations.
8. Ruthless testing
Code is only done when tests pass.
- Test at the interface (the seam). Tests survive internal refactors.
- When deepening replaces shallow modules, delete old tests on the old modules and write new tests at the new interface.
- Tests describe behaviour, not implementation.
Workflows
Writing new code
- Read language.md terminology. Read
<project-root>/.agent/CONTEXT.md for domain vocabulary.
- Identify the seam — where does a dependency vary?
- Define the interface (types, invariants, error modes, ordering).
- Verify depth: does the interface hide meaningful behaviour? Deletion test.
- Implement. Inject dependencies at seams.
- Test at the interface.
Refactoring
- Find friction — where does understanding one concept require bouncing through many modules?
- Classify dependencies (see deepening.md).
- Deepen the cluster: merge shallow modules, place the seam, inject adapters.
- Replace old tests with tests at the new interface.
Reviewing code
- Is the module deep? Or is the interface as complex as the implementation?
- Are concerns orthogonal? Or does one change require touching unrelated modules?
- Is coupling minimised? Are seams placed where things vary?
- Is anything duplicated that could be one source of truth?
- Does every name carry domain meaning?
- Are invariants enforced at the seams?
- Do tests sit at the interface, or are they leaking into implementation details?