documentation-and-adrs

Documentation and ADRs - 技术文档和架构决策记录指南

技能概述

Documentation and ADRs 提供完整的技术文档编写指南，帮助团队记录架构决策、编写 API 文档、维护 README，让代码的"为什么"和"是什么"同样清晰。

适用场景

1. 做出重大技术决策时

当你的团队需要选择框架、设计数据模型、挑选认证方案或决定 API 架构时，这个技能指导你创建架构决策记录（ADR），捕捉决策背景、约束条件和权衡考量。十分钟的 ADR 能避免六个月后同样的决策被重新辩论。

2. 发布公共 API 或更改用户行为时

在添加或修改公共 API、发布改变用户行为的功能前，使用此技能确保 API 参数、返回类型、异常都有完整文档，防止未来的困惑和重复问题。

3. 新成员入职或频繁重复解释同一事物时

当你发现自己反复解释同一个技术选择或项目约定时，说明该内容需要文档化。这个技能帮助你在 CLAUDE.md 中记录项目规范，让 AI 代理和未来工程师快速理解项目上下文。

核心功能

1. 架构决策记录（ADR）创建和管理

提供标准化 ADR 模板，涵盖状态、日期、上下文、决策、替代方案和后果等关键部分。指导你匹配现有项目的 ADR 惯例（位置、格式、编号、标题），而不是盲目引入新方案。包含完整的 ADR 生命周期管理（PROPOSED → ACCEPTED → SUPERSEDED/DEPRECATED），确保历史决策得到保留而非删除。

2. 内联文档和注释最佳实践

教你何时写注释（解释"为什么"而非"是什么"）、何时不写（自解释代码不需要注释重述）、如何记录已知陷阱（防止 AI 代理和开发者掉坑）。区分稳定注释（决策理由）和易过时注释（代码描述），只编写前者。

3. 多层次文档体系

覆盖 API 文档（TypeScript JSDoc、OpenAPI/Swagger）、README 结构（快速启动、命令列表、架构概述）、变更日志维护（Added/Fixed/Changed），以及专门针对 AI 代理的文档规范（CLAUDE.md、spec 文件、内联陷阱）。

常见问题

什么时候需要创建架构决策记录（ADR）？

在选择框架、库或主要依赖项，设计数据模型或数据库架构，选择认证策略，决定 API 架构（REST vs GraphQL vs tRPC），或选择构建工具、托管平台、基础设施时。任何难以逆转的决策都值得用 ADR 记录。

ADR 应该包含哪些内容？

完整的 ADR 应包含：状态（Accepted/Superseded/Deprecated）、日期、上下文（需求、约束、条件）、决策（你选择的做法）、替代方案（考虑过的其他选项及其优缺点）、后果（选择的积极和消极影响）。如果项目已有 ADR 惯例，应匹配现有的章节标题和格式。

代码注释和技术文档有什么区别？

代码注释是临地的、嵌入代码的，用于解释非显而易见的"为什么"（如为什么用滑动窗口算法）。技术文档是独立的、结构化的，面向未来的读者和 AI 代理，解释决策背景、API 用法、项目架构。代码注释关注特定实现细节，文档关注整体上下文和设计理由。