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

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架构决策记录留下任何链接痕迹发布之后也不负责保持同步。这不是能力缺失而是刻意划出的边界一份事后记录混入了验证或需求征集的职能就不再可信了。什么时候该轮到它触发标准只有一条构建的规模是否大过单个会话。你正处在什么状态正确动作还没做出任何决定需求仍是雾先跑/grill-with-docs完成决策别碰 to-spec已决定且工作量装得进一个上下文窗口直接/implement不产出 spec已决定且工作横跨多个会话先/to-spec再/to-tickets切片一张 wayfinder 地图已经走完/to-spec #map_issue喂主地图 issue不是零散的决策票最后一行最容易喂错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 anactor, I want afeature, so thatbenefit 的标准句式覆盖特性的所有侧面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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考