Appearance
Documentation and ADRs 解决的是项目只留下代码、没有留下决策背景的问题。好文档不重复解释代码做什么，而是记录为什么选这个方案、放弃了哪些方案、后续会承担什么后果。
AI 写文档怎么记录为什么：Documentation and ADRs 怎么用
下载 documentation-and-adrs 中文版 Skill ZIP
三个月后，你打开一段认证代码，只记得当时吵过一次方案。
它很少告诉你为什么这么做。
半年后再看项目，最难找的不是函数名，而是当初为什么选这个库、为什么接口这样设计、为什么没用另一个方案。
documentation-and-adrs 这个技能关注的就是这些背景。
不要写重复代码的文档
坏文档常常在重复代码：
md
这个函数会计算总价。如果函数名已经叫 calculateTotal，这句话价值很低。
更有用的是：
- 为什么这里不能用缓存。
- 为什么这个接口保持旧字段。
- 为什么这个迁移要分两步。
- 为什么选择 PostgreSQL 而不是 SQLite。
- 为什么这里必须在服务端校验。
AI 写文档时，要让它记录决策，不要复述代码本身就能说明的实现。
ADR 适合记录大决定
ADR 是 Architecture Decision Record，架构决策记录。
这些场景适合写：
- 选择框架、数据库、构建工具。
- 设计公共 API。
- 改认证方案。
- 做数据迁移。
- 引入外部服务。
- 做很难回退的技术决策。
ADR 不需要长。关键是记录：背景、决定、替代方案、后果。
一个轻量 ADR 模板
md
# ADR-001: [决策标题]
## 状态
Accepted
## 背景
[为什么需要做这个决定]
## 决定
[选择了什么方案]
## 替代方案
- 方案 A：为什么没选
- 方案 B：为什么没选
## 后果
- 好处
- 成本
- 后续约束这比一篇很长的“技术方案总结”更容易维护。
README 解决上手问题
README 更适合回答：这个项目是什么，怎么跑，常用命令是什么，基本结构是什么。
ADR 更适合回答：为什么这样设计。
不要把所有东西塞进 README。README 太长，后来的人也不看。
给 AI 的文档 Prompt
md
请为这次技术决策写一份轻量 ADR。
要求：
1. 记录背景和约束。
2. 说明最终选择。
3. 列出考虑过但放弃的方案。
4. 写清后果和未来维护成本。
5. 不要复述代码细节。你可能还需要
同类技能：
当一个决定未来会让人问“为什么”，现在就该写下来。