企业官网建设流程全解析

grill-with-docs 实战指南：一次会话内完成设计拷问与领域文档沉淀

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

把改动交给 AI 编程助手之前，最常见的翻车不是代码写错，而是你和助手对"要做什么"的理解根本不在一个频道。grill-with-docs 就是为这个问题设计的 Agent 技能：在一次会话里逐轮拷问你的设计，词一敲定就写进 CONTEXT.md 术语表，决策过三关就落成编号的架构决策记录（ADR）。读完本文，你能判断该选哪个拷问技能、把它装对并启用、看懂会话里每轮提问的推进逻辑，并知道会话结束后拿什么去喂下游规格流程。

选对拷问技能：四种处境对应四个出口

选型不看项目大小，看两件事：你在不在仓库里，以及这件事能不能装进一次会话。

grill-with-docs和wayfinder的分界就一条：会话数。装得进一次会话就用前者；硬用后者去规划一个范围良好的功能，是社区里最常见的手滑——它更慢、更重，为多会话工程而生。

安装前的三项依赖检查：缺一个就是空壳

这个技能最反直觉的一点是：入口文件正文只有一行英文指令。打开 SKILL.md，正文就是"把 Skill 工具分别调用 grilling 和 domain-modeling 各一次"——它自己不实现任何逻辑，访谈节奏全部委托给grilling，落盘纪律全部委托给 domain-modeling。所以第一项检查是：两个依赖技能必须同时在场，缺任何一个是"装上了但跑不动"。

第二项：这个技能被声明为仅手动触发（元数据里的disable-model-invocation: true，对应各 Agent 配置里的allow_implicit_invocation: false）。Agent 永远不会自己伸手去用它，你必须亲自输入/grill-with-docs。

第三项：装全三件套。两条安装路径：

# Claude Code claude plugins install mattpocock-skills # Codex 及其他 Agent npx skills@latest add mattpocock/skills

Claude Code 装完后，在每个仓库里执行一次/setup-matt-pocock-skills（它会问清你用哪个 issue 跟踪器、triage 用什么标签、文档存哪里）。走npx这条路的，安装器会让你勾选要装哪些技能——务必确认setup-matt-pocock-skills、grilling、domain-modeling三项都在勾选列表里，否则主技能只是一行没人接力的空指令。

访谈推进机制：设计树的前沿如何逐轮生长

进入会话后，你会看到提问不是撒网式的一次问完，而是一轮一轮推。技能把你的设计建模成一棵树：每个决策都分支出若干挂在它下面的子决策。它把"所有前置条件都已敲定的决策"称为前沿——也就是现在就能问、不必猜测未听到答案的问题集合。每一轮，整条前沿一次问完：问题编号，每个问题附一个推荐答案，然后停下等你的回答。

你的回答会重塑这棵树：敲定的决策把前沿往外推，解封那些依赖它的问题；某个问题的答案若依赖本轮仍未解决的另一问题，它就被推迟到更晚的轮次，不会提前抛出。还有两条纪律值得留意：查事实是它的活，不是你的——前沿问题需要环境事实时（文件内容、现有行为等），它派子代理去查，绝不向你伸手要任何自己能查到的东西，且不等探查返回就阻塞整轮，只有下游问题在等，前沿其余部分照常问；但决策权始终在你，每个决策都要摆到你面前然后等待。当前沿清空，会话结束：每条分支都访问过，没有东西被默默假设。你确认达成共识之前，它不会基于此采取任何行动。

术语当场落盘的五个动作：术语表的形成纪律

访谈进行的同时，第二台引擎在并行运转，它做的是主动的领域建模：你每说出一个词，它就找机会把它磨成术语表里的一条。五个动作会交替出现。

1. 对照术语表挑战：你用的词和 CONTEXT.md 里的既有定义冲突时，它当场指出——"术语表把 cancellation 定义为 X，但你刚才说的像是 Y，到底指哪个？"
2. 锐化模糊词：你说"account"，它会追问指 Customer 还是 User，这两个是不同的东西，不能共用一个词。
3. 造场景压测：讨论概念间的关系时，它编造边界场景逼你把概念边界说精确，而不是停在"大致上"。
4. 和代码交叉验证：你描述某事如何工作时，它去查代码是否同意；矛盾会被浮出来——"代码里取消的是整个 Order，但你刚说支持部分取消，哪个对？"
5. 当场写入：术语一敲定，立刻落进 CONTEXT.md，绝不攒到结尾批量补。

术语表只当术语表用：不写实现细节、不写规格、不当草稿纸。格式规范见 CONTEXT-FORMAT.md，标准结构如下：

# {上下文名称} {一两句话：这个上下文是什么、为什么存在。} ## Language **Order**: {对术语的一两句话描述} _Avoid_: Purchase, transaction **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account

书写规则：同一概念有多个叫法时选最好的一个，其余丢进_Avoid_；定义一两句话，写它"是什么"而非"做什么"；只收项目专属术语，通用编程概念（超时、错误类型）不配入表；术语自然聚簇时用子标题分组。

落盘位置还有一层推断：根目录存在CONTEXT-MAP.md说明是多上下文仓库，术语写进当前主题所属上下文的 CONTEXT.md（推断不出就问你）；只有根 CONTEXT.md 则是单上下文；两者皆无，就在第一个术语解决时懒创建根文件——在此之前，什么都不会凭空出现。

三道门槛：什么样的决策才配一份 ADR

决策的待遇比术语苛刻得多：一次会话里你拍板的多数决定，不值得留下任何文件。技能只在三个条件同时成立时才提议创建 ADR：

1. 难以逆转：日后改主意的代价可观，比如换数据库、换消息总线这类要花一个季度迁走的选型；
2. 缺上下文会令人惊讶：未来的读者看着代码会问"为什么偏偏这么做"；
3. 真实的权衡：确实存在竞争方案，你比较后出于具体理由选了其中一个。

缺一即跳过。够格的典型题材：架构形态（monorepo、写模型事件溯源）；上下文之间的集成模式（领域事件而非同步 HTTP）；边界与范围决策（Customer 数据归谁所有、别处只按 ID 引用）；对显而易见路径的刻意偏离（手写 SQL 不用 ORM，记下原因，免得下一个人去"修正"它）；代码里看不见的约束（合规禁用某云、合作方契约限定响应时间）；被否掉的替代方案且否得并不显然——不然六个月后总有人再提 GraphQL 一遍。

落盘在docs/adr/，顺序编号：扫描现存最大编号加一，0001-slug.md、0002-slug.md依此类推，目录本身也是懒创建。模板极简，一份 ADR 可以只有一段：

# {决策的短标题} {1-3 句话：背景是什么、决定了什么、为什么。}

Status frontmatter、Considered Options、Consequences 这类章节只在真正增值时才加。所以"术语表变锋利了、ADR 一份没出"的会话不是失败，是符合设计的常态。

会话结束后的三种去向：你的其他决策在哪

一次会话结束，能留在磁盘上的只有三样东西，而且地位并不平等：

第三行是最容易踩的坑。CONTEXT.md 是术语表，不是规格；那些精确的答案——顺序保证、否定性需求、数值默认值——大多挣不到 ADR，于是只活在共识达成的那个上下文窗口里。正确的接法是：不要清空上下文，把整段对话原样交给 to-spec 去合成规格；规格生成后，拿你自己的原始回答逐条回读核对——下游可能把你的精确答案弱化成含糊散文，看起来完整、其实丢掉了你真正拍板的东西。

这正是它在构建链里所处的头部位置：

grill-with-docs → to-spec → to-tickets → implement → code-review

它先于任何规格存在，产出的是to-spec直接可用、无需再访谈你的共享理解与已敲定词汇。若改动小到可以立刻动手，也可以跳过规格直奔implement。

两个"跑完却没发生什么"的排障路径

这个技能的故障形态不是报错，而是"看起来结束了，但什么都没发生"。

⚠️坑一：会话跑完，仓库里没有 CONTEXT.md 也没有 ADR。两个成因。无害的那个：无物可写——本次改动没有产生新词汇、也没有决策过门槛，本来就不该出现任何文件。真正的问题：当技能嵌套在另一层编排里运行（规格驱动开发包装器、多 Agent 框架、别人流水线里的一步）时，写文件那一半会被静默吞掉，访谈却照常进行。如果你处于这种配置，先检查实际工作目录的状态，再决定是否信任会话的输出。

坑二：问题一次性全部倾倒、没有任何推荐答案、也从不提 CONTEXT.md。这是两个依赖技能没被完整加载的信号。正文只是一行委托，找不到grilling和domain-modeling的 Agent 只能猜"grilling"是什么意思，产出就是一通无差别提问。更迷惑的是部分加载：grilling在了、domain-modeling不在，你得到一场体面的访谈，却没有一行纸面记录。该现象与模型和 effort 级别相关，是这个技能被报告最多的问题。怀疑时，直接问 Agent 它加载了哪些技能。

自检：五个"它在正常工作"的信号

下次会话结束后，对照这五条确认它真的在按设计运转：

• CONTEXT.md 在会话期间逐词变化，而不是结尾一次性冒出来；
• 术语表读起来是纯粹的词汇——项目自己的词加紧凑定义，没有任何实现细节或规格式散文；
• 代码库能回答的问题由读代码回答，没有被拿来问你；
• ADR 很少（甚至为零），而留下的每一份，都是你不想重辩一遍的决策；
• 它会因为既有术语表对某个词有不同定义，而当场挑战你刚说出口的用词。

五条都中，你就可以放心地把这段对话交给to-spec，进入构建链的下一环。

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