technical-docs

文档

技术写作、代码化图表和文档生命周期管理。将文档视为代码：进行版本控制、代码检查，并通过 CI 验证。

适用场景：创建或更新技术文档、生成 Mermaid 图表（流程图、ERD、时序图）、审查文档对代码的覆盖情况，或制定风格指南。

不适用场景：撰写营销文案、博客文章，或不与代码放在一起的内容。

快速参考

任务	方法	要点
文档同步审查	git diff main...HEAD + 导出项扫描	对照符号与文档覆盖情况
时序图	Mermaid sequenceDiagram + autonumber	将消息映射到函数调用
ERD	Mermaid erDiagram + 鸟爪表示法	从 Drizzle/Prisma 架构中推导
Git 图	Mermaid gitGraph	统一使用 main/develop/feature 分支
功能发布文档	概述 + 配置 + 示例 + 故障排除	每项新功能都要有检查清单
API 参考	根据 JSDoc/TSDoc 注释生成	切勿手动编写 API 参考文档
风格指南	主动语态 + 现在时 + 直接称呼读者	自然易读，同时表达准确
AI 辅助起草	清点 + 差距分析 + 起草 + 人工审查	AI 起草，人类核验准确性
Markdown 标准	YAML frontmatter + 标注语言的代码块	始终注明代码块语言
复杂图表	拆分为聚焦的子图 + 子图组	每张图限制在 15-20 个节点
README 模板	徽章 + 描述 + 快速入门 + API 链接	用户最先看到的内容；控制在 200 行以内
ADR 格式	状态、背景、决策、后果	编号管理，获批后不可修改
运行手册	症状、诊断、解决、升级处理	面向凌晨 3 点的突发事件编写；避免歧义

常见错误

错误	正确做法
使用静态图片绘制技术图表	在 Markdown 中直接编写 Mermaid 语法
使用 Agent1 这类通用参与者名称	使用与架构匹配的具体服务或角色名称
手动编写 API 参考文档	根据源代码中的 JSDoc/TSDoc 注释生成
图表有 20+ 个节点且未分组	使用子图对相关节点分组；限制在 15-20 个节点以内
文档引用过时的默认值	运行文档同步审查，将导出项与覆盖情况进行比较
使用“点击此处”作为链接文本	使用描述性锚文本，提升可访问性和清晰度
跳过标题层级	切勿从 H2 跳到 H4；保持层级连续
混用大段文字	使用项目符号、表格和图表，方便快速浏览
架构决策没有 ADR	记录决策的背景、状态生命周期和后果

任务委派

• 扫描代码库，查找未记录的导出项和文档缺口：使用 Explore Agent
• 基于现有代码库生成包含图表的完整文档站点：使用 Task Agent
• 为新项目规划文档架构和信息层级：使用 Plan Agent

如果有 mermaid-diagrams 技能，请将复杂图表的创建和高级 Mermaid 语法问题委派给它。 否则，建议使用：npx skills add oakoss/agent-skills --skill mermaid-diagrams 如果有 tldr-expert 技能，请将摘要和简要内容的编写委派给它。

参考资料

• 写作风格 -- 语气、风格、格式规则、错误消息指南和结构标准
• Mermaid 图表 -- 时序图、ERD、gitgraph、流程图模式，以及反模式和故障排查
• 文档覆盖度 -- 功能清单、差距分析、代码优先和文档优先审查工作流
• AI 协作 -- AI 与人工协作文档工作流、幻觉处理、文档即代码实践
• Markdown 标准 -- Frontmatter、标题、代码块、表格、提示框和链接约定
• 运行手册与入门指南 -- 事故运行手册模板、升级路径和开发者入门指南