---
title: "Architecture playbook · Agent Wranglers"
url: https://agentwranglers.se/playbook/architecture
updated: 2026-10-20
licence: "All rights reserved"
---

# Clean code and architecture playbook

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

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](https://agentwranglers.se/playbook/testing) 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](https://agentwranglers.se/playbook/architecture/code-review) 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.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers architecture playbook: https://agentwranglers.se/playbook/architecture`.

## Chapters

1. [Code review](https://agentwranglers.se/playbook/architecture/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. (8 required, 2 recommended)
2. [Names and functions](https://agentwranglers.se/playbook/architecture/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. (6 required, 2 recommended)
3. [Comments](https://agentwranglers.se/playbook/architecture/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. (2 required, 5 recommended)
4. [Errors and nulls](https://agentwranglers.se/playbook/architecture/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. (7 required, 1 recommended)
5. [Coupling](https://agentwranglers.se/playbook/architecture/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. (3 required, 2 recommended)
6. [SOLID and DRY](https://agentwranglers.se/playbook/architecture/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. (4 required, 4 recommended)
7. [Data shapes](https://agentwranglers.se/playbook/architecture/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. (7 required, 3 recommended)
8. [Dead code](https://agentwranglers.se/playbook/architecture/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. (4 required)
9. [Structure](https://agentwranglers.se/playbook/architecture/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. (3 required, 2 recommended)

See all 65 rules on one page in the [checklist](https://agentwranglers.se/playbook/architecture/checklist).