How to Review Assistant Changes Before You Hit Commit

Your assistant just finished. Forty files touched, tests green, a tidy summary in the terminal. The temptation is to skim the diff, nod, and commit. A week later you find a retry loop that was silently removed, a new dependency nobody chose, and a config value that only works on your machine.

Reading code you did not write is a skill. Reading code an assistant wrote fast, across many files, while you were half-watching, is a different one. To review assistant changes properly you need more than a diff viewer: you need the instructions the assistant was working from, the conversation that produced the code, and a rule for when a change is big enough to write down.

This guide gives you a repeatable review pass. It works with plain files and any assistant — Claude Code, Codex, Cursor or another agent. You will get the questions to ask of a diff, what to look for in a session transcript, a checklist to run before committing, and a way to decide when a change deserves a decision record instead of a quiet merge.

Why "just read the diff" is not enough

A diff tells you what the code says now. It does not tell you three things you need.

It does not show what was removed on purpose versus by accident. An assistant asked to "clean up the order service" will happily delete the guard clause that exists because of one bad Friday in March. The deletion looks like tidying. In a 600-line diff, it reads as noise.

It does not show the alternatives. The assistant may have considered three approaches and picked one for a reason you would disagree with. The diff shows only the winner. If the reasoning stays in a closed terminal window, you review the result without the argument.

It does not show what the assistant believed. Agents work from assumptions: that a field is nullable, that a job runs hourly, that an endpoint is internal. A wrong assumption produces code that passes review and fails in production. The assumption is stated in the conversation, not in the code.

There is also a volume problem. Human pull requests grow roughly as fast as a human can type. Assistant changes do not. A twenty-minute session can produce more diff than you would normally read in a day, and attention degrades long before the diff ends. The fix is not to read harder. It is to read in a different order.

Check the change against the instructions it followed

Start with the rules, not the code. Open your CLAUDE.md or AGENTS.md next to the diff and read the diff as an answer to those instructions.

This turns a vague "does this look right?" into a set of concrete yes/no questions. If your instruction file says:

## Conventions
- Use the existing `Result` type for fallible functions; do not throw.
- Database access goes through `src/db/queries.ts`. No inline SQL elsewhere.
- New dependencies need a note in `.prjcontext/memory/decisions.md`.
- Run `pnpm test && pnpm lint` before proposing a change.

then your first review pass is four searches, not a careful read:

git diff --stat                      # where did it touch?
git diff | grep -n "throw "          # rule 1
git diff --name-only | grep -v "db/" # rule 2 candidates
git diff package.json                # rule 3

Two useful outcomes come out of this pass. Either the change broke a rule, and you know exactly what to fix. Or the change broke a rule that turns out to be wrong or out of date — which is a signal that your instruction file needs an edit, not that the assistant misbehaved. Reviews are the main way instruction files stay honest. If you find yourself waving through the same violation three times, delete the rule.

A rule the assistant cannot verify is a rule it will drift away from. If a convention keeps getting missed, make it mechanical: a lint rule, a test, a CI check. See writing project instructions your assistant follows for how to phrase rules so they survive contact with a long session.

Read the session, not only the final code

The conversation is the design document you did not have to write. It is where the assumptions live.

You do not need to reread the whole thing. Scan for five kinds of moment:

• Assumptions stated as fact. "Since user.email is always set…" — is it? This single line explains more production bugs than any other.
• The point where you changed your mind. If you said "actually, do it the other way", the earlier attempt may still be half-present in the code. Partial reversals leave orphans: unused helpers, dead branches, an import nobody needs.
• Rejected options. "We could use a queue here, but polling is simpler for now." That is the sentence your future self will want in six months. It is also the sentence a fresh session will contradict next week unless you record it.
• Things the assistant flagged and you skipped. "Note: this will need a migration" is easy to scroll past at 6pm.
• Scope creep. Compare the first message to the final state. A session that started as "fix the timezone bug" and ended with a refactored date module is not necessarily wrong, but it is a different change than you approved.

A practical habit: before you close the terminal, ask the assistant for a short review brief — what it changed, what it assumed, what it was unsure about, and anything it touched outside the original request. Paste that into the pull request or keep it beside the session. It costs thirty seconds and gives the next reader a map.

Not every session is worth keeping, but the ones behind a non-obvious change usually are. Which AI coding sessions are worth keeping covers how to pick and trim them.

A short checklist to review assistant changes before you commit

Run this in order. It is deliberately front-loaded: the cheap, high-yield checks come first, so you catch the common failures before your attention runs out.

1. Scope. Does the diff touch only what the task needed? List the files. Anything surprising gets explained or reverted.
2. Secrets and local paths. Grep the diff for sk-, token, password, Bearer, /home/, /Users/. Assistants paste example values from conversation into code and config. See keeping secrets out of your AI context.
3. Deletions. Read the removed lines separately: git diff -U0 | grep "^-". Removals are where the quiet damage hides.
4. Dependencies. Any new package is a decision. Check the lockfile diff, not just package.json.
5. Rules. Walk the diff against CLAUDE.md / AGENTS.md as above.
6. Tests. Did the assistant add tests, or adjust existing tests so they pass? Changed assertions in an untouched test file deserve a hard look.
7. Error paths. Happy-path code is what assistants produce best. Read the catch blocks, the empty-list case, the timeout.
8. Run it. Not the tests — the thing. Start the app, hit the endpoint, click the button.
9. Reasoning. Can you explain, out loud, why each non-obvious change is the way it is? If not, either read the session or ask before committing.

Then commit in pieces. One large "implement feature X" commit made by an assistant is nearly impossible to bisect later. Splitting the work into three or four commits with real messages costs you five minutes now and saves an afternoon the day something breaks.

When a change deserves a decision record

Most changes need no record. Some need one badly, and the moment to notice is during review, while the reasons are still in your head.

Write a decision record when the change meets any of these:

The test is simple: if a fresh session, given only your code and your instruction file, would suggest undoing this change — write it down. Otherwise you will have the same argument with your assistant every month.

Keep it short. Four lines is a complete record:

### 2026-09-24 — Poll the notifier instead of queueing
Decision: The notifier polls every 30s; no message queue.
Why: One process, low volume. A queue adds a service to operate.
Revisit: If notification volume passes a few hundred per minute.

Lightweight decision records for AI-assisted projects has longer templates and where to store them.

Reviewing a change from someone else's session

Reviewing your own assistant's work is hard. Reviewing a teammate's is harder, because you have neither the code context nor the conversation.

Ask for three things with the change, and offer the same three when you are the author:

• The prompt or the goal. What was actually requested, in one sentence.
• The assumptions. What the assistant believed about the system.
• What was not done. Deferred work, known gaps, the migration that still needs writing.

If the session is available, read the first and last ten messages before opening the diff. The beginning tells you the intent; the end tells you what state the work was left in. Everything between is usually detail you can skip unless something in the diff surprises you.

A team norm worth adopting: assistant-authored changes get the same review as human-authored changes, and the author is the person who ran the session — not the tool. "The assistant wrote it" is not a review comment. Sharing AI coding context with your team covers how to pass this material around without leaking things that should stay local.

What a review habit saves you later

The immediate payoff is fewer bad merges. The larger one shows up over months.

Every review that ends in a small written artifact — a tightened rule in AGENTS.md, a four-line decision record, a saved session — makes the next session start better informed. The assistant stops re-proposing the approach you rejected, because the rejection is now a file it reads. Your instruction file gets sharper because reviews keep testing it against reality. Onboarding gets shorter, because the reasoning behind odd-looking code is written down next to the code.

Review is where context gets created. If you treat it as a gate to pass, you get nothing but merged code. If you treat it as fifteen minutes of writing things down, the project gets easier to work on every week.

How PrjLab handles this

We built PrjLab so the material a review needs lives beside the code. A repository holds your files plus three kinds of context with explicit types: .prjcontext/instructions/ for project instructions (CLAUDE.md and AGENTS.md at the project root are recognised too), .prjcontext/memory/ for decisions and notes, and .prjcontext/sessions/ for the conversations you chose to keep — so the rules a change was judged against and the session that produced it are one place, not three.

Every prj push creates an immutable version you can open in the browser, with a list of changes and a line diff between versions. That gives you a stable thing to point at in review: "the version where we switched to polling", with its decision record and session in the same snapshot. Run prj status first to see exactly what would be captured; the CLI skips .env files, key files, credential folders and anything in .gitignore or .prjignore, though it is a safety net rather than a complete secret scanner, so the review step is still yours.

Share a repository by handle as a reader or a writer when a teammate needs to review the change with its context, or prj clone it onto another machine. PrjLab sits beside git — git keeps your code history, PrjLab keeps the context around it. The getting-started guide walks through the first push.

Frequently asked questions

Should I review assistant-generated code more strictly than my own?

Not more strictly — differently. The failure modes are different: assistants rarely make syntax mistakes and often make scope, assumption and deletion mistakes. Weight your attention toward removed lines, error paths, new dependencies and anything outside the original request.

Do I need to read the whole session transcript?

No. Read the first few messages for intent and the last few for final state, then search the middle only when the diff surprises you. If the session is worth keeping at all, trim it to the parts that explain a decision before you save it.

What if the assistant broke a rule in CLAUDE.md that I no longer agree with?

Fix the file, not the code. An instruction you keep overriding is a stale instruction, and leaving it in place teaches you to ignore violations — which is exactly when the ones that matter slip past.

How small should commits be when an assistant did the work?

Small enough that each commit message is one honest sentence. If you need "and" twice, split it. This matters more with assistant work because the change was produced faster than your understanding of it.

If you want the instructions, decisions and sessions behind a change to travel with the code, start with the getting-started guide.