FIT Framework 多 AI 协作快速上手:Claude Code、Codex 与 Gemini CLI 的分工流水线实战
FIT Framework 多 AI 协作快速上手:Claude Code、Codex 与 Gemini CLI 的分工流水线实战
本指南面向希望在 FIT Framework 仓库中引入多 AI 协作的开发者,系统讲解如何借助
.ai-agents/配置目录,让 Claude Code、Codex(OpenAI/ChatGPT)、Gemini CLI 等主流 AI 工具在「需求分析 → 方案设计 → 代码实现 → 代码审查 → 提交」全流程中各司其职、无缝交接。读完本文,你将掌握任务模板的创建与状态跟踪、四种工作流的选用、AI 切换时机与人工检查点设置,以及常见协作故障的排查方法,可直接在本仓库中开启多 AI 协作开发。
一、协作前的准备:先读懂项目规范
在开始任何协作任务之前,请先阅读根目录的 AGENTS.md 文件,它定义了 FIT Framework 的基本开发规范和命令,包括:
- 构建命令:
mvn clean install(构建全部模块)、cd framework/fit/java && mvn clean install(仅构建 Java FIT 框架)、./build/bin/fit start(启动 FIT 运行时,依赖 Node.js,默认端口 8080); - 编码规范:使用
CodeFormatterFromIdea.xml格式化 Java 代码、公共 API 必须有 Javadoc、类头必须包含@author和@since; - 版权头更新规则:修改带版权头的文件时,先运行
date +%Y获取当前年份再更新,禁止硬编码年份; - 提交规范:遵循 Conventional Commits,格式为
<type>(<scope>): <subject>,type 取feat/fix/docs/refactor/test/chore,scope 为fit/waterflow/fel等模块名(可省略),subject 用中文且 20 字以内。
FIT Framework 采用双轨配置体系管理各 AI 工具的项目指令(详见 .ai-agents/README.md):
- 体系 A(Claude Code):
.claude/CLAUDE.md(启动时自动加载的快速参考)、.claude/project-rules.md(详细规则)、.claude/commands/(Slash Commands 实现); - 体系 B(AGENTS.md 标准):根目录
AGENTS.md供 Codex CLI、Gemini CLI、Cursor 等 TUI 工具启动时自动加载,另配合.ai-agents/codex/preferences.yaml与.ai-agents/gemini/preferences.yaml的各自偏好配置。
两套体系内容一致、只是文件位置与格式不同,而 .ai-agents/ 目录下的 workflows、templates 与 .ai-workspace/ 工作区则是两套体系共享的协作机制。
二、5 分钟快速开始:跑通一个协作任务
1. 创建你的第一个协作任务
# 复制任务模板
cp .ai-agents/templates/task.md .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
随后编辑任务文件,填写:
- 任务标题
- 任务描述
- 选择工作流(feature-development / bug-fix / code-review / refactoring)
任务文件是 YAML front matter + Markdown 正文的结构(模板见 .ai-agents/templates/task.md),其中 front matter 的关键元数据字段如下:
| 字段 | 取值示例 | 说明 |
|---|---|---|
id |
TASK-{yyyyMMdd-HHmmss} |
任务唯一标识,推荐即 .ai-workspace/active/ 下的目录名 |
type |
feature / bugfix / refactor / review / docs |
任务类型 |
workflow |
feature-development / bug-fix / code-review / refactoring |
采用的工作流 |
status |
active / blocked / completed |
任务状态 |
current_step |
requirement-analysis |
当前所处步骤 id |
assigned_to |
claude / codex / gemini / 留空 |
当前由哪个 AI 处理,留空表示等待认领 |
正文中包含任务描述、当前状态、上下文文件清单、相关资源、工作流进度、交接信息等章节,用于承载完整上下文。.ai-workspace/ 是已被 git ignore 的临时工作区(见 .gitignore),无需提交到版本库。
2. 使用 ClaudeCode 分析需求
在 Claude Code 中执行:
请分析 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md 中的任务
ClaudeCode 会:
- 读取任务描述
- 分析相关代码
- 创建需求分析报告:
.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/analysis.md
3. ClaudeCode 设计技术方案
请为 TASK-{yyyyMMdd}-{task-id} 设计技术方案
ClaudeCode 会创建 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/plan.md。
人工检查点:此步骤完成后,务必人工审查方案是否合理,再进入实现阶段。
4. 切换到 Codex/GeminiCli 实现代码
使用 Codex (OpenAI/ChatGPT):
请根据 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md 实现代码。
参考方案:.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/plan.md
或使用 GeminiCli:
请根据 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md 实现代码。
参考方案:.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/plan.md
AI 会:
- 读取任务和方案
- 编写代码实现
- 编写单元测试
- 创建实现报告:
.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/implementation.md
5. 切换回 ClaudeCode 审查代码
在 Claude Code 中:
请审查 TASK-{yyyyMMdd}-{task-id} 的实现
ClaudeCode 会:
- 读取实现报告
- 审查代码变更
- 创建审查报告:
.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/review.md
6. 根据审查结果决定
如果审查通过:
/commit
如果需要修改:切换到 Codex 或 GeminiCli 修复问题,然后重新审查。
三、四个内置工作流:从推荐流程到可执行 YAML
.ai-agents/workflows/ 目录以 YAML 格式定义了四个工作流,每个步骤都包含 required_capabilities(能力要求)、recommended_agents(推荐 AI)、tasks(任务清单)、inputs/outputs(输入输出文件)等字段:
| 工作流文件 | 适用场景 | 核心步骤链 |
|---|---|---|
| feature-development.yaml | 新功能开发 | requirement-analysis → technical-design → implementation → code-review → refinement → finalize |
| bug-fix.yaml | Bug 修复 | bug-analysis → bug-fix → code-review → finalize |
| code-review.yaml | 独立 PR/代码审查 | review-preparation → detailed-review → review-feedback |
| refactoring.yaml | 代码重构 | refactoring-analysis → refactoring-implementation → code-review → finalize |
以功能开发工作流为例,关键设计要点如下:
- 需求分析(推荐 Claude/Gemini):要求「code comprehension」「system analysis」「architecture understanding」能力,输出
analysis.md,必含需求理解、相关文件列表、影响范围评估、技术风险、依赖关系五个章节; - 技术方案设计(推荐 Claude):输出
plan.md,必含技术方案、实施步骤、文件清单、测试策略、性能考虑、安全考虑; - 代码实现(推荐 Codex/Gemini):输出
implementation.md,必含已修改文件列表、关键代码说明、测试结果、待审查事项、已知问题; - 代码审查(推荐 Claude):审查内容覆盖代码质量、OWASP Top 10 安全问题、性能影响、测试覆盖率、错误处理与可维护性,输出
review.md; - 问题修复(推荐 Codex/Gemini):条件为
review.status == 'needs_changes',逐项处理审查意见后重新进入 code-review; - 最终确认与提交:标注
human_decision: true,必须等待人工确认后才可执行 git commit。
工作流通过 human_checkpoints 定义人工检查点,例如功能开发在「技术方案设计之后」(required: true)与「最终提交之前」(required: true)各设一个强制检查点,保证人类始终掌握最终决策权。
四、常见场景:Bug 修复、代码审查与重构
场景 1:修复 Bug
# 1. 创建 Bug 任务
cp .ai-agents/templates/task.md .ai-workspace/active/BUG-{yyyyMMdd}-{task-id}/task.md
# 编辑:type: bugfix, workflow: bug-fix
# 2. ClaudeCode 分析 Bug
"请分析 BUG-{yyyyMMdd}-{task-id} 中的问题"
# 3. Codex/GeminiCli 修复 Bug
"请修复 BUG-{yyyyMMdd}-{task-id}"
# 4. ClaudeCode 审查修复
"请审查 BUG-{yyyyMMdd}-{task-id} 的修复"
# 5. 提交
/commit
Bug 工作流要求 bug-analysis 阶段输出 bug-analysis.md,必含 Bug 描述(现象、复现步骤、预期行为)、根本原因、相关代码、影响范围、修复思路;bug-fix 阶段除修复外还要求添加回归测试防止问题复现。
场景 2:代码审查
# 1. 创建审查任务
cp .ai-agents/templates/task.md .ai-workspace/active/REVIEW-PR-{task-id}/task.md
# 编辑:type: review, workflow: code-review
# 2. ClaudeCode 执行审查
/review {task-id}
# 或
"请审查 PR #{task-id}"
# 3. 根据审查报告采取行动
独立审查工作流的 detailed-review 步骤要求生成 review-report.md,包含总体评价(通过/需要修改/拒绝)、优点、按严重程度分类的问题清单、安全问题、性能建议、改进建议与批准建议。仓库提供了标准化的审查报告模板与交接文档模板,便于审查结果结构化沉淀。
场景 3:代码重构
# 1. 创建重构任务
cp .ai-agents/templates/task.md .ai-workspace/active/REFACTOR-{yyyyMMdd}-{task-id}/task.md
# 编辑:type: refactor, workflow: refactoring
# 2. ClaudeCode 分析和规划
"请分析 REFACTOR-{yyyyMMdd}-{task-id} 并制定重构计划"
# 3. 审查重构计划(重要!)
# 4. ClaudeCode 或 Codex/GeminiCli 执行重构
"请执行 REFACTOR-{yyyyMMdd}-{task-id} 的重构"
# 5. 审查 + 提交
重构工作流强调「小步快跑」:refactoring-analysis 阶段输出 refactoring-plan.md(问题分析、重构目标、重构策略、风险评估、测试策略);refactoring-implementation 阶段要求每步保持测试通过、频繁验证,输出 refactoring-result.md,再进入 code-review 与 finalize。
五、最佳实践
1. 任务命名规范
TASK-{yyyyMMdd-序号}.md # 一般任务
BUG-{yyyyMMdd-序号}.md # Bug修复
FEAT-{yyyyMMdd-序号}.md # 新功能
REFACTOR-{yyyyMMdd-序号}.md # 重构
REVIEW-PR-{pr-number}.md # PR审查
2. 关键检查点
每个任务至少有 2 个人工检查点:
- 方案设计后:确保技术方案合理
- 最终提交前:确保所有变更正确
3. 上下文完整性
确保每个步骤都创建完整的输出文件:
analysis.md- 需求分析plan.md- 技术方案implementation.md- 实现报告review.md- 审查报告
这样任何 AI 都能接手任务,这也是多 AI 协作「上下文共享」的核心——.ai-workspace/active/{task-id}/ 目录就是任务状态的唯一事实来源。
4. AI 切换时机
切换到 ClaudeCode:
- 需要系统性分析
- 代码审查
- 架构设计
- 安全审计
切换到 Codex (OpenAI/ChatGPT):
- 快速实现功能
- 编写单元测试
- 修复简单问题
- 快速迭代开发
切换到 GeminiCli (Google Gemini):
- 大规模代码分析
- 全局重构
- 复杂问题修复
- 需要超大上下文的任务
各 AI 的偏好配置还通过 codex/preferences.yaml 与 gemini/preferences.yaml 固化其行为:例如两者均设置 git.auto_commit: false、auto_push: false,即默认不自动提交、不推送,一切提交等待人工确认;Codex 配置为 Implementation & Testing Specialist,Gemini 配置为 Implementation & Multimodal Specialist,并各自声明了 recommended_steps(Codex 推荐 implementation/refinement/bug-fix,Gemini 推荐 implementation/refinement/bug-fix/code-review-assistance)。
5. 灵活应对
工作流是推荐,不是强制:
- 简单任务可以跳过某些步骤
- 可以根据实际情况调整顺序
- 人类始终拥有最终决策权
六、故障排查
问题 1:AI 不知道任务在哪里
解决方案:明确指定任务文件
请处理 .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
问题 2:上下文丢失
解决方案:检查 context 目录
ls -la .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/
确保每个步骤都创建了输出文件。
问题 3:任务状态不清楚
解决方案:查看任务文件
cat .ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/task.md
检查 current_step 和 assigned_to 字段。
问题 4:工作流程不清楚
解决方案:查看工作流定义
cat .ai-agents/workflows/feature-development.yaml
此外,Claude Code 用户可以直接使用 /check-task {task-id} 命令查看结构化状态报告(当前步骤、工作流进度、上下文文件清单与下一步建议),相关实现见 .claude/commands/check-task.md。
七、Claude Code 的 Slash Commands:协作的快捷键
Claude Code 的协作能力通过 .claude/commands/ 目录下的 19 个 Slash Commands 落地(详见 .claude/CLAUDE.md 与 .claude/commands/):
开发相关:
/commit [message] # 提交代码
/upgrade-dep <name> <old> <new> # 升级依赖
/test # 运行完整测试
/test-integration # 运行集成测试
任务管理:
/create-task <description> # 从自然语言描述创建任务
/analyze-issue <number> # 分析 GitHub Issue
/plan-task <task-id> # 设计技术方案
/implement-task <task-id> # 实施任务
/review-task <task-id> # 审查代码
/complete-task <task-id> # 完成任务
/check-task <task-id> # 查看状态
PR 和同步:
/pr [branch] # 创建 PR
/sync-issue <number> # 同步进度到 Issue
其中 /commit 会在提交前强制检查用户本地修改(先 git status --short 与 git diff)、动态更新版权头年份(date +%Y 获取当前年份,禁止硬编码),并在提交后要求更新 task.md 的 current_step/updated_at/assigned_to 字段(见 .claude/commands/commit.md);/create-task 则严格限定唯一产出为 task.md 和 analysis.md 两个文件,禁止直接实现业务代码(见 .claude/commands/create-task.md)。
八、三个 AI 的特点与分工
ClaudeCode - 思考型专家
- 擅长:需求分析、方案设计、代码审查、安全审计
- 特点:深度推理、系统性思考、架构能力强
- 配置:
.claude/目录
Codex (OpenAI/ChatGPT) - 执行型专家
- 擅长:代码实现、快速迭代、单元测试
- 特点:代码生成速度快、补全准确
- 配置:
.ai-agents/codex/目录
GeminiCli (Google Gemini) - 全能型专家
- 擅长:大规模代码分析、复杂问题修复
- 特点:超大上下文窗口(2M tokens)
- 配置:
.ai-agents/gemini/目录
在 FIT Framework 中,推荐的实战分工是:思考型任务(分析/设计/审查)优先 ClaudeCode,执行型任务(编码/修复/测试)优先 Codex 或 GeminiCli,大型代码库分析优先 GeminiCli(超大上下文优势)。Codex 与 GeminiCli 可互为替代,前者适合快速迭代与原型开发,后者适合跨模块的全局重构与复杂改动(对比见 .ai-agents/codex/README.md)。
九、配套脚本:让协作任务可验证
.ai-agents/scripts/ 提供了两个公共脚本(详见 .ai-agents/scripts/README.md),用于让 AI 产出的代码可以被真实验证:
- fit-service.sh:FIT 服务管理脚本,提供
start/verify/stop/cleanup四个子命令。启动时自动检测 8080 端口占用、等待健康检查最多 60 秒;验证阶段依次检查/actuator/health、/actuator/plugins、/openapi.html三个接口(verify_all汇总结果);支持作为库被其他脚本source加载; - run-test.sh:完整测试流程,依次执行清理构建产物 → Maven 构建与单元测试(
mvn clean install -pl '!ohscript',日志写入.ai-workspace/logs/maven-build-{timestamp}.log)→ 创建动态插件目录 → 启动 FIT 服务 → 验证健康检查 → 验证 Swagger 页面 → 清理环境。
所有日志统一输出到 .ai-workspace/logs/ 目录并在测试完成后保留,便于问题排查。这也意味着在协作任务的「实现」步骤之后,可以直接运行 ./.ai-agents/scripts/run-test.sh 验证实现是否通过构建与集成测试,再进入审查环节。
十、提示与进一步学习
实践中的六条建议:
- 先小后大:从简单任务开始熟悉流程
- 保持沟通:在任务文件和输出文件中写清楚
- 人工确认:关键步骤一定要人工审查
- 定期清理:完成的任务可以移到 completed 目录
- 灵活调整:根据实际情况调整工作流
- 发挥优势:根据各 AI 的优势选择合适的工具
进一步阅读:
- 协作总指南:.ai-agents/README.md
- 工作流定义:.ai-agents/workflows/
- 任务模板:.ai-agents/templates/
- ClaudeCode 配置:.claude/README.md
- Codex 配置:.ai-agents/codex/README.md
- GeminiCli 配置:.ai-agents/gemini/README.md
有问题查看 .ai-agents/README.md 或询问项目维护者。