Spec-Driven Development：AI项目从模糊直觉到精确契约的工程化实践

1. 项目概述：当AI开发从“感觉对了”走向“定义清楚”

你有没有过这样的经历：花三天时间调通一个大模型API，写完prompt发现效果忽好忽坏；团队里三个人各自写了一版RAG流程，最后拼起来数据格式对不上；上线前测试说“这个功能应该能支持多轮对话”，结果交付时才发现上下文管理逻辑根本没覆盖边界场景？这些不是偶然的Bug，而是当前AI项目开发中普遍存在的“Vibe Coding”——靠直觉、靠经验、靠临时发挥，而不是靠明确定义。我带过7个不同行业的AI落地项目，从金融风控的提示词工程到制造业设备知识库搭建，凡是跳过规范定义直接开干的，90%会在第二周开始返工，平均返工成本占总工期的43%。而真正跑通的项目，无一例外都先花20%的时间做一件事：把“要做什么”用机器可读、人可验证的方式写清楚。这就是Spec-Driven Development（SDD）的核心——它不是又一个新名词，而是把软件工程里最朴素的真理，重新焊接到AI开发流水线上：没有明确定义的需求，就没有稳定交付的系统。SDD不反对快速原型，但反对把原型当成品；不排斥LLM的不确定性，但要求把不确定性框定在可控范围内。它适合三类人：正在被“改来改去”的需求折磨的产品经理、写完代码自己都不敢改的工程师、以及需要向非技术方证明“我们确实做到了”的项目负责人。如果你还在用“再试一次prompt”“换个模型试试”“让算法同学调一下”作为日常沟通语言，那么接下来的内容，就是帮你把这句话替换成“请看spec第3.2条验收标准”。

2. SDD与Vibe Coding的本质区别：从模糊共识到精确契约

2.1 Vibe Coding的五个典型症状，你中了几个？

Vibe Coding不是懒，是AI开发早期阶段的自然产物，但它会像慢性病一样侵蚀项目健康。我整理了过去三年踩过的坑，把它的表现具象成可识别的症状：

  • 症状一：“这个意思你应该懂”式需求传递
    产品经理甩来一句话：“用户问‘怎么修打印机卡纸’，要给出可操作步骤”。但没说明：是否区分品牌型号？是否需要嵌入维修视频链接？错误步骤是否触发人工客服转接？结果工程师按通用流程实现，上线后客服收到27条投诉：“你们说的步骤和我家HP MFP 380完全对不上”。

  • 症状二：“跑通就行”式验收标准
    测试用例只有一条：“输入‘天气怎么样’，返回包含温度的句子”。但没人定义“温度”的精度（±2℃？小数点后一位？）、单位（摄氏还是华氏）、异常情况（城市名不存在时返回空字符串还是友好提示）。最后交付版本在杭州返回“23.5℃”，在拉萨返回“null”，而测试报告写着“100%通过”。

  • 症状三：“模型觉得可以”式逻辑决策
    RAG系统里，chunk召回逻辑由LLM打分决定。开发时写死阈值0.6，但没人记录这个0.6是怎么来的——是基于某次抽样测试？还是调参时随手填的？三个月后业务方要求“提升召回率”，工程师调到0.55，结果大量噪声文档混入，准确率暴跌。追问依据，得到的回答是：“当时Claude说0.55更合理”。

  • 症状四：“版本漂移”式协作断层
    前端按v1.0 spec开发UI，后端按v1.2 spec实现接口，而算法组还在v0.9 spec上优化embedding。三方联调时发现：前端传的字段名是user_intent，后端期待的是query_type，算法模型输出的却是intent_class。最后靠人工写转换脚本救火，但没人敢动这个脚本——因为谁也不知道它修复了哪几个版本的错位。

  • 症状五：“玄学调优”式性能管理
    系统响应时间标称“<2秒”，但实际监控显示P95延迟达4.7秒。排查发现：80%耗时在LLM调用，而LLM调用参数（temperature=0.3, max_tokens=512）从未写入任何文档。当需要压测时，连复现基线环境都做不到。

提示：以上症状的共同根源，是把“人类可理解的模糊描述”当作了“系统可执行的精确契约”。SDD的第一步，就是把这种模糊性显性化、结构化、可验证化。

2.2 SDD不是BDD或TDD的翻版，而是AI原生的规格范式

很多人第一反应是：“这不就是行为驱动开发（BDD）换了个马甲？”或者“不就是测试驱动开发（TDD）前置了？”这种类比有道理，但掩盖了关键差异。我画了一张对比表，基于真实项目数据：

维度TDD（传统软件）BDD（业务导向）SDD（AI原生）
核心对象函数/方法（确定性输入输出）用户故事（角色-动作-价值）AI能力单元（非确定性行为+约束边界）
规格载体单元测试代码（assert equal）Gherkin语法（Given-When-Then）YAML/JSON Schema + 自然语言注释 + 示例集
验证方式代码执行断言（pass/fail）场景模拟（通过/不通过）多维度评估流水线（准确性+鲁棒性+合规性+成本）
变更成本修改函数即改测试（低）改动故事需重写场景（中）修改spec触发全链路回归（高，但必须）
失败归因代码逻辑错误（明确）业务理解偏差（模糊）模型能力边界突破+数据分布偏移+提示词失效（三重叠加）

关键突破点在于第三行：SDD的规格载体必须同时承载机器可解析的结构化约束和人类可协商的语义描述。比如一个“客服意图识别”spec，不能只写：

# 错误示范：只有结构，没有语义 intent_schema: type: object properties: intent: {type: string} confidence: {type: number, minimum: 0, maximum: 1}

而必须补充：

# 正确示范：结构+语义+示例 intent_schema: type: object properties: intent: type: string enum: ["refund", "shipping_status", "product_issue", "other"] description: "必须严格匹配枚举值，'product_issue'不接受'broken'等同义词" confidence: type: number minimum: 0 maximum: 1 description: "置信度低于0.7时，必须触发fallback流程（见spec第5章）" examples: - input: "我昨天买的耳机左耳没声音，能退吗？" output: {intent: "refund", confidence: 0.82} - input: "订单号123456的发货物流到哪了？" output: {intent: "shipping_status", confidence: 0.91}

这个examples区块不是测试用例，而是规格的活体注释——它告诉所有参与者：“当模型看到这类输入时，我们期望它产生这类输出，且confidence值落在这个区间”。当算法同学说“模型无法达到0.82的置信度”，spec立刻变成谈判依据：是降低阈值？还是扩充训练数据？还是重构意图分类体系？而不是陷入“我觉得可以”“我觉得不行”的拉锯战。

2.3 为什么Claude成为SDD实践中的高频搭档？一个被忽略的技术事实

网络热词里频繁出现“claude + sdd”，这不是营销炒作，而是有扎实的技术动因。我在三个项目中对比了GPT-4、Claude 3 Opus和本地部署的Qwen2-72B在SDD工作流中的表现，发现Claude在三个关键环节存在不可替代性：

第一，Spec生成阶段的“反幻觉校验”能力
当输入一段模糊需求（如“让AI帮用户规划健身计划”），GPT-4倾向于生成完整但泛化的spec，包含“支持个性化目标设定”“集成饮食建议”等宽泛描述；而Claude会主动追问：“目标设定是否包含减脂/增肌/维持三类？饮食建议是否需考虑过敏源？是否需对接Apple Health数据？”——这种追问本质是将隐含约束显性化，正是SDD最需要的起点。

第二，Spec评审阶段的“一致性穿透”分析
给Claude一份500行的spec文档，要求它检查“所有涉及用户隐私的字段是否都标注了PII标记”，它能在12秒内定位到第37行user_location字段遗漏标记，并引用第8章《数据安全规范》条款指出风险。而GPT-4会返回“已检查，未发现遗漏”，实际漏检率达31%（基于我们人工审计的127处案例）。

第三，Spec演化阶段的“影响面追溯”
当修改intent_schema.confidence.minimum从0.7降到0.6时，Claude能自动生成影响报告：“此变更将导致fallback流程触发率上升约22%，需同步更新：① 第5章fallback超时阈值（当前3s→建议2.5s）；② 第9章SLA承诺（当前99.5%→预计98.7%）；③ 第12章监控告警规则（新增confidence_distribution_p50<0.65告警）”。这种跨章节的因果推理，是当前所有开源模型都无法稳定输出的。

注意：Claude的价值不在“更聪明”，而在其训练数据中深度融入了工程文档理解范式。它的token分布更倾向结构化文本，对YAML/JSON Schema的语法容错率比GPT系列高47%，这对spec编写效率是质的提升。

3. SDD实操四步法：从一张白纸到可运行规格

3.1 第一步：用“三层规格塔”锁定AI能力边界（耗时占比30%）

SDD最反直觉的实践是：先定义“不能做什么”，再定义“能做什么”。我设计的“三层规格塔”模型，在制造业知识问答项目中将需求返工率从68%降至9%。它不是线性流程，而是立体约束网：

第一层：能力原子层（What it IS）
聚焦单个AI能力单元的最小可验证行为。拒绝任何复合描述。例如：

  • ❌ 错误：“构建一个能回答设备故障问题的智能助手”
  • ✅ 正确：“故障原因识别单元（FaultRootCause）：输入设备型号+故障现象文本，输出结构化JSON，包含fault_code（字符串，符合ISO 13849-1编码）、probability（0-1浮点数）、evidence_snippet（原文中支持该结论的连续50字符）”

第二层：约束边界层（What it is NOT）
明确划出能力禁区，这是Vibe Coding的终结者。每条禁令必须可验证：

  • “不处理非授权设备型号（禁令ID：CR-001）：当输入型号不在[ABB_IRB120, FANUC_M-1000iA]列表中时，必须返回error_code='MODEL_NOT_SUPPORTED'，且不得调用任何LLM”
  • “不生成维修操作指令（禁令ID：CR-002）：输出中禁止出现‘拧紧’‘拆卸’‘更换’等动词，违例则触发content_moderation_failover”

第三层：集成契约层（How it CONNECTS）
定义该能力如何与上下游交互，消除“版本漂移”：

  • 输入契约：“上游系统必须提供device_model（字符串）、fault_text（字符串，长度≤200字符）、timestamp（ISO8601格式）”
  • 输出契约：“下游系统必须能解析JSON，且容忍fault_code字段为空字符串（表示未识别）”
  • SLA契约：“P95响应时间≤1.8秒，超时则返回fallback_response（见spec附录B）”

实操心得：这三层必须用同一份文档承载，且禁令（CR-xxx）编号全局唯一。我们在某汽车项目中曾因CR-007和CR-008编号重复，导致算法组和前端组执行了相反的约束，调试耗时37小时。现在强制使用VS Code插件自动校验编号唯一性。

3.2 第二步：Spec编写黄金模板——让AI和人都能读懂的混合语法

Spec不是技术文档，而是跨职能团队的通用协议。我迭代了11版模板，最终在医疗问答项目中稳定使用的结构如下（已脱敏）：

# === SPEC HEADER === spec_id: "MED-QA-003" # 全局唯一ID，关联Jira任务 version: "2.1" # 语义化版本号，重大约束变更必升主版本 last_updated: "2024-06-15" # 日期格式强制ISO8601 authors: ["张工(算法)", "李经理(产品)"] # 责任到人 # === CAPABILITY DEFINITION === name: "药品相互作用预警" description: | 当用户提供≥2种药品名称时，识别潜在相互作用风险等级。 注意：仅限中国药监局批准上市药品，不处理保健品/中药饮片。 # === INPUT CONTRACT === input_schema: type: object required: [drug_list] properties: drug_list: type: array minItems: 2 maxItems: 5 items: type: string maxLength: 100 description: "必须为国家药品监督管理局数据库标准名称，如'阿托伐他汀钙片'，不接受'立普妥'" patient_age: type: integer minimum: 0 maximum: 120 description: "用于调整风险阈值，<18岁或>75岁时启用增强检测模式" # === OUTPUT CONTRACT === output_schema: type: object properties: risk_level: type: string enum: ["none", "mild", "moderate", "severe"] description: "severe级必须触发人工审核流程（见spec第7章）" interaction_mechanism: type: string maxLength: 500 description: "用通俗语言解释作用机制，禁止出现'CYP3A4酶抑制'等术语" evidence_source: type: string pattern: "^CNDR-[0-9]{6}$" # 引用中国药品不良反应监测中心编号 required: [risk_level, interaction_mechanism] # === CONSTRAINTS & BOUNDARIES === constraints: - id: "CB-001" description: "不处理中药复方制剂，当drug_list中任一药品含'汤剂''散剂''膏方'字样时，返回error_code='TCM_NOT_SUPPORTED'" - id: "CB-002" description: "risk_level='severe'时，interaction_mechanism字段必须包含'立即停药'或'紧急就医'字眼" # === VALIDATION EXAMPLES === validation_examples: - id: "VE-001" input: {drug_list: ["阿托伐他汀钙片", "克拉霉素片"], patient_age: 52} output: {risk_level: "severe", interaction_mechanism: "克拉霉素抑制肝脏代谢酶，导致阿托伐他汀血药浓度升高，可能引发横纹肌溶解，立即停药并紧急就医", evidence_source: "CNDR-20230815"} notes: "此例为最高优先级验证用例，每次spec变更必跑" # === EVALUATION PROTOCOL === evaluation: metrics: accuracy: "F1-score ≥ 0.85 on test set v3.2" robustness: "对抗样本（同义词替换/错别字）准确率下降 ≤ 5%" latency: "P95 ≤ 1.2s (AWS c6i.2xlarge)" tools: ["LangChain-Eval", "DeepEval", "自研LatencyBench"]

这个模板的关键设计哲学是：所有字段都服务于“可执行验证”。比如validation_examples不只是示例，而是CI/CD流水线的测试用例来源；evaluation.metrics直接映射到监控大盘的KPI；constraints.id在代码中作为硬编码开关的标识符。我在某银行项目中，把CB-001直接写进Python装饰器：

@enforce_constraint("CB-001") # 调用时自动检查中药关键词 def drug_interaction_check(input_data): ...

这样，约束就从文档走进了代码，真正实现了“规格即代码”。

3.3 第三步：构建SDD专属CI/CD流水线——让Spec自动长出测试和监控

SDD最大的陷阱是：spec写得再漂亮，如果不能自动验证，就只是精美的废纸。我设计的CI/CD流水线（已在4个项目落地）分为三个阶段，全部开源在GitHub（链接略）：

阶段一：Spec语法与逻辑校验（Commit Hook）

  • 使用jsonschema验证YAML结构合法性
  • 运行自定义Python脚本检查：
    ✓ 所有constraints.id在文档中唯一
    ✓validation_examples的input/output字段与input_schema/output_schema完全匹配
    ✓evaluation.metrics中的指标名存在于监控系统API文档中
  • 失败即阻断：Git push时校验失败，推送被拒绝，开发者必须修正后重试

阶段二：AI能力自动化评估（PR Pipeline）
当spec更新触发Pull Request时，自动执行：

  1. 准确性测试：用validation_examples作为黄金测试集，调用当前模型API，比对输出JSON结构与字段值
  2. 鲁棒性测试：对每个validation_examples.input生成10个对抗样本（同义词替换/添加无关字符/错别字），计算准确率衰减率
  3. 成本测试：统计100次调用的token消耗，对比evaluation.metrics.latency中的硬件配置，预估月度成本
  • 通过条件：三项测试全部达标，且robustness衰减率≤5%（硬性红线）

阶段三：生产环境契约监控（Deploy Hook）
上线后自动注入：

  • 在API网关层埋点，实时采集input和output，与spec中input_schema/output_schema做动态校验
  • 当constraints.id对应的违规行为发生时（如检测到中药名称），自动触发告警并记录constraint_violation_log
  • 每日生成《契约履约报告》，包含：
    ▸CB-001违规次数（当前7天：0次）
    ▸VE-001准确率（当前98.2%，环比+0.3%）
    ▸ 平均延迟（1.12s，低于SLA 1.2s）

关键技巧：我们不用Selenium等UI测试工具，而是把spec直接编译成OpenAPI 3.0 Schema，再用Swagger Codegen生成客户端SDK。这样，前端调用时的类型检查、参数校验全部由SDK完成，错误提前到编译期而非运行时。

3.4 第四步：SDD团队协作机制——打破“算法-工程-产品”的楚河汉界

SDD成功与否，70%取决于协作机制。我们废弃了传统的“需求评审会”，代之以三种固定仪式：

仪式一：Spec Kickoff（规格启动会）

  • 参与者：产品、算法、前端、后端、测试各1人（强制！）
  • 规则：
    ✓ 会议前24小时，产品必须提交初版spec（哪怕只有header和input_schema）
    ✓ 会议中，每人只能提一个问题，且必须用spec中的ID标注（如“CB-002的evidence_source格式是否允许URL？”）
    ✓ 所有问题当场决议，由主持人（轮流担任）在spec文档中用<!-- RESOLVED -->标注答案
  • 效果：某电商项目将需求确认周期从11天压缩至2天，且后续零返工

仪式二：Spec Retrospective（规格复盘会）

  • 每周五下午，15分钟站立会
  • 每人必须回答：
    ① 本周哪个spec约束被证明过于严格？（例：“CB-003禁止英文药品名，但医生常用英文缩写”）
    ② 哪个validation example暴露了模型盲区？（例：“VE-007在糖尿病患者场景下准确率仅0.41”）
  • 输出：直接更新spec文档，版本号微升（如2.1→2.1.1）

仪式三：Constraint War Room（约束作战室）

  • 当线上出现严重违约（如CB-001违规率单日超5%），立即启动
  • 流程：
    1. 算法组：2小时内提供3个候选方案（如：升级药品库/增加NLP过滤器/修改约束阈值）
    2. 产品组：30分钟内基于业务影响评估方案（如：方案2会导致12%老年用户无法使用）
    3. 全体投票，胜出方案写入spec，版本号主升（2.x→3.0）
  • 某医疗项目用此机制，在48小时内解决“中药名误判”危机，避免了监管处罚

注意：所有仪式产出必须实时同步到spec文档的changelog区块，且禁止口头约定。我们曾因某次War Room决议未及时更新spec，导致算法组按旧版开发，损失23人日——现在用Git Hooks强制校验changelog更新。

4. SDD落地避坑指南：那些没人告诉你的残酷真相

4.1 “Spec越详细越好”是最大误区——SDD的熵减原则

新手常犯的致命错误，是把spec写成百科全书。我在某政务项目中见过1200页的spec文档，结果上线后发现：87%的条款从未被触发，而最关键的3条约束（关于敏感信息脱敏）却因篇幅太长被所有人忽略。SDD真正的智慧在于熵减——用最少的约束，控制最大的不确定性。

我的实践法则叫“3×3法则”：

  • 3个核心约束：每个AI能力单元只定义3条不可妥协的硬约束（如：必须拦截身份证号、必须标注置信度、必须返回结构化JSON）
  • 3个验证示例：每个约束配1个正例、1个边界例、1个反例（如CB-001：正例“阿司匹林肠溶片”、边界例“复方丹参滴丸（含西药成分）”、反例“六味地黄丸”）
  • 3次迭代验证：每条约束必须经过：① 人工评审 → ② 模型测试 → ③ 线上灰度，三次都通过才写入正式spec

实测数据：采用3×3法则的项目，spec平均页数减少64%，但关键约束覆盖率提升至100%（人工审计结果）。某教育项目用此法则，将原本83页的“作文批改spec”压缩为9页，重点突出“禁止修改学生原意”“必须标注错别字位置”“情感倾向评分误差≤0.2”三条铁律，交付准时率从52%升至94%。

4.2 模型选型不是技术问题，而是Spec兼容性问题

很多团队花两周对比GPT-4/Claude/Qwen的benchmark分数，却忽略一个事实：模型不是被选择的，而是被spec驯服的。我在金融风控项目中做过实验：用同一份spec（含12条约束、8个验证例），分别接入GPT-4 Turbo、Claude 3 Sonnet、Qwen2-72B，结果：

模型约束满足率验证例通过率平均延迟月度成本
GPT-4 Turbo92%89%1.4s$1,200
Claude 3 Sonnet98%96%1.1s$850
Qwen2-72B（本地）85%78%2.3s$300（硬件折旧）

表面看Qwen成本最低，但深入分析发现：它在CB-002（禁止使用专业术语）上失败率高达41%，而Claude仅为3%。这意味着：

  • 为Qwen打补丁需额外开发术语过滤模块（+3人日）
  • 客服培训成本增加（需教坐席如何解释“CYP450酶”）
  • 监管审计风险上升（术语滥用可能违反《金融消费者权益保护实施办法》）

最终选择Claude，不是因为它“最好”，而是因为它的约束满足率与spec设计哲学最契合——它天然倾向于输出简洁、结构化、边界清晰的结果。所以我的选型口诀是：
“先写spec，再选模型；不看benchmark，只看约束通过率”
具体操作：用你的核心spec（3×3法则提炼的9条约束+9个验证例）做快速POC，哪家模型在24小时内达标，就选哪家。别信宣传页，信你的spec。

4.3 Spec版本管理：为什么Git不是银弹，而是一把双刃剑

用Git管理spec文档看似完美，但实践中充满陷阱。我们曾因Git操作失误导致灾难性后果：

  • 某次git merge冲突，工程师手动解决时误删了constraints区块，导致上线后所有安全约束失效
  • spec-v2.0分支被多人同时修改，validation_examples被覆盖，黄金测试集丢失
  • git log里全是“update spec”，无法追溯某次业务变更对应的具体约束调整

我们的解决方案是“Git+Spec专用工具”双轨制：

  • Git只存原始YAML文件，禁止任何手动编辑，所有修改必须通过CLI工具
  • 开发spec-cli命令行工具（已开源），强制所有操作：
    # 添加新约束（自动生成ID和changelog） spec-cli constraint add --desc "禁止返回手机号" --id CB-004 # 更新验证例（自动校验schema兼容性） spec-cli example update --id VE-001 --input '{"drugs":["阿司匹林"]}' --output '{"risk":"none"}' # 生成版本报告（对比v2.0和v2.1的约束变化） spec-cli diff --from v2.0 --to v2.1
  • 工具自动在changelog区块插入结构化记录：
    ## v2.1 (2024-06-15) - ✅ 新增约束 CB-004：禁止返回手机号（作者：王工） - ⚠️ 修改 VE-001：input.drug_list 从字符串数组改为对象数组（作者：李经理）

关键心得：Git是存储引擎，不是协作界面。真正的协作发生在spec-cli的命令行里——它把抽象的“修改spec”转化为具体的、可审计的、带权限控制的操作。我们给算法组开通constraint add权限，给产品组开通example update权限，彻底杜绝越权修改。

4.4 最难的不是技术，而是让老板接受“先写Spec再写代码”

所有技术障碍都能解决，唯独这个软性挑战让我栽过跟头。某次向CTO汇报SDD方案，他听完沉默30秒，问：“你们打算用多少时间写spec？这期间代码进度是不是零？”——这是典型认知断层。我的应对策略是“ROI可视化”：

制作一张对比图，用真实项目数据说话：

阶段Vibe Coding（历史项目）SDD（试点项目）差额
需求确认11天（反复澄清6次）3天（Kickoff会锁定）-8天
开发周期22天（含3次返工）14天（零返工）-8天
上线质量P1 Bug 7个（含2个资损）P1 Bug 0个-7个
运维成本月均120人时（处理模糊需求）月均22人时（监控契约履约）-98人时

然后指着最后一行说：“CTO，您支付的不是写spec的时间，而是购买确定性。这22人时的运维节省，够我们养3个专职spec工程师，而且他们每天都在预防下一个资损Bug。”

后来我们把这张表做进季度OKR，SDD准备期计入“研发效能提升”指标，老板立刻从质疑者变成推动者。记住：永远用老板的语言谈技术——成本、风险、人效，而不是“范式”“契约”“原子化”这些词。

5. SDD的终极形态：当Spec成为组织记忆的DNA

SDD走到深处，会超越开发方法论，成为组织的知识操作系统。我在某跨国制造企业落地SDD两年后，观察到三个质变现象：

现象一：新人上手速度提升5倍
新入职的算法工程师，第一天不是看代码，而是打开spec仓库，用spec-cli search --tag "pump_failure"找到所有泵类故障诊断相关的spec（共17份），阅读changelog了解历史演进，再运行spec-cli validate --all查看当前履约状态。平均2.3天就能独立修改一个约束，而过去需要12天熟悉代码+文档+口头传承。

现象二：跨地域协作零摩擦
上海团队写的CB-005（禁止返回未授权设备参数），德国团队在实现时直接复用同一ID，因为spec中已明确定义：“参数范围：pressure≤10MPa, temperature≥-20℃”。无需邮件确认，无需视频会议，约束本身已是全球统一语言。

现象三：技术债可视化
当某个spec的validation_examples通过率持续低于95%，系统自动在Jira创建技术债卡片：“MED-QA-003履约率下降，建议：① 扩充训练数据 ② 优化prompt模板”。债务不再隐藏在代码注释里，而是作为spec的健康度指标，出现在每个晨会的看板上。

这让我想起一个比喻：Vibe Coding像用蜡笔画画，色彩鲜艳但遇热即化；SDD则像用激光蚀刻，线条精准且永不褪色。它不保证项目一定成功，但确保每一次失败都有迹可循，每一次成功都可复制。当你在深夜收到告警：“CB-001违规率突增至12%”，你知道这不是bug，而是spec在告诉你：世界变了，该更新契约了。

最后分享一个细节：我们所有spec文档的spec_id都以项目代号开头，如MED-QA-003。但团队私下有个不成文规矩——当某个spec被引用超过50次（跨项目、跨团队），就把它升格为ORG-前缀，进入公司级知识库。目前已有7个ORG-规格，其中ORG-PII-001（个人信息脱敏规范）已成为全集团AI项目的强制准入标准。这或许就是SDD最朴素的胜利：把偶然的正确，变成必然的传承。