SDD + TDD 纪律（跨项目可复用）

Overview

把"规格驱动开发（SDD）+ 测试驱动开发（TDD）+ 约束变更登记"沉淀成一套可直接套用的纪律，让 AI 在任何项目里都"写得快且信得过"。核心不是禁用 AI 的自由发挥，而是用 spec 先确认、测试先红后绿、共享契约先登记 三道闸门，把不可控的"AI 直接写实现" 变成人能 2 分钟审完、能回归、能信任的产物。

本 skill 不绑定任何具体技术栈；语言 / 框架 / 测试运行器由项目 spec 指定。

When to use

用户要求"按 spec 驱动 / TDD / 先写 spec / 测试先行"做任何开发。
在新项目（快项目）里想快速建立一套可信赖的 AI 编码纪律。
开始 / 修复 / 重构某个功能，且希望 AI 先出 spec 再写代码、先红测试再绿实现。
用户提到"约束登记""spec 先行""让 AI 写得快又信得过"等意图。

若项目已有 spec 体系（如 spec/CONVENTIONS.md、spec/system.spec.md、域 spec），直接复用它，不要重复造；若没有，先按" scaffolding"一节引导搭建。

Three hard rules（不可违背）

Spec 先行：任何待办项（新功能 / bug / 重构）动手写代码前，必须先有经人明确确认的 spec。未经确认，一个实现字符都不写。
测试伴随（TDD）：先按 spec 写测试（红），再写实现让测试绿。顺序不可颠倒；退出标准 = 测试全绿 + 静态类型校验通过。AI 说"写好了"不算数。
约束变更登记：任何触及"跨域共享契约"（错误模型 / 存储表结构 / 路由与域命名 / 类型规则）的改动，必须先在该契约的"索引表"登记并获人重新确认，才进入实现；未登记视为 spec 未确认。

Session-start SOP（每次动手前必跑）

定位项目的 spec 体系：优先读 spec/CONVENTIONS.md（流程法）→ spec/system.spec.md （跨域契约 + 索引表）→ 目标域 spec（如 spec/domains/<domain>.spec.md）。
路径不存在时，按"Scaffolding"一节先搭建，再继续。
判断本次改动属于：仅单域 / 跨域共享契约 / 新增域 —— 决定要不要动共享契约文件。
若涉及共享契约改动，先查索引表是否已有登记；没有就先补登记并等确认。

原则：没读 spec 三级文件就动手，视为违规。

Layered constraint model（约束放哪一层，防膨胀）

全局流程硬规则（任何任务都适用）→ 放 CONVENTIONS.md（或等价的总规范文件）。几乎不变；改动需全体 spec 复审。
跨域共享契约（错误模型 / 存储 / 路由 / 类型）→ 放 system.spec.md（等价的总契约文件）。仅在结构性变更时改。
单域契约（某业务自己的字段/行为）→ 放对应域 spec，引用共享契约，不重复定义。

经验法则：能上升为"以后所有需求都遵守"的放全局规范；只跟共享架构相关的放契约文件；否则放域 spec。共享契约文件是"活契约"，靠"索引表 + 同步规则"保持不漂移。

Standard flow（红 → 绿 checklist）

[ ] 探讨：写出 spec（域 spec 入 domains/，系统级契约入 system.spec.md）
[ ] 确认：人 review 并明确说"可以"（未确认不动手）
[ ] 红：按 spec 先写测试（按功能拆文件）→ 跑测试确认全红
[ ] 绿：写实现 → 先静态类型校验通过 → 再行为测试全绿
[ ] 回看：人审 spec + 测试（几十行），不是实现细节
[ ] 提交：spec + 实现 + 测试一并纳入版本管理

验证管线（完成的唯一判据）：静态类型校验（如 pyright）→ 行为测试（如 pytest）。任一不过即未完成。

Anti-patterns（AI 绝不可做）

跳过 spec 直接写实现
先写实现再"补"测试（顺序颠倒）
测试还没全绿就宣称"完成"
改了共享契约却没回契约文件 + 索引表 + 重新确认
在域 spec 里重复定义共享契约已有的规则（应引用，不复制）
把单域需求写进共享契约文件，导致它膨胀成大杂烩
用"我觉得这样也行"替代理性确认；拿不准就先问人，或先在 spec 写清"不在范围"

Completion criteria（什么是"真完成"）

同时满足才叫完成：

spec 经人确认（或本次改动已在索引表登记并确认）
静态类型校验 0 errors
行为测试全绿（含新增测试 + 既有回归不破）
spec 每条边界 / 错误都有对应测试且通过
若触及共享契约，索引表状态已同步更新

Edge cases（越界 / 拿不准时）

需求模糊：先和人澄清，或写进 spec 的"不在范围"划清边界，不自由发挥。
发现 spec 自相矛盾：先停，提给人，不擅自把改动当事实写进 spec。
必须改共享契约但人不在：先在索引表标"草稿 / 待确认"，实现留到确认后。
改旧代码：先确认既有 spec 是否仍成立；不成立就先更新 spec 再改实现。

Scaffolding（项目无 spec 体系时，先搭建）

若项目没有 spec/ 体系，按以下顺序引导搭建（模板见 references/）：

读 references/conventions_template.md → 写入项目 spec/CONVENTIONS.md（全局流程硬规则）。
读 references/system_spec_template.md → 写入项目 spec/system.spec.md （跨域契约 + 索引表 + 同步规则，初始状态标"草稿"或仅列已有域）。
每个业务域：读 references/domain_spec_template.md → 写入 spec/domains/<domain>.spec.md，并引用 ../system.spec.md。
在 system.spec.md 的索引表登记各 spec 及其状态，作为同步的单一事实源。

搭建完成后，后续开发即走上面的 SOP 与红→绿流程。

One-line mantra（给 AI 的紧箍咒）

没读规范 + 契约 + 目标域 spec，不动手；没 spec 确认，不实现；没测试全绿 + 静态校验通过，不算完；动共享契约，先登记索引表再等人确认。