Agent Skills
返回列表
📚

文档与决策记录

知识管理 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @kunlungrowth/documentation-and-adrs

技能介绍

为什么需要决策记录？

很多团队在架构调整后，只留下“做了什么”的代码，却没写下“为什么这么做”。比如选择了 PostgreSQL 而非 MongoDB，可能因为关系模型需求，但后人只能从代码里猜；改了公共 API 却没记录权衡，下次评审又要重走争论。当新人或 Agent 接手时，没有这些上下文，很容易重复已否决的方案，或者不理解某个看似奇怪的设计。

技能如何补上这块缺口？

核心是把决策的“为什么”变成可追踪的文档，而非重复代码的注释。具体步骤包括：

  • 先匹配现有约定：查代码库是否已有 ADR 目录（如 .adr-dir）、格式或编号规则，沿用而非另起炉灶。
  • 写结构化 ADR：默认存到 docs/decisions/，每篇含状态（Proposed/Accepted/Superseded）、日期、上下文（需求与约束）、决策、被考虑的替代方案及拒绝理由、后果。变更时写新 ADR 引用旧的，不删除历史记录。
  • 管好周边文档：内联注释只写非显而易见的“why”（比如限流选滑动窗口的原因），公共 API 配 JSDoc 或 OpenAPI，README 链到 ADR，维护 CHANGELOG。
  • 面向 Agent 友好：更新规则文件（如 CLAUDE.md），让 Agent 知道已有决策，避免重蹈覆辙。

哪些情况不该用？

别给自解释的代码写注释，别重复代码能说明的内容，也别给一次性原型补全套文档。当决策影响长期架构、用户行为或公共 API 时，再启动这个流程。

使用场景

  • 团队在 PostgreSQL、MongoDB、MySQL 之间做选型，需要把上下文、权衡与拒绝理由写成 ADR 供后人追溯。
  • 修改 REST 公共接口并同步 OpenAPI 文档时，要向调用方说明破坏性变更与替代方案。
  • 用 Agent 重构老服务时，需要在 CLAUDE.md 里记录已否决的方案，防止它重复提出同样决策。
  • Code Review 反复被问限流为何用滑动窗口，需要写一篇 ADR 把原因一次说清。

适合人员

  • 后端工程师或架构师，需要在重大选型与架构变更后留下可追溯的决策记录。
  • 用 AI 辅助开发的工程师，需要把团队既有约定和已否决方案写进规则文件供 Agent 读取。
  • 技术负责人，在评审架构变更时需要看到上下文、替代方案与后果，而不是只看结论。
  • 刚接手老代码的新成员，想理解某个非显而易见设计（如接口限流策略）的来由。