企业官网建设流程全解析

我把这个标题拆开看，核心就两个词：Context Engineering 和 Agent Harness。这两个概念几乎决定了一类团队用AI编码代理是"玩具级体验"还是"生产力工具级体验"。过去一年多，我前后试了好几轮AI编码工具，从最早的代码补全，到后来能自动改文件、跑测试的编码代理。第一周都觉得"这东西要逆天"，等到第四周再看产出曲线，又被打回原形。真正让效率从"感觉有用"变成"指标可查"的，不是换了更强的模型，而是把下面这两件事做扎实了。

先说结论：想让AI编码代理稳定地产出，靠的不是更长的提示词，也不是更大的上下文窗口，而是两套工程体系——一套决定"模型看得准不准"的上下文工程，一套决定"代理跑得稳不稳"的运行框架。这篇文章没有玄学，只有一条我实际跑过、验证过的落地清单。适合那些已经用上AI辅助编码、但边际效益明显下降的团队，也适合准备从"人写代码机器补全"升级为"人定任务代理执行"的开发者。

1. 为什么多数团队的AI编码效率卡在30%，而不是10x

我不止一次看到这样的场景：团队接入AI编码代理，配好模型、写好规则、信心满满。一个月后复盘，PR数量没涨多少，reviewer反而更累了。问题通常不在模型能力，而在三个结构性缺口。

1.1 三个卡点：记不住、看不见、没人管

记不住。代理拿到一个仓库的时候，它不可能像人一样先花两周通读项目。大多数工具默认只会把当前打开的文件或最近的diff喂给模型，于是模型对全局的判断经常是错的：它不知道这个项目有统一的异常处理基类，不知道某些模块不能引入某个依赖，不知道现有代码风格的隐含约定。这些"知道"，人靠的是经验，代理靠的是喂进去的上下文。你没喂，它就胡来。

看不见。即使代理记住了规则，它也不知道任务边界在哪里。我曾经在一个模拟重构项目里看到过典型崩溃现场：让代理重构老订单模块里的一个函数，它看到这个函数只有三处直接引用，放心地改了内部实现，结果这个函数被一个脚本以反射方式调用，改了签名之后线上直接报错。没有人告诉代理"先全仓库扫描引用来源再动手"，因为它"看不见"那个脚本。

没人管。代理跑起来之后，人工介入的触发点设计得极不合理。要么是完全没人在关键操作前把关，代理直接改核心配置；要么是每一步都要人点确认，把人活生生变成鼠标管理员。前者风险失控，后者效率归零。这不是代理的错，是工作流没设计好——缺少一个像样的Agent Harness。

1.2 反直觉事实：Token窗口再大，也不等于理解

很多团队迷信长上下文模型，认为把整个仓库塞进去就能解决一切。实践很快打脸：上下文窗口增大之后，信息熵也在增大。模型要在十万行代码里筛出"哪些和本次任务相关"，和让一个实习生在没有目录导读的情况下通读整套代码再动手，难度是一样的——绝大多数信息都是噪声。

这里我想给一个直白类比：上下文窗口就像一张办公桌，窗口再大，桌上东西越多，你要找的那张图纸照样被埋在最下面。代码补全时代，我们只需要在桌上放一个文件；代理时代，我们得学会主动往桌上放什么、不放什么。这个"桌面管理"就是上下文工程的本质。

1.3 把"代理"当"补全工具"用，效率永远上不去

还有一大部分团队对AI编码的使用停留在"聊天式补全"：人打开某个文件，让模型填空，然后人再黏贴回去。这种做法提升肯定有，但不会有质变。代理和补全工具的本质区别在于：代理拥有工具、能连续执行、能自我验证。只有当它拥有"读文件—搜代码—改代码—跑测试—迭代"的完整闭环时，人才能真正从流程里退出来，专注于任务定义和结果验收。而这个闭环，正是Agent Harness要解决的问题。

先把话放在这：如果今天你还在用AI编码代理做"高级自动补全"，后面讲的东西对你价值不大；如果你想让代理真的独立完成一个小任务、自己跑测试、自己拿结果回来，下面的内容可以直接照着做。

2. Context Engineering：让模型在正确的时间只看到正确的信息

上下文工程这个概念，我把它定义为：设计并维护进入模型上下文窗口的所有信息及其注入时机。它跟Prompt Engineering最大的区别是——提示词工程在"话术"层面下功夫，上下文工程在"信息体系"层面下功夫。前者是让模型听得懂，后者是让模型看到的东西恰好够用。

2.1 五段式上下文配方

我实践下来，一份稳定好用的上下文配方，应该分成五块，每块职责清晰：

• 系统规则：仓库级硬约束。比如"禁止在Service层直接操作数据库""所有对外接口必须写OpenAPI注释""代码基于Java 17"。这部分是正确性的底线，值得用最精确的语言写死。
• 仓库地图：一棵带注释的目录树，标注每个目录的职责、模块间依赖关系、关键入口文件。目的只有一个：让代理在动手之前知道自己在哪、影响面可能波及哪里。
• 任务切片：本次要解决的最小问题描述，必须包含验收标准。模糊描述是大忌，比如"提升可维护性"这种话喂进去，代理就会开始自由发挥。
• 工作内存：代理在执行过程中产生的中间结论。比如"确认了配置中心地址，决定采用方案B，遍历了三处调用点均无反射引用"。这相当于代理的临时记事本，下个循环接着用。
• 输出契约：期望产物的具体格式。比如"改动仅限两个文件，必须附带单元测试，diff不超过200行"。契约越清晰，代理的发散空间越小。

五块合在一起，才是完整的任务上下文。只喂前两块，等于让代理"了解规则但不知道干什么"；只喂中间三块，等于"知道干什么但随时踩坑"。

2.2 一份可抄的Token预算分配

我做过比较稳定的配方，在约70k-90k Token的上下文里是这样分配的：

如果上下文特别紧张，我会优先压缩"历史对话摘要"和"仓库地图"，但绝不压缩"系统规则"和"任务切片"。原因很简单：历史是过去式，新任务可以重新探索；规则和目标是方向，方向错了跑得越快偏得越远。

2.3 让配方文件可被工具读取

不同编码代理读取配方文件的方式不太一样，但逻辑大同小异。我习惯把配方写成结构化文件，方便工具解析。下面是示意结构：

{ "recipe": { "system_rules": "禁止在Service层直接操作数据库；Java版本17；所有对外接口必须有OpenAPI注释", "repo_map": { "order-service/src/main/java/com/example/order/": "订单核心逻辑，含状态机与价格计算", "order-service/src/main/java/com/example/order/config/": "配置类，禁止业务改动" }, "task_slice": "将OrderService中的状态机分支提取为独立枚举，增加分支覆盖测试，验收标准为所有测试通过且PR不超300行", "working_memory": [], "output_contract": { "files_to_change": ["OrderService.java", "OrderStatus.java"], "tests_required": true } } }

这个文件在任务启动时注入，代理每完成一个子步骤，工作内存会更新一次。对我来说，配方文件本身就是团队资产——新人来了看一遍配方，就能理解这个仓库的边界和开发约束。

2.4 上下文污染的代价

上下文工程里最容易被低估的是"污染"。我踩过一次很深的坑：一个任务处理完之后，下一轮任务没有清理工作内存，结果代理把它上一轮废弃的方案带进了新任务，差点引入一个根本不存在的依赖。人会被昨天会议上的结论带偏，代理也一样。所以，每个任务是干净启动还是连续对话，必须做成显式决策，不能默认让历史残留。

判断标准很简单：如果两个任务在代码上有接触面，用连续对话可以省去重复探索；如果任务完全独立，一定要干净隔离。我的默认选择是隔离，宁可让代理多花两分钟重新读文件，也不要让它带着旧任务的信息污染新任务。

3. Agent Harness：把编码代理从"玩具"变成"生产力工具"的骨架

如果说上下文工程是给模型配一副合适的眼镜，那Agent Harness就是给代理戴上一套受约束的肢体和工具带。它决定了代理能做什么、不能做什么、做到什么程度必须停下来问人。

3.1 Harness的本质：约束与使能的平衡

很多团队第一次跑代理，什么限制都不设，让代理自由发挥。结果就是它开始兴致勃勃地重写无关模块、在配置文件里加了一堆莫名其妙的参数、改完还不跑测试。这不是模型智障，是运行框架缺位。

一个合格的Harness要同时做到两件事：给代理足够的能力，让它能独立完成复杂任务；同时给它足够的约束，确保每一次操作都可控、可回滚、可追溯。没有约束的代理是失控的实习生，约束过多的代理是提线木偶。平衡点就藏在下面几个组件里。

3.2 五个核心组件，一个都不能少

我把一个可用的Harness拆成五层，缺一层就会出问题：

3.3 工具调用的质量藏在描述里

这一条特别容易被忽略。工具是代理的手，工具描述是大脑对这只手的认知模型。描述写得不清楚，代理就会反复试错。

我见过一个队伍的agent工具列表里写着"search_code - 搜索代码"。模型遇到"找出所有未处理异常的地方"这种任务时，不知道search_code是基于AST还是字符串匹配，也不知道能不能跨文件查引用，于是就会笨拙地反复试。另一组把同样的工具改成了"search_code - 基于AST精准检索符号定义与引用，支持跨文件查询，用于确认改动影响范围"，调用成功率和任务完成速度明显提升。

工具描述值得花时间精修，因为它直接决定了代理选择工具的成本和准确度。工具不是越多个越好，五到八个足够，每个都写清楚"什么时候用、能返回什么、不能做什么"。

3.4 最小Harness配置示意

我用一个简单配置来说明结构，不同工具语法有差异，但思路通用：

toolset: - read_file - write_file - search_code - run_tests - create_pr permissions: read_file: allow search_code: allow run_tests: allow write_file: require_human_approval create_pr: require_human_approval loop_control: max_iterations: 8 timeout_seconds: 600 observability: log_commands: true log_diff: true

这套配置的意思是：代理可以自由地读文件、搜代码、跑测试；但写文件和创建PR之前必须停下来等人确认。这既保留了代理的探索自由度，又在关键有风险的动作上加了人工闸门。我见过很多团队连"写文件要审批"都没设，结果代理在半小时内改了十几个文件，reviewer完全不知道从哪里看起。

3.5 断点续跑：代理也需要"失败恢复"

代理跑着跑着，很可能一次任务做到一半就达到迭代上限了。如果没有断点续跑机制，它就得从头再来，前面几轮的工作内存全部浪费。这就像人写代码写到一半电脑重启，还没保存。

好的Harness会把每一步操作落盘，包括产生过的中间结论、尝试过的方案、失败原因。这样即使中途停了，下一轮启动时也可以把工作内存恢复出来，接着往下跑。这个特性在复杂重构任务里能把成功率提升一大截。我建议选型的时候把这个当作硬指标，而不是锦上添花。

4. 从仓库审计到每日循环：一条可以抄走的落地清单

理论讲再多，不如给一条能够直接执行的路径。下面这套流程，是按"第一周-每日循环-验收标准"三个层次展开的。照着做，至少能让你两周内看到可量化的变化。

4.1 第一周：仓库审计与规则沉淀

第一周的目标不是"让代理写很多代码"，而是"让代理在一小块试验田里成功跑通一个任务"。具体动作如下：

1. 画模块边界。花半天时间把仓库按模块列出来，标注每个目录的职责和依赖方向。这一步产出仓库地图。
2. 收集隐式规则。把团队里"人尽皆知但文档没写"的约束整理出来。比如"这个模块的日志必须走统一格式""此处不能用某个公共组件""数据库操作必须在Repository层"。这些是代理最容易踩死坑的地方。
3. 挑选第一个试点任务。标准是：新功能模块、无历史包袱、影响范围小、验收标准清晰。
4. 建基线指标。记录当前的平均PR周期、一次通过率、评审修改率。没有基线，后面就无法证明效率提升。

如果一周过去了代理还是没能在你仓库里跑通一个像样任务，不要怀疑模型，回头检查规则文件和任务切片——大概率是某个关键约束没写进去，或者任务切得太大了。

4.2 任务的切片标准：一个可验证的最小闭环

切任务是整个流程里最难练的手感。好的切片长这样："将OrderService中的状态机分支提取为独立枚举，补充分支覆盖测试，改动范围限于order-service内，所有测试通过，PR不超过300行。"

坏的切片长这样："重构订单模块，提升可维护性。"

差别很明显：好的切片同时满足单一目标、产出可验证、影响范围明确、依赖尽量少四个条件。坏切片四个全不满足。要让AI编码代理稳定产出，人的核心工作就是把模糊的大目标切成可以喂给代理的小任务。这个能力和传统开发里的任务拆解没有本质区别，只是对象从人换成了模型。

4.3 每日循环怎么运转

我常用的一个节奏是这样：

• 09:00 花30分钟切当天的任务、更新配方文件、清理工作内存
• 09:30 启动代理跑第一批任务，人同时去做代码评审或方案设计
• 12:00 检查第一批diff，有偏差就补充上下文，重新切片
• 14:00 对失败任务做归因：是规则没写清，还是任务太大，还是工具权限不够
• 17:00 汇总当天的PR、测试结果、代理日志，顺手更新仓库地图

这个节奏里有一个关键动作：每天必须做失败任务的归因分析。不是"今天就到这吧"就完了，而是弄清楚代理为什么失败。规则问题改规则，切片问题改切片，工具问题改工具描述。归因越细，后面跑得越顺。

4.4 定义"完成"：测试是硬性完成条件

我给代理下的所有任务，完成定义里永远有一条：必须提供测试日志、编译输出或静态检查结果，并明确说明改动涉及的文件清单。代理说"我认为没问题"不算完成，必须有证据。

这一步是Agent Harness和玩具之间的分水岭。代码补全工具只负责给参考代码，质量由人兜底；代理要承担更多独立执行的职责，验证责任就得靠测试和构建工具来兜底。如果代理交付的代码没有对应测试和验证，等于把风险全部转嫁给了reviewer。设置完成定义后，review工作量反而能降下来。

5. 实测复盘：效率翻倍的真实数据与三个隐蔽陷阱

我在一个内部代号为"迁移重构"的模拟项目上完整跑过这套流程，前后对比了4周，数据如下：

数据不是魔术，原因是人机分工发生了根本变化：代理负责找引用、改签名、跑测试、补文档，人负责定义任务、验收质量、处理模糊地带。但过程中我也踩了不少坑，挑三个最隐蔽的说。

5.1 陷阱一：上下文污染让"昨日成功"变成"今日事故"

前面提过，某次连续多任务跑下来，我没有清工作内存，代理把上一个任务里弃用的方案带进新任务，甚至为此引了一个旧版本的依赖。更麻烦的是，它在新任务中自信地复用了旧结论，看起来逻辑自洽，实际上根基已经错了。

修复很简单：任务之间隔离工作内存，每个新任务强制重新整理配方。尤其当两个任务分属不同模块时，隔离能避免大量隐性错误。从那之后，我再没因为历史残留踩过同款坑。

5.2 陷阱二：代理的"自信错误"比显式失败更难发现

显式失败不可怕，测试跑挂、编译报错都是好事。可怕的是代理交付了一段看起来很合理的代码，但完全没有测试覆盖，而reviewer在diff里很难发现缺失的边界情况。

应对办法还是完成定义：要求代理在提出改动的同时提交测试证据。如果某个改动无法自动测试，必须在输出契约里写明人工验证步骤。这个习惯养成后，"看起来合理"的代码比例大幅下降，因为代理知道最终交付需要验证，而不是只有代码本身。

5.3 陷阱三：过度工程化的Harness导致没人用

第一版Harness我做得太重：权限分成四级、每一步操作都要录屏、要求所有代理行为必须出具报告。结果团队用了一周就放弃了，因为准备环境和走审批流程的时间比人直接写代码还要长。后来我重新来过，先用最小闭环——读、搜、改、测、PR五件套，加写操作审批——跑通之后，再逐步加观测和沙箱。记住：Harness是给效率服务的，不是给流程服务的。一开始追求完美框架，大概率会死在没人用。

5.4 10x的真正来源：人机分工的设计

最后想聊一句关于"10x"的看法。我不认为AI编码代理会让一个人突然拥有十倍产出，但它在合适的任务切片和运行框架下，确实能把"找引用、改签名、跑测试、查日志"这类体力活几乎全部自动化。当人在流程里只剩下任务定义和结果验收时，单位时间能产出的有效代码量会大幅上升——这才是"10x革命"真正的意思，不是模型更强了，而是人的精力分配更合理了。

我在实际操作中体会最深的一点是：每周五下午固定花30分钟重新审视一遍上下文配方文件，比每天调提示词有用得多。模型在升级，工具在换代，仓库在膨胀，但"先定义好模型能看到什么，再放开代理能做什么"这个顺序，才是AI编码代理拉开效率差距的真正分水岭。