The /domain-modeling Skill/domain-modeling 技能

What it does功能说明

domain-modeling builds and sharpens a project's ubiquitous language while you are designing: challenging a term that conflicts with the glossary, forcing a precise word where you used a vague one, and stress-testing a relationship with a concrete scenario until the boundaries are exact.domain-modeling 会在你进行设计时构建并精炼项目的通用语言：它会质疑与术语表冲突的词汇，在你使用模糊表达时强制要求使用精确词汇，并利用具体场景对关系进行压力测试，直到边界变得精确为止。

It is the active discipline, not the passive one. Reading GLOSSARY.md to borrow its vocabulary is a one-line habit any skill can do; this skill is for when you are changing the model. That is what makes it interrupt. It writes a resolved term into GLOSSARY.md at the moment it is resolved, in the middle of the conversation, rather than producing a tidy glossary at the end, because the batched version is a summary of a session, and the inline version is the session's actual output.这是一种主动式而非被动式的规范。阅读 GLOSSARY.md 来借用词汇是任何技能都能做到的简单习惯；而此技能适用于你正在修改模型的时候。这就是它会进行干预的原因。它会在术语确定的那一刻（即对话进行中）将其写入 GLOSSARY.md，而不是在最后才生成一份整洁的词汇表，因为批量生成的版本只是会话的总结，而内联版本才是会话的实际产出。

When to reach for it何时使用

Type /domain-modeling, or the agent reaches for it automatically when a task fits. In practice, automatic invocation is the weakest part of the skill: when grill-with-docs or wayfinder say to load it, models frequently load grilling and skip this one. If a grilling session runs and GLOSSARY.md is untouched at the end, that is what happened; invoke it by name alongside the other skill.输入 /domain-modeling，或者当任务匹配时，代理会自动调用它。在实践中，自动调用是该技能最薄弱的部分：当 grill-with-docs 或 wayfinder 建议加载它时，模型往往会优先加载 grilling 而跳过此项。如果 grilling 会话运行结束时 GLOSSARY.md 仍未被触动，说明就是这种情况；请在调用其他技能时通过名称显式调用它。

Reach for it when the words are the problem:当词汇本身成为问题时，请使用它：

Prerequisites先决条件

None up front. The skill writes into two places and creates both lazily:预先无需任何条件。该技能会向两个位置写入内容，并以惰性方式创建它们：

• GLOSSARY.md at the repo root, created by the first resolved term. In a repo with a GLOSSARY-MAP.md at the root, terms go into the per-context GLOSSARY.md the map points at instead.仓库根目录下的 GLOSSARY.md，由第一个确定的术语创建。如果仓库根目录下存在 GLOSSARY-MAP.md，术语则会被写入映射所指向的特定上下文 GLOSSARY.md 中。
• docs/adr/, created by the first ADR that clears the bar.docs/adr/，由第一个达标的 ADR 创建。

Nothing needs to exist before you start, and nothing is created speculatively.在你开始之前无需存在任何内容，也不会预先创建任何内容。

Two artifacts, two bars两个工件，两个标准

The glossary and the ADR are held to different standards, and conflating them is where most of the trouble in this skill comes from.词汇表和 ADR 遵循不同的标准，将它们混为一谈是该技能产生大部分麻烦的原因。

Miss any one of the ADR's three tests and there is no ADR. An easily-reversed decision will just get reversed; an unsurprising one is nobody's question; one with no real alternative records that you did the obvious thing.如果 ADR 的三项测试中任何一项不达标，就不会生成 ADR。一个容易撤销的决策会被直接撤销；一个不出人意料的决策无需讨论；一个没有真正替代方案的决策则会记录下你采取了显而易见的做法。

The GLOSSARY.md rule is the one to actually hold onto, because it is the one that breaks in the field. It is a glossary and nothing else. Left unchecked, models treat "write to GLOSSARY.md" as permission to persist every answer you give, and the file turns into a running spec. This is the most-reported problem with the skill, across several models.GLOSSARY.md 的规则是真正需要坚持的，因为它在实际应用中容易失效。它就是一个词汇表，仅此而已。如果不加约束，模型会将“写入 GLOSSARY.md”视为可以持久化你给出的每一个答案的许可，从而导致文件变成一份不断更新的规范。这是该技能在多个模型中被反馈最多的问题。

Cross-referencing, and where it stops交叉引用及其局限性

The move that makes the skill click: when you state how something works, it checks the code and surfaces the contradiction. "Your code cancels entire Orders, but you just said partial cancellation is possible, which is right?" The language and the code are made to agree, out loud, before either is changed.让该技能生效的关键操作：当你陈述某事的工作原理时，它会检查代码并浮现出矛盾之处。“你的代码取消了整个订单，但你刚才说可以部分取消，哪个是对的？”在修改任何一方之前，语言和代码必须先明确达成一致。

The limit is worth knowing. It cross-references code and the committed GLOSSARY.md/ADRs, and nothing else. It does not search your issue tracker, so a naming collision that was argued out and deliberately settled in a closed issue months ago gets surfaced as if it were new. There is an open request to fix this; until then, the workaround is to put the instruction in your own docs/agents/domain.md, which the skills already read.了解其局限性很有必要。它仅对代码和已提交的 GLOSSARY.md/ADR 进行交叉引用，除此之外不涉及其他内容。它不会搜索你的问题追踪系统，因此几个月前在已关闭的问题中经过争论并达成共识的命名冲突，会被当作新问题提出来。目前有一个修复此问题的待处理请求；在此之前，变通方法是将指令放在你自己的 docs/agents/domain.md 中，技能已经会读取该文件。

Common questions常见问题

My GLOSSARY.md is 500 lines. 1,000. 3,000. What do I do? The size is a symptom, not the disease: the file has absorbed implementation detail and decisions that were never glossary material. The fix is a direct instruction: /grill-with-docs make my GLOSSARY.md more concise and remove any implementation details from it. Run it against a bloated file and most of it goes. Only reach for a GLOSSARY-MAP.md split once the file is genuinely lean and still covers two domains that a reader would not want to hold at once; splitting a bloated file just gives you several bloated files. The skill's guidance here is not yet strong enough to prevent the growth in the first place, and the issue tracking that is still open.我的 GLOSSARY.md 有 500 行、1000 行甚至 3000 行。我该怎么办？ 文件大小是症状而非病因：该文件吸收了实现细节和从未属于词汇表范畴的决策。解决方法是直接下达指令：/grill-with-docs 让我的 GLOSSARY.md 更简洁并从中删除所有实现细节。对臃肿的文件运行此命令，大部分内容就会被清理掉。只有当文件确实精简，且涵盖了读者不希望同时处理的两个领域时，才考虑使用 GLOSSARY-MAP.md 进行拆分；拆分一个臃肿的文件只会让你得到多个臃肿的文件。该技能在此处的引导能力尚不足以从源头防止膨胀，相关问题追踪仍在处理中。

Why is it GLOSSARY.md and not GLOSSARY.md? This is the most-argued naming question in the whole skill set and it has no settled answer. The case against the current name is good: if it is "a glossary and nothing else", GLOSSARY.md says so, and, as one reader put it, "with ai agents everything is context". The case for it is the map: GLOSSARY-MAP.md pointing at several GLOSSARY.md files reads naturally in a way GLOSSARY-MAP.md does not, and context is the standing DDD word for a bounded area of the model. At least one person maintains a local fork purely to rename the file. You can do the same, but every other skill in the set looks for GLOSSARY.md, so a rename means patching all of them.为什么是 GLOSSARY.md 而不是其他名称？ 这是整个技能集中争论最多的命名问题，且没有定论。反对当前名称的理由很充分：如果它是“一个词汇表，仅此而已”，GLOSSARY.md 确实说明了这一点，而且正如一位读者所言，“在 AI 代理中，一切皆上下文”。支持它的理由是映射：GLOSSARY-MAP.md 指向多个 GLOSSARY.md 文件读起来很自然，而其他名称则不然，且“上下文”（context）是 DDD 中用于描述模型有界区域的标准词汇。至少有一个人为了重命名该文件而维护了一个本地分支。你可以这样做，但集合中的所有其他技能都在寻找 GLOSSARY.md，因此重命名意味着要修补所有这些技能。

Where did /ubiquitous-language go? It was removed, and it was not deprecated. Its job moved into domain-modeling, which maintains the whole model continuously rather than dumping a glossary out of one conversation. Vocabulary enforcement got more load-bearing, not less: it now runs underneath grilling, triage and mapping rather than as a separate pass you remember to do./ubiquitous-language 去哪了？ 它已被移除，并非弃用。它的功能转移到了 domain-modeling 中，该技能持续维护整个模型，而不是从一次对话中导出一份词汇表。词汇强制执行变得更加重要，而非相反：它现在运行在 grilling、triage 和 mapping 的底层，而不是作为你需要记住去执行的单独步骤。

How do I get a glossary for a codebase that has none? Ask for it explicitly rather than waiting for it to accumulate. /grill-with-docs help me scaffold my existing repo with a GLOSSARY.md is the documented route; expect a long interrogation: one user reported 50+ questions before the file was in shape. Incidental use builds the glossary far too slowly on a brownfield repo.我如何为没有词汇表的代码库获取词汇表？ 直接要求它，而不是等待它慢慢积累。/grill-with-docs 帮助我用 GLOSSARY.md 构建现有仓库是记录在案的路径；准备好迎接长时间的盘问：一位用户报告在文件成型前经历了 50 多个问题。在遗留系统（brownfield repo）上，附带使用构建词汇表的速度太慢了。

Can I keep the domain model and use my own ADR format? Not cleanly today. The glossary half and the ADR half ship in one skill, so a team with an established ADR convention (different template, different location, different naming) gets instructions that conflict with its house style. The current options are to copy the skill locally and edit it, or to override the ADR conventions in your repo's own agent docs. Splitting the two apart is an open request.我能保留领域模型并使用我自己的 ADR 格式吗？ 目前还不能完美实现。词汇表部分和 ADR 部分封装在一个技能中，因此拥有既定 ADR 规范（不同的模板、位置、命名）的团队会收到与内部风格冲突的指令。目前的选项是本地复制并编辑该技能，或者在你的仓库代理文档中覆盖 ADR 规范。将两者拆分开来是一个待处理的请求。

Does a glossary actually earn its keep? It is one more artifact to review, and it can go stale. Sometimes it does not, and it is worth being honest about where. DDD gets less useful the closer it gets to the implementation: the payoff is upstream, in naming and concept alignment, not in aggregates and layer ceremony. Synonym control matters at naming boundaries: module names, table names, status enums, issue titles, CLI commands. It matters much less in ordinary prose. There is also a live objection that domain terms compress communication between humans who already share them, and that an agent responds the same way to the plain-English description. On that reading, the glossary's value is keeping you and your reviewers aligned with what the agent is doing, not making the agent better. On a one-day build, skip it. And an unreviewed, agent-authored glossary is worse than none: it becomes confident-sounding lore that later sessions treat as truth.词汇表真的物有所值吗？它又多了一个需要审查的工件，而且可能会过时。 有时确实不值，诚实地面对它的价值所在很重要。DDD 越接近实现细节，其用处就越小：回报在于上游，即命名和概念对齐，而不是在聚合和层级仪式上。同义词控制在命名边界上很重要：模块名、表名、状态枚举、问题标题、CLI 命令。而在普通散文中，它的重要性要低得多。还有一个现实的反对意见是，领域术语压缩了人类之间本已共享的沟通，而代理对纯英语描述的响应方式是一样的。按照这种解读，词汇表的价值在于让你和你的审阅者与代理的行为保持一致，而不是让代理变得更好。对于为期一天的构建，跳过它吧。而且，未经审阅、由代理编写的词汇表比没有词汇表更糟糕：它会变成听起来很有权威的知识，后续会话会将其视为真理。

Can it turn my vague prompts into domain language for me? No, and there is no plan for a skill that does. A domain language you do not understand yourself becomes meaningless drivel once written down. This skill enforces precision once you have the understanding; it does not manufacture vocabulary you do not have. The related trap is using domain words without doing the modelling: right nouns over the wrong conceptual structure produce output that reads correct and is not.它能帮我把模糊的提示词转化为领域语言吗？ 不能，而且也没有计划开发这样的技能。如果你自己都不理解，领域语言写下来后就会变成毫无意义的废话。此技能在你理解之后强制执行精确性；它不会凭空制造你所不具备的词汇。相关的陷阱是在没有进行建模的情况下使用领域词汇：错误的构思结构上使用正确的名词，只会产生看起来正确但实际错误的结果。

It's working if如果出现以下情况，说明它正在发挥作用：

• It stops you mid-sentence to ask which of two things you meant, instead of picking one and moving on.它会在你话说到一半时打断你，询问你指的是两件事中的哪一个，而不是随意选一个继续。
• GLOSSARY.md changes during the conversation, not in a burst at the end.GLOSSARY.md 在对话过程中发生变化，而不是在最后一次性生成。
• It refuses to write an ADR for something you could undo tomorrow, and says which of the three tests failed.它拒绝为你明天就能撤销的事情编写 ADR，并说明了三项测试中哪一项未通过。
• New entries define what a thing is in one or two sentences and name the words you are giving up under _Avoid_.新条目会用一两句话定义事物，并在“避免”（Avoid）项下列出你正在放弃的词汇。
• It quotes your code back at you when your code and your sentence disagree.当你的代码和你的句子不一致时，它会将你的代码引用出来。
• GLOSSARY.md gets shorter as often as it gets longer.GLOSSARY.md 变短的频率和变长的频率一样高。

Where it fits适用场景

domain-modeling is a model-invoked reference that runs underneath other skills more often than it runs on its own. grill-with-docs drives it through a grilling session, wayfinder loads it while charting a map, triage uses it to keep tickets in the project's own words, and improve-codebase-architecture calls it as decisions crystallise. Its closest sibling is codebase-design: the two are the vocabulary layer under everything else, this one for the domain, that one for the module's shape. It is also reachable directly, when you want the discipline without committing to the steps of whatever skill would normally pull it in. When you are unsure which skill fits, ask-matt routes you.domain-modeling 是一种模型调用的参考，它在其他技能的底层运行的频率高于其独立运行的频率。grill-with-docs 在 grilling 会话中驱动它，wayfinder 在绘制地图时加载它，triage 使用它来保持工单使用项目自身的术语，improve-codebase-architecture 在决策具体化时调用它。它最亲密的兄弟是 codebase-design：两者是支撑其他一切的词汇层，前者针对领域，后者针对模块结构。当你想要这种规范而又不想提交到通常会调用它的技能步骤中时，也可以直接调用它。当你拿不准哪个技能适用时，ask-matt 会为你指引。