教程2026-11-14 · 智涌AI

domain-modeling Skill 怎么用:让 Agent 先统一术语再写码

domain-modeling Skill 教程头图:左侧大字「domain-modeling Skill」与 4 个会话动作、ADR 3 个必备条件、MIT 许可证数据卡;右侧终端面板展示 GLOSSARY.md 中 Order、Customer 术语及 Avoid 同义词

Agent 写的代码能跑,命名却一会儿叫 account、一会儿叫 user,解释一个问题要绕三句话。mattpocock/skills 仓库里有个 domain-modeling Skill,专门治这个:它借用领域驱动设计(DDD)里「通用语言」的做法,在你和 Agent 讨论设计时,逼双方把术语定死,写进仓库根目录的 GLOSSARY.md,难以回退的决定写成 ADR。这篇讲它怎么装、会话里会做哪些事、两份文件该怎么写。

它解决的是「Agent 太啰嗦」

仓库 README 把这个问题列为编程 Agent 的第二大毛病:Agent 被扔进一个项目,只能边干边猜行话,于是一个词能说清的事要用二十个词。作者给的修法是一份共享语言文档,帮 Agent 解码项目里的黑话。README 里的例子出自作者的 course-video-manager 仓库:

没有词汇表有词汇表
当课程某个章节里的一节课被「落地」(也就是在文件系统里分到位置)时出了问题materialization cascade 出了问题

README 列的附带好处有三条:变量、函数、文件按同一套语言命名;代码库对 Agent 更好找;Agent 思考时用词更精炼,token 也省一些。

安装:四种 Agent 各有命令

README 给的安装方式按 Agent 分,插件方式会自动更新,skills.sh 方式把可编辑文件拷进项目、需要手动更新。两种别同时装,否则每个 Skill 会出现两遍。

# Claude Code(插件,自动更新)
claude plugin install mattpocock-skills@claude-plugins-official

# Gemini CLI
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering

# Cursor、OpenCode、Windsurf、Amp 等(可编辑文件,手动更新)
npx skills@latest add mattpocock/skills -a cursor

装完在每个仓库里跑一次 /setup-matt-pocock-skills,它会问你用哪个工单系统、分诊用哪些标签、生成的文档存哪里。用 skills.sh 安装时,记得勾上这个 setup Skill。仓库许可证是 MIT。

会话里它会做的四件事

SKILL.md 强调这是一门「主动」的功夫:你在改领域模型时才用它,单纯读 GLOSSARY.md 查词不算。触发后它会:

  1. 拿词汇表挑刺:你用的词和 GLOSSARY.md 冲突,立刻指出。比如「词汇表里 cancellation 定义的是 X,你现在说的像是 Y,到底是哪个?」
  2. 收紧模糊用词:你说了个含糊或一词多义的词,它提议一个准确的规范词。比如「你说的 account,是 Customer 还是 User?这是两回事。」
  3. 编具体场景追问:讨论概念关系时,它自己编边界情况,逼你说清概念之间的分界。
  4. 对照代码:你描述某个东西怎么工作,它去查代码是否一致。比如「代码里取消的是整个 Order,你刚才说可以部分取消,以哪个为准?」

术语一旦敲定,它当场更新 GLOSSARY.md,不攒到最后。文件按需创建:还没有 GLOSSARY.md,就在第一个术语定下来时建;docs/adr/ 也是第一次需要 ADR 时才建。

GLOSSARY.md 只是词汇表,不是规格说明,也不是草稿本。

GLOSSARY.md 怎么写

格式文件给的模板是:顶部一两句说明这个上下文是什么,下面是 Language 区,每个术语加粗、一两句定义、用 _Avoid_ 列出不该再用的同义词:

# Ordering

接收并跟踪客户订单。

## Language

**Order**:
客户下的一次购买请求。
_Avoid_: Purchase, transaction

**Customer**:
下订单的个人或组织。
_Avoid_: Client, buyer, account

规则四条:观点要鲜明,同一概念多个叫法就挑最好的那个,其余进 _Avoid_;定义写它「是什么」,不写它「做什么」;只收本项目特有的概念,超时、错误类型这类通用编程概念再常用也不收;术语自然成簇时再分小标题。

多个限界上下文的仓库,根目录放一个 GLOSSARY-MAP.md,列出每个上下文的词汇表位置和上下文之间的关系,比如「Ordering 发出 OrderPlaced 事件,Fulfillment 消费它开始拣货」。Skill 会先看有没有这份地图来判断仓库结构;分不清当前话题属于哪个上下文时,它会问你。

ADR:三个条件缺一不写

ADR 放在 docs/adr/,按 0001-slug.md 顺序编号。模板短得出奇:一个标题,加一到三句话说清背景、决定和原因。状态、备选方案、后果这些段落只在确实有用时才加。

什么时候值得写,SKILL.md 和格式文件都给了同一个三条件判断:

条件缺了它为什么不写
难以回退容易改的决定,改主意时直接改就行
没有上下文会让人意外不意外的事,没人会追问为什么
是真实权衡的结果没有备选方案,就没什么可记的

格式文件举的合格例子包括:用 monorepo、写模型用事件溯源、两个上下文之间用领域事件而不是同步 HTTP、带锁定成本的技术选型(数据库、消息总线、认证服务)、「客户数据归 Customer 上下文,其他上下文只按 ID 引用」这类边界决定、故意偏离常规的选择(比如不用 ORM 手写 SQL)、代码里看不出来的约束(合规要求、合作方接口的 200ms 响应限制)。

和 /grill-with-docs 搭配用

grill-with-docs 的 SKILL.md 正文只有一行:依次调用 grilling 和 domain-modeling 两个 Skill。前者是一轮刨根问底的访谈,帮你在动手前把要做的事想清楚,站内 grill-me 教程 讲过;后者在访谈过程中把定下来的术语和决定落到文件里。README 作者的建议是每次要改东西前都跑一遍。

一个可以直接用的开场:

/grill-with-docs
我想给订单加「部分退款」。先别写代码,对照 GLOSSARY.md 和现有代码
问清楚 Refund、Cancellation、Order 之间的关系,术语定下来就更新词汇表;
如果涉及难以回退的设计选择,按三个条件判断要不要写 ADR。

词汇表多了之后,也适合放进 Home Repo 这类多仓库共享的位置,让不同仓库里的 Agent 说同一套话。

常见坑

完成标准

最后

挑你项目里最常被说混的两个词,今天就跑一次 /grill-with-docs,让 Agent 帮你把第一条 GLOSSARY.md 写出来。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。