documentation-and-adrs

documentation-and-adrs skill 概览

documentation-and-adrs skill 是做什么的

documentation-and-adrs skill 用于帮助智能体编写以“决策”为核心的技术文档，尤其适合产出 Architecture Decision Records（ADR）。它真正要解决的并不是“多写一点文档”，而是“把团队为什么选择这个方案、当时有哪些约束、又放弃了哪些备选方案”记录下来。这样一来，当代码本身不足以解释后续维护决策时，documentation-and-adrs skill 就会特别有价值。

哪些用户和场景最适合使用

这个 skill 最适合工程师、技术负责人、架构师，以及围绕架构、API、基础设施、认证、数据模型或面向用户的功能变更进行 Technical Writing 的团队。需要为未来的工程师或智能体保留可持续复用的上下文，而不只是为眼前任务写一份“看起来完整”的说明时，就应该用 documentation-and-adrs。

它和通用提示词有什么不同

普通提示词也许能生成一份条理清晰的总结，但 documentation-and-adrs skill 的重点是“决策记录”：背景、约束、选项、权衡与结果影响。这种框架之所以重要，是因为很多质量不高的文档都只描述“怎么实现”，却没有写清未来维护者真正需要的“为什么这样做”。

什么时候不建议安装

如果你只是想补一点行内代码注释、做轻量 README 整理，或者给一次性原型写文档，那么没必要安装这个 skill。对于那些意图已经被实现本身表达得非常清楚、也没有实际决策历史需要保留的代码路径，它同样不适合。

如何使用 documentation-and-adrs skill

安装入口与优先阅读内容

进行 documentation-and-adrs install 时，从 addyosmani/agent-skills 仓库添加这个 skill，然后优先阅读 skills/documentation-and-adrs/SKILL.md。这个 skill 只附带一份指导文件，没有辅助脚本，也没有可参考的额外文件可借力。因此，相比那些有工具链支撑的 skill，它更依赖你输入信息的质量。

如果你的环境支持安装 skill，可使用：
npx skills add addyosmani/agent-skills --skill documentation-and-adrs

然后查看：

• skills/documentation-and-adrs/SKILL.md

documentation-and-adrs skill 需要什么输入

这个 skill 在你提供“决策面”而不只是“想要什么格式”时效果最好。高质量输入通常包括：

• 正在提议的变更
• 受影响的系统或 API
• 约束条件，例如性能、合规、成本、截止时间或兼容性
• 已考虑过的备选方案
• 预期后果与风险
• 目标读者和输出位置，例如 docs/adr/ 或 docs/architecture/

较弱的输入示例：“Write an ADR for moving to GraphQL.”

更强的输入示例：

• Current state: REST API with versioning pain across mobile clients
• Decision needed: whether to adopt GraphQL for new product surfaces
• Constraints: keep existing REST endpoints for 12 months, small platform team, need field-level client flexibility
• Alternatives: improved REST conventions, tRPC, GraphQL gateway
• Decision owner: platform lead
• Output: ADR with status, context, decision, consequences, and rejected alternatives

如何编写提示词，提升 documentation-and-adrs skill 的使用效果

一个好的 documentation-and-adrs usage 提示词，既要要求输出结构，也要要求推理质量。比较稳妥的写法是：

1. 明确说明要记录的决策或文档类型。
2. 提供项目背景和约束条件。
3. 写明考虑过哪些选项。
4. 要求智能体显式梳理权衡、假设和后续动作。
5. 指定目标输出格式。

示例提示词：
“Use the documentation-and-adrs skill to draft an ADR for choosing an authentication strategy for our B2B SaaS. Compare hosted auth, self-managed OAuth, and passkeys-first. Include context, constraints, decision drivers, rejected options, consequences, migration notes, and open questions. Audience is future backend and security engineers.”

适合真实团队的推荐工作流

如果你想要一套真正能落地的 documentation-and-adrs guide 工作流，建议按这个顺序来：

1. 从 issues、PR、架构笔记和团队聊天记录中收集事实。
2. 先让智能体提取决策驱动因素，再开始起草。
3. 审看第一版，重点查漏：是否遗漏了备选方案，是否有未写明的约束。
4. 将输出整理成仓库内文档或 ADR，并使用稳定的命名和固定位置。
5. 等决策在生产环境中得到验证后，再更新记录。

这个 skill 在搭配具体源材料时，非常适合用于 Technical Writing；但如果你希望它凭空推断从未在任何地方记录过的业务动机或架构理由，它的效果会明显变差。

documentation-and-adrs skill 常见问题

documentation-and-adrs 适合 Technical Writing 新手吗？

适合，前提是新手已经能拿到决策背后的事实信息。这个 skill 能为 ADR 和决策文档提供很有用的结构，但它不能替代技术判断。对新手来说，最好的使用方式通常不是“从零直接生成一篇文档”，而是提供会议记录、issue 链接，或一份粗略的优缺点清单。

它和直接让模型“写文档”有什么区别？

通用的文档提示词通常优先优化可读性；documentation-and-adrs 优先优化“决策的可维护性”：为什么选这条路、当时有什么约束、未来读者在改动前需要知道什么。对于架构设计、公开 API 和基础设施选型，这种差异尤其关键。

这个 skill 的边界在哪里？

这个 skill 不是覆盖整个仓库的文档系统，不是 style linter，也不是带自动化能力的文档生成器。它提供的是流程与结构上的指导，而不是由工具强制执行的脚本或模板。如果你需要自动同步文档、规范校验或发布工作流，还需要在它之外搭配其他工具。

什么时候不该使用 documentation-and-adrs skill？

不要把它用于琐碎的实现细节、显而易见的重构、重复性的代码注释，或没有长期价值的探索性原型。如果团队其实还没有做出真正的决策，那么可以用这个 skill 来比较选项，但不要在决策尚未落定时，假装已经存在一份最终 ADR。

如何改进 documentation-and-adrs skill 的效果

提供“可支撑决策”的输入，而不是“只够做总结”的输入

想提升 documentation-and-adrs skill 输出质量，最快的方法就是提供足以支撑决策的证据。把被否决的选项、关键约束和预期后果都写进去。缺少这些信息时，产出往往会显得措辞成熟，但内容空泛。如果可以，最好补充 design docs、PR 描述、RFC 或事故复盘里的相关片段。

留意常见失败模式

最常见的问题包括：

• 反复描述实现细节，却没有记录决策依据
• 只是罗列备选方案，却没有解释它们为什么落选
• 漏掉风险、迁移成本或运维层面的后果
• 文档只写给当前评审者看，而不是写给未来维护者看

如果你发现了这些问题，可以要求它按“decision drivers, rejected alternatives, and downstream consequences”这个重点重写。

第一稿之后再迭代结构，而不是全部推倒重来

完成第一版后，最好让智能体针对薄弱部分做增强，而不是整篇重写。常见且有效的追问包括：

• “Make the tradeoffs more explicit.”
• “Add assumptions and what would change this decision.”
• “Separate immediate consequences from long-term maintenance impact.”
• “Rewrite for future engineers unfamiliar with this subsystem.”

按你的仓库规范来适配这个 skill

想让 documentation-and-adrs for Technical Writing 更贴合实际使用，就把你的文件命名规则、ADR 格式和文档存放路径明确告诉智能体。比如，说明你是使用类似 docs/adrs/0007-auth-strategy.md 这样的顺序编号 ADR，还是使用放在 docs/architecture/ 下的主题式文档。你的提示词越贴近仓库现有的文档约定，生成后需要手工清理和调整的工作就越少。