tdd-migrate

TDD 迁移

使用 Agent 编排 TDD 迁移，由 Agent 完成所有工作。保持主上下文干净。

适用场景

• “将 X 从 Python 移植到 TypeScript”
• “按照现有模式创建 N 个适配器”
• “将模块迁移到新架构”
• “对多个相似项目进行 TDD 实现”

参数

/tdd-migrate <source_path> <target_path> --pattern <reference> --items "item1,item2,item3"

• source_path：要分析的路径（现有代码）
• target_path：新代码的创建位置
• pattern：要遵循的参考文件／模式
• items：要创建的项目，以逗号分隔

工作流

Phase 0: YAML TODO List
    │
    ▼
Phase 1: TLDR Analysis ─────────────────┐
    │                                    │
    ▼                                    │ Parallel scouts
Phase 2: Write Failing Tests ───────────┤ per item
    │                                    │
    ▼                                    │
Phase 3: Implement (minimal) ───────────┤
    │                                    │
    ▼                                    │
Phase 4: Build + Pass Tests ────────────┘
    │
    ▼
Phase 5: QLTY Check ────────────────────┐
    │                                    │ Parallel
Phase 6: Review Agent Validates ────────┘
    │
    ▼
Phase 7: TLDR Diff (new vs reference)
    │
    ▼
Phase 8: Fix Issues (if any)
    │
    ▼
Complete

核心原则

1. 主上下文 = 仅用于编排

   • 绝不直接读取文件（使用 scout）
   • 绝不直接实现（使用 kraken/spark）
   • 绝不直接运行测试（使用 validator）
   • 仅传递上下文并协调

2. 所有工作都由 Agent 完成

   任务	Agent
   探索／分析	scout
   编写测试 + 实现	kraken
   快速修复	spark
   运行测试／验证	validator
   代码审查	critic

3. 相互独立的工作尽可能并行

   • 如果各项目相互独立，可并行实现所有项目
   • 审查 + QLTY 并行运行
   • TLDR 分析与规划并行运行

4. 每个主要步骤后都进行审查

   • 实现后：由 critic 审查
   • 修复后：由 validator 重新验证

说明

步骤 0：创建 YAML TODO

将 YAML 计划文件写入 thoughts/shared/plans/<name>-tdd.yaml：

---
title: <Migration Name>
date: <today>
type: implementation-plan
approach: TDD (test → build → pass → review)

items:
  - name: item1
    file: <target_path>/item1.ts
    test: <target_path>/__tests__/item1.test.ts
    deps: []
  - name: item2
    # ...

reference: <pattern_file>

workflow:
  per_item:
    1: Write failing test
    2: Implement minimal
    3: Build
    4: Pass test
    5: QLTY check
    6: Review
  final:
    7: Integration test
    8: TLDR diff

步骤 1：并行启动 Scout Agent

Task (scout): Analyze <source_path> with TLDR
Task (scout): Analyze <pattern> to understand structure
Task (scout): Read migration handoff if exists

步骤 2：启动 Kraken Agent（每个项目并行）

对于每个项目，启动一个 kraken，完成完整的 TDD 流程：

Task (kraken): Implement <item> using TDD workflow
  1. Read pattern file
  2. Write failing test
  3. Implement
  4. Run: bun test <test_file>
  5. Run: qlty check <impl_file>

步骤 3：并行审查 + 验证

Task (critic): Review all new files against pattern
Task (validator): Run full test suite
Task (validator): QLTY check all files

步骤 4：修复问题

如果 critic/validator 发现问题：

Task (spark): Fix <specific issue>
Task (validator): Re-validate

步骤 5：TLDR 差异分析

Task (validator): TLDR diff new files vs reference
  - tldr structure <new_file> --lang <lang>
  - tldr structure <reference> --lang <lang>
  - Compare patterns

步骤 6：更新连续性记录

将已完成的工作更新到台账中。

示例：Rigg 适配器

/tdd-migrate /Users/cosimo/Documents/rigg/src/sdk/providers \
  /Users/cosimo/Documents/rigg/src/sdk/providers \
  --pattern lmstudio.ts \
  --items "xai,cerebras,togetherai,deepinfra,perplexity"

结果：

• 5 个并行运行的 kraken Agent
• 39 项测试通过
• 所有适配器均可正常工作
• 总耗时约 15 分钟

反模式（请避免）

不好的做法	好的做法
在主上下文中读取文件	启动 scout Agent
在主上下文中编写代码	启动 kraken/spark Agent
在主上下文中运行测试	启动 validator Agent
跳过审查	始终启动 critic
按顺序处理项目	并行启动 kraken
在主上下文中修复	启动 spark

Agent 提示词

Scout（分析）

Explore <path> to understand:
1. Structure/patterns
2. Interfaces/types
3. Dependencies
Return actionable summary for implementation.

Kraken（TDD）

Implement <item> using TDD:
1. Read <pattern> for structure
2. Write failing test to <test_path>
3. Implement minimal to <impl_path>
4. Run: <test_command>
5. Run: qlty check <impl_path>
Report: status, issues, files created.

Critic（审查）

Review <files> against <pattern>:
1. Pattern compliance
2. Type safety
3. Missing registrations
4. Security issues
DO NOT edit. Report issues only.

Spark（修复）

Fix <specific issue>:
1. Read <file>
2. Make minimal edit
3. Verify fix

Validator（测试）

Validate <files>:
1. Run <test_command>
2. Run qlty check
3. Report pass/fail/issues

成功标准

• 所有测试通过
• QLTY 未报告任何问题
• Critic 未发现严重问题
• TLDR 差异分析显示符合模式
• 所有项目均已正确注册／导出