Skip to main content

🏗️ Getting Started: Projects with Existing ADRs

This guide helps you enhance and maintain projects that already have Architectural Decision Records (ADRs). You'll learn how to analyze existing decisions, identify gaps, and keep your ADR collection up-to-date.

💡 NEW: For intelligent workflow recommendations, see the Workflow & Development Guidance guide that provides AI-powered tool sequence recommendations based on your specific goals.

📋 Prerequisites​

Required Software​

  • Node.js ≥18.0.0
  • MCP Client (Claude Desktop, Cline, Cursor, or Windsurf)
  • Existing ADRs in your project

MCP Server Installation​

# Global installation (recommended)
npm install -g mcp-adr-analysis-server

# Verify installation
mcp-adr-analysis-server --version

⚙️ Configuration​

Environment Setup​

export PROJECT_PATH="/path/to/your/project"
export ADR_DIRECTORY="./adrs"  # or wherever your ADRs are located
export LOG_LEVEL="INFO"
export CACHE_ENABLED="true"

MCP Client Configuration​

Claude Desktop​

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "adr-analysis": {
      "command": "mcp-adr-analysis-server",
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

🚀 Step-by-Step Workflow​

Step 1: Discover and Catalog Existing ADRs​

Start by understanding what ADRs you already have:

Tool Call:

discover_existing_adrs

Parameters:

{
  "adrDirectory": "./adrs"
}

What this does:

  • Scans your ADR directory and initializes the .mcp-adr-cache infrastructure
  • Catalogs all existing decisions (or reports none found)
  • Identifies ADR format and structure
  • Creates an inventory of your architectural decisions
  • Always sets up the cache infrastructure, regardless of whether ADRs are found

Expected Output:

  • List of all ADRs with titles, numbers, and status (or "No ADRs found" if none exist)
  • Analysis of ADR quality and completeness
  • Identification of any formatting issues
  • Cache Infrastructure Status: Confirms .mcp-adr-cache setup is complete

💡 Important: discover_existing_adrs always initializes the cache infrastructure that other tools depend on, making it the recommended first step for any project - whether it has existing ADRs or not.

Step 2: Analyze Current Project Architecture​

Understand how your project has evolved since the ADRs were written:

Tool Call:

analyze_project_ecosystem

Parameters:

{}

What this does:

  • Analyzes your current codebase
  • Identifies technology stack and patterns
  • Compares current state with documented decisions
  • Detects architectural drift

Expected Output:

  • Technology stack analysis
  • Architectural patterns in use
  • Dependencies and frameworks
  • Potential inconsistencies with existing ADRs

Step 3: Identify Missing or Outdated Decisions​

Find gaps in your ADR coverage:

Tool Call:

suggest_adrs

Parameters:

{
  "analysisType": "comprehensive",
  "existingAdrs": [
    "Use React for Frontend",
    "PostgreSQL for Database",
    "Microservices Architecture"
  ]
}

What this does:

  • Analyzes code for undocumented decisions
  • Compares current architecture with existing ADRs
  • Suggests new ADRs for implicit decisions
  • Identifies outdated decisions that need updates

Expected Output:

  • List of suggested new ADRs
  • Recommendations for updating existing ADRs
  • Priority ranking for each suggestion

Step 4: Generate Enhanced TDD Action Items​

Create a comprehensive roadmap using the new two-phase TDD approach:

Tool Call:

generate_adr_todo

Parameters:

{
  "scope": "all",
  "phase": "both",
  "linkAdrs": true,
  "includeRules": true
}

What this does:

  • Extracts action items from existing ADRs with TDD approach
  • Links all ADRs for system-wide test coverage
  • Integrates architectural rules validation
  • Creates both test specifications and implementation tasks
  • Generates a prioritized todo list with validation checkpoints

Expected Output:

  • todo.md file with TDD-focused actionable items
  • Test specifications linking all ADRs
  • Implementation tasks with rule compliance checks
  • Production readiness validation criteria

Step 5: Advanced TODO Management​

Use the new TODO management system for complete lifecycle tracking:

Tool Call:

manage_todo

Parameters:

{
  "operation": "analyze_progress",
  "todoPath": "TODO.md",
  "timeframe": "month",
  "includeVelocity": true
}

What this does:

  • Complete TODO.md lifecycle management with smart parsing
  • Task status transitions (pending → in_progress → completed/blocked)
  • Dynamic health scoring integration
  • Progress analytics with velocity metrics
  • Interactive operations with confirmation flows

Advanced TODO Operations:

  • update_status - Update task statuses with notes and assignees
  • add_tasks - Add new tasks to specific sections with metadata
  • merge_adr_updates - Smart merge with ADR-generated tasks
  • sync_progress - Bidirectional sync between TODO.md and ADR status

Step 6: Validate Implementation Progress​

Use the enhanced validation system to ensure quality implementation:

Tool Call:

compare_adr_progress

Parameters:

{
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "deepCodeAnalysis": true,
  "functionalValidation": true,
  "strictMode": true
}

What this does:

  • Validates that implementations meet ADR goals
  • Distinguishes mock implementations from production code
  • Checks functional correctness in realistic environments
  • Provides reality-check mechanisms against LLM overconfidence
  • Validates cross-ADR dependencies and consistency

Expected Output:

  • Comprehensive validation report
  • Mock vs production code analysis
  • ADR goal compliance assessment
  • Actionable recommendations for improving implementation quality

🔄 Ongoing Maintenance Workflows​

Weekly ADR Review​

1. Check for New Decisions

Tool: suggest_adrs
Parameters: {
  "analysisType": "code_changes",
  "commitMessages": ["Recent commit messages from git log"]
}

2. Update Todo List with TDD Approach

Tool: generate_adr_todo
Parameters: {
  "scope": "pending",
  "phase": "both",
  "linkAdrs": true,
  "includeRules": true
}

3. Validate Current Implementation

Tool: compare_adr_progress
Parameters: {
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "strictMode": true
}

Monthly Architecture Audit​

1. Full Project Analysis

Tool: analyze_project_ecosystem
Parameters: {
  "includePatterns": ["*.js", "*.ts", "*.py", "*.java", "package.json"]
}

2. Generate Compliance Rules

Tool: generate_rules
Parameters: {
  "adrDirectory": "./adrs",
  "includeCompliance": true
}

3. Validate Current Code

Tool: validate_rules
Parameters: {
  "projectPath": ".",
  "rulesPath": "./architectural-rules.json"
}

🧪 Enhanced TDD Workflow for Existing ADRs​

When you have existing ADRs, you can use the enhanced TDD workflow to ensure proper implementation:

Phase 1: Generate Test Specifications​

Create comprehensive test specifications from your existing ADRs:

Tool: generate_adr_todo
Parameters: {
  "phase": "test",
  "linkAdrs": true,
  "includeRules": true,
  "outputPath": "todo-tests.md"
}

What this does:

  • Links all existing ADRs to create comprehensive test coverage
  • Generates mock test specifications for each architectural decision
  • Creates system-wide integration tests that validate ADR goals
  • Establishes clear testing boundaries for implementation

Phase 2: Generate Production Implementation​

Create production implementation tasks:

Tool: generate_adr_todo
Parameters: {
  "phase": "production",
  "linkAdrs": true,
  "includeRules": true,
  "outputPath": "todo-implementation.md"
}

What this does:

  • Creates implementation tasks that pass the test specifications
  • Ensures production code meets ADR goals and architectural rules
  • Validates cross-ADR dependencies and consistency
  • Provides clear criteria for production readiness

Validation and Quality Assurance​

Validate TODO completion against ADRs and environment:

Tool: compare_adr_progress
Parameters: {
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "projectPath": ".",
  "deepCodeAnalysis": true,
  "functionalValidation": true,
  "strictMode": true
}

Step 6: Deployment Readiness Validation​

Before deploying any changes based on your ADRs, ensure deployment readiness:

Tool Call:

deployment_readiness

Parameters:

{
  "operation": "full_audit",
  "targetEnvironment": "production",
  "maxTestFailures": 0,
  "requireTestCoverage": 80,
  "deploymentSuccessThreshold": 80,
  "integrateTodoTasks": true,
  "requireAdrCompliance": true
}

What this does:

  • Validates all tests are passing (zero tolerance by default)
  • Checks test coverage meets requirements
  • Analyzes deployment history for patterns
  • Validates ADR compliance in implementation
  • Creates blocking tasks for any issues found

Expected Output:

  • Deployment readiness score and confidence level
  • Test validation results with failure analysis
  • Deployment history patterns and recommendations
  • Critical blockers that must be resolved
  • Emergency override instructions if needed

Step 7: Safe Deployment with Smart Git Push​

Use enhanced git push with deployment readiness checks:

Tool Call:

smart_git_push

Parameters:

{
  "message": "Implement ADR-005: API versioning strategy",
  "branch": "main",
  "checkDeploymentReadiness": true,
  "enforceDeploymentReadiness": true,
  "targetEnvironment": "production",
  "strictDeploymentMode": true
}

What this does:

  • Runs comprehensive deployment readiness checks
  • Blocks push if tests are failing or coverage is low
  • Validates deployment history success rate
  • Enforces ADR compliance before allowing push
  • Provides detailed blocking reports with resolution steps

Validation and Quality Assurance​

Prevent mock implementations from being considered production-ready:

Tool: compare_adr_progress
Parameters: {
  "todoPath": "todo.md",
  "adrDirectory": "./adrs",
  "projectPath": "/path/to/project",
  "deepCodeAnalysis": true,
  "functionalValidation": true,
  "strictMode": true,
  "includeTestCoverage": true,
  "validateDependencies": true
}

Mock Detection Patterns:

  • Detects console.log returns, hardcoded values, TODO comments
  • Identifies missing error handling, input validation
  • Validates real database connections vs mock data
  • Ensures integration tests vs unit tests

📊 Advanced Analysis and AI-Powered Workflows​

AI-Powered Tool Orchestration​

When working with complex multi-step tasks, let AI plan the optimal tool sequence:

Tool Call:

tool_chain_orchestrator

Parameters:

{
  "operation": "generate_plan",
  "userRequest": "Update all ADRs for our microservices migration and ensure TODO tasks are aligned",
  "includeContext": true,
  "optimizeFor": "comprehensive"
}

What this does:

  • AI analyzes your request to generate optimal tool execution sequence
  • Prevents LLM confusion with reality checks and hallucination detection
  • Provides structured execution plans with dependencies
  • Includes confidence scoring and alternative approaches

Human Override for Complex Tasks​

When LLMs get confused or stuck, force AI-powered planning:

Tool Call:

troubleshoot_guided_workflow

Parameters:

{
  "taskDescription": "Review and update ADRs after architecture changes",
  "forceExecution": true,
  "includeContext": true
}

Troubleshooting Workflow​

For systematic problem solving with ADR/TODO alignment:

Tool Call:

troubleshoot_guided_workflow

Parameters:

{
  "operation": "full_workflow",
  "failureType": "build_failure",
  "description": "Build failing after implementing ADR decisions",
  "severity": "high"
}

Smart Project Health Scoring​

Get comprehensive project health metrics across all dimensions:

Tool Call:

smart_score

Parameters:

{
  "operation": "diagnose_scores",
  "includeRecommendations": true,
  "focusAreas": ["todo", "architecture", "deployment"]
}

Research Integration​

When updating or creating new ADRs, incorporate research:

Tool Call:

generate_research_questions

Parameters:

{
  "context": "Evaluating current database choice",
  "scope": "data_architecture",
  "existingDecisions": ["ADR-003: Use PostgreSQL for Primary Database"]
}

Content Security​

Ensure sensitive information is protected in your ADRs:

Tool Call:

analyze_content_security

Parameters:

{
  "content": "Your ADR content",
  "contentType": "documentation"
}

🎯 Common Scenarios​

Scenario 1: New Team Member Onboarding​

Goal: Help new team members understand architectural decisions

Workflow:

  1. discover_existing_adrs - Get complete ADR inventory
  2. Access adr://architectural_knowledge_graph resource
  3. generate_adr_todo with scope "all" - Show current priorities

Scenario 2: Major Refactoring Planning​

Goal: Ensure refactoring aligns with architectural decisions

Workflow:

  1. analyze_project_ecosystem - Understand current state
  2. suggest_adrs with analysis type "comprehensive"
  3. generate_research_questions for areas of uncertainty
  4. validate_rules against proposed changes

Scenario 3: Architecture Review​

Goal: Comprehensive review of architectural decisions

Workflow:

  1. discover_existing_adrs - Catalog current decisions
  2. analyze_project_ecosystem - Check implementation
  3. generate_rules - Extract current architectural rules
  4. validate_rules - Check compliance
  5. suggest_adrs - Identify missing decisions

🔧 Troubleshooting​

Common Issues​

ADRs Not Found

  • Check ADR_DIRECTORY environment variable
  • Ensure ADR files follow naming convention (e.g., 001-decision-title.md)
  • Verify file permissions

Inconsistent Analysis

  • Clear cache: manage_cache with action "clear"
  • Ensure PROJECT_PATH points to correct directory
  • Check for recent code changes

Missing Suggestions

  • Try different analysisType values
  • Include more file patterns in analysis
  • Check if existing ADRs list is complete

📈 Best Practices​

  1. Regular Reviews: Run weekly ADR analysis
  2. Keep ADRs Updated: Use suggested updates from analysis
  3. Document Decisions: Create ADRs for all significant choices
  4. Validate Implementation: Use rule validation regularly
  5. Research Integration: Include research findings in decisions

🔗 Next Steps​

Need Help? Open an issue on GitHub