tdd-guard: Instructions file for Claude Code

TDD Guard

Project Goal

TDD Guard is a Claude Code hook that enforces Test-Driven Development by intercepting file operations. When Claude Code attempts to edit or write files, TDD Guard:

1. Captures: Intercepts Edit, MultiEdit, and Write operations
2. Analyzes: Examines test results, file paths, and code changes
3. Validates: Checks TDD compliance using an AI model
4. Blocks: Prevents operations that skip tests or over-implement
5. Guides: Explains violations and suggests corrections

This automated enforcement maintains code quality without cluttering prompts with TDD reminders.

Development Workflow

Commit Guidelines

• Atomic commits: Each commit represents one logical change with its tests
• Test and implementation together: Never separate tests from the code they test
• Explain why, not what: Commit messages should explain the reason for the change
• Conventional format: Use prefixes to categorize changes: feat, fix, refactor, test, chore, docs

Example: feat: add network request filtering to reduce noise in captured data (explains why, not just what)

Project Structure

The codebase is organized with core functionality in src/ and language-specific reporters:

reporters/                        # Language-specific test reporters
├── go/                           # tdd-guard-go - Go test reporter
├── jest/                         # tdd-guard-jest - Jest reporter (npm)
├── minitest/                     # tdd-guard-minitest - Minitest reporter (gem)
├── phpunit/                      # tdd-guard/phpunit - PHPUnit reporter (composer)
├── pytest/                       # tdd-guard-pytest - Pytest reporter (pip)
├── rspec/                        # tdd-guard-rspec - RSpec reporter (gem)
├── rust/                         # tdd-guard-rust - Rust test reporter (crates.io)
├── storybook/                    # tdd-guard-storybook - Storybook test-runner reporter (npm)
├── test/                         # Shared test artifacts and integration tests
└── vitest/                       # tdd-guard-vitest - Vitest reporter (npm)

src/                              # Main CLI application
├── cli/                          # Hook entry point and context builder
├── config/                       # Configuration management
├── contracts/                    # Types and Zod schemas
├── guard/                        # Guard enable/disable management
├── hooks/                        # Claude Code hook parsing and processing
├── linters/                      # ESLint integration for code quality
├── processors/                   # Test result and lint processing
├── providers/                    # Model and linter client factories
├── storage/                      # Storage abstractions
├── validation/                   # TDD principle validation
│   ├── validator.ts              # Sends context to AI model and parses response
│   ├── context/                  # Formats operations for AI validation
│   ├── prompts/                  # TDD validation rules and AI instructions
│   └── models/                   # Claude SDK and Anthropic API clients
└── index.ts                      # Package entry point

test/                             # Main test suite (hooks, integration, utils)
docs/                             # Documentation (ADRs, configuration, etc.)