# Tdd Workflow

> Standardized Test-Driven Development (TDD) cycle (RED-GREEN-REFACTOR-VERIFY). Use when user asks to write tests, do TDD, implement test-first, or ensure code quality with high test coverage and regression prevention.

- Skill: `jochenyang/tdd-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jochenyang/tdd-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jochenyang/tdd-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: JochenYang (https://skillmd.com/u/jochenyang)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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