Ledger build

Ledger Build — TDD 实现 + 架构检查

Overview

根据行为契约，用 TDD 方式逐组件实现功能。每个 FC 条目必须经过完整的 RED-GREEN-REFACTOR 周期。

Core principle: 测试失败前不能写实现代码。先写代码后补测试 → 删掉重来。

Entry Gate

进入 build 前必须运行：

bash .ledger/bin/ledger.sh guard build

guard 失败则停止。不继续。

.ledger/contracts/[功能名].md 必须存在且通过 lint。

Step 0: 复杂度评估

读取 contract，按 constitution.md §12a 快速判定 + §12b 复杂度评分计算功能复杂度。

输出复杂度评估结果，然后继续。

---

Step 1: 生成组件计划

输出以下格式：

## 组件计划 — [功能名]

### 复杂度评分
| 维度 | 评分 | 说明 |
|------|------|------|
| FC 边界情况 | [N] | [说明] |
| 外部依赖 | [N] | [说明] |
| 状态转换 | [N] | [说明] |
| 跨模块影响 | [N] | [说明] |
| **总分** | **[N]** | [可一次 build / 需 exec plan / 需拆分] |

### 文件清单
| 文件路径 | 操作 | 说明 |
|---------|------|------|
| src/[路径] | 新建/修改 | [操作范围] |

### 接口变更（如有 API 变更）
[路径、方法、请求/响应格式]

### 架构主干影响
| 模块 | 责任 | 本次是否修改 | 是否符合边界 |
|------|------|--------------|--------------|
| [模块] | [责任] | 是/否 | 是/否/需确认 |

### 设计附件引用
| 附件 | 影响 |
|------|------|
| .ledger/design/[feature]-sequence.md | 调用顺序 / 状态变化 |
| .ledger/design/[feature]-interaction.md | UI 状态 / 表单反馈 |

### 实现顺序
1. 数据层（Model / Schema / Migration）
2. 业务逻辑层（Service / Handler）
3. 表现层（Router / Controller / Component）

### FC-TDD 映射
| FC | 测试文件 | 测试用例 | 实现文件 |
|----|----------|----------|----------|
| FC-01 | test/[path] | [test name] | src/[path] |
| FC-02 | test/[path] | [test name] | src/[path] |

### 不确定项
[需要人工确认的设计决策，无则写"无"]

⏸️ 强制暂停：展示组件计划，等待人工确认后才进入 Step 2。

---

Step 2: 逐 FC TDD 实现

按组件计划的实现顺序，逐个 FC 条目执行完整的 TDD 周期。

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

RED — 写失败测试

为当前 FC 写一个最小测试，展示预期行为。

Requirements:

• 测试名描述行为（不是 "test1"）
• 一个测试验证一件事（名字里有 "and"？拆开）
• 用真实代码，不用 mock（除非不可避免）
• 清晰展示预期 API

必须运行测试，看到失败：

[constitution.md §3 测试命令] [测试文件]

确认：

• 测试失败（不是报错）
• 失败信息符合预期
• 因为功能缺失而失败（不是拼写错误）

测试通过？说明你在测试已有行为，修改测试。

GREEN — 写最小代码

写最简单的代码让测试通过。

不要：

• 添加超出 FC 范围的功能
• 重构其他代码
• "改进"超出测试要求

必须运行测试，看到通过：

[constitution.md §3 测试命令] [测试文件]

确认：

• 测试通过
• 其他测试仍然通过
• 输出干净（无错误、无警告）

测试失败？修代码，不是改测试。其他测试也失败？现在就修。

REFACTOR — 清理

绿色状态下才能重构：

• 去除重复
• 改善命名
• 提取辅助函数

保持测试绿色。不添加新行为。

下一个测试

为同一个 FC 的下一个边界情况写失败测试。重复 RED-GREEN-REFACTOR。

FC 的所有测试通过后，进入下一个 FC。

TDD 违规处理

写代码前没写测试？ 删掉代码。从 RED 开始。

先写代码后补测试？ 删掉代码和测试。从 RED 开始。

测试立即通过？ 你在测试已有行为。修改测试使其失败。

不要保留"参考代码"。不要"适配"已有代码。删除意味着删除。

---

Step 3: 逐组件即时检查

每个组件的所有 FC 实现完成后，立即执行六项检查。

检查 1 — 技术约束合规（对照 constitution.md）

• 删除操作是否遵守删除策略
• API 响应是否使用统一格式
• 命名是否符合规范
• 是否引入了未登记的第三方库

检查 2 — 实体定义一致（对照 PAD.md）

• 字段名是否与 PAD.md 定义一致
• 状态值是否与 PAD.md 状态机一致
• 状态变化是否符合 PAD 核心业务主流程
• 成功后用户去向是否符合 PAD 体验一致性规则

检查 3 — 架构主干一致（对照 architecture.md）

• 实现是否落在 PID / 组件计划声明的模块中
• 实体写入是否由 architecture.md 中的 owner 模块负责
• 状态机变更是否在声明的 owner 模块中完成
• 权限判断是否位于 architecture.md 声明的位置
• 依赖方向是否违反 architecture.md
• 命中 ADR 触发条件时，是否记录或计划记录 ADR

检查 4 — 契约覆盖确认（对照 contracts/[功能名].md）

• 该组件负责的 FC/NF 条目是否已实现
• 该组件是否越出 PID Card "明确不做"清单

检查 5 — 设计附件一致（若 PID 声明附件）

• 是否符合 sequence 中的关键调用顺序和状态变化
• 是否符合 interaction 中的 UI 状态和反馈规则
• 是否符合 design brief 中的方案边界

检查 6 — 运行时边界扫描

• 并发写入模式（先读后写、计数器）
• 多表操作但无事务保护
• 外部调用但无失败处理
• N+1 查询风险

检查 6 发现高风险特征时：触发边界警告，暂停等待决策。

发现技术债时：

📋 技术债：[描述妥协内容] | 触发条件：[描述]
登记到 tech-debt.md？[A]是 [B]否

检查通过：输出单行确认，继续下一个组件。 发现问题：描述问题 + 对应规则 + 建议修正，等待处理后继续。

---

Step 4: 跨功能一致性扫描

所有组件完成后执行一次：

• 实体字段名在不同功能间是否一致
• 相同类型操作（删除/列表/错误提示）行为是否统一
• FDG 中定义的共享契约是否被遵守
• 当前功能的实现是否触碰了其他已完成功能的"明确不做"边界

输出：

✅ 一致性扫描通过 / ⚠️ 发现 N 个问题：[列表]

---

Step 5: 更新 state.md

bash .ledger/bin/ledger.sh state set-phase build-complete

---

Session 中断处理

功能较大、当前会话无法完成所有 FC 时，在完成当前 FC 并通过 TDD 周期后记录断点：

功能：[名称] | 阶段：build
已完成 FC：[列出]
下次继续：实现 FC-[N]

下次会话加载 ledger-build skill 时，读取 state.md 从断点继续。

---

完成输出

✅ build 完成：[功能名]
  复杂度评分：[N] 分
  实现组件：[N] 个
  FC 条目：[N] 个（每个经过 RED-GREEN-REFACTOR）
  检查：全部通过 / 发现并修复 [N] 个问题
  技术债：[N] 条已登记 / 无
  一致性：通过 / 已修复 [N] 个问题
→ 下一步：/ledger.verify 或加载 ledger:ledger-verify skill

---

Red Flags

Thought	Reality
"这个 FC 太简单不需要测试"	简单代码也会坏。测试 30 秒。
"我先写代码再补测试"	删掉代码，从 RED 开始。
"测试通过了所以没问题"	测试立即通过 = 你在测试已有行为。
"mock 一下更快"	mock 测的是 mock 行为，不是真实代码。
"重构一下不影响功能"	没有绿色保护的重构就是在赌博。
"这个 FC 可以跳过 TDD"	不可以。没有例外。
"我已经手动测过了"	手动测试 ≠ 系统化测试。没有记录，无法重跑。
"先探索一下再写测试"	可以。但探索完扔掉，从 TDD 开始。