文档里的代码到底能不能跑？让 AI 自动替你测一遍

文档里写的代码到底能不能跑？让 AI 自动替你跑一遍

你一定见过这种情况：打开一个开源项目的文档，照着示例敲命令，结果跑不起来——文档写的是 `psql`，实际应该用 `psql -h localhost`；文档说「先跑这个脚本」，实际上还缺一个环境变量。

这种「文档和实际代码脱节」的问题，每个工程师都遇到过，而且几乎每个开源项目都有。Supabase 最近在他们的 Agent Skills 里放了一个新 Skill，叫 test-the-docs，专门解决这个问题——它会帮你自动执行文档里的代码片段，验证文档是不是真的准确。

它是怎么工作的？

底层靠 Docker Compose 起一个临时沙盒环境，里面跑一个 runner 容器加上完整的 Supabase 本地栈（通过 `supabase start`）。然后逐条执行文档里的代码片段，对每条命令验证：

• 命令是否能成功执行（exit code = 0）
• 输出是否符合预期
• 是否有报错或超时

跑完之后生成一份验证报告，标注哪些示例通过了、哪些失败了，并给出具体错误原因。这份报告可以直接作为 PR 的一部分，reviewer 看到就知道「文档有没有被测过」。

为什么这个思路值得注意？

传统的文档测试依赖人工——维护者自己跑一遍示例，或者等用户报告「文档写错了」。这个 Skill 把这个流程自动化了，而且是在一个完全隔离的沙盒里跑，不污染本地环境，测完直接销毁。

对于维护者来说，这意味着：

• 每次文档更新（尤其是 CLI/SQL 示例），可以自动验证准确性
• PR review 时，reviewer 不需要自己跑一遍示例来验证文档
• 新贡献者写的文档示例，也会自动被检查

适用场景

• 开源项目维护者：确保文档示例始终和代码同步，减少用户「按文档跑不通」的抱怨
• 内部工具团队：验证内部工具的 README 和使用示例是否准确
• 技术文档工程师：作为文档质量检查流程的一部分

安装方式

需要先 clone Supabase 的 agent-skills 仓库，然后指定 Skill 路径安装：

git clone https://github.com/supabase/agent-skills.git
# 然后在 Claude Code 里通过 skills CLI 安装
npx skills add supabase/agent-skills --skill test-the-docs

也可以直接用 `/plugin install` 命令从 GitHub 安装。

需要本地有 Docker 和 Docker Compose 环境，因为整个验证过程是在容器里跑的。首次运行会拉取镜像，大约需要几分钟，之后每次运行会复用已有镜像。

如果你经常维护技术文档，或者在一个文档质量要求高的团队里，这个 Skill 可以帮你把「文档验证」从人工变成了自动化的流水线。

GitHub：https://github.com/supabase/agent-skills

相关 Skill：test-the-docs（来自 supabase/agent-skills，★110.9k，MIT License，更新 2026-09-22）

GitHub: https://github.com/supabase/agent-skills