企业官网建设流程全解析

3 类产出、2 个引擎：grill-with-docs 一次会话搞定设计拷问与领域文档沉淀

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

"Skills for Real Engineers" 是一套面向真实工程实践的 Agent 技能包，其中grill-with-docs用一场逐轮拷问的访谈把你和 Agent 对设计、对术语的理解磨到一致，并当场把术语写进CONTEXT.md术语表、把硬决策写进 ADR 架构决策记录——会话结束，共享语言留在磁盘上。

机制全景

这个技能本身不含任何逻辑：入口文件只有一行委托指令，真正的活由两个底层技能分头完成。

打开 skills/engineering/grill-with-docs/SKILL.md，正文只有一句：

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

也就是说，它是一个编排入口，把职责拆给两个引擎：

整个流程可以压缩成四步：

1. 你手动输入/grill-with-docs。元数据里disable-model-invocation: true（openai.yaml中对应allow_implicit_invocation: false），意味着模型不会自动伸手用这个技能，只能由人触发。
2. 入口把访谈交给grilling，把落盘交给domain-modeling。
3. 访谈引擎按设计树逐轮提问；写作引擎在术语和决策结晶的瞬间就把它们写进仓库。
4. 会话结束，仓库里留下三类东西：CONTEXT.md词条、docs/adr/下的决策记录、以及对话本身。

由于它直接往仓库写文件，且依赖两个外部技能，单独安装只会得到一个"一行字的空壳"——这一点会在后面的故障排查里再出现。

产出物拆解

一次会话最多产出三样东西，而且它们地位并不对等：术语进CONTEXT.md，过三门槛的决策进 ADR，其余一切只留在对话里。

术语表落盘规则

术语在解决的那一刻就地写入，绝不攒到结尾批量落盘。写入位置分两种结构：单上下文仓库写根目录CONTEXT.md；若根目录存在CONTEXT-MAP.md（表示多上下文），则写入对应上下文的CONTEXT.md，由技能自行推断当前话题归属哪个上下文，不确定时会先问你。文件按需懒创建——第一个术语结晶之前，磁盘上什么也不会有。

术语怎么被结晶出来？写作引擎在会话中持续执行五个动作：

注意边界：仅仅为了查词而读CONTEXT.md不算这个技能的用武之地，那是任何技能都能做到的一行习惯；这套纪律只在你改变模型时才生效。同时CONTEXT.md刻意只当术语表——不写实现细节、不写规格、不当草稿纸。共享语言带来的连锁收益是实打实的：变量、函数、文件按同一套词汇命名，代码库对 Agent 更好导航，Agent 也因语言更简练而少花思考 token。

标准格式（见 skills/engineering/domain-modeling/CONTEXT-FORMAT.md）：

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

书写规则四条：

• 要有主见：同一概念多个词时，选最好的一个，其余全部列入_Avoid_；
• 定义要紧凑：最多一两句话，写它"是什么"（IS），不写它"做什么"（does）；
• 只收项目专属术语：通用编程概念（超时、错误类型、工具模式）即使项目大量使用也不属于这里——加词前问一句：这是本上下文独有的概念吗？
• 自然聚簇时分组：术语形成内聚区域就用子标题归类；都属于单一区域时平铺列表也可以。

ADR 三重门槛与编号

决策记录写入docs/adr/，按顺序编号0001-slug.md、0002-slug.md依此类推（扫描现存最大编号加一）；目录同样懒创建，第一份 ADR 需要时才建。技能只在三个条件同时成立时才提议创建：

缺一即跳过，所以大多数决策不够格，大多数会话产出零份 ADR——这是设计而非故障。模板极简（见 skills/engineering/domain-modeling/ADR-FORMAT.md）：

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

一份 ADR 可以只有一段，价值在记录"做了决定"和"为什么"，不在填满小节。可选章节只在真正有价值时加：Status frontmatter（proposed | accepted | deprecated | superseded by ADR-NNNN，决策会被重审时）、Considered Options（被否方案值得记住时）、Consequences（存在不显而易见的连锁影响时）。

够格的具体类别：架构形态（monorepo、事件溯源写模型）；上下文间的集成模式（领域事件而非同步 HTTP）；带来锁定效应的技术选型（换掉要花一个季度的数据库、消息总线、认证提供方）；边界与范围决策（明确的"不做"和"要做"同样值钱）；对显而易见路径的刻意偏离（手写 SQL 不用 ORM，防止下一位工程师"修正"它）；代码里看不见的约束（合规禁用某云、合作方 API 要求 200ms 内响应）；以及被否掉且否掉理由不明显的替代方案（否则六个月后还会有人重提 GraphQL）。

第三类产出：对话本身

其余所有已敲定的内容，落点只有对话上下文。这正是最容易踩的坑：术语表不是规格，大多数回答也挣不到一份 ADR，且没有任何账本把每个已解决的答案一路对应到规格、票据和测试。"术语表变锋利了、ADR 为零"的会话完全符合设计，但它意味着你达成共识的大部分内容只存在于当前上下文窗口里——此时应把整段对话交给to-spec去合成规格，而不是直接清空上下文。

运行节奏

拷问环节的引擎是grilling：访谈被建模成一棵设计树，每个决策都分支出挂靠在它下面的子决策，整个会话就是"逐轮问完前沿、等回答、重算前沿"的循环。

1. 确定前沿。"前沿"指所有前置条件已经敲定的决策——你现在就能问、而不用猜测尚未听到答案的问题集合。
2. 一轮问完整个前沿。给每个问题编号，并附上推荐答案，然后停下等你的回答：

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

3. 回答重塑这棵树。已敲定的决策把前沿向外推，解封依赖它们的新问题；重算前沿后进入下一轮。一个问题的答案依赖本轮仍未解答的另一问题，它属于更晚的轮次，不要在本轮硬问。
4. 查事实是 Agent 的活，不是你的。前沿问题需要环境中的事实（文件系统、工具）时，派子代理去查，绝不把能自己查到的东西抛给你；同时不阻塞等待——进行中的探查算"未敲定的前置条件"，只有依赖它的下游问题要等，前沿其余问题现在就可以先问。但决策权始终在你：每个决策都要摆到你面前，然后等。
5. 前沿为空即结束。每一分支都被访问过，没有任何东西被默默假设。在你确认达成共识之前，Agent 不会基于这次访谈采取任何行动。

判断与选型

选技能只看你手头有什么，而"改动能否在一次会话内敲定"是grill-with-docs与wayfinder的分水岭。

分水岭就是会话次数：/grill-with-docs管单会话规划，/wayfinder管多会话规划。后者先把工作描绘成一张决策票据地图、再逐张解决，更慢更稠密——在一个范围良好的功能上对它过度伸手是常见错误。它并不取代本技能：地图中适合的部分会下探进一次 grilling 会话里。近亲关系上，grill-me是同样的访谈但无仓库无文件，domain-modeling是它所驱动的术语与 ADR 纪律，两者都坐落在grilling原语之上；不确定该用哪个时，交给路由技能ask-matt判断。

🔧 故障排查

问题大多集中在四类，按下表对号入座。

✅ 验证清单

五条全部成立，这次会话就是"工作正常"。

• CONTEXT.md在会话期间逐词增长，而不是结尾一次性冒出来
• 术语表读起来是纯粹的词汇：项目自己的词加紧凑定义，零实现细节、零规格式散文
• 代码库能回答的问题由读代码库回答，而不是拿来问你
• ADR 很少或为零，而得到的那几份都是"不得不重新辩一遍会很烦"的决策
• 它会因为既有术语表对某个词有不同定义，而当场挑战你刚用出的这个词

🔗 上下游与安装

grill-with-docs是主构建链的头部：它先于任何规格存在，产出的是后续环节直接综合所需的共享理解与已敲定词汇，下游谁也不用再访谈你一遍。

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

收尾动作就发生在这条链上：共识达成后，在同一段对话里调用to-spec（它只综合、不再访谈）；改动足够小就直接进implement。上游的wayfinder规划装不进一次会话的工程，并把地图的合适部分下传给它；选型不确定时问ask-matt。顺带一提，社区有个叫grill-domain-model的改名建议一直悬而未决，若落地，文档页会跟着移动。

安装需要保证依赖技能同时在场：

Claude Code：

claude plugins install mattpocock-skills

或在会话内执行/plugin install mattpocock-skills，之后在每个仓库运行一次/setup-matt-pocock-skills完成配置。

Codex 及其他 Agent（或想自己改的玩家）：

npx skills@latest add mattpocock/skills

安装器会让你挑选要装哪些技能——务必确认setup-matt-pocock-skills、grilling与domain-modeling都在其中，否则grill-with-docs就是一行空壳。配置完成后，在仓库内输入/grill-with-docs启动一次"边拷问边落盘"的会话。

打开你手头那个还没开始改动的仓库，输入/grill-with-docs，让设计树在前沿上逐轮长完——前沿为空的那一刻，把整段对话交给to-spec，就是这次对齐的标准收尾动作。

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