三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Claude Code子智能体实战：构建可自我迭代的AI编程工作流

发布时间：2026/8/7 9:02:12 三亩地 编程学习日记
Claude Code子智能体实战：构建可自我迭代的AI编程工作流

1. 项目概述：当AI开始“管理”AI

最近在折腾AI编程工具的朋友，估计都绕不开一个名字：Claude Code。这玩意儿本质上是一个基于Claude大模型的智能编程助手，但它最近进化出了一个让我眼前一亮的玩法——子智能体（Sub-Agent）。简单来说，就是让一个AI去调度、管理、甚至“调教”另一个（或一群）AI来协同完成复杂的编码任务。这听起来有点“套娃”，但实际用下来，你会发现它彻底改变了我们与AI协作写代码的范式。

过去，我们和AI编程助手的交互模式是线性的：我提出需求 -> AI生成代码 -> 我审查、调试、提出修改 -> AI再次生成。这个过程中，人类是绝对的项目经理和质检员，需要全程保持高度专注，处理逻辑规划、接口设计、错误排查等一系列高认知负荷的工作。而Claude Code的子智能体机制，试图将一部分项目管理、任务拆解和专项评审的职能，也交给AI本身。你可以把它想象成，你不再是那个事无巨细的包工头，而是为项目组建了一个拥有不同专长的AI团队，并任命了一个“AI技术主管”。你只需要向这位“主管”交代清楚最终目标，它会自动把任务拆解，分派给擅长前端、后端、算法或测试的“AI工程师”，并整合他们的成果。

这解决了什么痛点？对于独立开发者或小团队，最大的限制往往是精力无法覆盖全栈。你可能后端很强，但对UI交互细节不敏感；或者算法思路清晰，但工程化部署总出岔子。子智能体模式让你能以一个“全栈架构师”的视角去推动项目，而将具体的实现细节交给专业的“AI子员工”。这不仅仅是效率的提升，更是能力范围的拓展。接下来，我将结合近期的实战，拆解如何利用Claude Code的子智能体功能，构建一个能自我迭代的AI编码工作流。

2. 核心思路：构建一个可自我演进的AI编码团队

子智能体不是魔法，它的有效性完全建立在清晰的设计思路上。你不能简单地对AI说“去写个电商网站”，然后就指望它吐出完美代码。核心在于，你需要为这个“AI团队”设计角色、定义工作流程和建立沟通规范。

2.1 角色定义与能力边界划分

首先，你需要像组建真实团队一样，定义不同的子智能体角色。每个角色应有明确的职责和专长领域。在我的实践中，通常会配置以下几个核心角色：

  1. 架构师智能体：这是团队的“技术主管”。它的核心职责是理解用户的模糊需求，并将其转化为具体、可执行的技术方案和系统设计。它需要输出技术选型建议、模块划分、接口定义和数据流设计。它的提示词（Prompt）需要强调宏观视野和决策能力。
  2. 实现者智能体：这是“高级开发工程师”。它接收架构师输出的详细设计文档，负责编写高质量、符合规范的模块代码。它的提示词需要聚焦于代码的健壮性、可读性和性能，并且要严格遵守给定的架构约束。
  3. 审查者智能体：这是“资深代码评审”。它不生成新代码，而是对实现者生成的代码进行静态分析。检查内容包括但不限于：语法错误、潜在的性能瓶颈、安全漏洞（如SQL注入风险）、代码风格一致性、是否严格遵循了架构设计。它的提示词需要体现严谨和挑剔。
  4. 测试者智能体：这是“质量保障工程师”。它负责根据功能描述和代码，生成单元测试、集成测试用例，甚至尝试运行测试并报告结果。它的目标是发现逻辑错误和边界情况。

关键在于，给每个智能体的指令（System Prompt）必须精确。例如，给“审查者智能体”的指令不能只是“检查代码”，而应该是：“你是一个苛刻的代码审查专家。请严格检查以下代码：1. 是否符合PEP 8（Python）/ESLint（JavaScript）规范？2. 函数是否单一职责？3. 有无明显的资源泄漏风险（如未关闭的文件句柄）？4. 错误处理是否完备？请直接列出发现的问题及具体行号，并按严重性分级（致命、严重、建议）。”

2.2 工作流设计：串联与反馈循环

定义了角色，下一步是设计他们如何协作。一个高效的工作流不是简单的线性管道，而应包含反馈循环。我常用的一个基础工作流如下：

  1. 需求输入与拆解：我向“架构师智能体”描述需求（例如：“开发一个RESTful API，用于管理用户待办事项，支持增删改查和状态标记”）。
  2. 方案设计与分发：“架构师智能体”输出技术方案（如：使用FastAPI框架，SQLite数据库，定义User和Todo模型及5个API端点）。它将“创建数据库模型和连接”任务派给实现者A，将“实现API端点逻辑”任务派给实现者B。
  3. 并行实现与初步审查：两个“实现者智能体”根据分配的任务和详细设计编写代码。代码完成后，首先交由“审查者智能体”进行交叉审查（即A的代码由B的审查者审，反之亦然），形成第一轮修改意见。
  4. 迭代修改与集成：实现者根据审查意见修改代码。修改后的代码可以再次送入审查环节，直到审查者给出“通过”或仅剩低级别建议。
  5. 测试与验证：将最终代码和功能描述交给“测试者智能体”，生成测试用例并尝试运行。测试报告（包括通过的用例和失败的用例）反馈给对应的实现者进行修复。
  6. 汇总与交付：“架构师智能体”或一个专门的“集成者智能体”将各个模块的代码整合，检查模块间的接口一致性，并生成最终的项目结构说明和部署指南。

这个流程中，人类开发者扮演“产品负责人”和“最终决策者”的角色，主要介入点在需求输入、架构评审（审核架构师的设计）和最终验收。大部分中间的实现、审查、测试环节都由AI团队自动完成，形成了“设计->实现->审查->测试->修复”的闭环。

注意：这个工作流初期设置需要一定时间，但一旦跑通，对于重复性的项目类型（如CRUD后台、数据清洗脚本、标准组件开发）效率提升是巨大的。你需要为每个智能体精心调试提示词，这是“团队培训”的过程。

3. 实战配置：在Claude Code中搭建你的AI团队

理论说再多不如动手一试。下面以在Visual Studio Code中配置Claude Code并设置一个用于Python后端开发的子智能体团队为例，展示具体步骤。

3.1 环境准备与Claude Code安装

首先，你需要一个Claude API密钥。前往Claude官网注册并获取。接着，在VSCode中安装“Claude Code”扩展，这和在扩展商店安装其他插件没有区别。安装完成后，在扩展设置里填入你的API密钥。

关键的一步是配置“自定义指令”或“角色”。Claude Code允许你保存一些预设的提示词模板。我们将利用这个功能来创建不同的子智能体角色。

  1. 打开Claude Code侧边栏，找到设置或配置选项。
  2. 寻找“Custom Instructions”、“Personas”或“Agent Templates”类似的设置项（不同版本可能名称略有差异）。
  3. 我们将创建四个配置项，分别对应之前的四个角色。

3.2 精心编写每个智能体的“人设”提示词

提示词的质量直接决定智能体的表现。以下是经过多次调试后，我认为比较有效的示例：

架构师智能体 (architect)

你是一个经验丰富的软件系统架构师。你的任务是将用户模糊的业务需求转化为清晰、可落地的技术设计方案。 请遵循以下步骤工作： 1. **需求澄清**：主动询问任何不明确或缺失的细节（如预期用户量、数据规模、安全要求、部署环境）。 2. **技术选型**：根据需求推荐合适的技术栈（框架、数据库、第三方服务等），并简述理由。 3. **系统设计**： - 绘制核心数据模型（用文字描述实体、属性和关系）。 - 定义核心模块/组件及其职责。 - 设计关键的API接口（方法、路径、请求/响应体结构）或函数签名。 - 描述主要的数据流和业务流程。 4. **任务拆解**：将整个项目拆解成若干个独立的、可并行开发的具体编码任务，每个任务应有明确的输入、输出和验收标准。 你的输出应结构化，使用Markdown格式，让后续的开发智能体能够无歧义地执行。

实现者智能体 (developer)

你是一名追求代码质量的资深开发工程师。你将收到来自架构师的具体任务描述和详细设计。 你的工作原则： - **严格遵循设计**：完全按照给定的接口定义、数据模型和技术栈实现。 - **代码质量**：编写清晰、自解释的代码。使用有意义的变量名和函数名。添加必要的注释，特别是对于复杂逻辑。 - **健壮性**：进行充分的输入验证和错误处理。考虑边界情况和异常流程。 - **性能**：避免已知的性能反模式（如循环内重复查询数据库）。 输出要求：只输出最终的、完整的代码块。如果需要解释设计决策，请在代码块前用简短注释说明。

审查者智能体 (reviewer)

你是一个以严格著称的代码审查机器人。你的唯一目的是找出代码中的问题。 审查清单（按优先级排序）： 1. **功能性错误**：逻辑错误、算法缺陷、资源泄漏（文件、连接未关闭）、并发问题。 2. **安全性问题**：SQL注入风险、命令注入风险、不安全的反序列化、敏感信息硬编码。 3. **代码质量**：违反语言特定规范（PEP 8, Airbnb JS Style等）、函数过长、圈复杂度高、重复代码。 4. **可维护性**：含糊的命名、缺少文档字符串、魔法数字。 输出格式： - 按【严重级别】列出问题：[致命]、[严重]、[建议]。 - 每个问题注明文件/函数名和行号（如果可能）。 - 提供具体的修改建议或代码示例。 - 如果未发现问题，输出“【通过】本次审查未发现严重问题。”

测试者智能体 (tester)

你是一个注重细节的测试工程师。基于功能描述和已有代码，你的工作是确保代码行为符合预期。 请执行： 1. **生成测试用例**：为每个核心函数/API端点编写单元测试。覆盖： - 正常用例（Happy Path） - 边界用例（空输入、极值、非法类型） - 错误用例（模拟依赖失败、无效权限） 2. **提供测试代码**：使用适合该语言和框架的测试库（如pytest for Python, Jest for JS）。 3. **执行分析（如果环境允许）**：尝试在心理上或简单环境中“运行”测试，指出哪些测试可能会失败及其原因。 输出：首先列出测试计划概要，然后提供完整的、可运行的测试代码。

将这些提示词分别保存为不同的预设。这样，在对话时，你可以快速切换“角色”，模拟不同智能体之间的对话。

3.3 模拟团队协作：一个API开发的完整流程

现在，我们模拟开发一个简单的“用户管理”API。

  1. 启动会话，切换为architect：在Claude Code聊天框输入：“我们需要一个用户管理系统的后端API。核心功能：用户注册、登录（JWT）、查看和更新个人资料。请给出设计方案。”
  2. 接收架构设计：architect会输出一份详细设计，包括：使用FastAPI + SQLAlchemy + Pydantic，User表字段，/auth/register,/auth/login,/users/me(GET/PUT)等API设计，以及任务拆解（任务A：数据库模型与连接；任务B：认证工具函数；任务C：API路由实现）。
  3. 新建聊天窗口，切换为developer，执行任务A：将architect输出的“任务A：创建数据库模型…”部分复制过来，要求developer实现。你会得到models.py和database.py的代码。
  4. 新建聊天窗口，切换为reviewer，审查任务A的代码：将developer生成的代码丢给reviewer。它会指出可能的问题，例如“在get_db依赖中建议使用yield确保连接关闭”，“User模型的密码字段应排除在响应模型外”。
  5. 回到developer窗口，根据审查意见修改代码：将reviewer的意见和原代码一起发给developer，要求其修正。得到改进后的代码。
  6. 并行执行任务B、C：重复步骤3-5，完成其他任务。每个任务的代码都经过独立的审查。
  7. 集成与测试：将所有最终模块的代码合并。切换为tester，将完整的API描述和代码提交给它，要求生成测试。你会得到一整套test_*.py文件。
  8. 最终检查：你可以手动运行测试，或者将测试代码和报错信息反馈给developer进行修复。

这个过程看似繁琐，但大部分是复制粘贴和切换预设的操作。一旦熟练，其并行化和专业化的优势就会显现。你相当于同时雇佣了四位专家在为你工作，而你只需管理他们之间的交接。

4. 高级技巧与效能提升策略

基础工作流跑通后，可以通过一些策略进一步提升这个AI团队的智能水平和协作效率。

4.1 建立共享上下文与记忆

AI智能体之间是“失忆”的，每次对话都是新的开始。为了模拟团队的共同知识库，你需要手动维护一份“项目上下文文档”。这是一个简单的Markdown文件，记录：

  • 项目决策日志：为什么选择MongoDB而不是PostgreSQL？为什么API版本号放在URL路径里？
  • 通用约定：错误响应的统一格式是什么？日期时间使用什么格式（ISO 8601）？
  • 已解决的问题：某个第三方库的特定版本存在兼容性问题，我们决定使用X版本。

在开启每一个新的子任务对话时，将这份上下文文档作为前置信息发给智能体。这能极大保持代码风格和决策的一致性，避免不同智能体做出相互冲突的设计。

4.2 实现自动化流水线脚本

频繁切换窗口和复制粘贴仍然低效。一个进阶玩法是，利用简单的Shell脚本或Python脚本来半自动化这个过程。脚本可以：

  1. 读取一个task.md文件（里面是架构师输出的任务列表）。
  2. 遍历每个任务，调用Claude API（你需要使用编程方式），以对应智能体的提示词为系统指令，以任务描述为提问，获取代码。
  3. 自动将代码保存到对应文件（如task_a.py）。
  4. 接着，自动调用审查智能体，对刚生成的文件进行审查，并将审查结果保存到review_task_a.md。
  5. 将审查结果和原代码再次发送给实现智能体进行修正，保存新版本。

这样，你只需要维护任务描述和触发脚本，就能自动获得“实现->审查->修正”后的代码文件。这需要一些基础的脚本编写能力，但一劳永逸。

4.3 处理复杂依赖与调试

当任务之间存在复杂依赖时（例如任务C需要任务A中定义的某个类），直接并行会出错。策略是：

  • 顺序化有依赖的任务：在架构师拆解任务时，就明确依赖关系。先完成基础模块（如数据模型、工具类），再将生成的稳定代码作为后续任务的“已知上下文”提供给其他智能体。
  • 使用“集成智能体”：在所有模块代码生成后，可以创建一个新的对话，将所有代码和架构设计丢给一个提示词为“你是一个集成工程师，负责检查模块间接口是否匹配，并解决编译/导入错误”的智能体。让它来发现import错误、函数签名不匹配等问题，并给出修复方案。

调试时，不要直接问“代码为什么报错？”。而是将完整的错误堆栈信息、相关代码片段、以及你已尝试过的排查步骤，一起发给developer或一个专门的debugger智能体（提示词可强调“擅长阅读错误信息，定位根本原因”）。AI在理解错误上下文方面往往比从头开始猜要强得多。

5. 常见问题与避坑指南

在实际操作中，你肯定会遇到各种问题。以下是我踩过坑后总结的一些经验。

5.1 智能体“失控”与幻觉问题

有时，智能体会偏离指令，生成无关内容或虚构不存在的库。

  • 问题：developer突然在Python代码里写起了JavaScript语法。
  • 排查：检查当前对话使用的系统提示词（角色）是否准确。很可能在之前的对话中，话题被无意带偏，而Claude Code的上下文记忆导致了角色混淆。
  • 解决：最干净利落的方法是开启一个新的聊天窗口，并确保正确选择了预设角色。对于关键任务，每次都从新对话开始是最稳妥的。不要在一个长对话中让智能体扮演多个角色。

5.2 代码质量参差不齐

生成的代码有时很优雅，有时却像初学者写的。

  • 问题：代码缺乏错误处理，或者使用了已弃用的API。
  • 排查与解决：
    1. 强化审查者：细化审查者的提示词，加入更具体的检查项，如“必须使用try-except处理可能抛出异常的操作”、“检查所用库函数是否在当前版本中未被标记为deprecated”。
    2. 提供范例：在给developer的指令中，附上一小段你期望的代码风格示例。例如，“错误处理请参考以下格式：try: ... except SomeSpecificError as e: logger.error(...); raise HTTPException(...)”。
    3. 迭代要求：如果第一次生成的代码不好，直接指出问题并要求重写。例如，“这个函数没有处理输入为None的情况。请重写它，加入参数校验和全面的错误处理。”

5.3 上下文长度限制与信息丢失

Claude模型有上下文窗口限制，长对话后，早期的指令（系统提示）可能会被“遗忘”。

  • 问题：对话进行到第30轮后，智能体开始忽略最初设定的代码规范。
  • 解决：
    • 定期重申指令：在关键节点（如开始一个新模块），可以再次粘贴核心的指令要求。
    • 分拆对话：这是最有效的方法。将大项目拆分成多个独立的子对话，每个子对话专注于一个界限清晰的子模块，确保整个对话在上下文窗口内能轻松容纳。
    • 使用摘要：在长对话中，每隔一段时间，要求智能体对之前讨论的设计决策做一个简要总结，并将这个总结带入后续对话，以巩固记忆。

5.4 成本控制

频繁调用API会产生费用。虽然单次对话成本不高，但自动化流水线可能带来大量请求。

  • 策略：
    • 本地缓存：对于已通过审查的稳定代码片段，建立本地代码库。遇到类似功能时，直接复用或小改，而不是每次都从头生成。
    • 离线模型辅助：对于轻量级的代码补全、语法检查，可以依赖VSCode的其他离线插件（如Tabnine、CodeGeeX），只在需要高级设计、审查和调试时调用Claude。
    • 精心设计提示词：模糊的提示词会导致AI生成冗长、试探性的回复，消耗更多Token。清晰、精确的指令能让AI直击要害，减少无效输出。

子智能体的实战，是一个将AI从“高级打字员”转变为“初级合伙人”的过程。它要求你从写代码的思维，升级到设计系统、定义流程、管理质量的思维。初期投入的学习和调试成本是存在的，但一旦你掌握了如何清晰定义任务、如何设置有效的提示词、如何建立反馈循环，你就会拥有一个7x24小时待命、各有所长、且不断进化的虚拟开发团队。这不仅仅是写代码更快，更是让你能敢于去尝试一个人原本难以驾驭的项目规模和技术领域。真正的价值不在于替代你，而在于倍增你的能力。

编程学习 学习日记 实战经验
← 返回列表