Skip to main content

📋 Getting Started: New Projects with PRD.md

This guide helps you bootstrap architectural decisions for new projects using a Product Requirements Document (PRD.md). You'll learn how to automatically generate ADRs from requirements and create a solid architectural foundation.

📋 Prerequisites​

Required Software​

  • Node.js ≥18.0.0
  • MCP Client (Claude Desktop, Cline, Cursor, or Windsurf)
  • PRD.md file with your project requirements

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/new/project"
export ADR_DIRECTORY="./adrs"
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/new/project",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "EXECUTION_MODE": "full",
        "AI_MODEL": "anthropic/claude-3-sonnet",
        "ADR_DIRECTORY": "./adrs",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

📝 PRD.md Requirements​

Your PRD.md should include these sections for optimal ADR generation:

# Product Requirements Document

## Technical Requirements
- Performance requirements
- Scalability needs
- Security requirements
- Integration requirements

## Architecture Constraints
- Technology preferences
- Platform requirements
- Compliance needs
- Budget constraints

## Non-Functional Requirements
- Availability requirements
- Maintainability needs
- Monitoring requirements

🚀 Step-by-Step Workflow​

Step 1: Generate ADRs from PRD​

Transform your requirements into architectural decisions:

Tool Call:

generate_adrs_from_prd

Parameters:

{
  "prdPath": "PRD.md",
  "outputDirectory": "./adrs"
}

What this does:

  • Analyzes your PRD.md file
  • Identifies architectural decision points
  • Generates appropriate ADRs for each decision
  • Creates properly formatted ADR files

Expected Output:

  • Multiple ADR files in ././adrs/ directory
  • Each ADR addresses a specific architectural decision
  • ADRs follow standard format (Context, Decision, Consequences)
  • Numbered sequence (001-xxx.md, 002-xxx.md, etc.)

Step 2: Validate Generated Decisions​

Ensure the generated ADRs make sense for your project:

Tool Call:

analyze_project_ecosystem

Parameters:

{}

What this does:

  • Analyzes your project structure (if any exists)
  • Validates ADR decisions against project context
  • Identifies potential conflicts or gaps
  • Suggests refinements

Expected Output:

  • Validation report for generated ADRs
  • Recommendations for adjustments
  • Technology stack compatibility analysis

Step 3: Create Enhanced TDD Implementation Roadmap​

Generate actionable tasks using the new two-phase TDD approach:

Tool Call:

generate_adr_todo

Parameters:

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

What this does:

  • Extracts implementation tasks from ADRs with TDD approach
  • Links all ADRs to create system-wide test coverage
  • Integrates architectural rules validation
  • Creates both test specifications and implementation tasks
  • Generates comprehensive development roadmap with validation checkpoints

Expected Output:

  • todo.md file with TDD-focused implementation tasks
  • Test specifications linking all ADRs for comprehensive coverage
  • Implementation tasks with architectural rule compliance checks
  • Prioritized list of architectural work with production readiness criteria
  • Dependencies and sequencing information with validation gates

Step 4: AI-Powered Development Planning​

Let AI orchestrate your implementation workflow based on PRD requirements:

Tool Call:

tool_chain_orchestrator

Parameters:

{
  "operation": "generate_plan",
  "userRequest": "Implement PRD requirements with full ADR coverage and deployment readiness",
  "includeContext": true,
  "optimizeFor": "prd_implementation"
}

What this does:

  • AI analyzes PRD-generated ADRs to create optimal implementation sequence
  • Generates comprehensive tool execution plan with dependencies
  • Provides structured workflow preventing implementation gaps
  • Includes confidence scoring and alternative approaches

Step 5: Advanced Deployment Guidance​

Generate comprehensive deployment guidance from your ADRs:

Tool Call:

generate_deployment_guidance

Parameters:

{
  "adrDirectory": "./adrs",
  "environmentType": "production",
  "includeInfrastructure": true,
  "includeSecurityChecklist": true,
  "technologyFilter": ["web", "database", "api"]
}

What this does:

  • Extracts deployment requirements from ADR technology decisions
  • Generates environment-specific deployment procedures
  • Creates comprehensive infrastructure setup guides
  • Provides actionable deployment instructions with commands
  • Includes security checklists and validation procedures

Step 6: Smart Project Health Monitoring​

Track implementation progress against PRD goals:

Tool Call:

smart_score

Parameters:

{
  "operation": "sync_scores",
  "includeWeightOptimization": true,
  "focusAreas": ["todo", "architecture", "deployment", "prd_compliance"]
}

Step 7: Establish Quality Validation Framework​

Set up validation to ensure implementations meet ADR goals from the start:

Tool Call:

compare_adr_progress

Parameters:

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

What this does:

  • Establishes quality gates for new implementations
  • Sets up mock vs production code detection patterns
  • Creates validation criteria for each ADR goal
  • Provides reality-check mechanisms for implementation progress
  • Validates cross-ADR dependencies and system consistency
  • Ensures implementations meet original PRD requirements

Expected Output:

  • Quality validation framework configuration
  • Implementation standards and patterns
  • Validation checkpoints for each development phase
  • Clear criteria for production readiness assessment
  • PRD compliance validation reports

Step 8: Research Critical Decisions​

For complex decisions, generate research questions:

Tool Call:

generate_research_questions

Parameters:

{
  "context": "Database selection for high-traffic application",
  "scope": "data_architecture",
  "researchAreas": ["performance", "scalability", "cost"]
}

What this does:

  • Identifies areas needing additional research
  • Generates specific research questions
  • Creates research tracking templates
  • Suggests validation approaches

🔄 Iterative Refinement​

Refining Generated ADRs​

1. Review and Enhance

Tool: suggest_adrs
Parameters: {
  "analysisType": "comprehensive",
  "existingAdrs": ["Generated ADR titles"]
}

2. Add Missing Decisions

Tool: generate_adr_from_decision
Parameters: {
  "decisionData": {
    "title": "Additional Decision Title",
    "context": "Context from PRD analysis",
    "decision": "Specific architectural choice",
    "consequences": "Expected outcomes"
  }
}

Incorporating Research Findings​

Tool Call:

incorporate_research

Parameters:

{
  "researchFindings": "Research results and conclusions",
  "targetAdr": "001-database-selection.md",
  "updateType": "enhance"
}

🎯 Common PRD Scenarios​

Scenario 1: Web Application​

PRD Focus: User interface, API design, data management

Expected ADRs:

  • Frontend framework selection
  • API architecture (REST/GraphQL)
  • Database choice
  • Authentication strategy
  • Deployment architecture

Key Tools:

  1. generate_adrs_from_prd - Initial generation
  2. suggest_adrs - Fill gaps (caching, monitoring, etc.)
  3. generate_research_questions - For complex choices

Scenario 2: Microservices Platform​

PRD Focus: Scalability, service boundaries, data consistency

Expected ADRs:

  • Service decomposition strategy
  • Inter-service communication
  • Data management approach
  • Service discovery mechanism
  • Monitoring and observability

Key Tools:

  1. generate_adrs_from_prd - Core architecture
  2. analyze_environment - Platform constraints
  3. generate_rules - Service design principles

Scenario 3: Mobile Application​

PRD Focus: Platform support, offline capabilities, performance

Expected ADRs:

  • Platform strategy (native/cross-platform)
  • State management approach
  • Offline data strategy
  • Push notification system
  • App store deployment

🧪 TDD Workflow for PRD-Based Projects​

When starting from a PRD, the TDD workflow ensures your implementation matches the requirements:

Phase 1: Generate Test Specifications from PRD-Generated ADRs​

Create comprehensive test specifications:

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

Benefits for PRD-based projects:

  • Validates that all PRD requirements are testable
  • Creates system-wide test coverage based on architectural decisions
  • Establishes clear acceptance criteria for each requirement
  • Links business requirements to technical implementation through ADRs

Phase 2: Generate Production Implementation from Tests​

Create implementation roadmap:

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

Benefits for PRD-based projects:

  • Ensures implementation directly addresses PRD requirements
  • Maintains traceability from PRD to ADRs to implementation
  • Includes architectural rule compliance for all PRD-driven decisions
  • Provides clear production readiness criteria

Validation Against PRD Requirements​

Ensure implementations meet original PRD goals:

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

PRD-specific validation patterns:

  • Verifies functional requirements are actually implemented
  • Checks non-functional requirements (performance, security) are met
  • Validates business logic matches PRD specifications
  • Ensures user experience requirements are addressed
  • Confirms compliance requirements are satisfied

Common PRD Implementation Pitfalls to Avoid​

The validation system helps prevent:

Requirements Drift:

  • Mock implementations that don't meet actual PRD requirements
  • Features that work in isolation but don't integrate properly
  • Performance implementations that don't meet PRD criteria
  • Security implementations that don't address PRD compliance needs

Traceability Loss:

  • Code that implements features not described in the PRD
  • Missing implementations for critical PRD requirements
  • ADRs that don't align with actual PRD priorities
  • Tests that don't validate real PRD acceptance criteria

📊 Advanced Features and AI-Powered Workflows​

AI-Powered Troubleshooting​

When implementing PRD requirements runs into issues:

Tool Call:

troubleshoot_guided_workflow

Parameters:

{
  "operation": "full_workflow",
  "failureType": "deployment_failure",
  "description": "PRD implementation deployment failing in production environment",
  "severity": "high"
}

What this does:

  • Systematic analysis of implementation vs PRD requirements
  • AI-generated test plans with specific diagnostic commands
  • Integration with other MCP tools for comprehensive troubleshooting
  • Fallback templates when AI services are unavailable

Human Override for Complex PRD Tasks​

When LLMs get confused during complex PRD implementation:

Tool Call:

troubleshoot_guided_workflow

Parameters:

{
  "taskDescription": "Implement complex microservices architecture from PRD requirements with full deployment pipeline",
  "forceExecution": true,
  "includeContext": true
}

What this does:

  • Forces AI-powered planning through OpenRouter.ai
  • Cuts through LLM confusion with structured execution plans
  • Provides clear command schemas for complex PRD implementation
  • Includes confidence scoring and detailed execution notes

Deployment Readiness for PRD Projects​

Validate your PRD implementation is ready for production:

Tool Call:

deployment_readiness

Parameters:

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

PRD-specific validation:

  • Validates all PRD requirements have passing tests
  • Ensures test coverage meets requirements
  • Checks deployment history for stability
  • Validates ADR compliance with PRD goals
  • Creates blocking tasks for any gaps

Expected Output:

  • Deployment readiness score with PRD alignment
  • Test validation covering all PRD requirements
  • Critical blockers linked to specific PRD sections
  • Clear resolution steps for each issue

Smart Git Operations for PRD Projects​

Deploy with confidence using deployment-aware git push:

Tool Call:

smart_git_push

Parameters:

{
  "message": "Implement core PRD requirements with ADR compliance",
  "branch": "main",
  "checkDeploymentReadiness": true,
  "enforceDeploymentReadiness": true,
  "targetEnvironment": "production",
  "strictDeploymentMode": true
}

What this does:

  • Runs deployment readiness checks before push
  • Validates PRD implementation completeness
  • Blocks push if critical PRD requirements are missing
  • Ensures all tests are passing
  • Provides detailed failure reports with PRD traceability

Environment Analysis​

Understand deployment and operational context:

Tool Call:

analyze_environment

Parameters:

{
  "environmentType": "cloud",
  "constraints": ["budget", "compliance", "performance"]
}

Rule Generation​

Create architectural guidelines from your ADRs:

Tool Call:

generate_rules

Parameters:

{
  "adrDirectory": "./adrs",
  "includeCompliance": true,
  "outputFormat": "json"
}

Action Confirmation​

For critical implementation steps:

Tool Call:

request_action_confirmation

Parameters:

{
  "proposedAction": "Implement database migration strategy",
  "impactAssessment": "High - affects all data operations",
  "alternatives": ["Alternative approaches"]
}

🔧 Troubleshooting​

Common Issues​

PRD Not Parsed Correctly

  • Ensure PRD.md follows standard markdown format
  • Include clear section headers
  • Provide specific technical requirements

Generated ADRs Too Generic

  • Add more technical details to PRD
  • Include specific constraints and preferences
  • Use suggest_adrs to add missing specifics

Missing Critical Decisions

  • Review generated ADRs for gaps
  • Use analyze_project_ecosystem for validation
  • Manually create ADRs for missed decisions

📈 Best Practices​

  1. Detailed PRD: Include technical constraints and preferences
  2. Iterative Approach: Generate, review, refine ADRs
  3. Research Integration: Use research tools for complex decisions
  4. Validation: Check ADRs against project constraints
  5. Implementation Planning: Use todo generation for roadmap

🔄 Next Steps After ADR Generation​

1. Team Review​

  • Share generated ADRs with team
  • Gather feedback and refinements
  • Update ADRs based on team input

2. Implementation Planning​

  • Use generate_adr_todo for detailed tasks
  • Prioritize implementation order
  • Identify dependencies and risks

3. Ongoing Maintenance​

  • Set up regular ADR reviews
  • Use suggest_adrs for new decisions
  • Validate implementation against ADRs

🔗 Related Documentation​

Need Help? Open an issue on GitHub