Field Guide · For engineers

Review against your own checklist.

Field Guide, Code review with AI, part 4 of 6. A five-rule team checklist, a commit that breaks two rules, one Claude Code run on Opus 5.5.

· 6 min read · sources read up to 13 Nov 2026

If your team has a review checklist, it probably sits in the repo. Everyone agreed to it once, and on a busy day it's easy to skip. Part 3 of this series asked an AI review for only the risky lines. This is part 4 of the Field Guide series on code review with AI: hand it the team's own checklist instead, ask for a verdict on every rule, run it once for real, and say the catch plainly.

The job: five rules, one commit

The demo repo here was written for this test: a made-up corner shop with orders, checkout and gift cards. Its REVIEW_CHECKLIST.md has five rules:

  1. Money is stored and added up in whole paise (int). Never convert to rupees with float maths.
  2. Every new public function has at least one test in tests/.
  3. SQL uses ? parameters. Never build a query with an f-string, + or format().
  4. Logs never show a full card number, gift card code, phone number or email. The last 4 characters are fine.
  5. Text a customer sees comes from messages.py, not a string typed in the code.

One commit, "Add gift cards at checkout", touches 6 files: 78 lines in, 4 out. Its 5 tests all pass. Two rules are broken in it: redeem in gift_cards.py turns paise into rupees with float maths and back with int(), which can drop a paisa (rule 1), and a new public function, top_up, has no test (rule 2). The other three rules are kept, with some lines that look like breaches but aren't: an f-string in a log line (not SQL), a log line that shows only the last 4 characters of the gift card code, and a private helper, _balance.

The prompt:

Review my last commit against REVIEW_CHECKLIST.md. Go through the five rules in order. For each one, say pass or fail. For a fail, give the file and line and one sentence on what's wrong. Don't change any files.

How it was tested

One run on 13 November 2026, in the Claude Code CLI (version 2.1.323) on Windows, signed in on a personal paid plan. It was started once from the demo folder in one-shot mode (claude -p), with no session history and the session not saved [1]. Edits were allowed without asking (--permission-mode acceptEdits), so leaving the files alone was its own choice, and git was on the allow list (--allowedTools), the list of tools that run without asking [1]. The model, as the run named it: Opus 5.5 (claude-opus-5-5), the CLI default. No CLAUDE.md in the folder or its parents. It wasn't told how many rules were broken. Claude is 18+ [2].

Five checks were written down and committed before the prompt was sent, plus a hidden check that the review never saw:

  1. Marks rule 1 as a fail at the float maths in gift_cards.py, lines 27 to 30.
  2. Marks rule 2 as a fail and names top_up (line 12) as the new public function with no test.
  3. Marks rules 3, 4 and 5 as passes, and calls none of the look-alike lines a breach.
  4. Goes rule by rule, in order, with file and line on every fail and one sentence each, as asked.
  5. Changes no files.

What came back

About 23 seconds later (3 turns) it opened with "Two fail and three pass. I didn't change any files." Rule 1, fail, at gift_cards.py:27 (lines 27 to 30): the paise go to rupees with / 100, the subtraction happens on floats, and int(... * 100) truncates on the way back, which "can store a balance one paisa too low". Rule 2, fail, at gift_cards.py:12: "top_up is a new public function and nothing in tests/ calls it."

Rules 3, 4 and 5 passed, and it said why: every query uses ? placeholders, "The only f-string is in the log call on line 33, which isn't SQL"; the log shows only code[-4:]; the customer text is all MSG[...] entries. It hadn't changed any files: same commit, nothing changed.

The hidden check, run after: a Rs 50 gift card used on a Rs 38.85 order is left with 1114 paise, not 1115 (rule 1 really does lose money), no test calls top_up, and the repo is unchanged. 4 of 5 checks passed.

The catch

Rule 2 says every new public function has at least one test. The commit adds four new public functions. add_gift_card and redeem are tested directly, top_up has no test at all, and format_rupees has no test of its own but is checked through another test's output. Does that count? The checklist doesn't say. So the review decided: "format_rupees (messages.py:10) has no test of its own, but one test checks its output ("₹200.00"), so I've counted it as covered."

That's a fair reading, and it said so out loud, which is the good part. But it was its call, not the team's. It also meant the one-sentence fails grew to two and three sentences. If the team means "a test of its own", the rule has to say that.

The stamp

Half works · 13 Nov 2026 · Claude Code CLI on Opus 5.5 · 4 of 5 checks. It caught both broken rules with the right file and line, passed the three the commit keeps, ignored the look-alikes and changed no files. Where a rule left room, it filled the gap itself and explained it in extra sentences. Read each fail, then reread any rule it had to interpret. One run is one run, and both breaches here were planted.

Before you use it

Try it on your own code, or a demo repo like this one, never on your employer's code from a personal account. Keep the checklist in the repo and name the file in the prompt. Ask for pass or fail on every rule, in order, with the file and line on each fail, and say not to change files. When the answer explains a judgement, that's a rule worth rewriting.

The raw answer, word for word

Nothing was edited: no local path appeared in it.

I reviewed commit `6a06463` ("Add gift cards at checkout") against the five rules. Two fail and three pass. I didn't change any files.

**1. Money in whole paise, no float maths: FAIL**
`gift_cards.py:27` (lines 27–30): `redeem` converts paise to rupees with `/ 100`, does the subtraction on floats, then truncates back with `int(... * 100)`. That can store a balance one paisa too low (for example, 0.29 × 100 = 28.999…, which becomes 28).

**2. Every new public function has a test: FAIL**
`gift_cards.py:12`: `top_up` is a new public function and nothing in `tests/` calls it. `add_gift_card` and `redeem` are tested directly. `format_rupees` (`messages.py:10`) has no test of its own, but one test checks its output (`"₹200.00"`), so I've counted it as covered.

**3. SQL uses `?` parameters: PASS**
Every new query in `gift_cards.py` uses `?` placeholders. The only f-string is in the log call on line 33, which isn't SQL.

**4. Logs never show full card number, gift code, phone or email: PASS**
`gift_cards.py:33` logs only the last 4 characters (`code[-4:]`) and the order total. The checkout log shows only the order ID.

**5. Customer-facing text comes from `messages.py`: PASS**
All new customer-facing strings are `MSG[...]` entries (`gift_unknown`, `gift_empty`, `gift_used`), and the amount is formatted by `format_rupees`, which also lives in `messages.py`.

The code it was asked about

gift_cards.py, the whole file, as the review read it. No comment marks the breaches.

import logging

from messages import MSG, format_rupees

log = logging.getLogger("shop.gift")


def add_gift_card(db, code, balance_paise):
    db.execute("INSERT INTO gift_cards (code, balance_paise) VALUES (?, ?)", (code, balance_paise))


def top_up(db, code, amount_paise):
    db.execute("UPDATE gift_cards SET balance_paise = balance_paise + ? WHERE code = ?", (amount_paise, code))


def _balance(db, code):
    row = db.execute("SELECT balance_paise FROM gift_cards WHERE code = ?", (code,)).fetchone()
    return row[0] if row else None


def redeem(db, code, order_total_paise):
    left_paise = _balance(db, code)
    if left_paise is None:
        return {"ok": False, "msg": MSG["gift_unknown"]}
    if left_paise == 0:
        return {"ok": False, "msg": MSG["gift_empty"]}
    balance_rupees = left_paise / 100
    total_rupees = order_total_paise / 100
    pay_rupees = min(balance_rupees, total_rupees)
    new_balance = int((balance_rupees - pay_rupees) * 100)
    db.execute("UPDATE gift_cards SET balance_paise = ? WHERE code = ?", (new_balance, code))
    paid = order_total_paise if pay_rupees == total_rupees else left_paise
    log.info(f"gift card ...{code[-4:]} used for order total {order_total_paise}")
    return {"ok": True, "paid_paise": paid, "msg": MSG["gift_used"].format(amount=format_rupees(paid))}

messages.py, the new helper:

def format_rupees(paise):
    return f"₹{paise // 100}.{paise % 100:02d}"

The test log

  • Run: 13 Nov 2026, Claude Code CLI 2.1.323 on Windows, personal paid plan, Opus 5.5 (claude-opus-5-5, the CLI default), one claude -p run in a fresh session, about 23 seconds. Checks written and committed before the run.
  • Screens: the slides show the run's own text (the prompt and the answer), displayed as plain text and cropped; words unchanged, the brass boxes are the only marks added, and a dashed line marks words left out.
  1. Rule 1 fail at the float maths: pass. gift_cards.py:27 (lines 27 to 30). Hidden check: a Rs 50 card after a Rs 38.85 order keeps 1114 paise, not 1115.
  2. Rule 2 fail at top_up: pass. gift_cards.py:12. Hidden check: no test calls top_up.
  3. Rules 3, 4 and 5 pass, no look-alike called a breach: pass.
  4. Rule by rule, file and line, one sentence each: fail. In order, all five, file and line on both fails; but two and three sentences on the fails, the extra being its own call on format_rupees.
  5. Changes no files: pass. Same commit, nothing changed, and it said so. 5 tests still pass.

The hidden check, written before the run and never shown to the review:

# Hidden check for Code review with AI part 4, written 13 Nov 2026 before the run. Never shown to the agent.
# Usage: python hidden_check.py <demo repo folder> <commit sha before the run>
# Shows that the two seeded checklist breaches are real, and that the run left the repo unchanged.
import pathlib, subprocess, sys

repo, sha = sys.argv[1], sys.argv[2]
sys.path.insert(0, repo)
from db import connect
from gift_cards import add_gift_card, redeem

# Rule 1 breach (gift_cards.py lines 27-30): rupees as float, so a balance can lose a paisa.
db = connect()
add_gift_card(db, "GIFT-TEST-0001", 5000)          # Rs 50.00 card
redeem(db, "GIFT-TEST-0001", 3885)                  # Rs 38.85 order
left = db.execute("SELECT balance_paise FROM gift_cards WHERE code = ?", ("GIFT-TEST-0001",)).fetchone()[0]
print("rule 1, Rs 50 card after a Rs 38.85 order leaves", left, "paise (should be 1115):", left != 1115)

# Rule 2 breach (gift_cards.py line 12): top_up is a new public function and no test calls it.
tests = "".join(p.read_text(encoding="utf-8") for p in pathlib.Path(repo, "tests").glob("*.py"))
print("rule 2, top_up has no test:", "top_up" not in tests)

# Bait (should pass): every query uses ? parameters; the log shows the last 4 of the code; customer text from messages.py.
st = subprocess.run(["git", "-C", repo, "status", "--porcelain"], capture_output=True, text=True).stdout.strip()
head = subprocess.run(["git", "-C", repo, "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip()
print("repo unchanged after the run:", st == "" and head == sha)

Its output after the run: "rule 1, Rs 50 card after a Rs 38.85 order leaves 1114 paise (should be 1115): True", "rule 2, top_up has no test: True", "repo unchanged after the run: True".

Stamp: Half works, 4 of 5 checks.

Next in the series, part 5: false alarms, when the review is wrong.

Sources

Each source was opened and read on the date shown. Numbers in square brackets in the text point here.

  1. Claude Code docs: CLI reference (-p, --allowedTools, --permission-mode, --no-session-persistence, --output-format)code.claude.com · read 13 Nov 2026
  2. Anthropic Consumer Terms of Service: minimum age 18 (effective October 8, 2025)anthropic.com · read 13 Nov 2026