Adr Writing

ADR writing

A decision nobody can read was not recorded. This skill governs the shape of every file under docs/adr/ and of docs/ARCHITECTURE.md: how the file is named and retired, how the sections run, when to draw instead of explain, and what must hold before the document lands. When a change needs an ADR and what an agent owes the ADRs in force is .claude/rules/adr.md, loaded in every session; this skill does not repeat it.

Every sentence must pass one test: would someone meeting this codebase for the first time understand it without asking a question? If not, the fix belongs in the writing, not in the reader.

What an ADR is for

An ADR records an architecture-level decision: what was chosen, which alternatives were dropped and why, and what shape the code must now take. The reader is an agent or a person who will build against this decision months from now, not the author and not today's reviewer.

• Enough context, and no more. A line survives only if that reader would act differently for having read it.
• Never narrate your thinking. Deliberation, reversals, what an earlier draft said, what you worried about — none of it belongs. State the fact, the option, or the decision.
• The document never talks about itself. No "covered in the last section", no "this document does not decide X". Say the thing or delete it.
• Link outward instead of retelling. When the context lives in another ADR, a source file, a Jira issue, or an upstream document, cite it and reproduce only the sentence the reader must act on.
• Name the scope boundary once. What is out of scope gets one line — never the reasoning for deferring it, never a sketch of the deferred design.

After reading, does the reader know what was chosen, what was rejected, and what shape the code must take? If any of the three is missing it is a memo, not a decision record.

ADR file conventions

This is the definition of how an ADR file is named, titled, and retired. The one other copy is .github/instructions/adr.instructions.md, which restates the points Copilot needs because it cannot load a skill; keep the two in step.

• Filename — NNNN-title.md, for example 0001-explicit-project-prop-contract.md. The next number is the highest NNNN in docs/adr/ plus one. Numbers are never reused, so when the sequence has a gap the deleted number stays retired; git log -- docs/adr shows it.
• Title — # NNNN — <English noun phrase> (T1–T6). A Jira key goes in the sources section, never in the title. A supersede pointer goes on its own line, never in the title.
• No status field. An ADR on main is a decision in force — landing it there, merged and human-approved, is the record. A draft under review is proposed by virtue of sitting in an unmerged PR, and nothing marks it in the file. The one marker a file ever carries is reversal.
• Reversing a decision — do not edit the existing ADR's reasoning. Either keep the file and add a top line > superseded by NNNN naming what replaced it, or delete it outright. Both are allowed, and deleting is usually right once the decision and the code it described are both gone, because a retired file is then a trap a reader has to disprove. Git history holds what it said. Convert inbound references in surviving documents and source comments to plain ADR NNNN mentions.
• Partial replacement — if the new ADR replaces only part of the old, keep the old file, say so in the new ADR, and add a scoped pointer line rather than the blanket supersede marker.
• Mention form — documents and PR bodies write ADR NNNN. Source comments written before this convention say ADR-NNNN; they are corrected when the file is next edited, never swept.
• Language — the title is English; the body is Korean, with English technical terms and identifiers written as they appear in the code. An ADR that landed before this convention keeps its body language; a document is revised only when its content changes, never translated for its own sake. Section headings follow the body language, as references/document-shape.md fixes.