59 lines
1.2 KiB
Markdown
59 lines
1.2 KiB
Markdown
# Goal-First Tech Doc
|
|
|
|
用于新写或重构技术文档。目标是让读者最快知道：这份文档为谁解决什么问题，做到什么算完成，如何最小复现。
|
|
|
|
## Use When
|
|
|
|
- 写 README、runbook、design note、tool usage、实验复现说明。
|
|
- 把抽象说明改成可执行文档。
|
|
- 压缩一份过长但重要的技术文档。
|
|
|
|
不要用于：
|
|
|
|
- 只修错别字。
|
|
- 论文/slide/marketing 文案。
|
|
- 技术正确性审查。
|
|
|
|
## Required Inputs
|
|
|
|
- 文档目标或现有草稿。
|
|
- 目标读者。
|
|
- 相关命令、配置、代码、路径或接口。
|
|
|
|
## Output
|
|
|
|
重写后的文档或提纲，必须包含：
|
|
|
|
- Goal。
|
|
- Prerequisites / Context。
|
|
- Steps or Design。
|
|
- 一个最小例子。
|
|
- Caveats / Failure Modes。
|
|
|
|
## Rules
|
|
|
|
- 目标先于背景。
|
|
- 信息先于修辞。
|
|
- 删除不增加行动能力的句子。
|
|
- 保留前提、约束、错误处理和边界条件。
|
|
- 只要提到命令、接口、数据格式、目录结构，优先给最小例子。
|
|
- 如果信息缺失但不阻塞，明确写假设。
|
|
- 如果信息缺失会误导，先请求补充。
|
|
|
|
## Preferred Shapes
|
|
|
|
短任务文档：
|
|
|
|
1. Goal
|
|
2. Steps
|
|
3. Example
|
|
4. Caveats
|
|
|
|
短设计文档：
|
|
|
|
1. Goal
|
|
2. Constraints
|
|
3. Design
|
|
4. Example
|
|
5. Tradeoffs
|