写文档最怕什么？辛辛苦苦写完，结果被同事挑出一堆格式错误、语气不对甚至代码示例跑不通的毛病。这不仅尴尬，还浪费了大量的 Code Review 时间。Review Docs Agent 就是为了解决这个问题诞生的，它不像普通的拼写检查工具那样弱智，而是通过模拟“风格”和“内容”两个资深编辑，对你的文档进行地毯式轰炸审查。
核心功能
这个 Agent 的设计非常精妙，它引入了并行评估和状态追踪机制，把文档审查变成了流水线作业：
- 双核并行审查：启动时会自动分身成两个 Sub-Agent。Style Agent 负责死磕可读性（Readability）和语气（Voice），确保没有 AI 味和复杂的长难句；Content Agent 负责核对完整性（Completeness）和准确性（Accuracy），它甚至会去读取你的源代码文件，核对文档里的 API 调用是否正确！
- 状态文件追踪（State File）：这是它最强的地方！它会在暂存区生成一个 `review-tracker.md`，记录每一个发现的问题（Pending）、已修复的问题（Fixed）和误报（Wont-fix）。这意味着它有“记忆”，不会反复纠结同一个你已经确认过没问题的地方。
- 自动迭代闭环：发现问题后，它不仅能提出修改建议，还能自动执行修复，然后再次验证（Verify），直到所有评分达标。
适用平台
该 Skill 完美适配当前主流的 AI 编程助手，是提升文档质量的必备外挂。无论你使用的是 Cursor、GitHub Copilot、Claude Code，还是 OpenAI Codex、Gemini Code Assist，甚至是国内的 文心快码、腾讯云 CodeBuddy、华为云 CodeArts，都能通过挂载此 Agent 实现自动化的文档审查与修复。它能显著增强 IDE 对项目文档规范的理解能力，让 AI 替你完成繁琐的校对工作。
实操代码示例
Review Docs 最核心的逻辑在于它的状态追踪文件，以下是它自动生成的追踪报告格式，一目了然：
# Review tracker: [filename]
| ID | Issue | Type | Status | Round | Notes |
| --- | --- | --- | --- | --- | --- |
| 1 | 语气过于被动，建议改为主动语态 | Style | pending | 1 | 违反 writing-guide.md |
| 2 | API 参数缺少 'timeout' 说明 | Completeness | fixed | 1 | 已根据源码补充 |
| 3 | 示例代码中的导入路径错误 | Accuracy | verified-fixed | 2 | 经核对已修正 |优势分析
相比于单纯让 ChatGPT 帮你“润色文档”，Review Docs 的优势在于工程化和准确性：
- 拒绝瞎编：普通的 AI 可能会为了通顺而篡改技术细节。Review Docs 的 Content Agent 被强制要求读取源代码（Source Code）来验证文档中的 Claims，确保技术准确性。
- 避免死循环：通过 State File 机制，它清楚地知道哪些问题已经修过了，哪些问题是用户决定“不修”的，不会像无头苍蝇一样反复提出相同的愚蠢建议。
- 评分量化：每次审查都会给出具体的维度评分（如 Readability: 8/10），让你直观看到文档质量的提升曲线。
应用场景
- 开源项目维护：当有 Contributor 提交 PR 时，自动运行此 Agent 审查文档变动，确保风格统一，减轻 Maintainer 的负担。
- API 文档撰写：写完接口文档后，让它自动去对比后端代码，检查参数列表、返回值示例是否与代码实现一致，防止文档滞后。
- 新人入职指引：用它来扫描内部 Wiki 或 Onboarding 文档，确保术语准确、链接有效，给新人留下专业的印象。
最佳实践
想要发挥这个 Agent 的最大威力，建议在使用前配置好你的“红宝书”。你需要在项目中放置 `.claude/skills/shared/writing-guide.md`（写作风格指南）和 `docs-guide.md`（文档结构指南）。Review Docs 会严格遵循这些规则进行打分。例如，如果你讨厌“赋能”、“抓手”这类词，写进指南里，它就会铁面无私地把它们全部揪出来。此外，对于涉及到代码逻辑的文档，务必确保 Agent 有权限读取你的 `src` 或 `packages` 目录，这样它的准确性审查才能生效。为了拥有一套如此完善的文档自动化工作流，建议直接使用 Skill优仓 获取并部署该 Agent，让机器帮你搞定繁琐的校对工作。
暂无评论内容