Code review

Required

• Review the whole change against its base

  Required

  Review a branch as one solution, compared with the branch it will merge into. Never review only the changed lines.

• Check that it solves a named problem

  Required

  Every change must solve a problem someone can name, or add clear value to the codebase. Code without a reason is cost without return.

• Keep it simple to maintain

  Required

  Choose the simplest design that solves today's problem. A new developer or agent must understand a change without asking its author.

• Name the principle and the fix in every finding

  Required

  Every finding names the broken principle, the exact file and line, and a concrete fix. "This feels messy" is not a finding.

• Stay consistent with the codebase

  Required

  New code follows the patterns the codebase already uses for the same job. Two ways to do one thing doubles what every reader must learn.

• Write code that agents can parse

  Required

  Write code that people and AI agents can read in one pass, with clear names, small files, types and a predictable structure.

• Answer every question by number

  Required

  Answer every review question with its number, even when the answer is "no problems found". A skipped number counts as not reviewed.

• Verify every finding from scratch

  Required

  Check each finding again with a reviewer who starts fresh, such as a second person or a new AI agent. Drop findings that don't hold up.

Recommended

• Prefer the patterns the industry knows

  Recommended

  Solve common problems with the patterns and libraries most developers already know. Invent a new pattern only when the known ones fail.

• Report problems beyond the diff

  Recommended

  When the review finds other code that breaks the same rules, report it too, as a separate list.