When an AI Agent Forgets Your Design Decisions, What Should You Save?
The code preserves a design choice, but the reason for it is buried in an old chat. What will the next agent need before proposing the same rejected alternative?
- ADRs4AI stores design deliberations as Markdown files alongside a project.
- An agent’s recommendation, a human’s answer and an unresolved question remain distinct.
- Future sessions must still read the records; saving a decision does not enforce it in code.
Save the reasoning that the code cannot explain
The useful handoff is the problem, the options considered and the reason someone approved a choice. ADRs4AI puts that material in versioned project files so another session or model can read it. It extends the ADR practice to preserve deliberation, including questions that remain open.
Consider a hypothetical CSV export. “Generate it on the server” records an outcome. Adding the file-size and access requirements that drove that choice lets a future developer judge whether a browser implementation now makes sense. The goal is to preserve the basis for a decision while leaving room to change it.
An agent’s recommendation is not the human’s approval
The official record template separates contributors, status and dates from the questions being discussed. Its question blocks keep the recommendation and the eventual answer distinct.
| Record | What a future reader learns |
|---|---|
| Question and options | The unresolved choice and the approaches considered. |
| Recommendation and rationale | Which option the agent favors and the evidence behind it. |
| Confidence and a reason to reconsider | The basis for confidence and what observation would change the recommendation. |
| Human answer and iterations | What was actually decided and why it later changed. |
Questions use QST:; answers use ANS:. Recommendation attribution includes the model and date. Confidence is an author’s stated assessment, not a measured probability that the design will succeed.
A single unresolved choice is enough to begin
The repository template can seed a new project or supply files for an existing one. It includes a detailed ADR format, a simpler MADR option and a seed format for unstructured thoughts.
Write down one design problem, have the agent separate its threads into records, then answer the resulting questions. The getting-started guide presents a template, a seed and a first answered question as the starting loop.
When requirements change, record what changed and the replacement decision. Otherwise, a repository can preserve two conflicting choices without telling the next reader which one applies.
The extension makes the files easier to use
The ADRs for AI VS Code extension gathers open questions into a sidebar and provides an answer panel. Its basic editing features require no separate server, account or API key. Files live in docs/adr/ by default and remain readable without the extension.
Automatic commits on answer submission are off by default. Saving an answer and committing it are separate events.
Connect the records to the instructions used at the start of a task, and check that the captured decision matches what the human intended. The practical test is whether the next session can find the relevant reasoning and continue the work.