@wbern/claude-instructions



``
_==/ i i \==_
/XX/ |\___/| \XX\
/XXXX\ |XXXXX| /XXXX\
|XXXXXX\_ _XXXXXXX_ _/XXXXXX|
XXXXXXXXXXXxxxxxxxXXXXXXXXXXXxxxxxxxXXXXXXXXXXX
|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX|
XXXXXX/^^^^"\XXXXXXXXXXXXXXXXXXXXX/^^^^^\XXXXXX
|XXX| \XXX/^^\XXXXX/^^\XXX/ |XXX|
\XX\ \X/ \XXX/ \X/ /XX/
"\ " \X/ " /"
`

TDD workflow commands for Claude Code CLI.

> "TDD helps you to pay attention to the right issues at the right time so you can make your designs cleaner, you can refine your designs as you learn." — Kent Beck

Claude Code supports custom slash commands—type /foo and Claude receives the contents of foo.md as instructions (from .claude/commands/ in your repo or ~/.claude/commands/ in your home directory). This repo provides ready-made commands for Test-Driven Development workflows.

Custom commands are just a glorified copy-paste mechanism—but that simplicity is what makes them effective for establishing consistent development practices.

Instead of explaining TDD principles each session, type /red to write a failing test, /green to make it pass, /refactor to clean up. The commands guide Claude through each step methodically—you focus on what to build, Claude handles the how.

Want to go faster? Use /cycle to let Claude run the entire red-green-refactor sequence before checking in with you. For even more autonomy (your mileage may vary), /tdd gives Claude full discretion on when to advance between phases.

Also included are commands for commits, PRs, code reviews, and other tasks that come up during day-to-day development.

Installation

`bash
npx @wbern/claude-instructions # npm
`

`bash
pnpm dlx @wbern/claude-instructions # pnpm
`

The interactive installer lets you choose:

- Feature flags: Enable optional integrations like Beads MCP
- Scope: User-level (global) or project-level installation

After installation, restart Claude Code if it's currently running.

$3

To automatically regenerate commands when teammates install dependencies, add it as a dev dependency with a postinstall script:

`bash
npm install --save-dev @wbern/claude-instructions
`

Then add a postinstall script to your package.json:

`json
{
"scripts": {
"postinstall": "claude-instructions --scope=project --overwrite"
},
"devDependencies": {
"@wbern/claude-instructions": "^2.10.0"
}
}
`

This ensures commands are regenerated whenever anyone runs npm install, pnpm install, or yarn install.

CLI Options:

| Option | Description |
|--------|-------------|
| --scope=project | Installation scope (project, user) |
| --prefix=my- | Add prefix to command names |
| --commands=commit,red,green | Install only specific commands |
| --skip-template-injection | Skip injecting project CLAUDE.md customizations |
| --update-existing | Only update already-installed commands |
| --overwrite | Overwrite conflicting files without prompting |
| --skip-on-conflict | Skip conflicting files without prompting |
| --flags=beads,github | Enable feature flags (beads, github, gitlab, etc.) |
| --allowed-tools=Bash(git diff:),Bash(git status:) | Pre-approve tools for commands (non-interactive mode) |
| --skills=tdd,commit | Generate selected commands as skills (.claude/skills/) |
| --help, -h | Show help message |
| --version, -v | Show version number |

Customizing Commands

You can inject project-specific instructions into generated commands by adding a block to your CLAUDE.md or AGENTS.md file.

$3

Add this to your project's CLAUDE.md:

`markdown


My Project

Other instructions here...

Project-Specific Rules

- Always use pnpm instead of npm
- Run tests with pnpm test

`

When you run claude-instructions, the template content is appended to all generated commands.

$3

Use the commands attribute to inject content only into specific commands:

`markdown



Git Conventions

- Use conventional commits format
- Reference issue numbers in commits

`

This injects the content only into commit.md and ask.md.

$3

The generator looks for template blocks in this order:

1. CLAUDE.md (checked first)
2. AGENTS.md (fallback)

Only the first file found is used.

Which Command Should I Use?

$3

This is the core TDD workflow. Additional utility commands (worktrees, spikes, etc.) are listed in Available Commands below.

`mermaid
flowchart TB
Start([Start New Work])

Start --> Step1[1. PLAN]

Step1 --> Issue[📋 /issue
Have GitHub issue
Requires: GitHub MCP]
Step1 --> CreateIssues[📝 /create-issues
No issue yet
Optional: Beads MCP]

Issue --> Step2[2. CODE with TDD]
CreateIssues --> Step2

Step2 -->|Manual| Red[🔴 /red
Write failing test]
Red --> Green[🟢 /green
Make it pass]
Green --> Refactor[🔵 /refactor
Clean up code]
Refactor --> MoreTests{More tests?}

Step2 -->|Automated| Cycle[🔄 /cycle
Runs red+green+refactor]
Cycle --> MoreTests

MoreTests -->|Yes| Step2
MoreTests -->|No| Step3

Step3[3. SHIP]

Step3 --> Commit[📦 /commit
Create commit]
Commit --> ShipChoice{How to
merge?}

ShipChoice -->|Simple change| Ship[🚢 /ship
Direct to main
Requires: GitHub MCP]
ShipChoice -->|Show team| Show[👀 /show
Auto-merge + notify
Requires: GitHub MCP]
ShipChoice -->|Needs review| Ask[💬 /ask
Create PR
Requires: GitHub MCP]

Ship --> Done([✅ Done])
Show --> Done
Ask --> Done
`

Available Commands

$3

- /issue - Analyze GitHub issue and create TDD implementation plan
- /create-issues - Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria

$3

- /spike - Execute TDD Spike Phase - exploratory coding to understand problem space before TDD
- /tdd - Remind agent about TDD approach and continue conversation
- /red - Execute TDD Red Phase - write ONE failing test
- /green - Execute TDD Green Phase - write minimal implementation to pass the failing test
- /refactor - Execute TDD Refactor Phase - improve code structure while keeping tests green
- /cycle - Execute complete TDD cycle - Red, Green, and Refactor phases in sequence
- /simplify - Reduce code complexity while keeping tests green
- /tdd-review - Review test suite quality against FIRST principles and TDD anti-patterns

$3

- /commit - Create a git commit following project standards
- /busycommit - Create multiple atomic git commits, one logical change at a time
- /pr - Creates a pull request using GitHub MCP
- /summarize - Summarize conversation progress and next steps
- /gap - Analyze conversation context for unaddressed items and gaps
- /forever - Run autonomously until stopped or stuck
- /code-review - Code review using dynamic category detection and domain-specific analysis
- /polish - Review and address issues in existing code - fix problems or justify skipping

$3

- /ship - Ship code directly to main - for small, obvious changes that don't need review
- /show - Show code to team with auto-merge - for changes that should be visible but don't need approval
- /ask - Request team review and approval - for complex changes needing discussion

$3

- /worktree-add - Add a new git worktree from branch name or issue URL, copy settings, install deps, and open in current IDE
- /worktree-cleanup - Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees

$3

- /beepboop - Communicate AI-generated content with transparent attribution
- /add-command - Guide for creating new slash commands
- /kata - Generate a TDD practice challenge with boilerplate test setup
- /create-adr - Create a new Architecture Decision Record (ADR)
- /research - Research a problem in parallel via web docs, web search, codebase exploration, and deep ultrathink
- /commitlint-checklist-nodejs - Audit commit hook automation for Node.js projects
- /upgrade-deps - Check for dependency upgrades and assess safety before updating

Getting Started

$3

Here's a simple example to get you started with the TDD workflow:

1. Write a failing test (/red)

`
You: /red add a function that validates email addresses

Claude: I'll write a failing test for email validation.
[Creates test file with a test that checks email validation]
[Runs test - shows it failing because function doesn't exist yet]
`

2. Make it pass (/green)

`
You: /green

Claude: I'll implement the minimal code to pass the test.
[Creates the email validation function with basic implementation]
[Runs test - shows it passing]
`

3. Refactor for quality (/refactor)

`
You: /refactor extract regex pattern to a constant

Claude: I'll refactor while keeping tests green.
[Extracts magic values, improves code structure]
[Runs tests - confirms they still pass]
`

$3

Starting from a GitHub issue:

`
/issue 123
`

Claude analyzes the GitHub issue and creates a TDD implementation plan showing what tests to write.

Running a full TDD cycle:

`
/cycle implement user authentication with password hashing
`

Claude executes the complete red-green-refactor cycle: writes a failing test, implements it, then refactors.

Individual phases for more control:

`
/red test that users can't login with wrong password
/green
/refactor move password verification to separate function
`

Committing and creating PRs:

`
/commit
`

Claude reviews changes, drafts a commit message following project standards, and creates the commit.

`
/ask
`

Claude analyzes commits, creates a PR with summary and test plan.

$3

- /red - Claude writes ONE failing test based on your description
- /green - Claude writes minimal implementation to pass the current failing test
- /refactor - Claude improves code structure without changing behavior
- /cycle - Claude runs all three phases in sequence for a complete feature

The commands enforce TDD discipline: you can't refactor with failing tests, can't write multiple tests at once, and implementation must match test requirements.

Example Conversations

Conversation: Solving "Find Closest to Zero" Code Challenge

Summary: User works through solving a code challenge: given a list of integers, find the closest to zero. If there is a tie, choose the positive value. (challenge from cyber-dojo.org)

Commands: /red /green /refactor
Legend: 🔴 Red (test fails) | 🟢 Green (test passes) | 🔵 Refactor (cleanup)

---

👤 /red single element [1] returns 1

🔴 _writes test_

`typescript
expect(closestToZero([1])).toBe(1);
`

FAIL: closestToZero is not defined

👤 /green

🟢 _returns hardcoded 1_

`typescript
function closestToZero(nums: number[]): number {
return 1; // minimal - only need to pass current test
}
`

✅ Test passes

👤 /red two numbers [3, 2] returns 2

🔴 _writes test_

`typescript
expect(closestToZero([3, 2])).toBe(2);
`

FAIL: expected 1 to be 2

👤 /green

🟢 _sorts and returns first_

`typescript
function closestToZero(nums: number[]): number {
return nums.sort((a, b) => a - b)[0]; // minimal
}
`

✅ 2/2 tests pass

👤 /red with negative [-3, 2] returns 2

🔴 _writes test_

`typescript
expect(closestToZero([-3, 2])).toBe(2);
`

FAIL: expected -3 to be 2 (regular sort puts -3 first)

👤 /green

🟢 _sorts by absolute value_

`typescript
function closestToZero(nums: number[]): number {
return nums.sort((a, b) => Math.abs(a) - Math.abs(b))[0];
}
`

✅ 3/3 tests pass

👤 /red exact tie [-2, 2] returns positive 2

🔴 _writes test_

`typescript
expect(closestToZero([-2, 2])).toBe(2);
`

FAIL: expected -2 to be 2 (returns first when tied)

👤 /green

🟢 _adds tie-breaking: prefer positive_

`typescript
function closestToZero(nums: number[]): number {
return nums.sort((a, b) => {
const diff = Math.abs(a) - Math.abs(b);
return diff !== 0 ? diff : b - a;
})[0];
}
`

✅ 4/4 tests pass

👤 /refactor extract helper and use iteration instead of sort

🔵 _extracts helper function for comparison logic_

`typescript
function isCloser(candidate: number, current: number): boolean {
const candAbs = Math.abs(candidate);
const currAbs = Math.abs(current);
return candAbs < currAbs || (candAbs === currAbs && candidate > current);
}

function closestToZero(nums: number[]): number {
if (nums.length === 0) return 0;
let closest = nums[0];
for (const num of nums) {
if (isCloser(num, closest)) {
closest = num;
}
}
return closest;
}
`

✅ 4/4 tests still pass

👤 /refactor

🔵 _uses reduce for more functional style_

`typescript
function closestToZero(nums: number[]): number {
if (nums.length === 0) return 0;
return nums.reduce((closest, num) =>
isCloser(num, closest) ? num : closest,
);
}
``

✅ 4/4 tests still pass

Contributing

See CONTRIBUTING.md for development workflow, build system, and fragment management.

Credits

TDD workflow instructions adapted from TDD Guard by Nizar.

FIRST principles and test quality criteria from TDD Manifesto.

Example kata from Cyber-Dojo.