Skip to main content

TDD Guard

Automated Test-Driven Development enforcement for Claude Code

Author: @nizos  |  GitHub Repo  |  Stats unavailable

Overview​

TDD Guard is a utility that enforces Test-Driven Development principles for Claude Code by intercepting file modification operations and validating TDD adherence. It blocks actions that violate TDD rules, specifically preventing implementation without failing tests, over-implementation beyond test requirements, and adding multiple tests simultaneously.

Features​

  • Test-First Enforcement - Blocks implementation without failing tests
  • Over-Implementation Prevention - Prevents code beyond current test requirements
  • Multiple Test Detection - Blocks adding multiple tests simultaneously
  • Customizable Rules - Adjust validation rules to match your TDD style
  • Multi-Language Support - Works with JavaScript, Python, PHP, Go, and Rust
  • Automated Process Enforcement - Let TDD Guard handle discipline so you focus on design

Installation​

Requirements

  • Node.js 18+
  • Claude Code
  • Test framework for your language

Quick Start

1. Install TDD Guard

npm install -g tdd-guard

2. Add Test Reporter TDD Guard needs to capture test results from your test runner. Choose your language:

  • JavaScript/TypeScript
  • Python (pytest)
  • PHP (PHPUnit)
  • Go
  • Rust

See the official repository for language-specific test reporter setup.

3. Configure Claude Code Hook Use the /hooks command in Claude Code:

  1. Type /hooks in Claude Code
  2. Select PreToolUse - Before tool execution
  3. Choose + Add new matcher... and enter: Write|Edit|MultiEdit|TodoWrite
  4. Select + Add new hook... and enter: tdd-guard
  5. Choose where to save (Project settings recommended)

See Strengthening TDD Enforcement to prevent agents from bypassing validation.

Usage​

TDD Guard runs as a separate process and validates file modifications against TDD principles. It intercepts Write, Edit, and MultiEdit operations, checking for three primary TDD violations:

  1. Implementing functionality without a failing test
  2. Over-implementing beyond test requirements
  3. Adding multiple tests simultaneously

This automation lets you focus on problem-solving and design instead of manually policing TDD process adherence.

Security Notice TDD Guard hooks execute with your full user permissions. Review hook configurations carefully and ensure your development environment is properly secured.

For detailed configuration options and advanced usage patterns, see the official documentation.

Benefits​

TDD Guard automates TDD discipline enforcement, providing several key advantages:

  • Consistent Code Quality - Prevents common AI coding mistakes like jumping straight to implementation
  • Thorough Test Coverage - Ensures tests are written first and cover all functionality
  • Living Documentation - Your test suite becomes comprehensive documentation of your codebase
  • Focus on Design - Automated process enforcement lets you concentrate on problem-solving
  • Extended Enforcement - Can be configured to enforce additional coding standards beyond TDD
Performance Note

Be aware that TDD Guard can introduce lag to your Write, Edit, MultiEdit, and TodoWrite operations as it validates each action against TDD principles.

TDD Guard is developed by Nizar and is open-source under MIT License. For technical support, configuration help, and community discussions, please refer to the official GitHub repository.

Last updated on