domain-modeling

领域建模

设计时应主动构建并完善项目的领域模型。这是一项主动的实践——质疑术语、构思边界场景，并在概念明确的当下立即写下词汇表和决策。（仅仅为了了解词汇而阅读词汇表，并不算这项技能——任何技能都可以做到这种一行就能说明的习惯。这项技能适用于你正在改变模型，而不只是使用模型的情况。）

领域模型存在于两个地方：

• 词汇表 — docs/glossary/，每个术语对应一个 markdown 文件，格式须符合 uvx disambiguate 的要求（见下文）。绝不使用根目录下的 CONTEXT.md。
• 决策 — docs/adr/ 中的 ADR，遵循 writing-adrs 技能的要求。

如果有 writing-prose 技能可用，词汇表条目、ADR 和文档应使用该技能编写和检查，并注明 markdown——不得牺牲准确性和可理解性。

按需创建文件——只有在有内容可写时才创建。如果 docs/glossary/ 不存在，则在确定第一个术语时创建。

会话期间

根据词汇表进行质疑

当用户使用的术语与 docs/glossary/ 中现有的用法冲突时，立即指出。“你的词汇表将‘cancellation’定义为 X，但你似乎指的是 Y——到底是哪一个？”

明确模糊的语言

当用户使用含糊或一词多义的术语时，提出一个精确的规范术语。“你说的是‘account’——指的是 Customer 还是 User？两者并不相同。”

讨论具体场景

讨论领域关系时，用具体场景检验其合理性。构思能探查边界情况、促使用户明确概念之间界限的场景。

对照代码交叉核查

当用户说明某项功能的工作方式时，检查代码是否与之相符。如果发现矛盾，应指出：“你的代码会取消整个 Orders，但你刚才说可以部分取消——哪种说法才对？”

直接更新词汇表

术语确定后，立即在对应位置编写词汇表文件。不要积攒起来之后再处理——应在术语明确时及时记录。

词汇表条目不得包含任何实现细节。词汇表不是规范文档、草稿本或实现决策的存放处。它就是词汇表，仅此而已。

谨慎提议编写 ADR

只有符合 writing-adrs 技能中三项标准时，才提议创建 ADR（难以撤销、缺少背景时会令人意外、源于真实权衡）。格式、编号和位置也应遵循 writing-adrs 的要求。

词汇表条目格式

在 docs/glossary/ 中每个术语对应一个文件，格式须可供 uvx disambiguate 使用：

• 文件名即 slug：使用小写字母、数字和单个连字符（order-line.md → slug order-line）。Slug 必须唯一。
• 第一个二级标题是规范名称（必填）：## Order Line。
• 正文使用自由格式的 markdown：用一到两句简洁的话定义术语是什么，而非它做什么。同一概念有多个名称时，选出最合适的一个，并将其他名称列在 _Avoid_: 下。
• 交叉引用相关术语：使用标准 markdown 链接并以文件名为目标（[Customer](customer.md)），或使用 wiki 风格（[[customer]]）。这些链接会构成依赖图，供 disambiguate 按拓扑顺序呈现——基于其他术语的术语必须链接到这些术语。

docs/glossary/invoice.md 示例：

## Invoice

A request for payment sent to a [Customer](customer.md) after delivery.

_Avoid_: Bill, payment request

规则：

• 明确取舍。 每个概念只设一个规范术语；其他竞争用词列在 _Avoid_ 下。
• 只收录特定于本项目的术语。 通用编程概念（超时、错误类型、实用模式）不应收录，即使项目广泛使用这些概念。
• 编辑后使用 uvx disambiguate --lint 验证。