用途：该技能强调“记录决策而非仅记录代码”，用于在做出重大架构决策、在方案间取舍、新增或变更公开 API、发布影响用户行为的功能、以及反复解释同一问题时编写文档；不建议为明显的代码、一次性原型或无意义内容写文档。
主要能力： 一是架构决策记录（ADR），用于记录重大技术决策的理由，包括选型（框架、库、依赖）、数据模型或数据库模式、认证策略、API 架构（REST/GraphQL/tRPC）、构建工具与托管平台，以及任何难以逆转的决策。ADR 存放在 docs/decisions/ 并按序号命名，模板含标题（如 # ADR-001: Use PostgreSQL for primary database）、Status（Accepted | Superseded by ADR-XXX | Deprecated）、Date、Context、Decision、Alternatives Considered（逐项列 Pros/Cons/Rejected 理由）、Consequences。生命周期为 PROPOSED → ACCEPTED →（SUPERSEDED 或 DEPRECATED），不删除旧 ADR，决策变化时写新 ADR 引用并取代旧的。 二是内联文档：注释解释“为什么”而非“是什么”，避免复述代码；不留 TODO、不保留注释掉的代码；用文档注释记录已知陷阱（如必须在首次渲染前调用、并指向对应 ADR）。 三是 API 文档：TypeScript 优先用类型内联 JSDoc（含 @param、@returns、@throws、@example）；REST API 可用 OpenAPI/Swagger 描述路径、请求体与响应码。 四是 README 结构：项目名与一段描述、Quick Start（克隆、安装依赖、配置环境、启动开发服务器）、Commands 表（如 npm run dev、npm test、npm run build、npm run lint）、Architecture 概览并链接 ADR、Contributing。 五是变更日志：按版本和日期分组 Added、Fixed、Changed，并关联 issue 编号。
适用场景：新成员或 AI Agent 上手、保持 spec 与 CLAUDE.md 等规则文件最新、防止重复讨论同一决策、避免 Agent 重蹈已知陷阱。
限制：不适用于显而易见的代码、一次性原型或纯复述代码的注释；文档需随决策更新，避免过期。资料未提供安装命令、收费、平台支持或具体使用步骤。