文档和 ADR

概览

记录决策，而不只是记录代码。最有价值的文档会捕捉 why：促成某个决策的上下文、约束和权衡。代码展示构建了 what；文档解释 why it was built this way，以及 what alternatives were considered。这些上下文对未来在代码库中工作的工程师和 agent 都很重要。

何时使用

• 做出重要架构决策
• 在多个竞争方案之间做选择
• 添加或变更公开 API
• 发布会改变用户可见行为的功能
• 让新的团队成员（或 agent）熟悉项目
• 当你发现自己反复解释同一件事时

不应使用的情况： 不要记录显而易见的代码。不要添加只是复述代码本身的注释。不要为一次性原型编写文档。

Architecture Decision Records (ADRs，架构决策记录)