Codex 多 Agent 协作开发实战：一个人半天搞定全栈 AI 批改平台

从 0 到 1，用 Codex 驱动多个 AI Agent 并行开发一个 Spring Boot + React + DeepSeek 的 AI 作业批改平台。
本文涵盖多 Agent 协作模式、三层约束体系、Skill 设计、提示词工程、SSH 远程运维及踩坑实录。

---

一、先看成果：半天，一个人，一个全栈项目

项目名称：AIGrader — AI 作业批改平台
开源地址：https://github.com/xiaodangjia105/AIGrader
技术栈：Spring Boot 3.4 + Java 21 + React 18 + TypeScript + DeepSeek + PostgreSQL + Redis

指标	数据
开发时间	~4 小时（半天）
开发者	1 人
后端 Java 文件	63 个
前端 TS/TSX 文件	21 个
数据库表	9 张（含 pgvector）
REST API	30+ 个
AI 批改策略	3 种（选择/填空/主观题）
角色权限	3 套（教师/学生/管理员）

这不是一个 Demo 玩具，而是一个跑得通的完整闭环系统：教师布置作业 → AI 秒级批改 → 学生查看结果并订正 → 教师复核确认。

怎么做到的？答案是 Codex CLI + 多 Agent 并行协作。

---

二、为什么选择 Codex？

市面上的 AI 编码工具很多——GitHub Copilot、Cursor、Windsurf……但 Codex CLI 有几个独特优势，特别适合项目级全栈开发：

特性	Codex CLI	Copilot Chat	Cursor
Agent 自主执行能力	✅ 可自主读写文件、运行命令	❌ 仅建议代码	✅ 部分支持
多 Agent 并行	✅ 原生 spawn_agent	❌ 单会话	❌ 单会话
项目级约束（AGENTS.md）	✅ 目录作用域级	❌	⚠️ .cursorrules
Skill 插件体系	✅ 可扩展	❌	❌
终端原生	✅ CLI 原生	❌ IDE 插件	⚠️ IDE
SSH 远程运维	✅ 天然支持	❌	❌

核心差异：Codex 不仅是"代码补全"，而是一个能自主决策、分派任务、约束自身行为的 AI 开发 Agent。你可以把它当成一个永远不会累的初级工程师——前提是你得学会怎么"管"它。

---

三、多 Agent 协作模式：像管团队一样管 AI

3.1 核心理念：任务拆分 → 并行执行 → 人工审查

传统开发流程是串行的——写完后端再写前端，写完业务再写测试。Codex 的多 Agent 模式让你可以同时开多个 Agent 并行干活，每个 Agent 专注一个独立模块。

AIGrader 项目中，我把后续功能拆成了 4 个 Agent：

第一步：Agent-F（前端 JWT 登录对接）── 基础设施
    │
    ├──→ 第二步（并行）：
    │       Agent-A（AI 增强：Prompt 多维度 + 模型切换）
    │       Agent-B（业务增强：个性化评语 + 学习报告）
    │       Agent-C（管理增强：批量导入 + 准确率追踪）
    │
    └──→ 第三步：人工审查 + 合并

3.2 任务拆分三原则

原则一：低耦合，高内聚

每个 Agent 的修改文件集合要尽可能不重叠。如果 Agent-A 和 Agent-B 同时改 GradingService.java，合并时必冲突。我在 PROGRESS.md 里明确标注了每个 Agent 的文件范围：

Agent-A 后端文件：SubjectiveGradingStrategy / GradingResult / PromptTemplateService / ...
Agent-B 后端文件：CommentService / ReportService / Submission / ...
Agent-C 后端文件：QuestionService / QuestionController / BatchImportResultDTO / ...

原则二：基础设施先行

Agent-F（JWT 前端对接）是所有前端工作的前提——登录没通之前，Agent-A/B/C 的前端部分没法测试。所以 Agent-F 是第一阶段，完成后才能启动后续并行。

原则三：每个 Agent 独立可验证

给每个 Agent 的任务描述里包含"完成标准"——比如"后端 mvn compile 通过"、“前端 pnpm tsc --noEmit 无错误”。这样不需要等所有 Agent 都跑完才知道有没有问题。

3.3 实际操作流程

1. 编写任务文档（PROGRESS.md）：明确每个 Agent 的职责、文件范围、依赖关系
2. 开第一个 Codex 对话：给 Agent-F 分配 JWT 前端任务
3. Agent-F 完成后：审查代码 + 合并到主分支
4. 并行开 3 个 Codex 对话：分别给 Agent-A/B/C 分配各自任务
5. 逐个审查合并：每个 Agent 独立验证后再合并

💡 关键洞察：多 Agent 协作的精髓不在于"让 AI 替你做所有事"，而在于你花 30 分钟设计好任务拆分，AI 花 3 小时并行干活——你的角色从"码农"变成了"架构师+审查者"。

---

四、约束体系：让 AI 不跑偏的三层枷锁

AI Agent 最大的问题是过于自由——它会擅自改无关文件、加无用注释、甚至重构整个项目。Codex 通过 AGENTS.md 机制提供了目录级别的行为约束，我把这套体系设计成了三层：

4.1 第一层：AGENTS.md（项目宪法）

放在项目根目录，Codex 每次启动自动加载。这是我的 AGENTS.md 核心内容：

# 文件操作
- 禁止批量删除文件或目录（del /s、rd /s、rm -rf）
- 删除文件时，一次只能删除一个明确路径的文件

# 每次对话范围
- 每次对话只聚焦一个文件 / 一个类
- 任务完成后关闭对话，新开对话处理下一个任务

# 代码规范
- 代码应自解释，禁止添加不必要的注释
- 禁止添加版权/license 声明

# 配置安全
- API Key 等敏感信息使用环境变量
- .env 和 application-local.yml 已加入 .gitignore

这些约束看似简单，但极其有效。举例：

• “禁止批量删除”：防止 Agent 在清理时 rm -rf 误删整个项目
• “一次只聚焦一个文件”：防止 Agent 自作主张重构全局代码
• “禁止注释”：防止 Agent 写一堆 // TODO: optimize later 的废话

4.2 第二层：DEVELOPER_GUIDE.md（Agent 开发手册）

比 AGENTS.md 更具体，面向每个新 Agent 对话。包含：

• 技术栈和项目结构说明
• 环境变量列表
• 代码架构分层（Controller → Service → Repository）
• API 规范（返回格式、权限注解）
• 启动和测试命令
• 任务完成标准（编译通过、类型检查通过、汇报修改文件列表）

关键设计：每个 Agent 对话开始时，我都把 DEVELOPER_GUIDE.md 的内容发过去，确保它理解项目的技术上下文。

4.3 第三层：PROGRESS.md（任务调度中心）

这是整个多 Agent 协作的"指挥中心"。核心内容：

## Agent 任务分配

### Agent-F：基础设施 — 前端 JWT 对接
- 分支：codex/jwt-frontend
- 状态：待开始
- 文件：LoginPage.tsx / useAuthStore.ts / api.ts / types/index.ts
- 依赖：无
- 阻塞：Agent-A / Agent-B / Agent-C（需等 Agent-F 完成）

### Agent-A：AI 增强 — Prompt 多维度 + 模型切换
- 分支：codex/ai-prompt
- 后端文件：SubjectiveGradingStrategy / PromptTemplateService / ...
- 前端文件：AdminAIConfig.tsx / api.ts / ...
- 依赖：后端无依赖；前端依赖 Agent-F 完成

三层约束协作关系：

AGENTS.md         → "你不能做什么"  （行为边界）
DEVELOPER_GUIDE.md → "你应该怎么干"  （技术规范）
PROGRESS.md        → "你现在要干什么"（任务分配）

当一个新 Agent 启动时，三层信息同时加载，它就知道：边界在哪、技术栈是什么、本次任务范围多大。这比单纯一句"帮我写个登录页面"靠谱一万倍。

---

五、Skill 设计：封装项目知识，让 Agent 即插即用

5.1 什么是 Skill？

Codex 的 Skill 是一组可复用的指令集（SKILL.md），可以被 Agent 动态加载。你可以把它理解为"给 AI 的预制菜调料包"——不用每次都从头解释项目背景。

5.2 AIGrader 的 aigrader-dev Skill

我的 Skill 目录结构：

skills/aigrader-dev/
└── SKILL.md

内容精简但关键：

# AIGrader 开发辅助 Skill

## 项目上下文
AIGrader 是 AI 作业批改平台。详细需求见 PRD.md，开发计划见 DEVELOPMENT_PLAN.md。

## 开发规范
- 后端代码位于 backend/，前端代码位于 frontend/
- 遵循 PRD.md 第四节中的系统架构设计
- 每次改动聚焦一个文件 / 一个类
- 敏感配置通过环境变量注入，不提交到仓库
- 禁止批量删除文件

## 关键参考
- 需求文档：PRD.md
- 开发计划：DEVELOPMENT_PLAN.md
- 环境速查：ENV_INFO.md

5.3 Skill 的设计哲学

① 少即是多

Skill 不是把整个项目文档塞进去——那会让 Agent 的上下文爆炸。Skill 应该只包含最常被遗忘的关键约束和快速索引指针。详细文档让 Agent 自己去读。

② 可验证

每条约束都应该是可验证的。比如"禁止批量删除文件"——如果你发现 Agent 违规了，可以立刻指出来。模糊的约束（如"代码要优雅"）对 AI 没用。

③ 场景化

一个 Skill 对应一个场景。aigrader-dev 只服务于"开发 AIGrader 项目"这个场景。如果你还做运维，应该另外建一个运维 Skill。

---

六、提示词工程：怎么跟 AI Agent 说话

这是整个流程中最被低估的一环。很多人抱怨"AI 写的代码不能用"，90% 的原因是提示词写得太烂。

6.1 坏提示 vs 好提示

❌ 坏提示：

“帮我写一个学生作业提交功能”

结果：Agent 可能随便建个 HTML 文件、用内存变量存数据、完全不考虑权限和错误处理。

✅ 好提示：

"在 AIGrader 项目中，我需要实现学生提交作业功能。请先读取 PRD.md 了解需求，然后读取 DEVELOPER_GUIDE.md 了解技术规范。你需要：

1. 后端：在 SubmissionController 中添加 POST /api/submissions 接口
2. 后端：在 SubmissionService 中添加 submit 方法，调用 GradingService 触发 AI 批改
3. 前端：在 StudentAssignment.tsx 中添加提交按钮和作答区域
4. 完成后运行 mvn compile 和 pnpm tsc --noEmit 验证"

6.2 提示词设计五要素

我总结了一套 TARGET 框架：

要素	含义	示例
Target file	明确改哪个文件	“修改 SubmissionController.java”
Action	具体操作	“添加 POST /api/submissions 接口”
Reference	参考文档	“先读 PRD.md 和 DEVELOPER_GUIDE.md”
Guardrail	约束条件	“不要改无关文件，不要加注释”
Expectation	完成标准	“后端 mvn compile ，前端 tsc 零错误”
Test	验证方式	“用 curl 测试 API 返回 200”

6.3 提示词模板示例

这是我给 Agent-A（AI 增强）分配任务时的实际提示词：

你需要在 AIGrader 项目中实现 AI Prompt 多维度评分和分学科模板。

请先读取以下文件了解上下文：
- PRD.md（需求）
- DEVELOPER_GUIDE.md（开发规范）
- backend/.../ai/SubjectiveGradingStrategy.java（当前策略）
- backend/.../ai/PromptTemplateService.java（当前 Prompt 模板）

你需要修改的后端文件：
1. SubjectiveGradingStrategy.java：增加多维度评分（内容分 + 逻辑分 + 表达分）
2. PromptTemplateService.java：按学科（语文/数学/英语）提供不同 Prompt 模板
3. GradingResult.java：增加维度分数字段

完成后运行 `mvn compile`，确保编译通过。不要修改其他文件。

6.4 踩坑：提示词过长的问题

一开始我习惯把整个需求文档贴进提示词。结果 Agent 的注意力被稀释——它会在无关细节上纠结，比如花了 10 分钟思考"要不要加用户头像功能"。

解决方案：提示词只写 What（做什么）+ Where（在哪做），让 Agent 自己去读 How（怎么做） 的文档。

---

七、SSH 远程运维：让 Codex 管理你的云服务器

这是 Codex CLI 相比 IDE 类工具的一个杀手级场景——因为它本质是终端程序，天然支持 SSH。

7.1 实操流程

# 1. 在本地终端用 Codex 连接远程服务器
ssh user@your-cloud-server

# 2. 在远程会话中告诉 Codex 你要做什么
# 例如："检查 nginx 错误日志，找出 502 的原因并修复"

# 3. Codex 会自主执行：
#    - tail -f /var/log/nginx/error.log
#    - systemctl status nginx
#    - 检查 upstream 服务是否运行
#    - 必要时修改 nginx.conf 并 reload

7.2 为什么这个场景特别强？

• 环境一致性：Codex 直接操作生产环境，不需要你先在本地复现
• 权限安全：所有操作都在 SSH 会话中执行，rm -rf / 这种自杀命令会被 AGENTS.md 约束拦截
• 日志分析：AI 天然擅长从海量日志中提取异常模式，比人肉 grep 快 10 倍

7.3 实践案例

我在 AIGrader 项目中遇到一个问题：前端页面部分中文乱码，后端返回正常。

用 Codex SSH 到服务器后：

我："检查 Nginx 配置和后端编码设置，定位中文乱码原因"

Codex 自主执行：
1. cat /etc/nginx/nginx.conf → 发现 charset 未设置
2. locale → 确认系统 locale 为 UTF-8
3. mvn spring-boot:run 日志检查 → 发现数据库编码问题
4. 修改 Nginx 配置添加 charset utf-8;
5. nginx -s reload

3 分钟解决问题。如果自己排查，从 Nginx → 后端 → 数据库逐层检查，至少 20 分钟。

---

八、痛点与解决方案：真实踩坑实录

痛点 1：Agent 擅自扩大修改范围

现象：让 Agent 改一个 Controller，它顺手"优化"了 Service、Entity、甚至前端组件的命名。

根因：Agent 的"讨好型人格"——它觉得多干活你会更满意。

解决：

• 在 AGENTS.md 中明确：“每次对话只聚焦一个文件 / 一个类”
• 在提示词末尾加一句：“不要修改本任务范围外的任何文件”
• 用 Codex 的 update_plan 工具锁定步骤，每步完成后再推进

痛点 2：中文编码地狱

现象：Agent 写入的中文文件在 Windows 下是 GBK 编码，在 Linux/Mac 下是 UTF-8，导致乱码满天飞。

根因：Codex CLI 运行在 PowerShell 中，PowerShell 的默认输出编码是 GBK。

解决：

• 在 AGENTS.md 中加约束：“所有文件使用 UTF-8 编码”
• PowerShell 端设置 $OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()
• 用专门的 codex/fix-encoding 分支集中修复编码问题（见 git log）

痛点 3：Agent 生成大量废话注释

现象：Agent 在每个方法上加 // This method handles user login 这种废话注释。

根因：很多 LLM 的训练数据中，代码都有注释，它模仿了这个行为。

解决：AGENTS.md 中明确：“代码应自解释，禁止添加不必要的注释”。实测效果显著——加了这条后注释量减少 90%。

痛点 4：Agent 记不住之前的决策

现象：上一个 Agent 决定用 BigDecimal 存分数，下一个 Agent 用了 double。

根因：每个 Codex 对话是独立的，Agent 之间不共享记忆。

解决：

• DEVELOPER_GUIDE.md 中列出所有技术决策（“分数用 BigDecimal”、“API 返回 ApiResponse<T>”）
• 每个新对话开始时，先让 Agent 读取 DEVELOPER_GUIDE.md
• Skill 中沉淀核心约定

痛点 5：并行 Agent 的代码冲突

现象：Agent-A 和 Agent-B 同时改了 api.ts 的同一行。

根因：任务拆分时文件范围有重叠。

解决：

• PROGRESS.md 中给每个 Agent 标注"只读文件"和"读写文件"
• 如果两个 Agent 必须改同一个文件，让它们改不同区域（不同方法、不同 import）
• 实在不行就串行：Agent-A 完成合并后，Agent-B 再开始

---

九、我的开发流程全景图

08:00  写好 PRD.md + DEVELOPER_PLAN.md（花 1 小时想清楚要做什么）
09:00  初始化项目骨架（mvn archetype + pnpm create vite）
09:30  打开 Codex，给第一个 Agent 分配 M1 任务（项目初始化）
10:00  Agent 完成 M1，审查合并
10:10  开新对话，分配 M2（实体 + CRUD）
10:40  Agent 完成 M2，审查合并
10:50  开新对话，分配 M3（AI 批改引擎）
11:20  Agent 完成 M3，审查合并
11:30  开新对话，分配 M4-M6（前端页面 + 联调）
12:00  整体审查 + 修复编码问题 + 推送 GitHub

核心节奏：我写文档 → Agent 写代码 → 我审查 → 合并 → 下一个。

整个半天，我敲键盘的时间不超过 30%，大部分时间在思考架构、写约束文档、审查代码。这才是 AI 时代的正确开发姿势——你不是在"写代码"，你是在"管理写代码的 AI"。

---

十、总结：三个核心认知

认知一：AI Agent 不是"代码生成器"，是"初级工程师"

把它当成人来管理：给它明确的任务、清晰的约束、可验证的标准。你越把它当"工具"，它越像个工具；你越把它当"工程师"，它越像个工程师。

认知二：约束比能力更重要

一个无约束的"超级 Agent"比一个受限的"弱 Agent"危险 100 倍。三层约束体系（AGENTS.md → DEVELOPER_GUIDE.md → PROGRESS.md）是用好 Codex 的前提，不是可选。

认知三：你的角色变了

从"写代码的人"变成"设计系统的人"。你的产出不再是代码行数，而是架构设计 + 约束文档 + 审查质量。这其实是软件工程一直追求的"高杠杆"状态——只是 AI 让它变成了现实。

---

附录：资源链接

资源	地址
AIGrader 开源仓库	https://github.com/xiaodangjia105/AIGrader
Codex CLI 官方	https://github.com/openai/codex
DeepSeek API	https://api-docs.deepseek.com/
Spring AI 文档	https://docs.spring.io/spring-ai/reference/

---

后续计划出两篇专题深度篇：

• 《约束即代码：AGENTS.md 深度设计指南》 — 讲三层约束的设计方法论和最佳实践
• 《Codex SSH 远程运维实战》 — 讲怎么用 Codex 管理云服务器、排查线上问题

欢迎 Star ⭐ 项目仓库，有问题可以在 GitHub Issues 交流。