企业官网建设流程全解析

文档与代码的一致性，靠 AI 还是靠人？Spec Kit 给出的答案为什么在社区里吵翻了

【免费下载链接】spec-kit💫 Toolkit to help you get started with SDD or any other process!项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

2025 年 8 月，GitHub 开源了 Spec Kit——一个给 AI 编码助手套上"结构化流程"的工具包（docs/history.md 记录了项目从创始人 Den Delimarsky、John Lam 到社区主理人 Manfred Riem 的完整演进）。半年多过去，围绕它的讨论早已超出"又一个 AI 开发脚手架"的范畴，焦点集中在一个被反复追问的元问题：规格文档与代码之间的一致性，到底该交给 AI 自动维护，还是必须靠人的纪律来保证？

这个问题在社区里吵出了清晰的两派。一派推崇"规格即源代码"（spec-as-source）：既然 AI 能读懂规格并生成代码，那就应该让规格成为唯一人工编辑的产物，代码随时可以重新生成，一致性天然成立。另一派则坚持"规格锚定"（spec-anchored）：AI 生成的东西需要人审查、需要门禁、需要版本控制里的可追溯记录，一致性本质上是组织流程问题。而 Spec Kit 的独特之处在于——它没有站队，而是把这个问题拆成了两个可以被机制处理的小问题，然后把最终裁决权明明白白地还给了人。这正是它在社区里引发争议，也让 InfoQ 等媒体将其与 Kiro、Tessl 并列讨论的原因。本文结合仓库源码，拆解这套答案的逻辑与边界。

一致性困境的两派立场

先看争论的源头。传统开发里，文档与代码脱节是常态：PRD 写于需求阶段，设计文档写于开工之前，而代码会持续演进。Spec Kit 的方法论文档把这种现状概括为"权力的倒置"（The Power Inversion）：几十年来"代码是真理，规格只是脚手架"（spec-driven.md）。AI 编程让"规格直接生成代码"第一次在工程上可行，于是两种解决路径都变得有吸引力。

AI 派的论点很直接：既然生成代码的是 AI，那文档与代码的偏差本质上只是"生成输入过期了"。只要把规格当作唯一真相源，改需求就改规格，然后重新生成 plan、tasks、代码，一致性就不存在"维护"问题，只有"重新生成"。Spec Kit 的 spec-persistence 文档将这种模型命名为"Living Spec"（活的规格）：spec.md是契约，plan.md和tasks.md都是可抛弃的派生物（docs/concepts/spec-persistence.md）。

人治派的反驳同样有力：AI 的"重新生成"是不可靠的。Spec Kit 自己的文档就坦率承认，在长任务实施中，"agent 会在上下文压缩前后开始偏离计划、忽略任务、甚至产生幻觉"（docs/concepts/complex-features.md）。如果规格生成代码这条路本身会漂移，那么把全部信任押在"规格即真相"上，等于把一致性押在一个会失忆的执行者身上。所以人治派主张：一致性靠的是审查门禁、约定俗成、以及把每一次偏差记录下来的习惯。

有趣的是，这两派在 Spec Kit 的仓库里都能找到"自己人"写的论据——这正是争论在社区里持续升温的原因：工具本身没有替用户回答，而是把选择暴露了出来。

Spec Kit 的可执行规格方案能否真正破局

要理解 Spec Kit 的立场，得先看清它的三层设计：让规格可执行、让偏差可发现、让维护策略可被显式选择。这三层分别对应了"靠 AI"和"靠人"之间的全部争议空间。

第一层：用模板约束 AI，让规格"可执行"

Spec Kit 并不宣称 AI 能凭空写出好规格，而是用模板把 LLM 的行为约束住。在 templates/commands/specify.md 里可以看到这套约束的具体形态：

• 强制 WHAT 而非 HOW：模板明确要求"Focus on WHAT users need and WHY. Avoid HOW to implement (no tech stack, APIs, code structure)"，防止模型过早陷入实现细节；
• 显式不确定性标记：要求用[NEEDS CLARIFICATION: specific question]标出歧义，且上限 3 个，按"范围 > 安全/隐私 > 用户体验 > 技术细节"排序——不允许模型"猜"关键决策；
• 清单即质量门禁：/speckit.specify写完规格后必须生成checklists/requirements.md，逐项验证"无未澄清标记""需求可测试且无歧义""成功标准可量化"，失败则最多迭代 3 次修正。

这套机制的价值在于：它把"文档与代码一致"这个大而空的目标，降维成了"规格本身无歧义、可测试、可追溯"这组可检查的中间条件。模板不是靠人的意志维持纪律，而是把纪律写进了 AI 的执行路径里。社区的共识性评价（多篇 CSDN 技术解析文章）也聚焦于此：Spec Kit 让 AI 从"自由发挥的作家"变成"受约束的规格工程师"。

第二层：让偏差成为可发现的实体

规格写得再好，代码实现仍可能偏离。Spec Kit 对此的回答是/speckit.converge——一个专门用于"测量"一致性的命令。在 templates/commands/converge.md 中，它的执行逻辑定义得非常工程化：

• 以spec.md、plan.md、tasks.md为唯一意图来源（sole source of intent），加上宪法（constitution）作为治理约束；
• 对代码现状做审计，把每个缺口分类为missing（完全缺失）、partial（部分满足）、contradicts（与意图冲突）、unrequested（超出规格的多余实现）四种 gap 类型，并标注严重级别；
• 只追加、不重写：把所有未完成工作作为新任务追加到tasks.md末尾，绝不修改spec.md、plan.md或既有任务；当一切满足时，报告"✅ Converged"，且tasks.md保持字节级不变。

converge的存在意味着：Spec Kit 不承诺"AI 生成的代码永远对"，但它承诺每次偏差都会以可追踪任务的形式浮现——T042 <描述> per <source-ref> (<gap-type>)，其中 source-ref 指向FR-003、US1/AC2等具体规格条目。这就是"可执行规格"的第二层含义：一致性不是一个待维护的状态，而是一个每轮 implement 之后都要重新测量、并以任务形式回流的闭环。配合 git 扩展在before_/after_每个命令上的自动提交钩子（extensions/git/extension.yml），每一次规格变更、每一次实施结果都被固化在版本历史里——这为"谁改了哪一层、是否回流到了规格"提供了审计证据。

第三层：把"谁来维护"的选择权显式交还给人

真正让社区吵起来的是第三层。Spec Kit 官方文档在 docs/concepts/spec-persistence.md 中做了一个罕见的表态："Spec Kit intentionally leaves teams in control"——它故意不替团队决定需求变更后spec.md、plan.md、tasks.md的命运，而是命名了三种模型：

文档甚至明确写道："The model is a team convention, not a CLI setting."（模型是团队约定，不是 CLI 设置）。这正是争论的核心：AI 派看到的是 Living spec 的可行性与优雅，人治派看到的是 Flow-back 中"改了底层产物却未回流到规格"的静默漂移风险——而官方文档把这两种担忧都白纸黑字地写了下来，并给出选择模型的两道自测题：已完成的特性目录是历史记录还是可编辑工作区？spec.md是唯一真相源，还是plan.md/tasks.md可以成为平级真相源？

与其说 Spec Kit"破局"，不如说它把困局重新表述为了可决策的选项。在工作流引擎层面，它也贯彻了同样的哲学：workflows/speckit/workflow.yml 中 specify → plan → tasks → implement 的每一步之间都插入了人工gate（approve/reject，拒绝即中止）。AI 负责生成，人负责在每个门禁前裁决——一致性不是任何一方的独角戏。

从这场争论看 AI 辅助编程的下一站

把 Spec Kit 的争议放回行业坐标系里，能看到一条清晰的主线：AI 编程工具正在从"生成代码"走向"生成可追溯的意图链"。

第一，一致性问题的本质是"产物持久化"之争。社区情报中反复出现的对比框架（AIDD、Vibe Coding、SDD 三者的 2026 年讨论）说明：Vibe Coding 主张即时生成、即时丢弃；SDD 则要求规格、计划、任务、代码四层产物都在版本控制中长期存活。Spec Kit 的converge、hooks、spec-persistence 三件套，本质上是在回答"意图链存续多久、由谁编辑、如何对账"这三个问题——而这三个问题没有放之四海而皆准的答案，只有团队显式选择后的约定。InfoQ 将 spec-kit 与 Kiro、Tessl 并列分析，也正是因为三者在"意图如何持久化"上的不同取舍构成了当前工具设计的核心分水岭。

第二，"靠 AI 还是靠人"可能是个伪命题，真正的问题是"信任放在哪一层"。Spec Kit 给出的架构是：让 AI 承担生成（规格、计划、任务、代码），让机制承担发现（converge的 gap 分类、specify的清单门禁、git 的提交钩子），让人承担裁决（workflow gate、宪法、三模型选择）。这个分工在 docs/guides/contract-driven-development.md 的跨仓库协作场景中体现得最彻底——契约只有一个权威所有者，消费方 pin 版本，变更必须"先在权威源达成一致、再发布、再逐消费者评审"，绝不静默同步。这份文档甚至不需要新的 CLI 功能，它完全建立在"团队维护的约定与检查"之上。

第三，这场争论的终局，可能不是某个工具胜出，而是"意图优先"成为默认共识。Spec Kit 从 2025 年 8 月奠基到 2026 年 v1.0.0，演进路径本身就是注脚：它从 SDD 工具包成长为面向编码 Agent 的可扩展框架——integrations 目录下已有 40+ 个 agent 接入（src/specify_cli/integrations/），presets 可裁剪流程（如 presets/lean/README.md 把流程压到"只剩提示与产物"），extensions 可注入合规检查与 git 纪律。当 40 多种 Agent 都能跑同一套意图链时，讨论的焦点自然从"哪个模型更强"转向"意图如何被结构化管理"。

回到开头的题目：文档与代码的一致性靠 AI 还是靠人？Spec Kit 的答案在仓库里写得很直白——一致性不是被"维护"出来的，而是被"重新生成 + 持续测量 + 人工裁决"三者共同生产出来的。AI 负责把规格变成代码，机制负责让每次偏差可见，人负责在最关键的门禁处行使判断。社区之所以吵翻，是因为这套答案没有给出一个可以偷懒的"最终方案"，而是把一道原本模糊的工程难题，变成了一个必须由每个团队亲自作答的判断题。而这，或许恰恰是它最有价值的贡献。

【免费下载链接】spec-kit💫 Toolkit to help you get started with SDD or any other process!项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit