本文用DeepSeek Harness 以 IDE 角色来检验AI Coding 能接受spec，
首先要来检验两件事：
① spec.md 的章节完整度——若缺哪一章，AI Coding 是否就会卡在哪? 或开始乱编；
② DeepSeek Harness 这个 Coding IDE，能不能真的按spec 完成 AI Coding 工作。
最后再反推回规格端：一份让 AI Coding 顺畅的 SDD Spec 应该长什么样。
0. 一句话结论
Spec 不是「写得越细越好」，而是「每一章节都要能被 AI Coding 机器化处理」。
- 缺 §6（API Contract）→ AI Coding IDE 直接 Stop-the-Line：不自己编路由
- 缺 §10（验收表）→ 验证闸门没有依据，不含糊「能跑就算对」
- 缺 §8（状态流转）→ 状态值与 SoT 打架，AI Coding 被会迫二选一（就会埋事故）
同时也透过Harness IDE 的 8 项能力（文件 / 沙箱 / 验证循环 / 背景任务 / Todo / Context / Subagent / Stop-the-Line）来验证一份好的Spec 是否 AI Coding 能完成顺利交付；
结果证明；AI Coding 顺不顺畅，90% 是由 spec 的「可机器可读性」决定，不一定是模型强弱决定。
以下是AI 产制spec 参考模版:
1. spec.md 章节完整度 × AI Coding（逐章检验）
检验基准是实际使用的 spec 模板：
「如果缺了会发生什么？」注:以下全部来自某项目开发记录，不是推演文字。
| 章节 | AI Coding 需要它给什么 | 缺了会发生什么（真实 Log） |
|---|---|---|
| §1 Metadata | spec_code / module_code 唯一，且与 MODULE_PLANNING_JSON 逐字一致 | 路径漂移：规划 47 个 code 仅 25 落盘（.007→.006、.005→.002）；AI 找不到对应规格或建错路由 |
| §1.1 依赖与约束 | 显式列出要引用的 global Harness（RLS / 幂等 / 审计 / UI） | 没列 → AI 凭 repo 既有惯例猜，靠 lint / Stop-the-Line 事后补 |
| §1.S 跨 Spec 宣告 | 宣告与其他模块重叠的路由 / 表 | frr.002 §6.1–6.5/6.7/6.9–6.11 与 4 个模块重复 → G-CONFLICT，交付停摆 |
| §2 User Story | 业务目的，校验「为什么有这端点」 | 缺 → 验收口径模糊；对端点正确性影响小 |
| §3 前置条件 | 数据前提（哪张表要什么状态） | fund_drawdown.001：seed 需先把前 2 笔决策提升 APPROVED 才能演示；缺 → demo 造不出、验证卡关 |
| §4 流程概述 | 状态流转顺序（谁推进谁） | 流程没锁死 → transition 覆写幂等 key 的坑（事故 #3）就发生在规格没写「create key 保留」的地方 |
| §5 UI Fields | 字段 / 按钮 / 角色门禁（五态 + allowedRoles） | 缺 → 画面凭 repo 惯例兜底；11 个画面全数完成，但字段顺序依赖 global UI rules |
| §6 API Contract | 端点路径 / 方法 / 参数 / 错误码 | frr.002 §5.4 补录无端点 → G-MISSING-API；collateral-daily 三套路径并存；幂等 key 77 字符撞 varchar(64)（事故 #1） |
| §7 业务规则与校验 | 计算口径 / 单位 / 精度 / 阈值 | 集中度 KPI：spec 给百分比、threshold 用 0.10 → seed 除以 100 对齐；金融精度 rate 6 位 / 金额 4 位 |
| §8 审计与状态流转 | 状态值集合 / 转移 / 审计字段 | 状态值打架：spec UNMATCHED/FAILED vs SoT OPEN/RECALL_INITIATED（事故 #4）；四眼原则 → seed 需另建 operator maker |
| §10 验收与测试 | Given / When / Then / Error Code 测试表 | 缺 → 验证闸门没依据（验收缺失 Stop-the-Line）；有 → T004 / T005 / T006 直接变 curl 脚本 |
解读：从上往下，§6 与 §10 是「AI Coding 会不会停摆」的两道闸门；
§3 / §7 / §8 是「Spec 顺不顺」的润滑剂；
§1 / §1.1 / §1.S 是「Spec 认不认路」的地图。
AI Coding IDE 缺地图会绕路(自行发散)，缺闸门会停摆。
2. DeepSeek Harness IDE 能力 × AI Coding 完成度
下面表格区定义了 Harness 的 8 项 IDE 级能力；
这里逐项对照真实交付中发生的事件，回答「这个 Coding IDE 能不能完成 AI Coding」。
| IDE 能力（原文 F 区） | 真实交付对应事件 | 对「顺畅度」的贡献 |
|---|---|---|
| F1 文件操作 | 事故 #1/#3 的修复（_audit_correlation_id 截断、transition 不再覆写 key）都在 repo 内以 edit 完成 | 改档可追踪、可回滚；spec 指到哪改到哪 |
| F2 沙箱 + 审批 | 全程只改 backend/、vibe-md/、portal.html；系统目录零触碰 | 写操作受控，红线之外无意外写入 |
| F3 验证循环 | 9 份 spec 每份都跑「编译→启动→登录→冒烟→DB→重置→关停」 | spec §10 的每行测试可执行；「跑完才算」 |
| F4 背景任务 | boot server、回归测试放背景，与下一份 spec 开发并行 | 9 份 spec 的验证从串行变并行 |
| F5 Todo / Goal | 每份 spec 七步交付（分析→schema→后端→seed→UI→验证）全程可视 | 多 spec 不「做 A 忘 B」 |
| F6 Context 管理 | checkpoint 浓缩：SoT / 已交付 spec / 错误与修复 / 待办跨轮携带 | 下一个 session 接着做，不重读不重做 |
| F7 Subagent / Workflow | 研究 / 审查类工作丢背景 subagent，主 session 继续主线 | 验证与开发可平行，主线不被杂讯打断 |
| F8 Stop-the-Line | G-CONFLICT（frr.002 ×9 段）、G-MISSING-API（§5.4）、路径冲突（3 套）全部挡下回报 | 规格缺口的「编译错误」在开发期爆出，不是上线才爆 |
结论：Harness IDE 的 8 项能力与 AI Coding 所需全数命中
——「能不能完成」的答案是肯定的，
本案例 9/9 份 spec 交付（48 条 API + 11 个画面）就是完成度证明。剩余变量只剩 spec 本身的质量。
3. 一份 AI Coding 顺畅的 SDD Spec：12 条规划原则
以下每一条都能对应到一次真实事故或一个交付最佳实践。给产品PRD AI Spec 作者当 checklist 用。
- §6 是第一公民：每个流程步骤都要有端点；流程有、端点没有 → G-MISSING-API，宁先补 spec 再交付。
- 路径只准一套：
/api前缀与资源命名在 api-conventions 定死；同一功能不许两套路径并存
（实案：collateral-daily/snapshots vs collateral-daily-snapshots vs pledge-snapshots）。 - 状态值逐字对 SoT：spec 的状态 / 错误码 / 角色码必须能从字典逐字 grep 到；打架依 SoT 收敛并注「见差异回报」。
- 幂等 key 先算长度：命名如
DECISION_MEETING_INITIATE:{tenant}:{no}先算字符数，别撞 audit correlation_id varchar(64)；业务表给 varchar(128)。 - transition 规格写明「create key 保留」：状态推进不得覆写 create 的 idempotency_key，
重放靠 status/version 守卫——这是事故 #3 的直接教训。 - §10 验收表要能转成 curl：每行 Given / When / Then / Error Code 都要能变成 HTTP 冒烟
（happy / replay / 403 / 400 / 409 / 422 / 503）。 - §3 前置条件要可 seed：每个前置状态都要有 demo 数据路径（seed.py 可满足），否则验证卡关
（实案：fund_drawdown.001 先把前 2 笔决策提升 APPROVED）。 - §7 规则要给公式与单位：KPI 是百分比还是 ratio、金额几位小数、rate 几位，都要写死
（实案：集中度 60% vs 阈值 0.10 → seed 除以 100 对齐）。 - §5 UI 要有角色门禁：allowedRoles 明示；菜单可见性与 API 权限用同一组角色码
（SpecRegistry.allowedRoles + require_role 双门）。 - 跨模块重叠要 §1.S 先宣告：与别模块重复的路由 / 表先列出，AI 才知道哪些不该重做（预防 G-CONFLICT：frr.002 ×9 段）。
- §1.1 依赖清单要可直接执行：列出的 global Harness 就是 AI 的「开工前必读清单」，不列就等于让 AI 自行作主惯例(发散)。
- 错误码进字典：spec 出现的每个错误码都要在 error-code-lexicon 有条目，
AI 才能正确回 4xx/5xx 。
4. 券商股票再抵押系统实作画面参考
以下是透过 Deepseek Harness IDE 产生的"香港券商股票抵押融资系统" 参考画面：
这些都是可交付可落地的纯AI 开发应用系统!
扫一扫
440
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
