Human-AI PDCA Collaboration Framework

A disciplined framework for AI-assisted code generation using Plan-Do-Check-Act methodology with strict TDD discipline.

Two Ways to Use This Framework

Option 1: Claude Skill (Recommended for Regular Use)

Install once, auto-triggers when coding

• Best for: Consistent workflow across all coding sessions
• Setup: One-click installation in Claude.ai or Claude Code
• Experience: Automatic prompt loading, progressive disclosure
• Token efficiency: Loads only what's needed in background
• Maintenance: Update once, improves everywhere

📦 Get started with the Claude Skill →

Option 2: Manual Prompts (Best for Customization)

Copy/paste prompts as needed for each session

• Best for: Customizing prompts for specific contexts
• Setup: Create symlinks or copy files to .claude/ directory
• Experience: 100% visible in conversation, full control
• Flexibility: Easy to customize per-session
• Portability: Works with any AI tool, not just Claude

📝 Get started with Manual Prompts →

---

Which Option Should I Choose?

Use Case	Recommended Approach
Learning the framework	Start with Manual Prompts to understand each phase
Regular coding sessions	Use the Claude Skill for convenience
Team standardization	Claude Skill ensures consistency
Custom workflows	Manual Prompts for full flexibility
Non-Claude AI tools	Manual Prompts (skill is Claude-specific)

You can use both! Many users install the skill for daily work and keep manual prompts for special cases.

---

PDCA Framework Overview

The PDCA workflow consists of four phases:

1. Plan - Analysis and detailed planning
2. Do - Test-driven implementation
3. Check - Completeness verification
4. Act - Retrospection and continuous improvement

---

Manual Prompt Setup (Claude Code)

The rest of this document describes how to set up the manual prompt workflow in Claude Code using symlinked files.

For the Claude Skill setup, see claude-skill/README.md instead.

Prerequisites

• Windows 10/11 with Developer Mode enabled (for symlinks without admin rights)
• Claude Code CLI installed
• Git configured with core.symlinks = true

Project Structure

After setup, your project should have:

your-project/
├── .claude/
│   ├── instructions.md          # Main workflow instructions
│   ├── prompts/                 # Symlinked phase templates
│   │   ├── 1a Analyze to determine approach for achieving the goal.md
│   │   ├── 1b Create a detailed implementation plan.md
│   │   ├── 2. Test Drive the Change.md
│   │   ├── 3. Completeness Check.md
│   │   └── 4. Retrospect for continuous improvement.md
│   └── validation.md            # Pre-commit checklist
├── .claudeignore                # Files for Claude to ignore
└── LinkPrompts.ps1              # Script to create symlinks (optional)

Setup Steps

1. Enable Developer Mode (Windows)

To create symlinks without admin rights:

1. Open Settings → Update & Security → For Developers
2. Turn on Developer Mode
3. Restart PowerShell/Terminal

2. Configure Git for Symlinks

git config core.symlinks true

3. Create Directory Structure

From your project root:

# Create .claude directory structure
New-Item -ItemType Directory -Path ".claude\prompts" -Force

4. Create Symlinks to Prompt Templates

Option A: Manual Creation

# From your project root
# Replace $TEMPLATES_PATH with your actual path to the PDCA templates
$TEMPLATES_PATH = "C:\path\to\pdca-templates"

New-Item -ItemType SymbolicLink -Path ".claude\prompts\1a Analyze to determine approach for achieving the goal.md" -Target "$TEMPLATES_PATH\1. Plan\1a Analyze to determine approach for achieving the goal.md"
New-Item -ItemType SymbolicLink -Path ".claude\prompts\1b Create a detailed implementation plan.md" -Target "$TEMPLATES_PATH\1. Plan\1b Create a detailed implementation plan.md"
New-Item -ItemType SymbolicLink -Path ".claude\prompts\2. Test Drive the Change.md" -Target "$TEMPLATES_PATH\2. Do\2. Test Drive the Change.md"
New-Item -ItemType SymbolicLink -Path ".claude\prompts\3. Completeness Check.md" -Target "$TEMPLATES_PATH\3. Check\3. Completeness Check.md"
New-Item -ItemType SymbolicLink -Path ".claude\prompts\4. Retrospect for continuous improvement.md" -Target "$TEMPLATES_PATH\4. Act\4. Retrospect for continuous improvement.md"

Option B: Using Script

Create LinkPrompts.ps1 in your project root (or a shared location) and run it from each project directory.

5. Create .claudeignore

Create .claudeignore in your project root with appropriate patterns for your C# project (see section below).

6. Create .claude/instructions.md

Create the main instructions file that Claude Code will read automatically (see section below).

7. Create .claude/validation.md (Optional)

Create a validation checklist for pre-commit checks (see section below).

Configuration Files

.claude/instructions.md

# Project Development Workflow

This project follows a strict PDCA (Plan-Do-Check-Act) development process with TDD discipline.

## Workflow Phases

### Phase 1a: Analysis (MANDATORY FIRST)
- Execute codebase_search to discover existing patterns
- Validate external system formats before making assumptions
- Document architectural constraints
- Assess delegation complexity

### Phase 1b: Planning
- Create numbered, atomic implementation steps
- Define testing strategy (TDD with red-green-refactor)
- Identify integration touch points
- Plan for incremental delivery

### Phase 2: Test-Driven Implementation
**CRITICAL RULES:**
- ❌ DON'T test interfaces - test concrete implementations
- ❌ DON'T use compilation errors as RED phase
- ✅ DO write failing behavioral tests FIRST
- ✅ DO use real components over mocks
- Max 3 iterations per red-green cycle

### Phase 3: Completeness Check
- Verify all objectives met
- Audit process discipline
- Confirm no TODOs remain

### Phase 4: Retrospection
- Analyze critical moments
- Extract actionable insights
- Update working agreements

## Testing Conventions
- NUnit with Assert.That syntax
- Leverage TestUtils.cs and fixtures directory
- Add tests to existing fixtures when coherent
- Avoid proliferating new test files

## Process Checkpoints
Before proceeding with implementation:
- [ ] Have I searched for similar implementations?
- [ ] Have I validated external system formats?
- [ ] Have I written a FAILING test first?
- [ ] Am I implementing ONLY enough to pass the test?

## Detailed Phase Instructions
See `.claude/prompts/` directory for detailed instructions for each phase.

.claudeignore

# Build outputs
**/bin
obj
**/obj

# IDE and editor files
**/.vs
**/.idea
**/.vscode
**/*.DotSettings
**/*.user
**/*.suo

# OS files
**/.DS_Store
**/Thumbs.db
**/._.DS_Store
**/._*.*
**/._*

# Test outputs
**/test-output
**/TestResults
**/*.trx
**/*.dcvr

**/fixtures/output

# Logs
*.log

# NuGet
packages/
.nuget/

# Git
.git/

# Config
.lfsconfig

# Binaries
*.dll
*.exe
*.pdb
*.cache

.claude/validation.md

## Pre-Commit Validation Checklist

Before each commit, verify:

- [ ] Test was written and failed FIRST (true RED phase)
- [ ] Implementation makes test pass with minimal code
- [ ] No compilation-only reds (compilation errors don't count as RED)
- [ ] Using real components where possible (avoid unnecessary mocks)
- [ ] Following existing codebase patterns discovered in analysis
- [ ] TDD discipline maintained throughout (max 3 red-green iterations)
- [ ] Code is clean and refactored
- [ ] No TODOs or placeholder implementations remain

Usage Workflow

Starting a New Feature

Always work through phases sequentially:

Phase 1a: Analysis

claude-code "Following .claude/prompts/1a: Analyze implementing [feature description]. 
Search codebase for similar patterns before proposing approach. 
STOP after analysis and wait for approval."

Review the analysis before proceeding.

Phase 1b: Planning

claude-code "Based on approved analysis, create detailed implementation plan 
following .claude/prompts/1b. Break into atomic TDD steps."

Review the plan and approve specific steps.

Phase 2: Implementation (Step by Step)

# For each planned step:
claude-code "Test-drive step [N]: [specific requirement]. 
Follow .claude/prompts/2 TDD discipline strictly. 
Write failing test FIRST, then minimal implementation."

Key points:

• One step at a time
• Always RED (failing test) before GREEN (implementation)
• Review after each step before proceeding
• Maximum 3 red-green iterations per step

Phase 3: Completeness Check

claude-code "Run completeness check per .claude/prompts/3. 
Verify all planned steps complete and process followed."

Phase 4: Retrospection

claude-code "Retrospect on this implementation session following .claude/prompts/4. 
Identify what worked well and what to improve."

Best Practices

1. Explicit Phase References

Always mention .claude/prompts/[phase].md in your commands so Claude knows where to look.

2. One Phase at a Time

Don't ask Claude to "implement feature X end-to-end". Break it into discrete phases.

3. Stop and Review

Use explicit STOP instructions after analysis and planning phases for human review.

4. Context Preservation

Use t