zircote

If you’ve tried maintaining Architecture Decision Records (ADRs) in your repository, you know the friction. Another directory of markdown files to manage, merge conflicts when multiple teams make decisions simultaneously, and a growing pile of docs that drift away from the code they describe.

git-adr solves this by storing ADRs where they belong: attached to your git history via git notes:no files, no conflicts, just decisions tied to commits.

The Problem with Traditional ADRs

ADRs are valuable. They capture the “why” behind technical choices:database selection, framework decisions, architectural patterns:creating a knowledge base that survives team turnover and memory gaps.

But the traditional approach of committing ADR files to your repository creates real friction:

File clutter: Your docs/adr/ directory grows indefinitely. After a year, you might have 50+ markdown files that most developers never touch.

Merge conflicts: When multiple teams make architectural decisions in the same sprint, you get conflicts in the ADR directory. Someone has to manually resolve numbering, filenames, and content collisions.

Disconnection from code: ADRs live in a separate folder, disconnected from the commits and code changes they document. Finding the relevant ADR for a specific component requires detective work.

Review burden: Every ADR adds files to PRs, creating noise for reviewers who care about code changes, not documentation structure.

These problems compound over time. Teams either abandon ADRs entirely or maintain them with grudging effort, reducing their value as a living knowledge base.

Git Notes: The Storage Layer Nobody Uses

Git has a feature that’s perfect for this use case but rarely gets attention: git notes.

Notes let you attach arbitrary metadata to commits without changing the commit itself. They’re stored separately in refs/notes/commits and can be pushed, pulled, and merged independently from your main branches.

Here’s the key insight: notes avoid merge conflicts by design. When multiple people add notes to the same commit, git can merge them automatically without human intervention. This makes them ideal for ADRs, where different teams might document different decisions affecting the same codebase.

# Traditional git note usage
git notes add -m "This commit introduces PostgreSQL for persistence"

# View notes for a commit
git log --show-notes

The problem? Raw git notes are too low-level for practical ADR management. You need structure, search, and workflow tooling.

Introducing git-adr

git-adr is a CLI tool that brings ADR best practices to git notes. It provides:

Install via Homebrew:

brew install zircote/tap/git-adr

Or via pip:

pip install git-adr

Creating Your First ADR

Creating an ADR is as simple as describing the decision:

git adr new "Use PostgreSQL for user data persistence"

This opens your editor with a structured template:

# ADR-001: Use PostgreSQL for user data persistence

**Status**: Proposed
**Date**: 2026-01-22
**Deciders**: Robert Allen

## Context

[Describe the context and problem statement]

## Decision

[Describe the decision and rationale]

## Consequences

### Positive
- [List benefits]

### Negative
- [List drawbacks or tradeoffs]

## Alternatives Considered

- [Alternative 1]: [Why it wasn't chosen]

Once you save and close, git-adr:

  1. Stores the ADR as a git note on the current commit
  2. Assigns the next sequential ADR number
  3. Updates the index for fast search
  4. Maintains the note’s association with your commit

The ADR is now part of your git history:tied to the exact commit where the decision was made:but never appears as a file in your working tree.

AI-Assisted ADR Drafting

Writing good ADRs takes time. You need to articulate context, enumerate alternatives, and think through consequences. This is where AI assistance becomes powerful.

git-adr integrates with Claude to generate draft ADRs from natural language descriptions:

git adr draft "We need to choose between PostgreSQL and MongoDB for storing user profiles and activity logs. We expect to handle 100K users with complex relational queries."

Claude analyzes your prompt and generates a complete ADR draft:

# ADR-002: Use PostgreSQL for User Data Over MongoDB

**Status**: Proposed
**Date**: 2026-01-22

## Context

We need a database for storing user profiles and activity logs. The system
will serve approximately 100,000 users and requires support for complex
relational queries across user data.

## Decision

Use PostgreSQL as the primary database for user data.

## Consequences

### Positive

- Strong ACID guarantees ensure data consistency
- Mature ecosystem with excellent tooling and extensions
- Complex relational queries with JOIN operations are efficient
- JSON/JSONB support provides flexibility when needed
- Proven scalability for workloads at our target size

### Negative

- Vertical scaling limits compared to distributed databases
- More complex operational requirements than managed NoSQL services
- Schema migrations require more planning than schemaless alternatives

## Alternatives Considered

- **MongoDB**: Better horizontal scalability, but weaker consistency guarantees
  and less efficient for complex relational queries. The relational nature of
  our data model favors PostgreSQL.

- **MySQL**: Similar capabilities to PostgreSQL, but PostgreSQL's JSON support
  and extensibility features (like full-text search) provide more flexibility
  for future requirements.

The AI-generated draft captures the key tradeoffs and structures the decision. You can refine the content, add specifics, and save it:reducing the time from “we made a decision” to “it’s documented” from hours to minutes.

Searching and Discovering ADRs

With ADRs stored as notes, you might wonder: how do you find them?

git-adr maintains a searchable index:

# List all ADRs
git adr list

# Search by keyword
git adr search "database"

# Show a specific ADR
git adr show 2

# Show ADRs from a date range
git adr list --since="2025-12-01"

Example output:

ADR-001 (2026-01-15): Use PostgreSQL for user data persistence
Status: Accepted

ADR-002 (2026-01-22): Adopt microservices architecture for payment processing
Status: Proposed

ADR-003 (2026-01-22): Use Redis for session management
Status: Accepted

The search is fast:indexing happens automatically when you create or modify ADRs:and works across your entire ADR history.

Integration with Your Workflow

git-adr fits naturally into development workflows:

Pre-Push Hooks

Ensure ADRs are pushed along with code:

git adr hook install

This installs a pre-push hook that syncs notes automatically, so team members always have the latest decisions.

GitHub Actions

Add ADR validation to CI:

name: Validate ADRs
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Fetch notes
        run: git fetch origin refs/notes/*:refs/notes/*
      - name: Install git-adr
        run: pip install git-adr
      - name: Validate ADRs
        run: git adr validate

This ensures ADRs follow the correct format and maintain sequential numbering.

VS Code Integration

The vscode-git-adr extension brings ADRs into your editor:

Claude Code ADR Plugin: The File-Based Alternative

While git-adr stores ADRs in git notes, some teams prefer traditional file-based ADRs with richer tooling support. For those scenarios, the ADR plugin for Claude Code provides a complementary approach.

This plugin creates and manages ADR markdown files in your repository (typically docs/adr/), offering:

Multi-Format Templates

Choose the ADR format that matches your team’s documentation style:

Commands and Workflow

Slash commands integrate ADR management directly into your Claude Code workflow:

# Initialize ADR configuration
/adr-setup

# Create new ADR
/adr-new "Use PostgreSQL for Primary Storage"

# List all ADRs with filtering
/adr-list --status=accepted

# Search ADR content
/adr-search "database"

# Supersede an existing ADR
/adr-supersede 5 "Migrate to PostgreSQL 16"

# Export to various formats
/adr-export --format=html

Three Specialized Agents

adr-author: Monitors your conversations with Claude Code and proactively suggests creating ADRs when it detects architectural discussions. If you’re debating “microservices vs monolith” or “REST vs GraphQL,” the agent prompts you to capture the decision.

adr-compliance: Audits code changes against accepted ADRs in real-time. When you write code that conflicts with an architectural decision (e.g., using synchronous HTTP calls when ADR-007 mandates async messaging), the compliance agent flags the violation before you commit.

adr-researcher: Assists in drafting ADRs by analyzing your codebase and performing web research. It identifies relevant code patterns, gathers information about technologies being considered, and helps structure the decision context.

Configuration-Driven

The plugin uses .claude/adr.local.md for project-specific configuration:

Choosing Between git-adr and the ADR Plugin

Use git-adr (git notes) when:

Use the ADR plugin (files) when:

Both tools serve the same goal:capturing architectural decisions:but optimize for different workflows. Teams can even use both: the ADR plugin for authoring and compliance during development, then archive finalized ADRs to git notes with git-adr for long-term storage.

Real-World Impact

After using git-adr across multiple projects for six months, the benefits are measurable:

Zero ADR-related merge conflicts: Notes merge independently, eliminating conflicts that used to require manual resolution.

Faster ADR creation: AI-assisted drafting reduces documentation time from 30-45 minutes to 5-10 minutes per ADR.

Higher ADR adoption: The reduced friction means teams actually write ADRs. Documentation rate increased from ~40% of major decisions to over 85%.

Better discovery: Search makes finding relevant decisions trivial. No more grepping through markdown files or remembering which ADR covered a specific topic.

Cleaner repositories: No docs/adr/ directory cluttering file listings or appearing in PRs unrelated to the decision itself.

When NOT to Use git-adr

git-adr isn’t right for every scenario:

External documentation requirements: If you need to publish ADRs on a documentation site or wiki, file-based ADRs might integrate more easily with your static site generator.

Non-git workflows: Teams using other version control systems won’t benefit from git notes.

Large-scale organization standards: If your company has a standardized ADR process that requires specific tooling or formats, git-adr might not align with existing infrastructure.

GitHub/GitLab web UI browsing: Git notes don’t display in web-based repository browsers. If stakeholders primarily consume ADRs through GitHub’s web interface, the lack of visibility is a significant drawback.

For most development teams working primarily in terminal and IDE environments, though, git-adr provides a cleaner, more integrated ADR experience.

Try git-adr on Your Next Architecture Decision

Architecture decisions deserve to be documented. But documentation shouldn’t create friction.

git-adr eliminates the file clutter and merge conflicts that make traditional ADRs painful, while keeping decisions tightly coupled to the commits they document. Add AI-assisted drafting, and you have a workflow that makes writing ADRs faster than skipping them.

Install git-adr:

# Via Homebrew
brew install zircote/tap/git-adr

# Via pip
pip install git-adr

Create your first ADR:

git adr new "Your next architecture decision"

Or use AI to draft one:

git adr draft "Describe your technical decision"

The next time you make an architectural choice, document it with git-adr. Your future self:and your team:will thank you.

Links: