别让 AI Agent 直接改主分支：开发者使用 Codex / Cursor / Claude Code 的安全工作流

AI 编程工具现在越来越像“能干活的同事”，而不是只会补全几行代码的插件。

Codex 官方文档把它描述为可以读代码、改代码、运行代码的 coding agent；Codex cloud 还可以在自己的云环境里后台处理任务。 Cursor 官方也把自己定位成 coding agent，强调 Agent 可以理解整个代码库，在 Desktop、CLI、Web、Mobile 等场景协作。 Claude Code 官方文档则写得更直接：它可以读取代码库、编辑文件、运行命令，并集成到开发工具里。

这类工具的能力越强，越不能随便用。

很多人用 AI Agent 翻车，不是因为模型不行，而是因为一开始就给了它太大的权限：

# 危险示范
git checkout main
# 然后直接让 Agent：帮我优化一下整个项目

这类指令看起来省事，实际上很容易把风险放大：

• 它可能改到不该改的文件；
• 它可能顺手重构了一堆无关代码；
• 它可能跑了你没预期的命令；
• 它可能把测试改绿了，但业务逻辑改坏了；
• 它可能把一个小 bug 修成一个大 diff。

所以今天不聊“哪个 AI 编程工具最强”，只聊一个更实际的问题：

怎么让 AI Agent 安全地参与开发，而不是直接把主分支交给它。

---

一、先定原则：AI Agent 不能直接碰 main

团队开发里，最基本的一条规则是：
任何 AI 生成的代码，都应该像普通开发者代码一样走分支、测试、Review。

不管你用的是 Codex、Cursor，还是 Claude Code，都不要让它直接在主分支上大范围修改。

推荐流程是：

main
  └── agent/fix-login-timeout
        ├── AI 修改代码
        ├── 本地测试
        ├── 人工 Review
        └── 合并 PR

实际命令：

git checkout main
git pull

git checkout -b agent/fix-login-timeout

如果是比较复杂的任务，可以用 git worktree 单独开一个工作区：

git worktree add ../project-agent-task -b agent/refactor-user-service
cd ../project-agent-task

这样做的好处是：

• 主分支不会被污染；
• AI 改坏了可以直接丢掉；
• 多个 Agent 任务可以并行；
• diff 更容易 review；
• 回滚成本低。

AI Agent 的正确位置，不是“直接接管仓库”，而是“在隔离分支里完成一个明确任务”。

---

二、任务必须小，别让 Agent 猜需求

最容易出问题的提示词一般长这样：

帮我优化一下这个项目。

或者：

帮我重构一下代码。

这类需求太大，Agent 会自己脑补“什么叫优化”“什么叫重构”。

更好的写法是把任务限制成一个可验证的小目标：

任务：修复登录接口在 Redis 超时时返回 500 的问题。

限制：
1. 只允许修改 src/auth/login.ts 和 src/lib/redis.ts
2. 不要改接口路径
3. 不要改返回 JSON 结构
4. Redis 超时时返回明确错误码 AUTH_CACHE_TIMEOUT
5. 保留现有日志格式
6. 修改后运行 npm test
7. 最后列出修改文件、测试结果和潜在风险

这个提示词有几个关键点：

• 明确问题；
• 限定文件；
• 限定不能改什么；
• 给出验收标准；
• 要求运行测试；
• 要求输出风险说明。

AI Agent 最适合处理“边界清楚”的任务。
边界越模糊，越容易生成看似漂亮但不好合并的代码。

---

三、给 Agent 一份“安全开发说明”

我建议每个项目都准备一个内部文件，比如：

docs/ai-agent-safety.md

内容不用复杂，重点写清楚 Agent 能做什么、不能做什么。

示例：

# AI Agent 开发约束

## 允许做的事

- 修复明确 bug
- 补充单元测试
- 更新 README
- 解释已有代码
- 重构单个函数或单个模块
- 根据 issue 修改指定文件

## 禁止做的事

- 直接修改 main 分支
- 修改 .env、密钥、生产配置
- 大范围重构无关模块
- 修改鉴权、支付、权限逻辑，除非任务明确要求
- 自动删除测试
- 为了让测试通过而降低断言强度
- 未经确认修改数据库迁移文件
- 未经确认修改 CI/CD 配置

## 每次提交前必须输出

- 修改了哪些文件
- 为什么修改
- 怎么验证
- 测试是否通过
- 是否存在兼容性风险
- 是否需要人工重点 Review

然后每次让 Agent 工作前，把这段规则喂给它：

请先阅读 docs/ai-agent-safety.md。

接下来只处理我指定的任务，不要主动扩大修改范围。
如果你发现必须修改约束外文件，先说明原因，不要直接修改。

这个文件的价值不在于“约束模型一定听话”，而在于让团队形成统一的 Agent 使用规范。

---

四、哪些文件不要让 Agent 随便改？

下面这些文件，建议默认列入高风险区。

.env
.env.production
config/production.*
docker-compose.prod.yml
k8s/*.yaml
.github/workflows/*
package-lock.json
pnpm-lock.yaml
yarn.lock
db/migrations/*
src/auth/*
src/payment/*
src/permission/*
src/security/*

不是说 Agent 绝对不能改这些文件，而是改之前必须单独确认。

尤其是这几类：

1. 环境变量和密钥

不要把真实 .env 发给任何 AI 工具。

可以准备一份脱敏示例：

# .env.example
DATABASE_URL=postgres://user:password@localhost:5432/app
REDIS_URL=redis://localhost:6379
JWT_SECRET=replace-me

让 Agent 看 .env.example，不要看真实 .env。

2. 鉴权和权限逻辑

比如：

src/auth/
src/rbac/
src/permission/

这些地方一旦改错，不一定马上报错，但可能造成越权访问。

3. 支付和订单逻辑

支付类代码不能只看测试绿不绿。

你还要看：

• 金额单位有没有变；
• 幂等逻辑有没有破坏；
• 回调签名有没有校验；
• 重试逻辑有没有重复扣款风险。

4. 数据库迁移

Agent 很容易生成“看起来合理”的 migration，但数据库迁移是不可逆风险区。

让 Agent 写 migration 可以，但合并前必须人工逐行看。

---

五、用 Git diff 控制 Review 范围

每次 Agent 改完代码，第一件事不是跑去看功能，而是先看 diff。

git status
git diff --stat
git diff

如果你只想看某个文件：

git diff src/auth/login.ts

如果改动太大，先停下来。

我一般会用这个标准：

小任务：10 - 80 行 diff
中任务：80 - 300 行 diff
大任务：300 行以上必须拆分

超过 300 行的 Agent diff，不是不能合并，而是要问一句：

这个任务是不是本来就应该拆成多个 PR？

如果一个“修 bug”的任务改了 20 个文件，那多半是提示词没限制好。

---

六、让 Agent 自己写变更说明

不要只让 Agent 写代码，还要让它解释自己改了什么。

提示词可以这样写：

请基于当前 diff 输出一份变更说明：

1. 修改文件列表
2. 每个文件的修改原因
3. 解决了什么问题
4. 是否改变现有接口
5. 是否改变数据库结构
6. 是否影响鉴权或权限
7. 已运行哪些测试
8. 还有哪些风险需要人工 Review

理想输出应该像这样：

修改文件：
- src/auth/login.ts：增加 Redis 超时捕获，返回 AUTH_CACHE_TIMEOUT
- src/lib/redis.ts：增加 withTimeout 包装函数
- tests/auth/login.test.ts：补充 Redis timeout 测试

接口变化：
- HTTP 路径不变
- 响应结构不变
- 新增错误码 AUTH_CACHE_TIMEOUT

验证：
- npm test tests/auth/login.test.ts 通过
- npm run lint 通过

风险：
- 需要确认前端是否已兼容新错误码

这一步很重要。

因为 AI 写出来的代码，有时看起来没问题，但它自己一总结，你会发现它改了不该改的接口或状态码。

---

七、测试命令要写死，不要让 Agent 自由发挥

很多 Agent 会尝试自己找测试命令。

这当然方便，但我更建议在项目里明确写好脚本。

package.json 示例：

{
  "scripts": {
    "lint": "eslint src tests",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:auth": "vitest run tests/auth",
    "check": "npm run lint && npm run typecheck && npm test"
  }
}

然后告诉 Agent：

修改完成后，只运行以下命令：

npm run check

不要安装新依赖。
不要修改测试配置。
不要删除或跳过现有测试。
如果测试失败，请先说明失败原因，再提出修改方案。

为什么要这么写？

因为 Agent 有时为了“完成任务”，会做这些危险操作：

npm install 一个没必要的新包
改测试断言
跳过失败用例
删掉 flaky test
改 CI 配置

这些操作不一定是恶意的，但对项目来说很危险。

---

八、用提交模板限制 AI 产物

可以给 Agent 规定提交信息格式：

type(scope): summary

Changes:
- ...

Tests:
- ...

Risk:
- ...

示例：

fix(auth): handle redis timeout in login flow

Changes:
- add timeout wrapper for redis get operation
- return AUTH_CACHE_TIMEOUT when cache service is unavailable
- add test case for redis timeout

Tests:
- npm run test:auth
- npm run typecheck

Risk:
- frontend should confirm display copy for AUTH_CACHE_TIMEOUT

这样后面看 Git 历史会清楚很多。

不要接受这种提交：

update code
fix bug
AI changes
optimize project

AI 参与开发以后，提交记录更应该清楚，而不是更混乱。

---

九、一个适合团队的 AI Agent 工作流

可以把流程固定成 8 步：

1. 人先写清楚 issue
2. 创建 agent/* 分支
3. 限定 Agent 可修改范围
4. Agent 生成代码
5. 运行固定测试命令
6. Agent 输出变更说明
7. 人工 Review diff
8. 合并 PR

对应命令大概是：

git checkout main
git pull
git checkout -b agent/fix-login-timeout

# 让 Agent 在这个分支里处理明确任务

npm run check

git diff --stat
git diff

git add .
git commit -m "fix(auth): handle redis timeout in login flow"
git push origin agent/fix-login-timeout

然后走正常 PR。

如果团队用 GitHub，可以加一个 PR 模板：

## 变更说明

- 

## 测试结果

- [ ] npm run lint
- [ ] npm run typecheck
- [ ] npm test

## AI Agent 使用情况

- [ ] 本 PR 使用 AI Agent 辅助
- [ ] 已人工检查 diff
- [ ] 未修改密钥、生产配置、权限逻辑
- [ ] 未删除或跳过测试

## 风险点

- 

这不是形式主义。
当 AI Agent 越来越多地参与代码生产，PR 模板就是最低成本的风险控制。

---

十、Codex / Cursor / Claude Code 分别怎么用更安全？

这几个工具都能参与写代码，但我会这样分工。

Codex：适合独立任务

Codex 适合处理边界明确的任务，比如：

为 user service 补充单元测试
修复一个明确 issue
把一个工具函数迁移到新模块
根据 README 更新示例代码
为某个接口补充错误处理

OpenAI Developers 页面也提到，Codex 可以按你的意图生成代码、适配现有项目结构和约定，也能阅读陌生代码库并做 code review。

使用建议：

不要让 Codex “优化整个项目”。
让它处理一个 issue、一个模块、一个 PR。

Cursor：适合 IDE 内上下文开发

Cursor 更适合在项目里边读边改，尤其适合：

理解调用链
改前端组件
补局部逻辑
根据已有代码风格实现新功能
边看 diff 边调整

Cursor 官方产品页强调 Agent 能理解整个代码库，并在 Desktop、CLI、Web、Mobile 等场景工作。

使用建议：

让 Cursor 先解释项目结构，再让它改代码。
不要一上来就让它全仓库重构。

Claude Code：适合终端任务，但结构，再让它改代码。

不要一上来就让它全仓库重构。

###要注意命令权限

Claude Code 的优势是更贴编辑文件、运行命令。citeturn679866search9 Anthropic 的安全文档也提到，Claude Code 默认采用严格的会进入额外权限动作。citeturn679866search2

使用建议：

```text
不要一开始就放开所有命令。
先让它 explain，再让它 plan，最后再 approve 具体修改。

比较稳的提示词：

先不要修改文件。

请先完成：
1. 阅读相关代码
2. 输出问题原因
3. 给出修改计划
4. 列出将要修改的文件
5. 等我确认后再改

这比直接说“帮我修好”安全很多。

---

十一、别把 AI Agent 当初级程序员，也别当高级程序员

AI Agent 不是初级程序员。
因为它读代码、写代码、跑命令的速度非常快。

AI Agent 也不是高级程序员。
因为它没有你的业务背景，不知道哪些历史包袱不能动，不知道哪些接口兼容性不能破坏，也不知道线上事故发生后谁来背锅。

更准确的定位是：

AI Agent 是一个执行力很强、但需要明确边界和 Review 的工程助手。

你给它清楚的任务，它能节省很多时间。
你给它模糊的目标，它就可能制造一堆难以维护的 diff。

---

十二、会员工具可以怎么放进开发流程？

如果你长期使用 ChatGPT Plus、Claude Pro、Cursor、Kiro 这类工具，可以把 gpt68.com 当作第三方 AI 会员充值平台入口之一去了解。

但这里要分清楚：
gpt68.com 解决的是订阅充值流程问题，不是 OpenAI、Anthropic、Cursor、Kiro 的官方网站，也不是官方授权合作方。使用前要看清套餐说明、账号要求、到账说明和售后规则。

对开发者来说，真正提升效率的不是“开了会员”这件事，而是你有没有建立稳定流程：

需求先拆清楚
Agent 只改分支
文件范围先限制
测试命令固定
diff 必须人工看
PR 再合并

工具只是放大器。
流程对了，AI Agent 才是效率工具。
流程错了，AI Agent 只是更快地制造技术债。

---

总结

AI Agent 能帮开发者省时间，但前提是不要让它直接接管主分支。

我建议把规则固定下来：

不要直接改 main
不要给模糊任务
不要开放敏感文件
不要跳过测试
不要接受大而乱的 diff
不要省略人工 Review

更安全的流程是：

开 agent 分支
限定修改范围
让 Agent 小步改
运行固定测试
输出变更说明
人工看 diff
再走 PR

Codex、Cursor、Claude Code 都可以成为很强的开发助手。
但越是强的工具，越需要边界。

让 AI Agent 写代码不难。
难的是让它写出的代码能安全合并、方便回滚、长期维护。

这才是 AI 编程真正进入工程团队时，最该补上的一课。