Claude Code AI 辅助开发实践：对话流、Plan 模式与子代理协作

AI（人工智能）编程工具已经不只是“帮忙补全几行代码”的助手。用得好，它可以参与需求拆解、技术方案设计、代码生成、单元测试、代码审查和文档维护；用得不好，它也可能生成一堆看似完整、实际难以合入的代码。

Claude Code 的关键价值不在于替开发者写完所有代码，而在于把开发过程中的一部分认知负担转移出去：重复性的代码让 AI 处理，复杂判断仍由人控制。要做到这一点，不能只会输入一句“帮我实现某某功能”，而要把 AI 当成一个需要明确上下文、边界、约束和反馈节奏的协作者。

开发中的三个典型问题

日常开发里的低效率，很多并不是编码速度慢造成的，而是出现在需求理解、上下文切换和协作传递上。

更合理的方式是把 Claude Code 放进开发流程，而不是把它当成一个“代码生成按钮”。

flowchart LR
    A[需求输入] --> B[结构化需求]
    B --> C[技术方案]
    C --> D[模块拆分]
    D --> E[代码实现]
    E --> F[测试与审查]
    F --> G[合入与文档更新]

    B -.人工确认.-> C
    C -.人工确认.-> D
    F -.问题反馈.-> E

这里的重点是“结构化”和“确认节点”。AI 可以快速产出内容，但开发者必须在关键节点做方向判断。

Claude Code 的核心能力应该怎么用

Claude Code 常见的几个能力包括对话流设计、Plan 模式、系统提示词、SKILL、MCP（Model Context Protocol，模型上下文协议）和 SubAgent（子代理）。这些能力不是孤立功能，而是可以组合成一套 AI 辅助开发流程。

对话流设计：让 AI 在正确边界内思考

很多 AI 生成代码质量不稳定，并不是模型能力不足，而是输入太模糊。

比如一句：

帮我实现一个商家信息查询接口。

AI 可能只生成基础的 Controller、Service、Mapper，却不知道这些隐含要求：

• 查询结果需要按当前用户的数据权限过滤；
• 手机号、身份证号等敏感字段需要脱敏；
• 接口需要使用项目已有的权限注解；
• 返回格式必须符合统一响应模型；
• 查询条件要记录操作日志；
• 分页大小需要有限制。

对话流设计的目的，就是把这些隐含条件显式写出来，减少 AI 自由发挥的空间。

一个可复用的任务输入模板可以这样写：

# 任务目标
实现商家信息查询接口，支持按商家 ID、商家名称、商家状态查询。

# 功能边界
要做：
- 分页查询商家信息
- 按当前用户数据权限过滤结果
- 对手机号、身份证号脱敏
- 记录查询操作日志

不做：
- 不实现商家新增、编辑、删除
- 不修改现有商家主表结构

# 必须遵守
- Controller 返回 Result<T>
- 权限校验使用 @Permission
- 参数校验使用 @Valid 和 ValidatorUtil
- DTO 转换使用 ConvertUtil
- 数据访问使用 MyBatis-Plus

# 交付物
- Controller
- Service
- DTO
- Mapper 查询方法
- 单元测试

# 工作方式
先输出接口设计和实现计划，等待确认后再生成代码。

对话流有三个关键原则。

“遵循项目规范”对 AI 来说太宽泛，效果远不如“接口返回统一使用 Result<T>，错误码从 ErrorCode 中选择，飞书消息必须通过 FeishuClient 发送”。

Plan 模式：把复杂需求拆成可执行模块

复杂需求不能直接丢给 AI 生成代码。比如“实现一个拜访任务系统”，里面可能包含任务创建、审批、日程同步、列表查询、结果提交、导入、统计、通知、状态流转等功能。如果直接生成，很容易出现模块边界混乱、技术选型不一致、状态流转缺失等问题。

Plan 模式适合处理这种大任务。它本质上借鉴了 WBS（Work Breakdown Structure，工作分解结构）：先拆模块，再设计方案，再排优先级。

flowchart TD
    A[复杂需求] --> B[需求分析]
    B --> C[模块拆分]
    C --> D[技术方案设计]
    D --> E[依赖关系梳理]
    E --> F[优先级排序]
    F --> G[分阶段实现]

以“拜访任务线上化”为例，可以先拆出这样的模块清单：

这个拆分能让 AI 明确每次只实现哪个模块，也能让开发者控制交付顺序。

一个更稳妥的落地节奏是：

Plan 模式的价值不只是让 AI 有计划地工作，也让人可以在“模块边界”和“实现顺序”上提前发现问题。

CLAUDE.md：系统提示词要像护栏，不要像百科全书

CLAUDE.md 可以理解为 Claude Code 的团队规则文件。它告诉 AI 当前项目的技术栈、编码约束、工作方式和禁止事项。

常见错误是把 CLAUDE.md 写得特别长，从架构说明到代码规范全部塞进去。上下文越长，AI 越容易抓不住重点。系统提示词更适合做“护栏”，把高频出错点和硬性规则写清楚。

一个简洁的 CLAUDE.md 可以这样组织：

# Role
你是当前项目的后端开发助手，负责根据既有架构生成可合入代码。

# Hard Rules
- 不要修改未被任务明确要求修改的模块。
- Controller 返回统一使用 Result<T>。
- Service 必须遵循现有分层结构，不要绕过已有领域服务。
- 数据库操作使用 MyBatis-Plus。
- 第三方调用必须复用项目已有 Client，不要重复封装。
- 所有入参必须做非空校验和业务校验。

# Workflow
- 复杂任务先输出方案和文件变更列表，等待确认后再写代码。
- 每完成一个模块，需要说明修改了哪些文件、覆盖了哪些测试。
- 不确定时先提问，不要自行假设业务规则。

系统提示词可以按三类信息维护：

更好的做法是让 CLAUDE.md 引导 AI 去查文档，而不是把所有知识复制进去：

遇到分布式事务问题时，参考 docs/distributed-transaction.md。
遇到飞书消息发送问题时，复用 FeishuClient，调用示例参考 docs/feishu-message.md。

这样能降低系统提示词长度，也能让团队知识沉淀在更容易维护的位置。

SKILL：把稳定经验封装成可复用能力

SKILL 适合沉淀高频、稳定、规则明确的开发经验。它不是普通 Prompt 的简单收藏，而是把“某类任务应该怎么做”封装成可重复调用的能力。

适合封装成 SKILL 的场景包括：

比如团队内部已经有统一的 Elasticsearch SDK（Software Development Kit，软件开发工具包），就可以把调用方式、分页规范、异常处理和示例代码封装成 SKILL。以后遇到搜索需求，AI 不需要重新猜测实现方式，而是按团队固定模式生成代码。

MCP：让 AI 连接外部工具和数据源

MCP 解决的是 AI 与外部系统连接的问题。没有 MCP 时，AI 主要依赖对话上下文和静态文件；接入 MCP 后，AI 可以在授权范围内读取文档、创建文档、追加表格数据或调用内部工具。

flowchart LR
    A[Claude Code] --> B[MCP Server]
    B --> C[需求文档]
    B --> D[知识库]
    B --> E[多维表格]
    B --> F[内部工具]

常见用法有三类：

MCP 的边界要控制好。AI 能访问外部系统，不代表它应该拥有任意写权限。对于创建文档、追加记录这类低风险操作，可以适度开放；对于修改生产数据、发布配置、执行高危命令，需要人工确认或直接禁止。

结构化对话：让 AI 真正理解需求

传统“需求一句话，AI 直接写代码”的方式，在简单 CRUD（Create、Read、Update、Delete，增删改查）场景里能用，但一进入复杂业务就容易失控。

问题通常来自三个方面。

结构化对话可以分成三个阶段。

flowchart TD
    A[需求定义] --> B[边界明确]
    B --> C[迭代反馈]

    A1[用户故事] --> A
    A2[验收标准] --> A

    B1[必须遵守] --> B
    B2[建议参考] --> B
    B3[禁止事项] --> B

    C1[分模块实现] --> C
    C2[关键节点确认] --> C
    C3[持续更新方案] --> C

阶段一：用用户故事和验收标准描述需求

用户故事负责说明“谁在什么场景下需要什么能力”，验收标准负责说明“做到什么程度才算完成”。

【用户故事】
作为商家运营，我需要一个商家信息查询接口，查询结果需要根据我的数据权限进行过滤。

【验收标准】
- 支持按商家 ID、商家名称、商家状态查询。
- 支持分页查询，默认每页 20 条，最大 100 条。
- 查询结果需要根据当前用户的数据范围过滤。
- 商家手机号、身份证号需要脱敏。
- 接口需要权限校验，至少具有“商家查看”权限。
- 查询条件需要记录到操作日志，便于审计。

这种写法比“实现商家查询接口”更容易得到符合业务预期的代码。

阶段二：把技术约束分成“必须遵守”和“建议参考”

不同约束的强度不一样。硬性约束必须执行，参考约束可以帮助 AI 找到项目里的相似实现。

【技术约束】

必须遵守：
- 使用 Spring Boot 标准分层架构。
- 数据库访问使用 MyBatis-Plus。
- Controller 返回 Result<T>。
- 权限校验使用 @Permission。
- 参数校验使用 @Valid 和 ValidatorUtil。
- DTO（Data Transfer Object，数据传输对象）转换使用 ConvertUtil。
- 飞书消息发送必须使用 FeishuClient，不要重复实现。

建议参考：
- 状态流转参考 TaskServiceImpl 的状态机实现。
- 批量处理参考 AssignImportHandler 的异步处理方式。
- 数据权限过滤参考 ScopeServiceImpl 的范围查询逻辑。

禁止事项：
- 不要新增与现有 Client 功能重复的第三方 API 封装。
- 不要修改与当前任务无关的表结构。
- 不要硬编码 API Key、租户 ID 等敏感配置。

把约束拆清楚后，AI 更容易判断哪些规则不能突破，哪些代码可以借鉴。

阶段三：用迭代反馈控制生成节奏

一次性让 AI 生成 Controller、Service、Mapper、数据库脚本、单元测试，很容易等到最后才发现方向错了。更稳的方式是让 AI 在关键节点暂停。

sequenceDiagram
    participant D as 开发者
    participant A as Claude Code

    D->>A: 输入用户故事、验收标准、技术约束
    A-->>D: 输出模块拆分和实现计划
    D->>A: 确认计划，要求先设计表结构
    A-->>D: 输出表结构和索引
    D->>A: 调整索引，确认继续
    A-->>D: 生成 Service 核心逻辑
    D->>A: 审查业务逻辑，反馈问题
    A-->>D: 修改实现并补充测试
    D->>A: 确认后生成 Controller

关键确认点通常包括：

子代理协作：把 AI 从单助手变成小团队

单个 AI 助手处理简单任务没有问题，但复杂项目往往需要不同角色协作：有人负责方案设计，有人负责编码，有人负责审查，有人负责前端页面配置。Claude Code 的 SubAgent 模式可以模拟这种分工。

更推荐“中间产物驱动”的协作方式。所有子代理围绕同一份技术方案文档工作，而不是让多个代理自由对话。

flowchart TD
    A[协调者] --> B[技术方案架构师]
    B --> C[技术方案文档]

    C --> D[代码实现专家]
    D --> E[代码与测试]
    E --> F[代码审查专家]
    F --> G{是否通过}

    G -- 否 --> D
    G -- 是 --> H[更新技术方案状态]

    C --> I[前端页面生成器]
    I --> J[页面配置]

技术方案文档是单一事实来源，通常包含：

• 需求背景；
• 模块拆分；
• 数据模型；
• 接口定义；
• 外部依赖；
• 实现状态；
• 责任角色；
• 审查结论；
• 待解决问题。

四类常见子代理角色

这种分工的价值在于：每个代理只关注自己擅长的部分，减少通用 AI 在复杂任务中“什么都做一点、但都不够稳”的问题。

为什么要用技术方案文档做中间产物

如果让多个子代理直接互相沟通，代理数量一多，沟通链路会迅速变复杂。假设有 n 个代理，理论上的双向沟通关系接近：

n * (n - 1) / 2

4 个代理就有 6 条沟通关系，6 个代理就有 15 条。每条链路都可能产生信息不一致。

中间产物驱动的方式把协作压缩到一份文档上：

flowchart LR
    A[子代理 A] --> D[技术方案文档]
    B[子代理 B] --> D
    C[子代理 C] --> D
    E[子代理 D] --> D

好处很直接：

• 信息有唯一来源；
• 变更历史可追踪；
• 人工评审更方便；
• 新加入的开发者可以快速理解当前状态。

子代理协作的风险和处理方式

代码审查子代理不应该只说“代码结构清晰”。更有用的审查提示应该要求它检查具体项：

请从以下维度审查代码：
- 是否符合技术方案中的模块边界；
- 是否错误修改了无关文件；
- 是否缺少权限校验；
- 是否缺少参数校验；
- 是否存在事务边界问题；
- 是否处理了重复提交和幂等；
- 是否复用现有 Client；
- 是否补充了失败场景测试；
- 是否存在空指针风险；
- 是否记录必要操作日志。

人和 AI 如何分工

AI 编程落地时，最重要的不是“让 AI 写多少代码”，而是“哪些事情交给 AI，哪些事情必须由人负责”。

开发者要对 AI 生成的代码负责。AI 可以参与实现，但不能承担线上质量责任。

上下文管理的实用方法

Claude Code 的输出质量很大程度取决于上下文管理。上下文越混乱，生成结果越不稳定。

为不同模块创建独立对话线程

不要在同一个对话里同时实现任务分配、审批、统计和导入。更合适的方式是一个模块一个线程，每个线程只保留与当前模块相关的信息。

visit-task-create-thread
visit-task-approval-thread
visit-task-statistics-thread
visit-task-import-thread

把关键决策写进外部文档

复杂项目不要只依赖聊天历史。数据库设计、接口定义、状态机、异常码、第三方集成方式都应该写入外部文档，然后在对话中引用。

数据库设计参考 docs/visit-task-db.md。
任务状态机参考 docs/visit-task-state-machine.md。
飞书审批接入方式参考 docs/feishu-approval.md。

在阶段切换时重复关键约束

AI 在长对话里容易发生约束衰减。进入新阶段时，可以简短重申硬性规则。

现在开始实现任务审批模块。请继续遵守：
1. 飞书审批必须通过 FeishuApprovalClient；
2. 状态流转必须符合 visit-task-state-machine.md；
3. 所有写操作需要记录操作日志；
4. 不要修改任务创建模块的已确认接口。

用状态标记跟踪进度

技术方案文档里可以维护模块状态：

状态标记能减少“这个模块到底做到哪一步了”的沟通成本。

质量控制：AI 生成代码必须经过门禁

AI 生成代码后，质量控制要比人工编码更明确。原因很简单：AI 很擅长生成看起来完整的代码，但它不一定理解项目里的隐性约束。

一套可执行的质量门禁可以这样设计：

flowchart LR
    A[AI 生成代码] --> B[静态检查]
    B --> C[单元测试]
    C --> D[集成测试]
    D --> E[代码审查]
    E --> F[人工确认]
    F --> G[合入]

各层门禁关注点不同：

还可以维护一个“AI 常见错误清单”，每次发现问题就反向更新提示词和审查清单。

AI 编程的边界

Claude Code 能降低重复劳动，但不能替代工程判断。几个边界需要提前认识清楚。

AI 编程不是“少做审查”，而是要把审查做得更清晰。

可直接落地的工作流

把上面的内容组合起来，可以形成一套比较稳的 Claude Code 使用流程：

flowchart TD
    A[输入 PRD 或需求描述] --> B[结构化需求]
    B --> C[生成技术方案]
    C --> D{人工评审方案}
    D -- 不通过 --> C
    D -- 通过 --> E[模块拆分与排期]

    E --> F[选择单个模块]
    F --> G[生成接口与表结构]
    G --> H{人工确认}
    H -- 不通过 --> G
    H -- 通过 --> I[生成核心代码]

    I --> J[生成测试]
    J --> K[代码审查]
    K --> L{是否通过}
    L -- 不通过 --> I
    L -- 通过 --> M[更新技术方案状态]

    M --> N{是否还有模块}
    N -- 是 --> F
    N -- 否 --> O[整体回归与合入]

配套的输入资产包括：

开发者的新职责

AI 编程时代，开发者的核心能力会从“亲手写出每一行代码”逐渐转向“定义问题、拆解任务、约束 AI、审查质量、承担结果”。

更具体地说，开发者需要掌握这些能力：

• 把模糊需求改写成用户故事和验收标准；
• 把复杂系统拆成边界清晰的模块；
• 用明确约束限制 AI 的自由发挥；
• 通过中间产物控制协作过程；
• 用测试和审查识别 AI 代码中的隐藏问题；
• 把团队经验沉淀成 CLAUDE.md、SKILL 和知识库。

Claude Code 可以成为研发流程里的加速器，但前提是流程本身足够清晰。没有边界的需求、没有确认节点的生成、没有质量门禁的合入，只会把问题从“人写得慢”变成“AI 错得快”。

真正可持续的 AI 辅助开发，不是让 AI 替人做决定，而是让 AI 在明确规则下承担标准化工作，让人把精力放在业务判断、架构权衡和质量控制上。