design

设计

确定要构建什么、为什么重要、用户会有怎样的体验，以及它将如何工作。敲定重要决策，避免实现 Agent 被迫自行臆断。

流程

1. 阅读需求、仓库说明、相关代码和链接材料。沿用已确定的要求和仓库惯例。
2. 找出会影响行为、接口、数据、安全、运维或验证的未决事项。起草前先询问阻碍性问题，并给出建议答案。记录非阻碍性问题及建议的默认答案。
3. 使用下方的简洁结构编写 docs/<feature-slug>/design.md。常规功能的目标篇幅为 500 至 800 词。若重要决策或风险需要更多说明，则适当扩充；完整性比篇幅目标更重要。
4. 执行一次评审。根据现有证据弥补缺漏，并在“未决问题”下记录尚未解决的决策。
5. 停止并提交一份可供评审的设计方案。不要规划或实现该方案。

文档结构

# <Title>

> **Status:** Proposed for review

## 1. Requirements: what and why
Explain the problem, who has it, and the outcome they need. State the required capabilities, constraints, and what is out of scope. Make the value clear before introducing implementation details.

## 2. User experience
Describe the system as a black box: what the user does or supplies, what they see or receive, and what happens next. Walk through the main flow and relevant empty, invalid, denied, and failed outcomes, including recovery. For a CLI, API, or library, the user can be an operator or caller. Keep internal components and algorithms in the technical design.

## 3. Technical design and choices
Explain how the proposed change fits the existing system. Name the changed responsibilities, interfaces, and data. Record consequential technology choices with a reason and their main tradeoff. Add the relevant detail described below.

## 4. Acceptance and proof
Pair each testable condition with how it will be checked. Include affected failure paths and rules that must always hold. Reference earlier decisions instead of repeating their full definitions.

| ID | Done when | How to check |
|---|---|---|
| AC-1 | Observable condition | Exact command, automated scenario, or manual check |

## 5. Open questions
List unresolved decisions, the recommended answer, and whether they block planning or implementation. Write None when the design is settled.

技术细节

仅纳入本次变更需要决策的主题。必要时使用简短的小节。

• 技术选型： 语言、框架、主要依赖、存储和部署。对于新项目，选择核心技术栈。对于现有项目，引用既定选型，并说明新增或变更之处。若兼容性取决于版本，则注明固定版本。
• 结构和契约： 变更组件的职责与边界、API、命令、事件、架构、配置和迁移。如果存储的名称或 ID 发生变化，说明标识符的生成方式和兼容性。
• 故障与恢复： 说明可能发生的故障、故障后的状态、重试及其限制，以及恢复方式。若启动、运行期间的变更或关闭会影响结果，也应说明。
• 安全与运维： 信任边界、授权、敏感数据，以及与规模、延迟、连接、磁盘、内存或成本相关的限制。说明达到适用限制时会发生什么。

对于每项重要选择，说明决策内容、为何符合需求，以及主要代价或限制。仅当对比有助于解释选择时，才提及被否决的替代方案。将容易撤销的局部实现细节留给实现 Agent。

写作规则

• 使用平实的措辞，并解释必要术语。不要使用破折号。
• 每项事实只在一个位置说明。需求说明需要什么；用户体验描述可观察到的行为；技术设计解释如何实现。验收检查引用这些内容，不要另起一份重复说明。
• 解释使用段落，并列事实使用列表。仅在有助于说明关系或流程时使用图示。
• 将当前架构与提议的行为区分开。若存在 ARCHITECTURE.md，请链接该文件，并引用共享惯例，而不要重复说明。
• 对需要在规划、实现和评审期间保持稳定引用的规则，使用 INV-n。在“验收与验证”中为每条不变量注明验证方式。
• 保持引用的 AC-n 和 INV-n ID 与对应规则关联。绝不重新编号或重复使用；新增条目使用下一个未使用的 ID。
• 更新现有设计时，保留已链接的小节锚点。不要仅为了套用此模板而重构文档。

评审

返回设计前，请检查以下四点：

1. 新队友能否不阅读技术设计，就说明有哪些变化、为什么变化，以及用户体验会如何改变？
2. 实施 Agent 能否在无需自行做出重要产品或技术决策的情况下继续推进？技术选型是否有充分依据，并且与代码库兼容？
3. 是否明确说明了相关故障、数据变更、信任边界和运行限制，并提供足够细节，避免不安全或不兼容的实现？
4. 每项验收标准和不变量是否都有具体的验证方式？将含糊的时间要求或备选结果替换为一条可测试的规则。删除重复的背景信息和不涉及决策的章节。

返回内容

报告设计路径、主要技术决策及其权衡、任何阻塞性问题，以及评审结果。请简明扼要；具体细节已包含在设计中。