AI Can Write the Implementation. Who Owns the Decision?

AI can produce an implementation. The harder question is whether someone can explain six months later why the system was built that way.

The useful reasoning behind a change can be scattered across an issue, a prompt, an agent session, a review thread, and the code itself. Each place captures a fragment. None necessarily preserves the decision as a thing another engineer can inspect, challenge, or revisit.

This is not an argument that AI cannot reason, or that every coding task needs an architecture document. Even sound reasoning is not organizational knowledge if it disappears when the session closes. As implementation gets cheaper, preserving the important decisions becomes a larger part of engineering work.

A diff can show that a page now reads a query parameter, that a response is cached, or that a component has been split. It usually cannot tell a future maintainer which alternatives were considered, which product constraint mattered, or what evidence would make the team change course.

That missing context matters most when the implementation looks surprising. Why is this state in the URL instead of a store? Why did we keep a boundary in the server layer? Why is a migration staged across two releases? A reviewer may know the answer today. If it exists only in an informal conversation, the next person may infer a different rationale from the code.

A decision record should preserve the reason without trying to reproduce the whole conversation. It is a compact link between the problem, the chosen direction, its constraints, and the point at which the choice should be revisited.

For a consequential choice, I would capture:

• Context: What problem or constraint forced a decision?
• Decision: What approach are we taking?
• Why this option: Which requirements or tradeoffs made it preferable now?
• Alternatives: What realistic options did we consider, and why not choose them?
• Assumptions: What must remain true for this to work?
• Risks and tradeoffs: What are we knowingly accepting?
• Verification: What evidence will show the implementation respects the decision?
• Revisit trigger: What change in scale, product behavior, or evidence should make us reconsider?

A short note is enough when the choice is narrow. The record should be proportional to the consequences, not the novelty of the technology.

Imagine an agent is asked to make a filterable report page. The first implementation places selected filters in component state. During review, someone points out that users need to share filtered links and use browser back/forward navigation. The team chooses URL parameters as the durable source for the filters, keeps unfinished text local, and derives the server query from the submitted URL state.

Without a decision note, a later agent might move the filters into a global store because several components read them. The code would still build and might even pass the local tests, but it would silently remove shareable links or create two competing sources of truth. The companion article Your React App Probably Has Too Much Global State walks through the local, URL, server/cache, and shared-client choices behind this example.

A compact record might say:

The note is not a substitute for tests or implementation details. It gives the next person the intent they need to evaluate a proposed change. A future agent can read the linked issue, code, and decision, then make a deliberate adjustment instead of reconstructing the original discussion from scraps.

Put the durable note somewhere connected to the work: alongside an architecture decision record, in a project document, or in a concise section of the issue or pull request. Link it from the artifacts people already follow. The exact storage format matters less than discoverability and ownership.

For a small, local decision, the PR description and a useful test may be sufficient. A new file for every naming choice creates noise and makes important records harder to find. Persist a separate decision when the choice crosses component or team boundaries, creates a lasting constraint, carries meaningful risk, or is likely to be revisited independently of the implementation. This record complements rather than replaces a risk-focused review: the blast-radius checklist focuses on boundaries, evidence, and recovery for a change, while a decision record preserves why an approach was chosen.

The rule I use is simple: record a decision when losing its rationale would make a future change materially harder or riskier. Do not document every intermediate thought just because an agent produced it.

An agent handoff should distinguish what changed from why it changed. Alongside files touched and tests run, include decisions made, assumptions inherited, rejected alternatives that still matter, unresolved questions, and conditions that should trigger another review. That gives the next agent a useful starting point without preserving every token of the previous session.

This also sharpens human ownership. The agent can suggest an approach and implement it; the responsible engineer confirms whether the choice matches product constraints and accepts the tradeoffs. A generated explanation is not automatically a decision record. It becomes one when someone verifies it against the work and makes it findable.

As AI handles more implementation, engineering value moves toward architecture, product judgment, scope, review, and verification. Preserving intent connects those activities across time. It lets a team move quickly without making every future engineer replay the same discovery process.

The target is not more documentation. It is less lost context. Write down the decisions whose rationale will matter after the person, prompt, or agent session that produced the code is gone.