不是框架，是一箱可以拆开改造的工具。37 个技能只做一件事：把软件工程的基本功，压缩成智能体每次都能重复执行的动作。本图集以 mattpocock/skills 为蓝本、course-video-manager 为实战证据，讲清每个阶段做什么、输入什么、输出什么、为什么。
GSD、BMAD、Spec-Kit 试图接管开发过程，代价是你失去控制权，流程出了 bug 也难修。这套技能反其道而行：小、易改、可组合。四个最常见的失败模式，每个对应一组修复技能。看懂这张映射，就看懂了每个环节为什么存在。
"没人确切知道自己想要什么。"对齐失败，看到产出才发现理解错了，而鸿沟最大的成本在实现之后才暴露。
修复：grill-with-docs · grill-me
一轮轮追问，把模糊想法逼成清晰设计，发现点前移到第一行代码之前。
智能体被扔进项目自己猜行话，20 个词说 1 个词的事，命名不一致，代码库难导航。
修复：domain-modeling · writing-for-agents
把共享语言物化成 GLOSSARY 词汇表 + ADR，让每个后续会话持续受益。
没有反馈就没有纠偏，智能体在盲飞。"反馈速率就是你的速度上限。"
修复：tdd · diagnosing-bugs
红绿循环给智能体恒定反馈信号；调试先造"红命令"，再谈假设。
智能体写码太快，软件熵也加速积累。"最好的模块是深的：简单接口后面藏大量功能。"
修复：codebase-design · to-spec · improve-codebase-architecture
先问模块再写规格，深模块词汇，定期巡检深化候选。
主流程六个环节串联；原型是环节 1 到 3 之间的可选分支；三条汇入通道处理"不从想法开始"的工作；词汇层垫在最底下，代码库健康巡检在顶上闭环。
改一张规格远比改一堆代码便宜。对齐失败的发现点必须前移到写码之前，所以环节 1 成本最高、最该每次都用。
实现者是没有会话记忆的智能体。票 + 规格是它重建上下文的全部材料，所以环节 5 每票冷启动、结束即弃，多会话并行抓"前沿"上的票。
雾还没散时假装能写规格是谎言。wayfinder 只产决策不产代码，把不可知留在雾里，雾散到哪票才具体化到哪。
六张卡片对应主流程。每张只留骨架：左边是谁在做，中间是物质如何流转，右边是存在的理由。
一个还没配置过的仓库：git remote、已有 AGENTS.md / CLAUDE.md、是否 monorepo
每仓库跑一次，确认三件事：问题追踪器用哪个、分诊标签叫什么、领域文档放哪。先探索、再确认、后写入，绝不覆盖已有编辑
docs/agents/*.md 约定文件 + AGENTS.md 里的 Agent skills 块
后面所有编排技能都要回答"票发哪、标签叫什么、词汇表在哪"。把答案物化成文件，是整套体系能跨会话运转的前提
一个模糊想法 + 仓库现状（需要事实时派子智能体去查，不拿来烦你）
把想法画成设计树，按"前沿"逐轮提问：每轮把前置已定的问题一次全问出，每题附推荐答案。结束前不动手，直到你确认共识
共识 + GLOSSARY.md 当场新增术语 + 满足三条件的 docs/adr/ 决策档
对齐失败的根源是沟通鸿沟，最大成本在实现后暴露。"前沿 + 轮次"保证你永不被问前提未定的问题；推荐答案把访谈成本压到回一个"同意"
拷问中对话无法裁决的问题：状态机对不对、UI 该长什么样
逻辑问题 → 单个可玩 HTML；UI 问题 → 同路由若干 radically different 变体。铁律：第一天就是一次性的、一条命令能跑、不持久化、不抛光
一个决策（不是代码）：折进真实代码；原型留在 prototype/<name> 分支作一手证据
"一次性"是约束写法：不必维护，所以敢半天试三种方案。handoff 双向桥让分支不污染主对话；规格模板专门留例外条款收纳原型产出的状态机片段
同一窗口里已讨论清楚的一切（不再访谈，职责分离防震荡）
先定测试接缝并与你确认（越少越好，理想是一个），再按六段模板合成：问题 → 方案 → 超长用户故事清单 → 实现决策 → 测试决策 → 范围外
发布到追踪器、打 ready-for-agent 的规格文档（禁写文件路径与代码片段，原型决策密集片段除外）
实现者没有记忆，故事清单是它重建"功能服务谁"的唯一材料。禁路径因为 AI 时代文档半衰期极短：规格只承载决策，不承载定位
已发布的规格
切成曳光弹垂直切片：窄但穿全层、完成即可演示、大小正好装进一个新上下文。每票声明阻塞边。先给你过目粒度，批准后才发布
按依赖序编号的票（本地模式一票一文件），宽重构走 expand-contract 批次
水平切片每步不可演示，错误最后才暴露；垂直切片让每张票都是一次曳光弹试射。阻塞边让追踪器直接渲染"现在能拿哪些票"，并行成为可能
一张自包含的票（+ 规格 + GLOSSARY，动手前读词汇对齐命名）
在预约定接缝上红→绿：先失败测试，再最小实现；一次一片；定期类型检查与单测，最后全量。指令刻意极简，这是特性
绿测试 + 提交到当前分支；会话结束 /clear，上下文可丢弃
TDD 对智能体比对人更关键：红绿是它唯一的恒定反馈信号，不再盲飞。"接缝预先确认"让有限的测试落在关键路径而非摊薄到每个边缘
git diff 固定点...HEAD + 来源规格
Standards 轴（仓库规范 + 12 条坏味道基线）与 Spec 轴（缺失 / 越界 / 错实现）各派一个并行子智能体，互不污染
两节并列的报告：不合并、不重排序，各轴给出最严重问题
一个变更可能一轴过另一轴挂。混评时 Spec 的发现会被 Standards 的细节淹没；"不重排"防止聚合层替你决定哪轴更重要，那是人的判断
输入：堆积的 issue 与外部 PR。操作：复现验证声称 → 五态状态机分诊 → 拷问补全，先查重复实现与 .out-of-scope 拒绝档案。输出：附 agent brief 的 ready-for-agent 票。它产出的票不要再分诊。
输入：疑难 bug。操作：六阶段纪律环，核心是阶段 1 造反馈回路（十种手段，验收为红 capable、秒级、可无人值守的命令）；没有红命令禁止进入假设阶段。输出：修复 + 写在正确接缝上的回归测试。
输入：一个会话装不下的巨型雾团。操作：先拷问出目的地，再铺开四类决策票（research / prototype / grilling / task），雾散到哪票才具体化到哪；认领防撞，一次一票。输出：地图收口后移交 to-spec，不直接跳实现。
拷问的前沿推进、TDD 的红绿信号、评审的双轴隔离。这三个机制分别是失败模式 #1、#3 与评审可信度的解。
LLM 的物理约束决定了流程形状：约 150k token 以内模型推理敏锐，超过就开始劣化（smart zone）。两条规则由此派生，前面全景图里的两个虚线框就是它。
course-video-manager 是 Matt 用这套技能开发的真实应用（课程视频 authoring 与发布系统）。三个证据：词汇表、编排技能、可执行验证。
BEFORE："课程章节里的课被'实化'时出问题"（20 个词）
AFTER："materialization cascade 出问题"（4 个词）
GLOSSARY.md 653 行，每个术语带精确定义 + Avoid 禁词表（CourseVersion 禁用 Version、Revision）；docs/adr/ 下 50+ 份 ADR。每个术语都是一次拷问的产物。
项目自己的 .claude/skills/do-work 就是 implement 的同款形状：Phase 1 探索计划 → Phase 2 实现（按 DB-TDD / FRONTEND-TDD 分流，正是"模型调用承载纪律"）→ Phase 3 反馈回路（typecheck → test 顺序执行，失败不许前进）→ Phase 4 提交。
7 个项目级技能（verify-cvm、to-prd-project、optimize-loader）全部是"仓库自己的词汇"，不是通用模板。
verify-cvm 技能带 10 个可执行验证脚本（verify.sh / verify-db / verify-guard / verify-ledger / verify-clones...），把"系统确实工作"变成一条命令；tests/ 下有 effect-guards、complexity-guard、is-filming 等守卫测试，防止熵倒退。
反馈回路不靠自觉，靠脚本和红测试常驻。这正是失败模式 #3 的工程化解法。
编排薄、纪律厚。用户调用技能只做路由串联，可复用方法论下沉为模型调用技能；用户调用永不让渡方向盘。
产物物化。共识、语言、决策、任务全部落成文件（票、规格、GLOSSARY、ADR），跨会话不丢失，上下文因此可丢弃。
反馈回路优先。测试先行、红绿循环、调试先造红命令，让智能体永远不在盲区里飞。反馈速率就是速度上限。
| 时机 | 动作 |
|---|---|
| 每仓库一次 | 装技能 → 跑 /setup-matt-pocock-skills → 确认追踪器、标签、文档布局约定生效 |
| 每个新想法 | 先 /grill-with-docs 到前沿为空 → 对话裁决不了就原型分支 → 同窗口 /to-spec（接缝先行）→ /to-tickets 批准粒度后才发布 → 每票 /implement 结束即 /clear → 提交前 /code-review |
| 日常 | 外部堆积走 /triage；疑难 bug 走 /diagnosing-bugs（先红命令后假设）；每隔几天 /improve-codebase-architecture 巡检 |
| 反模式自查 | 别让智能体拷问未完就动手；别分诊 to-tickets 的票；别在规格里写文件路径；别写同义反复测试；别从 wayfinder 直接跳实现；别把 GLOSSARY 当便签 |