How to review AI code you don't understand: check the design before code exists, then review the diff against stated intent.
To understand AI generated code before merging it, stop trying to understand it only at the diff. Approve the design first, while no code exists, then review the diff against a stated intent, a file list and tests you can read. A reviewer who knows what the change was supposed to do can check it. A reviewer who sees only 900 changed lines can only skim.
Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section near the end accordingly. Everything before it works with any agent and any editor.
The problem: you approved a change you only half understood
The pull request is green. The tests pass. The summary reads well. You scroll the diff, recognize the shape, and approve. Two weeks later a teammate asks why the retry logic lives in the serializer, and you realize you cannot answer, because you never knew it was there.
This is a gap between what ships and what any human holds in their head. A person who writes code line by line builds a mental model as a side effect. An agent skips that step, and the model never forms unless the reviewer builds it deliberately. Amazon CTO Werner Vogels, speaking at AWS re:Invent 2025 as quoted by The Register, put the cost this way: when the machine writes it, you will have to rebuild that comprehension during review. He called that verification debt.
Sources: The Register: devs and AI code (Jan 9, 2026)
The numbers on how often this goes unchecked are uncomfortable. Sonar's State of Code Developer Survey, reported by The Register in January 2026 and covering more than 1,100 developers, found that 96% do not believe AI-generated code is functionally correct, yet only 48% say they always check it before committing. Sonar sells code review and verification software, as The Register notes, so read the survey as a vendor's self-reported data, not an independent measurement.
Sources: The Register: devs and AI code (Jan 9, 2026)
The 2025 Stack Overflow Developer Survey shows the same texture from a different angle. Asked about frustrations with AI tools, 66% of respondents picked "AI solutions that are almost right, but not quite", the most-cited answer, and 45.2% picked "Debugging AI-generated code is more time-consuming". Almost right is the dangerous kind of wrong, because it survives a quick read.
Sources: Stack Overflow Developer Survey 2025, AI section
Why reading harder does not fix it
The usual advice is to review more carefully. Careful reading helps, but three things work against it. The diff is large. The author never held the design in mind, so no one can say why a given line exists. And a diff shows what changed, not what should have changed. Missing work and unrequested work are both invisible in a diff.
Two Hacker News commenters describe the same wall. In one thread about coding agents, a commenter wrote that if you are human-reviewing all the output of AI, you are going to hit the human comprehension bottleneck. Their own answer was clear specs, clear architecture and tests that agents enforce, which also moves the effort toward the design. In a separate thread about a code review tool, another commenter said most human review of AI code they see is rubber stamping at this point, because the volume is too big for humans to keep up. These are individual opinions, not measurements, but they name the pattern precisely.
Sources: Hacker News: Ask HN, is anybody producing good code with coding agents? (comment by kittomic), Hacker News: Show HN, Stage (comment by stackskipton)
Faster review is a separate topic, covered in Stop Your AI Agent Writing 1,000-Line PRs. This post asks a different question: what does a reviewer need in hand so the diff means something?
The fix: put the human decision before the code exists
Understanding is cheapest at the design. A half-page plan is quick to read and can be argued with. The same decision, discovered inside a 900-line diff, is slow to find and often never found. So move your judgment earlier and make the diff a verification step instead of a discovery step. The plan does not prove the code matches it, which is exactly why the diff stays: you check it against the plan instead of discovering the approach from it.
| Question | Review at the diff only | Approve the design first |
|---|---|---|
| What are you judging? | Code that already exists and is hard to unpick | A short plan, before anything is built |
| Cost of disagreeing | Rewrite, re-review, lost time | Edit a paragraph |
| What the reviewer holds in mind | Nothing, unless they rebuild it from the code | The intended approach and file list |
| How surprises show up | Buried in hundreds of lines | As a file or step the plan never mentioned |
| Likely outcome | Skim and approve | Check the diff against the plan |
Six practical steps
These steps are general practice, not research findings. The quotes from other developers are individual opinions, included to show the idea in use.
1. Ask for the plan and the file list before any edit
Before the agent writes code, ask for a short plan: the approach in plain language, the exact files it expects to touch, and the files it will deliberately leave alone. In Claude Code, plan mode (Shift+Tab, or claude --permission-mode plan) has Claude read files and write a plan without editing your source until you approve it (the Claude Code docs note that in interactive terminal sessions where bypass permissions is available, the blocks of plan mode are not enforced), and you can ask for the file list inside that plan. A usable plan fits on one screen: the goal in a sentence, the approach in three or four bullets, the files to change, the files to leave alone, and the tests that will prove it works. Read the file list first. If it names a module you did not expect, you found your surprise for free. Later, an edit outside that list is a signal, a topic covered in Why Claude Code Edits Files You Never Named.
Push back at this stage. Ask why this approach and not the simpler one. Ask what happens to existing callers. An answer that takes the agent one line to give is a decision you now understand, and one you made on purpose rather than inherited.
2. Require an intent summary on every change
Make the agent state, in a few sentences, what the change is for, what behavior is different afterward, and what it chose not to do. A commenter on the Show HN thread for Sphinx, a hook that quizzes you on your AI's code, described writing a quality PR description that separates why, what and how, and said the process often leads them to understand hidden decisions the LLM made and occasionally uncovers bugs. Treat that as one developer's practice, not proof. Note that this commenter writes the description themselves, and the understanding comes from the act of writing it. An agent-drafted summary that you read and correct is a weaker substitute, but writing the intent down still gives the reviewer something to compare the code against.
Sources: Hacker News: Show HN, Sphinx (comment by rDr4g0n)
3. Cut the work into small phases you can hold in your head
Understanding does not scale with diff size, so cap the diff. Ask for one phase at a time, each with its own purpose, and review each before the next starts. Four 200-line reviews you understand beat one 800-line review you skimmed. Another commenter in the Ask HN thread described the same preference, saying they do not let Claude Code run wild for a long time and leave a mess to review.
Sources: Hacker News: Ask HN, is anybody producing good code with coding agents? (comment by leros)
4. Read the tests before you read the code
Tests are the most readable specification in the repository. Test names and assertions state behavior in a form a human can scan in minutes. Read them first: do they describe what you asked for? Would they fail if the feature were broken? In general practice, tests written before the implementation make a stronger spec than tests written to match it, which is why test-first matters beyond quality. Be wary if the agent edited existing tests to get green, a failure mode covered in How to Stop Claude Code Changing Tests to Pass.
5. Run an "explain this change" check
Before approving, explain the change back, out loud or in the review comment, without scrolling. What does it do? Why this approach? What breaks if this function is wrong? If you cannot, you have found the part you do not understand. Ask the agent to walk through that part, then check its explanation against the code instead of trusting it.
Some developers automate a version of this. The Sphinx project, shown on Hacker News as an open source hook, throws a questionnaire at you before you push to production, to check that you understand the code you are pushing. Reactions in the thread were mixed: one commenter suggested gating the submit-PR step instead of the production push, and another wrote that they built this and got frustrated with being questioned, so they stopped using it. Whether a quiz suits your team is your call. The underlying idea, proving to yourself that you understand before you ship, stands either way.
Sources: Hacker News: Show HN, Sphinx
6. Know when not to merge
The step that saves the most pain is permission to stop. Do not merge when any of these is true:
- You cannot explain, in two sentences, what the change does and why it takes this approach.
- The diff touches files that were not in the agreed plan, and no one can say why.
- The tests were edited alongside the code they cover, or no test would fail if the feature broke.
- The change reaches auth, payments, data deletion or migrations, and you are reviewing it for the first time with no design on record.
- The agent's summary and the diff disagree.
- You are approving because the checks are green and the queue is long.
Merging code you do not understand is a loan. Sometimes it is a reasonable loan, for a prototype or a throwaway script. Take it knowingly, and never on code that handles money, identity or user data.
A short review checklist
- Did I approve a plan before the code was written?
- Does the changed file list match the planned file list?
- Can I state the intent in two sentences without looking?
- Do the tests describe the behavior I asked for?
- Is this phase small enough to hold in my head?
- Did I check anything the agent told me about its own work against the code?
One more caution from the same discussions: a commenter on the Stage thread said that if they are reviewing AI code, they do not want AI summaries, they want to read the code and understand what it does. That is a fair limit on step 2. A summary orients you, but it does not replace reading the risky parts. Use it to decide where to read closely.
Sources: Hacker News: Show HN, Stage (comment by dawnerd)
Design-first is also not waterfall. The plan is half a page and one conversation, not a document that freezes. If that worry sounds familiar, Is Spec-Driven Development Just Waterfall? takes it on directly. And a related failure, the agent reporting success on work that is not finished, is the subject of Claude Code Said It's Done. It Wasn't..
Where TLM Forge fits
TLM Forge sizes each task as Light, Medium or Deep. On Medium and Deep tasks it shows you a design for your sign-off before building, so your first review is of intent, not code. On Pro, a hook makes subagent launches and code edits wait for your reply to the design. After the build, a final review wave of independent reviewer agents checks the result, and a commit hook blocks git commit, git push and gh pr merge if code changed since that review.
The limit: this does not replace reading the diff. The reviewer agents are LLMs and can miss things, Light tasks get no design sign-off and no review agents, and the commit hook only matches the command text of those three commands and can be turned off with TLMFORGE_HOOKS=0. You still own the decision to merge.
Frequently asked questions
01How do I review AI code I don't understand?
Do not start at the diff. Ask the author or agent for the intent, the planned file list and the tests, then compare the diff against them. Explain the change back in your own words. If any part still does not make sense, have it walked through and check the explanation against the code before approving.
02What is comprehension debt in AI-generated code?
It is an informal term, not a measured standard, for the gap between the code a team ships and the code anyone understands. Writing by hand builds understanding as a side effect. With an agent, you must build it on purpose or the cost shows up later. Amazon CTO Werner Vogels called the related review cost verification debt.
03Is it okay to merge AI code I only partly understand?
For a prototype or throwaway script, it can be a reasonable risk if you take it knowingly. For anything touching authentication, payments, data deletion or migrations, no. If you cannot explain what the change does and why, hold the merge until you can.
04How can I make AI-generated pull requests easier to review?
Ask for a plan and file list before any code, require a short intent summary, and keep each change to one phase. Put tests first so reviewers can read behavior before implementation. Smaller diffs with a stated purpose let a reviewer check the code instead of reconstructing it.
05Should I trust an AI summary of its own code changes?
Use it to decide where to look, not as proof. A summary describes what the agent believes it did, which can differ from the diff. Check the claims that matter against the code, especially for risky areas, and read those parts directly.