# 10.4 开发方法论

本节聚焦智能体编程的核心方法论，探讨如何将智能体融入日常开发工作流，实现从“写代码”到“编排 AI”的角色转变。

## 10.4.1 智能体开发闭环

在传统的开发流中，开发者亲自执行每一个循环。而在智能体工作流中，开发者上升为 **循环的管理者**。

这里说的“闭环”是**任务级闭环**，不是 [10.2 节](/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/10_agentic_coding/10.2_loop.md) 的单次 Agent Loop。10.2 的 **Think → Act → Observe** 发生在一次执行迭代内部；本节讨论的是开发者如何把许多轮微观迭代组织成一个可交付、可审查、可回退的工作流。至于审批、沙箱、Hooks 和规则等工程护栏，则放在 [10.5 节](/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/10_agentic_coding/10.5_best_practices.md) 处理。

### 10.4.1.1 任务级工作流：P-D-E-R 闭环

我们将智能体开发工作流概括为 **P-D-E-R** 四步循环：

* **Plan** - 规划任务目标
* **Decompose** - 拆解任务为原子任务
* **Execute** - 执行原子任务
* **Review** - 审查结果并迭代

```mermaid
graph TD
    subgraph P [1. 规划]
        P1[需求理解] --> P2[上下文组装]
    end

    subgraph D [2. 分解]
        D1[任务拆解] --> D2[制定计划]
    end

    subgraph E [3. 执行]
        E1[智能体编码] --> E2[工具调用]
    end

    subgraph R [4. 审查]
        R1[人工验收] --> R2[自动测试]
    end

    P --> D --> E --> R
    R -->|未通过| E
    R -->|通过| Done["完成"]
```

图 10-13：P-D-E-R 智能体开发循环

其中 **Execute** 往往会展开成多轮 Think-Act-Observe 微观循环；而 **Review** 的反馈既可能回到 Execute 继续修正，也可能上卷到 Plan / Decompose 重新定义任务边界。

### 10.4.1.2 工作流核心步骤

1. **准备上下文**：收集需求相关背景
2. **拆解为原子任务**：分化复杂需求
3. **智能体执行**：编码与迭代，直到反馈通过
4. **集成与交付**：系统测试与部署

### 10.4.1.3 规划先于执行

在现代智能体工具中，**规划模式** 是提升开发质量的核心功能。进入规划模式后，智能体不会立即编写代码，而是：

1. **调研代码库**：搜索相关文件，理解现有结构
2. **提出澄清问题**：确认需求边界和约束条件
3. **创建实施计划**：生成可编辑的 Markdown 计划文档
4. **等待批准**：用户确认后才开始实现

```mermaid
graph TD
    User[用户请求] --> Survey[代码库调研]
    Survey --> Qs[澄清提问]
    Qs --> Plan[生成计划]
    Plan --> Check{用户审核}
    Check -->|修改计划| Plan
    Check -->|批准| Impl[开始实现]
```

图 10-14：规划优先的开发流程

### 10.4.1.4 时间分配的重构

这种工作流的变化导致了开发者时间分配的显著转移：

| 活动        | 传统开发 | 智能体开发（典型变化）      |
| --------- | ---- | ---------------- |
| **需求与架构** | 相对较少 | 占比上升，需要更精确地定义问题  |
| **编写代码**  | 占比较高 | 占比下降，更多变成“审查与整合” |
| **调试与测试** | 稳定投入 | 更依赖自动化与回归测试      |
| **审查与验收** | 相对较少 | 占比上升，为 AI 产出把关   |

## 10.4.2 任务分解与提示词设计

好的任务分解和精准的提示词是智能体编程的两大基础能力。本节将 DECOMPOSE 任务分解框架与 CLEAR 提示词框架结合，形成 **“需求→分解→表达”** 的完整方法论。

### 10.4.2.1 DECOMPOSE 框架

```
D - Define     定义：明确任务目标和边界
E - Explore    探索：了解现有代码和约束
C - Chunk      切分：将大任务分解为小任务
O - Order      排序：确定执行顺序和依赖
M - Map        映射：为每个任务分配工具/智能体
P - Prompt     提示：为每个任务设计清晰的提示词
O - Observe    观察：监控执行过程
S - Synthesize 综合：整合结果并验证
E - Evolve     进化：总结经验更新规则
```

### 10.4.2.2 任务分解示例

**需求**：“实现一个用户认证模块”

**分解步骤**：

1. **需求理解**：确认认证方式（令牌/会话/第三方）、用户模型、安全要求（MFA、密码策略）
2. **技术调研**：查看现有代码结构、确认框架版本、选择依赖库
3. **实现**（可并行）：用户模型 → 认证逻辑 → API 路由（依赖前两项） → 前端集成
4. **测试**：单元测试、集成测试、安全测试
5. **文档与部署**：API 文档、部署配置、变更日志

### 10.4.2.3 CLEAR 提示词框架

分解完任务后，需要用精准的提示词向智能体表达每个子任务。本书提出 CLEAR 框架作为结构化的表达方式（注：此处的 CLEAR 为本书定义的实践框架，与其他同名框架定义不同）：

```
C - Context    上下文：提供相关背景信息
L - Location   位置：指明具体的文件和位置
E - Expected   预期：描述期望的行为或结果
A - Actual     实际：描述当前的问题或行为
R - Reference  参考：提供相关的参考实现
```

**示例应用**：

```markdown
C：API 使用某 Web 框架，认证采用令牌方案
L：@src/api/auth.py 的 verify_token 函数
E：Token 过期时应返回 401 并提示刷新
A：目前返回 500 错误，没有有意义的错误信息
R：参考 @src/api/middleware.py 中的错误处理模式
```

### 10.4.2.4 提示词实践技巧

**提供充足上下文**：指明文件位置、预期行为、参考实现。 例：`@src/api/users.py get_user 函数在 ID 为空时返回 500 错误。预期返回 400 + 清晰错误信息。参考 @src/api/orders.py 的处理模式。`

**分步骤执行复杂任务**：逐项拆解而非一步完成。 例：(1) 设计 Schema → (2) ORM 模型 → (3) 认证模块 → (4) CRUD API → (5) 订单逻辑 → (6) 集成测试

**验证与测试同步请求**：生成代码时同步要求单元测试、边界情况测试、并发测试。这让智能体更容易验证正确性。

## 10.4.3 规范驱动开发

规范驱动开发（Spec-Driven Development，SDD）是软件开发的一种方法论，它强调先编写 **规范文档**（Specification），再让智能体按规范实现。它特别适合智能体编程场景：规范文档既是给人的设计文档，也是给智能体的高精度指令。

### 10.4.3.1 为什么需要 Spec？

在传统开发中，开发者脑中有隐含的设计意图，边写代码边细化。但对智能体而言，**没有写下来的东西等于不存在**。规范文档解决了这个根本问题：

| 方式                 | 问题           |
| ------------------ | ------------ |
| 直接告诉智能体“实现一个缓存”    | 缺少约束，结果不可预测  |
| 口头描述 + 多轮对话修正      | 效率低，上下文积累不可控 |
| **先写 Spec，再交给智能体** | 一次性传达完整意图    |

### 10.4.3.2 Spec 文档的结构

一个有效的 Spec 通常包含以下要素：

```markdown
## 功能规范：[功能名称]

### 目标

简要描述这个功能要解决什么问题。

### 约束条件

- 技术栈、框架、性能要求
- 必须遵循的现有模式或接口

### 接口定义

具体的输入/输出、API 签名、数据结构。

### 行为规则

- 正常流程的预期行为
- 边界情况的处理方式
- 错误场景的响应

### 验收标准

- 功能通过的具体条件
- 必须覆盖的测试场景

### 参考

- 相关代码文件（使用 @ 引用）
- 类似功能的现有实现
```

### 10.4.3.3 示例：用 SDD 开发一个速率限制器

```markdown
## 功能规范：API 速率限制器

### 目标

为 API 网关实现请求速率限制，防止滥用。

### 约束条件

- 使用一个高速 KV 存储作为计数后端
- 与现有中间件链兼容（@src/middleware/chain.py）
- 单个请求增加延迟应尽量小

### 接口定义

class RateLimiter:
    def check(self, client_id: str) -> RateLimitResult
    def configure(self, policy: RateLimitPolicy) -> None

RateLimitResult: { allowed: bool, remaining: int, retry_after: int | None }
RateLimitPolicy: { requests_per_window: int, window_seconds: int }

### 行为规则

- 未超限：返回 allowed=True，更新计数
- 超限：返回 allowed=False，附带 retry_after 秒数
- 计数后端不可用时：降级放行，记录告警日志

### 验收标准

- 正常限流行为符合策略
- 后端故障时不阻塞请求
- 并发安全（多实例部署场景）
```

将这份 Spec 交给智能体后，它能清晰地理解：要做什么、不能违反什么、怎样算完成。相比模糊的口头描述，开发效率和产出质量都会大幅提升。

### 10.4.3.4 SDD 与 TDD 的关系

SDD 和 TDD 是互补而非替代关系：

```mermaid
graph LR
    Spec[Spec 规范文档] -->|定义| What["做什么"]
    TDD[TDD 测试用例] -->|定义| How["怎么验证"]
    What --> Impl[智能体实现]
    How --> Impl
    Impl --> Review[人工审查]
```

图 10-15：Spec 与 TDD 的互补关系

推荐的工作流是：**先写 Spec 定义边界，再写测试固化预期，最后让智能体实现**。这样智能体既有“目的地”（Spec），又有“导航仪”（测试），产出质量最高。

## 10.4.4 测试驱动开发

智能体在有明确目标可迭代时表现最佳。测试允许智能体做出更改、评估结果、逐步改进直到成功。

### 10.4.4.1 TDD 工作流

```mermaid
graph TD
    subgraph TDD [TDD + 智能体工作流]
        Define[1. 定义 Define] --> VerifyFail[2. 验证失败 Verify Fail]
        VerifyFail --> SubmitTest[3. 提交测试 Submit Test]
        SubmitTest --> Implement[4. 实现功能 Implement]
        Implement --> SubmitImpl[5. 提交实现 Submit Impl]
    end

    Define -->|让智能体根据预期<br>输入/输出编写测试| VerifyFail
    VerifyFail -->|告诉智能体运行测试<br>并确认失败<br>不要写实现| SubmitTest
    SubmitTest -->|满意后提交测试| Implement
    Implement -->|让智能体编写通过<br>测试的代码<br>不要修改测试| SubmitImpl
    SubmitImpl -->|满意后提交实现| Done
```

图 10-16：TDD 驱动的智能体工作流

### 10.4.4.2 TDD 提示词示例

```markdown
第一步（定义测试）：
"为 LRU 缓存类编写测试，测试以下场景：
 - 基本 get/put 操作
 - 容量超限时淘汰最久未使用的项
 - 并发安全
 不要实现功能，只写测试。"

第二步（验证失败）：
"运行测试确认它们失败（因为还没有实现）"

第三步（实现）：
"现在实现 LRU 缓存类让所有测试通过，不要修改测试文件"
```

## 10.4.5 架构可视化优先

在编写任何复杂功能之前，先让智能体画图。

### 10.4.5.1 为什么先画图？

1. **验证理解**：确认智能体脑子里的架构和你想要的一致
2. **文档化**：生成的图表直接存入 `docs/architecture/`，成为永久文档
3. **发现缺陷**：在写代码之前，通过看图往往能一眼发现逻辑漏洞

### 10.4.5.2 架构图提示词示例

```markdown
"为认证系统创建一个 Mermaid 序列图，包括：
 - 第三方登录提供商交互
 - 会话管理
 - Token 刷新流程
 - 错误处理分支"
```

**智能体输出**：

```mermaid
sequenceDiagram
    participant U as User
    participant C as Client
    participant A as Auth Server
    participant O as Identity Provider

    U->>C: 点击"Google 登录"
    C->>O: 重定向到登录授权页
    O->>U: 显示授权页面
    U->>O: 授权
    O->>C: 返回授权码
    C->>A: 发送 code
    A->>O: 交换访问令牌
    O-->>A: 返回令牌
    A->>A: 创建用户会话
    A-->>C: 返回访问令牌
    C->>C: 存储令牌

    Note over C,A: Token 刷新流程
    C->>A: 发送刷新令牌
    A->>A: 验证并生成新 token
    A-->>C: 返回新令牌
```

图 10-17：认证系统序列图示例

## 10.4.6 调试方法

当标准智能体交互难以解决 bug 时，Debug Mode 提供不同的方法：

```
Debug Mode 工作流程：
1. 生成多个关于可能出错的假设
2. 用日志语句检测代码
3. 要求重现 bug 同时收集运行时数据
4. 分析实际行为以定位根因
5. 基于证据进行定向修复
```

**适用场景**：

* 可重现但无法弄清的 bug
* 竞态条件和时序问题
* 性能问题和内存泄漏
* 曾经正常的回归问题

**提示词示例**：

```markdown
"这个函数有时会返回 null，但我不知道什么条件下会发生。
 请帮我：
 1. 列出可能导致返回 null 的所有情况
 2. 添加日志语句来追踪执行路径
 3. 建议如何重现这个问题"
```

***

**下一节**: [工程化实践](/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/10_agentic_coding/10.5_best_practices.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/agentic_ai_guide/di-san-bu-fen-gong-cheng-shi-jian-yu-luo-di/10_agentic_coding/10.4_workflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.