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

文档与代码的一致性靠 AI 还是靠人Spec Kit 给出的答案为什么在社区里吵翻了【免费下载链接】spec-kit Toolkit to help you get started with SDD or any other process!项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit2025 年 8 月GitHub 开源了 Spec Kit——一个给 AI 编码助手套上结构化流程的工具包docs/history.md 记录了项目从创始人 Den Delimarsky、John Lam 到社区主理人 Manfred Riem 的完整演进。半年多过去围绕它的讨论早已超出又一个 AI 开发脚手架的范畴焦点集中在一个被反复追问的元问题规格文档与代码之间的一致性到底该交给 AI 自动维护还是必须靠人的纪律来保证这个问题在社区里吵出了清晰的两派。一派推崇规格即源代码spec-as-source既然 AI 能读懂规格并生成代码那就应该让规格成为唯一人工编辑的产物代码随时可以重新生成一致性天然成立。另一派则坚持规格锚定spec-anchoredAI 生成的东西需要人审查、需要门禁、需要版本控制里的可追溯记录一致性本质上是组织流程问题。而 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的命运而是命名了三种模型模型变更规则适合场景风险Flow-back任何产物都可先改再人工对账小团队快速迭代静默漂移Flow-forward新需求开新特性目录旧目录不可变审计与历史清晰上下文碎片化Living spec只改spec.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 的每一步之间都插入了人工gateapprove/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考