ECShopX/tdd-guard/docs/configuration.md

Configuration Guide

This guide covers the configuration options for TDD Guard.

Environment Variables

TDD Guard uses environment variables for configuration. Create a .env file in your project root:

Note: If you're migrating from an older version using MODEL_TYPE, see the Configuration Migration Guide.

# Validation client for TDD enforcement (optional)
# Options: 'sdk' (default) or 'api'
VALIDATION_CLIENT=sdk

# Model version for validation (optional)
# Default: claude-sonnet-4-0
# See https://docs.anthropic.com/en/docs/about-claude/models/overview
TDD_GUARD_MODEL_VERSION=claude-sonnet-4-0

# Anthropic API Key
# Required when VALIDATION_CLIENT is set to 'api'
# Get your API key from https://console.anthropic.com/
TDD_GUARD_ANTHROPIC_API_KEY=your-api-key-here

# Linter type for refactoring phase support (optional)
# Options: 'eslint', 'golangci-lint' or unset (no linting)
# See docs/linting.md for detailed setup and configuration
LINTER_TYPE=eslint

Model Configuration

TDD Guard supports multiple validation clients:

• SDK (default) - Uses your Claude Code subscription
• API - Separate billing for CI/CD or faster validation
• CLI (deprecated) - Legacy option, not recommended

For detailed configuration, billing information, and troubleshooting, see the Validation Model Configuration guide.

If you're using the deprecated CLI client, see the Configuration Migration Guide.

Settings File Locations

Choose where to save your settings based on your needs:

• Project settings (.claude/settings.json) - Recommended for team consistency
• Local settings (.claude/settings.local.json) - For personal preferences
• User settings (~/.claude/settings.json) - For global configuration

Hook Configuration

See the Quick Start guide in the main README for detailed hook configuration instructions, including both interactive and manual setup methods.

Additional hooks:

• Quick commands - Enable tdd-guard on/off commands
• Session management - Automatic data clearing and rule setup
• Lint integration - Automated refactoring support
• Strengthening enforcement - Prevent agents from bypassing validation

Test Reporter Configuration

• JavaScript/TypeScript:
  • Vitest reporter configuration
  • Jest reporter configuration
• Python: See Pytest reporter configuration
• PHP: See PHPUnit reporter configuration
• Go: See Go reporter configuration
• Rust: See Rust reporter configuration

Custom Validation Rules

See Custom Instructions to customize TDD validation rules to match your practices.

Data Storage

TDD Guard stores context data in .claude/tdd-guard/data/:

• instructions.md - Your custom TDD validation rules (created automatically, never overwritten)
• test.json - Latest test results from your test runner (Vitest or pytest)
• todos.json - Current todo state
• modifications.json - File modification history
• lint.json - ESLint results (only created when LINTER_TYPE=eslint)

This directory is created automatically and should be added to .gitignore.

Troubleshooting

Dependency Versions

Vitest

Use the latest Vitest version to ensure correct test output format for TDD Guard:

npm install --save-dev vitest@latest

pytest

For Python projects, ensure you have a recent version of pytest:

pip install pytest>=7.0.0

Common Issues

1. TDD Guard not triggering: Check that hooks are properly configured in .claude/settings.json
2. Test results not captured: Ensure VitestReporter is added to your Vitest config
3. "Command not found" errors: Make sure tdd-guard is installed globally with npm install -g tdd-guard
4. Changes not taking effect: Restart your Claude session after modifying hooks or environment variables

Updating TDD Guard

To update to the latest version:

# Update CLI tool
npm update -g tdd-guard

# For JavaScript/TypeScript projects, update the Vitest reporter in your project
npm update tdd-guard-vitest

# For Python projects, update the pytest reporter
pip install --upgrade tdd-guard-pytest

Check your current version:

npm list -g tdd-guard
pip show tdd-guard-pytest