Tdd

Test-Driven Development — Multi-Agent Orchestration

Enforce disciplined RED-GREEN-REFACTOR cycles using separate subagents for test writing and implementation. The core innovation: the Test Writer never sees implementation code, and the Implementer never sees the specification. This prevents the LLM from leaking implementation intent into test design.

When to Use

• User requests TDD, test-first, or red-green-refactor workflow
• User says /tdd with a feature description or bug report
• User wants to add a feature with test coverage enforced from the start
• User wants to fix a bug by first writing a reproducing test

Invocation Modes

In --auto mode, skip all [HUMAN CHECKPOINT] steps. Print status lines instead:

[auto] RED  slice 1/4: "validates email format" — test failing as expected
[auto] GREEN slice 1/4: passing (attempt 1)
[auto] REFACTOR slice 1/4: 1 suggestion applied, 0 skipped

Stop and ask the user ONLY when:

• Implementation fails after 5 attempts
• Regressions cannot be auto-fixed after 3 attempts
• A script error makes it impossible to continue (missing binary, permission denied, etc.)

In --dry-run mode, validate the entire orchestration pipeline without executing any subagents or writing any code:

1. Phase 0 runs fully: detect framework, verify baseline, extract API, discover docs, create state file 2. Phase 1 runs fully: decompose into slices (still requires user approval) 3. For each slice: render all three agent prompts (Test Writer, Implementer, Refactorer) with actual variables. Print rendered prompts to the user with character counts. 4. No `Task()` calls are made. No test files are written. No implementation code is generated. 5. Validate: check that all template variables resolve (no {UNRESOLVED} placeholders), all scripts execute without error, and the state file is well-formed. 6. Report summary:

DRY RUN COMPLETE: {feature name}

Phase 0:
  Framework: {framework}
  Language: {language}
  Baseline: {pass|greenfield}
  API surface: {line count} lines
  Doc context: {line count} lines (or "none")

Phase 1:
  Slices: {N} ({layer breakdown})

Prompts rendered: {N * 3} (all variables resolved)
  Test Writer:   {char count} chars
  Implementer:   {char count} chars
  Refactorer:    {char count} chars

State file: .tdd-state.json written
No code was modified.

This mode is useful for:

• Validating that scripts work in the project's environment
• Reviewing prompt content before committing to a full TDD run
• Testing skill changes without side effects

Architecture Overview

ORCHESTRATOR (you, reading this file)
├─ Phase 0: Setup — detect framework, extract API, create state file
├─ Phase 1: Decompose into vertical slices → user approves
│
├─ FOR EACH SLICE:
│   ├─ Phase 2 (RED):    Task(Test Writer)  ← spec + API only
│   ├─ Phase 3 (GREEN):  Task(Implementer)  ← failing test + error only
│   └─ Phase 4 (REFACTOR): Task(Refactorer) ← all code + green results
│
└─ Summary

Context Boundaries (the key constraint)

Workflow

Phase 0: Setup (once per session)

Step 1: Detect framework and test runner.

Check for: package.json (jest/vitest), pyproject.toml/pytest.ini (pytest),
go.mod (go test), Cargo.toml (cargo test), Gemfile (rspec), composer.json (phpunit)

If ambiguous, ask: "What command runs your tests? (e.g., npm test, pytest)"

Step 2: Detect language from source files (for agent prompts):

TypeScript (.ts/.tsx), JavaScript (.js/.jsx), Python (.py), Go (.go), Rust (.rs), Ruby (.rb), PHP (.php)

Step 3: Verify green baseline.

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{TEST_COMMAND}"

Parse the JSON output.

• If status is "pass": proceed.
• If status is "fail": stop — "Existing tests are failing. TDD starts from a green baseline."
• If status is "error" AND total is 0: greenfield project — no tests exist yet. This is fine. Proceed.

Step 4: Extract the public API surface.

bash ~/.claude/skills/tdd/scripts/extract_api.sh {SOURCE_DIR}

Save the output — this is what the Test Writer will see. If empty (greenfield), that's expected.

Step 5: Discover project documentation.

bash ~/.claude/skills/tdd/scripts/discover_docs.sh {PROJECT_ROOT} --lang {LANGUAGE}

This searches for:

• Documentation files: README, ARCHITECTURE.md, docs/ folder, DESIGN.md, SPEC files, ADRs
• API specifications: OpenAPI/Swagger, GraphQL schemas, .proto files
• Source docstrings: JSDoc, Python docstrings, Go doc comments, Rust /// comments

Save the output as {DOC_CONTEXT}. This feeds into:

• Phase 1 — so slice decomposition is informed by documented behavior and API contracts
• Phase 2 — so the Test Writer writes tests aligned with documented intent, not just code signatures

If empty (no docs found), that's fine — proceed without doc context.

Step 6: Create the state file .tdd-state.json in the project root:

{
  "feature": "user's feature description",
  "framework": "jest|vitest|pytest|go|cargo|rspec|phpunit",
  "language": "typescript|javascript|python|go|rust|ruby|php",
  "test_command": "the full test command",
  "source_dir": "src/",
  "doc_context": "output from discover_docs.sh (or empty string)",
  "auto_mode": false,
  "dry_run": false,
  "slices": [],
  "current_slice": 0,
  "phase": "setup",
  "layer_map": {},
  "files_modified": [],
  "test_files_created": []
}

Each slice in the slices array includes a layer field: "domain", "domain-service", "application", or "infrastructure". See Phase 1 for how layers are assigned.

The layer_map maps directory prefixes to layers. Built during Phase 1 from project structure:

{
  "layer_map": {
    "src/domain/": "domain",
    "src/services/": "domain-service",
    "src/application/": "application",
    "src/infrastructure/": "infrastructure",
    "src/adapters/": "infrastructure",
    "src/controllers/": "infrastructure"
  }
}

If the project has no clear directory-layer mapping (flat structure), set layer_map to {} and skip path-based validation.

Step 5a (auto-detect layer_map): If layer_map is empty, scan the source directory for common DDD/layered architecture directory names and auto-populate:

Common directory → layer mappings (check if directories exist):
  */domain/       → "domain"
  */models/       → "domain"          (ORM models often serve as domain entities)
  */entities/     → "domain"
  */value_objects/ → "domain"
  */services/     → "application"     (unless clearly infrastructure)
  */application/  → "application"
  */use_cases/    → "application"
  */core/         → "application"
  */infrastructure/ → "infrastructure"
  */adapters/     → "infrastructure"
  */controllers/  → "infrastructure"
  */api/          → "infrastructure"
  */bot/          → "infrastructure"  (Telegram/Discord bot handlers)
  */handlers/     → "infrastructure"
  */repositories/ → "infrastructure"  (concrete repo implementations)

Only add entries for directories that actually exist in the source tree. If fewer than 2 directories match, leave layer_map empty (flat project). Present the auto-detected map to the user for confirmation:

Auto-detected layer map from directory structure:
  src/models/     → domain
  src/services/   → application
  src/core/       → application
  src/bot/        → infrastructure
  src/api/        → infrastructure

Does this mapping look correct? (adjust if needed)

Update state: "phase": "setup". Write state file immediately.

---

Phase 1: Specification Decomposition

Take the user's feature request and decompose into ordered vertical slices. Each slice is one testable behavior.

Use doc context: When decomposing, cross-reference {DOC_CONTEXT} from Phase 0 Step 5. Documentation often describes intended behaviors, edge cases, and API contracts that should inform slice boundaries. If docs mention specific error cases, validation rules, or behavioral requirements, consider them as slice candidates.

Inside-Out Slice Ordering

After identifying all slices, sort them inside-out by architectural layer. This ensures each slice can build on real (not mocked) implementations from previous slices:

1. Domain model slices first — pure logic, no dependencies, no mocks needed 2. Domain service slices — cross-aggregate operations using real domain objects 3. Application service / use case slices — orchestration using in-memory fakes for ports 4. Infrastructure adapter slices last — repos, external APIs, framework adapters

Assign each slice a layer tag: domain, domain-service, application, or infrastructure. Use the heuristics from references/layer_guide.md to classify.

Why inside-out? Domain slices produce real objects that later slices use directly. This minimizes mocking and catches integration issues early. It also ensures business rules are implemented and tested before any infrastructure decisions are made.

For simple projects where all code lives in one layer, all slices get layer: "application" and the ordering doesn't change — the guidance degrades gracefully.

Edge Cases in Slice Ordering

Infrastructure-only features (e.g., "add email provider retry logic", "switch from Postgres to MySQL"):

• If a feature has NO domain or application behavior changes, all slices may be infrastructure. This is valid — skip the inner layers entirely.
• Present as: "This is a pure infrastructure change. All slices are infrastructure-layer."

Missing port interface (domain-service needs a port that doesn't exist yet):

• The first slice that needs the port should create the interface as part of its implementation. The Implementer is allowed to create files in inner layers (domain/domain-service can define their own ports).
• Example: a domain-service slice for RegistrationService creates domain/ports/UserRepository interface as part of GREEN.

Cross-cutting slices (a slice touches multiple layers):

• Tag with the INNERMOST layer it touches. The Implementer may create files in that layer and any inner layers.
• Example: a use case that also introduces a new domain event is tagged application but creates a file in domain/events/.

Present to the user:

I've broken this into N vertical slices (ordered inside-out):

Domain:
1. [behavior] — [what the test verifies]

Domain Services:
2. [behavior] — [what the test verifies]

Application:
3. [behavior] — [what the test verifies]

Infrastructure:
4. [behavior] — [what the test verifies]

Each slice follows RED -> GREEN -> REFACTOR before moving to the next.
Does this decomposition look right?

If all slices fall in one layer, skip the layer headings and present as a flat list.

Wait for user approval (even in --auto mode — slice decomposition always needs sign-off).

Update state: Write slices array (each with layer field), set "phase": "decomposed".

---

Dry-Run Phase Override (Phase 2–4)

In --dry-run mode, replace Phases 2–4 entirely with the following for each slice:

1. Refresh API surface (extract_api.sh) 2. Render the Test Writer prompt with all variables filled in. Print it under a ### Test Writer Prompt (slice N) heading. 3. Render the Implementer prompt using placeholder test code: "(dry-run: test code would be generated by Test Writer)" for {FAILING_TEST_CODE} and "(dry-run: no test output)" for {TEST_FAILURE_OUTPUT}. 4. Render the Refactorer prompt using placeholder values: "(dry-run: no green output)" for {GREEN_TEST_OUTPUT}, "(dry-run: code from Test Writer)" for {ALL_TEST_CODE}, "(dry-run: code from Implementer)" for {ALL_IMPLEMENTATION_CODE}. 5. For each rendered prompt, verify no {UNRESOLVED_VARIABLE} patterns remain (regex: \{[A-Z][A-Z_]+\}). Report any unresolved variables as errors. 6. Print character counts for each prompt. 7. Move to next slice (no Task() calls, no file writes, no test runs).

After all slices are processed, print the dry-run summary and exit. Do NOT clean up the state file — it's useful for subsequent --resume.

---

Phase 2: RED — Write One Failing Test

Step 1: Refresh the API surface (it changes as slices are implemented):

bash ~/.claude/skills/tdd/scripts/extract_api.sh {SOURCE_DIR}

Step 2: Read the prompt template from references/agent_prompts.md -> "Test Writer Agent" section. Construct the prompt by filling in:

• {SLICE_SPEC}: The current slice's behavior description
• {LANGUAGE}: Detected language from Phase 0
• {FRAMEWORK}: Detected framework name
• {API_SURFACE}: Output from extract_api.sh
• {DOC_CONTEXT}: Output from discover_docs.sh (Phase 0 Step 5). Include only sections relevant to the current slice — filter by keyword match if the full output is large.
• {TEST_FILE_PATH}: Where the test should go (follow project conventions)
• {EXISTING_TEST_CONTENT}: Current content of the test file (if it exists), or "No test file exists yet."
• {FRAMEWORK_SKELETON}: The relevant skeleton from references/framework_configs.md
• {LAYER}: The slice's layer tag from Phase 1
• {LAYER_TEST_CONSTRAINTS}: Layer-specific test constraints (see agent_prompts.md -> Layer-Specific Constraint Lookup)

Step 3: Launch the Test Writer agent:

Task(subagent_type="general-purpose", prompt=<constructed prompt>)

Step 4: Parse the JSON response using the parse_agent_json logic from agent_prompts.md: 1. Strip markdown fences if present 2. Try direct JSON parse 3. If that fails, find first { and last }, try that substring 4. If still invalid: retry the Task call once with appended "Return ONLY a JSON object." 5. If still failing: extract test code manually from the raw response

Step 5: Write the test code to the test file. If the file exists, append the test function (and merge imports). If new, create with the agent's imports_needed + test_code.

Step 5a (post-write test smell scan): Scan the test code for common smells before running:

Step 5b (post-write layer lint): Scan the test code for layer-violating patterns:

If forbidden patterns found: 1. Remove the offending mock/pattern from the test 2. Re-launch Test Writer with appended: "Do NOT use mocking libraries. This is a {LAYER} layer test. Use real domain objects." 3. If second attempt still uses forbidden patterns, ask user

Step 6: Run the test to confirm it FAILS (expect an assertion failure, not a setup error):

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{TEST_COMMAND_FOR_SPECIFIC_TEST}"

Step 7: Evaluate the result with semantic validation:

Step 8 (interactive mode only — skip in --auto): Present to the user:

RED: Test written and failing as expected.

Test: {test_name}
File: {test_file_path}
Failure: {failure message from JSON}

This test verifies: {test_description from agent response}

Proceed to GREEN phase? (or adjust the test?)

Wait for user approval before proceeding to GREEN.

Update state: "phase": "red", add test file to test_files_created. Write state immediately.

---

Phase 3: GREEN — Minimal Implementation

Step 1: Read the failing test file and the test failure output (the full raw_tail from the RED phase run_tests.sh result).

Step 2: Build the file tree of source files (not test files, not node_modules, etc.):

find {SOURCE_DIR} -type f \( -name '*.ts' -o -name '*.js' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.rb' -o -name '*.php' \) | grep -v test | grep -v spec | grep -v node_modules | grep -v __pycache__ | grep -v vendor | grep -v target | grep -v dist | grep -v build | head -50

Step 3: Read existing source files that the test imports or references.

Step 4: Read the prompt template from references/agent_prompts.md -> "Implementer Agent" section. Fill in:

• {LANGUAGE}: Detected language
• {FAILING_TEST_CODE}: The complete test file content
• {TEST_FAILURE_OUTPUT}: The raw_tail from run_tests.sh JSON output
• {FILE_TREE}: Source file listing from Step 2
• {EXISTING_SOURCE}: Content of relevant source files (if any — may be empty for greenfield)
• {LAYER}: The slice's layer tag from Phase 1
• {LAYER_DEPENDENCY_CONSTRAINT}: Layer-specific dependency constraint (see agent_prompts.md -> Layer-Specific Constraint Lookup)

On retries (attempt > 1), also fill in the {?PREVIOUS_ATTEMPT} section:

• {PREVIOUS_ATTEMPT_DESCRIPTION}: the explanation field from the failed attempt
• {PREVIOUS_ATTEMPT_ERROR}: the raw_tail from the test run after the failed attempt

CRITICAL: Do NOT include the slice specification, feature description, or any future plans. The Implementer works from the test alone.

Step 5: Launch the Implementer agent:

Task(subagent_type="general-purpose", prompt=<constructed prompt>)

Step 6: Parse the JSON response. Validate layer boundaries, then apply file changes.

Step 6a (Layer path validation): If layer_map is not empty, check each file path in the response against the current slice's layer:

For each file in response.files:
  inferred_layer = lookup file.path against layer_map (longest prefix match)
  if inferred_layer exists AND inferred_layer != current_slice.layer:
    if inferred_layer is OUTER relative to current_slice.layer:
      REJECT: "Implementer created/modified {file.path} which belongs to
      the {inferred_layer} layer, but this is a {current_slice.layer} slice.
      Inner layers must not depend on outer layers."
      → Re-launch Implementer with appended constraint:
        "Do NOT create or modify files in {inferred_layer} directories.
        This slice is {current_slice.layer} only."
    if inferred_layer is INNER relative to current_slice.layer:
      ALLOW: outer layers may touch inner-layer files (e.g., adding a port interface)

Layer ordering for "outer" check: domain < domain-service < application < infrastructure.

If layer_map is empty (flat project), skip this validation.

Step 6b: Apply validated file changes:

For each file in the response files array:

• If action is "create" or "overwrite": Use the Write tool to create or overwrite the file with the complete content
• If action is "edit" (used for existing files over 200 lines): Use the Edit tool with old_string → new_string to apply the changes. The Implementer returns only the changed functions with surrounding context — identify the insertion point or the function being replaced, and use Edit tool accordingly. If the edit target is ambiguous, fall back to reading the full file and using Write.
• For existing files over 200 lines where the Implementer returned full content anyway (action = "overwrite"), prefer using Edit tool to apply only the diff — this prevents accidental reformatting of untouched code

Step 7: Run the specific test:

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{TEST_COMMAND_FOR_SPECIFIC_TEST}"

Step 8: RETRY LOOP (if test still fails):

attempt = 1
max_attempts = 5
previous_explanation = null
previous_error = null

while status != "pass" AND attempt <= max_attempts:
    previous_explanation = explanation from last Implementer response
    previous_error = raw_tail from last test run

    Launch FRESH Task(Implementer) with:
      - same test code + file tree + existing source (re-read!)
      - NEW failure output
      - PREVIOUS_ATTEMPT section filled in

    Apply changes (Write tool for each file)
    Re-run test
    attempt += 1

if still failing after max_attempts:
    STOP. Present to user:
    "Implementation failed after 5 attempts. Last error: {raw_tail}"
    Ask: "Adjust the test, try a different approach, or debug manually?"

Each retry is a fresh Task call with only the previous attempt's explanation and error. This prevents the Implementer from going down rabbit holes while giving it enough context to try a different strategy.

Step 9: Once the specific test passes, run the FULL test suite:

bash ~/.claude/skills/tdd/scripts/run_tests.sh {FRAMEWORK} "{FULL_TEST_COMMAND}" --all

Step 10: Handle regressions:

Step 11 (interactive mode only — skip in --auto): Present to the user:

GREEN: Test passing with minimal implementation.

Implementation: {explanation from agent response}
Files changed: {list}
All tests: {passed} passing, {failed} failing

Proceed to REFACTOR phase? (or adjust?)

Update state: "phase": "green", update files_modified. Write state immediately.

Step 12 (domain/domain-service slices only): Layer purity check before REFACTOR:

For each new/modified file in a domain or domain-service layer slice:

• Import scan: Read all import/require statements. Check each imported module against layer_map. Flag any import from an outer layer as a violation.
• Constructor check: Verify constructor takes NO parameters typed from outer layers (no ORM sessions, HTTP clients, framework configs)
• Static call check: No static method calls to outer-layer code
• If violations found, fix them now (move the dependency to a port interface) before entering REFACTOR

Step 13: Full-repo import scan (all layers, runs once per slice):

Scan ALL source files (not just session-modified) for dependency direction violations:

# For each source file, extract imports and check against layer_map
# Language-specific patterns:
#   Python: from X import Y, import X
#   TypeScript/JS: import ... from 'X', require('X')
#   Go: import "X"

For each file: 1. Determine its layer from layer_map (skip if no match) 2. For each import, determine the imported module's layer from layer_map 3. If imported layer is OUTER relative to file's layer → violation

Report violations to the user before REFACTOR:

Layer scan found N dependency direction violation(s):
- domain/user.py imports infrastructure/db.py (domain → infrastructure)
- domain/services/registration.py imports adapters/email.py (domain-service → infrastructure)

In --auto mode: attempt auto-fix (replace concrete import with port interface). In interactive mode: present violations and ask user how to proceed.

This supplements the Refactorer's import checking (which only sees session files) with a repo-wide scan. Static tools miss ~23% of violations (Pruijt et al., 2017) — combining textual + structural checks improves coverage.

---

Phase 4: REFACTOR

Step 1: Gather all context:

• All test files created/modified during this session
• All source files modified during this session
• The green test output

Step 2: Read the prompt template from references/agent_prompts.md -> "Refactorer Agent" section. Fill in:

• {LANGUAGE}: Detected language
• {GREEN_TEST_OUTPUT}: Full test output showing all green
• {ALL_TEST_CODE}: Content of all test files
• {ALL_IMPLEMENTATION_CODE}: Content of all modified source files
• {SLICE_LAYERS}: Comma-separated list of unique layers from all slices completed so far

Step 3: Launch the Refactorer agent:

Task(subagent_type="general-purpose", prompt=<constructed prompt>)

Step 4: Parse the JSON response. If suggestions is empty, skip to Step 6.

Apply suggestions one at a time, in priority order (high first):

For each suggestion: 1. Apply the code change (Edit tool, using old_code -> new_code for each file) 2. Run the project linter/formatter check (detect from project config):

• Python: python -m black --check {files} && python -m flake8 {files} && python -m mypy {files}
• TypeScript/JS: npx eslint {files} or npx tsc --noEmit
• Go: go vet ./...
• Rust: cargo clippy
• If lint fails -> revert immediately and skip this suggestion (same as test failure)

3. Run the full test suite 4. If any test fails -> revert immediately (re-read the file from before the edit and Write it back) and skip this suggestion 5. If all tests pass and lint passes -> keep the change

Step 5 (interactive mode only — skip in --auto): Present:

REFACTOR: Code improved, all tests still passing.

Applied: {list of accepted suggestions}
Skipped: {list of reverted suggestions, if any}
All tests: {count} passing

[Moving to slice N of M] or [All slices complete]

In --auto mode, print one-liner:

[auto] REFACTOR slice N/M: {applied_count} applied, {skipped_count} skipped

Update state: "phase": "refactor". Write state immediately.

---

Phase 5: Next Slice or Complete

If more slices remain -> increment current_slice in state, return to Phase 2.

If all slices complete -> present summary:

TDD Complete: {feature name}

Slices implemented: N
Tests written: N
Files created/modified: {list}
All tests passing: yes

Clean up: remove .tdd-state.json (in --auto mode, remove silently; in interactive, ask user).

---

Resume Support

When user invokes /tdd --resume:

1. Read .tdd-state.json from project root 2. Report current state: "Found TDD session for '{feature}'. Currently at slice {N}/{total}, phase: {phase}." 3. Resume from the current phase of the current slice 4. If auto_mode is true in state, continue in auto mode

---

Edge Cases

Greenfield Projects

No source files, no tests, no test configuration. Handle gracefully:

1. Phase 0 Step 3: If run_tests.sh returns status: "error" with total: 0, check if any test files exist. If none, this is greenfield — proceed. 2. Phase 0 Step 4: extract_api.sh will return empty output. Pass "(No existing API — this is a new project)" to the Test Writer. 3. Phase 2: The Test Writer will create test files from scratch. May need to set up the test framework config (e.g., jest.config.js, pytest.ini). If the first test run fails with a framework error (not a test failure), create minimal framework config and retry.

Bug Fix TDD

1. Write a test demonstrating the bug (should FAIL showing the bug exists) 2. Confirm failure matches the reported bug — human checkpoint 3. Fix: minimal code to make test pass (GREEN phase as normal) 4. Verify: no regressions

Existing Code (Characterization Tests)

1. Write a test for CURRENT behavior (should PASS — this is a characterization test) 2. Modify the test for DESIRED behavior (should FAIL) 3. Proceed with GREEN -> REFACTOR

User-Provided Tests

If user provides test code: 1. Run to confirm it fails (RED confirmed) 2. Skip to Phase 3 (GREEN) — user-provided tests are authoritative 3. Do not modify without asking

Flaky Tests

If a test sometimes passes/fails: stop, report, fix the flaky test before continuing.

---

Failure Recovery Reference

---

Layer Reference

See references/layer_guide.md for layer definitions, dependency rules, test strategies by layer, and detection heuristics.

Anti-Patterns to Avoid

See references/anti_patterns.md. Critical ones:

• Never modify a test to make it pass (change implementation, not tests)
• Never write implementation before tests
• Never write all tests at once (vertical slicing)
• Never test implementation details
• Never skip the RED phase
• Never let domain code import infrastructure (dependency direction violation)
• Never mock domain objects — construct real instances instead

---

Framework Quick Reference

See references/framework_configs.md for setup details.

TDD Skill for Claude Code

Multi-agent TDD orchestrator that enforces RED-GREEN-REFACTOR cycles with architecturally isolated context between test writing and implementation. The Test Writer never sees implementation code; the Implementer never sees the specification.

Usage

/tdd <feature description>          # Interactive mode with human checkpoints
/tdd --auto <feature description>   # Autonomous mode, stops only on errors
/tdd --resume                       # Resume from .tdd-state.json

Features

• Context isolation: Separate agents for test writing, implementation, and refactoring with strict information boundaries
• Vertical slicing: Features decomposed into independently testable behavior slices
• DDD/Onion layer awareness: Slices sorted inside-out (domain first, infrastructure last) with layer-specific test constraints and dependency direction enforcement
• Auto-retry: Up to 5 implementation attempts per slice with fresh agent context on each retry
• Greenfield support: Works on projects with zero existing tests or source code
• Framework detection: Jest, Vitest, pytest, Go test, cargo test, RSpec, PHPUnit

Architecture

ORCHESTRATOR (SKILL.md)
|-- Phase 0: Setup -- detect framework, extract API, create state file
|-- Phase 1: Decompose into vertical slices (inside-out by layer)
|
|-- FOR EACH SLICE:
|   |-- Phase 2 (RED):    Task(Test Writer)  <- spec + API + layer constraints
|   |   |-- Post-RED lint: block mocking libs in domain tests
|   |-- Phase 3 (GREEN):  Task(Implementer)  <- failing test + error + layer deps
|   |   |-- Layer path validation: reject files outside slice's layer
|   |   |-- Domain purity check (constructors, imports, statics)
|   |   |-- Full-repo import scan: catch violations in untouched files
|   |-- Phase 4 (REFACTOR): Task(Refactorer) <- all code + dependency direction audit
|
|-- Summary

DDD / Onion Layer Support

Each slice is tagged with a layer (domain, domain-service, application, infrastructure) which determines:

Enforcement is multi-layered (not just textual reminders):

1. Path validation (GREEN phase): Implementer output files checked against layer_map — rejects writes to outer-layer directories 2. Post-RED test lint: Scans test code for mocking libraries (jest.mock, Mock(), etc.) in domain/domain-service tests 3. Domain purity check: Verifies constructors take no outer-layer types, no static calls to infrastructure 4. Full-repo import scan: Checks ALL source files (not just session-modified) for dependency direction violations 5. Refactorer audit: Checks direct + transitive dependency violations, flagging as high-priority suggestions

Port interface rule: the consumer defines the contract — ports live in the layer that needs them, not the layer that implements them.

This layer awareness degrades gracefully: for simple projects where everything lives in one layer, all slices get layer: "application" and the constraints don't add overhead.

Edge cases handled: infrastructure-only features, missing port interfaces (created by first slice that needs them), and cross-cutting slices (tagged by innermost layer touched).

File Structure

tdd/
|-- SKILL.md                          # Main orchestrator (read by Claude Code)
|-- README.md                         # This file
|-- scripts/
|   |-- run_tests.sh                  # Test runner wrapper (JSON output)
|   |-- extract_api.sh                # Public API surface extractor
|-- references/
    |-- agent_prompts.md              # Agent prompt templates + constraint lookup
    |-- anti_patterns.md              # TDD and layer anti-pattern reference
    |-- framework_configs.md          # Per-framework test skeletons
    |-- layer_guide.md                # DDD/Onion layer definitions + test strategy

Research-Informed Design

The layer-aware testing approach is informed by empirical software engineering research:

• AI code + no arch constraints = 80% violation rate: LLM-generated code violates hexagonal architecture boundaries 80% of the time without explicit enforcement. Layer constraints in agent prompts directly counteract this. (arXiv:2412.02883 — TDD-Bench Verified, 2024)
• Static tools miss ~23% of dependency violations: Architecture compliance checking tools detect only 77% of dependencies on average. The refactorer supplements tooling by checking imports + transitive deps during code review. (Pruijt et al., Software: Practice and Experience, 2017)
• Test-driven prompting +38-45% accuracy: Using tests as specification improves LLM code generation accuracy by 38-45% over instruction-only prompting. RED-first is empirically better than spec-first for AI agents. (Naik et al., ICSE-Companion / IEEE TSE, 2024)
• TDD alone doesn't improve design: TDD's effect on design metrics is not as evident as expected -- the REFACTOR phase with dependency checks is where architectural quality emerges. (Turhan et al., IEEE, 2010/2017)
• TDD reduces defects 40-90%: Industrial teams using TDD saw 40-90% defect density reduction with 15-35% initial development time increase, offset by reduced maintenance. (Nagappan et al., Empirical Software Engineering, 2008)
• Over-mocking degrades LLM-generated tests: LLM-generated tests over-use mocking by 2-3x compared to human-written tests, leading to tests that pass despite broken implementations. In-memory fakes and Protocol-based test doubles produce more reliable test suites. (arXiv:2602.00409, 2025)

Full research survey: see references/layer_guide.md for citations applied to specific design decisions.

Installation

Copy tdd/ to ~/.claude/skills/tdd/ and ensure scripts/*.sh are executable:

cp -r tdd/ ~/.claude/skills/tdd/
chmod +x ~/.claude/skills/tdd/scripts/*.sh

Agent Prompt Templates

These templates are used by the orchestrator to construct Task tool calls with strict context isolation. Each agent receives ONLY the information listed -- nothing else.

Placeholders use {VARIABLE_NAME} syntax. Optional sections wrapped in {?SECTION}...{/SECTION} -- include only when the variable has content, omit entirely otherwise.

---

Test Writer Agent

subagent_type: general-purpose

Context boundary: Sees specification + API surface. Does NOT see implementation code, other slices, or implementation plans.

You are a TDD Test Writer. Your ONLY job is to write ONE failing test for a specific behavior.

## Specification for this slice
{SLICE_SPEC}

## Language and framework
- Language: {LANGUAGE}
- Framework: {FRAMEWORK}
- Test file location: {TEST_FILE_PATH}

## Public API surface (signatures only, no implementations)
{API_SURFACE}

Note: If the API surface is empty, the function/class does not exist yet. Write the test assuming the import path and function signature based on the specification. The Implementer will create the code.

{?DOC_CONTEXT}
## Project documentation (relevant excerpts)
{DOC_CONTEXT}

Use this documentation to understand intended behavior, API contracts, edge cases, and validation rules. Tests should align with documented behavior, not just inferred behavior from code signatures.
{/DOC_CONTEXT}

## Existing test file content (if any)
{EXISTING_TEST_CONTENT}

## Framework-specific test skeleton
{FRAMEWORK_SKELETON}

## Architectural layer for this slice
This slice belongs to the **{LAYER}** layer.

{LAYER_TEST_CONSTRAINTS}

## Mocking guidance (application layer)
When the slice is `application` layer and the code under test depends on async interfaces:
- Prefer writing a simple in-memory fake over using Mock/MagicMock with complex `.return_value` chains
- Use `AsyncMock` for any async method (not `MagicMock`)
- If a `@runtime_checkable Protocol` exists for the dependency, implement it with a fake class:

Instead of:

mock_repo = AsyncMock() mock_repo.get_by_id.return_value = User(id=1, name="test") mock_repo.save.return_value = None

Prefer (when the mock setup becomes non-trivial):

class FakeUserRepo: def __init__(self): self.saved = [] async def get_by_id(self, id: int) -> User: return User(id=id, name="test") async def save(self, user: User) -> None: self.saved.append(user)

For simple cases (1-2 methods, no state tracking), `AsyncMock` is fine. Use fakes when:
- The mock needs 3+ configured return values
- You need to track call history beyond simple assert_called
- The Protocol has methods that interact with each other

## Rules
1. Write EXACTLY ONE test function for the specified behavior
2. The test MUST fail because the implementation does not yet exist
3. Test through the public interface only -- no internal/private access
4. Use descriptive test names that read as behavior specs
5. Do NOT plan or think about implementation -- reason only from the specification
6. Do NOT write implementation code
7. Do NOT write helper functions beyond minimal test setup
8. Include all necessary imports in the test code
9. Follow the layer-specific test constraints above

## Output
Return a single JSON object. Do NOT wrap in markdown fences. Do NOT include any text before or after the JSON.

{"test_code": "the COMPLETE test code to add (including describe/it blocks, not just the assertion)", "test_name": "name of the test function", "test_description": "what behavior this test verifies", "imports_needed": "any import statements needed at the top of the file, or empty string if none"}

---

Implementer Agent

subagent_type: general-purpose

Context boundary: Sees failing test + error output + existing source. Does NOT see the original specification, slice descriptions, or future plans.

You are a TDD Implementer. Your ONLY job is to write the MINIMUM code to make a failing test pass.

## Language: {LANGUAGE}

## Failing test code
{FAILING_TEST_CODE}

## Test failure output
{TEST_FAILURE_OUTPUT}

{?PREVIOUS_ATTEMPT}
## Previous attempt (failed)
The following approach was tried and still failed:
{PREVIOUS_ATTEMPT_DESCRIPTION}

Error after previous attempt:
{PREVIOUS_ATTEMPT_ERROR}

Do NOT repeat the same approach. Try a different strategy.
{/PREVIOUS_ATTEMPT}

## File tree (source files only)
{FILE_TREE}

## Existing source code (files relevant to the failing test)
{EXISTING_SOURCE}

## Architectural layer
This code belongs to the **{LAYER}** layer.

{LAYER_DEPENDENCY_CONSTRAINT}

## Rules
1. Write the MINIMUM code to make the failing test pass
2. No code beyond what the test requires
3. No premature abstractions or extra error handling
4. No optimization -- simple and direct
5. Hardcoded values are acceptable if they satisfy the test
6. Do NOT modify the test file
7. Do NOT add features or behaviors not tested
8. For NEW files or files under 200 lines: return the COMPLETE file content
9. For EXISTING files over 200 lines: return ONLY the new/changed functions plus enough surrounding context (imports, class declaration line) for the orchestrator to apply as an edit. Set `"action": "edit"` for these files.
10. Respect the layer dependency constraint above -- do NOT import from outer layers

## Output
Return a single JSON object. Do NOT wrap in markdown fences. Do NOT include any text before or after the JSON.

{"files": [{"path": "relative/path/to/file.ext", "action": "create | overwrite | edit", "content": "COMPLETE file content for create/overwrite, or ONLY changed functions with context for edit", "description": "what this file does"}], "explanation": "brief explanation of the implementation approach"}

Use `"action": "edit"` for existing files over 200 lines. For edit actions, include the function(s) being added/changed with their imports and class context -- the orchestrator will use Edit tool (old_string → new_string) to apply.

Key change from v1: always return complete file content (no partial patches). The orchestrator uses the Write tool for creates, and for existing files it compares the returned content against the current content to determine what changed.

---

Refactorer Agent

subagent_type: general-purpose

Context boundary: Sees all implementation + all tests + green test results. Does NOT see the original specification or decomposition rationale.

You are a TDD Refactorer. All tests are currently passing. Your job is to suggest code improvements that preserve behavior.

## Language: {LANGUAGE}

## Current test results (all green)
{GREEN_TEST_OUTPUT}

## All test code
{ALL_TEST_CODE}

## All implementation code
{ALL_IMPLEMENTATION_CODE}

## Layers touched in this session
{SLICE_LAYERS}

## Rules
1. Do NOT change behavior -- all existing tests must continue to pass
2. Focus on: extracting duplication, improving naming, simplifying logic, applying appropriate patterns
3. Do NOT add new features, new tests, or new error handling
4. Each suggestion must be independently applicable (revert-safe)
5. Prefer small, targeted improvements over large restructurings
6. Apply the Rule of Three -- don't extract abstractions unless a pattern appears 3+ times
7. If no meaningful refactoring is needed, say so -- that's a valid outcome
8. Check all import statements for dependency direction violations: inner layers must NOT import from outer layers. Direction: domain → domain-service → application → infrastructure. Flag any violation as a HIGH priority suggestion.
9. Check for TRANSITIVE dependency violations: if file A imports file B, and B imports from an outer layer, then A has an indirect dependency on that outer layer. Trace one level deep: for each import in domain/domain-service code, check what THAT module imports. Flag transitive violations as HIGH priority with a note explaining the chain (e.g., "domain/User imports domain/validators which imports infrastructure/db — indirect violation").
10. Domain purity check: verify domain layer classes take NO constructor parameters whose types come from outer layers (no ORM session, no HTTP client, no framework config objects). Flag as HIGH priority.

## Output
Return a single JSON object. Do NOT wrap in markdown fences. Do NOT include any text before or after the JSON.

If refactoring is suggested:
{"suggestions": [{"description": "what this refactoring does", "priority": "high or medium or low", "files": [{"path": "relative/path/to/file.ext", "old_code": "exact code to find and replace", "new_code": "replacement code"}]}], "summary": "overall assessment of code quality"}

If no refactoring is needed:
{"suggestions": [], "summary": "Code is clean. No refactoring needed at this stage."}

---

Notes for the Orchestrator

JSON Response Parsing

Agents frequently wrap output in markdown fences despite instructions. Parse robustly:

def parse_agent_json(response_text):
    text = response_text.strip()
    # Strip markdown fences
    if text.startswith("```"):
        lines = text.split("\n")
        text = "\n".join(lines[1:])  # remove first line (```json or ```)
        if text.rstrip().endswith("```"):
            text = text.rstrip()[:-3]
    text = text.strip()
    # Try direct parse
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass
    # Find JSON substring
    first_brace = text.find("{")
    last_brace = text.rfind("}")
    if first_brace != -1 and last_brace != -1:
        return json.loads(text[first_brace:last_brace + 1])
    raise ValueError(f"Could not parse JSON from agent response")

Context Construction Checklist

When building each agent's prompt, verify these constraints:

Test Writer:

• [x] Contains slice spec
• [x] Contains API surface from extract_api.sh (run fresh each time)
• [x] Contains doc context from discover_docs.sh (if available — omit section if empty)
• [x] Contains language and framework
• [x] Contains existing test file content (if any)
• [x] Contains layer tag and layer-specific test constraints
• [ ] Does NOT contain any implementation source code
• [ ] Does NOT contain other slice descriptions
• [ ] Does NOT contain the feature description beyond the current slice

Implementer:

• [x] Contains the complete test file
• [x] Contains the test failure output (raw_tail from run_tests.sh)
• [x] Contains the file tree
• [x] Contains relevant existing source files
• [x] Contains previous attempt context (on retries)
• [x] Contains layer tag and layer-specific dependency constraint
• [ ] Does NOT contain the slice spec or feature description
• [ ] Does NOT contain future slice plans

Refactorer:

• [x] Contains ALL test files from this session
• [x] Contains ALL modified source files
• [x] Contains the green test output
• [x] Contains layer list for dependency direction checking
• [ ] Does NOT contain the original specification
• [ ] Does NOT contain the decomposition rationale

Retry Strategy for Implementer

On each retry (attempt > 1), add the {?PREVIOUS_ATTEMPT} section with:

• PREVIOUS_ATTEMPT_DESCRIPTION: the explanation field from the failed attempt's JSON response
• PREVIOUS_ATTEMPT_ERROR: the raw_tail from the new test run after applying the failed attempt

This gives the fresh agent enough context to avoid the same mistake without accumulating a long failure history.

Error Recovery

If an agent returns invalid JSON: 1. Apply the parse_agent_json logic above (handles fences + substring extraction) 2. If still invalid, retry the same Task call once with an appended instruction: "IMPORTANT: Your previous response was not valid JSON. Return ONLY a JSON object, nothing else." 3. If still failing after retry, fall back to the orchestrator reading the raw response and attempting to extract the relevant information manually (read the test code, file paths, etc.) 4. If all extraction fails, present the raw response to the user and ask how to proceed

Layer-Specific Constraint Lookup

When constructing agent prompts, substitute {LAYER_TEST_CONSTRAINTS} and {LAYER_DEPENDENCY_CONSTRAINT} based on the slice's layer:

{LAYER_TEST_CONSTRAINTS} for the Test Writer:

• domain: "Write tests using only domain types. NO database mocks, NO HTTP mocks, NO file system. Test pure business logic through public methods. Construct real domain objects directly — never mock them."
• domain-service: "Use in-memory fakes that implement repository/port interfaces. Test the domain service's coordination logic. NO real I/O, NO database, NO HTTP. Use real domain objects from the domain layer."
• application: "Use in-memory fakes for all ports and repositories. Prefer writing a 5-line in-memory fake class that implements the Protocol/interface over configuring a complex Mock(spec=...) with multiple return values. Use AsyncMock for async interfaces. Test the orchestration flow — that the use case calls the right domain operations in the right order. NO real infrastructure."
• infrastructure: "Test that the adapter correctly translates between domain types and external formats (SQL rows, HTTP responses, file contents). May use integration test patterns with real dependencies or test containers."

{LAYER_DEPENDENCY_CONSTRAINT} for the Implementer:

• domain: "This is the innermost layer. It MUST NOT import anything from domain-service, application, or infrastructure layers. No ORM imports, no HTTP clients, no framework imports. Only standard library and domain types."
• domain-service: "This layer may import from the domain model only. It MUST NOT import from application or infrastructure layers. If this service needs an external dependency (e.g., repository), define the port interface in the domain or domain-service layer — the consumer defines the contract."
• application: "This layer may import from domain model and domain services. It MUST NOT import from infrastructure. If this use case needs an external dependency not covered by an existing port, define the port interface here — the consumer defines the contract."
• infrastructure: "This layer may import from all inner layers. It implements interfaces defined in inner layers. Framework and external library imports are expected here."

{SLICE_LAYERS} for the Refactorer:

Comma-separated list of unique layers from all slices completed so far. Example: "domain, application, infrastructure".

Applying Implementer Output

For each file in the response files array, check the action field:

1. "create": Use Write tool to create the new file 2. "overwrite" (file ≤ 200 lines): Use Write tool to overwrite with the returned content 3. "overwrite" (file > 200 lines): Prefer using Edit tool to apply only the actual changes — diff the returned content against the current file and apply targeted edits. This prevents accidental reformatting of large files. 4. "edit": The Implementer returned only changed/new functions with context. Use the Edit tool with old_string → new_string:

• For new functions: identify the insertion point (end of class, after last import, etc.) and use Edit to insert
• For modified functions: use the existing function as old_string and the modified version as new_string
• For new imports: prepend to the existing import block

After applying all files, run the test immediately. If the full test suite catches regressions from a Write-based overwrite, consider re-applying via Edit instead.

TDD Anti-Patterns Reference

Phase Violations

Writing implementation before tests

Symptom: Code appears in source files before a corresponding test exists. Fix: Delete the implementation. Write the test first. Period. Why it matters: Implementation-first means the test is verifying what was built, not specifying what should be built. The test becomes a rubber stamp, not a design tool.

Writing all tests at once (horizontal slicing)

Symptom: Multiple test functions written in a batch before any implementation. Fix: Write exactly one test. Make it fail. Make it pass. Refactor. Then write the next test. Why it matters: Batch testing leads to batch implementation. The feedback loop widens, errors compound, and refactoring becomes risky because too many things change at once.

Skipping the RED phase

Symptom: A test is written and passes immediately without implementation. Fix: If the test passes without new code, either (a) the behavior already exists, (b) the test is trivially passing (wrong assertion), or (c) the test setup is wrong. Investigate. Why it matters: A test that was never seen failing provides no confidence. It might pass for the wrong reasons.

Modifying tests to match implementation

Symptom: After writing implementation, the test is changed to match what the code does rather than what the spec requires. Fix: The test encodes the REQUIREMENT. If the implementation doesn't match, fix the implementation. Only change the test if the user confirms the requirement was wrong. Why it matters: This inverts the authority chain. Tests are specifications; implementation serves them, not the other way around.

Test Quality Anti-Patterns

Testing implementation details

Symptom: Tests assert on private methods, internal state, call counts of mocked internals, or specific algorithm steps. Examples:

• expect(service._cache).toHaveLength(3) -- testing private cache
• expect(mockDb.query).toHaveBeenCalledTimes(2) -- testing internal query pattern
• expect(result.__internal_flag).toBe(true) -- testing private state

Fix: Test through public interfaces only. Assert on return values, side effects visible to callers, or observable state changes. Why it matters: Implementation-detail tests break on every refactor, even when behavior is preserved. They test HOW the code works, not WHAT it does.

Testing the framework, not the code

Symptom: Tests that verify the test framework, mocking library, or ORM works correctly. Examples:

• Mocking a database then asserting the mock returns the mocked value
• Testing that JSON.parse(JSON.stringify(x)) round-trips correctly

Fix: Tests should verify YOUR code's behavior, not third-party behavior.

Tautological tests

Symptom: Tests where the assertion is trivially true regardless of implementation. Examples:

• expect(true).toBe(true)
• expect(result).toBeDefined() (where result is always defined by the function signature)
• Asserting a function returns without throwing when it has no throw paths

Fix: Every assertion must be capable of failing given a plausible incorrect implementation.

Over-mocking

Symptom: More mock setup code than actual test code. Every dependency is mocked. Fix: Use real implementations where practical. Mock only at system boundaries (network, filesystem, clock). Prefer integration tests with in-memory fakes over unit tests with extensive mocks. Why it matters: Over-mocked tests pass even when integration is broken. They test the wiring, not the behavior.

Structural Anti-Patterns

God test

Symptom: A single test function that tests multiple behaviors with multiple assertions and complex setup. Fix: Split into one test per behavior. Each test should have one reason to fail. Pattern: Arrange-Act-Assert, each section clearly delineated.

Test interdependence

Symptom: Tests that depend on execution order, shared mutable state, or other tests' side effects. Fix: Each test sets up its own state and tears it down. Tests must pass when run in isolation or in any order.

Fragile test fixtures

Symptom: A change in test setup code breaks many unrelated tests. Fix: Use builder patterns or factory functions that provide sensible defaults. Each test overrides only what it cares about.

Testing trivial code

Symptom: Tests for getters, setters, constructors, or obvious one-liners. Fix: Skip tests for code with zero logic. Focus testing on code with conditionals, loops, transformations, or business rules.

Process Anti-Patterns

Gold plating during GREEN

Symptom: Implementation during the GREEN phase includes extra features, optimization, or error handling not required by the current test. Fix: Write the absolute minimum to make the test pass. If you want to add more, write a test for it first.

Skipping REFACTOR

Symptom: After GREEN, immediately writing the next test without cleaning up. Fix: Always assess the code after GREEN. Even if no refactoring is needed, consciously evaluate. Refactoring is where design emerges.

Premature refactoring

Symptom: Extracting abstractions after only one or two instances of a pattern. Fix: Wait for the "Rule of Three" -- extract abstractions only after seeing a pattern three times. In early TDD cycles, duplication is acceptable.

Ignoring test failures in the full suite

Symptom: A new test passes but existing tests break, and the broken tests are dismissed as "unrelated." Fix: Every test failure after GREEN is a regression until proven otherwise. Investigate and fix before moving to REFACTOR.

Layer & Dependency Anti-Patterns

Domain importing infrastructure

Symptom: Domain model code imports ORM classes, HTTP clients, file system modules, or framework utilities. Examples:

• from sqlalchemy.orm import Session in a domain entity
• import axios from 'axios' in a domain service
• use Illuminate\Database\Eloquent\Model in a domain value object

Fix: Domain code must have zero external dependencies. If the domain needs to persist or communicate, define an interface (port) in the domain layer and let infrastructure implement it. Why it matters: Domain code that imports infrastructure cannot be tested without that infrastructure. It also locks business logic to a specific technology choice.

Business logic in handlers/controllers

Symptom: Validation rules, calculations, state transitions, or conditional logic living in HTTP handlers, CLI commands, or event listeners instead of domain objects or services. Examples:

• Price calculation in an Express route handler
• Email format validation in a controller
• Order state machine transitions in a message consumer

Fix: Extract the logic into a domain entity, value object, or domain service. The handler should only translate HTTP/CLI/event input into domain calls and translate domain output back. Why it matters: Business logic in handlers is untestable without spinning up the framework. It also gets duplicated when you add a second entry point (API + CLI + queue consumer).

Mocking domain objects

Symptom: Using jest.mock(), unittest.mock.Mock(), or similar to create fake domain entities or value objects instead of constructing real instances. Examples:

• const user = { validate: jest.fn().mockReturnValue(true) } instead of new User("valid@email.com")
• mock_order = Mock(spec=Order) instead of Order(items=[item1, item2])

Fix: Domain objects are pure and cheap to construct. Use real instances in tests. Only mock at boundaries (repositories, external services). Why it matters: Mocking domain objects defeats the purpose of testing — you're testing your mocks, not your domain logic. If a domain object is hard to construct, that's a design smell.

Anemic domain model

Symptom: Entities with only getters/setters, all logic in services. Tests pass but the design is wrong — behavior is disconnected from the data it operates on. Examples:

• User class with only name, email properties; UserService.validateUser(user) does all validation
• Order with items list; OrderCalculator.calculateTotal(order) computes the total externally

Fix: Move behavior onto the entity that owns the data. user.validate(), order.calculateTotal(). Services coordinate; entities compute. Why it matters: Anemic models scatter related logic across services, making it harder to find, test, and enforce invariants. It's procedural code wearing OOP clothing.

Repository interface in wrong layer

Symptom: The repository interface (UserRepository, OrderRepository) is defined alongside its implementation in the infrastructure layer, rather than in the domain layer. Examples:

• infrastructure/repositories/user_repository.py contains both the interface and the PostgreSQL implementation
• src/database/UserRepository.ts defines the interface and exports it

Fix: Define the interface in the consuming layer (domain/ports/user_repository.py if consumed by domain services, application/ports/ if consumed by use cases). The infrastructure layer imports and implements it. The consumer defines the contract. Why it matters: If the interface lives in infrastructure, domain code must import infrastructure to reference it — breaking the dependency rule.

Service locator / static global container

Symptom: Domain or application code obtains dependencies through a global registry, static container, or service locator instead of constructor injection. Examples:

• Container.resolve(UserRepository) called inside a domain service method
• ServiceLocator.get('emailService') in a use case
• app.make('UserRepository') (Laravel) inside domain code
• @inject decorators that resolve from a global container at import time

Fix: Accept dependencies through the constructor (or function parameters). The composition root (in infrastructure) wires everything together. Domain and application code never knows where implementations come from. Why it matters: Service locators hide dependencies — the class signature doesn't reveal what it needs. Tests require configuring a global container instead of passing fakes directly. It also makes dependency direction invisible: a domain class appears independent but actually reaches into infrastructure at runtime.

Active Record bleed (ORM entity as domain object)

Symptom: The same class serves as both the database model (ORM entity) and the domain object. Framework-specific annotations, base classes, or conventions leak into domain logic. Examples:

• class User extends Model (Eloquent/ActiveRecord) used directly in domain services
• @Entity() class Order (TypeORM) with both column decorators and business logic
• Domain code calling .save(), .delete(), or .query() on domain objects
• SQLAlchemy Base subclass used as a domain entity

Fix: Separate the persistence model from the domain model. The infrastructure layer maps between them. Domain entities have zero ORM awareness. Why it matters: Active Record couples business logic to the database schema and ORM framework. Domain tests require a database (or complex mocking). Schema changes break business logic. The domain layer becomes untestable without infrastructure — violating the core DDD/Onion principle.

Test Framework Configuration Reference

JavaScript / TypeScript

Jest

Detection: jest in package.json devDependencies, or jest.config.js/ts/mjs

Run commands:

# All tests
npx jest

# Single file
npx jest path/to/file.test.ts

# Single test by name
npx jest --testPathPattern=file.test.ts -t "should calculate total"

# Watch mode
npx jest --watch

# With coverage
npx jest --coverage

Test file conventions: *.test.ts, *.test.js, *.spec.ts, *.spec.js, or files in __tests__/

Minimal test skeleton:

describe("ModuleName", () => {
  it("should [behavior]", () => {
    // Arrange
    const input = ...;

    // Act
    const result = functionUnderTest(input);

    // Assert
    expect(result).toBe(expected);
  });
});

Vitest

Detection: vitest in package.json devDependencies, or vitest.config.ts/js

Run commands:

# All tests (run once)
npx vitest run

# Single file
npx vitest run path/to/file.test.ts

# Single test by name
npx vitest run path/to/file.test.ts -t "should calculate total"

# Watch mode (default)
npx vitest

# With coverage
npx vitest run --coverage

Test file conventions: Same as Jest. Vitest is API-compatible with Jest.

Minimal test skeleton: Same as Jest (uses same describe/it/expect API).

Mocha + Chai

Detection: mocha in package.json, .mocharc.yml

Run commands:

npx mocha "test/**/*.test.js"
npx mocha --grep "should calculate"

---

Python

pytest

Detection: pytest in pyproject.toml/setup.cfg, pytest.ini, conftest.py

Run commands:

# All tests
pytest -v

# Single file
pytest tests/test_module.py -v

# Single test
pytest tests/test_module.py::test_function_name -v

# By keyword match
pytest -k "calculate and total" -v

# With coverage
pytest --cov=src -v

# Stop on first failure
pytest -x -v

Test file conventions: test_*.py or *_test.py, functions prefixed with test_

Minimal test skeleton:

def test_should_calculate_total():
    # Arrange
    items = [Item(price=10), Item(price=20)]

    # Act
    result = calculate_total(items)

    # Assert
    assert result == 30

With classes:

class TestCalculator:
    def test_should_add_numbers(self):
        calc = Calculator()
        assert calc.add(2, 3) == 5

    def test_should_handle_negative(self):
        calc = Calculator()
        assert calc.add(-1, 1) == 0

Fixtures:

import pytest

@pytest.fixture
def calculator():
    return Calculator()

def test_should_add(calculator):
    assert calculator.add(2, 3) == 5

pytest-asyncio

Detection: pytest-asyncio in pyproject.toml/requirements, or asyncio_mode in pytest.ini/pyproject.toml

asyncio_mode detection: Check pytest.ini and pyproject.toml for asyncio_mode = auto. When auto mode is set, @pytest.mark.asyncio is not needed — all async def test_* functions are automatically collected as async tests.

Run commands: Same as pytest (no difference for async tests).

Async test skeleton (asyncio_mode = auto):

from unittest.mock import AsyncMock, MagicMock


async def test_should_process_message():
    # Arrange
    service = MessageService()
    mock_repo = AsyncMock()
    mock_repo.save.return_value = None

    # Act
    result = await service.process("hello", repo=mock_repo)

    # Assert
    assert result.status == "processed"
    mock_repo.save.assert_awaited_once()

Async test skeleton (asyncio_mode = strict, or not set):

import pytest
from unittest.mock import AsyncMock


@pytest.mark.asyncio
async def test_should_process_message():
    service = MessageService()
    result = await service.process("hello")
    assert result.status == "processed"

Async fixtures:

import pytest
from unittest.mock import AsyncMock, MagicMock


@pytest.fixture
def mock_bot():
    bot = MagicMock()
    bot.send_message = AsyncMock()
    return bot


@pytest.fixture
def mock_update():
    update = MagicMock()
    update.effective_chat.id = 12345
    update.message.text = "test"
    return update


@pytest.fixture
async def db_session():
    """Async fixture with setup and teardown."""
    session = await create_test_session()
    yield session
    await session.close()

Key patterns:

• Use AsyncMock for any method that is async def — it returns an awaitable
• Use MagicMock for synchronous attributes/properties on async objects
• assert_awaited_once() / assert_awaited_once_with(...) — async equivalents of assert_called_once
• Async fixtures use async def + yield for setup/teardown

---

Go

go test

Detection: go.mod in project root

Run commands:

# All tests
go test ./...

# Single package
go test ./pkg/calculator/

# Single test
go test -run TestCalculateTotal ./pkg/calculator/

# Verbose
go test -v ./...

# With coverage
go test -cover ./...

# Race detection
go test -race ./...

Test file conventions: *_test.go in same package

Minimal test skeleton:

func TestShouldCalculateTotal(t *testing.T) {
    // Arrange
    items := []Item{{Price: 10}, {Price: 20}}

    // Act
    result := CalculateTotal(items)

    // Assert
    if result != 30 {
        t.Errorf("expected 30, got %d", result)
    }
}

Table-driven tests (idiomatic Go):

func TestCalculateTotal(t *testing.T) {
    tests := []struct {
        name     string
        items    []Item
        expected int
    }{
        {"empty list", []Item{}, 0},
        {"single item", []Item{{Price: 10}}, 10},
        {"multiple items", []Item{{Price: 10}, {Price: 20}}, 30},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := CalculateTotal(tt.items)
            if result != tt.expected {
                t.Errorf("expected %d, got %d", tt.expected, result)
            }
        })
    }
}

---

Rust

cargo test

Detection: Cargo.toml

Run commands:

# All tests
cargo test

# Single test
cargo test test_name

# Single module
cargo test module_name::

# With output
cargo test -- --nocapture

# Watch mode (requires cargo-watch)
cargo watch -x test

Test file conventions: #[cfg(test)] module in source files, or tests/ directory for integration tests

Minimal test skeleton:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn should_calculate_total() {
        let items = vec![Item { price: 10 }, Item { price: 20 }];
        let result = calculate_total(&items);
        assert_eq!(result, 30);
    }
}

---

Ruby

RSpec

Detection: rspec in Gemfile, .rspec file, spec/ directory

Run commands:

# All tests
rspec

# Single file
rspec spec/calculator_spec.rb

# Single test by line
rspec spec/calculator_spec.rb:15

# By description
rspec -e "should calculate total"

# With documentation format
rspec --format documentation

Test file conventions: spec/**/*_spec.rb

Minimal test skeleton:

RSpec.describe Calculator do
  describe "#total" do
    it "should calculate total for multiple items" do
      items = [Item.new(price: 10), Item.new(price: 20)]
      calculator = Calculator.new(items)

      result = calculator.total

      expect(result).to eq(30)
    end
  end
end

---

PHP

PHPUnit

Detection: phpunit in composer.json, phpunit.xml

Run commands:

# All tests
./vendor/bin/phpunit

# Single file
./vendor/bin/phpunit tests/CalculatorTest.php

# Single test
./vendor/bin/phpunit --filter testShouldCalculateTotal

# With coverage
./vendor/bin/phpunit --coverage-text

Test file conventions: tests/**/*Test.php, classes extend TestCase

Minimal test skeleton:

class CalculatorTest extends TestCase
{
    public function testShouldCalculateTotal(): void
    {
        $items = [new Item(price: 10), new Item(price: 20)];
        $calculator = new Calculator($items);

        $result = $calculator->total();

        $this->assertEquals(30, $result);
    }
}

DDD / Onion Layer Reference

Compact reference for layer-aware TDD. Not a DDD textbook — just enough for agents to enforce dependency direction and choose the right test strategy.

Why This Matters (Research-Backed)

• AI-generated code without architectural constraints produces 80% dependency violation rates in hexagonal architecture (arXiv:2512.04273, 2025). Layer constraints in agent prompts directly counteract this.
• Static tools detect only ~77% of dependency violations on average (Pruijt et al., 2017). Our refactorer supplements tooling by checking imports + transitive deps during code review.
• Test-driven prompting improves LLM code generation accuracy by 38-45% (Naik et al., 2024). RED-first with focused prompts is empirically better than spec-first.
• TDD alone doesn't automatically improve design (Turhan et al., 2017). The REFACTOR phase with dependency checks is essential, not optional — it's where architectural quality emerges.

Layer Definitions (Inside → Outside)

Domain Model (Core)

• Entities, Value Objects, Aggregates, Domain Events
• ZERO external dependencies (no ORM, no HTTP, no frameworks)
• Test with: direct construction, no mocks
• Example: User entity with email validation, Money value object with currency math

Domain Services

• Complex operations spanning multiple aggregates
• Depends on: Domain Model only (+ interfaces for ports it needs)
• Test with: real domain objects, in-memory fakes for repository interfaces
• Example: RegistrationService checking uniqueness via a repository interface

Application Services (Use Cases)

• Orchestrate domain logic, handle transactions, coordinate side effects
• Depends on: Domain Model + Domain Services
• Defines port interfaces that infrastructure will implement
• Test with: in-memory fakes for all ports/repositories
• Example: RegisterUserUseCase coordinating validation, persistence, email notification

Infrastructure & Presentation

• DB access, external APIs, controllers, CLI handlers, adapters
• Depends on: all inner layers (implements their interfaces)
• Test with: integration tests, may use real dependencies or test containers
• Example: PostgresUserRepository implementing UserRepository interface

Port Interface Placement

Ports (interfaces that abstract external dependencies) are defined by the layer that consumes them, not the layer that implements them:

• A UserRepository interface consumed by a domain service lives in domain/ports/ or domain-service/ports/
• A NotificationService interface consumed by an application use case lives in application/ports/
• Infrastructure implements these interfaces but never defines them

Rule: the consumer defines the contract; the provider fulfills it. This is the Dependency Inversion Principle.

Dependency Rule

Dependencies flow INWARD only. Inner layers define interfaces (ports); outer layers implement them (adapters).

Infrastructure → Application → Domain Services → Domain Model
     ↓               ↓               ↓                ↓
  implements     orchestrates     uses real        pure logic
  interfaces     via ports        domain objects   no imports

Violation example: domain/user.py importing from infrastructure.db import Session — domain must never import infrastructure.

Layer Detection Heuristics

When classifying a slice, ask: 1. Does it involve only business rules with no I/O? → domain 2. Does it coordinate multiple domain objects but still no I/O? → domain-service 3. Does it orchestrate a workflow (validate, persist, notify)? → application 4. Does it talk to a database, HTTP API, file system, or framework? → infrastructure

Test Strategy by Layer

API Reference

Calculator

Methods

• add(a, b) — Returns sum of a and b
• subtract(a, b) — Returns a minus b
• divide(a, b) — Returns a divided by b, raises ValueError on zero

Standalone Functions

• factorial(n) — Returns n!, raises ValueError for negative input

Calculator Project

A simple calculator library for arithmetic operations.

Features

• Basic arithmetic: add, subtract, multiply, divide
• Factorial computation
• Input validation with descriptive errors

Usage

from src.calculator import Calculator

calc = Calculator()
result = calc.add(2, 3)  # returns 5

TypeScript Calculator

Simple calculator with type safety.