--- name: moai-workflow-tdd description: > Test-Driven Development workflow specialist using RED-GREEN-REFACTOR cycle for test-first software development. Use when developing new features from scratch or when behavior specification drives implementation. when_to_use: > Use for Test-Driven Development: the RED-GREEN-REFACTOR cycle for test-first software development, new-feature implementation from scratch, and behavior-specification-driven implementation. license: Apache-2.0 compatibility: Designed for Claude Code allowed-tools: Read, Write, Edit, Bash(pytest:*), Bash(ruff:*), Bash(npm:*), Bash(npx:*), Bash(node:*), Bash(jest:*), Bash(vitest:*), Bash(go:*), Bash(cargo:*), Bash(mix:*), Bash(uv:*), Bash(bundle:*), Bash(php:*), Bash(phpunit:*), Grep, Glob user-invocable: false metadata: version: "1.0.0" category: "workflow" status: "active" updated: "2026-02-03" modularized: "true" tags: "workflow, tdd, test-driven, red-green-refactor, test-first" author: "MoAI-ADK Team" related-skills: "moai-workflow-ddd, moai-workflow-testing, moai-foundation-quality" # MoAI Extension: Progressive Disclosure progressive_disclosure: enabled: true level1_tokens: 100 level2_tokens: 5000 --- # Test-Driven Development (TDD) Workflow ## Development Mode Configuration (CRITICAL) [NOTE] This workflow is selected based on `.moai/config/sections/quality.yaml`: ```yaml constitution: development_mode: tdd # or ddd ``` **When to use this workflow**: - `development_mode: tdd` → Use TDD (this workflow, default) - `development_mode: ddd` → Use DDD instead (moai-workflow-ddd) **Key distinction**: - **TDD** (default): Test-first development for all work, including brownfield projects with pre-RED analysis - **DDD**: Characterization-test-first for existing codebases with minimal test coverage ## Quick Reference Test-Driven Development provides a disciplined approach for creating new functionality where tests define the expected behavior before implementation. Core Cycle - RED-GREEN-REFACTOR: - RED: Write a failing test that defines desired behavior - GREEN: Write minimal code to make the test pass - REFACTOR: Improve code structure while keeping tests green When to Use TDD: - Creating new functionality from scratch - Building isolated modules with no existing dependencies - When behavior specification drives development - New API endpoints with clear contracts - New UI components with defined behavior - Greenfield projects (rare - usually Hybrid is better) When NOT to Use TDD: - Refactoring existing code (use DDD instead) - When behavior preservation is the primary goal - Legacy codebase without test coverage (use DDD first) - When modifying existing files (consider Hybrid mode) --- ## Core Philosophy ### TDD vs DDD Comparison TDD Approach: - Cycle: RED-GREEN-REFACTOR - Goal: Create new functionality through tests - Starting Point: No code exists - Test Type: Specification tests that define expected behavior - Outcome: New working code with test coverage DDD Approach: - Cycle: ANALYZE-PRESERVE-IMPROVE - Goal: Improve structure without behavior change - Starting Point: Existing code with defined behavior - Test Type: Characterization tests that capture current behavior - Outcome: Better structured code with identical behavior ### Test-First Principle The golden rule of TDD is that tests must be written before implementation code: - Tests define the contract - Tests document expected behavior - Tests catch regressions immediately - Implementation is driven by test requirements --- ## Implementation Guide ### Phase 1: RED - Write a Failing Test The RED phase focuses on defining the desired behavior through a failing test. #### Writing Effective Tests Before writing any implementation code: - Understand the requirement clearly - Define the expected behavior in test form - Write one test at a time - Keep tests focused and specific - Use descriptive test names that document behavior #### Test Structure Follow the Arrange-Act-Assert pattern: - Arrange: Set up test data and dependencies - Act: Execute the code under test - Assert: Verify the expected outcome #### Verification The test must fail initially: - Confirms the test actually tests something - Ensures the test is not passing by accident - Documents the gap between current and desired state ### Phase 2: GREEN - Make the Test Pass The GREEN phase focuses on writing minimal code to satisfy the test. #### Minimal Implementation Write only enough code to make the test pass: - Do not over-engineer - Do not add features not required by tests - Focus on correctness, not perfection - Hardcode values if necessary (refactor later) #### Verification Run the test to confirm it passes: - All assertions must succeed - No other tests should break - Implementation satisfies the test requirements ### Phase 3: REFACTOR - Improve the Code The REFACTOR phase focuses on improving code quality while maintaining behavior. #### Safe Refactoring With passing tests as a safety net: - Remove duplication - Improve naming and readability - Extract methods and classes - Apply design patterns where appropriate #### Continuous Verification After each refactoring step: - Run all tests - If any test fails, revert immediately - Commit when tests pass --- ## TDD Workflow Execution ### Standard TDD Session When executing TDD through manager-develop: Step 1 - Understand Requirements: - Read SPEC document for feature scope - Identify test cases from acceptance criteria - Plan test implementation order Step 2 - RED Phase: - Write first failing test - Verify test fails for the right reason - Document expected behavior Step 3 - GREEN Phase: - Write minimal implementation - Run test to verify it passes - Move to next test Step 4 - REFACTOR Phase: - Review code for improvements - Apply refactoring with tests as safety net - Commit clean code Step 5 - Repeat: - Continue RED-GREEN-REFACTOR cycle - Until all requirements are implemented - Until all acceptance criteria pass ### TDD Loop Pattern For features requiring multiple test cases: - Identify all test cases upfront - Prioritize by dependency and complexity - Execute RED-GREEN-REFACTOR for each - Maintain cumulative test suite --- ## Quality Metrics ### TDD Success Criteria Test Coverage (Required): - Minimum 80% coverage per commit - 90% recommended for new code - All public interfaces tested Code Quality (Goals): - All tests pass - No test written after implementation - Clear test names documenting behavior - Minimal implementation satisfying tests ### TDD-Specific TRUST Validation Apply TRUST 5 framework with TDD focus: - Tested: Test-first approach ensures coverage - Readability: Tests document expected behavior - Unified: Style and structure consistent with the surrounding code - Security: Security tests written before implementation - Trackable: Test failures provide immediate, attributable feedback --- ## Integration Points ### With DDD Workflow TDD and DDD are complementary: - TDD for new code - DDD for existing code refactoring - Hybrid mode combines both approaches ### With Testing Workflow TDD integrates with testing workflow: - Uses specification tests - Integrates with coverage tools - Supports mutation testing for test quality ### With Quality Framework TDD outputs feed into quality assessment: - Coverage metrics tracked - TRUST 5 validation for changes - Quality gates enforce standards --- ## Troubleshooting ### Common Issues Test is Too Complex: - Break into smaller, focused tests - Test one behavior at a time - Use test fixtures for complex setup Implementation Grows Too Fast: - Resist urge to implement untested features - Return to RED phase for new functionality - Keep GREEN phase minimal Refactoring Breaks Tests: - Revert immediately - Refactor in smaller steps - Ensure tests verify behavior, not implementation ### Recovery Procedures When TDD discipline breaks down: - Stop and assess current state - Write characterization tests for existing code - Resume TDD for remaining features - Consider switching to Hybrid mode --- Version: 1.0.0 Status: Active ## Common Rationalizations | Rationalization | Reality | |---|---| | "I'll add tests after the implementation works" | Post-hoc tests verify what the code does, not what it should do. They miss the bugs RED phase catches. | | "The existing tests cover this case" | Existing tests verify old behavior. New behavior needs its own failing test first. | | "This function is too simple to test" | Simple functions accumulate complexity. The test documents expected behavior before drift. | | "I tested it manually in the terminal" | Manual checks do not persist. Tomorrow's change breaks the contract with no signal. | | "The test requires complex mocking" | If the test is hard to write, the code is hard to reason about. Refactor the design first. | | "Tests slow me down" | Test-first surfaces design problems early, when they are cheapest to fix. | | "I'll skip REFACTOR this cycle to keep moving" | Skipped refactors compound. The next cycle starts from a worse baseline. | **DAMP over DRY**: In test code, prefer Descriptive And Meaningful Phrases over Don't Repeat Yourself. Duplication inside a test that makes the intent obvious is better than an abstraction that hides it. **Beyonce Rule**: If you liked it, you should have put a test on it. Any behavior CI does not verify will eventually break without warning. ## Red Flags - Implementation file created in the same commit as its test file (RED phase skipped) - Test names describe implementation (test_function_returns_true) instead of behavior (test_user_login_rejects_expired_token) - All tests in a new file pass on first run — no RED phase was captured - Commit message says "add tests" after the feature is already merged - Test suite contains mocks of the code under test (mocking implementation, not collaborators) - Coverage dropped in the commit that added a new feature ## Verification - [ ] Git history shows a failing-test commit before the implementation commit, or evidence of RED in the same commit - [ ] Test names read as behavior specifications, not function descriptions - [ ] Every new public function has at least one corresponding test case - [ ] Full test suite passes (paste command output) - [ ] Coverage for changed files is measured and reported (show tool output) - [ ] No `skip`, `xit`, or disabled tests were added in this change - [ ] REFACTOR phase was executed or explicitly justified as unnecessary ## Test-First Anti-Cheat [ZONE:Evolvable] [HARD] The Red Flags and Verification checklists above sit in advisory (evolvable) blocks and are consumed by no completion gate. This section promotes them into two enforced invariants that make test-first falsifiable in the completion matrix. - **Invariant i — RED failure output is mandatory completion evidence.** The verbatim RED failing-test output (the failing-test run captured BEFORE any implementation makes it pass) MUST be observed and shown as part of run-phase completion evidence. A run that cannot produce this output skipped RED and cannot be reported as clean. - **Invariant ii — implementation written before its failing test is deleted and re-derived test-first.** Any implementation code written before its failing test exists MUST be deleted and re-derived from a failing test (RED then GREEN). "I already wrote the implementation, so the test passes on first run" is the exact failure mode this invariant forbids — it is test-after, not test-first, and it leaves no RED output (Invariant i) to show as evidence. These two invariants close the falsifiability gap: before them, a fully-passing self-verification matrix was producible with NO RED evidence, so test-first could not be distinguished from test-after by the completion report. After them, the matrix requires the verbatim pre-GREEN RED output, so a run that skipped RED has no such output to supply and the matrix is structurally incomplete.