Architecture checklist

Every rule in the architecture playbook, by chapter, required rules first. Each links to its own page with how we built it and how to check it.

Code review

• Required Review the whole change against its base
• Required Check that it solves a named problem
• Required Keep it simple to maintain
• Required Name the principle and the fix in every finding
• Required Stay consistent with the codebase
• Required Write code that agents can parse
• Required Answer every question by number
• Required Verify every finding from scratch
• Recommended Prefer the patterns the industry knows
• Recommended Report problems beyond the diff

Names and functions

• Required Name things for what they mean
• Required Never let a name mislead
• Required Keep functions short
• Required Keep nesting shallow
• Required Pass few arguments
• Required Make each function do one thing
• Recommended Use names you can search for and say aloud
• Recommended Split blocks into named functions

Comments

• Required Refactor clever code instead of explaining it
• Required Delete commented-out code
• Recommended Let the code explain itself
• Recommended Keep change history out of comments
• Recommended Say why, not what
• Recommended Keep docblocks only for what types cannot say
• Recommended Link every TODO to a ticket

Errors and nulls

• Required Throw exceptions instead of returning error codes
• Required Never return null
• Required Never pass null into a function
• Required Make fields required unless absence is valid
• Required Never swallow errors
• Required Release every resource you open
• Required Await every async call
• Recommended Use typed domain exceptions

Coupling

• Required Talk only to your direct neighbours
• Required Make the order of calls impossible to get wrong
• Required Pass state in instead of sharing globals
• Recommended Tell objects what to do
• Recommended Keep internals private

SOLID and DRY

• Required Keep each piece of knowledge in one place
• Required Give each module one reason to change
• Required Keep the contract in every subtype
• Required Build only what is needed now
• Recommended Extend code without editing it
• Recommended Prefer composition over inheritance
• Recommended Keep interfaces small
• Recommended Depend on abstractions at the edges

Data shapes

• Required Use typed objects instead of loose arrays
• Required Never type anything as mixed or any
• Required Convert to arrays and JSON only at the edge
• Required Parse input once at the boundary
• Required Use enums instead of magic strings
• Required Give each function one return type
• Required Insert text literally when you replace
• Recommended Wrap domain values in their own types
• Recommended Make data objects immutable
• Recommended Model each state as its own type

Dead code

• Required Delete code that nothing uses
• Required Remove flags that never change
• Required Remove unused dependencies
• Required Delete tests with their feature

Structure

• Required Point dependencies inward
• Required Allow no dependency cycles
• Required Format all code with one tool
• Recommended Group code by feature
• Recommended Name files after what they hold