用途
internal-docs 技能旨在帮助代理撰写、审阅和改进内部工程文档。内部文档是工程组织的连接组织,记录决策(RFC、设计文档)、保存运维知识(运维手册)、从故障中提取教训(事后复盘),并让机构知识可被发现(知识管理)。该技能使代理能够为特定受众起草、审阅和改进清晰、可操作、结构化的内部文档——从两页的 RFC 到详细的事件事后复盘。
触发条件
当用户希望撰写或起草 RFC 或设计文档、需要创建事后复盘或事件审查文档、要求构建运维手册或操作手册、希望组织或构建团队知识库、需要审阅现有内部文档的完整性或清晰度、询问文档模板、格式或最佳实践、想要编写 ADR(架构决策记录)、需要创建入职文档或团队指南时,应触发此技能。
不要触发的场景:面向公众的 API 文档或开发者文档(使用 api-design 技能)、README 文件或开源项目文档(使用代码级文档约定)。
关键原则
- 为读者而写,而非为作者:每份文档的存在都是为了向他人传递知识。确定谁将阅读它(决策者、值班工程师、新员工),并为其需求而构建结构,而非你的思考过程。
- 决策优于描述:最有价值的内部文档捕捉选择背后的“为什么”。只描述解决方案而不解释考虑过的替代方案和权衡的设计文档是不完整的。
- 可操作性是关键:说“调查问题”的运维手册毫无价值。没有具体行动项的事后复盘是演戏。每份文档都应让读者清楚知道下一步该做什么。
- 活文档会衰减:未维护的文档变得危险。每份文档都需要一个所有者和审查节奏,否则应标记明确的过期日期。
- 结构支持略读:工程师不会线性阅读文档。使用标题、TL;DR、表格和标注,使读者能在 30 秒内找到所需内容。
核心概念
内部文档分为四类,每类具有不同的生命周期和受众:
- 决策文档(RFC、设计文档、ADR):提出变更、收集反馈并记录最终决策。流程为草稿、审查、批准/拒绝。受众是需要评估提案的同事和利益相关者。
- 事件文档(事后复盘、事件审查):在出问题后编写。重建时间线、识别根本原因并产生行动项。受众是从失败中学习的更广泛工程组织。无责性是强制要求。
- 运维文档(运维手册、操作手册、SOP):为重复任务或事件响应提供分步程序。受众是凌晨 3 点需要快速修复问题的值班工程师。
- 知识文档(维基、指南、入职文档、团队页面):保存机构知识。受众各异,通常包括新团队成员和跨团队协作者。
常见任务
技能提供了以下任务的模板和指导:
- 起草 RFC:包含标题、作者、状态、日期、审查者、决策截止日期,以及 TL;DR、动机、提案、考虑的替代方案(至少两个)、权衡与风险、发布计划、开放问题等章节。
- 撰写事后复盘:包含事件日期、严重程度、作者、状态、检测时间、解决时间,以及摘要、时间线、根本原因(5 Whys)、促成因素、做得好的地方、做得不好的地方、行动项表格(具体、分配、有日期)。
- 创建运维手册:包含所有者、最后验证日期、预计时间、风险级别,以及何时使用、先决条件、步骤(精确命令或 UI 操作、预期输出、失败处理)、回滚、升级路径。
- 编写 ADR:轻量级、不可变的单一架构决策记录,包含状态、日期、决策者、背景、决策、后果。ADR 是仅追加的,若决策被逆转,编写新的 ADR 取代旧的。
- 审阅现有文档质量:按顺序检查受众、结构、完整性、可操作性、新鲜度、简洁性。
- 组织知识库:围绕教程、操作指南、参考、解释四个类别(改编自 Divio)构建团队知识,按类别、团队和系统标记文档。
适用场景
适用于工程团队内部的技术决策沟通、故障后学习、运维程序标准化、团队知识沉淀和新人入职等场景。特别适合需要结构化模板和最佳实践指导的文档工作。
限制
不适用于面向公众的 API 文档、开发者文档、README 文件或开源项目文档。技能中提到的参考文件(references/rfcs-and-design-docs.md 等)仅在需要深入细节时加载。首次激活时会检查伴随技能安装情况,并提供安装命令:npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>。