入门 约 20 分钟 2026-10-15 02:34:40 · 51 阅读

domain-modeling Agent Skill 实操:给项目配一部 AI 能查的词典

同一件事的两种说法,隔着一部词典。「There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)」——二十来个词,描述的是课程视频工具里的一个 bug;换成「There's a problem with the materialization cascade」,两个词说完,意思不变。这段 BEFORE/AFTER 不是编的教学例子,是 mattpocock/skills 仓库 README 里作者拿自己维护的 course-video-manager 项目做的真实对比:第二个句子能成立,是因为词汇表里躺着一条 Materialization Cascade 的定义。domain-modeling 这个 Agent Skill 干的就是这件事——AI 帮你写代码的过程中,把项目里反复出现又说不清楚的概念一个个钉下来写进 GLOSSARY.md,把「当初为什么这么做」的决策记进 docs/adr/,术语敲定的当场就落盘。

相关背景见站内 AI 编程总纲。另一套技能库 superpowers 的姊妹篇(Systematic Debugging、TDD)管调试与测试纪律,本篇的领域建模是同一张拼图的另一块。

为什么值得给 AI 一部词典

README 把这个问题排在代理失败模式的第二位,小标题就叫 The Agent Is Way Too Verbose:项目起步时,开发者与领域专家说的往往不是一种语言,代理被丢进项目里自己猜行话,于是二十个词才说得完一个词的事。作者搬出 Eric Evans《Domain-Driven Design》的原话压阵:

With a ubiquitous language, conversations among developers and expressions of the code are all derived from the same domain model.

通用语言(ubiquitous language)不只省口水。README 的 TIP 框里列了三样副产品:变量、函数、文件按同一套语言命名,代码库因此更好导航;代理思考消耗的 token 更少,因为手里的语言更精炼。这笔投资在每个会话里持续生息。

顺带交代出处:mattpocock/skills 是 Matt Pocock 的代理技能仓库,自述「Skills for Real Engineers. Straight from my .agents directory」,MIT 许可,本轮经 GitHub API 实查约 29.1 万 star(选题入库时快照记的是 282,647,易变数字,以 GitHub 页面为准)。engineering 分类下现有 20 个技能,domain-modeling 是其中之一。

安装:plugin 与 skills.sh 二选一

仓库有两种分发方式,README 特意提醒别都装:plugin 装完会自我更新;skills.sh 路线把可编辑的文件拷进你的项目,更新靠手动重跑。「Pick one per agent, because installing both gives you every skill twice」——两条路都走,每条技能会拿到两份。

Claude Code 用户一行搞定:

claude plugin install mattpocock-skills@claude-plugins-official

Codex 与 GitHub Copilot 走各自的 plugin marketplace(codex plugin marketplace add mattpocock/skills,Copilot 还需在 ~/.copilot/settings.json 里按 README 原文加一段 extraKnownMarketplaces)。Gemini CLI 是手动更新,两条命令分别装 engineering 与 productivity 两个目录:

gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivity

其它代理(cursor、opencode、devin、windsurf、amp、pi)用社区安装器,-a 指定代理名,不带参数会弹出选择界面:

npx skills@latest add mattpocock/skills -a cursor

skills 这个 npm 包本轮实查版本 1.7.2。安装时的技能选择界面里记得把 setup-matt-pocock-skills 勾上,之后更新用 npx skills@latest update。

装完先在每个仓库跑一次 /setup-matt-pocock-skills,每仓库一次即可。它会问三件事:issue 跟踪器用哪家(GitHub、GitLab、本地文件,或者你口头描述的任何东西);triage 时给工单打什么标签;生成的文档放在哪。engineering 类技能都依赖这份配置。

技能约定的文件结构

这个技能不发明新工具,它约定两个落盘位置:术语表和决策记录。结构判定是自动的,规则如下:

单一上下文与多上下文两种文件结构对比

单上下文与多上下文两种文件结构:根目录有无 GLOSSARY-MAP.md 决定走哪边(依据 SKILL.md「File structure」节绘制)

多数仓库只有一个上下文,根目录一个 GLOSSARY.md 加 docs/adr/ 就够。仓库长到 ordering、billing 各自成一派时,根目录放 GLOSSARY-MAP.md 指路,每个上下文养自己的词汇表和决策目录,全系统级别的 ADR 仍留在根部的 docs/adr/。地图文件还带一节 Relationships,用「Ordering → Fulfillment」这样的箭头写清上下文之间靠什么事件通信——GLOSSARY-FORMAT.md 给的示例里,Ordering 发出 OrderPlaced 事件,Fulfillment 消费它开始拣货。

文件一律懒创建,SKILL.md 的原话是「only when you have something to write」:没有 GLOSSARY.md,等第一个术语敲定时再建;没有 docs/adr/,等第一条 ADR 需要时再建。不为了结构而造空文件。

GLOSSARY.md 的词条长什么样

GLOSSARY.md 词条模板、三条规则与真实仓库词条示例

词条模板、三条硬规则,以及作者本人仓库里的真实词条节选

一个词条三段式:规范词、一两句定义、_Avoid_ 禁用清单。真实仓库里长这样(摘自 course-video-manager 的词汇表,README 链接的旧 commit,当时文件还叫 CONTEXT.md):

**Ghost Lesson**: A lesson that exists in the database but not yet on the file system (fsStatus = "ghost"). _Avoid_: Planned lesson, Draft lesson

**Materialize**: The act of transitioning a ghost entity to a real entity by creating its on-disk representation. _Avoid_: Create on disk, Realize

开头那段 BEFORE/AFTER 里的主角也在其中:Materialization Cascade,词条定义是「在 ghost course 里物化一节课时引发的连锁反应」。有了这条定义,二十个词的绕口解释才能换成两个词的黑话——黑话的前提是词典里查得到。

写词条的三条规则来自 GLOSSARY-FORMAT.md。要有主见:同一概念有多个词时,选最好的一个当规范词,其余全部押进 _Avoid_。定义收紧:最多两句,说「是什么」不说「做什么」。门槛要高:超时、错误类型这类通用编程概念不进词汇表,哪怕项目里用得再多——进来的必须是这个上下文独有的概念。

会话中的五个动作

SKILL.md 的 During the session 节规定了 AI 该主动做的事,每条都配了示范话术。你用的术语跟词汇表打架时,它当场指出来:

"Your glossary defines 'cancellation' as X, but you seem to mean Y. Which is it?"

你说得含糊时,它逼你选边:「You're saying 'account': do you mean the Customer or the User? Those are different things.」讨论领域关系时,它编边界场景来试探概念的接缝;你陈述某个机制时,它去翻代码对质——「Your code cancels entire Orders, but you just said partial cancellation is possible. Which is right?」术语一敲定,立刻更新 GLOSSARY.md,不许攒批处理。

有一处边界 SKILL.md 用括号特意划清:只是读 GLOSSARY.md 查词汇,不算这个技能的工作——那是任何技能都能做的一行习惯;domain-modeling 用在改模型的时候,不是消费模型的时候。它也是 model-invoked 技能,不需要打斜杠命令,任务对口时代理自己伸手(README 的 Reference 节对两类技能的分工有专门说明)。

ADR:三个条件全中才落笔

ADR 三问判定表与极简模板

ADR 三问与极简模板:难逆转、没上下文会奇怪、真权衡的结果,缺一个就跳过

决策记录不是日记,技能给了一道三问闸:难逆转(改主意的代价很大)、没上下文会奇怪(未来读者会问当初为什么)、真权衡的结果(存在真实备选项而你为具体理由选了这一个)。三个条件缺任何一个,这条 ADR 就不写。SKILL.md 的措辞是「Offer ADRs sparingly」——克制地提供。

真要写,模板短得反直觉:一个标题加一到三句话,「背景是什么、决定了什么、为什么」。ADR-FORMAT.md 的原话是「An ADR can be a single paragraph. The value is in recording that a decision was made and why, not in filling out sections」——价值在于记下决定过、为什么,不在于填表。Status、Considered Options、Consequences 这些节是可选的,「大多数 ADR 用不上」。编号扫 docs/adr/ 取最大值加一,文件名按 0001-slug.md 递增。

什么题材配得上 ADR,格式文件里给了清单:架构形态(写模型走事件溯源)、上下文间的集成方式(领域事件而非同步 HTTP)、带锁定的技术选型(换起来要一个季度的那种)、边界与归属(客户数据只归 Customer 上下文,别人只存 ID)、对显而易见路径的故意偏离(手写 SQL 不用 ORM,不写下来会有人好心帮你「修」掉)、代码里看不见的约束(合规原因禁用某云)。有一句值得抄在这:「The explicit no-s are as valuable as the yes-s」——显式写明不做什么,和写明做什么一样值钱,不然半年后又有人提议上 GraphQL。

几条如实交代的边界

GLOSSARY.md 必须干净。SKILL.md 原话:「GLOSSARY.md should be totally devoid of implementation details. Do not treat GLOSSARY.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.」它不是规格书、不是草稿本、不是实现决策的仓库,它只是词汇表。实现层面的东西要么进代码注释,要么进 ADR。

仓库哲学上,README 开篇就与 GSD、BMAD、Spec-Kit 那类接管整个流程的方案划清界限:那些方案拿走你的控制权,流程出 bug 时很难排查;这套技能走另一条路——small, easy to adapt, and composable,作者原话是「Hack around with them. Make them your own.」技能文件就在仓库里,鼓励魔改。共享语言的完整工作流还有个用户侧入口 /grill-with-docs(审问式设计会话,内建词汇表构建),domain-modeling 是从中抽出来自动触发的那一半。

本文步骤与图片依据 mattpocock/skills 仓库官方 README、SKILL.md、GLOSSARY-FORMAT.md 与 ADR-FORMAT.md 整理,真实词条引自 github.com/mattpocock/course-video-manager,版权归原作者所有。

评论 (0)