1. 项目概述与核心价值最近在折腾AI编程助手时发现了一个挺有意思的项目叫mylee04/claude-code-subagents。简单来说这是一个基于Claude API构建的“多智能体”代码生成与协作框架。它不是让一个AI大模型单打独斗去完成整个复杂的编程任务而是把任务拆解分配给多个各司其职的“子智能体”来协同完成。这就像是一个小型开发团队里面有架构师、前端工程师、后端工程师、测试工程师大家各管一摊但又紧密配合。这个项目的核心价值在于它试图解决当前大语言模型在代码生成任务中普遍存在的几个痛点。比如面对一个稍复杂的项目需求单个模型生成的代码往往结构松散、逻辑不连贯或者只关注局部而忽略了整体架构。claude-code-subagents通过引入“规划-执行-评审”的协作流程让多个智能体分别负责需求分析、架构设计、模块实现、代码审查等环节从而显著提升了生成代码的整体性、可维护性和正确性。对于需要快速原型开发、自动化脚本编写或者辅助代码重构的开发者来说这无疑是一个极具潜力的生产力工具。2. 核心架构与工作流拆解2.1 多智能体协作范式claude-code-subagents的核心思想是“分而治之”与“协同工作”。它通常包含以下几种关键角色智能体规划者/架构师负责理解用户需求将其拆解为具体的、可执行的任务清单并规划项目的整体结构和模块划分。执行者/开发者根据规划者分配的具体任务负责编写实现代码。根据项目复杂度可以有多个执行者分别负责不同模块或不同技术栈如前端、后端、数据库。审查者/测试员对执行者生成的代码进行审查检查其正确性、规范性、安全性并提出修改建议。有些实现中审查者还可能负责生成单元测试。协调者/管理者可选负责协调各个智能体之间的通信管理任务队列汇总最终结果。这种架构模拟了真实的软件工程流程使得AI生成的代码不再是“一锤子买卖”而是经过了一个初步的、自动化的“开发周期”其产出质量自然更有保障。2.2 典型工作流程解析一个完整的工作流通常遵循以下步骤我们可以将其类比为一个微型敏捷开发冲刺第一步需求分析与任务规划用户输入一个自然语言描述的需求例如“创建一个简单的待办事项Web应用支持增删改查使用React前端和Flask后端数据存到SQLite”。规划者智能体被激活。它调用Claude API分析这段描述识别出关键组件前端UIReact、后端APIFlask、数据库SQLite、核心功能CRUD。接着规划者会生成一份结构化的开发计划可能包括任务1初始化项目结构创建frontend/和backend/目录。任务2实现后端Flask应用定义/api/todos的GET、POST、PUT、DELETE接口。任务3创建SQLite数据库和todos表并编写数据访问层代码。任务4实现前端React组件如TodoList, TodoItem并调用后端API。任务5编写简单的样式CSS。任务6生成基本的README和运行说明。这个计划会被分解成一个个独立的、描述清晰的任务卡片放入任务队列。第二步任务分发与代码执行协调者或主循环从任务队列中取出一个任务例如“任务2实现后端Flask应用...”。该任务被分配给一个执行者智能体。执行者同样调用Claude API但这次获得了更具体的上下文“你是一名后端工程师请基于以下规划使用Flask实现待办事项的RESTful API...”同时附上相关技术栈要求和之前生成的任何相关代码如项目结构。执行者生成代码例如app.py文件包含Flask应用实例、路由定义和初步的业务逻辑。第三步代码审查与迭代优化执行者生成的代码不会直接成为最终产物而是提交给审查者智能体。审查者分析这段代码检查其是否满足要求、有无语法错误、是否符合PEP 8Python或ESLintJavaScript等规范、是否存在明显的安全漏洞如SQL注入风险。审查者生成审查意见例如“建议使用Flask-SQLAlchemy来更好地管理数据库会话”、“/api/todos/id的PUT接口应验证传入的JSON数据完整性”、“添加适当的错误处理try-catch”。根据项目配置这些意见可能直接返回给执行者进行修改或者由协调者决定是否采纳并创建新的修正任务。第四步集成与汇总所有通过审查或经过修正的代码模块由协调者智能体进行整合。它需要确保不同模块之间的接口兼容例如前端API调用URL与后端路由是否匹配导入的模块是否存在。最终生成完整的项目文件树、一份汇总的README以及可能的Dockerfile或运行脚本。注意上述流程是一个理想化的模型。实际项目中智能体间的交互逻辑、错误处理如某个智能体生成严重跑偏的代码怎么办、以及如何避免在循环审查中陷入死胡同都是设计上的挑战。mylee04/claude-code-subagents的具体实现会定义这些交互的规则和终止条件。3. 关键技术实现与配置要点3.1 智能体的构建与提示工程每个子智能体的核心都是一个精心设计的提示词模板。这是项目成败的关键。一个糟糕的提示词会导致智能体“听不懂任务”或“自由发挥过度”。规划者提示词重点在于结构化输出和能力限定。你是一个经验丰富的软件架构师。请将以下用户需求分解为具体的、可顺序执行的开发任务。 需求{user_input} 请以JSON格式输出任务列表每个任务包含 - id: 任务唯一标识 - description: 清晰的任务描述 - agent: 建议执行此任务的智能体类型 (如 “backend_engineer”, “frontend_engineer”, “devops”) - dependencies: 此任务依赖的其他任务id列表 确保任务分解逻辑合理覆盖从环境搭建到测试的完整闭环。这里强制要求JSON输出是为了便于程序自动化解析。同时通过“agent”字段实现了初步的任务路由。执行者提示词重点在于上下文提供和输出约束。你是一个专业的{agent_type}。你的任务是{task_description}。 项目当前上下文 - 技术栈{tech_stack} - 已有文件结构{existing_files} - 相关代码片段如有{relevant_code} 请只生成实现所要求功能所必需的代码。如果需要创建新文件请以注释“// FILE: path/to/file.py”开头然后编写该文件完整内容。如果修改现有文件请明确指出修改位置和内容。 确保代码简洁、高效、符合最佳实践。提供充足的上下文能极大减少智能体的臆测。约束输出格式如用特定注释标明文件方便后续自动化文件系统操作。审查者提示词重点在于多维度检查清单。你是一个严谨的代码审查员。请审查以下代码 代码块 审查重点 1. **功能性**代码是否准确完成了任务描述的要求 2. **正确性**有无语法错误、逻辑错误或运行时错误 3. **安全性**有无潜在的安全风险如注入、敏感信息硬编码 4. **可维护性**代码是否清晰、有注释、符合编码规范 5. **性能**有无明显的性能瓶颈 请按点列出发现的问题并为每个问题提供具体的修改建议。如果代码良好请输出“APPROVED”。将审查标准明确列出引导审查者进行系统性检查而不是泛泛而谈。3.2 状态管理与会话控制多个智能体协作意味着需要管理复杂的会话状态和上下文。会话隔离每个子任务都应该在一个独立的会话中与Claude API交互避免不同任务的上下文相互污染。这通常通过为每个任务创建新的API调用实现。上下文传递关键是如何把“规划”产生的信息以及之前“执行”产生的代码有效地传递给后续的智能体。常见的做法是维护一个项目上下文字典或知识图谱包含用户原始需求生成的项目结构树已创建文件的内容索引或关键函数签名任务之间的依赖关系图轮次控制与终止必须设置最大迭代轮次防止在“审查-修改”循环中陷入无限循环。例如当审查者连续三次给出“APPROVED”或者达到最大修改次数如5次时无论是否完美都终止当前任务进入下一个。有时引入一个“仲裁者”智能体来判断审查意见是否合理、是否需要采纳也是必要的。3.3 工程化与工具集成要让这个框架真正可用还需要一系列工程化考量文件系统操作智能体输出的可能是代码字符串框架需要能解析这些字符串并根据指示创建、读取、修改实际的文件。这需要稳健的文件路径处理和内容合并逻辑。依赖与包管理生成的代码往往依赖第三方库。高级的实现中规划者或某个专门的“工程智能体”需要能识别这些依赖并自动生成requirements.txt或package.json文件。错误处理与回退API调用可能失败智能体可能生成无法解析的垃圾输出。框架必须有相应的错误处理机制比如记录日志、重试、或者跳过当前任务并标记为失败。配置化通过配置文件如YAML来定义智能体的类型、各自的提示词模板、Claude模型版本如claude-3-opus-20240229、温度参数等使得框架易于调整和扩展。4. 实战从零搭建一个简易子智能体系统我们不用直接克隆mylee04/claude-code-subagents而是基于其理念用Python从头实现一个最简化的版本这能帮助你彻底理解其内部机理。4.1 环境准备与依赖安装首先确保你有一个可用的Claude API密钥从官方平台获取。我们使用anthropic官方Python SDK。# 创建项目目录并初始化虚拟环境 mkdir my_code_agents cd my_code_agents python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装核心依赖 pip install anthropic python-dotenv创建一个.env文件存放你的API密钥ANTHROPIC_API_KEYyour_api_key_here4.2 实现核心智能体基类我们创建一个agent.py文件定义一个所有智能体的基类封装与Claude API的通信。# agent.py import os from typing import List, Dict, Any from anthropic import Anthropic from dotenv import load_dotenv load_dotenv() class BaseAgent: def __init__(self, name: str, role_description: str, model: str claude-3-haiku-20240307): self.name name self.role_description role_description self.model model self.client Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) self.conversation_history: List[Dict[str, str]] [] def _build_system_prompt(self) - str: 构建系统提示词定义智能体角色。 return f你是一个AI助手扮演{self.name}的角色。 你的角色描述是{self.role_description} 请严格遵循你的角色设定来思考和回答问题。 def invoke(self, user_prompt: str, max_tokens: int 2000) - str: 调用Claude API并维护简单的会话历史。 system_prompt self._build_system_prompt() messages [{role: user, content: user_prompt}] try: response self.client.messages.create( modelself.model, max_tokensmax_tokens, systemsystem_prompt, messagesmessages ) result response.content[0].text # 可选保存历史用于需要多轮对话的复杂任务 self.conversation_history.append({role: user, content: user_prompt}) self.conversation_history.append({role: assistant, content: result}) return result except Exception as e: print(fAgent {self.name} 调用API失败: {e}) return fERROR: {e}4.3 实现规划者、执行者与审查者接下来我们创建具体的智能体类继承自BaseAgent并覆盖_build_system_prompt方法提供更具体的角色指令。# specialized_agents.py from agent import BaseAgent class PlannerAgent(BaseAgent): def __init__(self): super().__init__( name项目架构师, role_description你将用户需求分解为具体、可执行的开发任务清单。输出必须是结构化的JSON格式。 ) def _build_system_prompt(self) - str: # 更详细、约束性更强的系统提示词 base_prompt super()._build_system_prompt() structured_instruction 你的输出必须是纯JSON格式能被Python的json.loads直接解析。 JSON结构必须如下 { tasks: [ { id: 1, description: 任务描述, agent_type: backend|frontend|database|devops|general, dependencies: [] // 依赖的任务id列表 } ] } 请确保任务分解符合软件开发逻辑前后顺序合理。 return base_prompt structured_instruction class DeveloperAgent(BaseAgent): def __init__(self, specialty: str general): agent_type_map { backend: 后端工程师擅长Python/Flask/Django/Node.js, frontend: 前端工程师擅长React/Vue/HTML/CSS, database: 数据库工程师擅长SQL/SQLAlchemy, devops: DevOps工程师擅长Docker/部署, general: 全栈工程师 } role agent_type_map.get(specialty, 全栈工程师) super().__init__(namef{role}, role_descriptionf你是一名{role}负责编写高质量、可运行的代码。) class ReviewerAgent(BaseAgent): def __init__(self): super().__init__( name代码审查员, role_description你负责审查代码质量发现问题并提供具体修改建议。 ) def _build_system_prompt(self) - str: base_prompt super()._build_system_prompt() review_checklist 请从以下维度审查代码 1. 功能正确性是否满足需求 2. 代码规范是否符合语言惯例如PEP 8, ESLint 3. 错误处理是否有必要的异常捕获 4. 安全性有无硬编码密码、SQL注入等风险 5. 性能有无明显低效操作 请以清晰列表形式输出问题并为每个问题提供修改建议。如果代码没有问题请输出“**审查通过**”。 return base_prompt review_checklist4.4 实现协调者与主工作流现在我们创建一个orchestrator.py来串联整个流程。这是最核心的部分。# orchestrator.py import json import os import re from typing import Dict, List, Any from specialized_agents import PlannerAgent, DeveloperAgent, ReviewerAgent class CodeGenOrchestrator: def __init__(self): self.planner PlannerAgent() self.reviewer ReviewerAgent() # 可以根据任务类型动态创建不同的开发者智能体 self.developer_pool { backend: DeveloperAgent(backend), frontend: DeveloperAgent(frontend), general: DeveloperAgent(general) } self.project_context { user_request: , tasks: [], generated_files: {} # 文件名: 内容 } def parse_plan(self, plan_output: str) - List[Dict]: 解析规划者输出的JSON计划。 try: # 尝试从输出中提取JSON部分Claude有时会在JSON外加说明 json_match re.search(r\{.*\}, plan_output, re.DOTALL) if json_match: plan_str json_match.group() else: plan_str plan_output plan_data json.loads(plan_str) return plan_data.get(tasks, []) except json.JSONDecodeError as e: print(f解析任务计划失败: {e}) print(f原始输出:\n{plan_output}) return [] def execute_task(self, task: Dict, context: str) - str: 执行单个任务生成代码。 agent_type task.get(agent_type, general) developer self.developer_pool.get(agent_type, self.developer_pool[general]) prompt f 请完成以下开发任务 任务描述{task[description]} 项目当前上下文 {context} 请生成实现该任务所需的代码。 如果是创建新文件请在代码第一行用注释标明文件路径例如# FILE: app.py 请确保代码完整、可运行。 return developer.invoke(prompt) def review_code(self, task_desc: str, code: str) - str: 审查生成的代码。 prompt f 请审查以下代码该代码旨在完成此任务{task_desc} 代码 python {code} return self.reviewer.invoke(prompt) def extract_file_from_code(self, code: str) - Dict[str, str]: 从智能体输出中解析出文件名和内容。 files {} # 简单实现查找以 # FILE: 或 // FILE: 开头的行 lines code.split(\n) current_file None content_lines [] for line in lines: file_match re.match(r^\s*[#/]\s*FILE:\s*(.), line) if file_match: if current_file and content_lines: files[current_file] \n.join(content_lines).strip() current_file file_match.group(1).strip() content_lines [] elif current_file is not None: content_lines.append(line) # 处理最后一个文件 if current_file and content_lines: files[current_file] \n.join(content_lines).strip() # 如果没找到FILE标记则把整个输出当作一个无名文件不推荐 if not files and code.strip(): files[generated_code.py] code.strip() return files def run(self, user_request: str, output_dir: str ./generated_project): 主运行流程。 self.project_context[user_request] user_request print(f开始处理需求: {user_request}) # 步骤1: 规划 print(步骤1: 规划任务...) plan_raw self.planner.invoke(user_request) tasks self.parse_plan(plan_raw) print(f规划生成 {len(tasks)} 个任务。) for i, t in enumerate(tasks): print(f [{t[id]}] {t[agent_type]}: {t[description]}) # 步骤2 3: 循环执行与审查 os.makedirs(output_dir, exist_okTrue) completed_tasks [] for task in tasks: task_id task[id] print(f\n--- 处理任务 {task_id}: {task[description]} ---) # 检查依赖是否满足 deps task.get(dependencies, []) if not all(dep in completed_tasks for dep in deps): print(f 任务 {task_id} 的依赖 {deps} 未全部完成跳过。) continue # 构建当前上下文信息 context_str f用户需求: {user_request}\n已生成文件列表: {list(self.project_context[generated_files].keys())} # 执行任务 code_output self.execute_task(task, context_str) print(f 生成代码长度: {len(code_output)} 字符) # 审查代码 review_result self.review_code(task[description], code_output) print(f 审查结果: {review_result[:100]}...) # 打印前100字符 # 简单判断如果审查结果包含“通过”则认为审查通过 if 审查通过 in review_result or APPROVED in review_result.upper(): # 解析并保存文件 new_files self.extract_file_from_code(code_output) for file_path, content in new_files.items(): full_path os.path.join(output_dir, file_path) os.makedirs(os.path.dirname(full_path), exist_okTrue) with open(full_path, w, encodingutf-8) as f: f.write(content) self.project_context[generated_files][file_path] content print(f 已创建文件: {file_path}) completed_tasks.append(task_id) print(f 任务 {task_id} 完成并保存。) else: print(f 任务 {task_id} 未通过审查跳过保存。审查意见:\n{review_result}) # 在实际项目中这里可以加入重试逻辑根据审查意见修改代码。 print(f\n流程结束。在 {output_dir} 目录下生成了 {len(self.project_context[generated_files])} 个文件。) # 主程序入口 if __name__ __main__: orchestrator CodeGenOrchestrator() # 示例请求 request 创建一个Python脚本读取当前目录下的data.csv文件计算‘price’列的平均值并将结果输出到result.txt文件中。 orchestrator.run(request, output_dir./demo_output)4.5 运行与效果评估运行python orchestrator.py。你会看到控制台打印出规划、执行、审查的整个过程。最终在./demo_output目录下你应该会找到一个或多个Python脚本文件。实测心得与调优模型选择规划者 (PlannerAgent) 需要较强的逻辑分解能力建议使用能力更强的模型如claude-3-opus。执行者 (DeveloperAgent) 对代码生成能力要求高claude-3-sonnet或claude-3-haiku是性价比之选。审查者 (ReviewerAgent) 需要细致和严谨claude-3-sonnet表现不错。提示词迭代第一次运行效果往往不理想。你需要像调试程序一样调试提示词。观察每个智能体的输出如果它“跑偏”了就在系统提示词里增加更明确的约束或者提供更具体的例子Few-shot Learning。上下文管理我们这个简易版本只传递了文件名列表。在复杂项目中需要传递更丰富的上下文比如关键函数签名、数据结构定义甚至部分已生成代码的摘要以避免智能体生成冲突的代码。错误处理生产环境中需要对API调用失败、JSON解析失败、文件写入冲突等情况做更完善的异常处理和重试机制。5. 常见问题与进阶优化方向5.1 典型问题与排查问题现象可能原因排查与解决思路规划者输出非JSON格式提示词约束力不足或模型“自由发挥”。1. 在系统提示词中更严厉地强调“必须输出纯JSON”。2. 使用结构化输出功能如果API支持。3. 在代码中增加后处理尝试用正则表达式从文本中提取JSON块。执行者生成的代码无法运行缺少关键依赖、逻辑错误、或上下文不足。1. 审查者应重点检查代码的可运行性。2. 为执行者提供更详细的“技术栈约束”上下文。3. 实现一个“验证者”智能体尝试在沙箱环境中导入/运行生成的代码片段。审查者过于严苛或宽松审查标准不明确或与项目实际不符。1. 细化审查清单使其与项目使用的编码规范如Google Style对齐。2. 引入“审查严格度”参数通过提示词调整。3. 对于次要的格式问题可以设置自动格式化工具如black, prettier处理不让审查者纠结于此。智能体间循环修改审查者提出修改意见执行者修改后审查者又提出新问题陷入死循环。1. 设置最大迭代次数如3次。2. 引入仲裁逻辑如果连续两次修改都是风格类小问题而非功能错误则强制通过。3. 让审查者在提出意见时区分“阻塞性问题”和“建议性优化”。生成代码风格不一致不同执行者或同一执行者不同次调用代码风格迥异。1. 在所有执行者的系统提示词中统一编码风格要求如“使用f-string而非%格式化”“使用类型注解”。2. 在项目最后增加一个“代码格式化”阶段用工具统一处理。5.2 性能与成本考量使用多个Claude API调用成本是首要考虑因素。成本控制模型选型对创造性要求不高的任务如根据模板生成代码使用更便宜的haiku模型。上下文精简传递给智能体的上下文要精炼只包含必要信息避免冗长的历史对话这能显著减少Token消耗。缓存机制对于相同的输入提示词可以缓存输出结果避免重复计算。性能优化并行执行对于没有依赖关系的任务可以让多个执行者智能体并行调用API缩短整体耗时。异步调用使用异步IO来发起API请求避免同步等待。5.3 扩展与进阶玩法基础框架搭建好后有很多可以扩展的方向集成外部工具让智能体不仅能写代码还能调用命令行、操作数据库、调用第三方API。例如执行者生成数据库迁移脚本后一个“运维智能体”可以实际执行alembic upgrade head。引入记忆与学习为智能体增加长期记忆记录项目中的设计决策、遇到的坑和解决方案。当下次遇到类似任务时可以直接复用提升效率和质量。人类在环在关键节点如架构规划评审、重大代码合并前引入人工确认。可以设置一个“等待人工审核”的状态只有人工批准后流程才继续。领域定制化针对特定领域如Web开发、数据分析、游戏脚本训练专属的提示词模板甚至结合微调Fine-tuning让智能体成为该领域的专家。可视化与监控开发一个Dashboard实时展示任务执行状态、每个智能体的输入输出、Token消耗、成功率等指标方便调试和优化。这个项目最吸引人的地方不在于它能生成完美无缺的代码——目前这还不现实。它的价值在于提供了一种结构化、自动化地利用大模型解决复杂问题的方法论。通过将大模型“分包”给多个角色化的智能体并设计它们之间的协作规则我们能够引导AI产出更可靠、更可控的结果。这不仅是AI编程助手的一个进化方向也为其他需要多步骤推理和协作的AI应用提供了宝贵的思路。