Claude Code Integration With Decision Records
Decision Records · January 2025
Two commands. That's all it takes to give Claude Code persistent access to your team's architecture decisions. Here's the complete setup guide.
Teams that document architecture decisions often struggle to make that knowledge accessible when it matters most—during development. Claude Code changes this by connecting directly to your decision repository.
The integration takes two commands. No configuration files, no complex setup. Your AI assistant gains persistent access to every architecture decision your team has documented.
Why Connect Claude Code to Your Decisions?
Claude Code is powerful, but it lacks context about your specific architectural choices. It doesn't know why you chose PostgreSQL over MongoDB, why you went with microservices, or what trade-offs shaped your authentication approach.
When connected to Decision Records, Claude Code can:
- Search your decisions by keywords, status, or content
- Read full decision context including alternatives considered
- Create new decisions as you work (with write permissions)
- Reference past reasoning when suggesting implementations
This means fewer repeated discussions and more context-aware assistance.
Setup in Two Commands
First, get your API key from your Profile Settings page. Then run:
claude mcp add decision-records https://decisionrecords.org/api/mcp \
-t http -H "Authorization: Bearer YOUR_API_KEY"
Verify the connection:
claude mcp list
You should see decision-records listed with a green checkmark. That's it—Claude Code now has access to your team's architecture decisions.
Add Guidelines to Your CLAUDE.md
To make the most of this integration, add guidelines to your project's CLAUDE.md file. This tells Claude Code when and how to use your decision repository.
Copy this section into your CLAUDE.md:
## Architecture Decision Records (ADRs)
This project uses Decision Records (decisionrecords.org) to track
architecture decisions. Use the MCP tools to search, read, and
create decisions.
### When to CREATE a Decision Record
Create a new decision when:
- Making a significant technical choice (new library, service, pattern)
- Changing existing architecture (refactoring, migration)
- Establishing team conventions (coding standards, processes)
- Choosing between multiple valid approaches
### When NOT to Create a Decision
Skip decisions for:
- Bug fixes and minor refactoring
- Version updates without breaking changes
- Routine maintenance tasks
- Implementation details within existing decisions
### Using MCP Tools
Search for relevant decisions before implementing features:
mcp__decision-records__search_decisions(query="authentication")
Get full details of a specific decision:
mcp__decision-records__get_decision(id="ADR-42")
Create a new decision (requires write scope):
mcp__decision-records__create_decision(
title="Use JWT for API authentication",
context="We need stateless auth for the API...",
decision="We will use JWT tokens with...",
consequences="+ Stateless, scalable\n- Token revocation complexity"
)
### Decision Format (arc42)
Follow this structure:
- **Title**: Clear, action-oriented (e.g., "Use PostgreSQL for persistence")
- **Context**: What problem are we solving? What constraints exist?
- **Decision**: What did we decide? Be specific.
- **Consequences**: Both positive (+) and negative (-) impacts
How It Works in Practice
Once configured, the integration becomes seamless. When you ask Claude Code to implement a feature, it can automatically search for relevant decisions.
For example, if you say "implement user authentication", Claude Code might:
- Search decisions for "authentication"
- Find ADR-15: "Use JWT for API authentication"
- Read the full decision context
- Implement authentication aligned with your documented approach
No more implementations that contradict your architecture. No more explaining the same decisions repeatedly.
API Key Permissions
Decision Records API keys support two scopes:
- Read: Search, list, and view decisions (default)
- Write: Create new decisions and update existing ones
For most development workflows, read + write works best. Claude Code can document decisions as they're made, keeping your repository current without manual effort.
Getting Started
Ready to connect Claude Code to your architecture decisions?
- Create a free account if you don't have one
- Generate an API key from your Profile Settings
- Run the two commands above
- Add the CLAUDE.md guidelines to your project
Your AI assistant will never forget your architecture decisions again.