Claude 代码智能体农场 🤖🚜

协调多个 Claude 代码智能体并行工作，通过自动化修复 bug 或系统化实施最佳实践来优化您的代码库

🎯 这是什么？

Claude 代码智能体农场是一个强大的编排框架，可并行运行多个 Claude 代码 (cc) 会话，以系统化地改进您的代码库。它支持多种技术栈和工作流类型，允许 AI 智能体团队协同完成大规模的代码优化任务。

核心特性

• 🚀 并行处理：可同时运行 20 多个 Claude 代码智能体（使用 max_agents 配置最高可达 50 个）
• 🎯 多工作流支持：包括 bug 修复、最佳实践实施，或协调一致的多智能体开发
• 🤝 智能体协作：先进的锁机制防止并行智能体之间的冲突
• 🌐 多技术栈支持：涵盖 34 种技术栈，包括 Next.js、Python、Rust、Go、Java、Angular、Flutter、C++ 等
• 📊 智能监控：实时仪表板显示上下文警告、心跳状态跟踪及 tmux 窗格标题
• 🔄 自动恢复：根据工作模式自适应空闲超时，必要时自动重启智能体
• 📈 进度追踪：生成带有丰富差异摘要的 Git 提交，并提供全面的 HTML 运行报告
• 🔄 上下文管理：智能体在接近限制时自动清理自身上下文；同时支持一键向所有智能体广播 /clear 命令（Ctrl+R）
• ⚙️ 高度可配置：基于 JSON 的配置文件，支持变量替换与动态分块大小调整
• 🖥️ 灵活查看：多种 tmux 查看模式，并支持 Shell 自动补全
• 🔒 安全运行：自动进行设置备份与恢复，结合按大小轮转、文件锁定及原子操作确保安全性
• 🛠️ 开发环境搭建：集成 24 个工具安装脚本及预检验证功能
• 🎯 智能控制：优雅关闭程序，若在 3 秒内连续两次按下 Ctrl+C，则强制终止进程

📋 先决条件

• Python 3.13+（由 uv 管理）
• tmux（用于终端多路复用）
• Claude 代码（已安装并配置 claude 命令）
• git（用于版本控制）
• 项目所需工具（如 Next.js 使用 bun，Python 使用 mypy/ruff 等）
• direnv（可选但推荐，用于自动激活环境）
• uv（现代 Python 包管理器）

重要提示：cc 别名

智能体农场需要一个特殊的 cc 别名，以便以必要的权限启动 Claude 代码：

alias cc="ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions"

此别名将由安装脚本自动配置。

🚀 快速开始

1. 克隆并设置

git clone https://github.com/Dicklesworthstone/claude_code_agent_farm.git
cd claude_code_agent_farm
chmod +x setup.sh
./setup.sh

安装脚本将执行以下操作：

• 检查并安装缺失的先决条件
• 创建 Python 3.13 虚拟环境
• 安装所有依赖项
• 配置 cc 别名，自动检测并修正常见引号错误
• 验证现有别名，并修复不正确的引号模式
• 设置 direnv 以实现环境的自动激活
• 自动适配 bash 和 zsh shell

2. 验证设置

运行预检验证程序，确保所有配置正确无误：

claude-code-agent-farm doctor --path /path/to/project

该命令将检查：

• Python 版本兼容性
• 必要工具是否已安装（tmux、git、uv）
• Claude 代码配置及 API 密钥
• 项目特定工具的可用性
• 文件权限及其他常见问题

3. 启用 Shell 补全（可选）

若需更快地输入命令并享受 Tab 补全功能：

# 自动检测 Shell 并安装补全
claude-code-agent-farm install-completion

# 或者手动指定 Shell
claude-code-agent-farm install-completion --shell bash
claude-code-agent-farm install-completion --shell zsh
claude-code-agent-farm install-completion --shell fish

4. 选择您的工作流

用于传统 Bug 修复

# Next.js 项目
claude-code-agent-farm --path /path/to/project --config configs/nextjs_config.json

# Python 项目
claude-code-agent-farm --path /path/to/project --config configs/python_config.json

用于最佳实践实施

# 确保您已准备好最佳实践指南
cp best_practices_guides/NEXTJS15_BEST_PRACTICES.md /path/to/project/best_practices_guides/

# 使用最佳实践配置运行
claude-code-agent-farm --path /path/to/project --config configs/nextjs_best_practices_config.json

🛠️ 工具安装脚本

该项目包含一套全面的模块化系统，用于快速搭建开发环境：

可用的设置脚本

运行交互式菜单：

cd tool_setup_scripts
./setup.sh

或者直接运行特定的设置脚本：

1. Python FastAPI (setup_python_fastapi.sh)

   • Python 3.12+、uv、ruff、mypy、pre-commit、ipython

2. Go Web 应用 (setup_go_webapps.sh)

   • Go 1.23+、golangci-lint、air、migrate、mockery、Task、swag

3. Next.js (setup_nextjs.sh)

   • Node.js 22+、Bun、pnpm、TypeScript、ESLint、Prettier

4. SvelteKit/Remix/Astro (setup_sveltekit_remix_astro.sh)

   • 基于 Next.js 设置，扩展了 Vite、Playwright、Vitest、Biome 等工具

5. Rust 开发 (setup_rust.sh)

   • Rust 工具链、cargo 工具、Web 和系统编程相关工具

6. Java 企业级开发 (setup_java_enterprise.sh)

   • Java 21 LTS、SDKMAN、Gradle 8.11+、Maven 3.9+、JBang

7. Bash/Zsh 脚本编写 (setup_bash_zsh.sh)

   • Shell 开发工具及最佳实践

8. 云原生 DevOps (setup_cloud_native_devops.sh)

   • Docker、Kubernetes、Terraform、各类云工具

9. GenAI/LLM 运维 (setup_genai_llm_ops.sh)

   • 机器学习/人工智能开发工具与框架

10. 数据工程 (setup_data_engineering.sh)

    • 数据处理与分析相关工具

11. 无服务器边缘计算 (setup_serverless_edge.sh)

    • 无服务器与边缘计算相关工具

12. Terraform Azure (setup_terraform_azure.sh)

    • Terraform、Azure CLI、基础设施相关工具

13. Angular (setup_angular.sh)

    • Node.js、Angular CLI、TypeScript、测试工具

14. Flutter (setup_flutter.sh)

    • Flutter SDK、Dart、Android Studio、开发工具

15. React Native (setup_react_native.sh)

    • React Native CLI、移动开发相关工具

此外还提供以下设置脚本：

• PHP/Laravel (setup_php_laravel.sh)
• C++ 系统开发 (setup_cpp_systems.sh)
• Solana/Anchor (setup_solana_anchor.sh)
• Ansible (setup_ansible.sh)
• LLM 开发测试 (setup_llm_dev_testing.sh)
• LLM 评估与可观ility (setup_llm_eval_observability.sh)
• Kubernetes AI 推理 (setup_kubernetes_ai_inference.sh)

设置功能

• 🎨 交互式且安全：彩色提示信息，安装前始终询问确认
• 🔍 智能检测：检查现有安装情况以避免冲突
• 🛡️ 非破坏性：未经许可不会覆盖现有配置
• 🪟 兼容多种 Shell：支持 bash 和 zsh
• 📊 进度跟踪：显示已安装和待安装的内容

📖 架构说明

双脚本系统

该项目由两个独立但协同工作的脚本组成：

1. Python 脚本 (claude_code_agent_farm.py) - 大脑 🧠

这是主要的协调器，负责执行所有核心任务：

• 创建并管理带有多个窗格的 tmux 会话
• 通过运行配置的命令生成问题文件
• 在每个 tmux 窗格中启动 Claude Code 代理
• 监控代理的健康状况（上下文使用、工作状态、错误）
• 自动重启完成任务或遇到问题的代理
• 在 tmux 控制窗口中运行监控仪表板
• 支持通过 Ctrl+C 优雅关闭
• 管理设置的备份与恢复，防止损坏
• 实现文件锁机制以确保并发访问安全
• 将监控状态写入 JSON 文件以便外部监控

您只需运行此脚本，它就会持续运行（除非使用 --no-monitor 模式）。监控仪表板显示在 tmux 会话的控制窗口中，而不是启动终端中。

2. Shell 脚本 (view_agents.sh) - 窗口 🪟

这是一个可选的便捷工具，用于查看 tmux 会话：

• 不与 Python 脚本交互
• 在单独的终端中运行以查看代理活动
• 提供不同的查看模式（网格、聚焦、分屏）
• 仅是 tmux 命令的封装，方便使用
• 自动建议调整字体大小以适应大量代理

可以这样理解：

• Python 脚本 = 您的汽车引擎（负责所有工作）
• Shell 脚本 = 您的仪表盘摄像头（让您看到正在发生的事情）

隐藏命令

仅监控模式

有一个隐藏命令可用于仅运行监控界面：

claude-code-agent-farm monitor-only --path /project --session claude_agents

该命令读取监控状态文件并显示仪表板，而无需启动代理。

为什么采用双脚本设计？

1. 职责分离：核心逻辑（Python）与查看工具（Shell）
2. 灵活性：您可以仅监控代理，而不使用查看脚本
3. 独立性：任一脚本均可独立使用，无需另一脚本配合

🎮 支持的工作流

1. Bug 修复工作流

代理并行处理类型检查和 linter 问题：

• 运行您配置的类型检查和 linter 命令
• 生成合并的问题文件
• 代理随机选择部分问题进行修复
• 标记已完成的问题以避免重复
• 专注于修复现有问题
• 使用实例特定的种子以提高随机化效果

2. 最佳实践实施工作流

代理系统地实施现代最佳实践：

• 阅读全面的最佳实践指南
• 创建进度跟踪文档（@<STACK>_BEST_PRACTICES_IMPLEMENTATION_PROGRESS.md）
• 分阶段实施改进措施
• 跟踪每条准则的完成百分比
• 保持会话之间的连续性
• 支持通过特殊提示继续之前的工作

3. 协作智能体工作流（高级）

最复杂的 workflow 选项可以将智能体集群转变为一支协调一致的开发团队，从而实现复杂且具有战略意义的改进。令人惊讶的是，这一强大功能完全通过提示文件来实现！无需编写任何实际代码即可运行该系统；相反，大语言模型（尤其是 Opus 4）已经足够智能，能够理解并可靠地自主执行整个系统：

多智能体协调系统

此工作流实现了一种分布式协调协议，允许多个智能体同时在同一个代码库上协作而不会产生冲突。系统会在您的项目中创建一个 /coordination/ 目录结构：

/coordination/
├── active_work_registry.json     # 所有正在进行工作的中央注册表
├── completed_work_log.json       # 已完成任务的日志  
├── agent_locks/                  # 智能体锁文件目录
│   └── {agent_id}_{timestamp}.lock
└── planned_work_queue.json       # 计划但尚未开始的工作队列

工作原理

1. 唯一智能体身份：每个智能体生成一个唯一的 ID（agent_{timestamp}_{random_4_chars}）

2. 工作申领流程：在开始任何工作之前，智能体必须：

   • 检查活跃工作注册表以避免冲突
   • 创建锁文件以申领特定的文件和功能
   • 将其工作计划连同详细范围信息一起注册
   • 在整个工作周期中持续更新其状态

3. 防止冲突：锁文件系统可防止多个智能体：

   • 同时修改同一文件
   • 实现重叠的功能
   • 产生合并冲突或破坏性变更
   • 重复已完成的工作

4. 智能工作分配：智能体自动：

   • 从可用任务中选择不冲突的工作
   • 如果首选文件已被锁定，则将工作加入队列
   • 智能处理过期锁文件（超过 2 小时）
   • 通过描述性的 Git 提交进行协调

为何效果良好

该协调系统解决了几个关键问题：

• 消除合并冲突：基于锁的文件申领机制确保了干净的并行开发
• 防止重复劳动：智能体在开始工作前会检查已完成工作日志
• 支持复杂任务：与简单的 Bug 修复不同，智能体可以处理战略性改进
• 保持代码稳定性：功能测试要求可防止破坏性变更
• 高效扩展：20 多个智能体可以在互不干扰的情况下高效工作
• 聚焦业务价值：所有改进都需要经过论证和规划才能实施

高级特性

• 过期锁检测：自动处理超过 2 小时未使用的锁文件
• 紧急协调：针对严重冲突的告警系统
• 进度透明化：所有智能体都可以查看其他人在做什么
• 原子工作单元：每个智能体在释放锁之前都会完成完整的功能
• 详细规划：智能体必须在申领工作前制定全面的计划

最佳使用场景

此工作流特别适用于以下情况：

• 大规模重构项目
• 实施复杂的架构变更
• 在整个代码库中添加全面的类型注解
• 系统性的性能优化
• 多方面的安全改进
• 需要协调的特性开发

要使用此工作流，请指定协作智能体提示文件：

claude-code-agent-farm \
  --path /project \
  --prompt-file prompts/cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \
  --agents 5

🌐 技术栈支持

34 种支持的技术栈完整列表

该项目包含预配置的支持，涵盖以下领域：

Web 开发

1. Next.js - TypeScript、React 和现代 Web 开发
2. Angular - 企业级 Angular 应用程序
3. SvelteKit - 现代 Web 框架
4. Remix/Astro - 全栈 Web 框架
5. Flutter - 跨平台移动开发
6. Laravel - PHP Web 框架
7. PHP - 通用 PHP 开发

系统与编程语言

8. Python - FastAPI、Django 和数据科学工作流
9. Rust - 系统编程和 Web 应用程序
10. Rust CLI - 命令行工具开发
11. Go - Web 服务和云原生应用
12. Java - 使用 Spring Boot 的企业级应用
13. C++ - 系统编程和对性能要求极高的应用

DevOps 与基础设施

14. Bash/Zsh - Shell 脚本和自动化
15. Terraform/Azure - 基础设施即代码
16. 云原生 DevOps - Kubernetes、Docker 和 CI/CD
17. Ansible - 基础设施自动化和配置管理
18. HashiCorp Vault - 密钥管理和策略即代码

数据与 AI

19. GenAI/LLM Ops - AI/ML 运营和工具链
20. LLM 开发测试 - LLM 开发和测试工作流
21. LLM 评估与可观性 - LLM 评估和监控
22. 数据工程 - ETL、分析和大数据
23. 数据湖 - Kafka、Snowflake 和 Spark 集成
24. Polars/DuckDB - 高性能数据处理
25. Excel 自动化 - 基于 Python 的 Excel 自动化，并结合 Azure 使用
26. PostgreSQL 17 与 Python - 现代 PostgreSQL 17 结合 FastAPI/SQLModel

特殊领域

27. 无服务器边缘计算 - 边缘计算和无服务器架构
28. Kubernetes 上的 AI 推理 - 在 Kubernetes 上进行 AI 推理
29. 安全工程 - 安全最佳实践和工具
30. 硬件开发 - 嵌入式系统和硬件设计
31. Unreal Engine - 使用 Unreal Engine 5 进行游戏开发
32. Solana/Anchor - 在 Solana 上进行区块链开发
33. Cosmos - Cosmos 区块链生态系统
34. React Native - 跨平台移动开发

每个技术栈都包含：

• 优化后的配置文件
• 针对特定技术的提示
• 全面的最佳实践指南（共 31 份）
• 适当的分块大小和时间安排

自定义技术栈

您可以创建自己的配置：

{
  "comment": "自定义 Rust 配置",
  "tech_stack": "rust",
  "problem_commands": {
    "type_check": ["cargo", "check"],
    "lint": ["cargo", "clippy", "--", "-D", "warnings"]
  },
  "best_practices_files": ["./guides/RUST_BEST_PRACTICES.md"],
  "chunk_size": 30,
  "prompt_file": "prompts/rust_prompt.txt",
  "agents": 15,
  "max_agents": 50,
  "auto_restart": true,
  "git_branch": "feature/rust-improvements",
  "git_remote": "origin"
}

⚙️ 配置系统

核心配置选项

{
  "comment": "人类可读的描述",
  "tech_stack": "nextjs",
  "problem_commands": {
    "type_check": ["bun", "run", "type-check"],
    "lint": ["bun", "run", "lint"],
    "test": ["bun", "run", "test"]
  },
  "best_practices_files": ["./best_practices_guides/NEXTJS15_BEST_PRACTICES.md"],
  "chunk_size": 50,
  "agents": 20,
  "max_agents": 50,
  "session": "claude_agents",
  "prompt_file": "prompts/default_prompt_nextjs.txt",
  "auto_restart": true,
  "context_threshold": 20,
  "idle_timeout": 60,
  "max_errors": 3,
  "git_branch": null,
  "git_remote": "origin",
  "tmux_kill_on_exit": true,
  "tmux_mouse": true,
  "stagger": 10.0,
  "wait_after_cc": 15.0,
  "check_interval": 10,
  "skip_regenerate": false,
  "skip_commit": false,
  "no_monitor": false,
  "attach": false,
  "fast_start": false,
  "full_backup": false
}

关键参数

• tech_stack: 技术栈标识（支持34种技术栈之一）
• problem_commands: 用于类型检查、代码格式检查和测试的命令
• best_practices_files: 需要复制到项目中的最佳实践指南
• chunk_size: 每次代理迭代处理的基础行数或变更量（根据剩余工作动态调整）
• prompt_file: 使用哪个提示模板（共有36个可用模板）
• agents: 运行的代理数量（默认：20）
• max_agents: 允许的最大代理数量（默认：50）
• auto_restart: 启用自动重启代理
• context_threshold: 当上下文百分比低于此阈值时，自动清除上下文
• git_branch: 可选的特定分支，用于提交更改
• git_remote: 推送代码的远程仓库名称（默认：origin）

命令行选项

所有配置选项都可以通过命令行覆盖：

claude-code-agent-farm \
  --path /project \
  --config configs/base.json \
  --agents 10 \
  --chunk-size 30 \
  --auto-restart

完整选项参考

命令:
  doctor                   运行预启动验证检查
  monitor-only             显示监控仪表板（内部使用）

必填项:
  --path PATH               项目根目录

代理配置:
  --agents N, -n N         代理数量（默认：20）
  --session NAME, -s NAME  tmux会话名称（默认：claude_agents）
  --chunk-size N           覆盖配置中的chunk size

时间设置:
  --stagger SECONDS        代理启动之间的延迟（默认：10.0秒）
  --wait-after-cc SECONDS  启动代码检查工具后等待的时间（默认：15.0秒）
  --check-interval SECONDS 健康检查间隔时间（默认：10秒）

功能选项:
  --skip-regenerate        跳过重新生成问题文件
  --skip-commit           跳过git提交/推送
  --auto-restart          启用自动重启代理
  --no-monitor            仅启动代理并退出
  --attach                设置完成后附加到tmux会话

高级选项:
  --prompt-file PATH      自定义提示文件
  --config PATH           JSON配置文件
  --context-threshold N    当上下文百分比小于等于N%时，自动清除上下文（默认：20）
  --idle-timeout SECONDS   代理空闲N秒后标记为空闲状态（默认：60秒）
  --max-errors N           代理出现N次错误后禁用（默认：3次）
  --commit-every N         每隔N次重新生成周期后提交一次
  --tmux-kill-on-exit      退出时杀死tmux会话（默认：true）
  --no-tmux-kill-on-exit   退出后保持tmux会话运行
  --tmux-mouse             启用tmux鼠标支持（默认：true）
  --no-tmux-mouse          禁用tmux鼠标支持
  --fast-start             跳过shell提示符检测
  --full-backup            启动前对Claude设置进行完整备份

📝 提示系统

完整提示库（37个提示）

系统包含适用于所有工作流和技术栈的专用提示：

Bug修复提示（4个）

• default_prompt.txt - 通用Bug修复
• default_prompt_nextjs.txt - Next.js专用
• default_prompt_python.txt - Python专用
• bug_fixing_prompt_for_nextjs.txt - 高级Next.js修复

协作代理提示（1个）

• cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt - 多代理协作系统

最佳实践实施提示（31个）

• default_best_practices_prompt.txt - 通用实施
• continue_best_practices_prompt.txt - 继续现有工作

Web开发（7个）

• default_best_practices_prompt_nextjs.txt - Next.js 15
• default_best_practices_prompt_angular.txt - Angular
• default_best_practices_prompt_sveltekit.txt - SvelteKit
• default_best_practices_prompt_remix_astro.txt - Remix/Astro
• default_best_practices_prompt_flutter.txt - Flutter
• default_best_practices_prompt_laravel.txt - Laravel
• default_best_practices_prompt_php.txt - PHP

系统与语言（7个）

• default_best_practices_prompt_python.txt - Python/FastAPI
• default_best_practices_prompt_rust_web.txt - Rust Web应用
• default_best_practices_prompt_rust_system.txt - Rust系统
• default_best_practices_prompt_rust_cli.txt - Rust CLI工具
• default_best_practices_prompt_go.txt - Go应用
• default_best_practices_prompt_java.txt - Java企业应用
• default_best_practices_prompt_cpp.txt - C++系统

DevOps与基础设施（5个）

• default_best_practices_prompt_bash_zsh.txt - Shell脚本编写
• default_best_practices_prompt_terraform_azure.txt - IaC
• default_best_practices_prompt_cloud_native_devops.txt - DevOps
• default_best_practices_prompt_ansible.txt - Ansible自动化
• default_best_practices_prompt_vault.txt - HashiCorp Vault

数据与AI（7个）

• default_best_practices_prompt_genai_llm_ops.txt - AI/ML运维
• default_best_practices_prompt_llm_dev_testing.txt - LLM开发
• default_best_practices_prompt_llm_eval_observability.txt - LLM评估与可观ility
• default_best_practices_prompt_data_engineering.txt - 数据管道
• default_best_practices_prompt_data_lakes.txt - 数据湖
• default_best_practices_prompt_polars.txt - Polars/DuckDB
• default_best_practices_prompt_excel.txt - Excel自动化

专用领域（7个）

• default_best_practices_prompt_serverless_edge.txt - 边缘计算
• default_best_practices_prompt_kubernetes_ai.txt - Kubernetes AI
• default_best_practices_prompt_security.txt - 安全工程
• default_best_practices_prompt_hardware.txt - 硬件开发
• default_best_practices_prompt_unreal.txt - Unreal Engine
• default_best_practices_prompt_solana.txt - Solana区块链
• default_best_practices_prompt_cosmos.txt - Cosmos区块链
• default_best_practices_prompt_react_native.txt - React Native

变量替换

提示支持动态变量：

• {chunk_size} - 替换为配置的chunk size

提示示例：

每次处理大约{chunk_size}处改进...

🔄 工作原理

错误修复工作流

1. 问题生成：运行类型检查、代码 lint 和测试命令
2. 代理启动：在 tmux 窗格中启动 N 个代理
3. 任务分配：每个代理随机选择问题片段
4. 冲突预防：将已完成的问题标记为 [COMPLETED]
5. 进度跟踪：提交更改，并附带丰富的差异摘要，显示文件数量和变更统计信息

最佳实践工作流

1. 指南分发：将最佳实践指南复制到项目中
2. 进度文档：代理创建或更新跟踪文档
3. 系统化实施：逐步执行指南中的各项建议
4. 准确跟踪：保持诚实的完成百分比
5. 会话连续性：进度在多次运行之间持续保留

安全特性

1. 设置备份：在启动前自动备份 Claude 设置
   • 在项目目录下的 .claude_agent_farm_backups/ 中创建带时间戳的备份
   • 自动轮换保存最近 10 个备份
   • 强制限制总大小不超过 200MB，防止磁盘空间膨胀
   • 提供 --full-backup 标志以进行完整备份
   • 清理后报告备份存储状态
2. 设置恢复：检测到损坏时从备份恢复
   • 自动检测设置错误
   • 在代理启动时无缝恢复
3. 文件锁定：使用文件锁防止并发访问问题
   • 锁文件位于 ~/.claude/.agent_farm_launch.lock
   • 检测并清理 30 秒以上的过期锁
   • 防止同时启动多个 Claude 实例导致设置损坏
4. 权限管理：自动修复文件权限
   • 将 settings.json 的权限设置为 600
   • 将 .claude 目录的权限设置为 700
   • 确保正确的文件所有权
5. 原子操作：使用原子文件操作以确保安全
6. 紧急清理：优雅地处理意外退出
   • 清理 tmux 会话
   • 删除锁文件
   • 删除状态文件
7. 启动锁定：通过锁文件防止同时启动多个 Claude 实例
8. 自适应延迟：根据成功或失败智能调整启动延迟
   • 前一次启动成功时，延迟时间减半（健康状态下更快启动）
   • 前一次启动失败时，延迟时间加倍（保持安全性）
   • 最大延迟设为 60 秒，以防过度延迟
9. 代理数量限制：强制执行 max_agents 限制（默认：50）
10. 实例随机化：为每个代理添加唯一种子，以更好地分配工作

📊 监控仪表板

该 Python 脚本包含一个实时监控仪表板，显示：

• 代理状态：工作中、空闲、上下文不足、错误、已禁用
• 上下文使用情况：代理上下文窗口的使用百分比，并配有视觉警告
• 心跳间隔：自上次代理活动脉冲以来的时间（按颜色编码）
• 上次活动：代理上次执行操作的时间
• 上次错误：最近的错误消息（如果有）
• 会话统计：总重启次数、运行时间、活跃代理数
• 周期计数：已完成的工作周期数

上下文警告

每个 tmux 窗格的标题栏都会显示上下文警告：

• ⚠️ 严重（≤20%）：代理即将清除上下文
• ⚡ 低（≤30%）：上下文即将耗尽
• 健康水平则显示正常百分比

内置仪表板

监控仪表板运行在 tmux 控制器窗口中：

Claude 代理农场 - 14:32:15
┏━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ 代理    ┃ 状态     ┃ 周期 ┃ 上下文  ┃ 运行时间      ┃ 心跳┃ 错误 ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ 窗格 00  │ 工作中    │ 2      │ 75%      │ 0:05:23      │ 12s      │ 0      │
│ 窗格 01  │ 工作中    │ 2      │ 82%      │ 0:05:19      │ 8s       │ 0      │
│ 窗格 02  │ 空闲       │ 3      │ 45%      │ 0:05:15      │ 45s      │ 0      │
└──────────┴────────────┴────────┴──────────┴──────────────┴──────────┴────────┘

查看选项

# 使用查看脚本
./view_agents.sh

# 直接使用 tmux 命令
tmux attach -t claude_agents
tmux attach -t claude_agents:controller  # 仅仪表板

上下文重置宏

在任何 tmux 窗口中按下 Ctrl+R，即可向所有代理同时广播 /clear 命令。只需一次按键，即可释放所有代理的上下文，特别适用于多个代理上下文不足的情况。

代理状态

• 🟡 starting - 代理正在初始化
• 🟢 working - 正在积极处理任务
• 🔵 ready - 等待输入
• 🟡 idle - 已完成工作
• 🔴 error - 检测到问题
• ⚫ unknown - 状态不明

自动重启功能

当启用 --auto-restart 时：

• 通过心跳文件持续监控代理健康状况
• 对出现错误、进入空闲状态或心跳过期（超过 2 分钟）的代理进行重启
• 监控上下文使用百分比，并在低于阈值时清除上下文
• 自适应空闲超时会根据代理的工作模式调整
  • 跟踪所有代理的周期完成时间
  • 将超时设置为周期时间中位数的 3 倍（范围 30 秒至 600 秒）
  • 防止复杂任务中的误判
  • 加快简单任务的检测速度
• 实施指数退避策略以防止重启循环
  • 初始等待时间为 10 秒
  • 每次重启等待时间翻倍（最长 5 分钟）
• 记录每个代理的重启次数
• 达到最大错误次数后禁用代理

监控状态文件

系统会将监控状态写入项目目录下的 .claude_agent_farm_state.json 文件。该文件包含：

• 代理状态和健康指标
• 会话信息
• 运行统计信息

结构如下：

{
  "session": "claude_agents",
  "num_agents": 20,
  "agents": {
    "0": {
      "status": "working",
      "start_time": "2024-01-15T10:30:00",
      "last_activity": "2024-01-15T10:35:00",
      "last_restart": null,
      "cycles": 2,
      "last_context": 75,
      "errors": 0,
      "restart_count": 0
    }
  },
  "start_time": "2024-01-15T10:30:00",
  "timestamp": "2024-01-15T10:35:00"
}

外部工具可以读取此文件来监控农场的进展。

HTML 运行报告

每次运行结束时，系统会生成一份全面的 HTML 报告，内容包括：

• 运行摘要：持续时间、使用的代理数量、修复的问题数、提交的次数
• 代理性能：单个代理的统计信息，包括周期数、上下文使用情况、错误和重启次数
• 配置详情：本次运行使用的所有设置
• 可视化格式：丰富的 HTML 输出，带有语法高亮和深色主题

报告以 agent_farm_report_YYYYMMDD_HHMMSS.html 的形式保存在项目目录中。

特点：

• 单文件 HTML，内联样式（无外部依赖）
• 专业级深色主题，专为代码审查优化
• 可排序表格，带有颜色编码的状态指示器
• 完整的运行统计信息，可用于文档或拉取请求
• 在正常关闭时自动生成

💡 使用示例

快速测试运行

# 5 个代理，跳过 Git 操作
claude-code-agent-farm --path /project -n 5 --skip-regenerate --skip-commit

生产环境 Bug 修复

# 使用 Python 项目进行完整运行
claude-code-agent-farm \
  --path /python/project \
  --config configs/python_uv_config.json \
  --agents 15 \
  --auto-restart

最佳实践实施

# 系统性改进
claude-code-agent-farm \
  --path /nextjs/project \
  --config configs/nextjs_best_practices_config.json \
  --agents 10

增量提交

# 每 5 轮提交一次进度
claude-code-agent-farm \
  --path /project \
  --config configs/python_config.json \
  --agents 20 \
  --commit-every 5 \
  --auto-restart

自定义配置

# 覆盖配置设置
claude-code-agent-farm \
  --path /project \
  --config configs/base.json \
  --chunk-size 25 \
  --context-threshold 15 \
  --idle-timeout 120

无头运行

# 在 CI/CD 中无需监控的运行
claude-code-agent-farm \
  --path /project \
  --config configs/ci-config.json \
  --no-monitor \
  --auto-restart

专用技术栈

# Angular 开发
claude-code-agent-farm \
  --path /angular/project \
  --config configs/angular_config.json

# 区块链开发
claude-code-agent-farm \
  --path /solana/project \
  --config configs/solana_anchor_config.json

# 数据工程
claude-code-agent-farm \
  --path /data/project \
  --config configs/polars_duckdb_config.json

协作智能体模式

# 针对复杂改进的高级多智能体协作
claude-code-agent-farm \
  --path /project \
  --prompt-file prompts/cooperating_agents_improvement_prompt_for_python_fastapi_postgres.txt \
  --agents 20 \
  --auto-restart

🚨 故障排除

常见问题

智能体未启动

• 验证 cc 别名：alias | grep cc
• 手动测试 Claude Code：cc
• 检查 API 密钥配置
• 增加 --wait-after-cc 的等待时间
• 如果怀疑配置损坏，使用 --full-backup 标志

配置错误

• 验证 JSON 语法
• 确保所有路径正确
• 检查命令是否可用（mypy、ruff 等）
• 确认最佳实践指南存在

资源问题

• 每个智能体占用约 500MB 内存
• 如有必要，减少智能体数量
• 使用 htop 监控资源使用情况
• 检查日志存储的磁盘空间
• 遵守最大智能体数量限制（默认 50）

设置损坏

• 系统会自动备份设置
• 检测到错误时会从备份恢复
• 手动恢复：检查 ~/.claude/backups/
• 使用 --full-backup 进行全面备份

调试功能

• 状态文件：查看 .claude_agent_farm_state.json 以了解智能体状态
• 心跳文件：监控 .heartbeats/agent*.heartbeat 以跟踪活动
• 锁文件：在 ~/.claude/ 中查找 .agent_farm_launch.lock
• 备份目录：项目中的 .claude_agent_farm_backups/ 存放设置备份
• 预检：运行 claude-code-agent-farm doctor 诊断问题
• 紧急清理：Ctrl+C 触发优雅关闭
  • 第一次 Ctrl+C：优雅关闭并清理智能体
  • 第二次 Ctrl+C 在 3 秒内：强制终止 tmux 会话
  • 自动清理状态文件和锁文件
• 手动 tmux：tmux kill-session -t claude_agents 可强制清理

📁 项目结构

claude_code_agent_farm/
├── claude_code_agent_farm.py    # 主调度器
├── view_agents.sh               # tmux 查看工具
├── setup.sh                     # 自动化设置
├── pyproject.toml              # Python 项目配置
├── uv.lock                     # 锁定的依赖项
├── .envrc                      # direnv 配置
├── .gitignore                  # Git 忽略模式
├── configs/                     # 33 个配置文件
│   ├── nextjs_config.json      # Next.js Bug 修复
│   ├── python_config.json      # Python Bug 修复
│   ├── python_uv_config.json   # Python 使用 uv
│   ├── nextjs_best_practices_config.json
│   ├── angular_config.json     # Angular 开发
│   ├── flutter_config.json     # Flutter 移动应用
│   ├── rust_system_config.json # Rust 系统编程
│   ├── rust_webapps_config.json # Rust Web 应用
│   ├── rust_cli_config.json    # Rust CLI 工具
│   ├── go_webapps_config.json  # Go Web 开发
│   ├── java_enterprise_config.json # Java 企业级应用
│   ├── cpp_systems_config.json # C++ 系统
│   ├── php_config.json         # PHP 开发
│   ├── laravel_config.json     # Laravel 框架
│   ├── sveltekit2_config.json  # SvelteKit 框架
│   ├── remix_astro_config.json # Remix/Astro 框架
│   ├── bash_zsh_config.json    # Shell 脚本
│   ├── terraform_azure_config.json # Infrastructure as Code
│   ├── cloud_native_devops_config.json # DevOps 工具
│   ├── ansible_config.json     # Ansible 自动化
│   ├── vault_config.json       # HashiCorp Vault
│   ├── genai_llm_ops_config.json # AI/ML 运营
│   ├── data_engineering_config.json # 数据管道
│   ├── data_lakes_config.json  # Kafka/Snowflake/Spark
│   ├── polars_duckdb_config.json # 数据处理
│   ├── excel_automation_config.json # Excel 自动化
│   ├── serverless_edge_config.json # 边缘计算
│   ├── security_engineering_config.json # 安全
│   ├── hardware_dev_config.json # 硬件开发
│   ├── unreal_engine_config.json # 游戏开发
│   ├── solana_anchor_config.json # Solana 区块链
│   ├── cosmos_blockchain_config.json # Cosmos 区块链
│   └── sample.json             # 示例配置
├── prompts/                     # 37 个提示模板
│   ├── Bug 修复提示（4 个）
│   ├── 协作智能体提示（1 个）
│   ├── 通用最佳实践提示（2 个）
│   └── 技术栈特定的最佳实践提示（30 个）
├── best_practices_guides/       # 35 份最佳实践文档
│   ├── Web 开发（7 份指南）
│   ├── 系统与语言（7 份指南）
│   ├── DevOps 与基础设施（5 份指南）
│   ├── 数据与 AI（6 份指南）
│   └── 特殊领域（6 份指南）
├── tool_setup_scripts/          # 24 个开发环境设置脚本
│   ├── setup.sh                # 交互式菜单
│   ├── common_utils.sh         # 共享工具
│   ├── README.md              # 设置脚本说明
│   ├── Web 开发（4 个脚本）
│   ├── 系统与语言（3 个脚本）
│   ├── DevOps 与基础设施（3 个脚本）
│   └── 数据与 AI（3 个脚本）
└── __pycache__/                # Python 缓存（已忽略于 git）

🔧 高级主题

创建自定义工作流

1. 定义你的技术栈配置（参阅 34 个示例）
2. 创建合适的提示（遵循 37 个现有模式）
3. 添加最佳实践指南（可选，参阅 35 个示例）
4. 配置问题检测命令（类型检查、代码风格检查、测试）
5. 设置合适的分块大小（根据复杂度选择 20-75）
6. 先用少量智能体进行测试

扩展性考量

• 从小规模开始（5–10个代理），逐步扩展
• 默认最大支持50个代理（可通过max_agents配置）
• 当代理数量较多时，增加启动间隔时间
• 对于50个以上的代理，建议分批运行
• 使用--no-monitor进行无头模式运行
• 监控系统资源（内存、CPU）
• 根据性能调整分块大小

与CI/CD集成

#!/bin/bash
# 自动化代码改进脚本
claude-code-agent-farm \
  --path $PROJECT_PATH \
  --config configs/ci-config.json \
  --no-monitor \
  --auto-restart \
  --skip-commit \
  --agents 10

自定义Git工作流

在配置文件中设置自定义的Git分支和远程仓库：

{
  "git_branch": "feature/ai-improvements",
  "git_remote": "upstream",
  "skip_commit": false
}

性能调优

• 分块大小：根据剩余工作量自动调整
  • 按技术栈设定基础值：Python（50）、Next.js（50）、Rust（30）、Go（40）、Java（35）
  • 动态公式：max(10, total_lines / agents / 2)
  • 防止代理过早完成任务或处理琐碎工作
• 启动间隔时间：基于启动成功率自适应调整
  • 默认基线为10秒，防止配置损坏
  • 前一次启动成功时自动减半（最小值为基线）
  • 前一次启动失败时则加倍（最大60秒）
  • 系统健康时可实现更快的启动速度
• 上下文阈值：降低该值（15–20%）可更早清除上下文
• 空闲超时：根据任务复杂度调整
• 检查间隔：在响应速度和CPU占用之间取得平衡
• 心跳监控：检测卡住的代理（超过2分钟未发送心跳）
• 最大代理数：对于高性能系统可调高至50以上
• 清理后等待时间：默认15秒，确保Claude完全就绪
  • 若出现启动失败，可适当延长
• 增量提交：使用--commit-every N定期提交进度
  • 避免产生难以审查的大规模差异
  • 跟踪所有代理的最小循环次数以保证一致性

高级功能

可中断操作

• 所有长时间运行的操作均可通过Ctrl+C中断
• 优雅关闭会保留未完成的工作
• 在意外退出时执行紧急清理

智能错误检测

• 能够检测多种错误情况：
  • 配置损坏
  • 认证失败
  • 欢迎/设置界面
  • 命令未找到错误
  • 解析错误（TypeError、SyntaxError、JSONDecodeError）
  • 登录提示及API密钥问题
• 自动尝试恢复后再禁用代理
• 恢复过程中不影响其他正常工作的代理

提示中的变量替换

• {chunk_size}：替换为配置的分块大小
• 支持正则表达式模式，灵活定制提示模板

会话名称验证

• 仅允许字母、数字、连字符和下划线
• 防止因非法字符导致tmux报错

Shell提示检测

• 智能等待Shell提示后再发送命令
• --fast-start标志可跳过提示检测以加快启动
• 同时支持bash和zsh提示
• 多层稳健的就绪检查机制：
  1. 被动启发式方法，识别常见提示符号和当前目录名
  2. 主动探测回退机制，发送带有唯一标记的echo并等待响应——即使在极简或高度自定义的提示下也能生效
• 无缝兼容bash、zsh、fish及其他POSIX兼容Shell
• --fast-start标志可供高级用户选择完全跳过检测，以实现最快启动

用户确认

• 可中断的确认提示（Ctrl+C使用默认行为）
• 所有破坏性操作均采用安全默认值
• 清晰的用户交互信息提示

🤝 贡献说明

欢迎贡献！请按以下步骤操作：

1. Fork仓库
2. 创建特性分支
3. 如适用，添加测试
4. 更新文档
5. 提交拉取请求

添加新技术栈

1. 在configs/目录下创建配置文件（可参考34个示例）
2. 在prompts/目录下添加提示（提供37个示例）
3. 在best_practices_guides/目录下编写最佳实践指南（提供35个示例）
4. 在tool_setup_scripts/目录下添加设置脚本（提供15个示例）
5. 使用各类项目类型进行全面测试
6. 更新本README以记录新增内容

👨‍💻 作者

由Jeffrey Emanuel创作（jeffrey.emanuel@gmail.com）

📄 许可证

MIT许可证（附带OpenAI/Anthropic Rider条款）——详见LICENSE文件

⚠️ 重要提示

• 运行前务必备份代码
• 提交前仔细审查更改
• 初始运行时使用少量代理进行测试
• 首次运行时需监控行为以确保正常运作
• 大量代理运行时应监控资源使用情况
• 确保cc别名已正确配置
• 确保Git已配置正确的凭据
• 严格遵守代理数量限制（默认最大50个）
• Claude设置会自动备份和恢复
• 锁文件可防止并发启动和配置损坏
• 状态文件支持外部监控工具

🔍 其他资源

监控工具

• 可监控状态文件（.claude_agent_farm_state.json）以实现外部集成
• 心跳文件（.heartbeats/agent*.heartbeat）跟踪代理活动
• tmux窗格标题实时显示上下文警告
• tmux会话日志可用于调试代理问题
• Git提交历史可用于追踪改进

恢复选项

• 可从项目中的.claude_agent_farm_backups/手动恢复设置
• 清理锁文件：rm ~/.claude/.agent_farm_launch.lock
• 紧急会话清理：tmux kill-session -t claude_agents
• 查看之前会话的HTML运行报告以进行调试

性能优化

• 使用SSD以提升文件I/O性能
• 每个代理分配500MB内存
• 考虑API调用的网络带宽
• 运行期间使用htop监控CPU使用情况

---

祝您农耕愉快！🚜 愿您的代码整洁，代理高效产出。

📊 快速参考

技术栈支持汇总

类别	数量	示例
Web开发	8	Next.js、Angular、Flutter、Laravel、React Native
系统与语言	7	Python、Rust、Go、Java、C++
DevOps与基础设施	6	Terraform、Kubernetes、Ansible
数据与AI	8	GenAI/LLM、数据湖、PostgreSQL 17、Polars
特色领域	5	安全、硬件、区块链
总计	34

资源汇总

资源	数量
配置文件	37
提示模板	37
最佳实践指南	35
工具设置脚本	24

Claude Code Agent Farm 快速上手指南

Claude Code Agent Farm 是一个强大的编排框架，可并行运行多个 Claude Code (cc) 会话，通过自动化修复漏洞或系统性实施最佳实践来改进你的代码库。它支持多种技术栈，允许 AI 代理团队协作处理大规模代码优化任务。

🛠️ 环境准备

在开始之前，请确保你的系统满足以下要求：

系统要求

• 操作系统: Linux 或 macOS (Windows 需使用 WSL2)
• Python: 3.13+ (推荐使用 uv 管理)
• 终端复用器: tmux
• 版本控制: git
• 核心工具: Claude Code (需安装 claude 命令并配置 API Key)

前置依赖

根据你的项目类型，可能还需要安装特定工具（如 Next.js 项目需要 bun，Python 项目需要 mypy/ruff 等）。

注意：本项目依赖一个特殊的 cc 别名来启动带有必要权限的 Claude Code。 setup 脚本会自动配置此别名：

alias cc="ENABLE_BACKGROUND_TASKS=1 claude --dangerously-skip-permissions"

📦 安装步骤

1. 克隆仓库并运行设置脚本

git clone https://github.com/Dicklesworthstone/claude_code_agent_farm.git
cd claude_code_agent_farm
chmod +x setup.sh
./setup.sh

设置脚本将自动执行以下操作：

• 检查并安装缺失的前置依赖
• 创建 Python 3.13 虚拟环境
• 安装所有 Python 依赖
• 自动配置 cc 别名（检测并修复常见的引号错误）
• 设置 direnv 以实现环境自动激活
• 自动适配 bash 和 zsh shell

2. 验证安装

运行预飞行检查器以确保一切配置正确：

claude-code-agent-farm doctor --path /path/to/your/project

该命令会检查 Python 版本、必需工具（tmux, git, uv）、Claude Code 配置、API Keys 以及项目特定工具的可用性。

3. (可选) 启用 Shell 自动补全

为了更快的命令输入体验：

# 自动检测当前 shell 并安装补全
claude-code-agent-farm install-completion

# 或指定 shell 类型
claude-code-agent-farm install-completion --shell zsh

🚀 基本使用

场景一：自动化修复 Bug

让多个 Agent 并行处理类型检查和 Linter 报错。

Next.js 项目示例：

claude-code-agent-farm --path /path/to/nextjs-project --config configs/nextjs_config.json

Python 项目示例：

claude-code-agent-farm --path /path/to/python-project --config configs/python_config.json

场景二：系统性实施最佳实践

首先将最佳实践指南复制到项目中，然后运行专用配置。

# 1. 复制最佳实践指南 (以 Next.js 15 为例)
cp best_practices_guides/NEXTJS15_BEST_PRACTICES.md /path/to/your-project/best_practices_guides/

# 2. 运行最佳实践工作流
claude-code-agent-farm --path /path/to/your-project --config configs/nextjs_best_practices_config.json

💡 使用提示

• 监控面板：启动后，主监控面板将在 tmux 会话的控制器窗口中显示，而非你启动命令的终端。
• 查看 Agent 状态：你可以新开一个终端窗口，运行以下命令查看实时网格视图：

  ./view_agents.sh
  

• 停止运行：按 Ctrl+C 优雅关闭；若在 3 秒内连续按两次 Ctrl+C 则强制终止。
• 清空上下文：在所有 Agent 中广播 /clear 命令，只需在监控界面按 Ctrl+R。