How to Verify AI-Generated Code: Checklist

Why a green summary is not enough

Code from an agent tends to look finished. It compiles, it reads well, and the agent says the tests pass. None of that shows which checks ran, or whether they touched the lines that changed. The steps below work with any agent and any stack.

The checklist

1. Name the change: List what changed by kind: source, tests, configuration, schema, dependencies, docs. Each kind owes different proof.
2. Set the proof first: Decide which checks this change owes before you read any result, so a passing check you happened to run cannot stand in for the one you needed.
3. Confirm each check ran: Look for real output from each check. Silence is not a pass, and a missing tool is a skip, not a success.
4. Test the tests: Break the changed line on purpose and run the tests again. If nothing fails, nothing tested that line.
5. Read tests the agent edited: Deleted cases, loosened assertions and new skips can turn a failure green. Treat any edit to a test as part of the change.
6. Check every new name: Confirm each new import, package and API exists and is one you meant to add. Agents can invent names that look right.
7. Compare the diff to the ask: Unrelated edits, new dependencies and broad refactors are the reviewer's first questions, even when every check is green.
8. Look for secrets and private paths: Scan the diff for keys, tokens and machine paths before it leaves your branch.
9. Keep the evidence: Save what ran, on which commit, and the verdict. A later reader should not need to take anyone's word for it.
10. Refuse at the boundary: Put the rule where work lands, in a commit hook and in CI, so it holds for every agent and every person.

What Headron automates

Steps 1 and 2: atlas.yaml lists the checks each kind of file owes. headron gate <file> prints them.
Step 3: Gates report PASS, FAIL or NOT RUN, and a missing tool is SKIP, kept out of the pass count.
Step 9: headron verify --receipt <file> saves a receipt of the run, and headron mind --receipts retrieves them.
Step 10: headron init wires your agents, and a reusable workflow gives CI the same verdict.
Still yours: Steps 4 to 8 are judgement. Declare the checks you can in the contract, and keep a person reading the diff for the rest.

uv tool install headron-software && headron doctor
cd your-repo && headron init
headron verify

Questions

Can I trust AI-generated code if the tests pass?

Only if those tests ran and exercised the change. Break the changed line on purpose and run them again: if they still pass, they did not test it.

How do I review AI-generated code at scale?

Move what a machine can decide into checks that run for every change, so people spend their reading time on intent, design and risk rather than on whether the tests ran.

Should a person still review AI-generated code?

Yes, for anything that matters. Checks can show what ran and what passed. They cannot tell you whether the change was the right thing to build.

What is the most common mistake when verifying AI code?

Accepting the agent's report as the evidence. The agent that wrote the change is the least independent source on whether it works, so the proof should come from a check that left a record.

Related guides

Start

Run the free, MIT-licensed verifier or connect through MCP. Mind API adds hosted planning for agents and chats through your Headron account.

Read the docs Mind API reference Create an account Star on GitHub

How to verify AI-generated code