这篇讲什么
AI agent 第一次改到 prod.config.ts、删掉 .env.local、或”顺手整理”一个 migration 文件之后，你就明白：礼貌的指令并不泛化。这篇是真正能撑住的那套护栏：写进 repo 的规则、文件系统级的 deny list、分支保护、以及让不安全的改动在落地前就能被看见的工作流形状。
这篇适合谁看
把 Cursor、Claude Code、Codex 或任何 agent 类工具的写权限放进真实 repo 的所有人——独立开发者、小团队，尤其是 repo 涉及 secret、infra、生产数据的人。如果你目前唯一的护栏是”我礼貌地拜托 agent”，这篇就是写给你的。
什么时候适合用
第一次让 agent 在真实 repo 上自主跑之前。也包括 agent 改到了不该改的东西之后——那一刻你的规则才会真的被写下来。
开始前准备
- 盘点 repo 里已有的敏感物：
.env*、凭证、infra 配置、migration、部署脚本。列清单。 - 确认
.gitignore已经把 secret 排除——pre-commit hook 看的是 git，不是文件系统。 - 至少装一个 secret 扫描器（
gitleaks、detect-secrets、GitHub secret scanning）。pre-commit hook 形式最稳。 - 选定哪个分支是”仅人类”（通常是
main），规划分支保护强制 review。
具体步骤
- 在
CLAUDE.md/AGENTS.md根目录列禁区路径。 写具体：infra/、migrations/、.env*、secrets/、**/credentials.json。模糊规则（“配置文件小心点”）不泛化。 - 用
.gitignore风格的忽略，或 agent 原生的 ignore 文件（.cursorignore、.claudeignore等），让 agent 连读都读不到。上下文里没有 = 改不到。 - 关键文件强制人工 review ——用 CODEOWNERS 加
main分支保护。agent 可以提议，你来批准。 - 在干净的 tree 上跑 agent（无未提交本地改动），这样
git status显示的全是 agent 的改动，不混。 - 用 pre-commit hook（
gitleaks、pre-commit框架）——agent 和你都漏看时的最后防线。 main开分支保护：必须 PR、必须过 status check、不许 force push、至少一个人工 review。agent 即使想直推也推不上去。
一个具体的 CLAUDE.md 段落
## agent 禁区文件
- .env, .env.*, .env.local, .env.production
- infra/**, terraform/**, k8s/**
- migrations/**
- src/lib/secrets/**
- prisma/schema.prisma（读可以，改必须人工 PR）
- package-lock.json（只允许 `npm install` 改）
- VERSION, CHANGELOG.md（仅人改）
## 禁止的操作
- git push --force, git push --force-with-lease
- 任何已经推到 origin 的分支上的 git rebase
- npm publish, pnpm publish, yarn publish
- 项目根目录的任何 rm -rf具体路径很重要。模糊指导会变成玄学。
为什么”礼貌地拜托”会失败
- agent 跨 session 会重置；口头规则不持久。
- 长上下文会退化；写在顶部的规则可能被回放，中间的规则会被忘。
- 不同 agent（Cursor / Claude Code / Codex）尊重的约定不同。
- 即使有规则，agent 也会给自己找边界例外（“我必须改这个才能修 bug”）。
- 没有执行机制（hook、分支保护）的规则只是建议，不是护栏。
建议的操作流程
护栏（写下的规则 + ignore 文件 + hook + 分支保护）-> 在干净 tree 上跑 agent -> 审 diff -> 人提交或批准 PR -> push。每一层都很便宜，叠在一起就能抓住上一层漏掉的。
FAQ
- 单人开发也要分支保护吗？: 要。它还能拦住凌晨 2 点慌乱中的你自己。
- 如果我希望 agent 改一个本来被保护的文件呢？: 临时去掉规则、做完、恢复规则，分两个独立 step 提交。不要”就这一次”地放宽规则。
- pre-commit hook 的摩擦值得吗？: 你只要泄过一次
.env就觉得值。装上gitleaks然后忘了它。 - 能跑 shell 的 agent 怎么办？: 用沙盒 / 容器；shell 工具只允许 allow-list 命令。永远不让 agent 跑
sudo或生产部署命令。 - AI 项目要 CODEOWNERS 吗？: 要；把
infra/、migrations/、安全敏感文件标成必须人工 reviewer。 - 如果 agent 真的改了被保护的文件？: pre-commit 应当拦住；万一过了，
git revert那个 commit，把路径加进 ignore。别在同一处第二次怪 agent。
容易踩的坑
- 只口头说一次”别动 X”——规则必须写进 repo，否则一个 session 就遗忘。
- 没
CLAUDE.md/AGENTS.md—— agent 每个 session 自己发明约定。 - 在脏 tree 上跑 agent ——你的改动混进 agent 的改动，review 不可能。
- 让 agent 直推——唯一的人工 checkpoint 被绕过。
- 跳过 pre-commit hook ——“我在 review 里抓得住”终究有一次抓不住。
- 模糊规则（“小心一点”）——泛化不可预测；只用具体路径。