tdd

TDD Persona

在执行此流程前，先应用执行契约。

Agent 阶段

阶段 1：上下文与测试设计

1. load-context：加载 schema、路由和模式。
2. plan-tests：选择最合适的首个失败 spec。
3. write-tests：编写测试并验证失败。

硬性门禁 — tdd-process （来自 ruby-core-skills）

• 测试已存在且已运行。
• 因正确原因失败（例如 undefined method 'full_name'）。
• 如果失败原因不正确（语法、配置），返回 write-tests。

阶段 2：实现

1. 提案检查点：提出实现方案（例如“拼接名字 + 姓氏”）。
2. 范围检查：在现有授权范围内继续。
3. 最小实现：通过测试所需的最小改动。
4. 验证通过：bundle exec rspec spec/path/to/spec.rb。

如果测试未通过，进行最小修复并重新验证。

阶段 3：迭代（可选）

返回阶段 1 处理下一个行为，或继续阶段 4。

阶段 4：完成

1. 质量检查：bundle exec rubocop && bundle exec brakeman && bundle exec rspec。
2. write-yard-docs （来自 ruby-core-skills）：为公开 Ruby API 编写文档。
3. code-review：自查 PR diff。
4. 提交 PR：功能完成。

具体示例

以向 User 模型添加 full_name 方法为例的简要演练。完整的端到端示例见 assets/example.md。

步骤 1 — 编写失败的 spec（spec/models/user_spec.rb）：

RSpec.describe User, type: :model do
  describe '#full_name' do
    it 'returns first and last name joined by a space' do
      user = User.new(first_name: 'Jane', last_name: 'Doe')
      expect(user.full_name).to eq('Jane Doe')
    end
  end
end

运行：bundle exec rspec spec/models/user_spec.rb 预期失败：NoMethodError: undefined method 'full_name' for #<User ...> ✅

步骤 2 — 说明方案

提案：向 app/models/user.rb 添加 def full_name = "#{first_name} #{last_name}"。

步骤 3 — 最小实现（app/models/user.rb）：

def full_name
  "#{first_name} #{last_name}"
end

运行：bundle exec rspec spec/models/user_spec.rb → 1 example, 0 failures ✅

步骤 4 — 质量检查：

bundle exec rubocop && bundle exec brakeman && bundle exec rspec

全部通过 → 编写 YARD 文档 → 自查 → 提交 PR。

---

输出风格

完成一个 TDD 周期后，按照 assets/tdd-report-template.md 中的模板生成报告。报告至少必须包括：

• RED：spec 文件路径和行号、确切的失败类和消息、确认失败原因正确。
• Proposal：一行实现摘要和授权范围。
• GREEN：实现文件路径和行范围、spec 通过确认。
• Iterate：额外的 RED→GREEN 周期数量及每个周期的摘要。
• Quality Gate：RuboCop、Brakeman、完整 RSpec 套件、YARD 文档和自查结果。

---

集成

前驱	本 Persona	后继
load-context	tdd	code-review
define-domain-language	tdd	quality
无（独立）	tdd	PR submission

单独使用 plan-tests：如果你只需要决定下一个写哪个测试。

单独使用 write-tests：如果测试设计已确定，你只需要实现 spec。

---

错误恢复

测试因错误原因失败（语法/配置错误）：

1. 识别错误类 — SyntaxError、NameError、LoadError 表示测试问题，而不是缺少功能。
2. 修复测试以正确针对缺失行为，并重新运行，直到失败类正确（例如 NoMethodError）。

实现使测试通过但破坏了其他测试：

1. 运行 bundle exec rspec 以识别回归。
2. 修改实现，使其同时满足新测试和现有测试。
3. 如果无法做到，该功能与现有行为冲突 — 在继续前与用户讨论。

质量门禁失败（RuboCop/Brakeman）：

1. 运行 bundle exec rubocop -a 处理可自动修正的违规；手动修复剩余的违规。
2. 对于 Brakeman 警告，评估它们是否为误报 — 如果属实，在继续前修复。