Documentation and ADRs

Documentation and ADRs 是什么

Documentation and ADRs 是 addyosmani/agent-skills 仓库中的独立 Skill。编写与维护技术文档及架构决策记录，把背景、候选方案、权衡、决定、影响与后续复审条件写清楚。 来源清单的英文描述为：Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.。本文结合完整清单的章节和仓库信息重写为中文使用说明，保留其真实边界，不把 GitHub 热度等同于质量认证。

适用场景与使用价值

它适合在目标已经比较明确、但团队需要一套可重复方法和检查清单时使用。先确定读者、文档目的、事实来源、结构和维护责任，再建立提纲与模板；写完后核对术语、链接关系、示例、决策背景和后续更新入口。 如果任务非常简单、已有更权威的项目规范，或来源清单没有覆盖当前技术与渠道，应优先采用现有规则，不能为了使用 Skill 而增加流程。

核心能力与清单结构

完整清单把操作说明组织为 Overview、When to Use、Architecture Decision Records (ADRs)、When to Write an ADR、Match the existing convention first、ADR Template、Status、Date、Context、Decision 等章节。它不是只有一句提示词，而是通过这些章节约束任务识别、分析顺序、输出结构和检查点；实际使用时应回到对应章节确认细节，不能仅凭标题推断能力。

推荐执行流程

先把目标、对象、输入范围、不可改变的事实和成功标准写清楚，再阅读完整清单并定位与当前任务有关的章节。根据清单建立步骤和检查点，先用小样或低风险范围验证；随后分阶段执行，每一步保存依据、输出和异常。先确定读者、文档目的、事实来源、结构和维护责任，再建立提纲与模板；写完后核对术语、链接关系、示例、决策背景和后续更新入口。 完成后对照原始目标复核，不把计划、草稿、命令已运行或接口已受理描述成最终成功。

输入、输出与交付要求

输入至少应包含任务背景、当前材料、预期交付、适用技术或渠道、时间范围、组织规范和已知限制。输出应包括可继续使用的方案、代码、文档或清单，以及来源、假设、未解决问题、验证证据和下一步。缺失会改变权限、费用、合规或技术路线的信息时，应先补齐；无法补齐则明确标记假设。

依赖、账号与权限

来源是一份 Markdown Skill 清单，本身不会自动提供运行环境、账号或外部服务。实际依赖取决于清单建议和项目上下文，可能涉及代码仓库、浏览器、测试工具、分析平台或营销系统。读取资料只申请必要权限；涉及写文件、改代码、调用网络、上传数据、发送内容、付费或发布时，要在动作前核对账号、对象、范围与恢复办法。

副作用、限制与风险

自动整理可能丢失上下文、把讨论写成决策或让文档与代码脱节，格式正确也不代表内容准确。 GitHub 星标只表示仓库受到关注，不能证明每条方法都适合当前任务，也不代表代码、安全、许可或结果已经过第三方认证。仓库后续提交可能改变清单内容，因此复用时要记录提交版本并重新检查差异。单纯阅读清单不会改变外部状态，但执行其建议可能修改仓库、文档、配置、营销资产或线上系统，也可能访问网络、上传资料、触发消息与产生费用。所有副作用都应在实施计划中单独列出，高影响动作使用测试环境、副本、最小权限和人工确认点。

不适用边界

不编造决策过程和事实，不覆盖唯一原稿，不把未批准建议写成正式规范。 来源未声明的功能、效果与专业资质不能自行补写；需要法律、医疗、财务、安全或隐私判断时，应由相应专业人员复核。未经用户明确授权，不得替用户发送、发布、购买、部署、删除或改变真实外部系统。

失败处理与结果验收

失败时先停止继续扩大影响，保存输入、日志、差异、任务标识和当前状态，判断外部系统是否已经局部生效。能够回滚时恢复到已验证版本；异步任务优先查询原任务，避免重复创建、发送或扣费。若失败源于信息不足或清单与项目冲突，应退回澄清和方案选择，而不是无上限重试。验收要基于真实文件、测试结果、页面状态、指标或目标系统记录。抽查正常路径与边界案例，确认名称、数量、权限、时间、链接关系和格式均符合约定；高风险结论应由人工复核。未能实际运行或访问的部分必须明确标记为待验证，不能用推断替代证据。

适合谁使用

适合开发团队、架构师、维护者和技术写作者。 对新手而言，它可以作为提问和检查框架；对有经验的使用者，它更适合用来补足遗漏和统一团队口径。若组织已有更严格的安全、品牌或工程制度，应把来源清单作为辅助材料，而不是覆盖内部制度。

来源、热度、版本与许可

本条目来自 GitHub 热门 agent-skills 主题仓库 addyosmani/agent-skills，按 2026 年 10 月 8 日调研时的 Star 数记录为 102967。正文依据固定提交 1401c8b8030e023baeebb31781a6653fe8e93026 中的 skills/documentation-and-adrs/SKILL.md 与 GitHub 仓库详情整理。仓库通过 GitHub 元数据声明许可证为 MIT；复用时仍要检查清单、依赖与素材是否有额外许可要求。 热度用于发现候选，不替代源码、权限、隐私和依赖审查。

常见问题

1. Documentation and ADRs 主要解决什么问题？

Documentation and ADRs 是 addyosmani/agent-skills 仓库中的独立 Skill。编写与维护技术文档及架构决策记录，把背景、候选方案、权衡、决定、影响与后续复审条件写清楚。 来源清单的英文描述为：Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.。本文结合完整清单的章节和仓库信息重写为中文使用说明，保留其真实边界，不把 GitHub 热度等同于质量认证。它适合在目标已经比较明确、但团队需要一套可重复方法和检查清单时使用。先确定读者、文档目的、事实来源、结构和维护责任，再建立提纲与模板；写完后核对术语、链接关系、示例、决策背景和后续更新入口。 如果任务非常简单、已有更权威的项目规范，或来源清单没有覆盖当前技术与渠道，应优先采用现有规则，不能为了使用 Skill 而增加流程。是否采用它，应由任务匹配度和证据决定，而不是只看星标数量。

2. 开始前需要准备哪些资料？

输入至少应包含任务背景、当前材料、预期交付、适用技术或渠道、时间范围、组织规范和已知限制。输出应包括可继续使用的方案、代码、文档或清单，以及来源、假设、未解决问题、验证证据和下一步。缺失会改变权限、费用、合规或技术路线的信息时，应先补齐；无法补齐则明确标记假设。不要替用户猜测关键业务事实，必要输入不齐时应先列出缺口。

3. 建议按什么顺序使用？

先把目标、对象、输入范围、不可改变的事实和成功标准写清楚，再阅读完整清单并定位与当前任务有关的章节。根据清单建立步骤和检查点，先用小样或低风险范围验证；随后分阶段执行，每一步保存依据、输出和异常。先确定读者、文档目的、事实来源、结构和维护责任，再建立提纲与模板；写完后核对术语、链接关系、示例、决策背景和后续更新入口。 完成后对照原始目标复核，不把计划、草稿、命令已运行或接口已受理描述成最终成功。每个阶段都应保留检查点，让结果能够被复核和回退。

4. 需要哪些工具、账号或权限？

来源是一份 Markdown Skill 清单，本身不会自动提供运行环境、账号或外部服务。实际依赖取决于清单建议和项目上下文，可能涉及代码仓库、浏览器、测试工具、分析平台或营销系统。读取资料只申请必要权限；涉及写文件、改代码、调用网络、上传数据、发送内容、付费或发布时，要在动作前核对账号、对象、范围与恢复办法。凭据不得写入文章、日志或仓库，权限只授予当前任务所需范围。

5. 执行时可能产生哪些外部影响？

单纯阅读清单不会改变外部状态，但执行其建议可能修改仓库、文档、配置、营销资产或线上系统，也可能访问网络、上传资料、触发消息与产生费用。所有副作用都应在实施计划中单独列出，高影响动作使用测试环境、副本、最小权限和人工确认点。凡是发送、发布、删除、付费和生产写入，都应在动作前再次确认。

6. 哪些情况不适合直接采用？

不编造决策过程和事实，不覆盖唯一原稿，不把未批准建议写成正式规范。 来源未声明的功能、效果与专业资质不能自行补写；需要法律、医疗、财务、安全或隐私判断时，应由相应专业人员复核。未经用户明确授权，不得替用户发送、发布、购买、部署、删除或改变真实外部系统。超出清单、组织制度或专业能力的部分，应交给更合适的工具与人员。

7. 失败或结果异常时怎样处理？

失败时先停止继续扩大影响，保存输入、日志、差异、任务标识和当前状态，判断外部系统是否已经局部生效。能够回滚时恢复到已验证版本；异步任务优先查询原任务，避免重复创建、发送或扣费。若失败源于信息不足或清单与项目冲突，应退回澄清和方案选择，而不是无上限重试。恢复时优先利用原任务、备份和日志，避免重复动作扩大损失。

8. 如何验收结果并判断是否可信？

验收要基于真实文件、测试结果、页面状态、指标或目标系统记录。抽查正常路径与边界案例，确认名称、数量、权限、时间、链接关系和格式均符合约定；高风险结论应由人工复核。未能实际运行或访问的部分必须明确标记为待验证，不能用推断替代证据。无法实测的环节必须如实说明，不能把建议包装成已完成事实。