The weekend argument was about memory.
Three current essays arrived at the same pressure point from different directions. Simon Spati argues that the larger problem is not generated code by itself. It is a team losing the architecture and intent behind its choices.[1] Alex Ewerlof argues that cheaper code creation does not remove maintenance, reliability, security, scalability, or accountability.[2] Glyph Lefkowitz asks what an AI product would look like if checking claims, citations, and provenance were built into the work instead of left to a disclaimer.[3]
These are opinion essays, not controlled studies. Their overlap is still useful. Generation speed can lower the cost of making a change while raising the cost of reconstructing why that change exists.
A diff records what moved. It does not record why the old position was rejected.
The prompt is not the decision record.
A prompt may contain useful context, but it is often private to one session, mixed with abandoned instructions, and detached from the code after merge. A transcript can preserve too much while still hiding the one decision a maintainer needs.
The useful record is smaller. Name the pressure that forced a choice. State the choice. Record the costs it accepts. Give the decision an owner. Attach a check that can show when the choice no longer holds.
Use the repository as shared memory.
AWS Prescriptive Guidance describes an architectural decision record as a document for the decision, its context, and its consequences. The guide adds ownership and a lifecycle. Accepted records become immutable, and a later decision supersedes the old record instead of rewriting history.[4]
That process predates the current coding-agent wave. It fits the problem because it puts the explanation where the team can review it. The record does not need to be long. It needs a stable path, a named owner, and a link from the change that depends on it.
Add a check, not a confidence score.
Architecture prose can also go stale. Pair each decision with one observable condition. It might be a latency budget, a recovery drill, a dependency rule, a schema invariant, or a test that runs at a boundary.
This does not prove the whole architecture is right. It gives future maintainers a place to challenge the reason and a way to detect one broken assumption. The record becomes a working review input instead of a museum label.
Make the handoff boring.
- Create a short decision file under a predictable repository path.
- Link it from the pull request and from the code or configuration it governs.
- Name one owner who can explain or supersede it.
- Write one consequence the team accepts and one condition that would force review.
- When the choice changes, add a new record and point both records at each other.
The goal is not more paperwork. The goal is to stop paying senior-engineer time to excavate decisions from generated code, closed chats, and plausible guesses.