dotfiles/.config/opencode/skills/test-driven-development/SKILL.md

name, description, permalink

name	description	permalink
test-driven-development	Enforce test-first development for features and bug fixes — no production code before a failing test	opencode-config/skills/test-driven-development/skill

Test-Driven Development (TDD)

When to Use

Use this skill when implementing behavior changes:

• New features
• Bug fixes
• Refactors that alter behavior

If the work introduces or changes production behavior, TDD applies.

Core Rule

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

If production code was written first, delete or revert it and restart from a failing test.

Red → Green → Refactor Loop

1) RED: Write one failing test

• Write one small test that expresses the next expected behavior.
• Prefer clear test names describing observable behavior.
• Use real behavior paths where practical; mock only when isolation is required.

2) Verify RED (mandatory)

Run the new test and confirm:

• It fails (not just errors)
• It fails for the expected reason
• It fails because behavior is missing, not because the test is broken

If it passes immediately, the test is not proving the new behavior. Fix the test first.

3) GREEN: Add minimal production code

• Implement only enough code to make the failing test pass.
• Do not add extra features, abstractions, or speculative options.

4) Verify GREEN (mandatory)

Run the test suite scope needed for confidence:

• New test passes
• Related tests still pass

If failures appear, fix production code first unless requirements changed.

5) REFACTOR

• Improve names, remove duplication, and simplify structure.
• Keep behavior unchanged.
• Keep tests green throughout.

Repeat for the next behavior.

Quality Checks Before Completion

• Each behavior change has a test that failed before implementation
• New tests failed for the expected reason first
• Production code was added only after RED was observed
• Tests now pass cleanly
• Edge cases for changed behavior are covered

Practical Guardrails

• "I'll write tests after" is not TDD.
• Manual verification does not replace automated failing-then-passing tests.
• If a test is hard to write, treat it as design feedback and simplify interfaces.
• Keep test intent focused on behavior, not internals.

Related Reference

For common mistakes around mocks and test design, see testing-anti-patterns.