@namewta/speculo 0.2.6 → 0.2.9

package/template/canonical/canonical-specdev-grill-with-docs.md

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

package/template/canonical/canonical-specdev-spec.md

@@ -0,0 +1,82 @@
+# 编写 Spec
+
+此 work 读取当前对话上下文和代码库理解，产出一份 spec（你可能也称之为 PRD）。不要访谈用户 —— 仅综合你已经知道的内容。
+
+## 流程
+
+### 1. 探索代码库
+
+探索仓库以了解代码库的当前状态（如果尚未这样做）。在整个 spec 中使用项目的领域词汇表，并尊重所涉及区域的任何 ADR。
+
+先读取 ``CONTEXT`` 了解项目的领域词汇表——使用其中的术语定义，不要自创名称。
+
+再读取 ``ADR`` 了解已做出的架构决策——不要与已有决策冲突。如果 spec 涉及与某 ADR 相同或相邻的区域，在实现决策中引用该 ADR。
+
+`{change}` 为当前活跃变更的目录名，格式为 `<YYYY-MM-DD>-<topic>`。如果尚未创建变更目录，先运行 ``G-grill-with-docs`` 的启动变更阶段初始化 CONTEXT.md 和 ADR.md。
+
+**完成标准**：代码库当前状态已理解，领域词汇表和 ADR 已纳入考量。
+
+### 2. 草拟接缝
+
+草拟你将用于测试该功能的接缝（seam）。接缝是你可以插入测试以验证行为的位置——API 端点、CLI 命令、UI 交互点、事件回调等。
+
+**接缝规则：**
+
+- 优先使用现有接缝而不是新建。查看代码库中已有的测试，了解项目如何注入测试。
+- 使用尽可能高层的接缝。UI 测试 > API 测试 > 单元测试，按此优先级选择。
+- 如果需要新接缝，在尽可能高的层级提出。代码库中的接缝越少越好 —— 理想数量是 1 个。
+- 每个接缝描述：接缝位置（什么模块/组件）、接缝类型（E2E、API、单元）、何时触发、如何验证。
+
+**与用户确认这些接缝是否符合他们的期望。** 展示草拟的接缝列表，询问：
+- 接缝层级是否合适？（太高可能遗漏细节，太低可能过于脆弱）
+- 是否有遗漏的接缝？
+- 现有接缝是否已足够，无需新增？
+
+**完成标准**：测试接缝已草拟并经用户确认。
+
+### 3. 编写 spec
+
+按以下模板编写完整 spec，写入 ``spec``。
+
+---
+
+**问题陈述** —— 从用户视角描述用户面临的问题。不要描述技术问题——描述用户遇到的困境、无法完成的任务、或当前流程中的痛点。一两段即可，但必须具体到让读者理解"为什么需要这个功能"。
+
+**解决方案** —— 从用户视角描述问题的解决方案。描述用户将如何与新功能交互、他们的体验将如何改变。不要写实现细节——写用户能做什么、看到什么。一两段即可。
+
+**用户故事** —— 一个详细的、编号的用户故事列表。每个用户故事格式为：
+
+> 作为 &lt;角色&gt;，我希望 &lt;功能&gt;，以便 &lt;收益&gt;
+
+例如：*作为手机银行客户，我希望查看账户余额，以便做出更明智的消费决策。*
+
+用户故事列表应极其详尽，涵盖该功能的所有方面。覆盖以下维度：
+- 主要流程（happy path）—— 用户最常走的路径
+- 边界情况 —— 空数据、极限值、并发操作
+- 错误处理 —— 用户犯错时发生什么
+- 权限与角色 —— 不同角色的不同体验
+- 状态转换 —— 数据从创建到归档的每个状态变化
+
+**实现决策** —— 已做出的实现决策列表。可包含：将构建/修改的模块、这些模块将被修改的接口、开发者的技术澄清、架构决策、Schema 变更、API 契约、具体交互。不要包含具体文件路径或代码片段——它们可能很快过时。
+
+例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联在相关决策中，并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+
+**测试决策** —— 已做出的测试决策列表。包含：什么构成好测试的描述（只测试外部行为，不测试实现细节）、哪些模块将被测试、测试的先例（即代码库中类似类型的测试）。
+
+**超出范围** —— 描述此 spec 超出范围的内容。明确说出**不做什么**与说出做什么同样重要。对于每个超出范围的条目，简要说明原因（是后续版本的规划、还是技术上不可行、还是与产品愿景不符）。
+
+**补充说明** —— 关于该功能的任何补充说明。可包含：已知风险或不确定性、依赖的外部系统或团队、需要进一步调研的领域、迁移或废弃计划。
+
+---
+
+写入后，不要做额外的 triage 或标签操作——spec.md 的地位由其在变更目录中的存在本身决定。
+
+**完成标准**：spec.md 已写入变更目录——问题陈述、解决方案、用户故事、实现决策、测试决策、超出范围、补充说明各章节齐全，无残留 `[TODO:]`。
+
+## 子文件引用
+
+本入口为单文件 work，所有内容均已内联。以下引用仅在其他 work 需要读取 spec 时使用：
+
+- ``spec`` —— 编写的 spec 产物
+- CONTEXT.md —— 领域词汇表（阅读用）
+- ADR.md —— 架构决策记录（阅读用）