为什么没有项目上下文的 AI 代码审查会失败
Source: Dev.to
背景
每一次 AI 代码审查的开场方式都是一样的。
机器人打开你的 PR，扫描差异，标记缺少 try/catch，建议使用更具描述性的变量名，并指出可以对该函数进行记忆化以提升性能。所有这些在技术上都是正确的，但并没有实际帮助。
因为它不知道 fetchUser 是你们团队强制执行的命名约定，错误处理已经交由全局边界处理，或者正确性比性能更重要。机器人从未了解过你的项目。
这不是模型本身的问题，而是上下文问题。
这正是 pi‑reviewer 所解决的——一个 GitHub Action 与 pi TUI 扩展，能够把项目约定带入每一次审查。
在代理看到任何差异行之前，它会先读取：
AGENTS.md或CLAUDE.md—— 你的通用项目约定：命名规则、架构决策、遵循的模式REVIEW.md—— 审查专用规则：必须始终标记的内容、明确要跳过的内容
这些文件中的 Markdown 链接会被递归跟踪。如果 AGENTS.md 链接到 docs/api-conventions.md，该文件也会被内联。代理看到的是完整的全貌，而不仅仅是摘要。
审查指南
始终标记
fetch调用在.json()之前缺少res.ok检查- API 端点未在
/api/v1/下进行版本控制 - 函数命名为
getData、doStuff或其他通用名称
跳过
- 仅格式化的更改
- 对
pi-review.md内的更改
添加项目上下文
Before: the agent flagged a missing type annotation on an internal helper, suggested renaming a variable, and noted a stray console.log.
之前： 代理标记了内部辅助函数缺少类型注解，建议重命名变量，并指出了一个多余的 console.log。
After: it caught an unversioned API endpoint added in the same PR, flagged a fetch call missing the res.ok check — exactly the rule in REVIEW.md, and skipped the formatting‑only change in the generated file, as instructed.
之后： 它捕获了同一 PR 中添加的未版本化的 API 端点，标记了缺少 res.ok 检查的 fetch 调用——正好符合 REVIEW.md 中的规则，并且按照指示跳过了生成文件中的仅格式化更改。
Same model. Same diff. Completely different review.
同一模型。同一差异。审查结果却完全不同。
严重性过滤
并非所有发现都值得同等对待。pi‑reviewer 允许你按严重性过滤，以便专注于重要的内容。
uses: zeflq/pi-reviewer@main
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
pi-api-key: ${{ secrets.PI_API_KEY }}
min-severity: warn将 min-severity: warn 设置后，代理会完全跳过 INFO 级别的建议——无论是生成的内容还是发布到 PR 的内容。你也可以从 GitHub Actions UI 触发手动审查，并即时选择严重性级别。
三层级
- 🔴 CRITICAL – 错误和安全问题
- 🟡 WARN – 逻辑和类型错误
- 🔵 INFO – 风格和建议
Running pi‑reviewer
pi‑reviewer 在 pi 上运行——一个基于终端的编码代理，位于 pi mono 平台之上。一个 PI_API_KEY 可在所有受支持的模型和提供商之间通用。你选择模型，pi 会路由请求。这意味着你不被锁定在单一提供商——可以在不更改工作流的情况下切换模型，审查逻辑保持不变。
它也支持 SSH。如果你的项目位于远程机器上，--ssh 模式让代理直接在远程获取差异并读取你的约定——无需本地副本。
与 Anthropic Code Review 的比较
Anthropic 最近推出了 Code Review，这是一项内置于 Claude Code 的托管 PR 审查服务。它会读取 CLAUDE.md 和 REVIEW.md，并行运行多个专门的代理针对你的完整代码库进行检查，然后在代码中内联发布带有严重性标签的发现。它确实令人印象深刻，但也伴随以下限制：
- 在 Anthropic 基础设施上提供的托管服务
- 需要安装 GitHub App，仅在 Teams 和 Enterprise 计划中可用
- 每次审查费用约为 $15–25
- 仅限 Claude，且无法控制运行位置
pi‑reviewer 在你的 CI 中运行，费用仅为你的 token 使用费用，通过 pi mono 可使用任何模型，只需一个 secret 和一个工作流文件即可。无需 GitHub App，也不需要管理员审批流程。
如果你想在推送之前本地审查——根本不打开 PR——pi TUI 扩展可以让你在终端中使用 /review。
两个工具都会读取你的 CLAUDE.md 和 REVIEW.md。区别在于 它们运行的地点、费用以及你保留的控制程度。
入门指南
npx github:zeflq/pi-reviewer init该命令会生成一个工作流文件。添加你的 PI_API_KEY 密钥。从此之后的每个 PR 都会获得一个了解你项目的审查。
上下文文件 — AGENTS.md、REVIEW.md — 位于你的仓库中。它们受版本控制、团队可编辑，并随项目演进。你对约定的文档记录越完善，审查质量就会越高。
结论
洞察点不在于 AI 能够审查代码，而在于 没有项目上下文 的 AI 审查不过是另一个写得更好的 linter。真正重要的审查是能够了解 为什么 你的代码库会呈现出当前样貌的审查——它会针对这一点检查差异，而不是依据某种通用的“好软件”概念。
上下文就是一切。没有上下文的差异只是噪音。