documentation-and-adrs

# documentation-and-adrs 技能说明

## 技能简介

这个技能用于在开发过程中记录架构决策和关键文档。它强调记录“为什么”（背景、约束、权衡）而不仅是“做了什么”，帮助未来的工程师和 Agent 快速理解代码库背后的设计意图。

## 使用场景

- 做出重大架构决策或选择技术方案时
- 添加、修改公共 API 或改变用户可见行为时
- 设计数据模型、数据库 schema、认证策略或 API 架构时
- 需要为新成员或 Agent 记录项目上下文时
- 反复向别人解释同一件事时

## 使用方法

将该技能放入 Agent 的 skills 目录（如 `.claude/skills/documentation-and-adrs/`）即可自动启用。当上下文中出现“记录决策、架构选型、API 变更、写文档”等任务时，技能会自动触发。

使用该技能时的核心操作：

- **写 ADR（架构决策记录）**：仓库无现成约定时，在 `docs/decisions/` 下创建带序号的 ADR（如 `ADR-001`），包含 Status、Date、Context、Decision、Alternatives Considered、Consequences 等章节。
- **匹配现有约定**：创建 ADR 前先检查仓库中已有的 ADR 位置、编号方式、文件格式和标题风格，沿用惯例而不是另起一套。
- **写内联注释**：只注释代码中非显而易见的“为什么”，用 JSDoc 记录公共 API 的参数、返回值和异常。
- **记录已知坑**：对容易踩坑的代码块添加 `IMPORTANT` 说明，并关联相关 ADR。

## 注意事项

- 不要为显而易见的代码写注释，不要留 TODO 或注释掉的代码。
- 旧 ADR 不要删除，它们是历史上下文；决策变化时写新 ADR 并标记为 supersedes 旧 ADR。
- 若仓库现有约定与默认模板冲突，应指出冲突，而不是默默引入新格式。