企业官网建设流程全解析

claude-code-action 文档准确性审查子代理（documentation-accuracy-reviewer）设计与实战指南

【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action

本篇技术指南围绕开源仓库 claude-code-action 内置的 Claude Code 子代理 documentation-accuracy-reviewer 展开，系统讲解该子代理的定位、触发场景、frontmatter 配置、五大审查维度与结构化输出规范。读者将掌握如何在实现新功能、修改公共 API 或准备代码评审/发布时，利用该子代理对代码注释、README、API 文档进行逐项核验，并了解它如何与仓库中的review-pr命令及多个同级子代理协作，形成完整的文档质量保障闭环。

子代理定位：让文档审查从"人肉比对"走向自动化核验

documentation-accuracy-reviewer是 claude-code-action 仓库在.claude/agents/目录下定义的五个子代理之一，其角色声明为"具有代码文档标准、API 文档最佳实践与技术写作深厚专业知识的专家级技术文档审查者（expert technical documentation reviewer）"。它的核心职责可以概括为一句话：确保代码文档准确反映实现细节，并为开发者提供清晰、有用的信息。

该子代理并非泛泛的"校对员"，而是以代码实现为唯一事实来源（source of truth）做交叉核验：文档说什么，代码就必须做什么；代码改了什么，文档就必须同步更新。这种"文档 ↔ 实现"双向校验的机制，正是它在功能实现、API 变更、发布准备等节点发挥作用的基础。

何时触发：description 中的三类典型场景

子代理 frontmatter 中的description字段明确规定了使用时机与示例，是 Claude Code 进行工具/代理路由判断的关键输入。按文档原文，应在以下场景后使用该子代理：

• 实现需要文档更新的新功能之后：例如用户说"我刚添加了一个包含多个公共方法的新认证模块"，助手应响应"让我使用 documentation-accuracy-reviewer 子代理核验你这个新认证模块的文档是否完整准确"；
• 修改了既有 API 或函数之后：例如"请审查我刚写的支付处理函数的文档"；
• 完成一段需要文档审查的完整代码块之后，或在准备代码评审/发布（prepare code for review/release）时。

此外，当用户完成一个功能实现后，助手也会主动发起："现在功能已完成，我将使用 documentation-accuracy-reviewer 子代理确保所有文档准确且最新（up-to-date）"。可见该子代理被设计为随开发节奏滚动触发的常态检查项，而不是发布前的一次性动作。

仓库中 review-pr 命令 则展示了它被编排使用的典型路径：该命令使用Bash(gh pr comment:*)、Bash(gh pr diff:*)、Bash(gh pr view:*)三类工具获取 PR 上下文，然后依次启动code-quality-reviewer、performance-reviewer、test-coverage-reviewer、documentation-accuracy-reviewer、security-code-reviewer五个子代理，要求它们"只提供值得注意的反馈（only provide noteworthy feedback）"，最后由主代理汇总筛选后再以行内评论或顶层评论的形式输出。这意味着文档准确性审查是仓库 PR 评审流水线的固定一环。

frontmatter 配置解析：从 YAML 元数据看子代理运行机制

与 Claude Code 生态中其他子代理一致，该文件以 YAML frontmatter 声明元数据，正文则是系统提示词（system prompt）。各字段含义如下：

值得注意的两点实现细节：

1. 工具集与审查流程的匹配：Grep/Glob/Read用于定位并通读源码与文档，WebFetch/WebSearch用于必要时核对外部参考资料，TodoWrite用于把多文件审查拆解为可追踪任务，BashOutput/KillBash用于查看或终止后台命令输出。这套组合使子代理具备"先检索、再精读、后核验"的完整能力。
2. inherit模型的含义：子代理不引入额外的模型开销，直接复用当前会话模型，这与仓库内其余子代理（如 code-quality-reviewer、security-code-reviewer）保持一致，表明该子代理的价值在于精确的任务提示词（prompt）分工而非模型差异。

审查维度一：代码文档分析（Code Documentation Analysis）

该维度聚焦源码内嵌文档的质量，核心检查项如下：

• 公共接口文档完整性：核验所有公共函数（public functions）、方法（methods）和类（classes）是否具备恰当的文档注释（documentation comments）；
• 参数描述准确性：检查参数描述是否与实际参数类型和用途一致，防止"文档说 string，代码传 number"之类的错位；
• 返回值文档真实性：确保返回值文档准确描述代码实际返回的内容，包括返回类型与语义；
• 示例可执行性：验证文档中的示例能否在当前实现下真正运行——这是最容易被忽视也最影响开发者体验的一环；
• 边界与错误条件：确认文档是否覆盖了边界情况（edge cases）和错误条件（error conditions）；
• 过期注释清理：检查是否存在引用了已删除或已修改功能的过时注释（outdated comments）。

从源码结构看，这一维度与 claude-code-action 的仓库形态高度契合：项目主体为 TypeScript 编写的 GitHub Action（核心编排见 src/entrypoints/run.ts），涉及大量公共输入参数、MCP 工具方法与 GitHub API 封装（如 src/github/api/client.ts、src/mcp/github-file-ops-server.ts）。任何对这些公共接口的签名、默认值或行为的改动，都属于该维度应审查的范围。

审查维度二：README 核验（README Verification）

README 是开发者接触项目的第一入口，该维度要求对 README 做全面交叉比对：

• 内容交叉引用：将 README 内容与实际已实现的功能逐一对照，剔除"文档有、代码无"的夸大描述；
• 安装说明时效性：核验安装指引是否当前、完整、可复现；
• 使用示例与 API 同步：检查使用示例是否反映当前 API 形态；
• 功能清单真实性：确保特性列表准确对应实际可用功能；
• 配置项一致性：验证 README 中记录的配置项与实际代码中的参数定义一致；
• 遗漏识别：找出 README 尚未记录的新增功能。

对 claude-code-action 而言，仓库根目录的 README.md 与 base-action/README.md（后者对应独立发布的@anthropic-ai/claude-code-base-action，据 CLAUDE.md 记载其公共 API 不可破坏）都是该维度的重要审查对象。同时，docs 目录下还维护着一组结构化文档（docs/usage.md、docs/configuration.md、docs/setup.md、docs/security.md、docs/migration-guide.md、docs/faq.md、docs/solutions.md 等），README 与这些文档之间的相互引用和口径统一，也属于核验范围。

审查维度三：API 文档审查（API Documentation Review）

当项目对外暴露 API（HTTP 端点或 SDK 接口）时，该维度提供如下检查清单：

• 端点描述匹配：核验端点描述与实际实现是否一致；
• 请求/响应示例准确性：检查示例中的请求与响应是否符合真实行为；
• 认证要求正确性：确保认证需求被准确记录。对 claude-code-action 而言，这直接对应 src/github/token.ts 中实现的令牌优先级逻辑（用户提供的github_token输入优先于 GitHub App OIDC 令牌，claude_code_oauth_token与anthropic_api_key则面向 Claude API 而非 GitHub）；
• 参数类型、约束与默认值核验：参数的类型、取值范围、是否必填、默认值都需与实现一致；
• 错误响应文档：确认错误响应文档与实际错误处理逻辑相符；
• 废弃端点标记：检查已废弃端点是否被正确标记。

审查维度四：质量标准（Quality Standards）

除事实性核验外，该子代理还承担质量把关职责：

• 标记模糊、含混或误导性的文档（vague, ambiguous, or misleading）；
• 识别公共接口缺失的文档；
• 指出文档与实现之间的不一致；
• 提出清晰度与完整性的改进建议；
• 确保文档遵循项目特定规范——在本仓库中即指 CLAUDE.md 中记载的项目约定，例如"标签模式（tag mode）与代理模式（agent mode）通过prompt输入是否存在来自动检测"、GitHubContext为判别联合类型需先调用isEntityContext(context)再访问实体字段等关键约束。

这里体现了一个重要原则：文档审查不是"有没有写"的二值判断，而是"是否准确、清晰、服务目标读者"的持续改进。子代理明确要求区分"真正的文档问题"与"个人风格偏好"，避免把审查变成风格之争。

审查输出结构：可落地的五段式报告

文档对审查输出格式有明确规范，要求按以下结构组织分析：

1. 总体质量摘要（summary of overall documentation quality）——先给出整体结论；
2. 按类型分类的具体问题清单——按代码注释（code comments）、README、API 文档三类归类；
3. 每个问题的三要素：文件/位置（file/location）、当前状态（current state）、建议修复方式（recommended fix）；
4. 按严重程度排序——区分关键性错误（critical inaccuracies）与次要改进（minor improvements）；
5. 可操作的建议（actionable recommendations）——以行动导向收尾。

该结构保证了三点：结论先行（便于快速判断是否需要处理）、证据可追溯（每个问题都带文件与位置）、优先级明确（先修致命错误再谈润色）。当文档准确且完整时，文档明确要求"清楚地认可这一点"（acknowledge this clearly），而不是为了显得勤勉而强行挑刺；当需要核验特定文件或代码段时，则请求访问相应资源。

在仓库中的协作方式与运行环境

该子代理并非孤立运行，它依赖仓库既有的 Claude Code 工程化配置：

• 命令编排：.claude/commands/review-pr.md 将五个子代理组合为一次完整的 PR 评审，并约束"每个子代理只提供值得注意的反馈"，最终由主代理筛选后再发布；
• 代码风格钩子：.claude/settings.json 配置了PostToolUse钩子，在任何Edit|Write|MultiEdit操作后执行bunx prettier@3.5.3 --no-config --write .，保证文档与代码在提交前已统一格式化——这也是文档审查中"示例可运行、路径可引用"的底层保障之一；
• 同级子代理互补：同目录下的 code-quality-reviewer 关注代码可读性与可维护性、test-coverage-reviewer 关注测试覆盖与测试质量、performance-reviewer 与 security-code-reviewer 分别关注性能与安全，而本文主角则守住"文档准确"这条底线，五个子代理共同覆盖 PR 评审的质量维度；
• 开发验证命令：按 CLAUDE.md 记载，仓库以 Bun 为运行时，可用bun test运行测试、bun run typecheck做类型检查、bun run format/bun run format:check做格式化校验——这些命令同样可作为文档审查中"核验示例可执行性"时的辅助手段。

最佳实践：如何让文档审查真正生效

综合该子代理的提示词设计与仓库工程实践，可以沉淀出四条可复用的操作准则：

1. 以源码为唯一事实来源：任何文档结论都必须能追溯到对应实现；审查时优先调用Grep/Glob/Read定位真实代码，再对照文档逐项核验，而不是凭记忆判断；
2. 按变更粒度触发：新增公共接口、修改函数签名、完成功能块、准备评审/发布，四个节点各触发一次，把审查嵌入开发节奏而非留到大版本发布前；
3. 输出必须带位置与修复建议：只报"文档有误"而没有文件位置与修复方案，对开发者毫无价值；严重度排序（critical vs. minor）决定了处理顺序；
4. 遵守项目规范并避免风格之争：以 CLAUDE.md 等仓库规范为准绳，区分事实错误与个人偏好，准确完整的文档要明确肯定——这既维护了审查可信度，也保证了开发者愿意持续使用这套流程。

总而言之，documentation-accuracy-reviewer是一个以"实现驱动文档、文档服务开发者"为核心理念的专项子代理。它不仅给出了一份可直接复用的技术文档审查清单与输出模板，更通过review-pr命令与仓库的 Claude Code 配置，为 claude-code-action 的每次变更提供了可追溯、可执行、有优先级排序的文档质量保障。

【免费下载链接】claude-code-action项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-action