OpenClaw 技术文档评审 Playbook从仓库治理文件到文档站的全链路审查方法【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库内置的文档评审技能 .agents/skills/technical-documentation/references/review.md 为主线完整拆解其文档评审 Playbook如何界定评审范围、如何主动发现问题、如何分别审查 AGENTS.md/CONTRIBUTING.md 治理面与产品文档面以及如何输出分级结论。读完你能掌握一套可直接落地的文档全仓审计流程并结合仓库中真实的符号链接、docs 校验脚本和子代理编排来理解每一步的底层支撑。评审前先读什么Playbook 的位置与前置依赖review.md 本身是technical-documentation技能的审查分支入口第一行即要求先读principles.md再套用本清单Readprinciples.mdfirst, then apply this checklist。技能总入口 SKILL.md 规定了完整工作流先分类任务build或review再判定上下文是brownfield存量仓库改造还是evergreen追求长期保鲜的文档尽早盘点全量文档范围治理文件 产品文档检测多语言范围并定义一致性等级依次读取 references/principles.md治理规则集、references/agent-and-contributing.mdAGENTS/CONTRIBUTING 规则若涉及 OpenClaw 文档工作还需先读 references/openclaw.md构建任务走references/build.md评审任务走references/review.md并且要求主动发现问题不要等反复提示输出评审发现 校验说明 遗留缺口。评审所依据的原则来自 references/principles.md它合并了三套规则Matt Palmer 的更好文档的 8 条规则为人写作、为 Agent 优化funnel 结构what/why → quickstart → next steps用 Diataxis 搭骨架等、OpenAI cookbook 的质量约束示例自包含、不教不安全模式、术语精确而非生僻等以及一条冲突时的合并优先级读者任务成功 结构清晰 长期可维护性 Agent 优化。这条优先级直接决定了后文很多检查项的取舍。第 1 步范围界定与分类Scope and classificationPlaybook 的第一章要求在任何评审动作之前先回答四个问题文档类型与目标读者这是教程、how-to、参考还是解释写给谁看OpenClaw 的 overlay openclaw.md 进一步把页面类型细化为 Overview / Quickstart / Topic page / Guide / API-SDK-CLI reference / Testing guide / Troubleshooting / Governance file 八类并强调写作或评审之前先选定页面类型brownfield 还是 evergreen 意图决定后续是兼容现有文档 IA信息架构还是追求无时代感的表述与持久结构对应 Playbook 第 8、9 章读者的预期结果读者读完要完成什么任务全仓评审时必须同时覆盖两个面治理面governance surfaces即 AGENTS/CONTRIBUTING 及别名文件与产品文档面product-doc surfacesdocs/、各级 README 树、.md/.mdx/.mdc、.rst/.rsc、各文档框架的配置。最后一条对 OpenClaw 尤其重要如果目标文档属于 OpenClaw 文档体系还要叠加references/openclaw.md的页面类型、docs IA、内容保全preservation与校验检查。第 2 步调查行为准则Investigation behaviorPlaybook 对评审者的调查姿态给出了明确行为约束这也是该技能区别于普通读一遍给意见的关键主动发现不要等用户反复提示要主动找问题与风险发现更深问题的信号时继续深挖允许长耗时调查为保证置信度与正确性长时间、大规模的调查是被明确允许的SKILL.md 第 9 条同样重申善用子代理做有界并行发现例如文件盘点file-inventory、命令验证command validation、跨文档一致性检查最后合并为一个统一的问题集合无问题也要显式声明如果没找到问题要明说并指出残余风险或校验缺口默认apply-fixes模式对高置信度的文档缺陷默认在同一轮直接修复除非用户明确要求report-only不停留在 AGENTS/CONTRIBUTING 检查当任务是文档全量评审时必须继续深入到 docs 内容与文档框架两个面。OpenClaw 仓库为这条准则提供了现成的子代理实现位于 agents/ 目录四个代理各有职责与预算frontmatter 中可见model与maxTurns子代理文件模型/轮次预算职责inventory-agentinventory-agent.mdhaiku / 6 轮文件与配置发现、覆盖面映射、缺失路径检测governance-agentgovernance-agent.mdsonnet 级 / thinkingAGENTS/CONTRIBUTING/别名的优先级、冲突与策略漂移docs-framework-agentdocs-framework-agent.mdsonnet 级 / thinking框架配置、相对路径基线、文件路径与 URL 路径映射检查synthesis-agentsynthesis-agent.mdopus / 12 轮合并各子代理输出为一份去重、分优先级的行动计划这正对应 principles.md 中子代理输出必须归一化为单一一致的结论集的执行策略——并行发现单点收敛。第 3 步治理面审查Governance surface reviewPlaybook 第 3 章规定治理面的审查以 references/agent-and-contributing.md 为唯一事实来源source of truth覆盖文件清单、规范/别名映射与优先级冲突处理。审查要点按对象分组对 AGENTS.md确认 persona 意图、作用域、命令/工具边界是显式的frontmatter 风格若存在需符合仓库惯例存在预期时必须有Always总是、Ask first先询问、Never绝不三类行为边界要求给出具体命令示例与仓库内真实路径避免歧义。OpenClaw 仓库根部的 AGENTS.md 是一个典型的电报体治理文件开篇声明 Telegraph style. Root rules only. Read scopedAGENTS.mdbefore subtree work.即根文件只放硬性策略与路由子目录各自再放 scopedAGENTS.md。从源码结构看仓库内docs/、extensions/、scripts/下确实各有一层 scopedAGENTS.md与根文件的路由声明相互印证。对 CONTRIBUTING.mdissue/PR 工作流必须完整且可操作本地环境搭建、lint/test 命令、评审标准必须准确不能写死已失效的命令治理规则不得与嵌套的 AGENTS 指令冲突过大的文件要拆分成带链接的分节文档如工具专项 setup 与 release 文档。参考文件 agent-and-contributing.md 的CONTRIBUTING size and scope control一节进一步要求根CONTRIBUTING.md聚焦 setup、issue 流、PR 流、测试与评审门槛用 issue/PR 模板链接代替把全部流程细节内联过长就按领域拆分并从根文件链接内容大时优先迁入 docs 站Mintlify/Fern/Sphinx 工作流同时面向 Agent/机器可读性优化。Agent 平台感知与符号链接审计Playbook 还要求审查不同 Agent 平台如何消费这些文件面向 Cursor/Claude 这类基于 glob 的消费方引用要最小化、有界避免大路径集合膨胀上下文面向 Codex 的指引使用显式文件引用与确定性命令两个面必须表达同一个共享策略内核命令、边界、优先级而非分叉的指引审计.agents/.cursor兼容行为验证规范规则目录与符号链接状态是否符合仓库策略、符号链接目标完整性、即使存在.cursor兼容层AGENTS.md对 Codex 仍是规范引用检查跨 agent 与 contributor 文件的重复策略导致的上下文膨胀、规则冲突、技能与 agent 指令冲突检查 agent 指令与代码库不一致的信息、缺失或被引用的文件例如被命名为规范入口的 README/index 不存在、setup/命令漂移不存在的安装命令、本应模块级却写在根级的命令。这一点在 OpenClaw 仓库中可以实际验证仓库根目录存在CLAUDE.md - AGENTS.md的符号链接这正是 agent-and-contributing.md 所述canonical 存在时别名为兼容层策略的落地——AGENTS.md为唯一权威CLAUDE.md只是指向它的软链。该参考文件给出的规范布局是.agents/为规范规则目录、.cursor - .agents符号链接供 Cursor 自动加载、AGENTS.md作为规范策略文档OpenClaw 的 AGENTS.md 第 22 行规则也与之呼应NewAGENTS.md: add siblingCLAUDE.mdsymlink; editAGENTS.mdonly.新增 AGENTS.md 时加同名 CLAUDE.md 软链只编辑 AGENTS.md。第 4 步产品文档面审查Product documentation surface review第 4 章把镜头从治理文件转到面向用户的文档IA 覆盖核对根目录/各模块README*文件与docs/**树的文档信息架构是否完整框架原生源评审范围内的 Fern、Mintlify、Sphinx、MkDocs 等框架源确认指引与实际的事实来源文件一致逐文件检查.md/.mdx/.mdc/.rst/.rsc中的过时命令、缺失前置条件、断裂的交叉链接引用有效性确认被引用的文档路径与锚点真实存在可发现性标记应该拆分/合并以提升可发现性与可维护性的文档。对 OpenClaw 文档还有两条专项检查检查 docs/docs.jsonMintlify 站点配置、docs-list 路由提示、主路径 vsReference分区的放置、以及生成式参考页的可见性对 OpenClaw 文档的重写或分页要求有源证据的 keep/drop/move/destination 覆盖——即每条重要声明、警告、示例、命令、字段与排障事实都要能映射到保留/删除/移动的源证据。OpenClaw 仓库把第 1 点落成了可执行命令。package.json 中定义了一组 docs 校验脚本与 openclaw.md 的Validation一节列出的最小证明集一一对应pnpm docs:list # node scripts/docs-list.js文档清单与路由 pnpm docs:check-mdx # node scripts/check-docs-mdx.mjs docs README.md pnpm docs:check-links # node scripts/docs-link-audit.mjs pnpm docs:check-links:anchors # 同上加 --anchors校验锚点 pnpm docs:check-i18n-glossary # 术语表一致性 pnpm docs:check-config-examples # 文档中的配置示例核对 pnpm docs:map:gen # 生成带标题的文档映射openclaw.md 的校验原则是选择能覆盖所动面的最窄证明改导航跑docs:list/docs:check-links改 MDX 跑docs:check-mdx文档声称运行时行为时还要跑行为测试或命令探针如果被阻塞要明确写出哪条命令没跑、为什么。此外还有git diff --check兜底空白与冲突标记问题。第 5 步框架配置与路径映射检查Framework config and path mapping第 5 章解决评审中最常见的假阳性/假阴性来源——路径基准问题先检测并读取框架配置Fern 配置、Sphinxconf.py、Mintlify 配置或等价物路径解析必须以它为准相对引用要相对于声明它的文件/配置解析而不是相对于当前工作目录——这与本指南开篇对文档内相对链接必须换算为仓库根相对路径的要求同构文件系统路径与发布后的 URL 路由是两张独立的映射表两张都要验证显式标记路径映射漂移并用三类标准措辞missing file文件不存在、stale route路由指向已移动内容、wrong base path基路径解析错了。这三类标签让不同评审者输出的问题可以直接归并避免链接坏了这类无法执行的模糊描述。第 6 步结构审查Structural review第 6 章从读者动线角度检查文档骨架Funnel 检查文档是否具备 what/why → quickstart → next steps 的漏斗结构对应 principles.md 中 Matt Palmer 的第 2 条规则标题流与导航可发现性heading 层级是否支持读者跳过与回跳关键内容不得被困在图片或埋没的段落里——对人和 Agent 都是死路Diataxis 对齐教程/操作/参考/解释四象限不得混装混合目的的小节要拆开OpenClaw 文档必须匹配 openclaw.md 中显式的页面类型——先定类型再检查结构。openclaw.md 还为 Topic page 与 Guide 两类给出了具体形状可作为结构审查的对照清单Topic page 八段式命名实体的标题 → 无标题开场说明是什么/拥有什么/不拥有什么 → 仅在有账号/版本/权限依赖时才写 Requirements → 带最小可靠验证的 Quickstart → 任务关键选项内联、穷尽细节链接到参考页 → 按读者意图组织子主题 → 可观察失败与具体检查的 Troubleshooting → 相关链接Guide 九段式以结果命名的标题 → 说明读者能达成什么 → Before you begin → 仅在读者必须抉择时给Choose a path → 动词开头的步骤 命令 预期输出 检查 → 最小可靠测试 → 生产就绪安全/重试/限额/可观测性/迁移/清理 → 紧贴工作流的排障 → See also。第 7 步写作质量审查Writing quality review第 7 章是行文层面的四连检段落简洁、可扫读消除模糊代词与未定义术语它、该模块这类指代必须能唯一解析示例可执行且范围正确能复制即跑不引入未声明的依赖openclaw.md 进一步规定示例要一个概念单元一个代码块 语言标记围栏、占位符用尖括号命名如API_KEY、展示预期成功输出、绝不暴露真实密钥语气指令化、技术性、不空泛directive, technical, non-hand-wavy。第 8/9 步Brownfield 与 Evergreen 双模式第 8、9 章SKILL.md 把brownfield与evergreen作为任务分类的必选项Playbook 则为两种模式分别给出了检查重点Brownfield存量改造模式——兼容性优先与现有文档 IA 和约定兼容锚点、重定向、跨文档链接保持有效标记对 onboarding 与任务完成路径的回归术语变更要有意识地传播改了术语就全仓同步而不是只改一处。Evergreen长期保鲜模式——耐老化优先标记带日期戳但没有版本范围的脆弱表述例如目前不支持 X却不写截至哪个版本检查所有权与刷新信号是否在场谁负责、多久刷新、过期如何检测——对应 tooling.md 中 evergreen 一节Capture ownership, update cadence, and stale-content detection rules确保常规产品演进后建议仍然成立标记缺失的弃用/迁移指引。tooling.md 的brownfield 下优先兼容现平台、用现成组件先于引入新范式与只在现约束阻塞关键结果时才提迁移是这两个模式在平台选型上的延伸。第 10 步工具与平台审查Tooling and platform review第 10 章要求平台适配不确定时先读tooling.md对应 references/tooling.md。它把选型检查点归纳为六项现有栈锁定不为小收益强推迁移、API 工作流深度生成式参考、OpenAPI 支持、可测试性、协作模型docs-as-code、评审工作流、版本化、运行时质量搜索、导航、可复制代码块、AI 就绪度结构化内容、稳定 URL、机器友好且人可读、人类就绪度阅读复杂度、导航深度、少行话。评审时的三个动作检查内容是否有效使用平台原语tabs、callouts、endpoint 块等标记技术上正确但在所选平台上难以扫读的文档只有当平台化改进能降低认知负荷时才推荐。第 11 步多语言一致性审查Multilingual parity review第 11 章适用于存在多语言文档的仓库检查点为确认声明的事实来源语言与预期的一致性策略跨语言对比变更章节检查步骤/顺序/警告漂移同一操作在两种语言下步骤数或顺序不同即为漂移标记前置条件、版本说明、限额与安全指引的缺失更新仅当理由显式且用户影响低时才允许有意分歧当某语言版本一致性为部分时要求读者可见的状态说明。principles.md 的Multilingual parity rule是它的原则版本对任务关键内容步骤、警告、前置条件、限额目标是跨语言一致做不到完全一致就发布显式的一致性状态与同步意图。OpenClaw 侧的落地工具之一是pnpm docs:check-i18n-glossarypackage.json用于核对多语言术语表漂移。第 12 步输出格式Output formatPlaybook 规定评审交付物固定为三段顺序不可调换Blocking issues阻断项文件 要求的修复每条必须可执行精确到文件与动作Non-blocking improvements非阻断改进Validation notes校验说明已做 vs 未做done vs pending。SKILL.md 的 Outputs 一节在此之上要求交付完整的评审包更新稿或评审发现含明确下一步、校验说明查了什么、剩了什么、导航/维护建议、涉及 AGENTS/CONTRIBUTING 时的治理对齐摘要、agent 指令面地图主文件、别名文件、Codex/Claude/Cursor 处理方案、文档面覆盖图/docs、README 层级、框架源树各审了什么、自动发现的问题清单及已应用修复或 report-only 结论、使用子代理时的委派说明、多语言一致性注记、以及使用了仓库 overlay 时的 overlay 说明。Validation notes与 openclaw.md被阻塞就写明哪条命令没跑、为什么的要求合起来保证了每次评审的证据边界是可见、可复核的。小结把 Playbook 落到 OpenClaw 仓库把 12 个章节串起来OpenClaw 的文档评审流程可以概括为先定类型与模式第 1 章→ 带着主动调查姿态与子代理开工第 2 章→ 分治治理面与产品面第 3、4 章路径基准见第 5 章→ 结构与文字质量收口第 6、7 章→ 按 brownfield/evergreen 与平台适配补查第 8–10 章→ 多语言一致性第 11 章→ 三段式输出第 12 章。在 OpenClaw 仓库内这套 Playbook 不是纸面规范治理面的canonical 别名软链策略可直接对照根目录CLAUDE.md - AGENTS.md与 AGENTS.md 的路由规则产品面的引用存在性 锚点检查由 scripts/docs-link-audit.mjs 与 scripts/check-docs-mdx.mjs 等脚本自动化OpenClaw 特有的页面类型、保全矩阵与最小校验集则固化在 references/openclaw.md。对维护者而言遵循该 Playbook 做文档变更等价于在 PR 中同时回答了审了什么、按什么标准审、还剩什么没验证三个问题。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw 技术文档评审 Playbook：从仓库治理文件到文档站的全链路审查方法
OpenClaw 技术文档评审 Playbook从仓库治理文件到文档站的全链路审查方法【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库内置的文档评审技能 .agents/skills/technical-documentation/references/review.md 为主线完整拆解其文档评审 Playbook如何界定评审范围、如何主动发现问题、如何分别审查 AGENTS.md/CONTRIBUTING.md 治理面与产品文档面以及如何输出分级结论。读完你能掌握一套可直接落地的文档全仓审计流程并结合仓库中真实的符号链接、docs 校验脚本和子代理编排来理解每一步的底层支撑。评审前先读什么Playbook 的位置与前置依赖review.md 本身是technical-documentation技能的审查分支入口第一行即要求先读principles.md再套用本清单Readprinciples.mdfirst, then apply this checklist。技能总入口 SKILL.md 规定了完整工作流先分类任务build或review再判定上下文是brownfield存量仓库改造还是evergreen追求长期保鲜的文档尽早盘点全量文档范围治理文件 产品文档检测多语言范围并定义一致性等级依次读取 references/principles.md治理规则集、references/agent-and-contributing.mdAGENTS/CONTRIBUTING 规则若涉及 OpenClaw 文档工作还需先读 references/openclaw.md构建任务走references/build.md评审任务走references/review.md并且要求主动发现问题不要等反复提示输出评审发现 校验说明 遗留缺口。评审所依据的原则来自 references/principles.md它合并了三套规则Matt Palmer 的更好文档的 8 条规则为人写作、为 Agent 优化funnel 结构what/why → quickstart → next steps用 Diataxis 搭骨架等、OpenAI cookbook 的质量约束示例自包含、不教不安全模式、术语精确而非生僻等以及一条冲突时的合并优先级读者任务成功 结构清晰 长期可维护性 Agent 优化。这条优先级直接决定了后文很多检查项的取舍。第 1 步范围界定与分类Scope and classificationPlaybook 的第一章要求在任何评审动作之前先回答四个问题文档类型与目标读者这是教程、how-to、参考还是解释写给谁看OpenClaw 的 overlay openclaw.md 进一步把页面类型细化为 Overview / Quickstart / Topic page / Guide / API-SDK-CLI reference / Testing guide / Troubleshooting / Governance file 八类并强调写作或评审之前先选定页面类型brownfield 还是 evergreen 意图决定后续是兼容现有文档 IA信息架构还是追求无时代感的表述与持久结构对应 Playbook 第 8、9 章读者的预期结果读者读完要完成什么任务全仓评审时必须同时覆盖两个面治理面governance surfaces即 AGENTS/CONTRIBUTING 及别名文件与产品文档面product-doc surfacesdocs/、各级 README 树、.md/.mdx/.mdc、.rst/.rsc、各文档框架的配置。最后一条对 OpenClaw 尤其重要如果目标文档属于 OpenClaw 文档体系还要叠加references/openclaw.md的页面类型、docs IA、内容保全preservation与校验检查。第 2 步调查行为准则Investigation behaviorPlaybook 对评审者的调查姿态给出了明确行为约束这也是该技能区别于普通读一遍给意见的关键主动发现不要等用户反复提示要主动找问题与风险发现更深问题的信号时继续深挖允许长耗时调查为保证置信度与正确性长时间、大规模的调查是被明确允许的SKILL.md 第 9 条同样重申善用子代理做有界并行发现例如文件盘点file-inventory、命令验证command validation、跨文档一致性检查最后合并为一个统一的问题集合无问题也要显式声明如果没找到问题要明说并指出残余风险或校验缺口默认apply-fixes模式对高置信度的文档缺陷默认在同一轮直接修复除非用户明确要求report-only不停留在 AGENTS/CONTRIBUTING 检查当任务是文档全量评审时必须继续深入到 docs 内容与文档框架两个面。OpenClaw 仓库为这条准则提供了现成的子代理实现位于 agents/ 目录四个代理各有职责与预算frontmatter 中可见model与maxTurns子代理文件模型/轮次预算职责inventory-agentinventory-agent.mdhaiku / 6 轮文件与配置发现、覆盖面映射、缺失路径检测governance-agentgovernance-agent.mdsonnet 级 / thinkingAGENTS/CONTRIBUTING/别名的优先级、冲突与策略漂移docs-framework-agentdocs-framework-agent.mdsonnet 级 / thinking框架配置、相对路径基线、文件路径与 URL 路径映射检查synthesis-agentsynthesis-agent.mdopus / 12 轮合并各子代理输出为一份去重、分优先级的行动计划这正对应 principles.md 中子代理输出必须归一化为单一一致的结论集的执行策略——并行发现单点收敛。第 3 步治理面审查Governance surface reviewPlaybook 第 3 章规定治理面的审查以 references/agent-and-contributing.md 为唯一事实来源source of truth覆盖文件清单、规范/别名映射与优先级冲突处理。审查要点按对象分组对 AGENTS.md确认 persona 意图、作用域、命令/工具边界是显式的frontmatter 风格若存在需符合仓库惯例存在预期时必须有Always总是、Ask first先询问、Never绝不三类行为边界要求给出具体命令示例与仓库内真实路径避免歧义。OpenClaw 仓库根部的 AGENTS.md 是一个典型的电报体治理文件开篇声明 Telegraph style. Root rules only. Read scopedAGENTS.mdbefore subtree work.即根文件只放硬性策略与路由子目录各自再放 scopedAGENTS.md。从源码结构看仓库内docs/、extensions/、scripts/下确实各有一层 scopedAGENTS.md与根文件的路由声明相互印证。对 CONTRIBUTING.mdissue/PR 工作流必须完整且可操作本地环境搭建、lint/test 命令、评审标准必须准确不能写死已失效的命令治理规则不得与嵌套的 AGENTS 指令冲突过大的文件要拆分成带链接的分节文档如工具专项 setup 与 release 文档。参考文件 agent-and-contributing.md 的CONTRIBUTING size and scope control一节进一步要求根CONTRIBUTING.md聚焦 setup、issue 流、PR 流、测试与评审门槛用 issue/PR 模板链接代替把全部流程细节内联过长就按领域拆分并从根文件链接内容大时优先迁入 docs 站Mintlify/Fern/Sphinx 工作流同时面向 Agent/机器可读性优化。Agent 平台感知与符号链接审计Playbook 还要求审查不同 Agent 平台如何消费这些文件面向 Cursor/Claude 这类基于 glob 的消费方引用要最小化、有界避免大路径集合膨胀上下文面向 Codex 的指引使用显式文件引用与确定性命令两个面必须表达同一个共享策略内核命令、边界、优先级而非分叉的指引审计.agents/.cursor兼容行为验证规范规则目录与符号链接状态是否符合仓库策略、符号链接目标完整性、即使存在.cursor兼容层AGENTS.md对 Codex 仍是规范引用检查跨 agent 与 contributor 文件的重复策略导致的上下文膨胀、规则冲突、技能与 agent 指令冲突检查 agent 指令与代码库不一致的信息、缺失或被引用的文件例如被命名为规范入口的 README/index 不存在、setup/命令漂移不存在的安装命令、本应模块级却写在根级的命令。这一点在 OpenClaw 仓库中可以实际验证仓库根目录存在CLAUDE.md - AGENTS.md的符号链接这正是 agent-and-contributing.md 所述canonical 存在时别名为兼容层策略的落地——AGENTS.md为唯一权威CLAUDE.md只是指向它的软链。该参考文件给出的规范布局是.agents/为规范规则目录、.cursor - .agents符号链接供 Cursor 自动加载、AGENTS.md作为规范策略文档OpenClaw 的 AGENTS.md 第 22 行规则也与之呼应NewAGENTS.md: add siblingCLAUDE.mdsymlink; editAGENTS.mdonly.新增 AGENTS.md 时加同名 CLAUDE.md 软链只编辑 AGENTS.md。第 4 步产品文档面审查Product documentation surface review第 4 章把镜头从治理文件转到面向用户的文档IA 覆盖核对根目录/各模块README*文件与docs/**树的文档信息架构是否完整框架原生源评审范围内的 Fern、Mintlify、Sphinx、MkDocs 等框架源确认指引与实际的事实来源文件一致逐文件检查.md/.mdx/.mdc/.rst/.rsc中的过时命令、缺失前置条件、断裂的交叉链接引用有效性确认被引用的文档路径与锚点真实存在可发现性标记应该拆分/合并以提升可发现性与可维护性的文档。对 OpenClaw 文档还有两条专项检查检查 docs/docs.jsonMintlify 站点配置、docs-list 路由提示、主路径 vsReference分区的放置、以及生成式参考页的可见性对 OpenClaw 文档的重写或分页要求有源证据的 keep/drop/move/destination 覆盖——即每条重要声明、警告、示例、命令、字段与排障事实都要能映射到保留/删除/移动的源证据。OpenClaw 仓库把第 1 点落成了可执行命令。package.json 中定义了一组 docs 校验脚本与 openclaw.md 的Validation一节列出的最小证明集一一对应pnpm docs:list # node scripts/docs-list.js文档清单与路由 pnpm docs:check-mdx # node scripts/check-docs-mdx.mjs docs README.md pnpm docs:check-links # node scripts/docs-link-audit.mjs pnpm docs:check-links:anchors # 同上加 --anchors校验锚点 pnpm docs:check-i18n-glossary # 术语表一致性 pnpm docs:check-config-examples # 文档中的配置示例核对 pnpm docs:map:gen # 生成带标题的文档映射openclaw.md 的校验原则是选择能覆盖所动面的最窄证明改导航跑docs:list/docs:check-links改 MDX 跑docs:check-mdx文档声称运行时行为时还要跑行为测试或命令探针如果被阻塞要明确写出哪条命令没跑、为什么。此外还有git diff --check兜底空白与冲突标记问题。第 5 步框架配置与路径映射检查Framework config and path mapping第 5 章解决评审中最常见的假阳性/假阴性来源——路径基准问题先检测并读取框架配置Fern 配置、Sphinxconf.py、Mintlify 配置或等价物路径解析必须以它为准相对引用要相对于声明它的文件/配置解析而不是相对于当前工作目录——这与本指南开篇对文档内相对链接必须换算为仓库根相对路径的要求同构文件系统路径与发布后的 URL 路由是两张独立的映射表两张都要验证显式标记路径映射漂移并用三类标准措辞missing file文件不存在、stale route路由指向已移动内容、wrong base path基路径解析错了。这三类标签让不同评审者输出的问题可以直接归并避免链接坏了这类无法执行的模糊描述。第 6 步结构审查Structural review第 6 章从读者动线角度检查文档骨架Funnel 检查文档是否具备 what/why → quickstart → next steps 的漏斗结构对应 principles.md 中 Matt Palmer 的第 2 条规则标题流与导航可发现性heading 层级是否支持读者跳过与回跳关键内容不得被困在图片或埋没的段落里——对人和 Agent 都是死路Diataxis 对齐教程/操作/参考/解释四象限不得混装混合目的的小节要拆开OpenClaw 文档必须匹配 openclaw.md 中显式的页面类型——先定类型再检查结构。openclaw.md 还为 Topic page 与 Guide 两类给出了具体形状可作为结构审查的对照清单Topic page 八段式命名实体的标题 → 无标题开场说明是什么/拥有什么/不拥有什么 → 仅在有账号/版本/权限依赖时才写 Requirements → 带最小可靠验证的 Quickstart → 任务关键选项内联、穷尽细节链接到参考页 → 按读者意图组织子主题 → 可观察失败与具体检查的 Troubleshooting → 相关链接Guide 九段式以结果命名的标题 → 说明读者能达成什么 → Before you begin → 仅在读者必须抉择时给Choose a path → 动词开头的步骤 命令 预期输出 检查 → 最小可靠测试 → 生产就绪安全/重试/限额/可观测性/迁移/清理 → 紧贴工作流的排障 → See also。第 7 步写作质量审查Writing quality review第 7 章是行文层面的四连检段落简洁、可扫读消除模糊代词与未定义术语它、该模块这类指代必须能唯一解析示例可执行且范围正确能复制即跑不引入未声明的依赖openclaw.md 进一步规定示例要一个概念单元一个代码块 语言标记围栏、占位符用尖括号命名如API_KEY、展示预期成功输出、绝不暴露真实密钥语气指令化、技术性、不空泛directive, technical, non-hand-wavy。第 8/9 步Brownfield 与 Evergreen 双模式第 8、9 章SKILL.md 把brownfield与evergreen作为任务分类的必选项Playbook 则为两种模式分别给出了检查重点Brownfield存量改造模式——兼容性优先与现有文档 IA 和约定兼容锚点、重定向、跨文档链接保持有效标记对 onboarding 与任务完成路径的回归术语变更要有意识地传播改了术语就全仓同步而不是只改一处。Evergreen长期保鲜模式——耐老化优先标记带日期戳但没有版本范围的脆弱表述例如目前不支持 X却不写截至哪个版本检查所有权与刷新信号是否在场谁负责、多久刷新、过期如何检测——对应 tooling.md 中 evergreen 一节Capture ownership, update cadence, and stale-content detection rules确保常规产品演进后建议仍然成立标记缺失的弃用/迁移指引。tooling.md 的brownfield 下优先兼容现平台、用现成组件先于引入新范式与只在现约束阻塞关键结果时才提迁移是这两个模式在平台选型上的延伸。第 10 步工具与平台审查Tooling and platform review第 10 章要求平台适配不确定时先读tooling.md对应 references/tooling.md。它把选型检查点归纳为六项现有栈锁定不为小收益强推迁移、API 工作流深度生成式参考、OpenAPI 支持、可测试性、协作模型docs-as-code、评审工作流、版本化、运行时质量搜索、导航、可复制代码块、AI 就绪度结构化内容、稳定 URL、机器友好且人可读、人类就绪度阅读复杂度、导航深度、少行话。评审时的三个动作检查内容是否有效使用平台原语tabs、callouts、endpoint 块等标记技术上正确但在所选平台上难以扫读的文档只有当平台化改进能降低认知负荷时才推荐。第 11 步多语言一致性审查Multilingual parity review第 11 章适用于存在多语言文档的仓库检查点为确认声明的事实来源语言与预期的一致性策略跨语言对比变更章节检查步骤/顺序/警告漂移同一操作在两种语言下步骤数或顺序不同即为漂移标记前置条件、版本说明、限额与安全指引的缺失更新仅当理由显式且用户影响低时才允许有意分歧当某语言版本一致性为部分时要求读者可见的状态说明。principles.md 的Multilingual parity rule是它的原则版本对任务关键内容步骤、警告、前置条件、限额目标是跨语言一致做不到完全一致就发布显式的一致性状态与同步意图。OpenClaw 侧的落地工具之一是pnpm docs:check-i18n-glossarypackage.json用于核对多语言术语表漂移。第 12 步输出格式Output formatPlaybook 规定评审交付物固定为三段顺序不可调换Blocking issues阻断项文件 要求的修复每条必须可执行精确到文件与动作Non-blocking improvements非阻断改进Validation notes校验说明已做 vs 未做done vs pending。SKILL.md 的 Outputs 一节在此之上要求交付完整的评审包更新稿或评审发现含明确下一步、校验说明查了什么、剩了什么、导航/维护建议、涉及 AGENTS/CONTRIBUTING 时的治理对齐摘要、agent 指令面地图主文件、别名文件、Codex/Claude/Cursor 处理方案、文档面覆盖图/docs、README 层级、框架源树各审了什么、自动发现的问题清单及已应用修复或 report-only 结论、使用子代理时的委派说明、多语言一致性注记、以及使用了仓库 overlay 时的 overlay 说明。Validation notes与 openclaw.md被阻塞就写明哪条命令没跑、为什么的要求合起来保证了每次评审的证据边界是可见、可复核的。小结把 Playbook 落到 OpenClaw 仓库把 12 个章节串起来OpenClaw 的文档评审流程可以概括为先定类型与模式第 1 章→ 带着主动调查姿态与子代理开工第 2 章→ 分治治理面与产品面第 3、4 章路径基准见第 5 章→ 结构与文字质量收口第 6、7 章→ 按 brownfield/evergreen 与平台适配补查第 8–10 章→ 多语言一致性第 11 章→ 三段式输出第 12 章。在 OpenClaw 仓库内这套 Playbook 不是纸面规范治理面的canonical 别名软链策略可直接对照根目录CLAUDE.md - AGENTS.md与 AGENTS.md 的路由规则产品面的引用存在性 锚点检查由 scripts/docs-link-audit.mjs 与 scripts/check-docs-mdx.mjs 等脚本自动化OpenClaw 特有的页面类型、保全矩阵与最小校验集则固化在 references/openclaw.md。对维护者而言遵循该 Playbook 做文档变更等价于在 PR 中同时回答了审了什么、按什么标准审、还剩什么没验证三个问题。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考