如果你最近也在折腾AI Agent大概率会注意到一个高频词Loop Engineering。我第一次听到这个词以为是什么新编译理论直到自己做的周报Agent在线上把两个团队的业绩数据搞混还一本正经地写了分析结论我才彻底意识到Agent开发最大的敌人不是提示词写得不好而是我们根本没有用“循环”的方式去喂养它。这篇文章不讲空概念就拿一个PRD评审Agent的完整开发过程带你把Loop Engineering从理论过到实践。1. Loop Engineering到底是什么先解决“为什么”1.1 我的一次典型翻车现场先说上个月的真实经历。我接了一个内部需求用Claude自动汇总各团队的周报提取关键进展、风险项和下周计划做成固定格式的文档。第一版我自认为写得很完整明确的系统提示词、字段定义、接口对接、输出模板一个下午全部搞定。上线第一天就出问题——它把B团队的“待上线功能”写成了A团队的“已完成功能”备注栏还加了句煞有介事的“根据周报原文总结”。排查半天原因其实很简单我喂给它的上下文里两份周报的格式高度相似模型在长文本中混淆了归属而我的代码里没有任何校验机制。这件事让我重新思考一个问题为什么传统软件不会犯这种“串数据”的错误因为传统软件是确定性逻辑输入固定输出就固定。Agent不是。同一个提示词跑两遍结果可能不同换了上下文顺序结论可能完全翻转。面对这种概率性系统我原来的开发方式——写完就上线、出问题再补丁——本质上是在“撞大运”。1.2 核心循环Observe → Plan → Build → Run → ReflectLoop Engineering这个名字直译就是“循环工程”。它不是某个具体工具而是一套围绕Agent生命周期的工作方法核心思想可以用五个词概括Observe观察记录Agent每次运行的输入、输出、工具调用过程包括成功和失败。Plan计划根据观察结果决定下一轮改什么——是提示词、工具定义、上下文结构还是校验逻辑。Build构建做一个小改动绝不一次改多个变量。Run运行拿真实样例或固定测试集跑一轮观察改动效果。Reflect复盘整理这轮循环的得与失把结论写回文档进入下一轮。这五步走完一圈Agent的行为就会向“更符合预期”的方向逼近一步。关键在于每一步的产物都是下一轮的输入Observe产出的日志是Plan的依据Run产出的结果是Reflect的证据。整个系统是自反馈的而不是一次次从零开始“灵光一现”。为什么这个方法对Agent特别重要打个比方传统开发像盖楼有图纸按图纸施工验收看是否符合图纸。Agent开发更像驯狗没有哪个训犬师能靠一次性写好厚厚一本来让狗学会所有动作一定是“下达指令—观察反应—纠正—再来一次”的循环而且每次只强化一个行为。1.3 对比Loop Engineering vs 老思路、老方法我整理了一张自己在内部培训时用的对比表直接说透差别。维度传统“一次性提示词”开发Loop Engineering开发心态写完就交付养一个系统持续迭代对错误的态度出bug再修错误是下一轮改进的输入改动粒度经常大改提示词每轮只改一个变量质量依据跑一两个例子感觉还行固定评估集 日志回放可回溯性几乎没有每个版本的输入输出都有存档这套方法并不玄。它把“Prompt Engineering”从一种偏灵感的行为拉回到工程管理的轨道上。真正为难人的不是理解概念而是“什么时候该改提示词、什么时候该改工具、什么时候该改上下文”这些判断需要真实数据支撑而不是拍脑袋。1.4 什么场景最适合用Loop Engineering结合我做过的项目这类方法最适合以下几类场景RAG检索增强生成应用。知识库内容多、答案要求有据可查循环的关键点集中在召回质量和引用准确性。Agent工作流。多步骤任务、多工具调用每一环都可能失败需要通过循环逐环节加固。自动化内容生产。周报、摘要、邮件等有固定格式需求的场景输出稳定性是核心指标。需要长期维护的Agent。只要Agent会持续被使用需求就会变化循环就不会停。不适合的场景也有纯计算逻辑、一次性脚本、对延迟极其敏感且结果必须确定的系统。这些用传统代码就好没必要套Agent。2. 动手前的准备给循环工程搭好脚手架2.1 工具选型我为什么用这套组合很多教程一上来就推Agent框架我反而建议前期别用太重的东西。Loop Engineering的核心是“观察与反馈”框架越重你越难看到真实行为。当前阶段我实际使用的组合是Claude Claude Code作为Agent运行时的核心。选择它的原因很简单工具调用能力强能自然地在循环中接文件读写、执行命令、调用搜索。Git作为每一轮循环的版本管理。每一轮Prompt、代码、评估脚本的改动都要能回滚Git的diff就是你的“迭代日记”。自写的JSONL日志作为Observe环节的载体。一个用Python写的简易评估脚本作为Run环节的度量衡。工具本身不值钱值钱的是它们被组合成了一个闭环Claude Code负责执行Git负责留痕日志负责观察评估脚本负责判断。2.2 项目结构从第一天就为循环而设计目录结构是很多人忽略的细节。建立一个适合循环工程的项目结构第一天多花二十分钟后面省几十倍的时间prd-review-agent/ ├── agent.sh # 入口脚本跑一次就处理一份PRD ├── src/ │ ├── prompt.py # 所有提示词版本管理用变量区分 │ ├── schema.py # 输出Schema与校验逻辑 │ ├── loader.py # 文档读取与分块摘要 │ ├── tools.py # 自定义工具定义与容错 │ └── eval.py # 固定评估集运行脚本 ├── tests/ │ └── cases/ # 12个固定测试文档golden是期望结果 ├── logs/ │ ├── loop-001.jsonl # 每一轮循环的运行轨迹 │ ├── loop-002.jsonl │ └── loop-003.jsonl └── docs/ └── 迭代记录.md # 每轮改了什么、为什么改、效果如何这个结构的核心是“一切痕迹可追溯”。logs目录是循环的眼睛cases目录是循环的标尺迭代记录是循环的大脑。我在实际项目中靠这套结构在一个月里迭代了40多轮每一轮都有据可查没出现过“我改了什么导致效果变好/变坏都不知道”的窘境。2.3 最小可用脚本先跑通再谈优化准备阶段最后一步写一个能单次运行的最小脚本确认Claude的API能通、输出能落盘。我的做法是先用一个Python脚本做“裸调用”不接任何工具# run_once.py import os import json from anthropic import Anthropic client Anthropic(api_keyos.getenv(ANTHROPIC_API_KEY)) with open(docs/sample_prd.md, r, encodingutf-8) as f: prd_text f.read() resp client.messages.create( modelclaude-sonnet-4-20250514, max_tokens2048, system你是一位严谨的技术负责人请评审PRD并输出JSON结果。, messages[{role: user, content: prd_text}], ) print(resp.content[0].text)运行后把输出手动复制到logs/loop-000-raw.txt。为什么要手动因为在这一步我想用最笨的方式确认“裸模型到底会说出什么”而不是被框架里自动解析、自动后处理的逻辑掩盖真实行为。很多Agent问题的根源恰恰在于框架帮你做了过多“智能处理”让你根本看不到模型的原生输出。3. 项目实战PRD评审Agent的四轮迭代3.1 第一轮循环先跑通最小闭环再喊停现在进入主菜。我们要构建的Agent任务很明确输入一份产品需求文档PRD输出结构化的评审结论包括整体评分、主要风险、缺失项、补充建议。第一轮的提示词我故意写得很简单你是一位资深技术负责人。请评审下面这份PRD输出JSON格式结果。 字段要求score0-100整数、risks风险列表、missing缺失项列表。把一份正常的PRD喂进去模型输出的结果大致长这样{ score: 还不错, risks: 见下面分析有几点风险需要注意1、数据源未明确2、权限模型缺失, missing: 回滚方案、性能指标 }这个输出暴露了两个问题字段名没遵守risks成了字符串类型也乱了score不是整数。更麻烦的是这种输出在不同轮次之间不稳定有时候字段完全对有时候字段飘了。这里就是第一轮循环的Plan环节问题已经很清楚不是提示词写得不够漂亮而是“输出缺少结构化约束”。我在Build这一步做的改动很小引入了一个Pydantic模型做Schema校验并且给解析过程加上了重试机制# schema.py from pydantic import BaseModel, Field, ValidationError class ReviewResult(BaseModel): score: int Field(..., ge0, le100, description整体评分0-100) risks: list[str] Field(..., description风险点列表) missing: list[str] Field(..., description缺失项列表)配合一个带重试的解析函数import json from pydantic import ValidationError def parse_review(text: str, max_retries: int 3): for attempt in range(max_retries): try: # 去掉可能的markdown代码块包装 cleaned text.strip().strip() if cleaned.startswith(json): cleaned cleaned[4:] data json.loads(cleaned) return ReviewResult(**data) except (json.JSONDecodeError, ValidationError): continue raise RuntimeError(无法解析模型输出)这轮的Run结果很稳定格式问题基本消失了。但我从日志里观察到另一个潜在坑——模型偶尔会输出json包裹的代码块如果不做剥离JSON解析会直接挂掉。这种细节只有通过Observe环节才能发现靠想象是想不出来的。Reflect这一轮我写了三句话输出格式需要用Schema强制校验重试机制是合法的稳健手段日志里保留原始输出很重要因为解析失败时你需要人工回看原始内容。3.2 第二轮循环让评价从“感觉”变成“有依据”第一轮跑通后我拿真实PRD测试发现一个更隐蔽的问题模型的评分和评语经常“两张皮”。比如它给了一个58分理由却写着“整体方案较完整”而风险列表里只挤了一条不痛不痒的“建议补充性能测试”。这个评审没有任何参考价值。问题出在哪不是模型能力而是它缺少“评审认知框架”。你让它评一个苹果它可以凭印象说“还行”但如果你告诉它“甜度、脆度、香气、大小各占25分并要指出扣分原因”它的输出质量立刻不一样。我的改动在系统提示词里加了一套评审锚点你是一位资深技术负责人请按以下评审维度逐一打分每个维度必须列出扣分依据 1. 需求完整性25分背景、用户故事、功能清单、边界条件是否完整。 21-25分需求清晰边界明确16-20分需求基本清楚但边界模糊15分以下存在明显歧义或功能缺失。 2. 技术可行性25分涉及的数据来源、接口依赖、系统瓶颈是否说明。 3. 风险描述25分是否列出关键风险、影响范围、后备方案。 4. 验收标准25分是否有可执行、可量化的验收标准。 每条风险与缺失项必须引用PRD中的原文或章节作为依据格式见标题“XXX”。这里有个实操心得给分值时一定要给“锚点描述”。只写“按五个维度打分”和写“21-25分是什么标准、16-20分是什么标准”模型输出的稳定度完全是两个等级。锚点相当于把模糊的“评分”变成了有判断边界的分类任务。第二轮的Run结果用了真实验证我从3份不同质量的PRD上观察到明显变化评分与扣分依据基本对齐了例如给62分时理由会准确指向“验收标准中未提及性能目标见标题‘6. 验收标准’”。但新的问题又浮现出来——它偶尔会引用一个PRD里根本不存在的章节。3.3 第三轮循环把30页的长文档装进一个没有塞满的上下文第二轮的PRD都是短文档没有触及上下文长度问题。真正让我头疼的是第三轮遇到的一份30多页、带大量表格和技术细节的完整PRD直接塞进上下文后模型出现了典型的“长文迷失”现象——开头的内容记得很清楚中后段的关键约束全被忽略。我查日志发现一个典型错误模型声称“该方案与现有订单系统兼容”但实际上PRD的第17页明确写着“需要新增独立的结算服务避免与现有订单系统耦合”。模型并不是瞎编而是它在长距离上下文中丢失了被截断位置的细节。这轮我做的改动不再盯着提示词而是给Agent增加一个“文档地图”工具。核心逻辑很直白把长文按章节切块先用模型对每块做压缩摘要然后把这些摘要按原始章节编号组装成一个“预览地图”让大模型先读地图再根据任务需要按章节号调用原文。# loader.py def build_doc_map(prd_text: str) - list[dict]: chapters split_by_heading(prd_text) # 按 Markdown 标题切分 chunks [chunk_text(ch, max_chars4000) for ch in chapters] summaries [summarize_with_model(c) for c in chunks] return [ {id: i 1, title: raw_title, summary: s, chars: len(raw)} for i, (raw_title, s) in enumerate(zip(chapters, summaries)) ]实际运行时Agent的流程变成先读doc_map发现订单系统那一段在17章然后通过read_chapter(id17)工具拿回原文再结合原文写结论。这个“地图按需取段”的结构原理上很像人读书先翻目录再找重点章节精读。这轮循环留下的最大教训是不要天真地以为长文档靠“加大上下文窗口”就能解决。模型对超长上下文的注意力是非均匀的与其赌它在2万字的尾巴上不遗忘不如主动把文档结构喂给它。上下文本身也是工程的一部分是需要被设计、被压缩、被按需调用的资源。3.4 第四轮循环工具调用也会犯错而且很擅长一本正经地犯错Agent接上工具之后有几个很典型的错误模式调用参数写错、工具返回值没被正确引用、以及工具抛异常后Agent直接摆烂。我在第四轮遇到的具体场景是Agent需要先调用read_chapter拿某章的原文再根据原文写评审条目。结果它连续两次把章节号传成了字符串17.1.2 订单同步方案而工具定义明确要求传int类型的章号。还有一次工具返回了某个章节的内容Agent在结论里引用的却是“见标题‘10. 风险清单’”和实际返回的章节号对不上。这轮我做了三件事第一在工具定义里明确参数约束和错误提示# tools.py tools [ { name: read_chapter, description: 读取PRD指定章节的原文。参数chapter_id必须是整数来自doc_map中的id字段。若id不存在将返回错误信息请检查id后再调用。, input_schema: { type: object, properties: { chapter_id: {type: integer, minimum: 1} }, required: [chapter_id] } } ]第二在Agent运行逻辑中捕获工具异常把异常信息直接拼接回模型上下文让模型看到自己刚才哪儿错了自己决定怎么修正。这比“程序层面直接中断重试”更有效因为模型能在原地纠错并继续任务。def execute_tool(name: str, args: dict, context: list): try: result call_tool(name, args) context.append({role: user, content: f工具返回{result[:2000]}, tool_used: name}) except Exception as e: context.append({role: user, content: f工具调用失败{str(e)}请检查参数后重试或跳过。})第三给输出增加引用溯源校验模型在risks和missing里引用章节时必须使用{章节id}{原文摘要}的格式我写了一个简单的校验器如果引用的章节id不在doc_map的id集合里程序自动打回并要求重新生成。第四轮循环结束后Agent整体已经能稳定处理12份测试集里的文档格式稳定、评分有依据、长文能溯源、工具调用很少出错。但离“生产可用”还差一道关就是如何防止自己在后续迭代中把它改回一个烂样子。4. 调试复盘把玄学变成可评估的工程4.1 可观测性每一轮循环都留下“黑匣子”很多Agent项目死在“看不见”。你改了一版提示词跑了一次感觉“好像变好了”实际是随机波动还是真实改进答案只能从日志里找。我规定自己每一轮运行都写JSONL每一条记录包含以下字段字段说明示例timestamp运行时间2025-06-15T10:23:11Zloop_version循环版本号v007doc_name输入文档名sample_05.mdinput_hash输入文本哈希sha256:e3b0c44...output_text模型原始输出{score:72,...}schema_ok是否通过Schema校验truetool_calls工具调用序列[{name: read_chapter, args:{chapter_id:17}}]observed_issues人工记录的问题引用章节17不存在这个表看着简单但它在关键时刻救过我。有一次Agent表现忽好忽坏我对比了v012和v013两轮的日志发现v013的某次运行没有执行工具调用直接编了答案——因为那一次工具定义加载失败了。没有日志我可能又要去“优化提示词”而真实问题出在工具注册的时序错误。日志还有一个妙用回放。当模型表现下降时我把历史成功case的完整对话序列重新拉出来能直接定位是“上下文顺序变了”“某段工具返回内容变了”还是“新的系统提示词里出现了冲突指令”。这种回放能力是Loop Engineering的基石没有了它你改多少轮都是盲改。4.2 用评估集守住回归底线做循环工程师最怕的是这个改好了、那个改坏了。我建了一个只有12个case的小评估集覆盖了六种典型PRD正常文档、缺少验收标准的、超长文档、含复杂表格的、前后内容矛盾的、以及只有模糊描述一页纸的。评估脚本很朴素# eval.py import json from schema import ReviewResult, parse_review def evaluate(agent_func, cases): total 0 for case in cases: raw agent_func(case[doc]) try: result parse_review(raw) checks compare_to_golden(result, case[golden]) total checks except Exception: total - 10 # 格式不过关重罚 return total每次改完提示词或工具逻辑我就跑一遍这12个case记录总分。如果总分下降说明改动有回归风险立刻回滚如果某个case分数上升、其他没变说明改动有效。这套评估集成本很低但价值极高——它把“感觉变好了”变成了“量化指标变好了”。顺带说一个我在这个阶段容易犯的错误当我盯着某个case反复优化时其他case的分数明明降了我却选择性忽视。后来我养成了一个习惯评估结果必须记录在docs/迭代记录.md里只写“A涨了B降了”然后强迫自己对B的下降做解释。解释不清就回滚。4.3 常见问题与排查技巧实录把我在落地Loop Engineering过程中遇到的高频问题整理成了一张速查表适合贴在你的笔记本旁边现象根因解决手段输出字段名和类型飘忽不定缺少强Schema约束引入Pydantic/JSON Schema解析失败自动重试评分和评语互相矛盾提示词缺少评审锚点设置分段分值锚点并要求引用原文支撑超长文档丢失关键段落上下文长度导致注意力衰减分块摘要生成“文档地图”按需调用原文工具调用参数传错工具定义不够严谨定义参数类型、范围约束把异常回传模型自主纠错改了一个Case其他Case崩了没有做回归测试建立最小评估集每次迭代跑全量模型引用不存在的章节引用链路没有校验输出环节增加章节ID集合校验强制重生成模型偶尔答非所问上下文里混入了太多无关内容精简上下文把历史会话分段存储只取相关片段4.4 我的避坑心得最后说几条没有写在任何文档里的经验都是从踩过的坑里翻出来的。第一每轮循环只改一个变量。我吃过一次大亏有一轮同时改了提示词、工具定义和分块逻辑结果效果提升了。我以为三个改动都有效隔了两天又想回滚其中的“工具定义改动”却发现效果连带下降根本分不清是谁的功劳。后来我强制要求自己Build阶段只动一个地方改完必须记录“本次期望的变化是什么”Run完了对照日志核对。第二把“观察”看得比“修改”更重要。很多人拿到一个表现不满意的Agent第一反应是改提示词。但绝大多数问题根源在上下文缺失、工具定义混乱、或者评估标准不一致。我统计过自己40轮迭代里的改动类型其中纯提示词优化的只有不到三分之一其余都在调整上下文结构、工具调用和评估逻辑。第三保存每一轮版本哪怕只差一个逗号。我的做法是每轮迭代前打一个Git tag格式是loop-v036。这样当某轮改动“感觉有点不对劲”时可以随时把代码回滚到任意历史状态再对照日志看差异。第四接受Agent“养出来”而不是“写出来”的。这个心态转变至关重要。第一次做Agents的人普遍会焦虑“怎么第一版这么蠢是不是我提示词写错了”其实第一版蠢是常态。只要循环在转每一轮都有日志、有评估、有改进方向你最终一定会得到一个可靠的工具。真正可怕的不是它一开始蠢而是你没有任何机制让它变聪明。这是我在整个Loop Engineering实践中体会最深的一点这个方法论并没有给我什么魔法它只是把Agent开发从“赌一把”变成了“走一步看一步看清楚再走下一步”。如果你手头正好有个Agent项目卡在“感觉不稳定、不知道为什么”别急着堆提示词先搭好日志和评估跑一轮看看你会有完全不一样的判断。