What is an architecture decision record?
An architecture decision record (ADR) is a short document that captures one significant technical decision: the context, the choice that was made, the alternatives and the consequences. Kept as Markdown files beside the code, ADRs explain why the system looks the way it does long after the discussion has ended.
Keep each ADR findable
The Project Reading Kit already has a decisions.md file explaining why its fictional app keeps local files. For a larger project, split distinct decisions into separate Markdown records and add an index with status and links. A useful filename starts with a stable number and a short topic, such as 001-local-storage.md.
An ADR can use four headings: Context, Decision, Alternatives, Consequences. Link back to the requirement or architecture section that raised the question. Avoid recording only the conclusion; future readers need to know which trade-off was accepted.
Read it as a chain
Start at the specification’s requirement, follow its decision link, then return to the architecture description. If a decision supersedes an earlier one, state that relationship and link both records. Do not silently rewrite history as if the original choice had never existed.
This is a documentation convention, not an Aero Markdown feature. Aero can browse the local folder and relative links, but it does not generate or enforce architecture decision records. The Mac app is not publicly available yet. For a concrete example of connected project reading, follow the Field Notes walkthrough.