Rationale 模板

来源

这是中文译文，方便对照阅读。本站不发行中文版插件。英文原文 pstack/skills/architect/references/rationale-template.md，取自 pstack 官方仓库 cursor/plugins 的提交 12d587d。

本站英文页

Rationale 模板

与类型草图一并交付的说明文。一页。句首大写标题，无套话。斜体提示替换为实际内容。

问题

一段。我们要做什么，现有系统或约束中什么使形态不显然。若 阶段 A 发现设计必须遵守的约束（需互操作的现有类型、不能破坏的调用方、跨边界的 invariant），在此点名，让读者看到与你相同的约束。

用法（调用方视角）

先于类型草图写。展示消费者会读的 README 或快速上手，再加两三个其代码中的真实调用点：导入什么、调用什么、返回什么。形态 中的类型草图由此推导。二者必须一致。分歧时以用法为准修正草图，而非相反。调用方体验即规格，类型为它服务。

形态

推荐架构。先数据结构，再数据如何流经签名。点明承重决策。说明哪些 invariant 编码在类型里、校验在哪里、系统刻意不做什么。明确评判接口深度：公开面隐藏了哪些复杂度、仍暴露给调用方什么、为何接口不再更大。每项决策引用原则（如 per boundary-discipline），不要复述原则全文。

综合决策

由 arena 填写。记录哪个候选成为基底及原因、从其他候选采纳了什么、拒绝了什么及原因。

接受的权衡

所选形态做出的每项权衡一条。格式：「我们接受 X，换取 Y。」点明未来读者可能误以为是疏漏之处，包括看似过早优化或过早简化的情况。

考虑过的备选

必填。至少一个具体备选形态，一行说明为何落选。按接口深度评判，不单看实现是否简单。说明它向调用方暴露的复杂度与隐藏的复杂度。设计空间有真实竞争者时写两三个；约束迫使唯一答案时写一条即可，结论表述为「这是唯一可行形态，因为……」避免罗列同一形态的不同变体。本节是所选形态考虑并拒绝的设计备选，不是其他 runner 候选。

开放问题与风险

草图过程中注意到、需人类权衡的事项，以及实现前应标出的风险。以问题而非断言表述，使人类的回答即 resolution，而非评论。

下一步实现

按草图要建的第一件事。一句。综合后（或可选卡点后阶段 D 签字后）立刻开始写什么。