给 AI 编码 Agent 写权限前的 5 分钟检查清单

AI 编程 Agent 在代码仓库真正准备好之前，就已经能发挥很大作用。

真正危险的时刻，并不是 Agent 读取代码的时候，而是它可以编辑文件、运行会改变状态的命令，或者准备出一个看起来足够合理、仿佛可以直接合并的变更时。

在授予写入权限之前，先花五分钟完成下面这份预检。

1. 全新检出的代码能否进入可用状态？

明确写下准确的 runtime 版本、依赖安装命令，以及表示成功的预期信号。

如果环境配置依赖口口相传的经验——比如从聊天记录中复制的环境变量、无人记录的全局 package，或者只有某位队友知道如何使用的服务——Agent 就无法可靠地复现环境。

通过条件：新贡献者无需猜测，只需按照代码仓库中的说明操作即可。

2. 是否有快速验证命令？

Agent 需要在变更规模仍然较小时获得反馈。一个需要运行四十分钟的 CI pipeline 很有用，但它并不适合作为实际的内部迭代循环。

记录一条能够在几分钟内发现常见错误的聚焦命令：例如针对性测试、typecheck、lint 任务或小型 build。完整测试套件则作为单独的最终检查保留。

通过条件：代码仓库既有快速的本地检查，也有记录完善的完整验证流程。

3. 是否明确划定了变更边界？

读取文件不等于变更基础设施。安装依赖不等于部署。更新生成的代码也不等于编辑它的源文件。

你的说明应当明确区分：

• 会修改依赖或生成产物的命令；

• 破坏性操作；

• 生产环境、计费和基础设施变更。

通过条件：需要审批的操作被明确列出，而不是靠暗示。

4. 是否将 secrets 和不可信内容视为一等风险？

凭据不仅会通过提交到代码仓库的源文件泄露，也可能通过日志、截图、fixture 和诊断信息泄露。

与此同时，issue、pull request 描述、网页、日志和生成文件中，可能包含看起来像指令的文本。除非可信的代码仓库指南另有说明，否则 Agent 应将这些来源视为数据，而不是指令。

通过条件：代码仓库明确标识了敏感输出，并定义了指令权限边界。

5. 交接内容能否证明实际发生了什么？

“已完成”不是一个有用的结果。

一份可靠的交接说明，应列出修改过的文件、执行过的命令、观察到的结果、跳过的检查，以及仍然存在的不确定性。它应为审查者提供足够的证据，使其能够复现这个结论。

通过条件：你的任务模板或 pull request 模板要求提供验证证据。

将答案转换为评分

为每个方面打 0 到 2 分：

• 1 分：已有文档记录，但内容不完整或尚未验证；

• 2 分：已有文档记录，并且有当前证据支持。

低分并不意味着“永远不要使用 Agent”。它意味着应该先从只读模式或严格监督模式开始，并优先修复最重要的缺口。

我制作了一个免费、完全在浏览器中运行的版本，将这套检查扩展为 20 分制评分。它无需注册账户，也不会上传任何内容：

运行免费的 Agent-Ready Repo Audit

源代码也已在 GitHub 上公开。

如果你想直接获得可以投入实施的文件，而不是从零开始编写每一项策略，Agent-Ready Repo Kit 提供了代码仓库说明、安全防护规则、workflow、交接模板、评分卡，以及一个零依赖 validator。

披露说明：审计工具和代码仓库均免费。最后一个链接指向我销售的产品。本文在 AI 辅助下起草，并在发布前经过审核。

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。