writing-designs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Designs

编写设计文档

Takes

definition.md

from

docs/issues/YYYY-MM-DD-<slug>/

as input. Produces a design document grounded in research, not speculation.

Does NOT implement code, create PRs, or make architectural changes. Output is a design document only.

NO DESIGN DECISION WITHOUT A CITED REFERENCE

以

docs/issues/YYYY-MM-DD-<slug>/

目录下的

definition.md

作为输入，生成基于实际研究而非推测的设计文档。

不涉及代码实现、创建PR或架构变更，仅输出设计文档。

NO DESIGN DECISION WITHOUT A CITED REFERENCE

Workflow

工作流

- [ ] Step 1: Load Issue Definition
- [ ] Step 2: Research
- [ ] Step 3: Industry Baseline
- [ ] Step 4: Research Summary
- [ ] Step 5: Design Goals & Non-Goals
- [ ] Step 6: Proposed Design
- [ ] Step 7: Validate

- [ ] 步骤1：加载问题定义
- [ ] 步骤2：开展研究
- [ ] 步骤3：梳理行业基准
- [ ] 步骤4：撰写研究总结
- [ ] 步骤5：明确设计目标与非目标
- [ ] 步骤6：提出拟议设计
- [ ] 步骤7：验证检查

Step 1: Load Issue Definition

步骤1：加载问题定义

Read

definition.md

from the issue folder.

If no folder is specified, list available folders and ask
Extract: background, issue statement, current state, non-goals, open questions
Note open questions that affect design decisions

读取问题目录下的

definition.md

文件。

若未指定目录，列出可用目录并询问用户
提取信息：背景、问题说明、当前状态、非目标、待解决问题
记录会影响设计决策的待解决问题

Step 2: Research

步骤2：开展研究

Web search: Engineering blogs, technical articles, documentation
GitHub: Open-source implementations, issues, PRs showing patterns

Prioritize primary sources from companies that have solved this at scale. Use at least 3 distinct search queries.

Rules:

At least 5 references, each with a URL you actually visited
Verify each URL loads via
```
WebFetch
```
before including
Do NOT fabricate URLs

网络搜索：技术博客、技术文章、官方文档
GitHub调研：开源实现案例、相关Issue、体现通用模式的PR

优先参考已大规模解决该问题的企业的一手资料。至少使用3种不同的搜索关键词。

规则：

至少收集5份参考资料，每份需包含实际访问过的URL
纳入前需通过
```
WebFetch
```
验证每个URL可正常访问
禁止伪造URL

Step 3: Industry Baseline

步骤3：梳理行业基准

Common/default solution and widely adopted patterns
Trade-offs and known limitations
Cite references by title

通用/主流解决方案及广泛采用的模式
方案的权衡点与已知局限性
通过标题标注参考资料来源

Step 4: Research Summary

步骤4：撰写研究总结

Key patterns across sources
Which approaches fit the current issue and codebase
What research suggests about the issue's open questions

不同资料中的核心模式
哪些方案适配当前问题与代码库
研究结果对问题中待解决问题的启示

Step 5: Design Goals & Non-Goals

步骤5：明确设计目标与非目标

Design Goals — derive from issue statement, order by priority. Each must be verifiable: a measurable metric or testable assertion.

Non-Goals — inherit all from issue definition, add any discovered during research.

设计目标 —— 从问题说明衍生而来，按优先级排序。每个目标必须可验证：具备可衡量的指标或可测试的断言。

非目标 —— 继承问题定义中的所有非目标，补充研究过程中发现的新增非目标

Step 6: Proposed Design

步骤6：提出拟议设计

Reference specific files/modules from issue definition's current state
Explain key decisions and why alternatives were rejected (cite research)
Include interface definitions or data flows where helpful
Every decision traces to a design goal
Pseudocode acceptable; implementation code is not

参考问题定义中当前状态部分的具体文件/模块
解释关键决策，以及为何拒绝其他方案（需标注参考资料来源）
必要时包含接口定义或数据流图
每项决策都需对应到一个设计目标
可使用伪代码；禁止编写实现代码

Step 7: Validate

步骤7：验证检查

Check	Criteria
References	5+ entries with verified URLs via `WebFetch`
Industry Baseline	Cites references by title, no speculation
Design Goals	Verifiable, trace to issue statement
Non-Goals	All inherited items from issue definition included
Proposed Design	Every decision traces to a goal, no implementation code

If any check fails, return to the failing step and revise.

检查项	判定标准
参考资料	包含5份及以上通过 `WebFetch` 验证URL的条目
行业基准	通过标题标注参考来源，无推测内容
设计目标	可验证，且源自问题说明
非目标	包含问题定义中的所有非目标条目
拟议设计	每项决策都对应到一个目标，无实现代码

若任意检查项不通过，返回至对应步骤进行修订。

Output

输出要求

Save to

docs/issues/YYYY-MM-DD-<slug>/design.md

in the same folder as

definition.md

markdown

undefined

将文档保存至与

definition.md

同一目录下的

docs/issues/YYYY-MM-DD-<slug>/design.md

。

markdown

undefined

References

参考资料

Industry Baseline

行业基准

Research Summary

研究总结

Design Goals

设计目标

Non-Goals

非目标

Proposed Design

拟议设计


Missing any section invalidates the output.


缺少任意章节会导致输出无效。

Anti-patterns

反模式

❌ "Most apps probably use X" → ✓ "PDF.js uses X (PR #7793)"
❌ Atomic goal + best-effort design → ✓ reconcile goals and design
❌
```
keys.filter(k => ...)
```
→ ✓ "Collect keys ending with suffix"
❌ Unverified URLs → ✓ every URL visited via
```
WebFetch
```
❌ Features not traced to goals → ✓ every decision references a goal

❌ “大多数应用可能使用X” → ✓ “PDF.js使用X（PR #7793）”
❌ 绝对目标 + 尽力而为的设计 → ✓ 协调目标与设计方案
❌
```
keys.filter(k => ...)
```
→ ✓ “收集以指定后缀结尾的键”
❌ 未验证的URL → ✓ 所有URL均通过
```
WebFetch
```
访问验证
❌ 未关联到目标的功能 → ✓ 每项决策都需关联到一个设计目标