# tdd-guard

**Repository Path**: vcdplus/tdd-guard

## Basic Information

- **Project Name**: tdd-guard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-01
- **Last Updated**: 2025-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TDD Guard

[![npm version](https://badge.fury.io/js/tdd-guard.svg)](https://www.npmjs.com/package/tdd-guard)
[![CI](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/nizos/tdd-guard/actions/workflows/ci.yml)
[![Security](https://github.com/nizos/tdd-guard/actions/workflows/security.yml/badge.svg)](https://github.com/nizos/tdd-guard/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

为Claude Code提供自动化的测试驱动开发强制执行。

## 概述

TDD Guard确保Claude Code遵循测试驱动开发原则。当您的代理尝试跳过测试或过度实现时，TDD Guard会阻止该操作并解释需要做什么来代替——自动强制执行红-绿-重构周期。

<p align="center">
  <a href="https://nizar.se/uploads/videos/tdd-guard-demo.mp4">
    <img src="docs/assets/tdd-guard-demo-screenshot.gif" alt="TDD Guard Demo" width="600">
  </a>
  <br>
  <em>点击观看TDD Guard的实际运行</em>
</p>

## 特性

- **测试优先强制执行** - 阻止没有失败测试的实现
- **最小实现** - 防止超出当前测试要求的代码
- **Lint集成** - 使用您的linting规则强制重构
- **多语言支持** - TypeScript, JavaScript, Python, PHP, Go, and Rust
- **可定制规则** - 调整验证规则以匹配您的TDD风格
- **灵活验证** - 使用本地Claude或更快的Anthropic API
- **会话控制** - 在会话中途开启和关闭

## 如何阻止跳过测试或过度实现

TDD Guard通过多层防护体系来确保严格的TDD实践：

### 核心防护机制

#### 1. **钩子集成验证**
- 通过Claude Code的`PreToolUse`钩子，在每次文件操作（Write、Edit、MultiEdit）前自动触发验证
- 验证失败时会阻止操作并提供具体原因和下一步指导

#### 2. **AI驱动智能分析**
- 使用Claude模型分析代码修改是否符合TDD原则
- 基于动态生成的上下文提示进行验证，包括：
  - 当前测试状态
  - 代码修改内容
  - 文件类型识别
  - TODO列表状态

#### 3. **严格的TDD周期强制执行**

**Red Phase（红灯阶段）**：
- 只允许一次添加一个测试
- 必须是描述期望行为的失败测试

**Green Phase（绿灯阶段）**：
- 只允许编写刚好使当前测试通过的最小代码
- 根据测试失败类型匹配实现：
  - `"not defined"` → 只创建空存根
  - `"not a function"` → 只添加方法存根
  - 断言错误 → 只实现断言所需的最小逻辑

**Refactor Phase（重构阶段）**：
- 只有在相关测试通过时才允许重构
- 禁止在重构阶段添加新功能

#### 4. **绝对违规检测**
以下情况总是被阻止：
- **多重测试添加**：一次操作添加多个新测试
- **过度实现**：代码超出当前测试要求的实现
- **提前实现**：没有失败测试就编写实现代码
- **带红灯重构**：测试失败时尝试重构

#### 5. **防护措施防止绕过**
- **配置保护**：阻止读取`.claude/tdd-guard/**`目录
- **命令拦截**：阻止使用可能绕过验证的shell命令（如`sed`、`awk`等）
- **忽略模式**：可配置忽略特定文件类型

### 实施建议

1. **正确配置钩子**：在Claude Code中设置`PreToolUse`钩子匹配`Write|Edit|MultiEdit|TodoWrite`

2. **设置防护权限**：
```json
{
  "permissions": {
    "deny": ["Read(.claude/tdd-guard/**)"]
  }
}
```

3. **选择合适的AI模型**：根据需求选择Claude CLI或Anthropic API

4. **配置测试报告器**：根据使用的测试框架安装对应的报告器

这种多层防护确保了严格的TDD实践，强制开发者遵循红-绿-重构周期，防止跳过测试步骤或过度实现未测试的功能。

## 要求

- Node.js 18+
- Claude Code或Anthropic API密钥
- 测试框架 (Jest, Vitest, pytest, PHPUnit, Go 1.24+, or Rust with cargo/cargo-nextest)

## 快速开始

### 1. 安装TDD Guard

```bash
npm install -g tdd-guard
```

### 2. 添加测试报告器

TDD Guard需要从您的测试运行器捕获测试结果。请在下方选择您的语言：

<details>
<summary><b>JavaScript/TypeScript</b></summary>

选择您的测试运行器：

#### Vitest

在您的项目中安装[tdd-guard-vitest](https://www.npmjs.com/package/tdd-guard-vitest)报告器：

```bash
npm install --save-dev tdd-guard-vitest
```

添加到您的`vitest.config.ts`：

```typescript
import { defineConfig } from 'vitest/config'
import { VitestReporter } from 'tdd-guard-vitest'

export default defineConfig({
  test: {
    reporters: [
      'default',
      new VitestReporter('/Users/username/projects/my-app'),
    ],
  },
})
```

#### Jest

在您的项目中安装[tdd-guard-jest](https://www.npmjs.com/package/tdd-guard-jest)报告器：

```bash
npm install --save-dev tdd-guard-jest
```

添加到您的`jest.config.ts`：

```typescript
import type { Config } from 'jest'

const config: Config = {
  reporters: [
    'default',
    [
      'tdd-guard-jest',
      {
        projectRoot: '/Users/username/projects/my-app',
      },
    ],
  ],
}

export default config
```

**注意：** 对于Vitest和Jest，当您的测试配置不在项目根目录时（例如，在工作区或monorepo中），请指定项目根路径。这确保TDD Guard可以找到测试结果。有关更多详细信息，请参阅报告器配置文档：

- [Vitest configuration](reporters/vitest/README.md#configuration)
- [Jest configuration](reporters/jest/README.md#configuration)

</details>

<details>
<summary><b>Python (pytest)</b></summary>

安装[tdd-guard-pytest](https://pypi.org/project/tdd-guard-pytest)报告器：

```bash
pip install tdd-guard-pytest
```

在您的`pyproject.toml`中配置项目根目录：

```toml
[tool.pytest.ini_options]
tdd_guard_project_root = "/Users/username/projects/my-app"
```

**注意：** 当您的测试从子目录运行或在monorepo设置中时，请指定项目根路径。这确保TDD Guard可以找到测试结果。有关替代配置方法（pytest.ini, setup.cfg），请参阅[pytest报告器配置](reporters/pytest/README.md#configuration)。

</details>

<details>
<summary><b>PHP (PHPUnit)</b></summary>

在您的项目中安装tdd-guard/phpunit报告器：

```bash
composer require --dev tdd-guard/phpunit
```

对于PHPUnit 9.x，添加到您的`phpunit.xml`：

```xml
<listeners>
    <listener class="TddGuard\PHPUnit\TddGuardListener">
        <arguments>
            <string>/Users/username/projects/my-app</string>
        </arguments>
    </listener>
</listeners>
```

对于PHPUnit 10.x/11.x/12.x，添加到您的`phpunit.xml`：

```xml
<extensions>
    <bootstrap class="TddGuard\PHPUnit\TddGuardExtension">
        <parameter name="projectRoot" value="/Users/username/projects/my-app"/>
    </bootstrap>
</extensions>
```

**注意：** 当您的phpunit.xml不在项目根目录时（例如，在子目录或monorepo中），请指定项目根路径。这确保TDD Guard可以找到测试结果。报告器将结果保存到`.claude/tdd-guard/data/test.json`。

</details>

<details>
<summary><b>Go</b></summary>

安装tdd-guard-go报告器：

```bash
go install github.com/nizos/tdd-guard/reporters/go/cmd/tdd-guard-go@latest
```

将`go test -json`输出管道到报告器：

```bash
go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app
```

对于Makefile集成：

```makefile
test:
	go test -json ./... 2>&1 | tdd-guard-go -project-root /Users/username/projects/my-app
```

**注意：** 报告器充当过滤器，将测试输出原样传递，同时为TDD Guard捕获结果。有关更多详细信息，请参阅[Go报告器配置](reporters/go/README.md#configuration)。

</details>

<details>
<summary><b>Rust</b></summary>

安装tdd-guard-rust报告器：

```bash
cargo install tdd-guard-rust
```

使用它从`cargo test`或`cargo nextest`捕获测试结果：

```bash
# With nextest (recommended)
cargo nextest run 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough

# With cargo test
cargo test -- -Z unstable-options --format json 2>&1 | tdd-guard-rust --project-root /Users/username/projects/my-app --passthrough
```

对于Makefile集成：

```makefile
test:
	cargo nextest run 2>&1 | tdd-guard-rust --project-root $(PWD) --passthrough
```

**注意：** 报告器充当过滤器，将测试输出原样传递，同时为TDD Guard捕获结果。有关更多详细信息，请参阅[Rust报告器配置](reporters/rust/README.md#configuration)。

</details>

### 3. 配置Claude Code钩子

在Claude Code中使用`/hooks`命令：

1. 在Claude Code中输入`/hooks`
2. 选择`PreToolUse - Before tool execution`
3. 选择`+ Add new matcher...`并输入：`Write|Edit|MultiEdit|TodoWrite`
4. 选择`+ Add new hook...`并输入：`tdd-guard`
5. 选择保存位置（推荐项目设置）

请参阅[加强TDD强制执行](docs/enforcement.md)以防止代理绕过验证。

## 配置

**快速设置：**

- [切换命令](docs/quick-commands.md) - 使用`tdd-guard on/off`启用/禁用
- [会话清除](docs/session-clearing.md) - 新会话自动清理
- [自定义指令](docs/custom-instructions.md) - 自定义TDD验证规则
- [忽略模式](docs/ignore-patterns.md) - 控制哪些文件被验证

**高级：**

- [ESLint集成](docs/linting.md) - 自动重构支持
- [AI模型](docs/ai-model.md) - 在Claude CLI和Anthropic API之间切换

**注意：** 如果TDD Guard找不到Claude，请参阅[Claude二进制设置](docs/claude-binary.md)。

## 安全通知

正如[Claude Code钩子文档](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations)所述：

> 钩子以您的完整用户权限执行shell命令，无需确认。您负责确保您的钩子安全可靠。Anthropic不对因使用钩子而导致的数据丢失或系统损坏承担责任。

我们出于透明度分享此信息。请在使用钩子之前阅读完整的[安全注意事项](https://docs.anthropic.com/en/docs/claude-code/hooks#security-considerations)。

TDD Guard以您的用户权限运行，并可以访问您的文件系统。我们遵循安全最佳实践，包括自动安全扫描、依赖审计和测试驱动开发。如果您有安全顾虑，请审查源代码。

## 路线图

- 添加对更多测试框架的支持 (Mocha, unittest, etc.)
- 添加对其他编程语言的支持 (Ruby, Java, C#, etc.)
- 验证通过MCPs和shell命令进行的文件修改
- 为OpenCode和其他供应商无关的AI编码工具添加集成
- 当测试为绿色时鼓励有意义的重新构建机会
- 添加对每个项目多个并发会话的支持

## 架构分析

### 项目概述

TDD Guard是一个为Claude Code提供自动化测试驱动开发强制执行的工具。它确保Claude Code遵循TDD原则，通过阻止跳过测试或过度实现来强制执行红-绿-重构周期。

### 核心架构

#### 1. **多语言、多框架支持**
- **支持的语言和框架**：
  - JavaScript/TypeScript: Jest, Vitest
  - Python: pytest
  - PHP: PHPUnit
  - Go: go test
  - Rust: cargo test, cargo nextest
  - Ruby: RSpec (规划中)

#### 2. **架构分层**

```
┌─────────────────┐
│   CLI Layer     │  ← 命令行接口
├─────────────────┤
│   Hook Layer    │  ← Claude Code钩子集成
├─────────────────┤
│   Guard Layer   │  ← 核心Guard机制
├─────────────────┤
│ Validator Layer │  ← AI验证逻辑
├─────────────────┤
│ Reporter Layer  │  ← 多语言测试报告器
├─────────────────┤
│ Storage Layer   │  ← 数据持久化
└─────────────────┘
```

### 核心组件分析

#### **GuardManager** (`src/guard/GuardManager.ts`)
- **职责**：管理TDD Guard的启用/禁用状态和忽略模式
- **功能**：
  - 启用/禁用Guard
  - 文件忽略模式匹配
  - 配置持久化
- **设计模式**：单例模式，依赖注入

#### **验证器** (`src/validation/validator.ts`)
- **职责**：使用AI模型验证代码修改是否符合TDD原则
- **流程**：
  1. 生成动态上下文提示
  2. 调用AI模型（Claude CLI或Anthropic API）
  3. 解析模型响应
  4. 返回验证结果（block/approve）

#### **钩子处理器** (`src/hooks/processHookData.ts`)
- **职责**：处理Claude Code的钩子事件
- **支持的事件类型**：
  - `PreToolUse`: 工具使用前验证
  - `PostToolUse`: 工具使用后处理
  - `SessionStart`: 会话开始
  - `UserPromptSubmit`: 用户命令处理

#### **配置系统** (`src/config/Config.ts`)
- **职责**：管理项目配置和环境变量
- **配置项**：
  - 数据目录路径
  - AI模型类型
  - Linter类型
  - 项目根目录

### 报告器架构

#### **统一接口设计**
每个语言的报告器都遵循相同的架构模式：

```
Input → Parser → Transformer → Storage
```

#### **Go报告器示例** (`reporters/go/`)
- **Parser**: 解析`go test -json`输出
- **Transformer**: 转换测试结果为统一格式
- **Storage**: 保存到`.claude/tdd-guard/data/test.json`
- **Formatter**: 格式化输出，保持原始测试输出

#### **其他报告器**
- **Jest/Vitest**: 集成到测试配置中
- **pytest**: 通过插件系统
- **PHPUnit**: 通过监听器和扩展
- **Rust**: 作为cargo命令的管道过滤器

### 数据流和逻辑流程

#### **完整TDD周期验证流程**

```
1. 用户输入命令
   ↓
2. Claude Code触发PreToolUse钩子
   ↓
3. processHookData处理钩子事件
   ↓
4. 检查Guard是否启用
   ↓
5. 检查文件是否被忽略
   ↓
6. 构建验证上下文
   ↓
7. 调用AI验证器
   ↓
8. AI模型分析代码修改
   ↓
9. 返回验证结果 (block/approve)
   ↓
10. 如果block，阻止操作并显示原因
```

#### **测试结果收集流程**

```
测试运行 → 报告器 → 解析 → 转换 → 存储
     ↓         ↓       ↓      ↓       ↓
   go test   tdd-guard-go  JSON   统一格式  test.json
   pytest    pytest插件    JSON   统一格式  test.json
   jest      jest报告器    JSON   统一格式  test.json
```

#### **代码质量检查流程**

```
PostToolUse → 检测文件修改 → 运行Linter → 存储结果 → 下次验证时检查
```

### 存储架构

#### **数据文件结构**
```
.claude/tdd-guard/data/
├── test.json          # 测试结果
├── modifications.json # 代码修改记录
├── todos.json         # TODO列表
├── lint.json          # 代码质量检查结果
├── config.json        # Guard配置
└── instructions.md    # 自定义指令
```

#### **存储接口** (`src/storage/Storage.ts`)
- **职责**：抽象存储操作
- **实现**：文件系统存储 (`FileStorage`)
- **设计模式**：策略模式，支持不同存储后端

### 合约和类型系统

#### **Schema验证**
- 使用Zod进行运行时类型验证
- 确保数据一致性和安全性
- 支持多语言测试结果的统一格式

#### **类型定义**
- `ValidationResult`: 验证结果（block/approve）
- `Context`: 验证上下文
- `HookData`: 钩子事件数据
- `TestResult`: 统一测试结果格式

### 设计模式和最佳实践

#### **采用的设计模式**
1. **策略模式**: 不同AI模型的验证策略
2. **观察者模式**: 钩子事件处理
3. **工厂模式**: 报告器和Linter的创建
4. **适配器模式**: 不同测试框架的适配
5. **命令模式**: 用户命令处理

#### **架构优势**
- **可扩展性**: 易于添加新语言和测试框架
- **可维护性**: 清晰的分层架构
- **类型安全**: 全面的TypeScript类型定义
- **测试友好**: 完整的单元测试覆盖

### 安全考虑

#### **安全措施**
- 环境变量验证
- 路径遍历防护
- 输入数据验证
- 最小权限原则

#### **透明度**
- 开源代码审查
- 安全扫描集成
- 明确的安全警告

### 总结

TDD Guard是一个设计精良的TDD强制执行工具，具有：

1. **多语言支持**: 支持主流编程语言和测试框架
2. **AI驱动验证**: 使用Claude进行智能代码分析
3. **钩子集成**: 无缝集成到Claude Code工作流
4. **可配置性**: 灵活的配置和自定义选项
5. **健壮性**: 完善的错误处理和类型安全
6. **可扩展性**: 模块化架构便于功能扩展

该项目展示了现代软件架构的最佳实践，结合了AI技术、测试驱动开发原则和工程化方法，为开发者提供了强大的TDD实践工具。

## 开发

- [开发指南](DEVELOPMENT.md) - 设置说明和开发指南
- [架构决策记录](docs/adr/) - 技术设计决策和理由

## 贡献

欢迎贡献！随时提交问题和拉取请求。

**贡献者：**

- Python/pytest支持：[@Durafen](https://github.com/Durafen)
- PHP/PHPUnit支持：[@wazum](https://github.com/wazum)
- Rust/cargo支持：[@104hp6u](https://github.com/104hp6u)

## 支持

- [配置](docs/configuration.md) - 完整的设置文档
- [讨论](https://github.com/nizos/tdd-guard/discussions) - 提出问题并分享想法
- [问题](https://github.com/nizos/tdd-guard/issues) - 报告错误并请求功能

## 许可证

[MIT](LICENSE)