Back to Details

tdd-migration-pipeline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TDD Migration Pipeline

TDD迁移流水线

Orchestrator-only workflow for migrating or rewriting codebases. You do NOT read files, write code, or validate anything yourself. You only instruct agents and pipe context (paths, not contents).
仅由编排器主导的工作流，用于迁移或重写代码库。你无需自行读取文件、编写代码或进行任何验证工作，只需指导Agent并传递上下文（仅传递路径，而非内容）。

When to Use

适用场景

  • Migrating codebase from one language/framework to another
  • Rewriting a system with TDD guarantees
  • Large-scale refactoring with behavioral contracts
  • When you want zero context growth in the orchestrator
  • 将代码库从一种语言/框架迁移至另一种
  • 以TDD为保障重写系统
  • 基于行为契约的大规模代码重构
  • 希望编排器上下文不膨胀的场景

Core Principles

核心原则

  1. ZERO orchestrator execution - only instruct and pipe context
  2. All work done by agents - you never read/write/validate
  3. Context window stays flat - pass paths, not contents
  4. New code in separate directory - never modify source
  1. 编排器零执行 - 仅进行指导和上下文传递
  2. 所有工作由Agent完成 - 你永远不要自行读取/编写/验证内容
  3. 上下文窗口保持扁平 - 仅传递路径，而非内容
  4. 新代码存于独立目录 - 绝不修改源文件

Your Constraints

约束条件

  • Never say "let me read..." or "looking at..."
  • Only say "Agent X: do Y with Z"
  • Your context should NOT grow during execution
  • All agents must use 
    qlty
    and 
    tldr
    skills
  • 永远不要说“让我读取...”或“查看...”
  • 仅使用“Agent X：执行Y操作，使用Z”的表述
  • 执行过程中你的上下文不得膨胀
  • 所有Agent必须使用
    qlty
    和
    tldr
    技能

Pipeline Phases

流水线阶段

Phase 1: SPEC

阶段1：SPEC

Instruct spec-agent (use scout or architect):
- Analyze {source_path} using tldr-skill
- Output: spec.md with behavioral contracts, types, edge cases
Agent prompt template:
Analyze the codebase at {source_path} using tldr commands (tldr structure, tldr extract, tldr calls).
Create spec.md with:
- All behavioral contracts (what each function/class promises)
- Input/output types
- Edge cases and invariants
- Dependencies between components
Write to: {target_dir}/spec.md
指导spec-agent（使用scout或architect）：
- 使用tldr-skill分析{source_path}
- 输出：包含行为契约、类型、边缘情况的spec.md
Agent提示模板：
使用tldr命令（tldr structure、tldr extract、tldr calls）分析{source_path}下的代码库。
创建spec.md，包含：
- 所有行为契约（每个函数/类的承诺）
- 输入/输出类型
- 边缘情况与不变量
- 组件间的依赖关系
写入至：{target_dir}/spec.md

Phase 2: FAILING TESTS

阶段2：失败测试

Instruct test-agent (use arbiter):
- Read spec.md
- Write failing tests in {target_dir}/tests/
- Tests should define expected behavior before implementation

Instruct review-agent (use critic):
- Validate tests cover spec completely
- No gaps in behavioral coverage
指导test-agent（使用arbiter）：
- 读取spec.md
- 在{target_dir}/tests/中编写失败测试
- 测试需在实现前定义预期行为

指导review-agent（使用critic）：
- 验证测试是否完全覆盖spec内容
- 确保行为覆盖无遗漏

Phase 3: ADVERSARIAL (x3 iterations)

阶段3：对抗性测试（迭代3次）

Instruct premortem-agent (use premortem skill):
- Review spec + tests
- Identify failure modes, race conditions, edge cases
- DO NOT ASK - just add mitigations directly to spec
- Run 3 passes with fresh perspective each time
Key: Each pass should find NEW issues, not repeat previous ones.
指导premortem-agent（使用premortem技能）：
- 审核spec + 测试
- 识别故障模式、竞争条件、边缘情况
- 无需询问，直接将缓解措施添加至spec
- 以全新视角运行3轮审核
关键： 每一轮都应发现新问题，而非重复之前的内容。

Phase 4: PHASED PLAN

阶段4：分阶段计划

Instruct planner-agent (use architect or plan-agent):
- Input: spec.md + tests + mitigations
- Output: phased-plan.yaml
- Requirements:
  - Dependency-ordered phases
  - Each phase = one testable unit
  - Clear inputs/outputs per phase
指导planner-agent（使用architect或plan-agent）：
- 输入：spec.md + 测试 + 缓解措施
- 输出：phased-plan.yaml
- 要求：
  - 按依赖关系排序的阶段
  - 每个阶段对应一个可测试单元
  - 每个阶段有明确的输入/输出

Phase 5: BUILD LOOP (per phase)

阶段5：构建循环（按阶段执行）

For each phase in phased-plan.yaml:

  Instruct builder-agent (use kraken or spark):
  - Write code to pass tests for this phase
  - Use qlty for quality checks
  - Run tests after each change

  Instruct review-agent (use critic or judge):
  - Validate implementation matches spec
  - Check for regressions in previous phases
  - Verify no breaking changes
针对phased-plan.yaml中的每个阶段：

  指导builder-agent（使用kraken或spark）：
  - 编写代码以通过该阶段的测试
  - 使用qlty进行质量检查
  - 每次变更后运行测试

  指导review-agent（使用critic或judge）：
  - 验证实现是否符合spec
  - 检查之前阶段是否出现回归
  - 确认无破坏性变更

Phase 6: INTEGRATION VALIDATION

阶段6：集成验证

Instruct integration-agent (use atlas or validator):
- Use tldr to diff against {reference_repo}
- Check for:
  - No race conditions
  - No hangs or deadlocks
  - No breaking changes vs original
  - All behavioral contracts preserved
- Output: validation-report.md
指导integration-agent（使用atlas或validator）：
- 使用tldr与{reference_repo}进行差异对比
- 检查内容：
  - 无竞争条件
  - 无挂起或死锁
  - 与原代码相比无破坏性变更
  - 所有行为契约均得到保留
- 输出：validation-report.md

Invocation

调用方式

When invoking this workflow, specify:
yaml
SOURCE: {path to source code}
TARGET_DIR: {new folder for migrated code}
TARGET_LANG: {typescript|python|go|rust|etc}
REFERENCE_REPO: {url or path for final diff comparison}
SKILLS: [tldr-code, qlty-check, {domain-specific}]
调用此工作流时，需指定：
yaml
SOURCE: {源代码路径}
TARGET_DIR: {迁移代码的新文件夹}
TARGET_LANG: {typescript|python|go|rust|etc}
REFERENCE_REPO: {用于最终差异对比的URL或路径}
SKILLS: [tldr-code, qlty-check, {领域特定技能}]

Agent Mapping

Agent映射

PhaseAgent TypeSubagent
Specresearch
scout
or 
architect
Testsvalidate
arbiter
Reviewreview
critic
or 
judge
Premortemreview
premortem
skill
Planplan
architect
or 
plan-agent
Buildimplement
kraken
(large) or 
spark
(small)
Integrationvalidate
atlas
or 
validator
阶段Agent类型子Agent
Spec研究
scout
或
architect
Tests验证
arbiter
Review审核
critic
或
judge
Premortem审核
premortem
技能
Plan规划
architect
或
plan-agent
Build实现
kraken
（大型项目）或
spark
（小型项目）
Integration验证
atlas
或
validator

Example Orchestration

编排示例

undefined
undefined

Phase 1

阶段1

Task(scout): "Analyze /src/old-system using tldr structure and tldr extract. Create spec.md at /migration/spec.md with all behavioral contracts."
Task(scout): "分析 /src/old-system，使用tldr structure和tldr extract。 在/migration/spec.md创建包含所有行为契约的spec.md。"

Phase 2

阶段2

Task(arbiter): "Read /migration/spec.md. Write failing tests to /migration/tests/ that define expected behavior."
Task(critic): "Review /migration/spec.md vs /migration/tests/. Report any behavioral gaps."
Task(arbiter): "读取/migration/spec.md。在/migration/tests/中编写失败测试， 定义预期行为。"
Task(critic): "审核/migration/spec.md与/migration/tests/。 报告任何行为覆盖缺口。"

Phase 3 (x3)

阶段3（3轮）

Task(premortem): "Review /migration/spec.md and /migration/tests/. Identify failure modes. Add mitigations directly to spec. Pass 1/3." [repeat with "Pass 2/3", "Pass 3/3"]
Task(premortem): "审核/migration/spec.md和/migration/tests/。 识别故障模式。直接将缓解措施添加至spec。第1轮/共3轮。" [重复执行，分别标注"第2轮/共3轮"、"第3轮/共3轮"]

Phase 4

阶段4

Task(architect): "From /migration/spec.md and /migration/tests/, create /migration/phased-plan.yaml with dependency-ordered phases."
Task(architect): "基于/migration/spec.md和/migration/tests/， 创建/migration/phased-plan.yaml，包含按依赖关系排序的阶段。"

Phase 5 (loop)

阶段5（循环）

Task(kraken): "Implement phase 1 from /migration/phased-plan.yaml. Code goes in /migration/src/. Run tests after."
Task(critic): "Review /migration/src/ against /migration/spec.md. Check for spec compliance and regressions." [repeat for each phase]
Task(kraken): "实现/migration/phased-plan.yaml中的阶段1。 代码存入/migration/src/。每次变更后运行测试。"
Task(critic): "审核/migration/src/是否符合/migration/spec.md。 检查是否符合spec要求及是否出现回归。" [针对每个阶段重复执行]

Phase 6

阶段6

Task(atlas): "Run full integration tests on /migration/src/. Use tldr to diff against /src/old-system. Output /migration/validation-report.md."
undefined
Task(atlas): "对/migration/src/运行完整集成测试。 使用tldr与/src/old-system进行差异对比。 输出/migration/validation-report.md。"
undefined

Anti-Patterns (DO NOT)

反模式（禁止操作）

  • Reading files into your context ("let me check the code...")
  • Writing code directly ("I'll implement this function...")
  • Validating anything yourself ("looking at the tests, I see...")
  • Modifying the source directory
  • Skipping the adversarial phase
  • Running build without tests first
  • 将文件内容读取到你的上下文中（如“让我查看代码...”）
  • 直接编写代码（如“我将实现这个函数...”）
  • 自行验证任何内容（如“查看测试后，我发现...”）
  • 修改源目录
  • 跳过对抗性测试阶段
  • 未先编写测试就开始构建

Success Criteria

成功标准

  • All tests pass
  • qlty reports clean
  • tldr diff shows no breaking changes
  • No race conditions or hangs
  • validation-report.md confirms behavioral equivalence
  • 所有测试通过
  • qlty报告无问题
  • tldr差异对比显示无破坏性变更
  • 无竞争条件或挂起
  • validation-report.md确认行为等价性