/taiyi-dev

name: taiyi-dev
description: TaiyiForge 第6阶段 — TDD开发执行。四端通用。
paradigm: Operator

taiyi-dev — TDD 开发

> 进入本阶段前请优先读 `.taiyi/changes/<slug>/PHASE-CONTEXT.md`（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

| 框架 | 用途 | 何时加载 | |------|------|---------| | **Harness** | 阶段门禁与推进（`apply` 清单 · `status` → `continue`；legacy：`npx taiyi apply/complete`） | 全程 | | **Superpowers** | `test-driven-development` — TDD 红→绿→重构循环 | 步骤 1（强制） | | **Superpowers** | `systematic-debugging` — 测试失败时诊断 | 异常处理时 | | **Superpowers** | `verification-before-completion` — 完成前验证 | 完成前 |

**GStack / OpenSpec / Spec-Kit / OMO** 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游确认

• task 阶段已过关（`engineTruth` 确认）
• TASK.md 中无未解决的 `[depends_on: ?]`
• 当前 git 分支干净（无未提交的临时修改）

0.2 Profile 判定

| Profile | 开发要求 | |---------|---------| | `full` | 全 TDD（红→绿→重构）+ 全部 0.x 检查 + self-review(R1-R11) | | `api/ui` | 同 full | | `lite` | TDD 可选，0.x 检查中的 0.5（破坏性变更）必须执行 | | `micro/spike` | 仅 0.1（grep 已有抽象）+ 0.5（破坏性变更） | | `nano` | TDD 可选，0.5 必须执行 |

0.3 前置检查清单

• [ ] task 阶段已过关
• [ ] todo 列表已就绪（每个 T0X 一个 todo 项）
• [ ] 理解 TASK.md 的 verify 标准和 write_files 边界

---

步骤

**dev 无 json 视图**：过关证据为 `.dev-complete`（`command` + `exitCode: 0`）。实现边界仍来自 `task.json` / 渲染后的 `TASK.md`。

0. 上下文加载

先读 PHASE-CONTEXT.md 确认范围，再读 TASK.md 拿到任务清单。**不写不在 TASK 中的功能。**

0.1 沿用已有抽象 grep（强制）

写新代码前 grep 同类模式，贴入 SUMMARY：

# grep -rn "class.*Adapter" src/  → 找到 LLMAdapter 抽象基类
# grep -rn "from.*middleware" src/ → 找到 LoggingMiddleware 模式

**不 grep 直接写 = 制造重复抽象**。

0.2 扫 LESSONS（强制）

grep -rn "LESSON" .taiyi/changes/<slug>/ 2>/dev/null || echo "无 LESSONS"

对 active 条目声明差异。相同方案已记录失败教训 → **停手，选不同方案**。

0.3 UI 任务额外检查

确认 UI-DESIGN.md 存在。颜色/字体/间距从 UI-DESIGN.md 派生。**禁硬编码 hex**。

0.4 Schema 变更检查

生成可逆迁移（up + down）。grep 确认数据库当前结构，避免迁移冲突。

0.5 破坏性变更高门槛

命中任一 → **STOP，展示引用分析结果，等用户明确指示**：

• 删除 ≥ 5 行代码
• 修改公共导出（export function / export class）
• 改 API 端点签名（path / method / request body）
• 改 DB Schema 列名或类型

---

1. TDD 红→绿→重构（强制）

<tdd_enforcement> STEP A — WRITE FAILING TEST ONLY

• Write the test that defines the expected behavior. Do NOT touch business logic yet.
• The test MUST be a real assertion (not console.log, not TODO).

STEP B — CAPTURE RED EVIDENCE（MANDATORY）

• Run the test script. Capture the RED (failing) terminal output.
• PASTE the failing output into .dev-complete as evidence under "RED: <test-id>".
• DO NOT proceed to step C without RED evidence.

STEP C — IMPLEMENT GREEN

• Write the minimum production code to make the test pass.
• Re-run the exact same test. Capture GREEN (passing) output.
• Paste GREEN output into .dev-complete alongside the RED evidence.

STEP D — REFACTOR

• Optional cleanup. Tests MUST stay green.

<three_case_rule> 最低测试覆盖 (强制) — 每个新函数必须 ≥ 3 个 test case: 1. happy case — 正常输入返回预期输出 2. edge case — 边界输入 (空/null/0/最大值/Unicode/...) 3. error case — 异常输入 (类型错/null/无效格式) 走 error 处理分支

禁止单 case 提交. 三个 case 缺一即视为覆盖不足.

反模式 (禁止):

• 只测 happy path 不测边界
• console.log / TODO 代替断言
• 把 3 个 case 写成"复用同一断言"的循环 (虽然技术正确但语义模糊)

</three_case_rule> </tdd_enforcement>

**TDD 违规处理**：Agent 跳过 RED 证据直接写实现 → 删除实现代码，回退到 A 步。

2. 提交前 diff 边界 verify

git diff --stat

与 TASK.md 各任务 `write_files` 逐条比对：

• ⚠️ 增改文件超出 write_files → **STOP**，记录范围蔓延
• ⚠️ 修改了禁动清单中的文件 → **STOP**，回退修改

3. Self-review（R1-R11）

每条诊断格式：`Symptom → Source → Consequence → Remedy + 文件:行号`

| 维度 | 检查项 | 命中条件 | |------|--------|---------| | **R1 函数过载** | 函数/方法 > 40 行 | 超过拆分为 2+ 函数 | | **R2 文件膨胀** | **单个源文件 > 1000 行**（不含测试和配置文件） | 拆为多个模块 | | **R3 变更传播** | 修改公共接口导致 3+ 文件连锁改动 | **STOP**，重新设计接口 | | **R4 知识重复** | 3+ 处实现同一逻辑 | 提取为共享函数 | | **R5 偶然复杂** | 不必要的配置/抽象/泛型 | 简化或删除 | | **R6 依赖混乱** | A 层直接引用 B 层内部类型 | 用接口解耦 | | **R7 领域扭曲** | 代码命名与 REQUIREMENT 域语言不一致 | 统一术语 | | **R8 嵌套过深** | 条件/循环嵌套 > 4 层 | 提前 return / 提取函数 / 策略模式 | | **R9 循环依赖** | 模块 A↔B 互相 import | 提取共享接口到独立文件 | | **R10 沉默错误** | 空 catch、await 无 try、Promise 不 catch | 补错误处理（至少 log） | | **R11 魔术值** | 硬编码字符串/数字（非配置/常量） | 提取为命名常量或 config key |

4. SUMMARY + .dev-complete

写入 `.taiyi/changes/<slug>/.dev-complete`：

# .dev-complete

## TDD 证据
### T01: validateEmail
RED:
$ npx vitest run tests/unit/validation.test.ts
# 粘贴 red 输出
GREEN:
$ npx vitest run tests/unit/validation.test.ts
# 粘贴 green 输出

## 0.x 检查
- [x] 0.1 grep 已执行：找到 Adapter 模式
- [x] 0.2 LESSONS 已扫描：无冲突
- [x] 0.5 破坏性变更：否

## Self-review
- R1 函数过载: ✅
- R2 文件膨胀: ✅ (180 行)
- R3 变更传播: ⚠️ 修改了公共接口 → 重新设计
- ...

## 偏差
预估：T01(30min) + T02(2h) = 2.5h
实际：T01(20min) + T02(3h) = 3.2h
偏差：+28% — T02 因方案调整超时

---

过关（Harness）

1. 逐项检查 `## 质量自检`；有未通过项则不要过关。 2. 可选清单：`scripts/taiyi-forge.sh apply <slug> dev`（只输出实现清单，**不过关**）。 3. 预检：`scripts/taiyi-forge.sh status <slug> --json --compact` — 解析 `engineTruth`（`qualityReady` / `blockers`）。 4. 用户确认后过关：`scripts/taiyi-forge.sh continue <slug>`。 5. 过关后再 `status --json --compact`，读 `engineTruth`；若 `currentPhase` 已变为 `test`，切换到 taiyi-test Skill 并通知用户。

Legacy：`npx taiyi apply <slug> dev` 或 `npx taiyi complete <slug> dev` 仍可用；聊天优先 `/taiyi:apply` · `/taiyi:continue`。

产出

• `.taiyi/changes/<slug>/TASK.md`（参考）
• 实现代码（在项目中）
• `.taiyi/changes/<slug>/.dev-complete`

与下游衔接

| 下游 | 需要 | |------|------| | `taiyi-test` | 实现代码 → 测试目标；TASK verify 标准 → 测试预期；.dev-complete → 偏差追踪 | | `taiyi-review` | 实现代码 → 审查对象；diff → 范围蔓延检测基线 |

异常处理

| 场景 | 处理 | |------|------| | 测试失败 | DIAGNOSE（读失败输出 + stack trace）→ 写 FIX 计划 → 最小改动修复 → 重跑所有测试。**最多 3 轮**，超限停手上报用户 | | compile/lint 错误 | 读错误输出的文件行号 → 逐条修复。**不要**整文件重写或 rewrite from scratch | | 门禁不通过 | 读 `engineTruth` 确认当前阶段。若是前阶段工件未满足 → 展示缺什么文档，让用户决定回退 | | 任何破坏性变更（0.5 协议命中） | STOP，展示引用分析结果，等用户明确指示 | | TDD 阶段发现 TASK 任务拆分不合理 | 在 .dev-complete 中记录偏差，**不要**中途改 TASK.md。等 review 阶段处理 | | 多个任务共享同一个文件 | 标记为"写冲突"，**只能串行执行**。先完成的任务提交后，后一个任务 rebase | | 非零 exit code | 最多 1 次自动重试，第二次必须等用户指令 | | 误过关本阶段或后续 | `scripts/taiyi-forge.sh undo <slug> dev` |

<fatal_constraints>

• NEVER mark complete without verification passing.
• NEVER skip 0.5 protocol for breaking changes.
• NEVER