technical-documentation

技术文档

目的

编写、审阅和审计清晰、明确且易于维护的技术文档，供人类和 Agent 使用。涵盖产品文档、贡献者治理文件和 Agent 指令文件。正文遵循简明技术英语，避免读者或 Agent 产生误解。通过分片、对抗性检查和并行修复，将审计扩展到包含数百个页面的文档树。

适用场景

• 在现有产品或代码库中创建或全面改造文档（棕地项目）。
• 构建长期准确且可重复使用的常青文档。
• 审阅文档差异，检查其结构、清晰度和操作正确性。
• 对整个代码库的治理文件和产品文档进行全面审计（包括 docs/、README*、.md/.mdx/.mdc、Fern/Sphinx/Mintlify/MkDocs 源文件）。
• 审计大型或杂乱的文档树：数百个页面、超过 20k 个字符的页面、令人困惑的导航、多种语言环境或糟糕的阅读体验。
• 将晦涩或含糊的英语改写为简明技术英语，适用于操作步骤、参考页面、错误消息、工具描述、AGENTS.md 和 CONTRIBUTING.md。
• 更新或审阅 AGENTS.md 和/或 CONTRIBUTING.md，使 Agent 和贡献者工作流与当前代码库实践保持一致。
• 为包含别名指令文件的代码库设计治理文档策略（CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）。
• 诊断 Agent 文件偏差问题：团队需要反复编写提示词，才能发现缺失文件、失效命令或策略冲突。

证据和产物

• 常规的限定范围审阅和审计结果保留在聊天或标准输出中。默认不要创建报告文件、台账或分片目录。
• 只有在交付内容有明确要求，或大型审计、任务续接或交接有具体需要时，才创建持久化证据。写入文件前，说明其使用者和用途。
• 对于必须保留的证据，统一使用一个由任务专用的位置。大型或可续接的工作流需要相关约定时，应保留覆盖范围、去重、日志和恢复方面的约定。
• 无论调查结果是直接呈现还是写入文件，都要报告覆盖范围和缺口。减少持久化并不意味着减少调查。

工作流

1. 将任务分类为 build、review、audit 或 rewrite，并将上下文分类为 brownfield 或 evergreen。
2. 尽早梳理请求涉及的文件、目录或差异范围。对于覆盖整个文档的工作，还要纳入治理文档和产品文档。仓库大小本身不会扩大已限定的审查范围。
3. 检测多语言范围并定义所需的对等程度。
4. 阅读 references/agent-and-contributing.md，了解 Agent 指令和 CONTRIBUTING.md 规则。
5. 阅读 references/principles.md，了解适用的规则集（Matt Palmer、OpenAI 和 ASD-STE100）。
6. 在撰写或改写任何正文之前，阅读 references/simplified-technical-english.md。按文件选择 Strict 或 STE 风格模式。
7. 如果委派有帮助且存在 Agent 工具，则使用 sub-agent-assisted；否则使用 single-agent。当范围需要拆分，或用户请求 Workflow 时，阅读 references/workflows.md。只有在用户明确同意且有可用的 Workflow 工具时，才使用 workflow。
8. 对于 build 任务，遵循 references/build.md。
9. 对于 review 任务，遵循 references/review.md 并主动检测问题。
10. 当请求的审计范围需要拆分时，遵循 references/large-docs-audit.md。先运行第 0 轮机械扫描和仓库原生验证器，再按字符预算拆分，并完整审计范围内的每个页面。按分块批量执行对抗性检查。持续进行后续轮次，直到连续两轮没有发现新问题；报告每轮新增的问题数量，不要声称已收敛。切勿为了适应消息长度而提前结束审计。
11. 对于 rewrite 任务，先运行 scripts/ste-lint.py，按照 STE 流程改写，然后再次运行该检查。不得增加严重违规项。除非用户要求提供规则表，否则只返回改写后的文本。
12. 对于大规模修复，编辑前先使用 references/pr-program.md 将问题清单归类到 PR 中，然后按阶段顺序提交。
13. 当平台或工具选择会影响建议时，使用 references/tooling.md。
14. 在请求范围内主动全面排查问题。除非用户要求只报告问题，否则在同一轮中修复有充分把握的问题。
15. 在 brownfield 模式下，优先兼容现有文档信息架构、工具和发布状态。在 evergreen 模式下，优先采用历久弥新的措辞和持久的结构。
16. 返回交付内容以及验证说明、覆盖范围、对等状态和剩余差距。

子 Agent 编排指南

当请求的工作范围较广时，优先委派。对于覆盖整个仓库、多框架或冲突较多的工作，默认使用委派。

• inventory-agent -> agents/inventory-agent.md（haiku）：文件／配置发现、覆盖范围图、缺失路径检查。
• ste-lint-agent -> agents/ste-lint-agent.md（haiku）：按分片建立确定性的 STE lint 基线。
• governance-agent -> agents/governance-agent.md（sonnet）：AGENTS/CONTRIBUTING/别名优先级、冲突、策略偏移。
• docs-framework-agent -> agents/docs-framework-agent.md（sonnet）：框架配置、相对路径基准、文件路径与 URL 路径映射。
• verify-agent -> agents/verify-agent.md（sonnet）：对一项发现进行对抗性反驳。
• docs-ux-audit-agent -> agents/docs-ux-audit-agent.md（fable）：完整阅读一个分片并审查读者体验，输出台账。
• ste-rewrite-agent -> agents/ste-rewrite-agent.md（fable）：在保留含义的前提下，按 Strict 或 STE 风格重写。
• remediation-agent -> agents/remediation-agent.md（fable）：将已验证的发现应用于一个文件，并重新运行验证器。
• synthesis-agent -> agents/synthesis-agent.md（fable）：将输出合并为一份按优先级排序的修复计划。

使用 Claude Workflows（references/workflows.md）时，审计模板会为每个分片运行 docs-ux-audit-agent，并为每个分片批量运行一次 verify-agent，随后进行综合整理和完整性审查。逐项发现并行调用验证器，是这些运行耗尽会话容量的主要原因，因此验证应保持批量处理，并限定范围。修复模板会针对每个文件运行 remediation-agent，并由审查者跟进。只有在用户选择加入后，才启动 Workflow。

输入

• 文档类型（教程、操作指南、参考文档、说明文档）和目标读者。
• 文件范围、目录范围或差异范围。
• 文档框架／工具限制（Fern、Mintlify、Sphinx、MkDocs 等）。
• 任务模式（build、review、audit、rewrite）以及现有项目／长期维护意图。
• 每个文件的 STE 模式（strict 或 flavored），也可由技能根据文档类型推断。
• 目标 Agent 和人类兼容性意图。
• 所需调查深度（快速检查、全面检查）。在请求范围内，审计默认采用全面检查。
• 执行级别（workflow、sub-agent-assisted、single-agent）以及是否选择加入 Workflow。
• 修复模式（默认 apply-fixes，或 report-only）。
• 持久化证据的用途和路径；仅在 证据和产物 要求时提供。需要大型审计台账时，在审计根目录使用 .audit/ledger.jsonl。
• 多语言范围：事实来源语言、目标地区语言、内容一致性预期。

输出

• 更新后的草稿、改写后的文本，或附有明确后续操作的审查发现。
• 验证说明（已检查内容、尚未处理内容），包括 STE lint 前后的数量。
• 审计覆盖范围说明：按目录列出已阅读页面数与范围内页面总数。
• 带状态计数的发现（未解决、已验证、已反驳、已修复、不予处理）；默认以内联形式呈现，或写入所需台账。
• 超长页面的拆分计划，以及导航／信息架构变更清单。
• AGENTS/CONTRIBUTING 有改动时，提供治理文档一致性摘要。
• Agent 指令表面映射（主文件、别名文件、Codex/Claude/Cursor 处理计划）。
• 请求范围内的文档表面覆盖图（/docs、README 层级、框架源目录）。
• 委派说明：使用的 Agent 或 Workflow 运行 ID、委派范围、发现的合并方式。
• 各轮发现数量及收敛情况说明。
• 任务涉及大规模修复时，提供 PR 计划。
• 多语言一致性说明（同步、部分同步并说明原因，或有意保持差异）。

流程

stateDiagram-v2
    [*] --> ScopeInventoryAndRules
    ScopeInventoryAndRules --> SelectMode
    state SelectMode <<choice>>
    SelectMode --> Build: build
    SelectMode --> Review: review
    SelectMode --> RewriteWithLint: rewrite
    SelectMode --> AuditScope: audit
    AuditScope --> InlineAudit: scoped work needs no sharding
    AuditScope --> ShardedAudit: scope requires coverage ledger and shards
    Build --> ValidateAndReport
    Review --> ValidateAndReport
    RewriteWithLint --> ValidateAndReport
    InlineAudit --> ValidateAndReport
    ShardedAudit --> ValidateAndReport
    ValidateAndReport --> [*]
    note right of ShardedAudit
        Workflow tool use requires opt-in.
        Retain evidence only for a declared need.
    end note