用途：记录架构决策、API 契约与系统行为，重点解释设计背后的“为什么”，因为代码本身已说明“是什么”。
适用时机：做架构或设计决策、变更公开 API 或接口、交付影响其他团队的功能、记录权衡及其理由。
文档类型： 一、架构决策记录（ADR）。包含标题（简短名词短语）、上下文（技术或业务背景）、决策（决定了什么）、后果（正负面结果）、状态（Proposed / Accepted / Deprecated / Superseded）。保存路径为 docs/decisions/{YYYY-MM-DD}-{title}.md。 二、API 文档。需覆盖端点路径与方法、请求与响应 schema、错误码与恢复策略、鉴权要求、速率限制与配额、版本信息。 三、行内文档。解释“为什么”而非“是什么”，说明非显而易见的决策与权衡，标注陷阱与边界情况，引用相关 ADR、规格或 issue，避免复述代码已表达的内容。 四、README 与入门文档。每个项目应说明：项目做什么（一段话）、如何安装与运行、如何跑测试、如何贡献、更多文档在哪。
流程：第一步识别需要记录的内容，如新架构决策、变更的公开接口、非显而易见的实现选择、上手时的摩擦点；第二步选择合适格式，架构决策用 ADR，API 表面用 API 文档，非显而易见的代码用行内注释，项目概览用 README；第三步面向读者写作，假设读者懂领域但不了解本系统，用具体例子，保持内容最新或标记为过期，优先短小聚焦而非长篇；第四步复核准确性，验证代码示例仍可用、引用的路径与命令正确、文档与当前实现一致。
常见借口与现实：“代码自解释”——代码说明是什么，文档说明为什么，两者都需要；“文档很快过期”——过期是更新的信号，不是停止文档化的理由；“以后再写”——以后不会来，应与实现同步写。
核验项：架构决策有对应 ADR；公开 API 有带示例的文档；行内注释解释“为什么”；README 最新且可操作。
限制：资料未提供具体工具、收费、平台或安装命令。