Agent Practice / 02
日常开发中的 Agent 工作流：从 Context 到 Loop 的实战方法论
Context Engineering、Harness Engineering、Loop Engineering——这三个词在面试里是知识点，但在日常开发中它们是真实的生产力差距。同一个 Claude Code，有人一轮就出高质量代码，有人反复改十轮还是跑不通。差距不在模型能力，在于你给它的上下文质量、你设计的执行骨架、你控制循环的方式。
这篇文章把三层 Engineering 拍平到日常开发场景——你每天打开终端、写代码、提 PR 时，怎么用这些方法论让 Agent 从“偶尔有用”变成“稳定高效”。
一、三层 Engineering 在日常开发中的角色
| 层次 | 面试里怎么说 | 日常开发中是什么 |
|---|---|---|
| Context Engineering | 送进模型的上下文组合 | 你的 CLAUDE.md、Skill 文件、Rule 配置、项目结构 |
| Harness Engineering | Agent 的控制循环骨架 | 你选什么工具、怎么拆任务、怎么组织一次开发会话 |
| Loop Engineering | 循环的退出和纠错 | 你怎么让 Agent 自验证、出错时怎么引导、什么时候该停下来自己接手 |
三者是递进关系：Context 决定 Agent“看到什么”，Harness 决定“怎么跑”，Loop 决定“跑多久、怎么收”。
二、Context Engineering 实战：让 Agent 一开始就少犯错
CLAUDE.md 是你最重要的基础设施
CLAUDE.md 不是文档，是 Agent 每轮对话都会读取的系统指令。写好它等于给所有后续交互打好地基。
最小有效 CLAUDE.md 结构：
# 项目概述
一句话说清这个项目是什么、技术栈、主要目录结构
# 开发约定
- 语言/框架版本
- 代码风格（命名、导入顺序、错误处理模式）
- 测试要求（跑什么命令、覆盖率标准）
- 禁止项（不能用的库、不能碰的目录）
# 常用命令
- 启动开发服务器：xxx
- 跑测试：xxx
- 构建：xxx
- lint：xxx
常见错误：
- 写太长（超过 500 行 Agent 注意力会涣散）
- 写太抽象（“代码要写得好”没有意义，“所有 error 必须 wrap 后返回，不允许裸 panic”有意义）
- 从不更新（项目结构变了但 CLAUDE.md 还是老的）
Skill 文件：可复用的领域上下文
当你发现自己在对话中反复描述同一件事（“我们的 API 返回格式是这样的”、“部署流程是这样的”），就该把它沉淀为 Skill。
适合做成 Skill 的内容：
- 特定类型任务的执行步骤（如“写一个新 API 端点”的标准流程）
- 领域知识（如“我们的权限模型有 4 层”）
- 代码模板和约定（如“新建 React 组件必须包含 xxx”）
不适合做成 Skill 的：
- 一次性的任务描述
- 频繁变动的临时状态
- 太泛泛的通用知识（模型已经知道了）
Rule 配置：自动化的行为约束
Rule 是比 CLAUDE.md 更细粒度的行为控制，通常放在 .claude/settings.json 里：
{
"permissions": {
"allow": ["Bash(npm test)", "Bash(npm run lint)"],
"deny": ["Bash(rm -rf *)"]
}
}
实战经验：
- 允许自动跑测试和 lint → Agent 可以自验证而不需要你手动确认
- 允许读取但限制写入范围 → 防止改到不该改的文件
- 把常用的安全命令加入白名单 → 减少权限弹窗打断心流
三、Harness Engineering 实战：工具选型和任务拆分
工具选型：不同场景用不同 Agent
没有万能工具。选择的核心逻辑是：任务的上下文范围有多大？需要多少轮交互？
| 场景 | 推荐工具 | 原因 |
|---|---|---|
| 单文件内的小改动 | Cursor Tab / Copilot | 补全足够，不需要 Agent 循环 |
| 跨文件重构（< 10 文件） | Claude Code / Cursor Composer | 需要理解多文件关系但范围可控 |
| 大型重构（> 20 文件） | Claude Code + Worktree | 需要隔离执行、分批验证 |
| 新功能开发（需求明确） | Claude Code | 需要完整的 plan → code → test 循环 |
| Debug（有报错信息） | Claude Code / Cursor | 贴入错误信息让 Agent 定位 |
| Code Review | Claude Code /code-review | 需要读取 diff 全貌 + 逐文件分析 |
| 文档撰写 | Claude（对话） | 不需要工具调用，纯文本生成 |
切换时机：如果发现 Agent 连续 3 轮没产出有效结果 → 可能工具选错了或上下文不够。
任务拆分：大任务怎么喂给 Agent
Agent 最擅长的是“目标清晰、范围有界、可验证”的任务。大任务必须拆：
拆分原则：
- 每个子任务可独立验证：完成后能跑测试或肉眼确认
- 子任务之间依赖最小化：不要让后面的任务强依赖前面的中间状态
- 先骨架后填肉：先生成接口/类型定义，再实现具体逻辑
大型重构的标准流程：
Step 1: 让 Agent 分析当前代码结构，输出改动计划
↓ 你审核计划，调整范围
Step 2: 按模块逐个执行改动
↓ 每个模块改完跑一次测试
Step 3: 全量测试 + lint
↓ 修复集成问题
Step 4: 生成 PR 描述
反模式：“帮我重构整个认证模块”——范围太大、无法验证中间状态、Agent 容易跑偏。
正确姿势：“先列出认证模块的所有文件和它们的依赖关系” → 审核后 → “把 session 存储从 Redis 改成 JWT，只改 auth/session.go 和 auth/middleware.go，改完跑 go test ./auth/…”
会话管理：一次会话该干多少事
一个会话 = 一个目标。不要在一个会话里又改 bug 又加功能又重构——上下文会互相污染。
实用规则：
- 一个会话的改动量控制在一个 PR 能审完的范围内
- 如果对话超过 20 轮还没收敛 → 新开会话，带上最新状态重新开始
- 复杂任务用 TodoWrite（或手写 plan）追踪进度，防止 Agent 遗忘已完成的步骤
四、Loop Engineering 实战：让 Agent 自己跑、自己验证、自己停
自验证循环：Write → Test → Fix
日常开发中最有价值的 Loop 模式是 Verification Loop——Agent 写完代码自己跑测试，测试不过自己修：
如何触发：
你的指令：
"实现 XX 功能。完成后运行 npm test，如果有测试失败，修复后重新运行，
直到所有测试通过。"
这比“实现 XX 功能”强 10 倍——因为你把退出条件和验证手段都交代清楚了，Agent 会自动进入 Loop 直到通过。
前提条件：
- 项目有可运行的测试（Agent 跑不了测试就无法自验证）
- 测试命令在 CLAUDE.md 或 Skill 中定义（Agent 知道跑什么）
- 权限允许自动执行测试命令（不需要你每轮点“允许”）
渐进式引导：Agent 跑偏时怎么拉回来
当 Agent 连续失败时，直觉反应是“算了我自己写”。但更高效的做法是渐进式引导：
| Agent 状态 | 你的干预 |
|---|---|
| 第 1 次失败 | 不干预，让它自己看错误信息重试 |
| 第 2 次失败（同一个错） | 给一句提示：“错误在 XX 方向，不是 YY” |
| 第 3 次失败 | 给具体约束：“用 XX 方案，不要用 YY” |
| 第 4 次仍失败 | 自己定位问题，只让 Agent 写你明确的修改 |
核心原则：每轮干预都缩小搜索空间，而不是重复让 Agent 自己猜。
什么时候该停下来自己接手
不是所有任务都适合让 Agent 循环到底。识别这些信号后果断接手：
- Agent 在两个方案之间震荡：改成 A → 测试失败 → 改回 B → 测试失败 → 又改成 A
- 错误信息 Agent 无法理解：底层依赖版本冲突、环境配置问题
- 需要全局判断的决策：架构选型、是否引入新依赖、是否该拆成多个 PR
- 连续 5 轮无进展：token 在燃烧但产出为零
接手不等于放弃 Agent——定位问题后可以把精确的修改指令交回给 Agent 执行。
Token 预算意识
日常开发中 token 不是无限的。实用策略：
- 新开会话解决新问题：不要在一个巨长的会话里追加无关任务
- 精简上下文：贴报错信息时只贴关键部分，不要全量日志
- 一次说清楚：与其 5 轮对话逐步补充需求，不如第一轮就把需求、约束、验证标准说完整
- 用 /compact 压缩：会话太长时主动压缩，保留关键上下文
五、AI Code Review 实战
Code Review 是 Loop Engineering 的典型应用——Agent 读 diff → 逐文件分析 → 输出发现 → 你决定是否采纳。
触发方式
# Claude Code 内置
/code-review
# 或手动指令
"Review 当前 branch 相对于 main 的所有改动，关注：
1. 逻辑 bug
2. 边界情况遗漏
3. 可以简化的代码
4. 安全风险
按文件逐个分析，每个发现标注严重程度（P0-P3）"
让 Review 质量更高的技巧
- 给具体维度：不说“帮我 review”，而是指定关注点（性能？安全？可读性？）
- 提供业务上下文：告诉 Agent 这个改动的业务目的，它才能判断逻辑是否合理
- 分层 review：先让 Agent 做一轮自动 review → 你看完发现后 → 对可疑点追问 → 最终决策
Review 的局限
Agent 擅长发现的：语法问题、明显逻辑错误、代码重复、命名不一致、缺少错误处理。
Agent 不擅长的：业务逻辑正确性、性能瓶颈（需要运行时数据）、架构合理性、是否过度设计。
六、完整工作流示例
示例：给现有系统加一个新 API 端点
Phase 1: Context（30 秒）
├── 确认 CLAUDE.md 是最新的
├── 如果有相关 Skill（如"新建 API 端点"模板），确认它存在
└── 如果是新领域，在对话开头补一段业务背景
Phase 2: Harness（指令设计，1 分钟）
├── 一次性说清楚：
│ "在 api/handlers/ 下新建 orders.go，实现 POST /api/orders 端点
│ 接收 {user_id, items, address} 创建订单
│ 参考 api/handlers/users.go 的风格
│ 完成后运行 go test ./api/... 确保通过"
└── 给出参考文件（Agent 不用自己找）
Phase 3: Loop（Agent 自动执行）
├── Agent 写代码
├── Agent 跑测试
├── 如果失败 → 自动修复 → 再跑测试
└── 直到通过（或你介入）
Phase 4: 验收（2 分钟）
├── 看 diff 是否合理
├── 手动测一下 happy path
└── 有问题则精确指出让 Agent 改
总耗时：5-10 分钟完成一个完整端点（含测试）。
示例：大型重构——迁移状态管理方案
Session 1: 调研和计划
├── "列出所有使用 Redux 的文件及其依赖关系"
├── Agent 输出文件列表和依赖图
├── 你审核后决定迁移顺序
└── 输出：迁移计划（哪些文件按什么顺序改）
Session 2-N: 逐模块执行（每个 session 处理 1-3 个文件）
├── "把 store/auth.ts 从 Redux 迁移到 Zustand，参考 store/ui.ts 的写法"
├── Agent 改代码 + 跑测试
├── 你验收后进入下一个模块
└── 每个 session 结束确认测试全绿
Final Session: 收尾
├── "删除 Redux 相关依赖，更新 package.json，全量测试"
├── "生成本次重构的 PR 描述"
└── 提交
关键：每个 session 只做一小块，做完验证，再下一块。 不要试图一个 session 搞定整个迁移。
七、不同工具的切换策略
| 你在做什么 | 最佳选择 | 为什么 |
|---|---|---|
| 写新功能，需求清楚 | Claude Code | 完整循环 + 自动测试 |
| 快速补全一小段代码 | Cursor Tab | 零延迟，不打断心流 |
| 跨多文件的复杂修改 | Claude Code + Plan 模式 | 先输出计划再执行 |
| 不确定怎么实现 | Claude 对话 | 先讨论方案，不急着写代码 |
| 修复一个 CI 报错 | Claude Code（贴入错误） | Agent 看错误信息定位问题 |
| 学习一个新库的用法 | Claude 对话 / 文档 | 理解优先，不需要工具调用 |
| Review 别人的 PR | Claude Code /review | 结构化分析 + 逐文件拆解 |
切换的信号：
- 你发现自己在 Agent 里反复描述同一个东西 → 沉淀为 Skill 或 CLAUDE.md
- Agent 输出太慢（任务太简单不值得走完整循环）→ 降级到 Tab 补全
- Agent 反复犯错（缺乏项目理解）→ 补充 Context 而不是重复催促
小结
- Context 是地基：CLAUDE.md + Skill + Rule 决定 Agent 从第一轮开始就走在正确方向上
- Harness 是骨架：选对工具、拆好任务、管好会话——这三件事决定执行效率
- Loop 是收敛器：让 Agent 自验证、渐进式引导、知道什么时候该接手
- 一次说清楚比分十轮补充高效 10 倍：需求、约束、验证标准、参考文件——一轮全给
- 大任务必须拆：每个子任务可独立验证，每个 session 有明确的完成标准
- 工具不是信仰：不同场景切不同工具，在 Agent 和手动之间灵活切换
下一篇建议继续看：
- AI Coding 面试：解题流程与交付策略——把这些方法论压缩到 30-60 分钟面试场景