开发团队的 Spec Skills 工作区搭建指南

我到现在已经给三个不同的开发团队搭过 Spec Skills 工作区，结论是：几乎每次落地的成败都卡在工作区布局上。工具本身没什么问题，真正的产品其实是文件系统。下面这套是我在用的目录结构、会接入的 CI 门禁，以及真正能留下来的按周推进节奏。

模板资源流程实践

发布于 2026-03-10 · ✓ 已更新 2026-05-06 · 阅读约 7 分钟 · 作者：Spec Coding 编辑部 · 审校：编辑与事实核查政策

我反复回到的仓库布局

第一步要决定的是 specs、prompts 和配置到底放在哪里。我以前把它们塞在 wiki 或独立的文档仓库里，这两种做法都不到一个季度就烂掉了。现在我把所有东西都推进应用仓库，这样 spec 就和实现它的代码一起走。三个顶层目录承担了绝大部分工作。

my-service/
├── .spec skills/
│   ├── config.yaml          # 模型、上下文根目录、脱敏规则
│   └── ownership.yaml       # 谁来审批 prompt 版本升级
├── prompts/
│   ├── spec-draft.md        # v2.3 — owner: @platform-eng
│   ├── review-pass.md       # v1.7 — owner: @qa-lead
│   └── CHANGELOG.md
├── specs/
│   ├── README.md            # 如何编写一个 feature 文件夹
│   ├── 2026-03-checkout-v2/
│   │   ├── spec.md
│   │   ├── acceptance-criteria.md
│   │   └── risks.md
│   └── 2026-04-fraud-rules/
│       ├── spec.md
│       ├── acceptance-criteria.md
│       └── risks.md
├── src/
└── tests/

Spec Skills 在这个仓库里的所有行为，都能在这三个目录里看得清清楚楚。我把仓库交给新人，他不用跑一次 CLI，就能看到 spec 契约、prompt 库和工具配置。

/specs 目录内部

每个 feature 都有自己独立的文件夹，命名用日期前缀加一个简短的 slug。我只坚持三个文件，多一个都不要，因为每多一个必填文件，就多一个整体被跳过的理由。spec.md 用朴素的文字描述这个 feature：我们要做什么、我们明确不做什么、谁对这个决策负责。acceptance-criteria.md 放的是 QA 真正会去核对的通过/失败条款。risks.md 列出上线后可能出问题的点，以及发布后谁来盯着仪表盘。

验收标准我用 Given/When/Then 写，因为 Spec Skills 把它当上下文读得很顺，人当 checklist 看也很顺。下面是一个来自真实 checkout feature 的例子：

- Given a logged-in customer with a saved card
  When they submit checkout with a promo code
  Then the promo is applied before tax and the receipt lists both lines

- Given the payment processor returns a 5xx error
  When checkout retries twice and still fails
  Then the order moves to "pending" and the customer sees a retry screen, not an error page

Prompt 库放在哪里、归谁管

我把 prompts 放在 /prompts 里，不放共享 wiki。这是我见过最常犯的搭建错误：团队把 prompt 库丢进 Notion 或 Confluence，因为感觉它像文档，结果六个月后没人知道哪个版本是当前版本。Prompt 就是代码，它需要 diff、需要 PR、需要评审人。

每个 prompt 文件都有一段 front-matter，写明 owner 和当前版本。版本升级必须提 PR，并且至少有一个来自 owner 团队的评审人。我把这一点接进 .spec skills/ownership.yaml，工具会拒绝使用版本号和 ownership 清单对不上的 prompt。仅此一条检查，就挡掉了一半以上的漂移。

真正能抓到问题的 CI 门禁

我在每一个动到业务代码的 PR 上跑三条检查。它们都很小、很快、几乎不会误报——也正因为如此，团队才没把它们撕掉。

拒绝：如果 PR 在 /specs 下新增了一个 feature 文件夹但没有 spec.md，直接 reject。/specs 下没有 spec 文件的新文件夹，一定是错的。
警告：如果 spec 或源码被修改了，但 acceptance-criteria.md 没动过，机器人会发一条评论，问验收标准是不是还成立。有时候答案是“是”，光是这句提问本身就值了。
阻塞：如果 risks.md 存在，但它的“Known risks”标题下没有任何风险条目，就阻塞合并。一个空的 risks 文件比没有这个文件更糟，因为它看起来像做过尽调。

我把这些写进一个 shell 脚本，由 GitHub Actions 调用。总耗时不到四秒。

编辑器集成与访问控制

当 IDE 插件连上以后，Spec Skills 会把 /specs 作为环境上下文读取。在 VSCode 里，我把扩展配置成根据当前分支名的 slug 自动加载对应的 spec 文件夹；我切到 feature/2026-04-fraud-rules，工具就会在我敲下第一条 prompt 之前先把那个 spec 文件夹拉进来。这一点小小的便利，对推广采用的作用比任何一次培训都大。

访问控制分两个地方管。Prompt 库用标准的 GitHub CODEOWNERS，只有指定的评审人才能批准版本升级。.spec skills/config.yaml 只归平台团队所有，因为这个文件一改糊涂，所有开发同时遭殃。/specs 目录对所有人开放；spec 就是团队在思考问题，把它关起来就等于把这件实践扼杀掉。

按周推进的落地节奏

我试过把这个节奏压缩到三天，不 work。四周的节奏给团队留出了足够的空间去养成习惯，又不至于失掉势头。

第 1 周 — 安装。平台团队加上 .spec skills/，把 /specs/README.md 搭起来，把两三个已有的 prompt 迁进 /prompts。这一周还不要求任何人必须使用工具。
第 2 周 — 写第一份 spec。由一位愿意尝试的工程师挑一个真实的、即将开发的 feature，手动把三个文件的文件夹写出来。这一步的目标是发现摩擦点，不是上线。
第 3 周 — 第一个 AI 辅助的 PR。同一位工程师提一个 PR，描述里链接到 spec 文件夹。CI 门禁正式上场。团队一起把这份 diff 读一遍。
第 4 周 — 度量。数一数这一周有多少 PR 链接到了 spec 文件夹，有多少 spec 文件夹是完整的，以及评审人在“这玩意到底要干嘛”这个问题上花了多少时间。把数字公开出来，然后调整。

最常见的搭建错误

反复出现的失败模式，老实说相当一致。Prompts 最终被塞进共享 wiki，然后烂掉。/specs 目录在上线后的一次转向之后就没人再更新，和现实脱节。没人真正管 prompt 库，版本升级悄无声息，同一天同一件事，不同工程师用工具跑出来的结果都不一样。monorepo 有时候想让二十个服务共享同一个 /prompts，对通用 prompt 来说没问题，对领域相关的 prompt 就是灾难；我会按服务路径把它们拆开。polyrepo 则是反过来的问题，那些真正所有服务都要用的 prompt，需要发布成一个共享的包。

新人上手与回退

新工程师入职第一天就会拿到一份 /specs/README.md。它讲清楚三文件结构，展示一个好的示例，并写明谁来回答关于 spec 的问题。这一个文件能替掉大约两个小时的 onboarding 会议。

万一团队想彻底放弃 Spec Skills，回退做起来无聊得恰到好处。删掉 .spec skills/，卸掉 IDE 插件，仓库里所有 spec 和所有 prompt 都还以纯 markdown 的形式躺在那里。Specs 才是资产，工具是可以换的。这一点我希望每一位团队 lead 在第一周开始之前就真正理解。

评审时看什么

这篇文章适合用在搭 Spec Skills 工作区时。别从“原则”聊起，直接拿一条真实改动来对照，看看规格里还缺什么。

目录结构是否能区分输入、输出和审阅记录。
权限是否按任务收窄。
CI 是否检查生成内容和规格是否对应。
团队是否知道失败结果放在哪里复查。

工作区不是文件夹美化。它决定 AI 输出能不能被团队接住。

工作区先管目录，再管工具

团队搭 Spec Skills 工作区时，第一件事不是调模型，而是约定文件放哪。spec、prompt、计划、会话日志和测试证据如果散在聊天窗口里，后面没人能复盘。

Repository layout:
docs/specs/{feature}/spec.md
docs/specs/{feature}/review.md
prompts/{feature}/implementation.md
ai-runs/{date}/{feature}/session.json
tests/evidence/{feature}/commands.txt
.github/pull_request_template.md

边界：不要一开始就把所有团队拉进来。先选一个 API 或后台流程试点，两周内跑通从 ticket 到 spec、从 spec 到 PR、从 PR 到证据的闭环。

工作区权限别等出事再补

我会把 owner 写进目录规则：谁能改 prompt，谁能批准 spec，谁能删除 ai-runs 日志，谁能修改测试证据。工作区不是资料夹，它是审计系统。权限、状态、保留周期和回滚联系人都要在 README 里写清楚。

可复制产物：Spec Skills 工作流包

把这段用于真实的 Spec Skills 运行前。它会把输入、边界和人工评审点放在同一处，避免输出看起来完整但责任不清。

Spec Skills 工作流包：开发团队的 Spec Skills 工作区搭建指南

本次要做的决策：
- 把这篇文章里的工作流应用到一个真实工单，并确认输入、边界、输出和人工评审点。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

工具边界：模型可以起草结构和问题，范围、契约行为、发布风险仍然必须由责任人确认。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。

关键词：Spec Skills 工作区 · /specs 目录 · prompt 库 · CI 门禁 · 开发团队落地

专题阅读路径

这篇文章归入 AI 编码治理主题。先读 Hub，再结合下面的清单、模板或工具落到具体项目里。

继续阅读

编辑说明与免责声明

最近复核：2026-04-28。编辑部检查了示例、内链和可复制评审片段，确保内容更适合真实项目使用。

本文用于软件工程教学与实践参考，不构成法律、税务或投资建议。示例场景用于解释规格方法，不对应真实客户数据。

作者信息：Spec Coding 编辑部
编辑政策：编辑与事实核查政策
联系方式：联系页面