Skills Guide

TDD Red/Green/Refactor

VerifiedSafe

Enforces the TDD cycle: write a failing test (red), implement minimal code to pass (green), then refactor while keeping tests green. Best for any testable code change, especially in projects using Vitest.

Download and use
Sby Skills Guide Bot
TestingIntermediate
3/4/2026
Claude CodeCursorCodex
#tdd#red-green-refactor#vitest#unit-testing#test-first

Recommended for

Claude CodeTest generationCursorCodexQA / test engineer

Automated summary

Enforces a strict TDD loop — failing test, minimal implementation, refactor — for any code change that can be covered by tests, with Vitest mandated as the test framework.

Strengths

  • Requires a failing test before any implementation, keeping the work anchored on an observable behavior.
  • Consistently prefers the narrowest test command (single file, then package, then repo).
  • Explicitly bans `bun:test` and supplies the expected Vitest patterns (vi.fn, vi.hoisted, vi.spyOn).
  • Includes a clear fallback procedure when tests cannot run due to missing deps, credentials, or environment.

Limitations

  • Tightly coupled to one stack (Turborepo, `bun run test`, Vitest), so the commands do not transfer as-is.
  • The "types always pass" rule can be unrealistic on a legacy codebase with pre-existing type errors.
  • Sets no coverage target or broader test strategy beyond the smallest observable behavior.
When to use it

Use it for any testable bug fix or feature where you want a failing test to drive the implementation.

When not to use it

Skip it for untestable changes (throwaway scripts, configuration, exploratory prototyping) or on stacks that don't use Vitest.

Security analysis

Safe
Quality score88/100

The skill only defines a standard TDD workflow and uses Bash for running tests. It contains no destructive commands, credential handling, network exfiltration, obfuscation, or safety-disabling instructions.

No concerns found

How this analysis is made

Examples

New feature, test first
Add a processRefund function to packages/core that rejects refunds older than 90 days. Follow TDD: write the failing Vitest test first and show me the red run, then implement the minimal code to make it green.
Bug fix with regression test
The applyDiscount helper rounds incorrectly for zero-decimal currencies. Write a failing Vitest test that reproduces the bug, make it pass with the smallest change, then refactor with tests still green.
Tests can't run locally
I don't have DB credentials locally. I need to add email validation to the signup handler — write the failing test first anyway, note the expected outcome, and give me the exact command to run once I have the env set up.

name: tdd-red-green-refactor description: Enforce TDD workflow (red → green → refactor). Use for any code change that is testable. allowed-tools: Read, Grep, Glob, Edit, Write, Bash

TDD Red / Green / Refactor

Use this skill whenever making code changes that should be covered by tests.

Non-negotiables

  • Start with a failing test that expresses the behavior (red).
  • Implement the smallest change to pass (green).
  • Refactor for clarity/structure after green, keeping tests passing.
  • If no tests exist, add a minimal test harness + a failing test first.

Workflow

  1. Identify the smallest observable behavior.
  2. Add or update a test to fail on current code.
  3. Run the smallest relevant test command (targeted if possible).
  4. Implement the minimal code to make it pass.
  5. Refactor with tests still green.
  6. Report: test command(s) run + results.

If tests cannot run

  • State why (missing deps, env, credentials, etc.).
  • Still write the failing test first and note the expected outcome.
  • Provide a suggested test command for the user to run.

Test targeting

Prefer the narrowest scope:

  • single file
  • package-level
  • repo-level only if needed

Typecheck policy

Types always pass. Do not blame pre-existing errors. Fix or revert.

WE USE VITEST - NOT BUN:TEST

This is non-negotiable. Never use bun:test imports or APIs.

// ✅ CORRECT - Vitest
import { describe, it, expect, vi, beforeEach } from 'vitest'

// ❌ WRONG - bun:test (DO NOT USE)
import { describe, it, expect, mock } from 'bun:test'

Test commands

# All tests via Turborepo
bun run test

# Filtered by package
bun run test --filter=@skillrecordings/core
bun run test --filter=web

# Direct Vitest (when you need fine-grained control)
bun run test:all
bun run test:all -- -t "name of test"
bun run test:all -- packages/core/src/tools/process-refund.test.ts

Common Vitest patterns

// Mocking
const mockFn = vi.fn()
vi.mocked(someModule).someMethod.mockResolvedValue(result)

// Hoisting mocks (required for factory functions)
const mockClient = vi.hoisted(() => ({ method: vi.fn() }))
vi.mock('./client', () => ({ client: mockClient }))

// Spying
vi.spyOn(object, 'method').mockImplementation(...)

Notes to include in the response

  • Which test you wrote first.
  • The command used to hit red and green.
  • Any refactor that changed structure but not behavior.

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/tdd-red-green-refactor-mmbizjlk' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/tdd-red-green-refactor-mmbizjlk/download' --output '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md.part' && mv '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md.part' '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

Tools declared by the author (check availability in your agent): Read, Grep, Glob, Edit, Write, Bash

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

After inspection, copy the complete folder into your project using one of the commands below, then open a new tool session. The command stops if a folder with the same name already exists: compare the files before replacing it.

Claude Code
test -f '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && test -s '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && mkdir -p '.claude/skills' && test ! -e '.claude/skills/tdd-red-green-refactor' && cp -R '.skill-downloads/tdd-red-green-refactor-mmbizjlk' '.claude/skills/tdd-red-green-refactor'

Cursor
test -f '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && test -s '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && mkdir -p '.cursor/skills' && test ! -e '.cursor/skills/tdd-red-green-refactor' && cp -R '.skill-downloads/tdd-red-green-refactor-mmbizjlk' '.cursor/skills/tdd-red-green-refactor'

Codex
test -f '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && test -s '.skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md' && mkdir -p '.agents/skills' && test ! -e '.agents/skills/tdd-red-green-refactor' && cp -R '.skill-downloads/tdd-red-green-refactor-mmbizjlk' '.agents/skills/tdd-red-green-refactor'

OpenSkills

OpenSkills must already be installed. The local install/read procedure is checked with OpenSkills 1.5.0, which requires Node.js ≥ 20.6.0. Catalog slugs are not resolved automatically.

Official OpenSkills installation
openskills install './.skill-downloads/tdd-red-green-refactor-mmbizjlk'

openskills read 'tdd-red-green-refactor-mmbizjlk'

Reading should display the installed file content and its base directory. It does not run the skill or install its dependencies.

For an agent that reads AGENTS.md, then sync the index. This command changes AGENTS.md: review the diff before using it.

openskills sync

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/tdd-red-green-refactor-mmbizjlk/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

ClickHouse Performance Comparison

Testing

Evaluate ClickHouse performance test results, check PR performance changes, compare with history, and assess whether a result is actionable.

Claude CodeintermediateSafe 49,547
Skills Guide Bot

Analyze CI Performance Reports

Testing

Analyze CI performance comparison reports for a ClickHouse PR. Cross-references master history to distinguish real regressions from flaky tests.

Claude CodeintermediateSafe 49,516
Skills Guide Bot

Santa Method

Testing

Multi-agent adversarial verification with two independent reviewers. Output is checked twice and iteratively fixed until both pass before shipping.

Claude CodeCodexCursorintermediateSafe 244,766
Skills Guide Bot