FIT Framework 多 AI 协作快速上手:Claude Code、Codex 与 Gemini CLI 的分工流水线实战

原创2026-10-15 09:25:031,630 阅读
文章标签:后端人工智能AI 应用Agent 框架RAGMCP 服务MCP Clients微服务插件系统流程编排依赖注入

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 会:

  1. 读取任务描述
  2. 分析相关代码
  3. 创建需求分析报告:.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 会:

  1. 读取任务和方案
  2. 编写代码实现
  3. 编写单元测试
  4. 创建实现报告:.ai-workspace/active/TASK-{yyyyMMdd}-{task-id}/implementation.md

5. 切换回 ClaudeCode 审查代码

在 Claude Code 中:

请审查 TASK-{yyyyMMdd}-{task-id} 的实现

ClaudeCode 会:

  1. 读取实现报告
  2. 审查代码变更
  3. 创建审查报告:.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 个人工检查点:

  1. 方案设计后:确保技术方案合理
  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 验证实现是否通过构建与集成测试,再进入审查环节。

十、提示与进一步学习

实践中的六条建议:

  1. 先小后大:从简单任务开始熟悉流程
  2. 保持沟通:在任务文件和输出文件中写清楚
  3. 人工确认:关键步骤一定要人工审查
  4. 定期清理:完成的任务可以移到 completed 目录
  5. 灵活调整:根据实际情况调整工作流
  6. 发挥优势:根据各 AI 的优势选择合适的工具

进一步阅读:

有问题查看 .ai-agents/README.md 或询问项目维护者。

登录后查看全文
fit-framework