swingerman-atdd

ATDD — Acceptance Test Driven Development for Claude Code

A Claude Code plugin that enforces the Acceptance Test Driven Development (ATDD) methodology when building software with AI. Write human-readable Given/When/Then specs before code, generate project-specific test pipelines, and maintain the discipline of two-stream testing.

Inspired by Robert C. Martin's (Uncle Bob) acceptance test approach from empire-2025. The ideas, methodology, and key insights in this plugin come directly from his work and public writings on Spec Driven Design (SDD) and ATDD.

Why ATDD with AI?

When using AI to write code, two problems emerge:

1. AI writes code without constraints — without acceptance tests anchoring behavior, AI can "willy-nilly plop code around" (Uncle Bob's words) and write unit tests that pass but don't verify the right behavior.
2. Implementation details leak into specs — AI naturally tries to fill Given/When/Then statements with class names, API endpoints, and database tables instead of domain language.

This plugin solves both problems by enforcing the ATDD workflow and guarding against implementation leakage. The result: two test streams (acceptance + unit) that constrain AI development, producing better-structured, more reliable code.

"The two different streams of tests cause Claude to think much more deeply about the structure of the code. It can't just willy-nilly plop code around and write a unit test for it. It is also constrained by the structure of the acceptance tests." — Robert C. Martin

How It Works

1. Write Given/When/Then specs (natural language, domain-only)
                    ↓
2. Generate test pipeline (parser → IR → test generator)
   Pipeline has DEEP knowledge of your codebase internals
                    ↓
3. Run acceptance tests → they FAIL (red)
                    ↓
4. Implement with TDD (unit tests + code) until BOTH streams pass
                    ↓
5. Review specs for implementation leakage
                    ↓
6. Mutation testing → verify tests actually catch bugs
                    ↓
7. Iterate — next feature, back to step 1

The generated pipeline is NOT like Cucumber. It's what Uncle Bob calls "a strange hybrid of Cucumber and the test fixtures" — the parser/generator has deep knowledge of your system's internals and produces complete, runnable tests. No manual fixture code needed.

Installation

Add the marketplace and install the plugin:

/plugin marketplace add swingerman/atdd
/plugin install atdd@swingerman-atdd

Or test locally by cloning:

git clone https://github.com/swingerman/atdd.git
claude --plugin-dir ./atdd

Getting Started

1. Start the ATDD workflow

/atdd:atdd Add user authentication with email and password

Claude will guide you through understanding the feature, then help you write acceptance specs.

2. Write your first spec

Create a file in specs/ at your project root:

;===============================================================
; User can register with email and password.
;===============================================================
GIVEN no registered users.

WHEN a user registers with email "bob@example.com" and password "secret123".

THEN there is 1 registered user.
THEN the user "bob@example.com" can log in.

3. Generate the test pipeline

Claude analyzes your codebase and generates a project-specific parser, IR format, and test generator tailored to your language and test framework (pytest, Jest, JUnit, Go testing, RSpec, etc.).

4. Red → Green → Refactor

Run the acceptance tests (they should fail), then implement with TDD until both acceptance tests AND unit tests pass.

5. Check for leakage

/atdd:spec-check

The spec-guardian agent reviews your specs for implementation details that shouldn't be there.

Team-Based ATDD Workflow

For larger features, you can orchestrate an agent team that follows the ATDD workflow. The team lead coordinates specialist agents — each with a clear role and strict instructions.

Tip: The plugin includes an atdd-team skill that automates team setup and orchestration. Just say "build [feature] with a team" and the skill handles role creation, phase sequencing, and prompt generation.

Works With Existing Teams

Already running an agent team? The atdd-team skill detects active teams and gives you three options: