High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- CLAUDE.md
- src/validation/validator.ts (referenced in CLAUDE.md)
- src/config/Config.ts (referenced in Config.test.ts)
- src/guard/GuardManager.ts (referenced in GuardManager.test.ts)
- src/contracts/schemas/toolSchemas.ts (referenced in toolSchemas.test.ts)
TDD Guard is an automated enforcement system designed to ensure that AI coding agents, specifically Claude Code, adhere to Test-Driven Development (TDD) principles. The system operates by intercepting file operations (Write, Edit, MultiEdit) through Claude Code hooks, analyzing the proposed changes against current test results, and utilizing an AI model to validate TDD compliance.
The architecture is built on a modular TypeScript foundation, supported by a suite of multi-language test reporters that bridge the gap between various testing frameworks (Jest, Vitest, pytest, Go, etc.) and the core validation logic. Sources: README.md:9-15, CLAUDE.md:3-10
Core System Components
The project is organized into several distinct layers that handle interception, state management, and validation.
| Component | Responsibility |
|---|---|
| CLI / Hooks | Entry point that parses Claude Code hook events (PreToolUse, UserPromptSubmit). |
| Guard Manager | Manages the enabled/disabled state of the guard and handles file ignore patterns. |
| Storage Layer | Abstractions for persisting test results, configurations, and session data. |
| Validation Engine | Formats context (code changes + test output) and consults an AI model for a decision. |
| Language Reporters | Standalone tools that capture results from native test runners and save them in a standard format. |
Sources: CLAUDE.md:31-48, src/guard/GuardManager.test.ts:7-15, README.md:30-100
Operational Flow
The following diagram illustrates the lifecycle of a single code modification request intercepted by TDD Guard:
The system intercepts operations like Write or Edit before they execute, ensuring the "Red-Green-Refactor" cycle is maintained. Sources: CLAUDE.md:5-10, src/validation/prompts/response.ts:10-20
Validation Logic and AI Integration
The core of TDD Guard's decision-making process is the Validator. It combines the proposed code changes with state information gathered from the local environment to generate a prompt for an AI model (Claude).
Context Building
The validator gathers several pieces of information to form a "Dynamic Context":
- Modifications: The
old_stringvsnew_stringfor edits or the full content for new files. - Test Output: Results from the most recent test run, processed into a human-readable format.
- Todos: Current task status if a todo-tracking tool is used.
- Lint Results: Static analysis status to ensure refactoring follows quality rules.
Sources: src/validation/context/context.test.ts:25-50, src/validation/prompts/tools/test-output.ts
TDD Ruleset
The AI model is instructed via a strict ruleset defined in the prompts/ directory. These rules define what constitutes a violation:
- Multiple Test Addition: Adding more than one new test in a single operation.
- Over-Implementation: Adding logic that exceeds what is required to fix the current failing test (e.g., adding methods when only a class stub is needed).
- Premature Implementation: Writing implementation code before a failing test exists.
Sources: src/validation/prompts/rules.ts:24-45, src/validation/prompts/operations/edit.ts:15-30
Configuration and State Management
The Config class and GuardManager handle the system's operational parameters. Configuration can be driven by environment variables or local configuration files.
The GuardManager uses a Storage implementation (typically FileStorage) to persist settings like guardEnabled and ignorePatterns. Sources: src/config/Config.test.ts:35-60, src/guard/GuardManager.test.ts:40-70
Multi-Language Reporter Architecture
TDD Guard achieves language neutrality through a decentralized reporter architecture. Each supported language provides a reporter that translates native test output into a standardized test.json format located in .claude/tdd-guard/data/.
Reporter Implementation Patterns
- Direct Integration: Reporters like
tdd-guard-vitestortdd-guard-jestplug directly into the test runner's API. - Output Piping: The Go reporter (
tdd-guard-go) and Rust reporter (tdd-guard-rust) act as filters, reading JSON or standard output from the test process and extracting results.
Conclusion
The architecture of TDD Guard is designed for high extensibility and low friction. By offloading the complex "intelligence" of TDD compliance to an AI model while maintaining strict local state through language-specific reporters, it provides a robust enforcement mechanism that integrates directly into the developer's workflow via Claude Code hooks. Sources: README.md:10-20, CLAUDE.md:3-10