Feagent CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

项目概述

Feagent 是企业级AI Agent编排与执行平台，基于 FastAPI + LangChain + DDD-lite 架构。

当前阶段: 多Agent协作系统（Phase 8+ - Unified Definition System）

• 三Agent架构：CoordinatorAgent、ConversationAgent、WorkflowAgent
• EventBus事件驱动通信
• 八段压缩器（PowerCompressor）
• WebSocket实时通道
• 可配置规则引擎与干预系统
• 自描述节点验证与依赖图

---

Claude ↔ Codex 协作工作流（精简版）

1. 需求理解 → Claude 快速识别疑问 → Codex 深度推理
2. 上下文收集 → Codex 全面检索 → 输出分析报告
3. 任务规划 → Claude 基于分析制定计划
4. 代码执行 → Claude 直接编码（遇复杂逻辑调用 Codex）
5. 质量审查 → Codex 深度审查 → Claude 最终决策

角色分工 / 产出

• Claude：提炼问题、制定计划、落地代码与决策
• Codex：深度推理/检索、给出代码原型（统一 diff 参考）、质量审查
• 产出物：分析报告 → 计划 → 代码原型参考 → 落地实现 → Codex Review 意见 → Claude 采纳/决策

与现有规则/架构的对齐

• 对应“架构顺序”：需求分析→Domain→Ports→Infrastructure→Application→Interface；在 Domain/Ports 阶段优先让 Codex 做深推与检索。
• 代码执行阶段继续遵守“每次最多改 2 个文件 + TDD”与命名约定。
• 前端/后端改动时保持原有项目结构；Codex 仅给出参考 patch，真实修改由 Claude 完成。
• 关于 Codex 详细调用规范与合作要求，沿用文末《Core Instruction for CodeX MCP》与《Codex Tool Invocation Specification》。

---

关键规则（必读）

开发约束

1. 开发节奏：每次最多修改2个文件，等待用户确认后继续

2. TDD强制：Red → Green → Refactor

   • Domain层覆盖率 ≥ 80%
   • Application层覆盖率 ≥ 70%

3. 架构顺序（严格）：

   需求分析 → Domain → Ports → Infrastructure → Application → Interface
   

4. 依赖方向（单向）：

   Interface → Application → Domain ← Infrastructure
   

   Domain层禁止导入: SQLAlchemy、FastAPI、LangChain 或任何框架

命名约定

模式	含义	示例
get_xxx	必须存在，否则抛异常	get_agent(id)
find_xxx	允许返回None	find_agent(id)
XxxUseCase	应用层用例	CreateAgentUseCase
XxxInput/Request/Response	DTO	CreateAgentInput

---

开发命令

后端

# 安装依赖
pip install -e ".[dev]"

# 数据库迁移
alembic upgrade head
alembic revision --autogenerate -m "description"

# 启动服务器（Windows 必须使用 python -m）
python -m uvicorn src.interfaces.api.main:app --reload --port 8000

# 测试
pytest                                              # 全部测试
pytest tests/unit                                   # 单元测试
pytest tests/integration                            # 集成测试
pytest tests/unit/domain/entities/test_agent.py -v # 单个文件
pytest -k "test_create_agent"                       # 按名称

# 代码质量
ruff check .                             # Lint
ruff format .                            # Format
pyright src/                             # 类型检查