jochenyang/tdd-workflow

TDD Workflow Skill

This skill standardizes the Test-Driven Development process to achieve high code quality and maintainability.

The TDD Cycle

Follow these 4 steps strictly for every new feature or bug fix:

1. RED: Write a Failing Test

• Action: Create a new test file or add a case to an existing one.
• Requirement: The test must fail (showing that the feature is missing or the bug is present).
• Goal: Define the expected behavior before writing implementation code.

2. GREEN: Make it Pass

• Action: Write the minimal implementation code necessary to make the test pass.
• Requirement: Don't worry about code elegance yet. Correctness is the only priority.
• Goal: Confirm the solution works as intended.

3. REFACTOR: Clean Up

• Action: Optimize implementation and test code while ensuring tests remain green.
• Requirement: Remove duplication, improve naming, optimize performance, and follow project standards.
• Goal: Ensure the code is maintainable and efficient.

4. VERIFY: Final Validation

• Action: Run the full test suite and check coverage.
• Requirement:
  • Ensure all tests (not just the new ones) pass.
  • Target coverage: >80% for the new/modified component.
  • Verify edge cases (null values, network failures, out-of-bounds, etc.).

Best Practices

Test First, Always

Never write implementation code before its corresponding test. If you find yourself implementing logic first, stop and write a test that covers it.

One Test at a Time

Don't write multiple tests at once. Follow the cycle: one test → implementation → refactor → next test.

Keep Tests Simple

Tests should be easy to read and understand. Use the Arrange-Act-Assert pattern:

• Arrange: Set up the initial state and dependencies.
• Act: Invoke the function or method being tested.
• Assert: Verify the output or state change.

Test Behavior, Not Implementation

Focus on what the code does, not how it does it. This makes your tests more resilient to internal refactoring.

Common Pitfalls

• Skipping RED: Writing a test that accidentally passes (e.g., because it doesn't assert anything) provides no value.
• The "Big Bang" implementation: Writing too much code in the GREEN phase. Keep it minimal.
• Ignoring REFACTOR: Leaving "quick and dirty" code in the codebase after tests pass.
• Incomplete Mocks: Using real dependencies (databases, APIs) in unit tests, making them slow and flaky.

Integration with other Agents

• dev-planner: Provides the feature breakdown that informs which tests to write.
• code-reviewer: Verifies that the TDD process was followed and that tests are high-quality.
• bug-analyzer: Uses tests to reproduce bugs before implementing fixes.

Helper Scripts

• scripts/run-tests.sh - Run the test suite and generate coverage report.
• scripts/init-test.sh - Scaffold a new test file based on project templates.

Mastery Checklist

• [ ] Does every new feature have a failing test first?
• [ ] Is implementation minimal in the GREEN phase?
• [ ] Was the code refactored and linted after passing?
• [ ] Is test coverage >80% for the modified areas?
• [ ] Are all tests passing after the final implementation?

Boundaries

• Focus on RED-GREEN-REFACTOR-VERIFY discipline for new behavior and bugfixes.
• Do not skip the failing-test reproduction step for bug work unless the owner explicitly accepts the risk.
• Do not use TDD ritualistically when the task is documentation-only or otherwise non-executable.

When NOT to Use

• Pure architecture or design planning → use dev-planner
• Frontend UI implementation → use frontend-design
• API design → use api-designer
• Database schema design → use database-engineer
• Security auditing → use quality-assurance

Escalation Rules

Pause and ask the owner before:

• proceeding when the bug cannot be reproduced with a failing test
• broadening a narrow fix into a large refactor during the GREEN phase
• closing the task with partial verification on high-risk paths

Final Output Contract (MANDATORY)

Every use of this skill should end with:

1. Skill Fit - why TDD is the right workflow here
2. Primary Deliverable - RED/GREEN/REFACTOR progress and changed tests
3. Execution Evidence - failing test, passing test, and verification commands
4. Risks / Open Questions - flaky tests, missing coverage, or blocked environments
5. Next Action - the next verification or implementation step