| 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, mcp__context7__resolve-library-id, mcp__context7__get-library-docs |
| 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"} |
| 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:
constitution:
development_mode: tdd
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:
- Testability: Test-first approach ensures testability
- Readability: Tests document expected behavior
- Understandability: Tests serve as living documentation
- Security: Security tests written before implementation
- Transparency: Test failures provide immediate 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
Last Updated: 2026-02-03
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
