Agentic Coding 工作流：从提示词到循环工程

一次让我重新想清楚工作流的翻车

今年三月初，我接了一个看起来简单的任务：修复用户反馈模块的导出功能——CSV 导出的表头和内容列数不一致，导致 Excel 打开后错位。我把这个任务丢给 Agent，prompt 写得很随意：「修复 CSV 导出表头和数据列不一致的问题」。

二十分钟后，Agent 返回了一大段 diff。表头确实修好了，但它顺手重构了整个导出模块的目录结构，把三个测试文件的 import 路径全部改了，还把一个已经废弃的 JSON 导出函数也做了「优化」。我花了四十分钟把无关改动回退，比我自己手写修复还慢。

问题不在模型能力，在于我没有给它一个可执行的工作流。我给了它一个目标，但没给边界、验证标准和回退条件。这次翻车让我意识到：Agentic Coding 的核心不是写好 prompt，而是设计一个从上下文到验证的完整循环。

从提示词到循环：一个正在发生的范式转移

Andrej Karpathy 在 2025 年底提出「Vibe Coding」这个概念时，描述的是开发者凭感觉跟 AI 对话、快速出原型的状态。不到一年，行业就发现这种模式在真实工程场景里撑不住——需求会变、上下文会丢、验证会漏。

Anthropic 在 2026 年初发布的《Agentic Coding Trends Report》中指出，采用 Agentic 编码的团队在「多步骤工程任务」上的交付质量，比纯 prompt 驱动方式高出 40% 以上，但前提是他们建立了结构化的工作流¹。DeepLearning.AI 的课程《Spec-Driven Development with Coding Agents》把这种结构化方法叫做「规格驱动开发」：先写清楚规格，再让 Agent 按规格执行，用验证循环确保结果不偏离²。

Addy Osmani 在 2026 年 6 月的博文「Loop Engineering」中把这种转变概括得更直接：「你不再是一个亲自 prompt agent 的人。你要设计的是那个替你 prompt 的系统。」³

这三条线索指向同一个结论：Agentic Coding 的竞争力不在于你能写出多精巧的 prompt，而在于你能不能把「理解上下文 → 制定计划 → 执行修改 → 验证结果 → 沉淀经验」这条链路变成可重复、可检查的工程循环。

五个环节的工程化拆解

我把这条链路拆成五个环节。每个环节都有它该做的事、容易犯的错和可以对照的检查标准。

上下文：让 Agent 看到你看到的

上下文不只是当前打开的文件。它包括代码结构、文档、历史决策、团队约定和当前任务目标。Agent 犯的大部分「自作主张」错误，根源都是上下文缺失——它不知道不该做什么，就只能猜。

稳定约束（编码规范、架构边界、技术栈选型）应该沉淀到项目级文件（如 CLAUDE.md、AGENTS.md）。临时目标（本次任务范围、不碰的模块、验收标准）应该写在任务描述里。两者混在一起会让 Agent 分不清长期规则和临时偏好。

// ❌ 坏做法：约束散落在 prompt 里，每次重写
const prompt = `
  修复 CSV 导出问题。注意我们的项目用的是 TypeScript，
  不要改目录结构，测试放在 tests/ 目录下，导出模块不要
  动其他文件...
`
 
// ✅ 好做法：稳定约束在项目文件，临时目标在任务卡片
// CLAUDE.md（长期约束，自动加载）:
// - TypeScript 严格模式
// - 测试放 apps/tests/，不放 apps/src/
// - 单个文件不超过 500 行
 
// 任务描述只写本次目标:
const taskCard = `
  ## Goal
  修复 CSV 导出表头与数据列数不一致
  
  ## Constraints
  - 只改 export/csv.ts 和对应测试
  - 不动目录结构和废弃函数
`

项目文件的优势在于它是持久化的——Agent 每次启动都自动加载，不需要你反复在 prompt 里复述同样的规则。Anthropic 的 Agent SDK 文档明确建议，持久规则应该放在 CLAUDE.md 里而不是初始 prompt 里，因为 CLAUDE.md 在每次请求时都会重新注入，而 prompt 会在上下文压缩时丢失⁴。

计划：在动手前发现需求缺口

复杂任务直接让 Agent 动手写代码，就像不画图纸就砌墙。计划阶段的核心价值不是产出文档，而是在动手前暴露需求缺口和隐含假设。

DeepLearning.AI 的规格驱动课程强调「项目宪章」（project constitution）的概念——用一份结构化的 markdown 文件定义目标、边界、技术约束、已有决策、子任务划分和验收标准²。这比 prompt 多了强制思考的过程。

<!-- ❌ 坏做法：一句话 prompt，隐含假设全靠猜 -->
<!-- 
  "给搜索结果加个分页"
  问题：每页多少条？后端分页还是前端分页？
  要不要改 URL 参数？空结果怎么处理？
-->
 
<!-- ✅ 好做法：结构化任务卡片，隐含假设显式化 -->
## Goal
搜索结果页增加分页功能
 
## Constraints
- 每页 20 条，后端分页
- URL 参数用 ?page=N，支持直接访问
- 空结果复用现有的 EmptyState 组件
 
## Out of Scope
- 不改搜索接口协议
- 不做无限滚动
- 不加服务端渲染优化

计划阶段的另一个关键作用是给 Agent 设定「不做清单」。我的经验是，明确告诉 Agent 不碰哪些东西，比告诉它做什么更有效——因为模型的默认行为是尽可能多做。

执行：保护工作区，控制变更半径

执行阶段最容易失控。Agent 修改了不相关的文件、重写了已有的实现、静默吞掉了错误——这些都不是模型「不听话」，而是工作流没有设置防护栏。

Claude Code 的 Agent SDK 提供了多层控制：工具权限（哪些工具可以自动执行）、Hooks（在工具执行前后拦截检查）、预算上限（防止无限循环）⁴。关键是把这些控制当作工程基础设施来配置，而不是每次都靠人盯着。

// ❌ 坏做法：Agent 无限制执行，出问题才发现
// 直接跑一个开放 prompt，不设上限
const result = await query({
  prompt: "improve this codebase"
  // 没有 maxTurns，没有 allowedTools，没有 budget
})
 
// ✅ 好做法：限制工具范围、设置预算、配置检查钩子
const result = await query({
  prompt: "修复 CSV 导出表头与数据列数不一致",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],  // 只给必要工具
    settingSources: ["project"],              // 加载项目规范
    maxTurns: 15,                             // 防止无限循环
    effort: "high",                           // 匹配任务复杂度
    // Hooks 可以在工具执行前拦截危险操作
  }
})

Addy Osmani 在 Loop Engineering 博文里提出一个重要概念：把「做事的 Agent」和「检查的 Agent」分开³。写代码的模型给自己打分，就像学生批改自己的作业——它倾向于认为自己的输出是对的。一个独立的验证步骤（甚至用不同模型）能显著提高质量。

验证：从「生成了代码」到「有证据支持」

验证是把 Agentic Coding 从玩具变成工程工具的分水岭。没有验证的 Agent 输出只是「看起来像代码的文本」，有验证的输出才是「可以交付的工程变更」。

不同任务需要不同的验证方式。不是所有任务都需要写单元测试——类型检查、构建通过、浏览器验收、截图对比、日志检查都可以是有效的验证手段。关键是验证方式要和任务风险匹配。

// ❌ 坏做法：Agent 说「修好了」就信了
// 没有运行任何验证命令，完全依赖模型的自我评估
// Agent 输出："已修复 CSV 导出问题，测试应该能通过。"
// 实际上测试跑都没跑
 
// ✅ 好做法：在任务卡片中定义验证命令，Agent 必须执行并报告结果
// Acceptance 部分：
// - pnpm --filter web check-types 通过
// - pnpm --filter web test -- --grep "CSV export" 通过
// - 手动验证：导出 10 行数据，确认表头和列数一致

美团技术团队在 AI Coding 实践中总结了「Red-Green-Refactor」三阶段验证循环：先写一个会失败的测试（Red），让 Agent 实现功能使测试通过（Green），再让 Agent 重构代码保持测试仍然通过（Refactor）⁵。每个阶段都有自动化验证作为护栏。

复盘：把一次经验变成可复用资产

复盘不是写总结报告。它是把这次任务中发现的模式沉淀为可复用的工程资产——规则更新到项目文件、边界条件补进测试、常见问题写成 Skill、重复操作升级为 Hook 或模板。

<!-- ❌ 坏做法：复盘写成流水账，下次还会犯同样的错 -->
<!-- 
  "3月5日修复了CSV导出问题，Agent多改了目录结构，
   以后需要注意。"
  问题：没有可执行的行动项，三个月后新人还会踩同一个坑。
-->
 
<!-- ✅ 好做法：复盘产出可落地的工程改进 -->
## 本次发现
Agent 在没有明确约束时会自行扩展修改范围
 
## 改进项
- [x] 在 CLAUDE.md 中增加「不修改无关目录结构」约束
- [x] 新增 export 模块的快照测试，防止目录结构被改
- [x] 创建 export-fix Skill 模板，包含标准任务卡片

一条端到端任务链路

把五个环节串起来，一个完整的 Agentic Coding 任务链路如下：

这条链路把「写代码」放在中间，而不是第一步。前面的上下文加载和计划确认决定了 Agent 能不能做对事，后面的验证和复盘决定了交付质量和经验是否可复用。

以「修复首页搜索接口报错」为例，实际执行过程：

1. 加载上下文：读取 Header 搜索组件、API 调用模块、最近的 git log
2. 判断复杂度：涉及 UI + API 两层，属于中等复杂，需要计划
3. 生成计划：先定位错误类型 → 确定失败态处理方案 → 最小修改 → 验证
4. 人确认：不重做 Header UI，不改后端接口协议
5. 执行：在 API 层增加错误捕获，UI 层显示降级状态
6. 验证：类型检查通过 → 单元测试覆盖错误分支 → 浏览器验证降级展示
7. 复盘：把「API 调用缺少错误处理」这个模式补进项目的 API 模块规范

三种典型场景的对比实践

场景一：修复 lint 错误

场景二：实现新功能

场景三：跨模块重构

工作流成熟度对比

什么时候不要让 Agent 自动推进

不是所有任务都适合让 Agent 端到端自动执行。以下场景应该让 Agent 做探索、梳理和方案比较，但不直接进入写文件阶段：

• 需求目标仍在变化，团队还没达成共识
• 涉及生产数据或用户隐私，误操作代价不可逆
• 需要跨团队确认接口契约，Agent 没有信息源
• 验证环境不可用（依赖未就绪、第三方服务宕机），且没有替代检查手段
• 安全敏感区域（鉴权、加密、支付逻辑），需要人逐步审查

这些场景不是不能用 Agent，而是要把 Agent 的角色从「执行者」切换为「分析者」。让它读代码、找问题、列方案、做对比，但最终修改由人来决定。

团队采用路径与质量指标

先把 Agentic Coding 工作流用在低风险、可验证的任务上——修 lint、补文档、整理测试失败、实现小型功能。等团队积累足够样例和信心后，再扩大到跨模块功能和长期自动化。

可以用四类指标观察采用效果：

这些指标比「Agent 生成了多少行代码」更接近真实的工程价值。返工率高说明上下文或计划阶段有问题；验证覆盖低说明团队还在「信任 Agent 的自我评估」；变更集中度低说明执行边界没设好；接管成本高说明计划产出不够清晰。

交付前检查清单

以下清单按任务阶段分组，可以在每次 Agentic Coding 任务中逐项检查：

上下文阶段

• 项目级约束文件（CLAUDE.md / AGENTS.md）已更新到最新
• 任务相关的代码文件路径已明确列出
• 历史决策和已有约定已记录在 Agent 可访问的位置

计划阶段

• 任务目标用一句话可以清晰描述
• 约束条件（不碰什么）已显式列出
• 验收标准已定义，且可以用命令验证
• Out of Scope 已标注，避免 Agent 自行扩展

执行阶段

• Agent 的工具权限已收窄到必要范围
• maxTurns 或预算上限已设置
• Hooks 或权限规则已配置，拦截危险操作

验证阶段

• 验证命令已实际运行（不只是 Agent 声称通过）
• 验证结果已作为证据记录在交付报告中
• 验证方式与任务风险匹配（不是所有任务都需要单测，但关键路径必须有）

复盘阶段

• 本次发现的问题模式已记录
• 可复用的改进项已转化为具体行动（更新规范 / 补测试 / 建模板）
• 重复出现的问题已考虑升级为自动化（Skill / Hook / 模板）

小结

Agentic Coding 工作流的本质是把「写 prompt 碰运气」变成「设计循环工程」。上下文让 Agent 看到全貌，计划在动手前暴露假设，执行阶段控制变更范围，验证提供交付证据，复盘把经验变成可复用资产。这五个环节形成的循环不是一次性的，而是随着每次任务不断加固——项目文件越来越精准，任务模板越来越成熟，验证手段越来越自动化。

最终决定 Agentic Coding 效果的，不是你用了多强的模型，而是你的工作流能不能让模型在正确的边界内、用正确的方式、做正确的事。

参考资料