新项目 Agent 接管与代码审查 SOP
i
版本 v1.0 · Coding Agent 通用：适用范围：GitHub / Gitee / GitLab / 本地已有项目 / Agent 中途接手项目。适用 Agent：Codex、ZCode、DSH、Claude Code、Gemini CLI 及其他 Coding Agent。核心原则：先理解 → 再验证 → 后修改 → 再审查。
一、核心原则
Agent 接管一个新项目时，禁止直接进入开发状态。
必须按照以下顺序执行：
项目接管
↓
环境识别
↓
项目扫描
↓
建立项目认知
↓
建立架构地图
↓
追踪真实调用链
↓
验证实际功能
↓
代码审查
↓
形成问题清单
↓
制定修改方案
↓
用户确认 / 明确授权
↓
执行修改
↓
测试
↓
二次代码审查
↓
交付
禁止：
刚拉项目
↓
看几个文件
↓
直接重构
二、第一阶段：项目接管
2.1 接管指令
首次接管项目时，向 Agent 发送：
你现在接手的是一个已有项目。
当前阶段属于“项目认知阶段”，不是开发阶段。
暂时禁止修改任何代码、配置、数据库和项目结构。
你的任务是完整理解这个项目。
请按照以下顺序执行：
1. 扫描项目目录结构
2. 判断技术栈
3. 判断运行环境
4. 找出项目入口
5. 找出构建和启动方式
6. 找出核心业务模块
7. 找出核心数据模型
8. 找出 API / 路由
9. 找出数据库及持久化机制
10. 找出外部服务和第三方依赖
11. 找出测试体系
12. 找出部署方式
13. 分析核心业务流程
14. 分析核心数据流
15. 分析模块依赖关系
16. 找出明显的技术债务
17. 找出可能存在的 Bug
18. 找出代码存在但实际上未接入主流程的模块
要求：
- 不修改任何文件
- 不重构
- 不优化
- 不修 Bug
- 不删除文件
- 不安装无必要的依赖
- 不改变项目结构
- 不根据猜测下结论
无法确认的内容必须标记为“未知”。
完成后生成项目认知报告，并停止等待下一步指令。
三、第二阶段：项目结构扫描
Agent 必须识别：
项目根目录
├── package.json / pyproject.toml / pom.xml / go.mod / Cargo.toml
├── README
├── 配置文件
├── 源代码
├── 测试
├── 数据库
├── 脚本
├── 构建文件
├── Docker
├── CI/CD
└── 文档
重点回答：
3.1 技术栈
包括：
- 编程语言
- 前端框架
- 后端框架
- UI 框架
- 数据库
- ORM
- 构建工具
- 包管理器
- 测试框架
- 部署方式
- 第三方服务
四、第三阶段：建立 PROJECT_CONTEXT.md
项目认知完成后，在项目根目录建立：
PROJECT_CONTEXT.md
内容必须包括：
# Project Context
## 1. 项目用途
## 2. 项目当前状态
## 3. 技术栈
## 4. 运行环境
## 5. 启动方式
## 6. 构建方式
## 7. 部署方式
## 8. 项目目录结构
## 9. 核心模块
## 10. 核心入口
## 11. 核心 API
## 12. 数据模型
## 13. 数据流
## 14. 核心业务流程
## 15. 模块依赖关系
## 16. 外部服务
## 17. 配置系统
## 18. 测试系统
## 19. 当前已实现功能
## 20. 当前未实现功能
## 21. 已知问题
## 22. 技术债务
## 23. 可疑代码
## 24. 未确认事项
## 25. 修改注意事项
五、第四阶段：建立架构地图
Agent 必须进一步分析项目，而不能只停留在目录结构。
至少生成：
系统架构图
模块关系图
核心业务流程图
数据流图
推荐使用 Mermaid。
例如：
flowchart TD
User --> API
API --> Service
Service --> Domain
Domain --> Repository
Repository --> Database
六、第五阶段：追踪真实调用链
这是整个 SOP 最重要的部分之一。
Agent 不允许仅根据：
文件名
类名
函数名
目录名
注释
README
判断某个功能“已经实现”。
必须追踪真实调用关系。
例如：
用户输入
↓
Controller
↓
Service
↓
Domain
↓
Repository
↓
Database
检查：
- 谁调用它？
- 它调用谁？
- 数据从哪里来？
- 数据在哪里修改？
- 数据最终去了哪里？
- 是否真的进入主流程？
- 是否存在绕过正式架构的路径？
重点识别：
Dead Code
Stub
Mock
TODO
临时实现
空实现
未接入模块
Feature Flag
隐藏分支
硬编码
绕过正式 API 的调用
重复实现
七、第六阶段：核心功能验证
在修改代码之前，Agent 必须验证项目当前实际状态。
至少执行：
1. 安装 / 检查依赖
2. 启动项目
3. 执行构建
4. 执行现有测试
5. 检查关键 API
6. 检查关键业务流程
7. 检查日志
8. 检查明显运行时错误
如果项目无法启动：
不要立即修改代码。
先判断：
环境问题
依赖问题
配置问题
数据库问题
代码问题
外部服务问题
并记录原因。
八、第七阶段：代码审查
代码审查分为七个维度。
8.1 功能正确性
检查：
- 业务逻辑错误
- 边界条件
- 空值处理
- 异常处理
- 状态错误
- 并发问题
- 数据一致性
8.2 架构正确性
检查：
- 是否违反项目架构
- 是否存在跨层调用
- 是否绕过 Service / Domain / API
- 是否存在循环依赖
- 是否存在过度耦合
- 是否存在职责混乱
- 是否存在重复业务逻辑
8.3 需求符合度
如果项目存在：
需求文档
设计文档
架构方案
开发计划
必须逐项对照。
输出：
| 项目 | 要求 | 当前实现 | 状态 |
|---|---|---|---|
| A | 已实现 | 已实现 | ✅ |
| B | 已实现 | 部分实现 | ⚠️ |
| C | 已实现 | 未实现 | ❌ |
| D | 不应该存在 | 存在 | 🔴 |
九、第八阶段：安全审查
检查：
SQL 注入
XSS
CSRF
命令注入
路径穿越
权限绕过
敏感信息泄露
API Key 泄露
密码硬编码
Token 泄露
危险文件上传
不安全的反序列化
错误的 CORS
特别检查：
.env
config
日志
前端源码
Git 历史
Docker
CI/CD
禁止将：
API Key
Secret
Password
Token
私钥
写入源码。
十、第九阶段：性能审查
重点检查：
N+1 查询
重复请求
重复计算
无限循环
高频 Tick
内存泄漏
大对象复制
不必要的 AI 调用
不必要的数据库查询
同步阻塞
大量并发请求
对于 AI 项目额外检查：
Token 消耗
Context 过大
重复 Context
重复调用模型
无意义的模型调用
模型调用没有缓存
模型调用没有超时
模型失败没有降级
十一、第十阶段：工程质量审查
检查：
重复代码
过长函数
过大文件
命名混乱
职责不清
过度抽象
过度封装
魔法数字
魔法字符串
废弃代码
无效注释
错误注释
TODO
FIXME
临时方案
注意：
不要为了“代码看起来漂亮”而过度重构。
优先处理：
Bug
架构错误
安全问题
数据错误
性能问题
维护风险
十二、第十一阶段：建立问题清单
所有问题必须分类。
P0：致命问题
例如：
项目无法启动
核心数据损坏
严重安全漏洞
核心功能完全不可用
P1：严重问题
例如：
核心业务逻辑错误
架构关键路径错误
重要数据不一致
核心功能异常
P2：一般问题
例如：
性能问题
代码耦合
异常处理不足
维护成本较高
P3：优化项
例如：
代码风格
命名
小规模重构
非必要优化
十三、第十二阶段：生成审查报告
生成：
CODE_REVIEW.md
结构：
# Code Review
## 1. 总体结论
## 2. 项目当前状态
## 3. 架构符合度
## 4. 功能完成度
## 5. 发现的问题
### P0
### P1
### P2
### P3
## 6. 架构问题
## 7. 数据流问题
## 8. 安全问题
## 9. 性能问题
## 10. 工程质量问题
## 11. 代码存在但未实际使用的模块
## 12. 潜在 Bug
## 13. 技术债务
## 14. 建议修改顺序
## 15. 不建议修改的部分
## 16. 未确认事项
## 17. 最终结论
十四、第十三阶段：制定修改方案
代码审查完成后：
禁止 Agent 自动大规模修改。
先生成：
IMPLEMENTATION_PLAN.md
必须说明：
问题
↓
原因
↓
修改方案
↓
影响范围
↓
涉及文件
↓
风险
↓
测试方案
例如：
## 问题：NPC 被硬编码触发
### 原因
当前 TavernService 中存在直接触发 NPC 的逻辑。
### 修改方案
将 NPC 触发逻辑移动至 Event System。
### 影响范围
- TavernService
- EventEngine
- NPCService
### 风险
可能影响现有 NPC 对话。
### 测试
1. 玩家进入酒馆
2. 不主动寻找 NPC
3. NPC 不应该强制出现
4. 玩家主动寻找 NPC 时正常触发
十五、第十四阶段：执行修改
只有明确进入开发阶段后，Agent 才允许修改代码。
修改原则：
小步修改
↓
单项验证
↓
测试
↓
再修改下一项
禁止：
一次修改几十个模块
十六、第十五阶段：修改后的二次审查
修改完成后必须再次执行代码审查。
重点检查：
1. 原问题是否真正解决
2. 是否产生新 Bug
3. 是否破坏原功能
4. 是否破坏架构
5. 是否引入新的依赖
6. 是否产生死代码
7. 是否留下临时方案
8. 是否与 IMPLEMENTATION_PLAN.md 一致
形成：
POST_REVIEW.md
十七、最终交付检查
Agent 最终必须回答：
项目是否可以启动？
项目是否可以构建？
测试是否通过？
原问题是否解决？
是否存在未解决的 P0/P1？
是否修改了架构？
是否新增依赖？
是否新增配置？
是否修改数据库？
是否存在需要人工确认的问题？
十八、禁止 Agent 自作主张的行为
以下行为默认禁止：
❌ 大规模重构
❌ 删除看起来没用的代码
❌ 删除旧模块
❌ 更换框架
❌ 更换数据库
❌ 更换依赖
❌ 更换技术栈
❌ 改变 API
❌ 改变数据结构
❌ 修改项目架构
❌ 为了“最佳实践”重写系统
除非用户明确授权。
十九、Agent 的判断原则
遇到不确定的问题：
不要猜
不要自作主张
不要为了让代码通过而修改架构
应该：
发现问题
↓
分析原因
↓
记录不确定性
↓
提出方案
↓
等待确认
二十、推荐的 Agent 接管命令
以后新项目可以直接发送：
请按照项目《新项目 Agent 接管与代码审查 SOP.md》执行。
当前进入【项目接管阶段】。
要求：
1. 只读
2. 不修改代码
3. 完整扫描项目
4. 建立项目认知
5. 分析架构
6. 追踪核心调用链
7. 验证当前实际运行状态
8. 找出代码存在但未实际接入的功能
9. 找出潜在 Bug
10. 建立 PROJECT_CONTEXT.md
完成后停止。
不要自行进入开发阶段。
二十一、推荐工作模式
以后项目开发统一采用：
┌──────────────┐
│ 新项目接入 │
└──────┬───────┘
↓
┌────────────────┐
│ 项目认知阶段 │
│ PROJECT_CONTEXT │
└───────┬────────┘
↓
┌────────────────┐
│ 架构分析阶段 │
│ Architecture │
└───────┬────────┘
↓
┌────────────────┐
│ 真实调用链分析 │
└───────┬────────┘
↓
┌────────────────┐
│ 当前代码审查 │
│ CODE_REVIEW │
└───────┬────────┘
↓
┌────────────────┐
│ 制定修改方案 │
│ IMPLEMENTATION │
└───────┬────────┘
↓
┌────────────────┐
│ 执行修改 │
└───────┬────────┘
↓
┌────────────────┐
│ 测试与验证 │
└───────┬────────┘
↓
┌────────────────┐
│ 二次审查 │
│ POST_REVIEW │
└───────┬────────┘
↓
交付
二十二、核心原则总结
整个 SOP 可以浓缩为：
不要让 Agent 一上来写代码。
正确流程是：
先认识项目
↓
再理解架构
↓
再追踪真实代码
↓
再验证项目
↓
再进行代码审查
↓
再制定方案
↓
再修改
↓
再测试
↓
再审查
最终目标不是让 Agent：
“会写这个项目的代码。”
而是让 Agent：
“知道这个项目是什么、为什么这么设计、现在实际上是怎么运行的，以及修改一个地方会影响什么。”
评论
留言无需注册，填个昵称就能说上两句。