AI Audit Trail for Infrastructure Changes Starts in the Repo

An AI audit trail is the record that lets someone reconstruct, months later, why an AI-assisted change to production infrastructure looks the way it does. We care about it because the diff survives every incident review, while the reasoning behind it rarely does.

Coding assistants made Terraform, Helm and pipeline changes much faster to write. They did not make them faster to explain, and the explanation used to be a by-product of the slow typing.

In this post we cover where the reasoning gets lost, the five fields we keep for every AI-assisted change, how to store them so they survive, when a full record is overkill and what to do this week.

The Reasoning Behind AI-Assisted Changes Disappears First

Picture a page at 03:00 for a deploy blocked by a Terraform plan. The module has a lifecycle block with three ignore_changes entries added six months ago, and the commit message says "update networking". The engineer who merged it remembers working through the refactor with an assistant, and the session is gone.

That block matters more than it looks. HashiCorp's lifecycle documentation says the argument is for a resource "created with references to data that may change in the future, but should not affect the resource after its creation." In practice it tells Terraform to stop reconciling part of the real world, and the reason it was safe to do that is exactly the part nobody wrote down.

We see the same pattern in pipeline changes, IAM policies and autoscaling rules. The code passes review because it works. What the reviewer approved was the function, while the intent stayed in a context window that has since been discarded.

• Why the Plan Output Is Not Enough

A plan shows the resources that will change and the attributes that differ. It cannot show the alternatives considered, the constraint that ruled one out, or the incident that prompted the change in the first place.

We treat the plan as evidence that a change is mechanically correct. The audit trail has to answer a different question, which is why this change was the right one, and that needs words a human chose.

• Why Asking the Model Later Does Not Work

A common answer is to paste the code back into an assistant and ask what it does. That produces a plausible explanation of the code as it stands, built from the code alone.

It cannot recover the constraint the original prompt carried, the warning a colleague raised in review, or the outage that made the change urgent. A confident after-the-fact explanation can send an on-call engineer in the wrong direction, because it describes what the block could be for rather than what it was for.

This Is an Old Documentation Problem AI Made Faster

Missing rationale is not new. Michael Nygard described it in 2011 in Documenting Architecture Decisions, where he wrote that "A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision." Without the context, he argued, that person either accepts the decision blindly or reverses it blindly.

What changed is the rate. Writing HCL by hand was slow enough that the author usually understood every line and often explained it in the commit. An assistant can produce a working module in a minute, so the number of decisions per week goes up while the time spent on each one goes down.

We think of this as a documentation debt that compounds faster than before. The fix is the same one Nygard proposed, applied to smaller and more frequent decisions.

Five Fields Every AI Audit Trail Entry Should Keep

We keep a short, fixed set of fields for any AI-assisted infrastructure change that alters behaviour, permissions, cost or data. The list is deliberately small, because a long template is the first thing people skip at the end of a long day.

1. The Intent in One Sentence

Write the goal as the human understood it, such as cutting NAT gateway cost in one region without breaking cross-region peering. A reviewer who disagrees with the intent can stop there, which saves everyone reading the diff.

We phrase it as an outcome rather than an action. "Move egress to a shared gateway" describes the change, while "halve egress spend for the batch fleet" describes what success looks like.

2. The Constraints Given to the Model

Record the limits the prompt carried, in plain words. Typical ones are "no public IPs", "no downtime for the payments service" and "keep the existing state addresses".

This is the field that a later reader cannot reconstruct from the code. It also shows a reviewer which risks the author already thought about, so the review can spend its time on the ones nobody mentioned.

3. What a Human Overrode

List every suggestion the author rejected or rewrote, with one line of reason each. If the assistant proposed a public subnet and the author forced private-only, that belongs here.

We find this the most useful field during incidents. An override marks the exact places where a human judged the model wrong, which are also the places a future change is most likely to undo by accident.

4. How the Result Was Verified

Note what was checked before merge. Examples include a plan reviewed against a staging state, a provider argument confirmed in the official documentation, or a load test run against the new limits.

The point is to separate claims that were tested from claims that were accepted on trust. Assistants sometimes invent provider arguments that look real, and a record of what was verified tells the next person which parts deserve suspicion.

5. The Link to What Prompted It

Point to the ticket, incident or investigation that led to the change. When a change came out of an incident, link the investigation record rather than restating it.

We keep this link even for small changes. It is the cheapest way to answer "why did we do this" a year later, and it connects the change to the evidence that justified it, which is the same reason we argue that a postmortem should keep the search and not only the answer.

Where the Record Should Live So It Survives

The record has to sit next to the code, travel with it through forks and migrations, and be searchable with the same tools engineers already use. Chat exports and vendor dashboards fail at least one of those tests.

Location	Survives a tool change	Searchable in an incident	Best for
Pull request description	Partly, it stays with the hosting platform	Yes, through the platform search	Routine changes with a reviewer
Commit message trailers	Yes, it lives in Git history	Yes, with git log	Short, machine-readable fields
Decision record file in the repository	Yes	Yes, with grep	Changes that set a pattern others will copy
Chat transcript export	Rarely	Poorly, too much noise	Raw evidence attached to one of the above

GitHub's documentation on pull request templates says contributors "will automatically see the template's contents in the pull request body." We put the five fields in that template for infrastructure repositories, so they appear without anyone remembering to add them.

For the fields that tools should read, we use commit trailers. The git interpret-trailers documentation defines a trailer as "a key-value pair with a colon as a separator", which makes a field like an AI-assisted flag easy to query across the whole history.

Reduce batch fleet egress cost in eu-west-1

AI-Assisted: yes
Constraints: no public IPs; keep state addresses
Overrides: rejected public subnet for workers
Verified: plan against staging state; provider docs
Refs: INC-2291

A review does not end at approval, though. A reviewer who sees only the diff can approve a change they do not understand, which is why we argue that a pull request alone is not a review gate. The record gives the reviewer something to disagree with.

• Logging the Agent Side of the Trail

When an AI agent rather than a person proposes the change, the trail needs the agent's side too. That means the queries it ran, the evidence it read and the reasoning it gave, captured automatically rather than reconstructed.

We prefer agents that hold read-only credentials and write a log of every action, because that log becomes part of the audit trail without anyone typing it. We describe how we approach read-only access with every agent action logged, and the same standard is one of the guardrails in the five rules for AI agents in production.

When a Full Decision Record Is Overkill

Not every change needs five fields. We skip the record for these kinds of change.

• Formatting and linting changes that a plan shows as no-ops.
• Version bumps that a dependency bot proposed and a passing test confirmed.
• Renames and moves where the state addresses are migrated and the plan is empty.

We also skip it when the change is fully explained by a linked incident and the diff is a single line. Forcing a template onto trivial work teaches people to fill it with filler, and filler is worse than nothing because it looks like evidence.

The line we use is behaviour. If the change can alter what production does, who can reach what, what it costs or where data goes, it gets the fields, however small the diff. Drift between what the record says and what is deployed is its own risk, which we cover in our configuration drift triage guide.

Start Your AI Audit Trail With One Template

We would add the five fields to the pull request template of your busiest infrastructure repository this week, and agree that AI-assisted changes carry the trailer. After a month, search for the trailer during your next incident review and see how many questions the records answer.

The aim is an AI audit trail that a stranger can read at 03:00 without the author. Operate logs every agent's reasoning and every query it runs, and proposes any code fix as a patch file an engineer reviews and applies.