DEV Community

Cover image for How to Automate ADR Reviews and Keep Your Architectural Decisions in Sync with Your Codebase
Tosin Akinosho
Tosin Akinosho

Posted on

How to Automate ADR Reviews and Keep Your Architectural Decisions in Sync with Your Codebase

#architecture #adr #documentation #automation

The Problem Nobody Talks About

If you've been in software architecture for any time, you know the pain. You carefully document an architectural decision in an ADR (Architectural Decision Record). You link it to pull requests, reference it in code reviews, and feel good about having actual documentation for once. Six months later, that ADR describes a system architecture that hasn't existed for two years.

I've seen this pattern repeat across dozens of teams. ADRs start as living documents and end up as digital dust collectors. New team members read them and make decisions based on outdated information. Code reviews reference constraints that were removed ages ago. And nobody notices until something breaks.

The core issue is that maintaining ADRs manually is time-consuming and easy to skip when deadlines loom. But what if you could automate it? What if an AI agent could review your ADRs against your actual codebase and tell you exactly what needs to be updated?

That's exactly what the ADR Review and Synchronization Prompt enables. Let me walk you through how it works.

Prerequisites

Before you begin, you'll need access to the MCP ADR Analysis Server:

Your ADRs should follow the standard format with status fields (Proposed, Accepted, Deprecated, Superseded, Implemented) stored in a directory like docs/adrs/ or adr/.

Full Prompt 

# ADR Review and Synchronization Prompt

## Persona

You are an expert Senior Software Architect responsible for maintaining the integrity and accuracy of our project's Architectural Decision Records (ADRs). Your primary goal is to ensure that ADRs are not just historical documents, but living artifacts that accurately reflect the current state of the codebase.

**Current Date:** 2026-01-24 20:02:21 EST

## Core Task

Your task is to perform a comprehensive review of all ADRs within the project located at `{PROJECT_PATH}`. You will use the `mcp-adr-analysis-server` to analyze the codebase and compare it against each ADR. The ultimate goal is to synchronize the ADRs with the code, updating their status and content as necessary.

## Step-by-Step Instructions

1.  **Initiate the Review:**
    *   Invoke the `reviewExistingAdrs` tool from the `mcp-adr-analysis-server`.
    *   Set `projectPath` to the root of the project you are analyzing.
    *   Use `analysisDepth: 'comprehensive'` and `includeTreeSitter: true` to ensure the most accurate and in-depth analysis.
    *   Set `generateUpdatePlan: true` to get actionable recommendations.
    *   Example call:

        ```

json
        {
          "tool": "reviewExistingAdrs",
          "args": {
            "projectPath": "{PROJECT_PATH}",
            "adrDirectory": "docs/adrs",
            "analysisDepth": "comprehensive",
            "includeTreeSitter": true,
            "generateUpdatePlan": true
          }
        }


        ```

2.  **Analyze Each ADR:**
    For each ADR returned by the `reviewExistingAdrs` tool, perform the following analysis based on the `complianceScore`, `gaps`, and `recommendations`:

    *   **Case 1: Full Implementation (Compliance Score >= 8.0)**
        *   **Action:** Update the ADR status to `Implemented`.
        *   **Justification:** The code fully implements the decision recorded in the ADR.

    *   **Case 2: Partial Implementation (5.0 <= Compliance Score < 8.0)**
        *   **Action:** Do not change the status. Create a `todo.md` file or update an existing one with tasks to address the identified `gaps`.
        *   **Justification:** The ADR is not fully implemented, and the remaining work needs to be tracked.

    *   **Case 3: Code is a Better Solution**
        *   **Condition:** The analysis indicates that the code has evolved beyond the ADR, implementing a different, but superior, solution.
        *   **Action:**
            1.  Update the ADR content to reflect the new implementation. Clearly state that the original decision was superseded by a better approach and describe the new approach.
            2.  Set the ADR status to `Implemented`.
        *   **Justification:** The ADR should reflect the current, superior state of the architecture.

    *   **Case 4: Not Implemented (Compliance Score < 5.0)**
        *   **Action:** Do not change the status. Review the ADR to determine if it is still relevant. If not, propose to supersede or deprecate it in a separate action.
        *   **Justification:** The decision has not been implemented, and its relevance needs to be re-evaluated.

3.  **Generate Final Report:**
    *   Produce a summary report of the actions taken.
    *   For each ADR, list the file name, original status, new status, and a brief justification for the change.
    *   If a `todo.md` was created or updated, include its content in the report.

## Output Format

Your final output should be a single markdown document containing:

1.  A summary table of all reviewed ADRs with their old and new statuses.
2.  A "Justification" section detailing the reasoning for each change.
3.  The content of the `todo.md` file, if any tasks were generated.

### Example Summary Table

| ADR File | Original Status | New Status | Justification |
| --- | --- | --- | --- |
| `adr-001.md` | Accepted | Implemented | Code fully aligns with the ADR. |
| `adr-002.md` | Accepted | Implemented | Code implements a superior solution; ADR updated. |
| `adr-003.md` | Accepted | Accepted | Partial implementation; tasks added to `todo.md`. |
Enter fullscreen mode Exit fullscreen mode

Step 1: Initiate the ADR Review

The first step is invoking the analysis server to examine your ADRs against your codebase. Here's the core invocation:

{
  "tool": "reviewExistingAdrs",
  "args": {
    "projectPath": "/path/to/your/project",
    "adrDirectory": "docs/adrs",
    "analysisDepth": "comprehensive",
    "includeTreeSitter": true,
    "generateUpdatePlan": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Parameter explanations:

  • projectPath: Root directory of your project
  • adrDirectory: Where your ADRs are stored (e.g., docs/adrs)
  • analysisDepth: Use "comprehensive" for thorough analysis
  • includeTreeSitter: Enables deep code parsing for accurate verification
  • generateUpdatePlan: Produces actionable recommendations

The server analyzes your codebase structure, dependencies, and implementations, then compares findings against each ADR to calculate a compliance score (0-10 scale).

Step 2: Interpret Compliance Scores

The compliance score tells you how well your code matches your documentation:

Score Range Meaning Action
≥ 8.0 Full Implementation Update status to "Implemented"
5.0 - 7.9 Partial Implementation Don't change status; add tasks to todo.md
< 5.0 Not Implemented or Superseded Review relevance; may need to deprecate

Step 3: Handle Each Case

Case 1: Full Implementation (Score ≥ 8.0)

When code fully implements a documented decision:

  1. Update the ADR status to Implemented
  2. Justification: "Code fully aligns with the ADR"

Example:

## Status

- [x] Accepted
- [x] Implemented
- [ ] Deprecated
- [ ] Superseded
Enter fullscreen mode Exit fullscreen mode

Case 2: Partial Implementation (5.0 ≤ Score < 8.0)

When some aspects are implemented but gaps remain:

  1. Keep the current status (typically "Accepted")
  2. Create or update todo.md with tasks to complete implementation

Example todo.md:

# ADR Implementation Tasks

## adr-003.md - API Gateway Integration
- [ ] Implement rate limiting middleware
- [ ] Add circuit breaker configuration
- [ ] Document error handling patterns
Enter fullscreen mode Exit fullscreen mode

Case 3: Code Implements a Better Solution

When the codebase has evolved beyond the ADR with a superior approach:

  1. Update the ADR content to reflect the new implementation
  2. Explain that the original decision was superseded
  3. Set status to Implemented

Update format:

## Status

- [x] Accepted
- [x] Implemented
- [ ] Deprecated
- [x] Superseded by ADR-XXX

**Note:** This ADR was originally accepted for [original approach].
However, during implementation, we discovered [reason for change]
and adopted [new approach] instead. See ADR-XXX for the current implementation.
Enter fullscreen mode Exit fullscreen mode

Case 4: Not Implemented (Score < 5.0)

When an ADR hasn't been implemented and may no longer be relevant:

  1. Do NOT change the status
  2. Review whether the ADR is still relevant
  3. Propose to supersede or deprecate if needed

Step 4: Generate the Final Report

, generateAfter completing your review a summary report documenting changes:

Summary Table Template

ADR File Original Status New Status Justification
adr-001.md Accepted Implemented Code fully aligns with the ADR
adr-002.md Accepted Implemented Code implements a superior solution; ADR updated
adr-003.md Accepted Accepted Partial implementation; tasks added to todo.md

Full Example Workflow

Here's a complete example of the review process:

{
  "tool": "reviewExistingAdrs",
  "args": {
    "projectPath": "/workspace/my-api-project",
    "adrDirectory": "docs/adrs",
    "analysisDepth": "comprehensive",
    "includeTreeSitter": true,
    "generateUpdatePlan": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Sample response from the server:

{
  "adrs": [
    {
      "file": "adr-001.md",
      "title": "Use GraphQL for API Layer",
      "currentStatus": "Accepted",
      "complianceScore": 9.2,
      "gaps": [],
      "recommendations": ["Update status to Implemented"]
    },
    {
      "file": "adr-002.md",
      "title": "Event-Driven Architecture",
      "currentStatus": "Accepted",
      "complianceScore": 6.5,
      "gaps": [
        "Event schema registry not implemented",
        "Dead letter queue configuration missing"
      ],
      "recommendations": ["Create implementation tasks for remaining gaps"]
    },
    {
      "file": "adr-003.md",
      "title": "Monolithic Database",
      "currentStatus": "Accepted",
      "complianceScore": 2.1,
      "gaps": [
        "Codebase has migrated to microservices with separate databases"
      ],
      "recommendations": ["Supersede this ADR with new microservice data patterns"]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Actions taken:

  1. adr-001.md: Status updated to "Implemented"
  2. adr-002.md: Created todo.md with event architecture tasks
  3. adr-003.md: Updated ADR to document microservices migration, status set to "Superseded"

Integration Tips

Here are some practical ways to integrate ADR reviews into your workflow:

Schedule Regular Reviews

  • Add ADR review to your sprint tasks
  • Run before major releases
  • Include in quarterly architecture audits

CI/CD Integration

  • Trigger ADR analysis on significant architectural changes
  • Add compliance checks to pull request automation
  • Fail builds if ADR gaps exceed thresholds

Team Workflow

  • Make ADR updates explicit tasks in story estimation
  • Include ADR review in code review checklists
  • Celebrate teams that keep ADRs synchronized

Benefits of Automated ADR Synchronization

When you make ADR maintenance an ongoing practice rather than an occasional cleanup, you get:

  • Trustworthy onboarding: New team members can rely on ADRs being accurate
  • Effective code reviews: Reviewers can reference current architectural constraints
  • Visible technical debt: Gaps in ADR implementation highlight unfinished work
  • Cultural shift: Documentation becomes valuable rather than optional

Conclusion

ADRs only work when they're accurate. The drift between documentation and implementation is the silent killer of architectural integrity. But with tools like the MCP ADR Analysis Server and a systematic review process, you can keep your ADRs synchronized with reality.

The tools are available at:

What remains is making ADR maintenance an ongoing commitment. Start with one review. See what you find. Then decide how to make it part of your regular workflow.

Top comments (0)