ADR: Practical Guide to Documenting Architecture and Supercharging Generative AI

Introduction

For tech managers and development teams, documenting architectural decisions has always been a challenge. How many times have you asked yourself "why did we choose this approach?" months or years after a decision was made? Or needed to explain the context of a technical choice to a new team member?

Architecture Decision Records (ADRs) emerge as a practical and structured solution to this problem. But beyond documenting decisions, ADRs hold even greater potential: they become a rich and structured context for generative AI agents, allowing these systems to better understand the project and provide suggestions that are more accurate and aligned with the architectural decisions already taken.

In this article, I explore how to start documenting architecture using ADRs and how this practice can transform interaction with generative AI and AI agents, turning them into true partners in software development.

What are Architecture Decision Records (ADR)?

Architecture Decision Records are documents that capture important architectural decisions in a structured way. Created by Michael Nygard in 2011 and popularized by ThoughtWorks, the ADR format documents not just "what" was decided, but primarily the "why" and the "context" that led to that decision.

Basic Structure of an ADR

A typical ADR contains:

  • Status: Proposed, Accepted, Deprecated, or Superseded
  • Context: The situation that led to the decision
  • Decision: What was decided
  • Consequences: Positive and negative impacts of the decision
  • Alternatives Considered: Other options evaluated and why they were discarded

Why are ADRs Important?

For tech managers and development teams, ADRs offer:

  • Traceability: Understanding the history of decisions and their context
  • Onboarding: New team members understand decisions quickly
  • Consistency: Similar decisions can reference previous ADRs
  • Learning: Documenting trade-offs helps in future decisions
  • Communication: A clear basis for architectural discussions

How to Start with ADRs

Step 1: Define the Structure

Start by creating a `docs/adr/` or `architecture/decisions/` folder in your project. Each ADR should be a sequentially numbered Markdown file:

docs/
└── adr/
    ├── 0001-record-architecture-decisions.md
    ├── 0002-use-markdown-for-content.md
    ├── 0003-implement-modular-components.md
    └── template.md

Step 2: Use a Template

A basic ADR template follows this structure:

# ADR-0001: [Decision Title]

**Status**: Accepted

**Date**: YYYY-MM-DD

**Deciders**: [Names of people involved]

**Tags**: [tag1, tag2, tag3]

## Context

[Describe the context that led to this decision]

## Decision

[Describe the decision taken]

## Consequences

### Positive
- Benefit 1
- Benefit 2

### Negative
- Drawback 1
- Drawback 2

Step 3: Document Important Decisions

Not every decision requires an ADR. Focus on decisions that:

  • Affect the structure, dependencies, or interfaces of the system
  • Are difficult to reverse
  • Have multiple viable alternatives
  • Impact multiple teams or stakeholders

Step 4: Keep ADRs Updated

ADRs are living documents. When a decision is superseded or deprecated, update the status and create a new ADR referencing the previous one.

ADRs and Generative AI: A Powerful Combination

The Problem with Limited Context

When you use generative AI agents (like ChatGPT, Claude, or GitHub Copilot) without architectural context, they work with generic information. The result is suggestions that may not align with decisions already made in the project, generating inconsistencies and rework.

How ADRs Improve AI Context

ADRs provide structured and rich context that allows AI agents to:

  1. Understand Past Decisions: Agents can reference ADRs to understand why certain approaches were chosen
  2. Suggest Consistent Solutions: With knowledge of past decisions, suggestions are more aligned
  3. Identify Conflicts: Agents can warn when a new suggestion conflicts with existing ADRs
  4. Generate Documentation: ADRs serve as a basis for generating consistent technical documentation

Practical Example: Using ADRs in Prompts

Imagine you have an ADR documenting the decision to use Markdown for content. When asking an AI agent for help, you can include:

Consult ADR-0002 in docs/adr/0002-use-markdown-for-content.md 
before suggesting content management alternatives.

The project has already decided to use Markdown. Suggestions must be 
compatible with this architectural decision.

The agent now has sufficient context to provide aligned suggestions, rather than proposing solutions that conflict with documented decisions.

Benefits for Tech Managers

1. Architectural Visibility

ADRs provide a clear view of architectural decisions, facilitating:

  • Regular architectural reviews
  • Identification of decisions that need to be revisited
  • Communication with stakeholders regarding trade-offs

2. Efficient Onboarding

New team members can read ADRs to quickly understand:

  • Why certain technologies were chosen
  • Which alternatives were considered
  • What the project's architectural principles are

3. Better Use of Generative AI

With well-documented ADRs, tech managers can:

  • Create more effective prompts for AI agents
  • Ensure AI suggestions align with architectural decisions
  • Reduce rework caused by inconsistent suggestions

Real Use Cases

Case 1: Integration with GitHub Copilot

When using GitHub Copilot in a project with ADRs, you can:

  1. Reference relevant ADRs in code comments
  2. Copilot will understand the architectural context
  3. Suggestions will be more consistent with documented decisions

Case 2: ChatGPT/Claude for Architectural Review

When requesting an architectural review, include ADRs in the context:

Analyze this architectural change proposal considering 
the following ADRs:
- ADR-0001: Use of modular architecture
- ADR-0002: Markdown as content source
- ADR-0003: Type-safe models

Is the proposal compatible with these decisions?

Case 3: Documentation Generation

ADRs can be used to generate consistent technical documentation:

Based on the project's ADRs, generate architecture documentation 
explaining the key decisions and how they relate to each other.

Best Practices

1. Keep ADRs Concise

ADRs should be focused and direct. Avoid overly long documents that hinder reading and comprehension.

2. Use Clear Language

Write for an audience that may not have participated in the original decision. Explain technical terms when necessary.

3. Reference Related ADRs

When a decision is based on another, reference the previous ADR:

This decision extends ADR-0001, which established the use of 
modular architecture.

4. Update Status

Keep the status of ADRs updated. Deprecated decisions should be clearly marked.

5. Include Diagrams When Useful

Diagrams (using Mermaid, for example) can make ADRs clearer:

graph TD
    A[Decision: Use Markdown] --> B[Benefit: Versioning]
    A --> C[Benefit: Editability]
    A --> D[Trade-off: Parsing required]

Common Challenges and How to Overcome Them

Challenge 1: "I Don't Have Time to Document"

Solution: Start small. Document only critical decisions. Over time, the practice becomes natural, and the value becomes evident.

Challenge 2: "ADRs Become Outdated"

Solution: Integrate ADRs into the code review process. When a decision changes, updating the ADR should be part of the process.

Challenge 3: "I Don't Know What to Document"

Solution: Document decisions that generated discussion or have multiple viable alternatives. If it was an easy decision, it probably doesn't need an ADR.

Examples of What to Document in an ADR

Mobile (iOS/Android):

✅ Document: Decision to use MVVM-C architecture instead of MVC or VIPER

  • Why: Affects the entire project structure, has multiple viable alternatives, and impacts how the team develops.
  • Context: Team discussed MVVM, VIPER, and Clean Architecture. Decision impacts navigation patterns and testability.
  • ADR Example: "ADR-0005: Use MVVM-C as architectural pattern for iOS projects"

❌ Do not document: Choice to use `UIColor.red` instead of `UIColor.blue` for a specific button

  • Why: Simple UI decision, easy to reverse, does not affect architecture.

Backend:

✅ Document: Decision to use GraphQL instead of REST API

  • Why: Affects how clients consume the API, has significant trade-offs (complexity vs. flexibility), and impacts multiple teams.
  • Context: Need to reduce over-fetching, multiple clients with different data needs.
  • ADR Example: "ADR-0008: Adopt GraphQL as API standard for new endpoints"

❌ Do not document: Choice of variable name or structure of a specific function

  • Why: Local implementation decision, does not affect system architecture.

Frontend Web:

✅ Document: Decision to use React instead of Vue or Angular

  • Why: Affects the entire frontend stack, has long-term implications (ecosystem, hiring, maintenance), and is difficult to reverse.
  • Context: Team evaluated React, Vue, and Angular considering ecosystem, learning curve, and project needs.
  • ADR Example: "ADR-0003: Use React as the main framework for frontend development"

❌ Do not document: Choice to use `flexbox` instead of `grid` for a specific layout

  • Why: Local CSS decision, easy to adjust, does not affect architecture.

Pattern for Identifying What to Document

If the decision meets at least 2 of these criteria, consider documenting it in an ADR:

  • ✅ Affects multiple components or modules of the system
  • ✅ Has multiple viable alternatives with significant trade-offs
  • ✅ Is difficult or costly to reverse
  • ✅ Impacts other teams or stakeholders
  • ✅ Generated discussion or debate within the team
  • ✅ Establishes a standard or convention for the project

Conclusion

Architecture Decision Records are much more than documentation. They are a powerful tool for:

  • Communication: Facilitating understanding of architectural decisions
  • Traceability: Maintaining a history of why decisions were made
  • Onboarding: Accelerating the integration of new team members
  • Generative AI: Providing rich context for AI agents

For tech managers, investing in ADRs means investing in architectural clarity and a solid foundation for the efficient use of generative AI. When AI agents have access to well-documented ADRs, they become more effective partners, providing suggestions aligned with the project's architectural decisions.

Start small, document important decisions, and observe how ADRs transform not only documentation but also the quality of interactions with generative AI in your projects.

I hope this guide has brought clarity on how to start with ADRs and how they can supercharge the use of generative AI. I invite you to try this practice in your projects and discover the benefits firsthand.

References and Sources

Articles and Official Documentation

  1. "Documenting Architecture Decisions" - Michael Nygard
  1. "The three hats of a technology leader" - ThoughtWorks
  1. "Level up your developer experience" - ThoughtWorks

Recommended Books

  1. "Software Architecture: The Hard Parts" - Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani
  • O'Reilly Media, 2021
  • Covers difficult architectural decisions and how to document them
  1. "Building Evolutionary Architectures" - Neal Ford, Rebecca Parsons, Patrick Kua
  • O'Reilly Media, 2017
  • Explores evolutionary architecture and the importance of documenting decisions
  1. "Fundamentals of Software Architecture" - Mark Richards, Neal Ford
  • O'Reilly Media, 2020
  • Comprehensive guide on software architecture and documentation practices

Resources from Renowned Companies

  1. Red Hat - "Why you should be using architecture decision records"

Tools and Templates

  1. ADR Tools
  1. ADR GitHub Action
  1. Mermaid Live Editor
  • Online tool to create Mermaid diagrams for ADRs
  • Allows visualizing and testing diagrams before including them in ADRs
  • Available at: https://mermaid.live

Standards and Conventions

  1. MADR (Markdown Architecture Decision Records)
  1. ADR GitHub Organization