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

Install once, auto-triggers when coding

• Best for: Consistent PDCA 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
• Platforms: macOS, Linux, Windows

📦 Get started with Standard Skill →

Standard skill + persistent task tracking across sessions

• Best for: Complex features spanning multiple days/weeks
• Additional features: Git-backed memory, cross-session continuity, searchable retrospectives
• Requirements: Install beads CLI and MCP server (Go 1.23+, ICU headers)
• Works like: Standard skill with optional beads commands in each phase
• Backward compatible: All beads commands are optional, skip them if beads not installed

🎯 Get started with Beads Skill →

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
• Platforms: macOS, Linux, Windows

📝 Get started with Manual Prompts →

You can mix and match! Many users:

• Install Standard Skill for daily work
• Keep Manual Prompts for special cases
• Add Beads Skill when starting complex, long-running features

Research shows AI code generation without human oversight leads to measurable quality degradation:

• 10x increase in duplicated code (GitClear 2024)
• 7.2% decrease in delivery stability per 25% AI adoption increase (Google DORA 2024)
• 19% slower development with AI tools vs. without (METR 2025)

PDCA Framework keeps humans actively engaged, empowered, and accountable while using structured prompts to regulate agent behavior toward transparency and discipline.

Read the full framework paper: SOSA 2025 Notes — Presentation prepared for XP 2026

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

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 (recommended), see claude-skill/README.md instead.

• Claude Code CLI installed
• Git

Windows only: Windows 10/11 with Developer Mode enabled (for symlinks without admin rights)

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              # Windows only: script to create symlinks

git config core.symlinks true

Windows only: Enable Developer Mode first:

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

macOS/Linux:

mkdir -p .claude/prompts

Windows (PowerShell):

New-Item -ItemType Directory -Path ".claude\prompts" -Force

macOS/Linux:

# Replace $TEMPLATES_PATH with your actual path to the PDCA templates
TEMPLATES_PATH="/path/to/pdca-templates"

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

Windows (PowerShell):

$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"

Create .claudeignore in your project root with patterns appropriate for your stack. Example:

# Build outputs
**/bin
**/obj
**/dist
**/build
node_modules/

# IDE and editor files
**/.vs
**/.idea
**/.vscode

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

# Test outputs
**/TestResults
**/*.trx
**/coverage/

# Logs
*.log

# Git
.git/

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

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

# 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

## 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.

## 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

Always work through phases sequentially:

claude "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.

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

Review the plan and approve specific steps.

# For each planned step:
claude "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

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

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

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

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

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

Use the same Claude Code conversation/task thread to maintain context across phases.

If Claude strays from TDD discipline:

• Stop the task immediately
• Point out the specific violation
• Repost the relevant phase instructions
• Resume with corrected approach

Each implementation step should be:

• Completable in one TDD cycle
• Testable in isolation
• Additive (doesn't break existing tests)

macOS/Linux:

• Check that git config core.symlinks is true
• Verify you have write permissions to the project directory
• Try creating one symlink manually to test permissions

Windows:

• Verify Developer Mode is enabled
• Check that git config core.symlinks is true
• Ensure you're running PowerShell from the project root

• Explicitly reference .claude/prompts/[phase].md in commands
• Break requests into smaller, phase-specific chunks
• Add "STOP and wait for approval" to prevent Claude from jumping ahead
• Review .claude/instructions.md - ensure it's clear and concise

• Verify you're requesting "failing test FIRST"
• Check that RED phase is behavioral failure, not compilation error
• Limit to 3 red-green iterations per step
• Reference .claude/prompts/2 explicitly in implementation requests

• Start new Claude Code task after 8-10 implementation steps
• Reference previous work: "Based on previous implementation of [X]..."
• Keep .claude/instructions.md concise so it's always in context

To use these prompts across multiple projects:

1. Keep your master prompts in a central location (e.g., iCloud, Dropbox, or a shared drive)
2. Create symlinks per project pointing to those masters
3. All projects stay in sync with your master PDCA templates

macOS/Linux — shared script example:

#!/bin/bash
# link-prompts.sh — run from your project root
TEMPLATES_PATH="${1:-$HOME/pdca-templates}"
mkdir -p .claude/prompts
for f in "1a Analyze to determine approach for achieving the goal" \
         "1b Create a detailed implementation plan"; do
  ln -sf "$TEMPLATES_PATH/1. Plan/$f.md" ".claude/prompts/$f.md"
done
# ... remaining phases

Windows — shared script example:

# LinkPrompts.ps1 — run from your project root
param([string]$TemplatesPath = "C:\pdca-templates")
New-Item -ItemType Directory -Path ".claude\prompts" -Force
# ... symlink creation

• Claude Code Documentation
• PDCA Process Repository
• claude-skill/README.md — recommended skill-based setup

This setup guide is part of the Human-AI PDCA Collaboration Process framework, licensed under CC BY 4.0.

Attribution: Ken Judy with Claude Anthropic

Last Updated: 2026