★ FEATURED ARTICLE 1. 三套工具都试过之后我为什么还是选择自己搭去年下半年开始我陆续在几个中型项目里尝试了 Spec Kit、OpenSpec 和 Superpowers 这三套规格驱动开发工具。说实话每一套都有让人眼前一亮的设计但真正放到团队日常协作里跑上两三个月问题就一个个冒出来了。这篇文章不是要踩谁捧谁而是把我踩过的坑、做过的对比、以及最终决定自己搭一套轻量方案的全过程摊开来聊。如果你也在纠结选哪套规格管理工具或者已经用了一段时间但总觉得哪里不对劲那这篇内容应该能帮你省下不少试错时间。先交代一下背景。我所在的团队大概十来人同时维护着三四个中等规模的项目技术栈以 TypeScript 和 Python 为主偶尔涉及一些基础设施配置。我们需要的不是什么重型的企业级方案而是一套能让规格文档和实际代码保持同步、让新成员快速上手、让变更可追溯的轻量机制。Spec Kit、OpenSpec 和 Superpowers 都是在社区里口碑不错的选项我花了大概两个月时间分别做了深度试用下面把核心发现整理出来。2. 三套工具的核心设计思路拆解2.1 Spec Kit 的规格优先理念Spec Kit 的核心思路是“规格即源头”。它要求你在写任何代码之前先用它定义的格式把功能规格写清楚然后基于这份规格生成任务列表、实现计划最后才进入编码阶段。这套流程理论上很完美尤其适合需求相对稳定、迭代周期较长的项目。我实际用下来Spec Kit 最大的优势在于它的结构化程度非常高。每个功能都有明确的 spec 文件、plan 文件和 tasks 文件三者之间有严格的对应关系。当你需要回溯某个功能为什么这么实现时顺着这条链路查下去基本都能找到答案。但问题也出在这里——它的流程太重了。一个小功能的改动可能要更新三四个文件而且这些文件之间的同步全靠人工维护。团队里有人改了 spec 但忘了更新 tasks或者 plan 和实际实现脱节这种情况出现几次之后大家对这套流程的信任度就下降了。2.2 OpenSpec 的轻量灵活路线OpenSpec 走的是另一条路。它不强制你遵循固定的文件结构而是提供了一套约定和工具让你用自己喜欢的方式组织规格文档。它的核心理念是“规格应该活在代码旁边”所以鼓励你把规格文件直接放在项目目录里和代码一起版本控制。这套思路我一开始非常喜欢因为它足够灵活不会给团队增加太多额外负担。但用了一段时间后发现灵活的另一面就是缺乏约束。不同的人写出来的规格格式差异很大有的人写得详细有的人就几句话带过。当项目规模变大、参与人数变多之后规格文档的质量参差不齐就成了大问题。你想找某个功能的规格说明可能要在好几个地方翻找而且格式不统一阅读成本很高。2.3 Superpowers 的技能封装思路Superpowers 的设计理念和前两者都不太一样。它更强调“技能”的概念把常见的开发任务封装成可复用的技能模块每个技能有自己的规格说明、实现模板和验证步骤。你可以把它理解成一套面向规格驱动开发的工具箱里面装了很多预制的“招式”。这套方案在特定场景下非常好用比如你要实现一个标准的 CRUD 接口或者搭建一个常见的项目脚手架直接调用对应的技能模块几分钟就能搞定。但它的局限性也很明显——当你的需求偏离了预制技能的覆盖范围或者需要做一些定制化程度较高的功能时这套工具就帮不上什么忙了。而且技能模块的更新频率如果跟不上技术栈的变化用起来会越来越别扭。2.4 三套方案的核心差异对比为了更直观地展示三套方案的差异我把关键维度整理成了下面这张表对比维度Spec KitOpenSpecSuperpowers核心思路规格即源头严格流程规格活在代码旁灵活约定技能封装预制模块上手难度中等需要理解完整流程低几乎没有学习成本低但需要熟悉技能库流程约束强必须按顺序执行弱全靠团队自觉中等技能内有固定流程定制化能力中等格式固定但内容自由高完全自由低受限于预制技能适合场景需求稳定、周期长的项目小团队、快速迭代标准化程度高的任务主要痛点流程重维护成本高质量参差缺乏约束覆盖面有限更新滞后这张表是我用了两个月之后总结出来的不一定全面但基本反映了三套方案在实际使用中的真实表现。你会发现没有哪一套是完美的每套方案都在灵活性、约束性和维护成本之间做了不同的取舍。3. 实际使用中暴露的关键问题3.1 规格与代码的同步难题不管用哪套工具最核心的问题始终是规格文档和实际代码怎么保持同步这个问题听起来简单做起来极难。我试过三种常见的同步策略每种都有各自的坑。第一种是“先写规格再写代码”这是 Spec Kit 推崇的方式。理论上很美好但实际执行时开发过程中总会遇到各种预料之外的情况代码实现和最初的规格产生偏差。如果每次偏差都回头改规格工作量巨大如果不改规格很快就变成了一纸空文。第二种是“代码写完再补规格”这是很多团队在实际压力下的无奈选择。但事后补的规格往往流于形式写的人不上心看的人也不信任。而且补规格的时间点很难把握写早了代码还没定型写晚了又失去了指导意义。第三种是“规格和代码同时演进”听起来最合理但操作起来对团队的纪律性要求极高。我们试过在每次代码评审时同步检查规格更新坚持了大概三周就坚持不下去了因为评审本身就已经很耗时再加上规格检查效率下降明显。3.2 团队协作中的认知负担另一个容易被忽视的问题是认知负担。Spec Kit 的文件结构比较复杂新成员加入后需要花不少时间理解 spec、plan、tasks 之间的关系。OpenSpec 虽然结构简单但因为缺乏统一格式每个人都要花时间去适应别人写的规格。Superpowers 的技能库虽然好用但记住有哪些技能、每个技能怎么用本身就是一笔不小的认知开销。我观察到一个现象当工具的认知负担超过某个阈值时团队成员会开始绕过它。比如直接在代码注释里写说明而不是去更新规格文档或者在聊天工具里讨论方案而不是去修改 plan 文件。一旦绕过行为成为常态这套工具实际上就已经失效了。3.3 工具链集成的现实困境三套工具在工具链集成方面也各有各的问题。Spec Kit 的命令行工具功能比较完整但和 CI/CD 流程的集成需要不少定制工作。OpenSpec 几乎没有官方工具支持全靠社区贡献的脚本质量参差不齐。Superpowers 的技能模块和主流框架绑定较紧一旦你的技术栈有特殊之处集成起来就很麻烦。我们尝试过把规格检查加入到 CI 流程里比如在合并请求时自动检查规格文件是否更新。但很快就发现这种检查要么太松形同虚设要么太严频繁阻塞正常合并。找到一个合适的平衡点需要反复调整规则而这个调整过程本身就很消耗精力。4. 自己搭一套的完整思路与落地步骤4.1 明确核心需求边界在决定自己搭之前我先花了一周时间梳理团队的真实需求。这个过程很关键因为如果不清楚自己要什么很容易搭出一个四不像的东西。我把需求分成了“必须有”、“最好有”和“不需要”三类。必须有的需求包括规格文件必须和代码放在同一个仓库里用同样的版本控制流程规格格式要足够简单任何人五分钟内能看懂要有一个轻量的检查机制确保规格不会长期不更新新成员能在半天内学会整套流程。最好有的需求包括能和现有的 CI 流程做轻度集成支持多种规格类型功能规格、接口规格、配置规格有一个简单的索引页面方便查找。明确不需要的包括复杂的权限管理、可视化编辑器、自动生成代码、多语言支持。这些功能听起来很美好但对我们这个规模的团队来说投入产出比太低。4.2 目录结构与文件约定设计基于上面的需求我设计了一套非常简单的目录结构。核心思路是每个功能模块一个目录目录里放一个SPEC.md文件格式固定为四个部分——背景、需求、设计、验证。project-root/ ├── specs/ │ ├── user-auth/ │ │ └── SPEC.md │ ├── payment-flow/ │ │ └── SPEC.md │ └── notification/ │ └── SPEC.md ├── src/ └── ...SPEC.md的模板长这样# 功能名称 ## 背景 简要说明这个功能要解决什么问题为什么需要它。 ## 需求 列出具体的功能需求每条需求用一句话描述可验证。 ## 设计 说明技术方案、关键决策和取舍理由。 ## 验证 列出验证方式包括测试用例、手动检查步骤等。这个模板看起来简单得有点过分但正是这种简单让它容易被坚持执行。四个部分分别对应了“为什么做”、“做什么”、“怎么做”和“怎么验证”覆盖了一个功能从构思到落地的完整链路。4.3 轻量检查机制的实现为了保证规格不会长期不更新我写了一个简单的脚本在 CI 流程里做两件事第一检查每个SPEC.md文件的最后修改时间如果超过 90 天没有更新就在合并请求里发一个提醒不阻塞合并第二检查代码目录里是否有新增的功能模块没有对应的SPEC.md文件如果有同样发提醒。这个脚本用 Python 写核心逻辑不到 50 行import os import time from pathlib import Path SPECS_DIR Path(specs) SRC_DIR Path(src) STALE_DAYS 90 def check_stale_specs(): now time.time() for spec_file in SPECS_DIR.rglob(SPEC.md): mtime spec_file.stat().st_mtime days_old (now - mtime) / 86400 if days_old STALE_DAYS: print(f[提醒] {spec_file} 已 {int(days_old)} 天未更新) def check_missing_specs(): for module_dir in SRC_DIR.iterdir(): if module_dir.is_dir(): spec_file SPECS_DIR / module_dir.name / SPEC.md if not spec_file.exists(): print(f[提醒] 模块 {module_dir.name} 缺少规格文件) if __name__ __main__: check_stale_specs() check_missing_specs()这个脚本的定位很明确只提醒不阻塞。因为一旦阻塞合并大家就会想办法绕过它反而适得其反。提醒机制的好处是它把问题暴露出来但不强制立刻解决给团队留出了灵活处理的空间。4.4 与现有工作流的融合方式自己搭的方案要能融入现有工作流而不是另起炉灶。我们的做法是把规格更新纳入到现有的代码评审流程里但不做强制要求。具体来说在合并请求的模板里加了一个检查项“如果本次改动涉及功能变更请确认对应的 SPEC.md 已更新。”这个检查项是勾选框不勾也能提交但评审人会看到。另外我们在每周的例行同步会上花五分钟过一遍上周的规格更新情况。不是逐条检查而是看看有没有明显的遗漏。这种轻量的定期回顾比在每次合并时严格检查要可持续得多。5. 实操过程中的关键细节与避坑经验5.1 规格文件的粒度控制规格文件的粒度是个很容易踩坑的地方。太粗了没有指导意义太细了维护成本高。我的经验是一个SPEC.md对应一个相对独立的功能模块这个模块的代码量大概在几百到一千行左右。如果某个模块的规格文件超过了两千字说明粒度太细了可以考虑拆分如果某个规格文件只有两三句话说明粒度太粗了需要补充细节。还有一个实用技巧在写规格的时候假设读者是一个刚加入团队的新人。如果新人看完这份规格能理解这个功能是做什么的、为什么这么做那粒度就差不多了。如果新人看完还是一头雾水说明要么写得太简略要么用了太多内部术语。5.2 版本变更时的规格处理功能迭代时规格怎么处理这个问题我纠结了很久。最初的方案是每次变更都新建一个规格文件但很快文件就多到没法管理。后来的方案是直接在原文件上修改但这样又丢失了历史记录。最终的方案是主规格文件只保留当前最新状态历史变更记录放在文件末尾的“变更日志”部分。每次修改规格时在变更日志里加一行写明日期、修改人和修改摘要。这样既保持了主文件的简洁又保留了必要的追溯能力。## 变更日志 | 日期 | 修改人 | 摘要 | |------|--------|------| | 2024-03-15 | A同学 | 增加短信验证码登录方式 | | 2024-02-20 | B同学 | 调整密码强度校验规则 |这个变更日志不需要写得很详细一两句话说明改了什么就行。关键是养成习惯每次改规格都顺手加一行。5.3 团队推广的渐进策略自己搭的方案要推广到团队最忌讳的就是一上来就全面铺开。我的做法是先在两个小项目上试点跑了一个月收集反馈调整细节然后再逐步推广到其他项目。推广过程中我特别注意两点第一不强制要求所有人立刻使用而是先让愿意尝试的人用起来用实际效果说话第二定期收集使用中的问题快速迭代改进。比如有同事反馈说模板里的“验证”部分不知道怎么写我就在模板里加了一个示例情况就好多了。5.4 常见问题速查表下面这张表整理了我在实操中遇到的高频问题和解法供你参考问题现象可能原因解决思路规格文件长期不更新缺乏提醒机制或提醒太弱加入 CI 提醒定期回顾规格格式不统一模板不够具体或缺乏示例完善模板提供填写示例新人不看规格规格太抽象或找不到入口在 README 里加链接用通俗语言重写规格和代码脱节变更时忘记同步在合并请求模板里加检查项规格文件太多太散粒度太细合并相关模块控制文件数量这张表我放在团队 wiki 的显眼位置新成员遇到问题时先查表大部分常见问题都能找到方向。6. 自己搭这套方案的实际收益与局限6.1 收益可控、可改、可持续自己搭这套方案最大的好处是可控。因为每一行脚本、每一个模板都是自己写的遇到问题可以立刻改不用等上游更新也不用迁就别人的设计理念。比如我们发现 90 天的提醒周期太长了改成 60 天改一行配置就行。这种灵活性是使用现成工具很难获得的。另一个收益是可持续性。因为方案足够简单不依赖任何外部工具或服务所以不会因为某个工具停止维护而受影响。即使团队人员变动这套方案也能靠文档和模板传承下去。我算过一笔账维护这套方案的时间投入大概每周不到半小时主要是处理一些提醒和偶尔的模板调整成本非常低。6.2 局限功能有限依赖自觉当然这套方案也有明显的局限。它没有自动生成代码的能力没有可视化的规格编辑器也没有复杂的权限管理。这些功能在某些场景下确实有用但对我们这个规模的团队来说投入产出比不高。另一个局限是它高度依赖团队自觉。因为没有强制约束如果团队成员不配合这套方案很容易流于形式。我的应对方式是一方面通过提醒机制保持可见性另一方面通过定期回顾和正面激励比如在周会上表扬规格写得好的同事来维持氛围。说实话这需要持续投入精力不是搭完就一劳永逸的。6.3 什么情况下建议自己搭根据我的经验以下几种情况比较适合自己搭一套轻量方案团队规模在 5 到 20 人之间项目迭代节奏中等不是那种每天都要发版的极端情况团队里有一两个愿意维护工具链的人对规格管理有明确需求但现有工具总觉得不太合身。反过来如果团队规模很小三五个人可能直接用 OpenSpec 这种轻量方案就够了没必要自己搭。如果团队规模很大几十上百人可能需要更重型的企业级方案自己搭的轻量方案可能撑不住。如果项目对合规性要求极高需要完整的审计追踪那还是应该选择功能更完整的商业方案。7. 后续可以继续打磨的方向这套方案目前跑了大概半年整体运行平稳但还有几个地方可以继续打磨。第一个是规格文件的搜索功能现在只能靠目录结构来找如果有一个简单的全文搜索页面会更方便。第二个是规格和测试用例的关联现在验证部分只是文字描述如果能和实际的测试文件建立链接追溯性会更好。第三个是规格模板的多样化目前只有一种通用模板未来可以考虑针对不同类型的模块比如 API 模块、UI 模块、数据模块提供不同的模板。不过这些都是锦上添花的事情不急。我的原则是先保证核心流程稳定运行再考虑优化。毕竟工具是为人服务的如果为了优化工具而增加了使用负担那就本末倒置了。最后分享一个我在实际操作中的小体会规格管理的核心不是工具而是习惯。再好的工具如果团队没有养成写规格、看规格、更新规格的习惯都是白搭。反过来即使工具很简陋只要习惯养成了效果也不会差。所以如果你也在考虑类似的事情我的建议是先把习惯建立起来工具的选择和搭建可以慢慢来。
阅读完成 · 觉得有帮助？
