A diff shows what changed. Agent-written code also needs context, verification results, human decisions, and known limits.
A coding agent can touch four files, generate a large diff, run several commands, and still leave the reviewer with the same unanswered question:
Why should anyone trust this change?
The diff shows the implementation. It does not show the original task, the reasoning behind the design, the checks that actually ran, or the parts that remain unverified.
Writing code became cheaper. Reviewing the result did not.
The diff is still necessary. It is no longer sufficient.
For agent-written code, I think the permanent record should preserve the task, engineering intent, final change, verification evidence, and known limitations. Prompts, tool calls, intermediate attempts, and checkpoints belong somewhere else.
The transcript is not the software history
An agent session can contain a long sequence of exploratory work:
Prompt
Files inspected
Tool calls
Intermediate attempts
Failed tests
Checkpoints
Reverted changes
Final patch
That record may help someone audit or reproduce the execution. It can also become very large, especially when an agent investigates several possible causes before settling on one implementation.
Most of that material has no lasting value in the project history.
A checkpoint helps restore an earlier state. A commit should explain a decision that remains useful after the session ends.
The distinction is easier to see when the records are separated:
AGENT EXECUTION
prompts
attempts
tool calls
checkpoints
↓
observability
ACCEPTED CHANGE
task
intent
diff
verification
limitations
↓
Git
REVIEW DECISION
review
approval
↓
pull request
The execution record answers, "What did the agent do?"
The Git commit answers, "What change did the project accept?"
The pull request answers, "Who reviewed and approved it, and under what conditions?"
Those are related questions, but they do not need the same document.
This is no longer only an individual workflow
Coding agents can now investigate issues, modify repositories, execute verification commands, and prepare pull requests.
That workflow is moving beyond a developer working alone in a local checkout. Spotify has described its background coding agent, Honk, operating through an internal engineering platform. The company reported more than 1,500 AI-generated pull requests merged through that platform and later described the context and feedback loops needed to make those changes reliable.
Amazon Q Developer follows a similar issue-driven workflow. According to AWS documentation, it can work from a GitHub issue, implement a change, and open a pull request for review. The implementation and the review remain separate steps.
At that scale, producing a patch becomes less of a constraint. The harder question is what evidence an organization should require before accepting it.
Sources: Spotify Engineering: Honk and AWS documentation for Amazon Q Developer.
What the diff leaves out
A hypothetical payment bug makes the gap concrete.
Suppose an issue called ENG-412 reports duplicate payment processing. An agent investigates the worker, the Redis lock, and the webhook handler. It tries one implementation, changes a test, reverts that approach, and produces a final patch involving four files.
The final diff may say:
4 files changed
87 insertions
31 deletions
That summary tells the reviewer how large the patch is. It does not answer the questions that affect acceptance:
- What behavior was supposed to change?
- Which test reproduced the original failure?
- Did the agent change an existing test?
- Why does the implementation use a Redis idempotency lock?
- Which commands ran against the final version?
- What was not tested?
A useful commit does not need to preserve every failed attempt. It does need to retain the information required to understand the accepted decision.
Verification should come from the repository
The agent can propose a solution and run commands. The repository tools remain the source of truth for compilation, linting, and tests.
That means the commit or pull request should record the commands and their actual output:
pytest tests/payments/
ruff check .
mypy src/
For example:
Verification:
- pytest tests/payments/: 142 passed
- ruff check .: passed
- mypy src/: passed
- existing tests modified: no
These results are illustrative. The real values must come from the repository where the change was made.
The tool name is useful for provenance:
Generated with Claude Code
It does not establish correctness. A Co-authored-by trailer can satisfy an internal attribution or audit requirement, but it does not replace test output.
The evidence should also state what did not run:
Not run:
- end-to-end tests require a local payment provider
- load tests were not executed
That small section makes the boundary of the verification explicit.
Passing tests does not settle the whole question
An agent can change the implementation and the tests. That creates a review point that should never remain implicit.
A test may have changed because the expected behavior was wrong. It may also have changed because the agent adjusted the test until the implementation passed.
The reviewer needs to know which happened.
Verification:
- tests added: tests/payments/test_idempotency.py
- existing tests modified: no
- tests removed: no
If an existing test changes, explain why:
Existing test modified:
- updated the fixture to match the payment provider's documented
duplicate webhook response
A green test suite is evidence about the cases covered by that suite. It does not establish that every relevant behavior is correct.
The discussion around SWE-bench includes examples of patches that pass available tests while failing broader evaluation. That is one reason the accepted record should include scope and limitations, not only a green status.
A practical contract for the commit
I would keep the permanent record small:
Task
Intent
Change
Verification
Limitations
Task
State where the work came from:
Refs: ENG-412
This might point to an issue, an incident, or a technical specification. The purpose is to let a future reader recover the original problem.
Intent
Describe the engineering decision in one or two sentences.
Use a Redis-backed idempotency lock so duplicate webhooks do not
create multiple payment records across worker instances.
This is more useful than documenting the entire chain of prompts that led to the decision.
Change
The diff remains the central artifact. Keep the scope reviewable.
An agent can produce a large patch quickly, but the cost of understanding that patch still falls on the reviewer. If a small issue creates thousands of changed lines, the commit should explain why or be split before review.
Verification
Record the commands and the results from the final state of the repository.
Verification:
- pytest tests/payments/: 142 passed
- ruff check .: passed
- mypy src/: passed
- existing tests modified: no
Limitations
State where the verification stops:
Limitations:
- provider sandbox was unavailable locally
- concurrency was checked with unit tests only
- production load characteristics were not measured
A limitation does not weaken the record. It defines the boundary of the claim.
The pull request records acceptance
The commit and the pull request should not carry the same information.
The commit should remain useful when someone reads it months later, outside the original review conversation. The pull request can hold the discussion around acceptance:
Reviewed:
- payment idempotency behavior
- migration compatibility
- test coverage
Open risk:
- production concurrency was not measured
Approved by: [reviewer]
That is where reviewer questions, requested changes, follow-up work, and the final approval belong.
The agent may have produced the implementation. A human still decides whether the project should accept it.
Where execution history can live
There are legitimate reasons to preserve the agent's execution history.
A regulated environment may need an audit trail. A team may want to study failed attempts. An observability system may capture prompts, tool calls, repository state, and command output for debugging.
Those records can be valuable without becoming part of every Git commit.
The useful boundary is:
Execution evidence → accepted change → human acceptance
The execution log supports the change. The commit describes the change. The pull request records the acceptance decision.
Antigravity CLI's checkpointing documentation illustrates why checkpoints belong to the execution layer. They help restore a previous state while work is in progress. They are not automatically the right explanation for a change that remains in the repository.
Worktrees have a similar limit. They isolate parallel execution, but isolation does not provide verification, review, or acceptance.
A commit template for agent-written code
A practical template could look like this:
Fix duplicate payment processing
Refs: ENG-412
Intent:
Use a Redis-backed idempotency lock so duplicate webhooks do not
create multiple payment records across worker instances.
Verification:
- pytest tests/payments/: 142 passed
- ruff check .: passed
- mypy src/: passed
- existing tests modified: no
Limitations:
- provider sandbox unavailable locally
- concurrency checked with unit tests only
- production load not measured
The template does not attempt to reconstruct the agent's entire thought process. It records the information a maintainer needs to evaluate the accepted result.
Known limit
This format cannot compensate for incomplete requirements, weak tests, or behavior that only appears under production load.
Some changes will need a design document, an incident record, a security review, or a separate audit trail. The commit remains one part of that system.
Its job is narrower: preserve the engineering decision, the evidence available at acceptance time, and the limitations that future readers should not have to rediscover.
Agents make patches cheap. The decision to accept a patch still requires engineering judgment.
Git history should preserve that decision.
Top comments (0)