doc-maintenance

文档维护

通过将代码库与现有文档进行对比，系统地审查、整理和修正文档，以发现过时内容、缺失内容和组织混乱的问题。

触发时机

• 合并功能分支或完成重构后
• 依赖升级或 API 变更后
• 新成员入职时对项目文档感到困惑
• 定期维护（每月或每次发布）
• 手动运行 scripts/doc_audit.py 并发现问题时

工作流概览

Phase 1: Audit       → Run deterministic scan + haiku search agents
Phase 2: Triage      → Classify findings by severity and action type
Phase 3: Remediate   → Dispatch specialized agents to fix/create docs
Phase 4: Quality     → docs-architect reviews all changes

---

阶段 1：审查

步骤 1a — 运行确定性扫描

执行随附的审计脚本，获取基准报告：

python3 skills/doc-maintenance/scripts/doc_audit.py

该脚本会生成结构化报告，涵盖：

• 已损坏的内部链接（指向不存在文件的 Markdown [text](path)）
• 孤立文档（没有被其他文档或 README 链接的文件）
• 缺失的必需结构（docs/ 或 manual/ 中缺少预期文件夹或文件）
• 相对于代码已过时的文档（文档所引用的子树自文档上次修改以来发生了显著变更——通过 Git 日志统计文档上次编辑至今的代码提交来衡量，而非依据文档的绝对年龄；后者会导致稳定的架构文档产生噪声）
• 空文件或占位文件（内容少于 3 行）

添加 --json 可生成机器可读的输出。添加 --root PATH 可覆盖项目根目录检测。

步骤 1b — 调度搜索 Agent

完成确定性扫描后，启动子 Agent 进行深入分析。 模型选择根据任务校准：模式枚举使用 haiku，多文件关联与判断使用 sonnet。完整的提示词模板见 references/agent-dispatch.md。

Agent 1 — 代码到文档覆盖扫描（subagent_type: "Explore"，model: "haiku"）： 搜索代码库中的公共 API、CLI 命令、配置架构和导出模块。 通过 grep 检查是否存在对应内容，与现有文档交叉比对。报告所有未记录的内容。 haiku 已足够，因为核心步骤是枚举模式并通过 grep 检查是否存在。

Agent 2 — 文档到代码的新鲜度扫描（subagent_type: "general-purpose"， model: "sonnet"，按文档文件分别调度）： 为范围内的每个 markdown 文件调度一个 sonnet Agent，并提供文件内容。该 Agent 会：(a) 提取所有具体的代码引用（函数名、CLI 标志、文件路径、配置键、API 端点）， (b) 通过 grep / codanna / Read 对照当前代码逐一核实，(c) 将不匹配项报告为 RENAMED / REMOVED / CHANGED。需要使用 sonnet 并按文档文件分别调度，因为新鲜度核验通常需要追踪多个文件（处理程序 → 中间件 → 配置），而要区分已重命名和已移除，需要查看新位置，而不只是确认旧位置已不存在。

Agent 3 — 结构合规扫描（subagent_type: "Explore"，model: "haiku"）： 将当前 docs/ 和 manual/ 布局与 references/folder-structure.md 中规定的文件夹结构进行比较。报告缺失的文件夹、放置不当的文件和命名违规。 这里使用 haiku 很合适——这只是针对规范进行纯模式匹配。

Agent 4a — ASCII 图示检测器（subagent_type: "Explore"，model: "haiku"）： 扫描 markdown，查找制图字符（─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼）、箭头标记 （-->、<--、==>）或包含多个节点的缩进树结构。将每处结果报告为可转换为 Mermaid 图示的候选项，并建议图示类型。这里使用 haiku 很合适， 因为这是机械式模式检测——找出字符并报告位置。

Agent 4b — 缺失图示判断扫描（subagent_type: "general-purpose"， model: "sonnet"，按文档文件分别调度）： 为范围内的每个 markdown 文件调度一个 sonnet Agent。Agent 阅读文档，并标记添加图示可以显著提升理解效果的部分——顺序很重要的多步流程、包含具名组件的架构关系、状态转换、请求/响应序列。关键在于，sonnet 只会在图示比文字说明更有帮助时标记（并非每个步骤列表都需要图示）。 haiku 往往会过度标记（认为每个列表都可以画成图示），或标记不足（漏掉隐含的流程描述）；sonnet 的判断才能确保这类信号可靠。

并行启动 Agent 1、2、3、4a、4b——但 Agent 2 和 4b 会在内部按文档文件分别调度，因此实际调用次数为 2 + (2 × N_docfiles)，而非 5 次。

步骤 1c — 合并结果

将脚本输出与 Agent 的发现合并为一份审计报告。去重重叠的发现。 该报告将作为第 2 阶段的输入。

---

阶段 2：分类

将每项发现归入以下操作类别之一：

类别	说明	示例
过时	文档存在，但引用了过时的代码/行为	CLI 标志已重命名，但文档仍显示旧名称
缺失	应当编写文档的项目没有对应文档	公共 API 端点没有参考文档
孤立	文档存在，但无法访问/没有链接	指南文件未列入任何索引或导航
位置不当	文档存在，但位于错误的文件夹	教程放在 docs/architecture/ 中
无关	文档涉及已删除的功能	已删除功能的指南
结构问题	文件夹结构偏离规定布局	缺少 docs/security/ 文件夹
图表转换	ASCII/文本图表应改为 Mermaid	架构文档中复杂的方框流程图
缺少图表	某个章节可以从图表中受益	仅用文字描述的多步骤流程

分配严重程度：

• P0 — 面向用户的文档存在事实错误（manual/）
• P1 — 开发者文档引用了不存在的代码
• P2 — 缺少公共 API 或功能的文档
• P3 — 结构/组织问题
• P4 — 轻微过时、外观问题

---

阶段 3：修正

将每项发现交给相应的专业 Agent。使用 Task 工具和下方列出的子 Agent 类型。详细提示模板请参阅 references/agent-dispatch.md。

文档类型	子 Agent 类型	目标位置
API 参考文档	reference-builder	docs/reference/ 或 docs/api/
架构文档	technical-writer	docs/architecture/
开发者指南（风格、本地开发、工作流）	technical-writer	docs/development/
测试文档	technical-writer	docs/testing/
安全文档	technical-writer	docs/security/
面向用户的教程	learning-guide	manual/tutorials/
面向用户的操作指南	learning-guide	manual/guides/
面向用户的入门指南	learning-guide	manual/getting-started/
计划和提案	technical-writer	docs/plans/
ASCII 图表转换	mermaid-expert	现有文档内
为文字章节新增图表	mermaid-expert	现有文档内

并行派发： 将相互独立的修正文档任务分组并同时派发。只有在一个文档依赖另一个文档时才按顺序处理（例如，教程链接到某个 API 参考文档，因此需先完成该参考文档）。每批最多并行派发 4 个修正 Agent。

更新现有文档： 向 Agent 提供当前文件内容以及需要修正的具体发现。指示其进行最少且有针对性的编辑。

新建文档： 向 Agent 提供相关源代码、目标文件路径和文件夹结构规范，确保其遵循命名约定。

---

阶段 4：质量门禁

所有修正 Agent 完成后，派发一个 docs-architect Agent 审查所有变更。质量门禁检查：

1. 准确性 — 文档是否与当前代码一致？
2. 完整性 — 是否涵盖所有公共接口？
3. 组织结构 — 文件夹结构是否符合规定布局？
4. 交叉引用 — 所有内部链接是否有效？
5. 一致性 — 语气、格式、标题级别是否一致？
6. 无孤立文档 — 每份新文档是否都链接自索引或父级文档？

如果质量门禁未通过，返回阶段 3，处理标记出的具体问题。最多进行 2 轮修正，之后升级给用户处理。

---

文件夹结构

规定的文件夹布局定义在 references/folder-structure.md 中。摘要如下：

docs/ — 内部/开发者文档

docs/
├── architecture/    — System design, ADRs, component diagrams
├── development/     — Developer guides: style, local setup, issue tracking
├── plans/           — Proposals, RFCs, roadmaps
├── reviews/         — Code review records, audit reports
├── testing/         — Test strategy, coverage reports, test plans
├── reports/         — Generated reports, metrics, analysis
├── security/        — Security policies, threat models, audit findings
├── api/             — Internal API docs (OpenAPI specs, gRPC protos)
├── reference/       — CLI reference, config reference, manpages
├── ideas/           — Exploratory notes, spikes, brainstorms
└── archive/         — Deprecated docs preserved for history

manual/ — 面向用户的文档（项目根目录）

manual/
├── getting-started/ — Installation, quickstart, first steps
├── guides/          — How-to guides for common tasks
├── tutorials/       — Step-by-step learning paths
├── reference/       — User-facing command/config reference
└── troubleshooting/ — FAQ, common errors, known issues

README.md — 项目根目录

主 README 会接受准确性审查，但不会重新组织。有关 README 的发现将作为过时/缺失项报告，以便手动修正。

---

反模式

• 未确认文档所述功能确实已移除前，不要删除文档
• 重组文档时，务必更新所有内部交叉引用
• 不要仅为填充文件夹结构而创建空文件——只创建包含实际内容的文档
• 不要在 docs/ 和 manual/ 之间重复内容——改用链接
• 不要将面向用户的文档移入 docs/，也不要将开发者文档移入 manual/