Opinionated Workflow Guide

A prescriptive, step-by-step approach to professional software development using developer-tools-mcp. This workflow removes decision fatigue by providing a single, battle-tested path from idea to deployment.

Prerequisites

This workflow requires the developer-tools-mcp server. See MCP Servers for installation instructions.

Core Workflow Commands

The developer-tools-mcp workflow provides these essential commands:

Project & Context Management

/project-init           # Initialize AI-friendly project structure
/project-update        # Analyze and update project documentation
/context-prime         # Load project understanding for AI
/record                # Maintain scratchpads for tracking information

Specification Workflow

/project-prp           # Create Product Requirements Prompt for gathering requirements
/spec-generate         # Create detailed specifications from requirements
/spec-implement        # Transform specs into working code
/spec-finish           # Mark specifications as implemented
/test-generate         # Create comprehensive test suites

Version Control

/git-status            # Enhanced status with change analysis
/git-stage             # Intelligent file staging
/git-commit            # Create semantic commits
/git-push              # Push with branch management
/git-pr                # Generate structured pull requests

Complete Project Lifecycle

1. Project Initialization

Start every new project with proper structure:

# Create and enter project directory
mkdir my-web-app && cd my-web-app
git init

# Start Claude
claude

# Initialize AI-friendly structure
/project-init

# What gets created:
# - ai-docs/CONTEXT.md (project vision)
# - CLAUDE.md (coding conventions)
# - specs/ (specification directory)
# - .gitignore (with AI-specific patterns)

Expected Output: Project structure with templated documentation ready for AI understanding.

2. Project Analysis and Updates

Keep project documentation synchronized with code changes:

# Start Claude
claude

# Analyze existing codebase and update documentation
/project-update

# Or focus on specific areas
/project-update --focus architecture
/project-update --focus api

# What happens:
# - Analyzes code structure and patterns
# - Updates ai-docs/ with discovered conventions
# - Documents new architectural patterns
# - Creates missing documentation files

3. Context Priming and Recording

Before any development work, establish AI context and set up recording:

# Start Claude
claude

# Load project understanding
/context-prime "Building a task management web app with user authentication"

# What happens:
# - Reads ai-docs/ for existing context
# - Understands project architecture and patterns
# - Identifies active specifications
# - Assesses confidence level for next actions

# Set up continuous recording for complex tasks
/record "debugging session findings"

# What happens:
# - Creates scratchpads/ directory
# - Maintains topic-based notes throughout session
# - Records decisions, findings, and solutions
# - Preserves knowledge across sessions

Confidence Routing:

• ≥0.8: Proceed with autonomous development
• 0.7-0.8: Provide explanations before proceeding
• <0.7: Enter interactive mode with clarifying questions

4. Requirements Gathering (Optional)

For complex features with unclear requirements:

# Create structured requirements document
/project-prp "real-time collaboration feature"

# What happens:
# - Creates requirements/feature-name.md
# - Provides structured template for requirements
# - Guides through systematic requirements gathering
# - Collects examples and constraints
# - Improves specification confidence

This step is automatically suggested when /spec-generate confidence is below 0.7.

5. Specification-Driven Development

Create detailed specifications before writing code:

# Start Claude
claude

# Generate comprehensive specification
/spec-generate "User authentication system with JWT tokens, password reset, and OAuth integration"

# Interactive refinement (if needed)
Add rate limiting to login attempts
Include email verification for new accounts

Generated Specification Structure:

• 🎯 Executive Summary: Clear objectives and business value
• 🔷 High Level Objective: Goals, research, and constraints
• 🔶 Self Validation: Consistency checks and requirement gaps
• 🔵 Product Schema: Technical architecture and interfaces
• ⚡ Action: Implementation steps and validation criteria

6. Implementation

Transform specifications into working code:

# In Claude chat:
/spec-implement

# What happens:
# - Reads the specification thoroughly
# - Analyzes existing codebase patterns
# - Generates complete, production-ready code
# - Creates or updates multiple files systematically
# - Follows project conventions from CLAUDE.md

Implementation Features:

• Extends existing code rather than replacing
• Includes comprehensive error handling
• Follows established project patterns
• Creates database migrations if needed
• Updates configuration files

7. Testing Strategy

Generate comprehensive test suites:

# In Claude chat:
/test-generate

# Generate from BDD scenarios in specification
/test-generate --from-bdd

# Focus on specific components
/test-generate --files src/auth/

# Update existing tests with missing cases
/test-generate --update

Testing Philosophy:

• Integration-first: Mock only external dependencies (APIs, databases)
• Behavior-focused: Test observable outcomes, not implementation details
• Comprehensive coverage: Happy path, edge cases, and error scenarios

8. Version Control Workflow

Professional git workflow with semantic commits:

# In Claude chat:

# Check repository status with change analysis
/git-status
# Shows:
# - Current branch and upstream status
# - Uncommitted changes with suggestions
# - Recommended next actions

# Stage files intelligently
/git-stage
# Or stage specific files/patterns
/git-stage "src/**/*.ts"
# Features:
# - Smart file selection
# - Ignores build artifacts
# - Groups related changes

# Create semantic commit with conventional format
/git-commit
# Analyzes changes and generates: "feat(auth): implement JWT authentication with OAuth integration"
# Or force immediate commit without confirmation
/git-commit --force

# Push to remote with branch management
/git-push
# Handles:
# - Sets upstream for new branches
# - Suggests PR creation after push
# - Shows remote URL for quick access

# Create comprehensive pull request
/git-pr
# Generates PR with summary, test plan, and breaking change notes

9. Specification Completion

Mark specifications as implemented and organize:

# After implementation and testing
/spec-finish

# Or specify particular spec
/spec-finish --spec specs/user-authentication.md

# What happens:
# - Updates specification status metadata
# - Optionally moves to specs/implemented/
# - Creates git commit for completion
# - Updates project documentation

Example: Complete Feature Development

Building a user profile system from start to finish:

# Start Claude
claude

# 1. Analyze existing codebase
/project-update --focus models

# 2. Establish context and recording
/context-prime "Adding user profile management to existing app"
/record "profile feature implementation"

# 3. Gather requirements (if complex)
/project-prp "user profile management system"
# Interactive requirements gathering...

# 4. Create specification
/spec-generate "User profile editing with avatar upload, validation, and privacy settings"

# 5. Refine requirements (interactive)
Add profile picture size limits and format validation
Include audit logging for profile changes
Add bulk privacy setting updates

# 6. Implement the feature
/spec-implement
# Creates:
# - Profile editing components
# - Avatar upload handling
# - Database schema updates
# - API endpoints with validation
# - Privacy setting management

# 7. Generate comprehensive tests
/test-generate
# Creates:
# - Integration tests for profile workflows
# - Upload validation tests
# - Privacy setting tests
# - API endpoint tests
# - Error scenario tests

# 8. Version control workflow
/git-status                    # Review changes
/git-stage                     # Stage all relevant files
/git-commit                    # Create semantic commit
# Result: "feat(profile): add user profile editing with avatar upload and privacy controls"

# 9. Push and create PR
/git-push                      # Push to remote
/git-pr                        # Generate structured PR

# 10. Mark specification complete
/spec-finish --spec specs/user-profiles.md

Project Structure

Expected directory layout after initialization:

my-web-app/
├── ai-docs/                    # AI context documentation
│   ├── CONTEXT.md             # Project vision and overview
│   ├── ARCHITECTURE.md        # System design (created as needed)
│   ├── PATTERNS.md            # Code conventions (created as needed)
│   └── WORKFLOWS.md           # Team processes (created as needed)
├── specs/                     # Active specifications
│   ├── user-authentication.md
│   ├── user-profiles.md
│   └── implemented/           # Completed specifications
├── src/                       # Source code
├── tests/                     # Test suites
├── CLAUDE.md                  # Project coding conventions
├── package.json               # Dependencies and scripts
└── README.md                  # User documentation

Real-World Examples

Debugging Production Issue

# Start Claude
claude

# Load context for debugging session
/context-prime "Investigating memory leak in user session handling"

# Create specification for the fix
/spec-generate "Fix memory leak in session management with proper cleanup and monitoring"

# Implement the solution
/spec-implement

# Create tests to prevent regression
/test-generate --focus memory

# Commit with proper urgency indicators
/git-commit
# Result: "fix(critical): resolve memory leak in session cleanup"

Adding Third-Party Integration

# Start Claude
claude

# Context for integration work
/context-prime "Integrating Stripe payment processing"

# Comprehensive specification
/spec-generate "Stripe payment integration with webhook handling, subscription management, and error recovery"

# Implementation with external dependencies
/spec-implement
# Handles:
# - API key configuration
# - Webhook endpoint creation
# - Payment flow implementation
# - Error handling and retry logic

# Integration-focused testing
/test-generate --strategy integration
# Mocks Stripe API calls but tests real integration logic

# Secure commit handling
/git-commit
# Ensures no API keys are committed

Database Migration

# Start Claude
claude

# Context for schema changes
/context-prime "Adding user roles and permissions system"

# Detailed migration specification
/spec-generate "Database migration for role-based access control with user groups and granular permissions"

# Implementation includes migration scripts
/spec-implement
# Creates:
# - Migration files with rollback capability
# - Model updates
# - Permission checking middleware
# - Admin interface updates

# Test migration scenarios
/test-generate --focus migration

# Careful version control
/git-commit
# Result: "feat(db): add role-based access control with migration"

Best Practices

Start Every Session with Context

# Start Claude first
claude

# Always begin with context loading
/context-prime

# Or specify focus area
/context-prime "working on API performance optimization"

Trust the Specification Process

• Don't skip specifications for complex features
• Let the AI ask clarifying questions when confidence is low
• Refine specifications before implementation
• Use specifications as contracts with stakeholders

Leverage Confidence-Based Routing

• High confidence: Let tools work autonomously
• Medium confidence: Review explanations before proceeding
• Low confidence: Engage in interactive refinement
• Very low confidence: Provide more context or examples

Maintain Project Knowledge

# In Claude chat:
/project-update --focus architecture

# Keep CLAUDE.md current with team conventions
# Update ai-docs/ with new architectural decisions

Use Progressive Enhancement

Start simple and add complexity:

# Start Claude
claude

# 1. Basic feature specification
/spec-generate "Basic user login with email/password"

# 2. Implement core functionality
/spec-implement

# 3. Add complexity in follow-up specifications
/spec-generate "Add OAuth login options to existing authentication"

Integration with Deployment

Preparing for Production

# Start Claude
claude

# Generate deployment specification
/spec-generate "Production deployment with Docker, monitoring, and CI/CD pipeline"

# Implement deployment configuration
/spec-implement
# Creates:
# - Dockerfile and docker-compose.yml
# - CI/CD pipeline configuration
# - Environment-specific configuration
# - Health check endpoints
# - Monitoring setup

# Test deployment process
/test-generate --strategy e2e

Monitoring and Maintenance

# Start Claude
claude

# Create maintenance procedures
/spec-generate "Production monitoring and incident response procedures"

# Implement monitoring tools
/spec-implement
# Adds:
# - Application metrics
# - Error tracking
# - Performance monitoring
# - Automated alerting
# - Log aggregation

Philosophy

The opinionated workflow succeeds because it:

1. Eliminates Choice Paralysis: One proven path instead of endless options
2. Builds Quality In: Testing and documentation happen automatically
3. Maintains Consistency: Specifications ensure predictable outcomes
4. Scales with Complexity: Confidence-based routing adapts to task difficulty
5. Preserves Knowledge: AI context grows with the project
6. Supports Collaboration: Specifications serve as team contracts

This workflow transforms development from ad-hoc coding into systematic engineering, producing maintainable, well-tested, and thoroughly documented software systems.

Next Steps

• Using Subagents - Scale to complex multi-agent coordination
• Troubleshooting - Solve common workflow issues
• MCP Servers - Extend capabilities with additional servers