Claude Code TDD Workflow: Enforce Test-Driven Development with Isolated Agents

Claude Code TDD Workflow is a Claude Code plugin developed by hugo-bluecorn. It enforces the red-green-refactor TDD cycle using seven context-isolated agents, solving the problems of unreliable program instructions and session drift in AI-assisted development. The plugin follows the Unix philosophy: each agent is restricted to a single responsibility, and they are combined into a pipeline to complete complex workflows.

With the popularity of AI coding assistants, developers face two core dilemmas:

Unreliable Program Instructions

Prompts like 'write tests first then implement' given to Claude vary in quality across different runs. This issue has been confirmed by more than 12 controlled experiments, and verbal constraints are hard to enforce.

Inevitable Session Drift

In long sessions, attention to early instructions fades, and key constraints are automatically compressed or discarded. Even a 1 million-token context window can't fully eliminate this, forcing developers to repeatedly set constraints and consume cognitive resources.

Core Philosophy: AI Practice of Unix Philosophy

The plugin follows the Unix philosophy—each tool does one thing well and is combined into a pipeline. Agents like planners, implementers, and verifiers focus on single responsibilities; developers orchestrate decisions, and agents execute with discipline.

Three-Layer System Architecture

1. TDD Pipeline Layer: Planning phase (read-only codebase research, decompose feature slices), Implementation phase (execute red-green-refactor cycle, verifier does isolated black-box verification), Release phase (update CHANGELOG, push code, etc.).
2. Role System Layer: Coding workflow patterns, knowledge references, and behavioral constraints generate reusable role files (e.g., /role-ca loads the architect role), and the TDD pipeline runs independently.
3. Convention System Layer: Language-agnostic, supports multiple languages via external convention packages (current support for Dart/Flutter, C++, etc.), adding new languages requires no plugin modification.

Combination of Four Primitives

The plugin uses four primitives of Claude Code:

Primitive	Capability Provided	Plugin Usage
Agent	Isolate context, restricted tool access	Each TDD phase runs with an independent agent
Skill	User-facing commands, orchestration logic	/tdd-plan generates planners, etc.
Hook	Lifecycle event handler	Enforce test order, auto-run tests, etc.
Script	Shared tools	Project detection, convention loading, etc.

Agent Configuration

Agent	Model	Context	Purpose
tdd-planner	opus	Read-only, planning mode	Research codebase, return structured plan
tdd-implementer	opus	Read-write, full tools	Execute red-green-refactor
tdd-verifier	haiku	Read-only	Black-box verification
tdd-releaser	sonnet	Bash write-only	Release process
role-creator	opus	Read-only	Generate role files

Hook Enforcement

• validate-tdd-order.sh: Ensure implementation files can only be written if test files exist
• auto-run-tests.sh: Auto-run tests after file changes
• planner-bash-guard.sh: Whitelist read-only Bash commands for planners

Four agents (planner, implementer, verifier, context updater) have persistent memory to accumulate knowledge across sessions.

The plugin solves real pain points in AI programming:

• Reliability: Mechanical enforcement eliminates the uncertainty of 'sometimes works, sometimes doesn't'—hooks don't rely on the model's goodwill.
• Repeatability: The role system allows workflow patterns to be coded and reused without repeated context setup.
• Objectivity: The verifier's isolated context enables independent judgment of test results.
• Scalability: The convention system supports new languages via external packages without modifying core code.

This project provides insights for AI tool design:

1. The stronger the capability, the more important constraints are: When AI modifies code directly, prompts are insufficient—architectural isolation, mechanical enforcement, and process orchestration are needed.
2. Unix philosophy applies to the AI era: Small tools, single responsibility, pipeline combination—each agent does one thing but together complete complex workflows.
3. Reference architecture patterns: AI development tools should let AI perform better within clear boundaries, not do more.