# tdd-guide

The tdd-guide Claude Code skill guides red-green-refactor cycles and works with test suites. It can draft tests from requirements and inspect coverage reports for gaps.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 143 installs · ★ 1183 repo stars
- Author: borghei
- License: LicenseRef-MIT-Commons-Clause · policy=link-only · description only; the file stays with the author
- Source: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/tdd-guide/SKILL.md
- Updated: 2026-11-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/borghei-tdd-guide

## What it does

The skill guides red-green-refactor steps, drafts tests from requirements, and reads LCOV, Istanbul JSON, or Cobertura XML coverage reports. It can also assess test quality and convert tests across Jest, Vitest, Pytest, JUnit, and other supported frameworks.

The package includes `scripts/tdd.py`, a CLI with `coverage`, `generate`, and `quality` commands. `coverage` reports files and lines below the target; it returns exit code 1 while gaps remain. Its default threshold is 80, and `--threshold` lets you set another value.

Generated stubs fail until you add a real assertion. To generate them, provide a framework and requirements or an API specification; coverage analysis takes a report file.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill tdd-guide -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tdd-guide/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tdd-guide/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill tdd-guide -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tdd-guide/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill tdd-guide -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tdd-guide/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install borghei/Claude-Skills engineering/tdd-guide/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/tdd-guide/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill tdd-guide -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/borghei/Claude-Skills --path engineering/tdd-guide
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tdd-guide/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add borghei/Claude-Skills --skill tdd-guide -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/borghei/Claude-Skills/tree/HEAD/engineering/tdd-guide/SKILL.md

## When to use it
- write a failing test for a new feature
- draft tests from requirements or an API specification
- find uncovered files and lines in a coverage report
- assess test quality and flag test smells
- convert tests between Jest, Pytest, JUnit, and Vitest

## Example prompts
- Generate pytest stubs from `requirements.json` with `python scripts/tdd.py generate requirements.json --framework pytest`.
- Inspect `coverage.lcov` with a threshold of 80 using `python scripts/tdd.py coverage coverage.lcov --threshold 80`.
- Assess `tests/test_discount.py` and return JSON with `python scripts/tdd.py quality tests/test_discount.py --format json`.

## Similar
- [tdd](https://affpapa.org/en/nevibecode/skills/glebis-tdd.md) — skill · 262 installs
- [tdd-orchestrator](https://affpapa.org/en/nevibecode/skills/tdd-orchestrator.md) — skill · 51 installs
- [TDD Red Phase - Write Failing Tests First](https://affpapa.org/en/nevibecode/agents/tdd-red-phase-write-failing-tests-first.md) — subagent · ★ 41430 repo stars
- [tdd-red](https://affpapa.org/en/nevibecode/commands/tdd-red.md) — command · ★ 42780 repo stars
- [test-analysis-extensions](https://affpapa.org/en/nevibecode/skills/test-analysis-extensions.md) — skill · 4200 installs
- [python-tdd-with-uv](https://affpapa.org/en/nevibecode/skills/python-tdd-with-uv.md) — skill · 449 installs

## Other versions with the same name
- [tdd-guide · alirezarezvani](https://affpapa.org/en/nevibecode/skills/tdd-guide.md) — 1017 installs
- [tdd-guide · alirezarezvani](https://affpapa.org/en/nevibecode/skills/alirezarezvani-tdd-guide.md) — ★ 907 repo stars

From the same set: [borghei/claude-skills](https://affpapa.org/en/nevibecode/by/borghei/claude-skills.md) — 120 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
