Documenting decisions: ADRs and documentation for whoever comes later

How to record the why of technical choices: architectural decisions (ADRs), documentation of APIs and features, comments that explain the reason. For whoever will read it in a year, person or agent.

MethodologymetodologiadocumentazioneADRingegneria del software19 November 2026 · 3 min read

In a year someone will open the project and wonder why there is a message queue where a direct call would have done. If nobody wrote down the reason, the choice will be repeated, undone or, worse, defended without knowing why. Documenting does not mean writing a lot: it means recording what the code alone does not say.

What the code does not say

The code says what the system does. It does not say why one road was chosen over another, which constraints there were, which alternative was discarded and why. This is the content that is lost first when people change.

Architecture decision records (ADRs)

An ADR (Architecture Decision Record) is a short note, one per decision, that contains:

  • Context: the problem and the constraints of the moment.
  • Decision: what was chosen.
  • Alternatives considered: and why they were not chosen.
  • Consequences: what becomes easier, what harder, which risks are accepted.
  • Status: proposed, accepted, replaced by another decision.

It is written at the moment you decide, when the reasoning is fresh. They are not rewritten: a changed decision is recorded with a new note that replaces the earlier one, so the history remains.

You write an ADR when the choice is hard to undo, involves several parts of the system, or when someone, in the future, will reasonably ask "but why?".

Documentation of APIs and features

For whoever uses an interface, what matters is: what it is for, a working example, the parameters with their constraints, the possible errors and what to do. Documentation that can be run (tested examples) ages better than purely descriptive documentation. When you change a public API, you update the documentation in the same change.

Comments in the code

A comment that repeats the code is noise. A useful comment explains the why of an anomaly: "we round down here because the supplier truncates". You also mark non-obvious constraints and the cases the code protects. When the code changes, the comment changes with it, or is deleted.

For whoever will read: people and agents

Documentation also serves the agents that will work on the project: a rules file, written decisions and an index by area make them more reliable, for the same reason they help a new colleague.

Where to keep documentation

Near the code, in the same repository, reviewed in the same changes. Documentation somewhere else, updated separately, drifts almost at once.

Warning signs

  • Important decisions kept only in someone's memory.
  • Comments that describe what the code does instead of why.
  • Documentation that did not change while the API did.
  • ADRs rewritten instead of replaced.
  • No trace of the alternatives discarded.

An example

A team chooses not to use a relational database for a module. A note written the same day: context (a lot of semi-structured data, frequent writes), decision, alternatives considered (the relational database already in use, discarded because of the cost of schema migrations), consequences (cross-cutting queries are harder). Two years later, a new colleague understands the choice in two minutes and knows when it is worth revisiting.

When to use it

When taking architectural decisions, changing public APIs, releasing a feature, or when you need to record a context that future developers and agents will have to know.

This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.

This article is an OIAR skill

What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.

documentation-and-adrsA method for recording the why of technical choices: ADRs (context, decision, alternatives, consequences, status), documentation of APIs and features with examples, comments that explain the reason. Use it when taking an architectural decision, changing a public API or releasing a feature.