Clean code and architecture playbook

A clean code and architecture playbook for any language. It covers code review, names, functions, comments, errors, coupling, SOLID design, data shapes, dead code and structure. The testing playbook covers how to test it.

Every rule has a check that a linter, a type checker or a test can run. Where no tool can decide, the code review chapter gives a numbered question to answer instead.

AI agents write code fast, and they copy what they see. Clean code gives them good patterns to copy, so every change keeps the codebase easy to read.

Chapters

1. Code review

   Review the whole change against its base with numbered questions. Name the principle, the code and the fix, then verify each finding from scratch.

   • Required 8
   • Recommended 2

2. Names and functions

   Names that say what things are, and small functions that each do one thing. Short, shallow and with few arguments, so anyone can read them at a glance.

   • Required 6
   • Recommended 2

3. Comments

   Let names and small functions carry the meaning. Keep a comment only for a reason the code cannot show, and let version control keep the history.

   • Required 2
   • Recommended 5

4. Errors and nulls

   Throw clear, typed errors instead of returning codes. Never return or pass null, and give every field a value unless absence is a valid state.

   • Required 7
   • Recommended 1

5. Coupling

   Let each module talk only to its direct neighbours. Make the order of calls impossible to get wrong, share no global state and hide the rest.

   • Required 3
   • Recommended 2

6. SOLID and DRY

   Keep each piece of knowledge in one place and give each module one reason to change. Extend code by adding to it, not editing it.

   • Required 4
   • Recommended 4

7. Data shapes

   Pass data as named, typed objects that say what they hold. Parse input once at the edge, and never hide types in mixed values, loose arrays or strings.

   • Required 7
   • Recommended 3

8. Dead code

   Delete code that nothing calls, flags that never change and packages nobody imports. Version control remembers it, so the codebase does not have to.

   • Required 4

9. Structure

   Arrange code so dependencies point one way, folders follow features, files are easy to find, and no module depends on itself through a loop.

   • Required 3
   • Recommended 2

All 65 rules on one page