The agent wrote the code. The tests are green. The linter is clean. You can't explain what changed.

Description and use

When developers rely on AI agents, they can lose code understanding within a month, even if the code passes all automated checks. Implementing a comprehension check and allocating time for architectural maintenance preserves the ability to debug and evolve the codebase.

Problem

When developers rely on AI agents to write code, they can lose the mental model of the code within a month, leading to a situation where the code passes all automated checks but the author cannot explain its intent or debug it when issues arise.

Outcome

Implementing a comprehension check and dedicating time for mental model maintenance prevents the loss of understanding that can occur after a month of agent-driven development, ensuring developers can still debug and evolve the codebase.

Workflow

• 1. Review every line of the agent-generated diff initially.
• 2. Within a week, skim the diff and rely on the agent’s summary.
• 3. Approve based on green tests and auto-LGTM after two weeks.
• 4. After a month, developers cannot explain the code’s intent during reviews.
• 5. When the agent fails to fix a bug, developers cannot step in due to lack of understanding.
• 6. Implement a comprehension check: close the diff, write a brief explanation of what changed, why, and what breaks if reverted.
• 7. If explanation fails, set a breakpoint, observe variables and call stack, and try again.
• 8. If still unclear, do not merge the PR.
• 9. Allocate one day a week for architecture review and mental model maintenance.

Evidence

Two independent custdevs reported the same timeline: a month of agent-driven development, and the developer can no longer explain the code they are shipping.

Source

Compilation, green tests, and auto-LGTM — the three signals most pipelines use to accept a change — can all pass on code nobody understands.

Source

If you can close the diff, describe what changed, why it changed, and what breaks if it reverts — you own the change. If you can’t, the diff owns you.

Source