Spec coding

---

正确的 Spec Coding 方法论

一、个人角色

作为个人开发者 + AI Agent 协作时，Spec Coding 的核心目标是：让 AI 一次做对，减少来回纠偏。
- 1. Spec（设计文档）的写法
必须回答 4 个问题，缺一不可：

段落	要回答的问题	反例
背景/现状	现在是什么样的？哪里痛？	一上来就写方案，没交代上下文
根因	为什么痛？不是表象、是根因	"提现拉取慢" vs "双层循环 × 200 币种 = 800 次串行 HTTP，大部分返回 null"
方案	怎么解决？有没有更简单的路子？	只写"加个接口"，不讲为什么是加接口而不是改循环
不做（YAGNI）	明确不做什么，划清边界	不写边界 → AI 自作主张多改了三张表

实际范例（优秀）：

问题

pullFinanceAuditedWithdrawsIntoGateway 每次 300 秒

根因

双层嵌套循环遍历所有币种 (N) × 两种 wallet_type (2)，产生 4N 次 HTTP 调用。
大部分返回 null，因为：

1. 内层 wallet_type 循环是冗余的
2. 大多数时候绝大部分币种没有待处理的已审核提现
3. is_open 过滤条件有误

方案

1. Finance 新增接口 — 获取已审核提现币种列表
2. Gateway 重构 — 先查有数据的币种，再只对这些币种拉取

不做

• 不动原有的 /co_transfer 和 /increment_transfer 端点
• 不引入新的消息队列

- 2. plan（执行计划）的写法

原则：不给 AI 留任何"自己判断"的空间。 每一条指令都应该是机械可执行的。

关键要素：

约束声明（放在最前面）

• 技术栈：Java 8 / Spring Boot 2.2.6 / MyBatis-Plus / JUnit 5 / Mockito 3.1.0
• 硬约束：不改 ContractAct、不改 BillingService 接口、0 张新表、0 个 DDL
• 日志：SLF4J + 业务 ID，不打敏感信息

文件地图

操作	文件路径	职责
新增	xxx.java	...
修改	yyy.java	...（明确标注"只加方法，不改已有逻辑"）

Task 1: [一句话目标]

• Step 1: 在 XxxMapper.java 新增方法声明
  （贴完整代码块）
• Step 2: 在 XxxMapper.xml 新增 SQL
  （贴完整 XML）
• Step 3: 提交
  git add ... && git commit -m "feat(模块): 中文描述"

Task 2: ...

核心纪律：

• Step 粒度 = 一次可验证的小改动（一个方法、一条 SQL、一个 commit）
• 每步给出完整代码，不要让 AI 推断——推断是 bug 的来源
• 每步给出 commit message，保持提交规范一致
• 文件地图前置，让 AI 在执行前就知道整条改动链路
• 硬约束用否定句写："不改 X"比"注意 X"有效 10 倍

- 3. Spec → Plan 的流转

你的脑子------------------Spec-------------------Plan-----------AI Agent
─────── ──────── ──────── ──────── ──────── ────────
想清楚-----------------→写成设计文档-------→拆成可执行步骤------→逐条执行+提交
"做什么+为什么" "怎么做+按什么顺序"

⚠️ 不要跳过 Spec 直接写 Plan。unified-transfer 的 Plan 虽然自己充当了半个 Spec（开头有路由表），但缺少独立设计文档的后果是：后面的人不知道为什么选了 Option B 而不是 Option A，决策上下文丢失。

---

二、团队角色

团队视角下，Spec Coding 的目标变成：让多个人 + 多个 Ag

1. 建立约定文档（缺失 → 必须补）

docs/superpowers/ 当前最大问题是没有 README。团队需要一份 README.md 至少覆盖：

Superpowers 工作流约定

何时写 Spec

• 涉及 ≥3 个文件改动的需求 → 必须先写 Spec
• 涉及新接口 / 新表 / 新模块 → 必须先写 Spec
• 纯 Bug 修复（改动 <20 行） → 可跳过 Spec，直接写 Plan

何时写 Plan

• 所有 Spec 必须有对应 Plan（除非需求取消）
• Plan 最早在 Spec 评审通过后编写

命名规则

• Spec: YYYY-MM-DD-<功能名>-design.md
• Plan: YYYY-MM-DD-<功能名>.md

状态标记

在文件名或文件头部标注：

• [Draft] / [Reviewing] / [Approved] / [Implementing] / [Done]

2. Spec 的评审清单（团队 CR 用）
   评审 Spec 时，逐条打勾：

• 根因写清楚了吗？ — 不是"XX 慢"，是"为什么慢"
• 方案是最简的吗？ — "能不能少改一个文件？能不能不加表？"
• YAGNI 边界划了吗？ — 明确写了"本次不做"的清单
• DB 变更标了吗？ — DDL 贴完整 SQL，标注是否需要手动执行
• 依赖/风险列了吗？ — 改了公共类会影响哪些下游模块？
• 和现有设计一致吗？ — 枚举放 common 还是模块内？返回格式跟现有接口对齐了吗？

3. Plan 的评审清单

• 硬约束在前吗？ — 不改的文件/类/接口明确列出
• 文件地图完整吗？ — 新增/修改一目了然，没有遗漏
• Step 可独立验证吗？ — 每步做完能编译 / 能跑单测
• 异常路径覆盖了吗？ — 接口挂了怎么办、参数非法怎么办
• 单测写了吗？ — Plan 里有测试文件的step

4. 团队协作中的配对规则
   | 情况 | 正确做法 | 当前反例 |
   | ------------------------|---------------------------------------- |------------------------------------------ |
   | 写了 Spec 但没写 Plan | 标记 Spec 状态为 [Approved]，等 Plan 补充 | lock-position-task-safety 有 Spec 无 Plan |
   | 写了 Plan 但没写 Spec | 补充 Spec（至少把 Plan 里的设计描述抽出） | sms-balance-low-alert Plan 很完整但缺独立 Spec |
   | 需求变更导致 Spec 改 | Spec 先更新 → Plan 同步更新，不要只改 Plan 不改 Spec | -- |
   | 紧急修复没时间写完整 Spec | 至少写一份「轻量 Spec」：根因 + 方案 + 边界，一页纸 | -- |

三、一句话总结

┌──────┬──────────────────────────────────────────────────────────────────────────────┐
│ 角色 │ 核心原则 │
├──────┼──────────────────────────────────────────────────────────────────────────────┤
│ 个人 │ Spec 把"为什么"讲透，Plan 把"怎么做"写到没有歧义——不给 AI 留推断空间 │
├──────┼──────────────────────────────────────────────────────────────────────────────┤
│ 团队 │ Spec 是团队的决策记录、Plan 是团队的执行标准——缺一不可配对走，约定先行再开工 │
└──────┴──────────────────────────────────────────────────────────────────────────────┘