@namewta/speculo 0.2.2 → 0.2.6

package/template/canonical/canonical-domain-modeling.md

@@ -0,0 +1,289 @@
+# 领域建模
+
+---
+
+name: domain-modeling
+description: 通过无情面试打磨领域模型。挑战术语、发明边界场景、在决策结晶的瞬间写入 CONTEXT.md、ADR.md 和 LOG.md。当用户想要确定领域术语或通用语言、记录架构决策，或当其他技能需要维护领域模型时使用。
+
+---
+
+## 1. 面试（Grilling）
+
+请对我进行无情的面试，深入探讨该方案的每一个方面，直到我们达成共识。沿设计树的每个分支逐步推进，逐个解决决策之间的依赖关系。每个问题都给出你的推荐答案。
+
+一次只问一个问题，等待我对每个问题给出反馈后再继续。一次问多个问题会让人困惑。
+
+如果某个*事实*可以通过探索代码库找到，请自行查找，不要来问我。但*决策*由我来做 —— 将每个决策提交给我并等待我的回答。
+
+在我确认我们已达成共识之前，不要执行该方案。
+
+## 2. 领域建模规程
+
+在设计过程中积极构建和精炼项目的领域模型。这是*主动*规程 — 挑战术语、发明边界场景、并在决策结晶的那一刻立即写下词汇表和决策。仅仅_阅读_ `CONTEXT.md` 获取词汇不是本技能 — 那是任何技能都可以做到的一行习惯。本技能用于当你正在_改变_模型，而不仅仅是消费它时。
+
+### 文件结构
+
+```
+/
+├── CONTEXT.md
+├── ADR.md
+└── LOG.md
+```
+
+只维护这三个文件。没有 `docs/adr/` 目录下的编号文件，没有 `CONTEXT-MAP.md`。随着模型演进，在文件内部增、删、改条目。
+
+### 对照词汇表挑战
+
+当用户使用的术语与 `CONTEXT.md` 中的现有语言冲突时，立即指出。"你的词汇表将 'cancellation' 定义为 X，但你似乎指的是 Y — 到底是哪个？"
+
+### 精炼模糊语言
+
+当用户使用含糊或重载的术语时，提出一个精确的规范术语。"你在说 'account' — 你指的是 Customer 还是 User？它们是不同的东西。"
+
+### 讨论具体场景
+
+当讨论领域关系时，用具体场景进行压力测试。发明探索边界情况的场景，迫使用户精确界定概念之间的边界。"你说订单可以部分取消 — 未取消的商品怎么办？它们还能发货吗？"
+
+### 与代码交叉引用
+
+当用户陈述某事如何工作时，检查代码是否一致。如果发现矛盾，指出来："你的代码取消的是整个 Order，但你刚才说部分取消是可能的 — 哪个是正确的？"
+
+### 及时更新 LOG.md
+
+当设计问答中形成任何结论时，当场更新 `LOG.md`。它是完整的设计轨迹 — 记录"当时讨论了什么、最终固定了什么行为以及对应哪个 ADR"。
+
+**三个文件的分工**：
+
+| 文件 | 职责 | 维护方式 |
+|------|------|----------|
+| `LOG.md` | 完整设计轨迹 — 所有确认、延后、被替代的结论 | 持续增删改，条目可被后续决定修订 |
+| `CONTEXT.md` | 精炼的规范词汇表 — 只保留当前有效的术语 | 增删改，保持精炼 |
+| `ADR.md` | 难以逆转、令人意外、存在真实权衡的架构决策 | 只追加不删除，可标记废弃 |
+
+三者关系：LOG.md 是最完整的记录 → CONTEXT.md 从中提取术语定义 → ADR.md 从中筛选同时满足三个条件的架构决策。
+
+**日志条目格式**：每条日志使用 `## LOG-XXXX: {标题}` 二级标题，编号从 `0001` 开始顺序递增。
+
+**状态标记**：
+- `Status: accepted` — 已确认的现行结论
+- `Status: deferred` — 暂不决定，留待后续讨论
+- `Status: superseded` — 被后续决定替代，标注 `Superseded by: LOG-XXXX`
+
+**维护规则**：
+- 每次完成设计问答，同步更新 `LOG.md`、`CONTEXT.md` 与 `ADR.md`。
+- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
+- 日志可以记录具体交互和边界场景；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
+- 每个日志条目应关联对应的 ADR（如有）：`Related: ADR-XXXX`。
+- 状态为 `deferred` 的条目保留，以便后续恢复讨论时知道从什么问题开始。
+
+### 及时更新 CONTEXT.md
+
+当术语确定时，当场更新 `CONTEXT.md`。不要批量处理 — 发生时立即捕获。
+
+`CONTEXT.md` 应该完全不包含实现细节。不要将 `CONTEXT.md` 当作规范、草稿纸或实现决策的仓库。它只是词汇表，别无其他。
+
+- **新增术语**：在合适的子标题下追加条目。
+- **修改术语**：直接更新定义文本和 `_Avoid_` 列表。
+- **删除术语**：移除整个条目。
+- **术语更名**：删除旧条目，新增新条目。
+
+### 谨慎更新 ADR.md
+
+仅在以下三个条件全部满足时才向 `ADR.md` 追加一条决策记录：
+
+1. **难以逆转** — 以后改变主意的成本是有意义的
+2. **没有上下文会令人惊讶** — 未来的读者会疑惑"他们为什么这样做？"
+3. **真实权衡的结果** — 存在真正的替代方案，你出于特定原因选择了一个
+
+如果缺少任何一个条件，跳过 ADR。
+
+`ADR.md` 中每个决策是一个 `## NNNN: {标题}` 二级标题，编号顺序递增，条目之间用 `---` 分隔。可以修改已有条目、标记废弃 — 但不要删除。
+
+### 什么算 ADR
+
+- **架构形态。** "我们使用 monorepo。" "写模型采用事件溯源，读模型投影到 Postgres。"
+- **上下文间的集成模式。** "Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。"
+- **带来锁定效应的技术选择。** 数据库、消息总线、认证提供商、部署目标。不是每个库 — 只是那些需要花一个季度才能替换的。
+- **边界和范围决策。** "客户数据由 Customer 上下文拥有；其他上下文仅通过 ID 引用它。"明确的"不做"和"要做"同样有价值。
+- **有意偏离显而易见路径的决策。** "我们使用手动 SQL 而不是 ORM，因为 X。"
+- **代码中不可见的约束。** "由于合规要求，我们不能使用 AWS。" "由于合作伙伴 API 合同，响应时间必须低于 200ms。"
+- **拒绝的原因不明显的被拒绝替代方案。** 如果你考虑了 GraphQL 而因微妙原因选择了 REST，记录下来 — 否则 6 个月后有人会再次建议 GraphQL。
+
+## 3. CONTEXT.md 格式
+
+### 规则
+
+- **要有主见。** 当同一概念存在多个词时，选择最好的那个，并将其他的列在 `_Avoid_` 下。
+- **定义保持精炼。** 最多一两句话。定义它是什么，而不是它做什么。
+- **仅包含特定于该项目上下文的术语。** 通用的编程概念（超时、错误类型、工具模式）即使项目广泛使用也不属于这里。添加术语前自问：这是该上下文独有的概念，还是一个通用编程概念？只有前者才属于这里。
+- **当自然形成聚类时，用子标题分组术语。** 如果所有术语属于一个单一的凝聚领域，扁平列表也可以。
+- **随时增删改。** 模型演进时，直接修改文件：添加新术语、删除废弃术语、修正定义、术语更名。不要堆积 — 保持词汇表精炼且反映当前模型。
+
+### 模板
+
+<context_template>
+# {项目名称} 领域词汇表
+
+{对该上下文是什么以及为什么存在的一两句话描述。}
+
+## {术语分组}
+
+**Order**：
+{对该术语的一两句话描述}
+_Avoid_: Purchase, transaction
+
+**Invoice**：
+发货后发送给客户的付款请求。
+_Avoid_: Bill, payment request
+
+**Customer**：
+下订单的个人或组织。
+_Avoid_: Client, buyer, account
+</context_template>
+
+## 4. ADR.md 格式
+
+所有架构决策记录存放在仓库根目录的单一 `ADR.md` 文件中。
+
+### 模板
+
+<adr_template>
+# 架构决策记录
+
+## 0001: {决策的简短标题}
+
+{1-3 句话：背景是什么，我们做了什么决策，以及为什么。}
+
+---
+
+## 0002: {另一决策标题}
+
+{1-3 句话描述。}
+
+---
+</adr_template>
+
+每个决策是一个 `##` 二级标题，编号从 `0001` 开始顺序递增。决策之间用 `---` 分隔。
+
+就这样。一个 ADR 条目可以就是一个段落。其价值在于记录*已经*做出了决策以及*为什么* — 而不是填满各个部分。
+
+### 追加新决策
+
+1. 读取 `ADR.md`，找到最高现有编号
+2. 编号加 1
+3. 在文件末尾追加新条目
+
+### 可选附加元素
+
+仅当它们真正增加价值时才包含这些。大多数 ADR 不需要它们：
+
+- **日期** — 在标题行的 `{标题}` 后面加 `（YYYY-MM-DD）`
+- **Status** — `**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN`。当决策被重新审视时，直接修改状态标记
+- **Considered Options** — 仅当被拒绝的替代方案值得记住时
+- **Consequences** — 仅当需要指出非显而易见的下游影响时
+
+### 带可选元素的示例
+
+<adr_example>
+## 0003: 写模型采用事件溯源（2025-03-15）
+
+**Status**: accepted
+
+Order 聚合需要完整的变更历史用于审计和补偿。我们选择事件溯源 —
+所有状态变更作为不可变事件存储，当前状态从中投影。
+
+**Considered Options**:
+- 事件溯源（已选）— 天然审计日志，支持时间旅行调试
+- CRUD + 审计表 — 更简单，但审计日志与业务逻辑解耦，容易不同步
+- 仅 CRUD — 无审计历史，不满足合规要求
+
+**Consequences**:
+- 写路径复杂度增加；读路径需要投影
+- 事件 schema 演进需要显式版本策略
+</adr_example>
+
+### 修改已有决策
+
+- **澄清或补充后果** — 直接编辑条目正文
+- **改变状态** — 修改 `**Status**` 字段（如 accepted → deprecated）
+- **废弃** — 将状态改为 `deprecated`，如被新决策替代则加上 `superseded by ADR-NNNN`
+- **不要删除** — 即使决策被废弃，保留条目作为历史上下文
+
+### 何时提供 ADR
+
+以下三个条件必须同时为真：
+
+1. **难以逆转** — 以后改变主意的成本是实质性的
+2. **没有上下文的话令人惊讶** — 未来的读者会看着代码想"他们到底为什么这样做？"
+3. **真实权衡的结果** — 确实存在替代方案，你基于特定原因选择了一个
+
+如果决策容易逆转，跳过它 — 你反正会逆转的。如果不令人惊讶，没人会想为什么。如果没有真正的替代方案，那就没有可记录的，除了"我们做了显而易见的事"。
+
+### 什么算作
+
+- **架构形态。** "我们使用 monorepo。" "写模型采用事件溯源，读模型投影到 Postgres。"
+- **上下文间的集成模式。** "Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。"
+- **带来锁定效应的技术选择。** 数据库、消息总线、认证提供商、部署目标。不是每个库 — 只是那些需要花一个季度才能替换的。
+- **边界和范围决策。** "客户数据由 Customer 上下文拥有；其他上下文仅通过 ID 引用它。"明确的"不做"和"要做"同样有价值。
+- **有意偏离显而易见路径的决策。** "我们使用手动 SQL 而不是 ORM，因为 X。"
+- **代码中不可见的约束。** "由于合规要求，我们不能使用 AWS。" "由于合作伙伴 API 合同，响应时间必须低于 200ms。"
+- **拒绝的原因不明显的被拒绝替代方案。** 如果你考虑了 GraphQL 而因微妙原因选择了 REST，记录下来 — 否则 6 个月后有人会再次建议 GraphQL。
+
+## 5. LOG.md 格式
+
+### 规则
+
+- **记录每一次设计结论。** 无论大小，只要在访谈中确认、延后或被替代，都写入 LOG.md。宁可多记，不要遗漏。
+- **状态驱动。** 每个条目明确标记 `accepted`、`deferred` 或 `superseded`，让读者一眼知道当前有效性。
+- **关联 ADR。** 如果该结论同时满足 ADR 的三个条件，在 LOG 中标注 `Related: ADR-XXXX`，并在对应 ADR 条目中也关联回 LOG。
+- **保持可修订。** 后续决定改变既有结论时，直接更新原条目状态和正文，不要新建一条矛盾的条目。标注 `Superseded by: LOG-XXXX`。
+- **不堆积废弃条目。** 被替代的条目保留但标记清楚；延后（deferred）的条目保留以便后续恢复讨论。
+- **记录具体交互和边界。** 与 CONTEXT.md 的精炼不同，LOG.md 可以记录讨论中的具体场景、边界条件和交互细节。
+
+### 模板
+
+<log_template>
+# 设计决策日志
+
+本文件记录设计访谈中已经确认、延后或被替代的具体结论。它保存"当时讨论了什么、最终固定了什么行为以及对应哪个 ADR"；`CONTEXT.md` 是规范词汇表，`ADR.md` 是难以逆转的架构决策，本文件则是可持续增删改的完整设计轨迹。
+
+## 维护规则
+
+- 每次完成一个设计问答，同步更新 `LOG.md`、`CONTEXT.md` 与 `ADR.md`。
+- 已确认结论使用 `accepted`；暂不决定使用 `deferred`；被后续决定替代使用 `superseded`。
+- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
+- 日志可以记录具体交互和边界；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
+
+## LOG-0001: {决策的简短标题}
+
+Status: accepted
+Related: ADR-0001
+
+{背景：讨论了什么问题，做出了什么决定，以及为什么。可以记录具体的交互过程、边界场景和固定行为。}
+
+## LOG-0002: {另一决策标题}
+
+Status: deferred
+
+{为什么暂不决定，以及后续恢复讨论时应从什么问题开始。}
+
+## LOG-0003: {被替代的决策标题}
+
+Status: superseded
+Superseded by: LOG-0004
+
+{原决策内容，以及为什么被替代。保留作为设计演进的历史上下文。}
+</log_template>
+
+### 追加新日志
+
+1. 读取 `LOG.md`，找到最高现有编号
+2. 编号加 1
+3. 在文件末尾追加新条目
+
+### 修改已有日志
+
+- **改变结论** — 将原条目状态改为 `superseded`，标注 `Superseded by: LOG-XXXX`，在新条目中说明替代原因
+- **延后决定被重新讨论** — 将状态从 `deferred` 改为 `accepted`，或新建条目替代原条目
+- **补充细节** — 直接编辑条目正文，不改变状态
+- **不要删除** — 即使结论被替代，保留条目作为设计演进的历史上下文