本目录包含 FIT Framework 项目的 AI 智能体协作配置，支持多个主流 AI 工具（Claude Code、Codex、Gemini CLI、Cursor 等）在同一项目中高效协作。

💡 提示：如需快速了解项目规范，请先阅读对应工具的配置文件（详见下方"配置体系说明"）。本文档专注于多 AI 协作机制的详细说明。

本项目采用双轨配置体系，不同 AI 工具使用不同的配置文件：

适用工具：Claude Code

配置文件：

• .claude/CLAUDE.md - 快速参考（启动时自动加载）
• .claude/project-rules.md - 详细规则
• .claude/commands/ - Slash Commands 实现

特点：

• Claude Code 专属配置，包含 Slash Commands 和特定规则
• 自包含，不依赖其他配置文件
• 启动时自动加载 .claude/CLAUDE.md

适用工具：Codex CLI、Gemini CLI、Cursor、其他 TUI 工具

配置文件：

• AGENTS.md - 项目开发规范（根目录）
• .agents/codex/preferences.yaml - Codex 特定配置
• .agents/gemini/preferences.yaml - Gemini 特定配置

特点：

• 遵循 AGENTS.md 标准（Linux Foundation AAIF）
• 轻量级，专注于项目开发规范
• 启动时自动加载 AGENTS.md

项目规范（两套独立但内容一致）
    ├── 体系 A：.claude/ (Claude Code 使用)
    │   ├── CLAUDE.md (快速参考)
    │   └── project-rules.md (详细规则)
    │
    └── 体系 B：AGENTS.md (其他工具使用)
        ├── AGENTS.md (项目规范)
        └── .agents/{tool}/preferences.yaml (工具配置)

协作机制（两套体系共享）
    └── .agents/ (多 AI 协作配置)
        ├── workflows/ (工作流定义)
        ├── templates/ (任务模板)
        └── README.md (本文件 - 协作指南)

工作区（两套体系共享）
    └── .ai-workspace/ (任务跟踪和上下文共享)
        ├── active/ (进行中的任务)
        ├── blocked/ (被阻塞的任务)
        └── completed/ (已完成的任务)

为什么需要两套体系？

• Claude Code 仅加载 .claude/CLAUDE.md，不会自动读取 AGENTS.md
• 其他 TUI 工具遵循 AGENTS.md 标准，自动加载根目录的 AGENTS.md
• 两套体系内容一致，只是文件位置和格式不同

.agents/                  # AI配置目录（版本控制）
├── README.md               # 本文件
├── workflows/              # 工作流定义（推荐流程）
│   ├── feature-development.yaml
│   ├── bug-fix.yaml
│   ├── code-review.yaml
│   └── refactoring.yaml
├── templates/              # 任务模板
│   ├── task.md            # 任务跟踪模板
│   ├── handoff.md         # 交接文档模板
│   └── review-report.md   # 审查报告模板
├── codex/                  # Codex (OpenAI/ChatGPT) 专用配置
│   ├── preferences.yaml
│   └── README.md
└── gemini/                 # Gemini 专用配置
    ├── preferences.yaml
    └── README.md

.ai-workspace/              # 工作目录（临时文件，被 git ignore）
├── active/                 # 进行中的任务
│   └── {task-id}/
│       ├── task.md        # 任务主文件
│       ├── analysis.md    # 需求分析
│       ├── plan.md        # 技术方案
│       ├── implementation.md  # 实现报告
│       └── review.md      # 审查报告
├── completed/             # 已完成的任务
│   └── {task-id}/
│       └── task.md + context files
├── blocked/               # 被阻塞的任务
│   └── {task-id}/
│       └── task.md + context files
└── logs/                  # 执行日志

1. 需求分析（推荐：ClaudeCode）

   • 理解需求，分析现有代码
   • 输出：.ai-workspace/active/{task-id}/analysis.md

2. 方案设计（推荐：ClaudeCode）

   • 设计技术方案，制定计划
   • 输出：.ai-workspace/active/{task-id}/plan.md

3. 代码实现（推荐：Codex / GeminiCli）

   • 根据方案编写代码和测试
   • 输出：.ai-workspace/active/{task-id}/implementation.md

4. 代码审查（推荐：ClaudeCode）

   • 审查代码质量、安全性、性能
   • 输出：.ai-workspace/active/{task-id}/review.md

5. 问题修复（任意 AI）

   • 根据审查意见修复问题
   • 循环到代码审查

6. 最终提交（人工确认）

   • 人工审核后执行提交

重要：以上流程是推荐而非强制，人类决定使用哪个 AI 执行哪个步骤。

基于三个独立评估的综合结果（满分 5 分），帮助你选择最合适的 AI 工具：

ClaudeCode

• 🧠 最擅长: 需求分析、方案设计、代码审查、最终提交
• 💡 核心优势: 深度推理、系统性分析、架构设计、安全审查 (OWASP Top 10)
• 🎯 定位: 架构师 + 审查员 + 质量把关者
• 📝 特色: 内置 /commit 命令，深度理解项目规范
• 🔧 配置: .claude/ 目录（项目根目录）

Codex (OpenAI/ChatGPT)

• 🧠 最擅长: 代码实现、问题修复
• 💡 核心优势: 代码生成速度快、补全准确、快速迭代
• 🎯 定位: 超级程序员
• 📝 特色: 代码生成效率最高，实现阶段首选
• 🔧 配置: .agents/codex/ 目录

GeminiCli (Google Gemini)

• 🧠 最擅长: 需求分析、代码实现、问题修复
• 💡 核心优势: 超大上下文 (2M tokens)、全局分析、快速编码
• 🎯 定位: 全能助手 + 分析师
• 📝 特色: 可一次性加载海量代码进行全局分析
• 🔧 配置: .agents/gemini/ 目录

思考型任务 (分析/设计/审查) → 优先选择 ClaudeCode
执行型任务 (编码/修复/测试) → 优先选择 Codex 或 GeminiCli
大型代码库分析           → 优先选择 GeminiCli (超大上下文优势)
安全审查和架构评估       → 必须使用 ClaudeCode
快速迭代和原型开发       → 优先选择 Codex

任何 AI 都可以通过读取以下内容接手任务：

• 任务文件：.ai-workspace/active/{task-id}/task.md
• 上下文：.ai-workspace/active/{task-id}/

# 复制任务模板
cp .agents/templates/task.md .ai-workspace/active/TASK-{task-id}/task.md

# 编辑任务描述
vim .ai-workspace/active/TASK-{task-id}/task.md

在 Claude Code 中：

请分析并设计 TASK-{task-id} 的实现方案

ClaudeCode 会：

• 读取任务文件
• 分析现有代码
• 制定技术方案
• 输出到 context 目录

使用 Codex (OpenAI/ChatGPT)：

根据 .ai-workspace/active/TASK-{task-id}/task.md 实现代码
参考方案：.ai-workspace/active/TASK-{task-id}/plan.md

或使用 GeminiCli：

根据 .ai-workspace/active/TASK-{task-id}/task.md 实现代码
参考方案：.ai-workspace/active/TASK-{task-id}/plan.md

AI 会：

• 读取任务和方案
• 编写代码实现
• 编写单元测试
• 更新任务状态

在 Claude Code 中：

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

根据使用的 AI 工具提交代码（Claude Code 的 /commit 命令）

工作流文件位于 workflows/ 目录，使用 YAML 格式定义。

每个步骤包含：

• required_capabilities: 能力要求
• recommended_agents: 推荐的 AI（claude/codex/gemini）
• tasks: 任务清单
• inputs/outputs: 输入输出文件

详见各工作流文件。

不同 AI 工具会自动读取不同的项目指令文件：

测试方法：在不同位置创建带唯一标识符的 CLAUDE.md 文件（.claude/rules/、子目录、~/.claude/），观察 Claude 接收到的系统上下文。

核心结论：

1. 启动时加载（永久）

   • 加载位置：.claude/CLAUDE.md + .claude/rules/*.md + ~/.claude/CLAUDE.md
   • 注入方式：拼接到系统提示词（持续生效）
   • 合并策略：简单拼接，无智能合并

2. 按需加载（临时）

   • 加载位置：子目录 CLAUDE.md（如 test-subdir/CLAUDE.md）
   • 触发时机：首次 Read 该目录下文件时
   • 注入方式：通过 <system-reminder> 注入到函数结果（临时生效）
   • 限制：Write 工具不触发加载

3. 文件组织建议

   .claude/
   ├── CLAUDE.md            # 核心配置（100-200 行）
   └── rules/               # 模块化规则（每个 50-100 行）
       ├── 01-xxx.md        # 用数字前缀控制顺序
       └── 02-yyy.md
   

注意事项：

• 避免重复定义规则（拼接时不去重）
• 控制总长度（建议 .claude/ 总计 ≤500 行）
• 子目录规则按需加载（节省 token）

测试方法：

1. 创建多级目录 .gemini-test/level1/level2/
2. 在各级目录放置包含特定指令（Tag）的 AGENTS.md
3. 运行时 cd 进入深层目录，观察回复是否包含所有 Tag
4. 结论：无需重启，目录切换即时生效，所有层级的 AGENTS.md 内容被拼接注入

核心结论：

1. 配置驱动加载

   • 默认行为：Gemini CLI 默认查找 GEMINI.md。
   • 项目配置：本项目通过 .gemini/settings.json 的 context.fileName 字段将其重写为 ["AGENTS.md"]，以遵循 Linux Foundation AAIF 标准。
   • 加载源：因此，实际加载的是 AGENTS.md。

2. 级联加载（Cascading Context）

   • 触发机制：依赖 CLI 启动时的目录。

     • Gemini CLI 的 Shell 环境通常在每轮对话后重置，因此 Agent 无法通过 cd 命令持久切换目录。
     • 如果需要加载子模块规则（如 framework/fit/AGENTS.md），用户必须在该目录下启动 Gemini CLI，或者在该目录下运行 IDE。

   • 级联顺序： Global (~/.gemini/) + Project Root + ... + Parent Dir + Current Dir

   • 合并策略：简单拼接（Concatenation）。

   • 💡 使用技巧：如何临时激活子目录规则？ 虽然 Agent 无法持久保持目录状态，但您可以在 Prompt 中明确指示上下文。

     • 方法 1（推荐）：“请进入 framework/fit 目录，检查 Main.java 的代码规范”。
       • 结果：Agent 执行 cd，CLI 立即加载 framework/fit/AGENTS.md，规则在当前回复中生效。
     • 方法 2（手动引用）：“请参考 framework/fit/AGENTS.md 的规则进行开发”。
       • 结果：Agent 读取文件内容作为普通上下文使用。

3. 文件组织建议

   • 根目录 AGENTS.md：存放绝大多数通用规则。这是最安全、最可靠的地方。
   • 子目录 AGENTS.md：仅用于那些用户通常会在该目录下启动终端进行开发的独立子项目。对于普通的模块化项目，建议尽量将规则合并到根目录，避免因目录层级问题导致规则未加载。

测试方法：

1. 在项目根创建多级目录 codex-agents-test/level1/level2/
2. 在各级目录放置包含特定指令（Tag）的 AGENTS.md
3. 在项目根启动 Codex CLI（v0.92.0）
4. 执行 cd 后再 pwd，并读取子目录文件（如 test.md），询问是否加载子目录 AGENTS.md

核心结论：

1. 命令级 Shell（无目录持久化）

   • cd 只对当前命令生效
   • 下一轮命令会回到启动目录

2. 启动时加载

   • 仅加载启动目录的 AGENTS.md（或 ~/.codex/AGENTS.md）
   • 没有发现自动级联加载多级目录规则

3. 无按需加载

   • 读取子目录文件不会触发自动注入该目录下的 AGENTS.md

4. 使用技巧

   • 需要子目录规则时，必须在该目录启动 Codex CLI
   • 或在 Prompt 中明确指示："请读取 path/to/AGENTS.md 并严格遵守其中规则"

测试方法：基于 OpenCode 开源代码（packages/opencode/src/session/）的实现逻辑分析

核心结论：

OpenCode 的配置注入机制是最复杂且最智能的，原因：

1. 支持多模型（Claude、GPT、Gemini、Qwen 等），每个模型有独立的系统提示词
2. 分层注入（7 层提示词架构）
3. 动态按需加载（Read 工具自动向上遍历）
4. 支持远程配置（HTTP URL + glob 匹配）

1. 启动时加载（永久生效）

加载优先级（找到一个就停止）：

• 项目级：AGENTS.md > CLAUDE.md > CONTEXT.md
• 全局级：~/.config/opencode/AGENTS.md > ~/.claude/CLAUDE.md > $OPENCODE_CONFIG_DIR/AGENTS.md
• 用户自定义：opencode.json 中的 config.instructions（支持 glob 和 HTTP URL）

关键特性：

• ✅ 按优先级去重（项目级和全局级各取一个）
• ✅ 支持远程配置（HTTP URL，5 秒超时）
• ✅ 支持 glob 匹配（如 packages/*/AGENTS.md）

2. 按需加载（临时生效）

触发时机：首次 Read 工具读取某个目录下的文件时

行为：

• 从当前文件目录向上遍历到项目根目录
• 查找每级目录的 AGENTS.md/CLAUDE.md/CONTEXT.md
• 通过 <system-reminder> 标签注入到 Read 工具输出中
• 三层去重：不在系统提示词中 + 不在已加载列表 + 不在当前消息已加载

关键特性：

• ✅ 智能去重（避免重复注入）
• ✅ 向上遍历（自动加载父目录配置）
• ✅ 消息级缓存（同一消息不重复）
• ⚠️ 只有 Read 工具触发（Write/Edit/Bash 不触发）

3. 多模型支持

模型特定提示词：

• Claude：prompt/anthropic.txt
• GPT/O1/O3：prompt/beast.txt
• Gemini：prompt/gemini.txt
• Codex（GPT-5）：prompt/codex_header.txt
• 其他（Qwen 等）：prompt/qwen.txt

特殊处理：

• Codex 通过 options.instructions 发送系统提示词
• 其他模型通过 system 消息发送
• Agent 自定义提示词优先级高于模型默认提示词

4. 配置层次总结

5. 文件组织建议

project/
├── AGENTS.md                    # 核心配置（所有模型共享）
├── .claude/CLAUDE.md            # Claude Code 专用（可选）
├── packages/
│   ├── api/AGENTS.md            # API 模块规则（Read 时加载）
│   └── web/AGENTS.md            # Web 模块规则（Read 时加载）
└── opencode.json                # 可选：远程配置 + glob

6. 使用技巧

• 节省 token：将通用规则放根目录，模块特定规则放子目录（按需加载）
• 远程配置：适合公司统一规范或开源社区规则，但关键规则建议本地存储
• 多模型项目：利用 OpenCode 的多模型支持，为不同模型配置不同提示词

ClaudeCode 的配置保持在 .claude/ 目录（项目根目录），包括：

• Slash Commands
• Project Rules
• Permissions

参考：.claude/README.md

Codex (OpenAI/ChatGPT) 的配置在 .agents/codex/ 目录。

GeminiCli 的配置在 .agents/gemini/ 目录。

所有 AI 都应该：

1. 读取 AGENTS.md（项目根目录）获取项目开发规范
2. 遵循 .agents/workflows/ 中的工作流定义
3. 使用 .ai-workspace/ 进行任务跟踪和上下文共享

以下步骤需要人工确认：

1. 方案设计完成后：审查技术方案是否合理
2. 代码审查完成后：决定是否需要修改
3. 最终提交前：确认所有变更无误

• .ai-workspace/{status}/{task-id}/ 包含任务的完整上下文
• 切换 AI 时，新的 AI 会读取这些文件了解进度
• 保持文档完整和准确，便于协作

• tasks/active/：正在进行的任务
• tasks/blocked/：遇到问题被阻塞的任务
• tasks/completed/：已完成的任务（可定期清理）

• 主配置文件：AGENTS.md（中文）、AGENTS.en.md（英文）
• ClaudeCode 配置：.claude/README.md
• Codex 配置：.agents/codex/README.md
• GeminiCli 配置：.agents/gemini/README.md
• 贡献指南：CONTRIBUTING.md
• PR 模板：.github/PULL_REQUEST_TEMPLATE.md

如果你之前使用单一 AI 工具，现在想启用多 AI 协作：

1. ✅ 保持现有配置（.claude/、.agents/codex/、.agents/gemini/）
2. ✅ 创建 .ai-workspace/ 目录（已被 git ignore）
3. ✅ 开始使用任务模板进行协作
4. ✅ 不需要修改现有工作流程

A: 不是。工作流是推荐的最佳实践，你可以灵活调整。

A: 可以。这个配置也支持单 AI 工作，只是提供了多 AI 协作的能力。

A: 查看任务文件的 current_step 字段和 context/ 目录下的文件。ClaudeCode 用户可使用 /check-task 命令。

A: 不需要，这是临时工作目录，已在 .gitignore 中忽略。

A: 定期删除 tasks/completed/ 和 context/ 下的旧任务文件。

A: 不是必需的。你可以根据需要选择安装其中一个或多个。配置支持灵活组合。

配置版本: 2.0.0 支持 AI: ClaudeCode, Codex, GeminiCli 基于标准: AGENTS.md (Linux Foundation AAIF)