Delivery Playbook · Craft
Code review
What happens between a change being written and being merged, and what a reviewer actually checks.
Owner: CTO · Last reviewed: · Next review: 28 April 2027
Our rule is that every change is reviewed by a person who understands it before it merges. This page shows what that review is, so the rule is more than a promise. It is Gate 2, Ready to merge, in our quality gates.
What our rules require
- At least two team members approve a pull request before it is merged, and one of them is senior
- "Code reviewed" is part of the definition of done for every development task and bug
- Unit tests must pass and a QC tester must verify the function before the work is done
- The Tech Lead confirms that code reviews are complete before a release
- Engineers look for security problems and project risks while they review, as well as while they write
What a reviewer checks
| Question | What the reviewer looks for |
|---|---|
| Does it do what was asked? | The change meets the acceptance criteria of the story, and nothing more |
| Is it small enough to understand? | A change that cannot be read in one sitting is sent back to be split |
| Are the tests honest? | Tests fail when the code is wrong. Tests that only repeat the code are not accepted |
| Is it safe? | No secrets in code, inputs are checked, new dependencies are justified |
| Can the next person change it? | Clear names, no needless complexity, consistent with the agreed design |
| Can the author explain it? | If the author cannot say why it works, it is not ready, whoever or whatever wrote it |
What the author does first
- Keeps the change small and linked to one story
- Writes a short description of what changed, why, and how it was tested
- States whether AI helped write it, and which parts the author checked most closely
- Runs the tests and checks before asking for review
How to write a good review comment
- Say what you see and why it matters, not only what to change
- Separate must-fix from suggestions
- Ask a question when you are unsure, instead of assuming a mistake
- Be kind to the person and strict with the code
For changes where AI wrote some or all of the code, the same review applies, with extra attention described in how an engineer reads AI-written code.
Related
Craft
How an engineer reads AI-written code
The extra care we take with code that an AI tool wrote, and why the engineer stays responsible for it.
Craft
Testing
The kinds of testing we do, who does each, and how defects are reported and closed.
Quality & AI
Quality gates
Four gates a change passes between idea and production, and what each one checks.
