technical-documentation

技术文档

目的

编写并审查技术文档，确保文档对人和 Agent 都清晰、可执行且易维护，并涵盖贡献者治理文件和 Agent 指令文件。

使用时机

• 为现有产品/代码库创建或彻底改造文档（brownfield）。
• 构建旨在长期保持准确且可复用的常青文档。
• 审查文档差异，检查结构、清晰度和操作正确性。
• 对整个仓库执行文档审计，既要涵盖治理文件，也要涵盖产品文档面（docs/、README*、.md/.mdx/.mdc、Fern/Sphinx/Mintlify 风格的源文件）。
• 更新或审查 AGENTS.md 和/或 CONTRIBUTING.md，使 Agent 和贡献者的工作流与仓库当前实践保持一致。
• 改进包含贡献说明、问题模板、PR 流程和审查关卡的仓库上手文档。
• 为包含别名指令文件的仓库设计治理文档策略（例如 CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）；如果存在 AGENTS.md，则将其视为规范文件，并将别名保留为兼容入口。
• 诊断 Agent 文件漂移问题，例如团队不得不通过反复提示才能发现缺失文件、命令失效或策略冲突。
• 应用仓库特定的文档覆盖规则，包括现有的 OpenClaw 页面类型、文档 IA、保留和验证规则。

工作流

1. 对任务进行分类：build 或 review；上下文：brownfield 或 evergreen。
2. 尽早盘点完整的文档范围（治理文件 + 产品文档）：AGENTS/CONTRIBUTING/别名文件，以及文档目录、框架源文件和根目录/模块 README。
3. 检测多语言范围（多种语言的 README/文档），并定义所需的一致性级别。
4. 阅读 references/agent-and-contributing.md，了解 Agent 指令和 CONTRIBUTING.md 工作流规则（盘点、规范文件/别名映射、双模式平衡、交付物标准，以及优先级/冲突处理）。
5. 阅读 references/principles.md，了解适用规则集（Matt Palmer 与 OpenAI）。
6. 进行 OpenClaw 文档工作时，在构建/审查手册之前阅读 references/openclaw.md。
7. 对于构建任务，遵循 references/build.md。
8. 对于审查任务，遵循 references/review.md，并主动检测问题，无需等待反复提示。
9. 对于复杂或高风险任务（构建或审查），可以在需要时进行更长时间、更深入且更全面的调查，以确保信心。
10. 如果可用，使用子 Agent 执行范围明确的并行发现/审查工作，然后将结果合并为一份连贯的最终交付物。
11. 当平台/工具选择会影响建议时，使用 references/tooling.md。
12. 主动排查治理文件和文档内容面中的问题；除非明确要求仅提供报告，否则应在同一轮中修复高置信度缺陷。
13. 在 brownfield 模式下，优先确保与当前文档 IA、工具和发布状态兼容。
14. 在 evergreen 模式下，优先考虑长期有效的措辞、更新策略和持久化结构。
15. 返回交付物、验证说明、一致性状态和剩余差距。

子 Agent 编排指南

仓库较大或请求的变更范围广泛时，优先使用子 Agent；对于全仓库、多框架或高冲突工作，默认使用子 Agent。

• inventory-agent -> agents/inventory-agent.md（fast／Claude haiku）：文件／配置发现、覆盖图和缺失路径检查。
• governance-agent -> agents/governance-agent.md（thinking／Claude sonnet）：AGENTS/CONTRIBUTING／别名优先级、冲突和策略偏移。
• docs-framework-agent -> agents/docs-framework-agent.md（thinking／Claude sonnet）：框架配置、相对路径基准以及文件路径与 URL 路径的映射检查。
• synthesis-agent -> agents/synthesis-agent.md（long／Claude opus）：将子 Agent 的输出合并为一个按优先级排序的修复计划和一个统一的优先级模型。

输入

• 文档类型（教程、操作指南、参考或说明）和受众。
• 文件范围或差异范围。
• 文档框架／工具约束（Fern、Mintlify、Sphinx 等）。
• 构建／审查模式以及存量项目／长期维护意图。
• 面向目标 Agent 和人类的兼容性意图。
• 涉及的文档框架载体（例如 Fern、Sphinx、Mintlify、Markdown/MDX/MDC/RST/RSC 文件）。
• 期望的调查深度／时间预算（快速检查与全面审查）。
• 执行模式（可用的 single-agent 或 sub-agent-assisted）。
• 修复模式（默认使用 apply-fixes，或按要求使用 report-only）。
• 多语言范围：事实来源语言、目标语言区域和一致性预期。
• 仓库专用覆盖层约束（如果有）。

输出

• 更新后的草稿或审查发现，并附明确的后续操作。
• 验证说明（检查了什么，以及仍有哪些未完成）。
• 针对长期质量的导航／维护建议。
• 涉及 AGENTS/CONTRIBUTING 时的治理文档对齐摘要。
• Agent 指令载体图（主要文件、别名文件以及 Codex/Claude/Cursor 处理计划）。
• 文档载体覆盖图（审查了 /docs 下的哪些内容、README 层级以及框架专用的源代码树）。
• 自动检测的问题清单及已应用的修复（或明确的仅报告发现）。
• 使用子 Agent 时的委派说明（委派范围以及如何合并发现）。
• 多语言一致性说明（已同步、部分同步并说明理由，或有意保持差异）。
• 使用仓库专用覆盖层时的相关说明。