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

[matscederholm]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• 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

1. 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/

2. Better Organization

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

3. Team Collaboration

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

4. Scalability

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

5. 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

[github-actions]

Found 1 possible duplicate issue:

1. [FEATURE] Support global prompt templates path (e.g., ~/.claude/prompts/) #13633

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #13633.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.