charted-design

协作式设计文档

目标

逐节采访用户，以编写设计文档。如果可以使用 AskUserQuestion 工具，请使用它。 重要：每完成一节后，都要将当前状态写入已解析的设计文档文件夹（见下方的 设计文档位置）。 磁盘上的设计文档文件是主要交付成果。 根据功能的复杂程度调整采访方式。

写作风格

仅对设计文档输出应用以下规则（不适用于本技能文件）：

• 优先使用简短的项目符号句子，而非段落。
• 每条只表达一个观点；每行长度大致控制在屏幕宽度内（约 150 个字符）。
• 在采访期间提出草稿内容以及最终汇总文档时，均采用此风格。

设计文档位置

在写入任何内容前，先确定此工作区中的设计文档存放位置：

• 根目录：工作区根目录下的 design-docs/
• 子文件夹：例如 contributing/design-docs/、docs/design/ 或其他项目专用路径
• Monorepo：多个项目可能各自拥有文件夹（例如 apps/web/design-docs/、packages/core/design-docs/）

确定方式：

1. 搜索现有设计文档文件夹（名为 design-docs 的目录，或类似 001-*.md 的编号文件）
2. 如果用户指定了项目或路径，则使用该路径
3. 如果只有一个明确的位置，则使用该位置
4. 如果有多个候选位置或找不到位置，先询问用户要使用哪个文件夹，再进行任何写入

确定后，在本次会话的其余时间内均使用该文件夹。

输出文件

• 路径：已解析的设计文档文件夹（见上文）
• 名称：NNN-short-kebab-title.md——NNN 为补零编号（例如 001、002）
• 序号：列出该文件夹及其子文件夹（例如 archived/）中的文件，取最大编号并加一。文件夹为空时，从 001 开始
• 标题：根据功能描述拟定简短的 kebab-case 标题（先询问用户）

采访流程

对于每一节：

1. 说明本节内容以及需要收集的信息
2. 提出有针对性的问题以收集信息
3. 立即将该节的草稿写入设计文档文件——更新磁盘上的文件，而不只是写在聊天中
4. 告知用户文件路径和已更新的章节；请用户检查或编辑文件，并在继续之前确认或提出更正

如果用户回答的内容属于后续章节，先予以确认，并说明到相应章节时会将其补充进去。

章节顺序与提示

1. 目标

说明这项工作为何重要——用户痛点、业务成果或机会。重点在目的，而非解决方案。

提问：谁遇到了这个问题？他们有什么痛点或需求？为什么现在解决它很重要？

目标应描述成果和需求，而非功能或实现方式：

• 正确示例：“用户在规划餐食时，需要花费大量时间在庞大的食谱目录中寻找内容。”
• 错误示例：“添加一个搜索输入框，在用户输入时筛选食谱。”

如果用户描述的是解决方案，应先将其重述为背后的需求，再撰写本节。将功能、用户体验和技术方案留到“期望行为”和“设计”章节。

2. 非目标

提问：哪些内容明确不在范围内？人们可能会以为包含在内、但实际上不包含的内容有哪些？

3. 期望行为

提问：描述用户可见的行为。用户会看到什么、点击什么或经历什么？请逐步说明各种场景。

将每种行为格式化为复选框：

- [ ] User sees a search input and a list of rules below it.
- [ ] Typing in the search input filters the visible rules by name.

4. 设计

提问：从高层次来看，应如何实现？涉及哪些组件、服务或数据结构？

4a. 图表

绘制一张 Mermaid flowchart，展示关键组件及其交互。

图例：

• 方角 = Angular/React/Vue 组件或后端 HTTP 控制器
• 圆角（即 [(xyz)]）= 服务
• 箭头：methodName({param1: Type1}): ReturnType
• [input1: Type1] = Angular/React/Vue 输入/属性，或后端请求/事件参数
• (output1: Type1) = Angular/React/Vue 输出/回调，或后端响应/事件
• 使用 <br> 避免标签内容被截断

将图表写入设计文档文件，并请用户在那里审阅。

4b. 实现细节

询问：有什么算法、边缘情况或约定吗？ 如果没有要补充的内容，则留空。

优先使用代码片段，而不是复选框。仅当类型、接口或签名尚不存在、不明显或有重大变化时，才添加代码片段。使用 JSDoc 说明不明显的行为。如果签名已能说明行为，则省略 JSDoc。跳过显而易见的现有代码和小改动。

仅当细节无法用类型、接口或签名表达时，才使用复选框（接线、排序、注册）。

暂时不要添加 PR 编号——PR 计划完成后再添加（请参阅下方的 PR 链接）。

```ts
/**
 * Empty cart returns `[]`, never null.
 * Does not create a cart.
 */
interface CartRepository {
  getItems(): CartItem[];
}
```

- [ ] Cart reads items with `inject(CartRepository)`.
- [ ] Register `CartRepository` in the cart feature providers.

5. 测试策略

询问：对于设计中的每个组件或单元，有哪些行为值得测试？

格式：按组件分组（##），每个测试场景使用 ### 标题，标题下方列出普通项目符号步骤。暂时不要在标题中添加复选框或 PR 编号——PR 计划完成后再添加（请参阅下方的 PR 链接）。

示例：

## Cart component

### Displays cart items

- Arrange fake cart repository to return 3 items: keyboard, mouse, monitor.
- Mount `Cart` component.
- Assert 3 items displayed with labels: "Keyboard", "Mouse", "Monitor".

6. PR 计划

提出按顺序排列、小规模、重点明确、逐步推进的 PR，要求：

• 绝不破坏现有行为
• 可独立审查和合并
• 差异保持聚焦

规则：

• 脚手架 PR：如果新增文件较多，将 WIP 脚手架放在单独的 PR 中
• 先整理 PR：如果必须更改接口，先进行向后兼容的更改（可选参数、弃用）
• 功能 PR：每个 PR 增加一项用户可见或可测试的功能

添加一张 Mermaid flowchart，展示 PR 之间的依赖关系。将每个 PR 列为复选框：

- [ ] PR#1 — Scaffold Cart component, repository interface, and test files.
- [ ] PR#2 — Display cart items from repository.

将 PR 计划写入设计文档文件，并请用户在那里审阅。

7. PR 链接

用户确认 PR 计划后：

1. 对于已确认复选框列表中的每个 PR，在 PR 计划下方添加一个 <details> 块，并附上 <summary> 标题。
2. 在每个块内添加 任务 和 测试策略 部分。
3. 将每项实现细节分配给对应的 PR。不要在该 PR 的任务中将代码片段作为代码片段复制。
4. 将顶层测试策略中的每个测试场景分配给对应的 PR。
5. 确认实现细节和顶层测试策略中的所有内容都已分配。
6. 删除现已为空的实现细节和顶层测试策略部分。
7. 从 PR 计划中删除复选框列表；保留依赖关系图。

8. 考虑过的替代方案

询问：是否考虑过其他方案？为什么不采用？

9. 其他事项

询问：还有其他事项吗——待解决的问题、风险、未来想法？ 如果没有，则留空。

最后一步

确保文件中包含所有部分；如果尚未执行 PR 链接，则完成该步骤，并向用户展示最终路径。文档应已存在于磁盘上——此步骤用于验证和清理，而不是首次组装文档。

模板

# Goals

{goals}

# Non-Goals

{non_goals}

# Desired Behavior

{desired_behavior}

# Design

{design}

## Diagram

```mermaid
{diagram}
```

## Implementation Details

{implementation_details}

# Testing Strategy

{testing_strategy}

# PR Plan

```mermaid
{pr_dependency_diagram}
```

{pr_details}

<details>
<summary>🚧 PR#N — {pr_title}</summary>

## Tasks

```ts
/**
 * Empty cart returns `[]`, never null.
 */
interface CartRepository {
  getItems(): CartItem[];
}
```

- [ ] {task_that_cannot_be_a_snippet}

## Testing Strategy

### 🚧 {test_title}

- {step_1}
- {step_2}

</details>

# Alternatives Considered

{alternatives}

# Kitchen Sink

{kitchen_sink}

其他资源

• 完整示例请参阅 resources/example-design-doc.md