企业官网建设流程全解析

grill-with-docs 实操拆解:设计对齐的同时,把领域文档直接写进仓库

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

准备动手改代码,但计划还模糊、描述事物的词都没定下来时,在仓库里输入/grill-with-docs,Agent 会和你进行多轮设计澄清:期间每敲定一个术语就当场写入CONTEXT.md术语表,每个通过三道门槛的决策就落成一份 ADR。这就是 grill-with-docs 做领域文档沉淀的完整机制。下面从入口、选型、提问节奏、写作纪律到排错逐层拆解,读完你可以直接在自己的仓库里跑起来,并判断它是否工作正常。

入口只是一行委托指令

打开 skills/engineering/grill-with-docs/SKILL.md,正文只有一行:

Call the Skill tool twice, for "grilling" and "domain-modeling".

它自己不含任何逻辑,而是委托给两个更底层的技能:grilling 提供提问机制,即沿设计树逐轮发问;domain-modeling 提供写作机制,即术语辨析与CONTEXT.md、ADR 的落盘纪律。元数据里还声明了disable-model-invocation: true(对应 openai.yaml 中的allow_implicit_invocation: false):该技能只能由你输入/grill-with-docs手动触发,Agent 不会自行伸手去用。

这里有个坑:只装grill-with-docs而不装那两个依赖,你得到的就是一行空壳,后面的排错部分会展开讲。

手边有什么,就选什么技能

先记住一点:grill-with-docs是单会话工具,主战场是"在仓库里、改动开始前、计划尚模糊、词汇未定稿"。具体怎么选,五条判定句:

• 根本不在任何工作目录里 → 用 grill-me;
• 有仓库,且改动能在一次会话内敲定 → 用grill-with-docs;
• 工程大到一次会话装不下(绿地构建、大型功能)→ 用 wayfinder;
• 仓库没有任何领域文档,脑中也没有特定功能 → 还是grill-with-docs,只是目标对准整个仓库而非某次改动;
• 决策卡在别人脑子里的知识上 → 用 to-questionnaire。

grill-with-docs和wayfinder的分界只有一个点:需要几场会话。一次装得下就用前者;要跨多次就用后者——它先把工作拆成问题追踪器上的一张决策票据地图,再逐张解决直到路径清晰。对范围明确的功能动用 wayfinder 属于杀鸡用牛刀,而且它更慢更稠密。两者并非互斥:wayfinder 可以把地图中适合的部分下探回单轮 grilling 会话。

开始前:文件落在哪、何时出现

这个技能会往你的仓库里写文件,所以要先处于一个可以安全写入的位置:

• 术语:已敲定的词进根目录CONTEXT.md术语表;若根目录存在CONTEXT-MAP.md(表明仓库是多功能上下文),则写进对应上下文自己的CONTEXT.md;
• 决策:写进docs/adr/目录。

这些文件全部懒创建——第一个术语或决策结晶之前,什么都不会出现,不需要任何前置脚手架。另外别忘了入口说过的前提:grilling与domain-modeling必须同时在场。

提问节奏:设计树与前沿轮次

提问阶段完全由 grilling 驱动,核心是把澄清过程建模成一棵设计树:每个决策都是一个节点,它的下面挂着一串依赖它的、必须逐一敲定的后续决策。节奏是"发一轮问题 → 等你的回答 → 算出下一轮":

1. 找出前沿(frontier):所有前置条件已经敲定的决策,也就是现在就能发出、不必先猜测未听到答案的问题;
2. 一轮之内把整个前沿问完:每个问题编号,并附上 Agent 自己的推荐答案;
3. 你的回答重塑这棵树:已敲定的决策把前沿向外推,解封依赖它们的问题。某个问题的答案若取决于本轮仍未解答的另一问题,它属于更晚的轮次,而不是本轮。

一轮问题的固定格式:

❓ **Q1** - **<问题标题>**: <问题正文,可以是多段,包含多个选项> ➡️ <你的推荐答案> --- ❓ **Q2** - **<问题标题>**: <问题正文,可以是多段,包含多个选项> ➡️ <你的推荐答案>

两条边界值得注意。一是找事实是 Agent 的活:前沿问题需要环境中的事实(文件系统、工具等)时,它派子代理去查,不会向你索要自己就能查到的东西;也不阻塞等待——进行中的探查只算一个"未敲定的前置条件",只有它下游的问题等回报,前沿其余部分现在就问。二是决定权始终在你手上:每个决策都摆到你面前,然后等。前沿里再无问题可发时,会话结束:设计树每个分支都访问过,没有任何隐藏假设;且在你确认双方对齐之前,它不会基于结果采取任何行动。

写作纪律:会话中的五个动作

澄清一开始,domain-modeling 就同步工作。这是一门主动学科:挑战术语、发明边界用例、在术语与决策结晶的瞬间写下来。(仅仅"读"CONTEXT.md查词不算这个技能,那是一行习惯,任何技能都能做;它适用于你在改变模型,而不只是消费模型。)具体是五个动作:

1. 对照术语表挑战:你用的词和CONTEXT.md既有语言冲突时当场指出——"你的术语表把 'cancellation' 定义为 X,但你似乎指的是 Y";
2. 锐化模糊语言:你用含糊或过载的词时,提议一个精确的规范词——"你说 'account':指的是 Customer 还是 User?这是两个不同的东西";
3. 具体场景压测:讨论领域关系时,编造探测边缘情况的场景,逼你把概念之间的边界说精确;
4. 与代码交叉引用:你描述某事物如何工作时,检查代码是否同意——"你的代码取消了整个 Order,但你刚才说支持部分取消,哪个是对的?";
5. 即时更新CONTEXT.md:术语一敲定就写进文件,绝不攒到结尾批量写。

配套铁律:CONTEXT.md只做术语表——不写实现细节、不写规格、不写草稿笔记。

什么情况要写 ADR:三道门槛与够格清单

技能对 ADR 是"吝啬"的,只有以下三个条件同时成立才提议创建:

1. 难以逆转:日后改变主意的成本很高;
2. 缺乏上下文会令人惊讶:未来读者看到代码会问"他们为什么这么做?";
3. 真实权衡的结果:存在真正可选的方案,你出于具体原因选了一个。

缺一条就跳过。所以大多数决策不配 ADR,大多数会话产出零份 ADR,这都属正常。

落盘纪律由 ADR-FORMAT.md 规定:ADR 存放在docs/adr/,顺序编号0001-slug.md、0002-slug.md依此类推;目录同样懒创建,只在第一份 ADR 需要时建立;编号方法是扫描docs/adr/现存最大编号加一。模板极简:

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

一份 ADR 可以只有一段。它的价值在于留下"这件事被决定了"和"为什么"的标记,而不在于章节填得多满。可选章节只在真正增值时才加:Statusfrontmatter(proposed | accepted | deprecated | superseded by ADR-NNNN,决策会被重新审视时有用)、Considered Options(被否掉的替代方案值得记住时才写)、Consequences(需要点名非显而易见的连锁影响时才写)。

哪些决策够格,官方清单如下:

CONTEXT.md 怎么写:结构、规则与单/多上下文

CONTEXT-FORMAT.md 给出标准结构:

# {上下文名称} {一两句话描述这个上下文是什么、为什么存在。} ## Language **Order**: {对该术语一两句话的描述} _Avoid_: Purchase, transaction **Invoice**: A request for payment sent to a customer after delivery. _Avoid_: Bill, payment request **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account

书写规则四条:要有主见——同一概念有多个词时,选最好的一个,其余列进_Avoid_;定义要紧凑——最多一两句话,写它"是什么"(IS),不写它"做什么"(does);只收本项目上下文专属术语——通用编程概念(超时、错误类型、工具模式)即使项目大量使用也不属于这里,加词前问一句:这是本上下文独有的,还是通用编程概念?自然聚簇时用子标题分组——若所有术语同属一个内聚区域,平铺列表也可以。

单上下文与多上下文仓库:绝大多数仓库是单上下文,根目录一个CONTEXT.md即可;多上下文时,根目录放CONTEXT-MAP.md,列出各上下文的位置与关系,并用Relationships段描述上下文间交互(如 "Ordering emitsOrderPlacedevents; Fulfillment consumes them to start picking

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