Contents

Templates show AI where to write. Keeping architecture decision records (ADRs) readable requires defining what belongs in them and what belongs elsewhere, with authors and reviewers following the same rules.

Key Points#

  • Keep lasting decisions in ADRs, and move task progress, migration schedules, and routine implementation details elsewhere.
  • Explain the project's actual problems so readers can understand the decision without retracing past discussions.
  • Turn recurring review comments into writing rules, using rule IDs and examples to make the required changes concrete.
  • Give AI authors and reviewers shared guidelines rather than separate instructions.

The Limits of Templates#

TOKIUM's product team already had an ADR template with “Context,” “Decision,” “Consequences,” and an optional “Alternatives Considered” section, plus status and date metadata. AI filled in each section, but the resulting records were often difficult to review.

One ADR included a migration dependency diagram and a 23-row task table. Another described the hypothetical risks of storing ordinary configuration alongside secrets without mentioning that the project already did so. An ADR about email safety mixed lasting policy with method names, environment variable syntax, and address-matching details.

These documents contained useful information. The problem was where it belonged. Readers had to separate decisions from temporary work and implementation steps, and fill in missing context. Adding more headings would not solve this.

Draw the Boundaries of a Decision#

An ADR explains the problem, the chosen response, and its consequences. It needs to remain useful after the implementation changes and the migration ends.

Use these four boundaries when reviewing drafts.

| Keep in the ADR | Put elsewhere | |---|---| | Conditions that must hold during migration | Task owners, deadlines, and progress | | Requirements to prevent email delivery to unauthorized recipients | Environment variable names and parsing syntax | | Problems with the project's current configuration | Generic warnings that omit the actual situation | | Accepted trade-offs and their rationale | Detailed implementation steps |

For example, “Staging emails must go only to approved recipients, and sending must be blocked if no configuration is present” expresses a lasting requirement. Comma-separated configuration and lowercase normalization usually belong in specifications or implementation records.

Ask: Could the implementation change while this decision remains valid? If so, details tied to that implementation probably belong elsewhere. Judgment is still needed, though. Choosing a particular technology or protocol can itself be an architectural decision. Abstraction should preserve that choice, not erase it.

Turn Review Comments into Rules#

TOKIUM examined 34 PRs that changed ADRs and 830 review comments, extracting 32 rules. This is a useful approach: start with recurring review problems rather than imagining an ideal document.

In your own repository, collect recent ADR review comments and categorize recurring corrections. Give each rule a stable ID, a requirement level, and a short example. Reserve MUST for acceptance requirements, and use SHOULD where exceptions can be justified.

Start with a small set of rules like these.

  • C-1, MUST: Verify factual statements against code or primary sources.
  • C-3, MUST: Make the problem and decision understandable within the ADR.
  • D-1, MUST: Keep migration progress and task tables outside the ADR.
  • D-4, SHOULD: Preserve implementation flexibility unless the implementation choice itself is the decision.

For rules that require judgment, add a practical question. For D-1, ask whether the text becomes unnecessary once the task is complete. Use fictional good and bad examples to avoid accidentally preserving old project decisions in the guidelines.

Use a Single Source for Rules#

Keep the guidelines alongside the ADR template so authors can consult both before writing. Rules hidden in a review prompt come too late: authors discover them only after submitting the document.

Incorporate the same guidelines into both the ADR writing workflow and the AI review workflow. If the tool supports directory-specific instructions, use a short reference instruction to load the guidelines when editing ADR files. Avoid copying the full rules into multiple prompts, as the copies will drift.

Require review comments to identify the applicable rule, the problematic passage, and the necessary correction. “D-1: Move this progress table to the migration plan” tells authors what to do. “Make this more readable” does not.

Check Evidence and Accountability#

Even a well-formatted ADR can rely on evidence that no one can verify. TOKIUM reports that AI reviews flagged decisions supported only by in-person meetings and work delegated to test plans that did not exist in the repository.

Before accepting an ADR, check that its evidence is accessible and that delegated work has either a reference to an existing document or a clear owner. Keep unresolved decisions visibly unresolved rather than treating them as settled.

The reported examples show that shared rules can make review comments more specific. They are not measured evidence of shorter review times or proof that AI can judge architectural quality. Humans still need to assess whether the decision solves the problem and whether its costs are acceptable.

Next Step#

Review your five most recent ADR PRs and turn the most frequent correction into a shared rule with an ID, a requirement level, and fictional before-and-after examples.

Source: https://zenn.dev/tokium_dev/articles/adr-authoring-guideline

Contents