# TDD Commands Quick Start Guide

Generic, reusable slash commands for Test-Driven Development with Claude Code.

## What This Is

A set of 5 slash commands that enforce TDD discipline:
- ✅ RED → GREEN → REFACTOR cycle
- ✅ Test behavior, not implementation
- ✅ Prevent common TDD mistakes
- ✅ Work with any language/framework

## Installation

### 1. Copy Command Files

```bash
mkdir -p .claude/commands/
```

Copy these 5 files to `.claude/commands/`:
- `red.md` - Write failing tests (RED phase)
- `green.md` - Implement to pass tests (GREEN phase)
- `next.md` - Pick next feature from TODO
- `test.md` - Run test suite
- `refactor.md` - Improve code quality (optional)

### 2. Create CLAUDE.md

Copy `CLAUDE.md.template` to your project root as `CLAUDE.md` and fill in:
- Project structure
- Test patterns and locations
- Implementation patterns
- Test commands
- Mocking strategy

### 3. Create TODO.md

Copy `TODO.md.template` to your project root as `TODO.md` and fill in:
- Features to implement
- Phase organization
- Priority order
- Current progress

## Usage

### Basic Workflow

```
1. /next        # Pick next feature from TODO.md
   ↓
2. /red         # Claude writes failing tests
   ↓
3. /green       # Claude implements code
   ↓
4. /test        # Verify all tests pass
   ↓
5. /refactor    # Clean up (optional)
   ↓
   Repeat from step 1
```

### Example Session

```
You: /next

Claude: Looking at TODO.md...
        Next feature: "User authentication"
        Starting RED phase - writing tests...
        [Creates tests/test_auth.py with 5 failing tests]
        Tests FAIL ❌ (expected)

You: /green

Claude: Implementing authentication...
        [Creates src/auth.py]
        Tests PASS ✅ (5/5)
        Running full suite... 23/23 tests passing

You: /test

Claude: Running pytest...
        ===== 23 passed in 0.45s =====
        ✅ All tests passing

You: /next

Claude: Next feature: "Password reset flow"
        Starting RED phase...
```

## What Each Command Does

### `/next`
- Reads TODO.md to find next unchecked item
- Reads CLAUDE.md for project context
- Explains what the feature does
- Automatically starts RED phase

### `/red`
- Reads CLAUDE.md for test patterns
- Writes tests describing expected behavior
- Tests public API, not implementation
- Runs tests to confirm they fail

### `/green`
- Reads CLAUDE.md for implementation patterns
- Writes minimal code to pass tests
- Follows existing conventions
- Runs tests to confirm they pass
- Runs full suite to check for regressions

### `/test`
- Reads CLAUDE.md for test command
- Runs full test suite
- Shows summary (passed/failed/time)
- Reports any failures

### `/refactor`
- Reads CLAUDE.md for coding standards
- Looks for code smells (duplication, long methods, etc.)
- Improves code incrementally
- Runs tests after each change
- Stops if tests fail

## Key Features

### Generic Commands
Commands work with any project:
- ✅ Python, JavaScript, TypeScript, Go, Rust, Java, etc.
- ✅ pytest, jest, go test, JUnit, etc.
- ✅ Any project structure

### Project-Specific Context
All project details live in two files:
- **CLAUDE.md** - How to build/test, patterns to follow
- **TODO.md** - What to build, priority order

### Enforces Best Practices
- ❌ Can't skip writing tests first
- ❌ Can't test private methods
- ❌ Can't add untested features
- ❌ Can't break existing tests
- ✅ Forces RED → GREEN → REFACTOR

## What Goes in CLAUDE.md

**Required sections:**
1. Project structure (where files go)
2. Test file naming and location
3. Test structure pattern (example test)
4. What to test vs what not to test
5. Mocking strategy
6. Test command (how to run tests)
7. Implementation patterns

**Optional sections:**
- Commit message format
- Coding standards
- Reference documentation
- Common pitfalls

See `CLAUDE.md.template` for full example.

## What Goes in TODO.md

**Structure:**
```markdown
## Phase 1: Foundation
- [x] Completed feature
- [ ] Next feature          ← /next picks this
- [ ] Feature after that

## Phase 2: Core Features
- [ ] Feature A
- [ ] Feature B
```

**Tips:**
- Organize by priority phases
- Use `[x]` for complete, `[ ]` for incomplete
- Add notes about dependencies
- Keep it up to date

## Common Mistakes to Avoid

### ❌ Don't Do This:
```python
# Testing implementation (HOW it works)
def test_calls_internal_method():
    api._internal_method()  # Don't test private methods

def test_constructs_correct_url():
    assert api._build_url() == "/api/v1/users"  # Don't test URL construction
```

### ✅ Do This:
```python
# Testing behavior (WHAT it does)
def test_list_returns_users():
    """List should return array of User objects."""
    users = api.list()
    assert isinstance(users, list)
    assert all(isinstance(u, User) for u in users)

def test_get_raises_not_found_for_invalid_id():
    """Get should raise NotFoundError for invalid ID."""
    with pytest.raises(NotFoundError):
        api.get(id=999999)
```

## Benefits

**For Developers:**
- 🎯 Clear workflow (no decision fatigue)
- 🛡️ Catch bugs early (tests first)
- 📚 Tests serve as documentation
- 🔄 Safe refactoring (tests protect you)

**For Teams:**
- 📋 Consistent process (everyone uses same workflow)
- 👀 Easy code review (behavior is clear from tests)
- 🚀 Faster onboarding (commands guide new devs)
- ✅ Higher quality (TDD discipline enforced)

## Troubleshooting

**Q: Commands not showing up?**
- Ensure files are in `.claude/commands/`
- Restart Claude Code
- Check file extensions are `.md`

**Q: Claude not following patterns?**
- Check CLAUDE.md has complete examples
- Make sure patterns match your project
- Add more specific examples

**Q: Tests failing in green phase?**
- Re-read the test requirements
- Start with simplest test first
- Check CLAUDE.md patterns

**Q: Need to skip a feature?**
- Update TODO.md to reorder priorities
- `/next` will pick the next unchecked item

## Example Projects

### Python with pytest
- Test location: `tests/unit/`
- Test command: `pytest tests/`
- Mocking: `pytest-httpx` for HTTP

### Node.js with Jest
- Test location: `__tests__/`
- Test command: `npm test`
- Mocking: `jest.mock()` or `nock`

### Go
- Test location: Same dir as code
- Test command: `go test ./...`
- Mocking: `httptest` package

### TypeScript with Vitest
- Test location: `tests/` or `__tests__/`
- Test command: `npm run test`
- Mocking: `vi.mock()` or `msw`

## Files to Share

When sharing with team, provide:
1. `.claude/commands/` directory (5 command files)
2. `CLAUDE.md.template` (for them to customize)
3. `TODO.md.template` (for them to customize)
4. This `TDD-COMMANDS-QUICKSTART.md` guide

## License

These commands are generic TDD workflow tools. Use freely in any project.

---

**Questions or improvements?** Update this guide and share back with the team!
