用途
该技能用于软件项目技术文档的撰写、审阅与结构组织,帮助开发者理解系统、使用 API、遵循操作流程并做出有依据的架构决策。它把工程组织常用的文档归纳为五类,并针对每类给出结构、写法与维护要求。
主要能力
- API 文档:作为参考层,逐项描述端点、参数、响应结构与错误码,要求内容详尽准确;每个端点按顺序包含认证方式、请求体字段表、真实响应示例和错误表。
- 教程:作为学习层,按有序步骤带读者从零走到可用结果,结构包括标题、前置条件、编号步骤、验证方法与后续步骤,强调每一步可复现。
- 架构文档:作为上下文层,说明系统如何组织及为何如此,建议采用 C4 模型分层展开(系统上下文、容器、组件、代码),每层配图并附解释性文字。
- 架构决策记录(ADR):作为历史层,每条记录一次决策的背景、备选方案、所选方案及理由,采用 Michael Nygard 格式,一经接受不可修改;如需推翻,另写新 ADR 取代原记录。
- 运维手册(Runbook):作为行动层,为部署、事件响应、数据迁移等操作提供分步指令,面向压力下的值班工程师,要求每步给出确切命令与预期输出,并包含症状、前置条件、回滚与最后测试时间。
- 文档审阅清单:从准确性、完整性、目标读者、结构、示例、新鲜度和可操作性七个维度检查现有文档。
使用方式
技能在用户需要编写或改进 API 文档、创建教程、撰写 ADR、编写运维手册、记录系统架构、审阅文档、编写 README 或建立团队文档规范时触发;不适用于营销文案、博客和销售内容,也不适用于仅涉及代码注释的场景。使用时应遵循若干原则:面向读者而非作者;优化扫读体验,用标题、列表、表格和代码块让读者在 30 秒内找到所需信息;先给具体示例再解释;文档尽量与代码同仓维护,在 PR 中审阅、在 CI 中检查;一篇文档只承担一个目的。详细模板可查阅 references/ 目录下的 api-docs.md、tutorials.md、architecture-docs.md、adrs.md 和 runbooks.md,仅在任务需要深入细节时加载。
适用场景
适用于工程团队编写 REST、GraphQL、gRPC 接口文档,创建入门教程,记录架构设计与决策,编写部署和事故处理手册,以及建立团队文档标准。
限制
资料未提供该技能的收费、价格、平台支持范围或效果保证等信息。部分内容(如 Mermaid、PlantUML 等图表工具)仅在资料中作为示例提及,未说明具体配置要求。