### Preflight Checklist - [x] I have searched [existing requests](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20label%3Aenhancement) and this feature hasn't been requested yet - [x] This is a single feature request (not multiple features) ### Problem Statement Summary Add automatic loading of Architecture Decision Records (ADRs) from ~/.claude/adr/ directory, similar to how CLAUDE.md files are currently loaded. This would allow teams to maintain architectural decisions

[FEATURE] Add support for Architecture Decision Records (ADRs) in ~/.claude/adr/

Resolved 💬 3 comments Opened Dec 13, 2025 by matscederholm Closed Dec 16, 2025

Preflight Checklist

[x] I have searched existing requests and this feature hasn't been requested yet
[x] This is a single feature request (not multiple features)

Problem Statement

Summary

Add automatic loading of Architecture Decision Records (ADRs) from ~/.claude/adr/ directory, similar to how CLAUDE.md files are currently loaded. This would allow teams to maintain architectural decisions as separate, version-controlled documents that Claude Code automatically follows.

Problem / Use Case

Current State:

Teams can document architectural guidance in CLAUDE.md files
Works well for small amounts of guidance
Becomes unwieldy with multiple architectural decisions
No clean separation between different decision domains
Difficult to share and version control individual decisions

Real-World Example:
Our organization has standardized on ADRs for documenting architectural decisions across our platform team. We have decisions covering:

Certificate management strategy (3 different sources: cert-manager, Google Managed Certs, External Secrets)
Database migration patterns
Logging and monitoring standards
Secret management approaches
Deployment strategies

We want Claude Code to automatically follow these decisions without cramming everything into a single CLAUDE.md file.

Proposed Solution

Auto-read all .md files from ~/.claude/adr/ directory at conversation start, similar to how CLAUDE.md is loaded.

Directory Structure

~/.claude/
├── CLAUDE.md # Existing - general preferences
└── adr/ # NEW - architectural decisions
├── 001-certificate-management.md
├── 002-database-strategy.md
├── 003-logging-standards.md
└── 004-secret-management.md

Loading Behavior

All .md files in ~/.claude/adr/ loaded automatically
Numbered files loaded in order (001, 002, 003...)
ADRs available throughout conversation context
No explicit user action needed (like CLAUDE.md)

ADR Format

ADRs would follow the industry-standard format:
# ADR 001: Certificate Management Strategy

Status: Accepted
Date: 2025-01-13

## Context
[Why this decision was needed]

## Decision
[What we decided to do]

## Consequences
[Positive and negative outcomes]

## What Claude Should Do
[Specific guidance for Claude Code]

Benefits

Industry Standard Format

ADRs are a widely-adopted practice in software architecture:

Original format by Michael Nygard (2011)
Recommended by AWS, Azure, Google Cloud
Supported by tools like adr-tools, log4brains
References:
https://adr.github.io/
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/

Better Organization

Each decision is a separate file
Natural versioning (001, 002, 003...)
Easy to find specific decisions
Clean separation of concerns

Team Collaboration

Share ADRs via git repository
Review changes via pull requests
Track decision evolution over time
Onboard new team members with ADR history

Scalability

CLAUDE.md stays focused on preferences
ADRs handle architectural decisions
Add new ADRs without bloating existing files
Archive/supersede old decisions cleanly

Cross-Project Consistency

Same ADRs apply across all repos
Developers symlink team ADR repo to ~/.claude/adr/
Claude follows team standards automatically
No copy-paste into each project's CLAUDE.md

Example Workflow

Team Setup

# Team maintains ADR repository
git clone git@github.com:orgname/platform-adrs.git ~/platform-adrs

# Developers symlink to Claude directory
ln -s ~/platform-adrs/adr ~/.claude/adr

# Claude Code now automatically follows team decisions

Developer Experience

User: "I need to add TLS to this service"

Claude: "Based on ADR-001 (Certificate Management), this is an internal
service in cluster-x, so I'll create a cert-manager Certificate
resource with Let's Encrypt. I'll add it to certificate.yaml following
your naming convention."

Additional Context

This feature would complement existing Claude Code features:

CLAUDE.md: Personal/project preferences
ADRs: Team architectural decisions
Skills: Reusable automation
MCP Servers: External tool integration

Together they create a comprehensive customization story.

Proposed Solution

Technical Proposal

Implementation Options

Option 1: Simple File Loading (Minimum Viable)

Scan ~/.claude/adr/*.md on conversation start
Load in alphabetical/numerical order
Treat as additional context (like CLAUDE.md)

Option 2: Structured ADR Support (Enhanced)

Parse ADR metadata (status, date, supersedes)
Only load "Accepted" ADRs
Skip "Superseded" or "Deprecated" ADRs
Show ADR references in responses ("per ADR-001...")

Option 3: Smart Indexing (Future)

Index ADR topics/keywords
Load relevant ADRs based on conversation context
Reduce token usage for large ADR collections

Backward Compatibility

Completely opt-in (no ~/.claude/adr/ = no change)
Existing CLAUDE.md behavior unchanged
No breaking changes to current workflows

Alternative Considered

Using CLAUDE.md: Currently possible but:

❌ Single file becomes large and unwieldy
❌ Difficult to share specific decisions
❌ No natural versioning/numbering
❌ Hard to track decision evolution
❌ Mixing preferences with architectural decisions

Success Criteria

After implementation:

Developers can place ADRs in ~/.claude/adr/
Claude Code automatically loads them on conversation start
Claude references ADRs when making suggestions ("per ADR-001...")
Teams can share ADR repos across organization
No impact to users without ~/.claude/adr/ directory

Real-World Value

Our team would immediately benefit:

~10-15 architectural decisions to codify
Platform team of 10+ engineers
Multiple repos (infrastructure, config, Terraform)
Consistent patterns across projects
Reduced "tribal knowledge" problem
Better onboarding for new team members

Alternative Solutions

It will be a lot of text in CLAUDE.md otherwise and hard to keep up to date.

Priority

Medium - Would be very helpful

Feature Category

CLI commands and flags

Use Case Example

I ended up with claude suggesting this for my use case and I filled out what he asked and then he came to it and understood that this was not in the implementation. However as I saw this as a great way to propagate organisation knowledge (as we already use adr) I thought it best to at least propose this.

Additional Context

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗