1. 总则

1.1. 概述

为了确保 AI Agent 遵循 TDD(测试驱动开发)的开发模式,Agent 必须严格按照 Red-Green-Refactor 三个阶段的循环进行开发。在执行每个阶段前,Agent 必须向开发者明确声明其当前所处的阶段。

本准则旨在确保 Agent 遵循正确的 TDD 开发流程,避免跳过关键步骤。

1.2. 环境配置:强制使用指定的 settings.xml

核心要求: 所有对 mvn@ 命令的调用(如 mvn test@, mvn compile@ 等),都**必须**使用 --settings@ (或 -s@) 参数来指定一个自定义的 settings.xml 文件,以确保能够访问内部的 Maven 仓库。

  • 命令格式示例: mvn --settings [settings.xml的绝对路径] test

  • settings.xml 文件路径: [settings.xml的绝对路径]

Agent 在执行任何 Maven 命令前,必须确认此路径已被正确配置和使用。

核心要求: 所有对 python 命令的调用(如 python test_example.py),都**必须**使用 --settings@ (或 -s@) 参数来指定一个自定义的 settings.xml 文件,以确保能够访问项目代码文件。

  • 命令格式示例: mvn --settings [settings.xml的绝对路径] test

  • settings.xml 文件路径: [settings.xml的绝对路径]

Agent 在执行任何 python命令或者cmd命令行前,必须确认此路径已被正确配置和使用。


2. TDD 三阶段循环

2.1. 第一阶段:RED (写失败的测试)

2.1.1. 目标

编写一个必然失败的测试用例,明确定义即将实现的功能需求。

2.1.2. 核心准则

  • 允许: Agent 可以在 src/test/ 目录下创建新的测试文件或添加新的测试方法

  • 要求:

    • 测试必须是失败的(因为对应的实现代码尚未存在或不完整)

    • 一次只测试一个功能点

    • 测试代码要简单清晰

    • 测试名称要明确表达测试意图

  • 禁止: Agent 不能修改 src/main/ 目录下的任何现有代码

  • 验证: 运行测试必须显示红色(失败状态)

2.1.3. 交互示例

  • 开发者提示: "我需要实现一个计算器的加法功能"

  • Agent 回应: "已激活 RED 阶段。我将先编写一个失败的测试用例来定义加法功能的需求。"

2.2. 第二阶段:GREEN (让测试通过的最简实现)

2.2.1. 目标

编写最简单的实现代码,让当前失败的测试通过。

2.2.2. 核心准则

  • 允许: Agent 可以创建、修改 src/main/ 目录下的代码

  • 要求:

    • 优先考虑最简单的实现方式

    • 专注于满足当前测试用例

    • 快速实现功能让测试通过

  • 禁止:

    • 不能修改测试代码

    • 不考虑代码质量和性能优化

    • 不进行过度设计

  • 验证: 运行测试必须显示绿色(通过状态)

2.2.3. 交互示例

  • Agent 回应: "已激活 GREEN 阶段。我将实现最简单的代码来让刚才的测试通过,不考虑优化和设计。"

2.3. 第三阶段:REFACTOR (重构优化)

2.3.1. 目标

在保持测试通过的前提下,改进代码的设计、质量和可维护性。

2.3.2. 核心准则

  • 允许: Agent 可以重构 src/main/ 目录下的实现代码

  • 要求:

    • 改进代码设计和质量

    • 消除重复代码

    • 提高代码可读性和可维护性

    • 每次重构后必须运行测试确保通过

  • 禁止:

    • 不能修改测试的行为和期望

    • 不能破坏现有功能

    • 验证: 重构过程中和完成后,所有测试必须保持绿色

2.3.3. 交互示例

  • Agent 回应: "已激活 REFACTOR 阶段。我将重构代码以提高质量,同时确保所有测试保持通过状态。"


3. TDD 最佳实践

3.1. 循环节奏

  • 小步快走: 每个 Red-Green-Refactor 循环应该很短(几分钟到十几分钟)

  • 频繁验证: 每个阶段完成后都要运行测试验证

  • 逐步推进: 一次只关注一个小功能点

3.2. 测试质量要求

  • 快速执行: 单元测试应该在秒级内完成

  • 独立性: 测试之间不应该有依赖关系

  • 可重复性: 测试结果应该是确定的和可重复的

  • 清晰命名: 测试方法名应明确表达测试意图

3.3. 代码质量保证

  • 持续重构: 在每个循环的 REFACTOR 阶段改进代码

  • 消除重复: 遵循 DRY(Don't Repeat Yourself)原则

  • 保持简洁: 代码应该简洁明了,易于理解

3.4. 流程控制

Agent 在每个阶段转换时,必须:

  1. 明确声明即将进入的阶段

  2. 说明当前阶段的具体目标

  3. 完成阶段后验证结果

  4. 确认是否继续下一个循环