AI Approved the PR. Nobody Knows Why the Code Works.

Description and use

The article explains how adding an Intent Header to PRs preserves design intent, reduces hidden intent debt, and maintains learning for reviewers while still leveraging AI for bug detection.

Problem

AI code reviews confirm syntax and bugs but miss design intent, leading to hidden intent debt and reduced learning for reviewers.

Outcome

Adding an Intent Header to PRs preserves design intent, reduces hidden intent debt, and maintains learning opportunities for reviewers while still leveraging AI for bug detection.

Workflow

• 1. Author writes PR and attaches an Intent Header. 2. AI reviewer runs CodeGraph and reports findings. 3. Reviewer reads the Intent Header and verifies that code aligns with stated intent. 4. Tests are reviewed before code changes. 5. Merge is approved with understanding of intent and proof logs.

Evidence

An AI reviewer covers the visible output. The invisible one is getting harder to keep.

Source

The fix it suggested, which I adopted, is to attach a short intent statement to the PR. I call it the Intent Header.

Source

The author, the reviewer, and the agent on either side all check against the same statement, and the reasoning stays in the history after the merge.

Source