企业官网建设流程全解析

to-spec 拆解：把会消失的对话，变成下一场会话能接手的规格文档

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills

一场会话刚跑完，方案形状已经敲定，上下文窗口（context window）却马上要清空或压缩。不写下来，明天的新会话就会从头再问一遍。to-spec 做的就是这个归档动作：它把刚结束的对话与代码库现状合成一份 spec（规格文档），作为一条 issue 发布进项目的问题追踪器（issue tracker），让后续会话无需重新解释即可接手。

一句话把它钉死

📌 在决策已经做完、对话却即将消失的那一刻，to-spec 把整场对话和代码库现状压缩成一份规格文档，作为一条 issue 落进问题追踪器并打上ready-for-agent标签，交给后续会话直接领取。

它偏不做什么

讲能力之前，先看它拒绝什么。

它拒绝采访。技能正文一开头就把"只综合已知、不再提问"定为硬约束：调用它的时候，决定已经做完了，它的职责是从对话线程和代码库里把决策捞出来，而不是重开一轮问答。spec 是已发生决策的事后记录，不是制造新决策的场所；任何它断言过、实际却没人拍板的东西，都算这份文档的缺陷。

它拒绝被 Agent 主动调用。SKILL.md 头部的disable-model-invocation: true与 agents/openai.yaml 里的allow_implicit_invocation: false双重上锁：模型永远不会自己伸手去拿这个技能，只有人敲下/to-spec它才会动。

它拒绝验证、拒绝搜索、拒绝善后。它不检查追踪器里是否已有重叠的 issue，不对自己尊重的 ADR（架构决策记录）留下任何链接痕迹，发布之后也不负责保持同步。这不是能力缺失，而是刻意划出的边界：一份事后记录混入了验证或需求征集的职能，就不再可信了。

什么时候该轮到它

触发标准只有一条：构建的规模是否大过单个会话。

最后一行最容易喂错：wayfinder 的产出是散在整张地图上的决策，而非交付物，/to-spec正是把它们折叠成一份可构建文档的那一步。把地图直接灌进/implement，丢掉的就是这次折叠。

缺了它哪步会塌

to-spec 能动手的前提，是项目里已经写好"落点"和"词汇"。这两样由/setup-matt-pocock-skills一次性配置。

若没配置，它有一条明确的拦截路径：不猜测追踪器、不往随手目录里写文件，而是直接要求先跑/setup-matt-pocock-skills。缺的东西具体落在三处：

• 落点：追踪器可以是 GitHub（走gh命令行）、GitLab（走glab），或内置的本地 Markdown 约定。本地约定下 issue 与 spec 全部活在.scratch/里，spec 固定在.scratch/<feature-slug>/spec.md，具体路径约定可看 issue-tracker-local.md。
• 分诊词汇：五种标准 triage（分诊）角色——needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。to-spec 发布后自动打的那个标签就在其中。
• 领域词汇：CONTEXT.md与 ADR 目录的读取约定，保证 spec 用项目自己的名词写。

三者缺任何一样，spec 要么落不了地，要么落错地方；下游靠标签语义工作的 to-tickets 与 implement 也就无法识别它的状态。

拆开看它内部那几步

🧵 整个流程能拆成四步递进，前两步都不写正文的一个字。

第一步：勘探代码库，对齐项目词汇

先看代码库现状（已看过则跳过）。从这一步起，spec 全程只允许使用项目的领域术语表——CONTEXT.md 的 Language 一节正是这份词汇表的定义处——并尊重触及区域内的所有 ADR。这一步读的是词汇，不是需求：它不会向用户开新话题。

第二步：先勾勒测试缝，再求确认

动笔之前，先画出这个特性将在哪些 seam（测试缝，即观察行为而不伸手进模块内部的公共边界）上被测试，并把清单摆出来求确认。偏好规则按强度排序：

"Existing seams should be preferred to new ones."

已有的缝优于新建的；取能取到的最高一层；全代码库越少越好——

"The ideal number is one."

必须新建时，也尽量在最高点提出。这一步不是走过场：确认过的 seam 会沿下游传导。tdd 技能只在事先商定的 seam 上写测试，未经确认的缝上一个测试都不写（见 tdd 技能定义）；code-review 之后对照 spec 审 diff，没人同意过的 seam 会在那时被挑出来。在实现里临时决定测试边界，等于绕过协商直接制造审查问题。

第三步：按七节模板写 spec

模板固定七节：

Problem Statement / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope / Further Notes

模板里埋了几条值得细读的工程纪律：

• User Stories 要求极其详尽，逐条采用 "As an<actor>, I want a<feature>, so that<benefit>" 的标准句式，覆盖特性的所有侧面；
• Implementation Decisions 有一条硬红线：禁止具体文件路径与代码片段，理由是路径会比 spec 先过时。唯一例外是原型（prototype）产出的、比散文更能精确编码决策的片段（状态机、reducer、schema、类型形状）——内联进对应决策，注明来源，且只保留决策密集的部分；
• Testing Decisions 必须给出 prior art（先例），即代码库里同类型的既有测试，让后续实现有参照物。

第四步：发布并打标签

spec 写完后发布到已配置的追踪器，随即打上ready-for-agent标签。技能原文解释了这个标签的分量：

"no need for additional triage"

文档已完整到 Agent 可以据此开工。注意它是输入标记而非工作指令——这个区别对某些下游消费者并不可见，坑在后面单列。

上下游交接的是什么

grill-with-docs（做决策）→ to-spec（归档）→ to-tickets（切片）→ implement（构建）→ code-review（审计）

上游交给 to-spec 的是决策：grill-with-docs 负责它不参与的那轮决策环节；wayfinder 走完整张地图时也在这里并入，交接物同样是散在地图上的决策，不是交付物。

下游 to-tickets 把 spec 切成曳光弹（tracer-bullet）式的垂直 ticket——每张票切一条穿过所有层的窄而完整的路径，尺寸按一个全新上下文窗口切分，并声明自己的阻塞边。交接至此从"决策记录"变成"可执行切片"；spec 本体从此不再被编辑，它只是一份快照，真正该活下来的知识应回写进CONTEXT.md与 ADR。

动手前先把这几个坑填了

⚠️ 实战中反复被报告的几个边缘，按"现象、成因、处置"各一句交代清楚。

ready-for-agent 标签被 AFK Agent 误伤

轮询ready-for-agent的 AFK Agent 会一口气构建整份 spec，而不是拾取 ticket 切片。因为对轮询者来说，"输入标记"与"工作指令"没有可见差别。处置：在 AFK Agent 的提示词里显式排除父级 spec，或在/to-tickets跑完后剥掉该标签。

上下文清空前：spec 被 /to-tickets 截断

切片时下游技能读到的 spec 只剩截断版。因为大 spec 超出了追踪器能干净回读的容量，又没有本地副本兜底。处置：在/to-spec与/to-tickets之间不做清空或压缩，同一窗口连着跑，spec 根本不需要被重新拉取。

起草前的查重得自己做

发布的 spec 悄悄与追踪器里已有 issue 重叠。因为起草前它不搜索重叠工作。处置：在活跃区域，跑/to-spec之前先自行搜一遍追踪器。

spec 被读成"太长、太密"

全文完整、密集、引用重，人通读困难。因为它主要写给 Agent 看，且没有摘要模式。处置：人只精读 seams 与 Out of Scope 两处，那是错误决策最便宜被抓住的位置；若 spec 读来令人意外，问题在 grilling 太浅，不在 spec 太长。

重构工作撞上 User Stories 模板

围绕接口与不变量写出的用户故事没人想要。因为模板重 user stories 小节，对架构类工作是错误形状。处置：倚重 implementation-decisions 与 testing-decisions 两节，把持久的架构决策经/grill-with-docs落成 ADR，别硬塞进 spec。

怎么确认它这次没跑偏

✅ 每次跑完，对照五组信号自检：

• 应当看到它从第一句就开始动笔，而不是再抛一轮新问题来"确认需求"；
• 应当看到它动笔前把 seams 摆出来求确认，且提议得尽量少，而不是写完才补一批测试边界求追认；
• 应当看到 spec 里出现项目自己的名词，而不是泛化的产品管理套话；
• 应当能认出其中每个决策都拍板过，而不是有内容为填满某个小节而生造；
• 应当看到 Out of Scope 一节里有真实内容——被拒绝过的东西往往是整页最有用的几行，而不是空着的"无"。

对话会消失，spec 不会。它把这一场会话的决策从上下文窗口里抽出来，钉在追踪器上，等下一场会话来接手。

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills