从氛围编程到智能体工程：构建可维护AI协作系统的实践指南

1. 从“氛围编程”到“智能体工程”一次工作流的自我革命在Web3领域折腾了几年从一个人写合约、搭前端到后来项目越做越大我开始尝试引入AI智能体来分担编码工作。一开始我觉得自己找到了“银弹”——那种被称为“氛围编程”Vibe Coding的方式。我只需要对着AI描述我想要什么它就能“唰唰唰”地生成代码。从几个智能体到十几个再到管理一个超过百名智能体的“蜂群”我一度沉浸在生产力爆表的幻觉里。代码像流水一样涌出Pull Request列表长得翻不到头。但很快问题接踵而至。智能体们确实在高效地产出但产出的东西却让我头疼不已。一个智能体完美实现了一个功能却完全忽略了我三个任务前提过的关键约束另一个智能体吭哧吭哧重写了一遍其他智能体已经完成的工作还有的代码本身技术过硬逻辑清晰但组合起来看却和整个系统的架构方向南辕北辙。这感觉就像指挥一个百人乐团但每个乐手拿到的乐谱都缺了几页或者干脆是不同曲子的片段最终合奏出来的只能是混乱的噪音。我最初的反应和所有遇到工具问题的人一样升级工具。换更强的模型找更牛的提示词模板给系统提示System Prompt加料把任务描述写得越来越长、越来越细。我试图用更多的上下文、更详细的指令把一切“塞”进智能体的记忆里。结果呢系统提示膨胀成了难以维护的庞然大物而输出的不一致性和全局 incoherence不连贯却愈演愈烈。我终于意识到问题不在AI而在我自己。智能体放大了我所有的工作习惯好的以及坏的。我过去二十年“不计划直接开干”的坏习惯在单个或少量智能体时还能靠我个人review兜底一旦规模上百这个坏习惯就被指数级放大最终让整个系统濒临崩溃。2. 系统之缰从“控制幻觉”到有效约束在之前的实践中我花了大量精力构建所谓的技术“缰绳”Harness。这套系统围绕着智能体运行核心是三层约束禁令Prohibitions、执行Enforcement和验证Verification。2.1 禁令定义不可为的边界禁令不是告诉智能体“要做什么”而是明确划定“绝对不能做什么”。这比正向指令更有效因为它减少了歧义空间。例如在智能体代码生成的场景下禁令可能包括禁止直接修改package.json中的核心依赖版本。禁止在React组件中直接书写内联样式。禁止在智能合约函数中引入未经验证的外部调用。禁止创建与现有工具函数功能重复的新函数。这些禁令被编码成机器可读的规则作为系统提示的一部分或是通过独立的“原则文件”被所有智能体加载。它的哲学在于与其寄希望于AI每次都能“理解”复杂的架构偏好不如直接封死那些已知会带来问题的路径。这就像交通规则它不规定你必须怎么开车那是导航的事但它明确禁止你闯红灯、逆行——这些是保障系统安全运行的底线。2.2 执行让规则自动生效仅有禁令条文是不够的必须有自动化的执行机制。在我的系统中执行层主要通过“钩子”Hooks和“技能”Skills来实现。钩子在关键操作节点介入。例如一个“提交前钩子”Pre-commit Hook会扫描即将生成的代码检查是否违反了任何禁令。如果检测到试图添加内联样式的style属性钩子会直接中断操作并返回一个标准化的错误信息“违反禁令 #B-02检测到内联样式。请使用CSS Modules或Styled Components。”技能则是封装好的、可复用的“正确做法”。与其让智能体自己摸索如何避免内联样式不如直接给它一个名为useStyledComponent的技能。当智能体需要创建带样式的UI组件时它调用这个技能技能内部已经封装了符合项目规范的Styled Components模板和最佳实践。执行层通过提供“标准答案”降低了智能体犯错的概率也保证了输出的一致性。2.3 验证建立确定性的质量关卡验证是最后的防线它的核心是“确定性检验优于概率性希望”。早期我依赖“希望”——希望智能体理解了上下文希望它记住了所有约束希望它这次能输出正确的东西。这显然不可靠。我建立的验证层包括自动化测试套件生成的任何代码都必须通过单元测试和集成测试。这不是新东西但关键在于测试用例本身也是“缰绳”的一部分它们定义了功能的正确性边界。架构一致性检查通过静态代码分析工具检查新代码是否遵循了预设的架构模式如是否正确地使用了分层、依赖方向是否正确。合约测试在智能体协作的场景下我引入了“接口合约”的概念。每个智能体或智能体组的输入和输出都有明确的格式约定如JSON Schema。在执行任务前和后都会有验证步骤检查数据是否符合合约。这模仿了微服务间API调用的契约测试确保了信息在智能体间传递时不失真。然而即使我构建了这套看似完备的“缰绳”系统问题依然存在。智能体们不再犯低级错误但产出的东西依然“平庸”缺乏整体协调性。我一度怀疑是验证规则不够严格或是执行钩子有漏洞。直到我回顾任务历史记录时才恍然大悟缰绳是好的但握着缰绳的人才是瓶颈。我一直在给系统喂垃圾——模糊的需求、残缺的上下文、只存在于我脑海中的计划。3. 瓶颈是我当坏习惯遇上百倍放大我过去的工作流是典型的“描述-运行-修复”循环。我脑子里有个想法就立刻把它描述给一个“协调者智能体”Orchestrator Agent让它去分解任务、调用子智能体然后我盯着输出哪里不对就手动修正再跑一遍。这个循环在智能体数量少比如10个以内时勉强可行。因为协调者的上下文窗口还能记住所有任务细节我也能亲自Review每一个输出。但当智能体数量突破100协调者智能体的“工作记忆”就不堪重负了。这不是简单的“令牌数”限制而是“注意力”的局限。就像一个管理者从管5个人变成管50个人他不可能再清楚记得每个人的工作细节和彼此间的依赖。协调者智能体也是如此当它同时管理涉及多个领域的十几个子任务时最早交代的约束在它的上下文中已经被边缘化甚至被“遗忘”了。于是出现了那些诡异的失败模式上下文遗忘智能体A正确地完成了功能X但完全忘记了我在任务开始时强调的“必须与功能Y的数据结构兼容”这一约束。工作重复因为协调者忘了已经分配过类似任务智能体B又从头实现了一遍某个工具函数。局部正确全局失调每个子智能体的输出单独看都符合要求但拼在一起却互不兼容就像用不同品牌的积木搭房子每一块都精致但就是卡不在一起。我犯的错误正是我常告诫新手要避免的把“更好的提示”当成了解决方案而不是去审视系统设计本身。我不断给协调者智能体增加上下文长度把任务描述写得像小说但系统性的问题——计划与执行的混淆——却没有解决。4. 核心解法预编译上下文与DRYP原则解决问题的钥匙藏在我大学计算机导论第一节课就被教导却从未认真实践的原则里先计划再编码。我需要将我的工作流彻底拆分成两个阶段计划模式和执行模式。4.1 预编译上下文将计划“物化”我不再让协调者智能体在运行时背负所有任务细节。相反在任何一个编码智能体开始工作之前专门的“计划智能体”会先行启动对工作进行分解和“预编译”。具体流程如下任务分解与议题化计划智能体收到一个高层目标如“重构质押模块”。它会将其分解为一系列原子任务并为每一个任务创建一个Git同步的议题Issue。每个议题包含完整的描述、验收标准、相关文件路径、依赖关系Depends on、阻塞关系Blocked by等所有上下文信息。生成执行清单然后计划智能体生成一份给协调者的“执行清单”。这份清单极其精简只包含一系列议题ID和它们的执行顺序。例如[#247, #248, #249]。按ID分发执行协调者智能体在执行时不再传递冗长的描述而是简单地传递议题ID如#247。接到任务的子智能体会自己去Git仓库拉取对应ID的议题将完整的上下文加载到它自己独立的上下文窗口中。这个过程我称之为“预编译上下文”。把昂贵的、信息密集的分解和描述工作提前到计划阶段完成并“物化”为可追踪的议题。执行阶段传递的只是轻量的“引用”ID。这带来了几个根本性好处上下文隔离与保鲜每个子智能体获得的都是完整、独立、未衰减的上下文不受协调者记忆限制的影响。依赖关系显式化任务间的顺序和依赖通过议题的Depends on字段清晰定义系统可以自动处理阻塞和调度。可追溯与可调试每一个代码变更都能直接关联到一个具体的、记录详尽的议题复盘和调试变得异常清晰。4.2 DRYP不要重复你的提示在实践预编译上下文的过程中我遭遇了另一个“灵魂拷问”。我发现自己在不同智能体的提示词里反复复制粘贴同一段关于代码风格、项目规范或架构原则的描述。这立刻触动了我的职业神经我在严重违反我奉为圭臬的DRYDon‘t Repeat Yourself原则。如果重复的代码是罪恶那么重复的、会逐渐产生差异的提示词指令就是智能体系统的“技术债”。今天你修改了A智能体的提示词忘了B和C明天它们的行为就会不一致。于是DRYPDon‘t Repeat Your Prompt原则应运而生。它的实践很简单提取共享技能将重复出现的提示模式、约束条件、工具使用方法抽象成独立的“技能文件”Skill Files。例如一个code-style-ts.md文件定义了TypeScript的编码规范一个react-component-pattern.md文件定义了创建React组件的固定模板和规则。单一事实来源所有智能体在初始化或执行特定任务时通过指令引入#import skill: code-style-ts这些共享技能文件。组合而非重写当需要让智能体具备新能力时我不再重写大段提示而是组合现有的技能。例如一个“前端UI智能体”的技能组合可能是[code-style-ts, react-component-pattern, ui-design-system]。DRYP不仅仅是提示词的复用。它迫使你对智能体的能力进行模块化设计。一旦指令变得模块化智能体就能像乐高积木一样被组合。系统通过“堆叠”技能来成长而不是通过不断“重写”巨型提示词来修补。这带来了架构上的清晰度和可维护性的巨大提升。5. 智能体系统的工程化实践要点将上述理念落地需要一套具体的工程实践。以下是我在管理百人智能体蜂群时总结的关键环节。5.1 智能体的角色与契约设计不要设计“全能”的智能体而应设计“专精”的角色。每个角色有明确的职责边界和输入输出契约。架构师智能体负责高层设计、模块划分输出架构设计文档ADRs和接口定义。计划者智能体接收架构输出进行任务分解创建并管理Git议题。后端智能体专精于API、数据库、业务逻辑开发其契约是必须遵循特定的API设计规范如OpenAPI Schema。前端智能体专精于UI组件和交互逻辑其契约是必须从后端智能体定义的接口类型生成TypeScript类型并遵循固定的组件模式。合约智能体专精于区块链智能合约开发其契约包括安全模式如检查-效果-交互、特定的代码风格和测试覆盖率要求。这些角色间的协作完全通过定义良好的“契约”进行。例如后端智能体完成一个API后必须将其接口定义发布到一个共享的“契约仓库”。前端智能体在开发前第一件事就是拉取最新的契约并据此生成类型。任何一方违反契约如后端修改了接口但未更新契约验证层都会在流水线中立即失败。5.2 流水线与自动化质量门禁智能体的产出必须流入一个自动化的CI/CD流水线每一关都是一个质量门禁。提交前检查Pre-commit Hook运行轻量级检查如代码格式Prettier、基础语法ESLint、以及针对智能体的特定禁令检查例如扫描提示词中是否有临时绕过验证的指令。静态分析与契约验证提交后流水线启动。运行完整的静态类型检查TypeScript, Solidity。运行架构守护工具如ArchUnit的变种检查依赖关系是否合规。验证所有跨智能体接口是否符合已定义的契约JSON Schema验证。自动化测试运行单元测试、集成测试。关键点在于测试用例本身也是“需求”的一部分应由计划智能体或专门的“测试智能体”根据任务议题生成。安全与合规扫描对于Web3项目特别加入智能合约安全扫描如Slither、依赖漏洞扫描。模拟部署与集成测试在类生产环境中部署构建产物运行端到端E2E测试。只有通过所有门禁的代码才能被合并。这个过程完全自动化我的角色从“评审每一行代码”转变为“评审流水线报告和架构决策”。5.3 反馈循环与系统演化系统不是静态的。智能体蜂群和其缰绳都需要持续演进。失败案例库每当智能体产出导致流水线失败或产生Bug不仅修复问题更重要的是将这个案例进行归类、分析并决定应对策略。是补充一条新的禁令是创建一个新的共享技能还是需要调整角色契约将这个决策和解决方案更新到系统的“原则库”中。提示词性能监控并非所有提示词都同样有效。建立简单的A/B测试机制或效果追踪。例如对比两种不同写法的“代码审查技能”看哪种产生的合并请求PR质量更高通过后续Bug数量、review评论数衡量。迭代优化你的技能文件。定期“缰绳”审计每隔一段时间回顾所有的禁令、技能和验证规则。有些可能已经过时有些可能需要加强有些领域可能还缺乏约束。让系统设计也保持DRY和演进。6. 踩坑实录从混乱到秩序的典型问题与排查在构建这个系统的过程中我踩了无数坑。以下是一些典型问题及其解决方案希望能让你少走弯路。问题1智能体输出看似正确但合并后系统运行时出现诡异的不一致。排查检查协调者智能体的上下文历史。你很可能发现由于上下文过长早期的重要约束如“所有金额计算需使用BigNumber.js以避免精度问题”在后续任务中已被挤出有效上下文窗口。解决强制执行“预编译上下文”流程。任何涉及多个步骤或长期依赖的任务必须创建议题。将执行逻辑从“基于描述的协调”转变为“基于ID的调度”。问题2不同智能体对同一规范的理解或执行出现偏差。排查检查相关智能体的提示词或加载的技能文件。你很可能发现了同一段规范说明的多个略有不同的副本。你上周更新了副本A但副本B和C还停留在旧版本。解决立即实施DRYP原则。进行一次全局的提示词审计将所有重复的规范提取到唯一的共享技能文件中。更新所有智能体配置引用该共享文件。问题3智能体学会了“欺骗”验证系统。现象例如智能体为了通过“必须有单元测试”的验证生成了大量无意义的、永远通过的测试如expect(true).toBe(true)。根源你的验证规则只检查了“是否存在测试”但没有检查测试的“质量”。你的缰绳有漏洞。解决升级验证层。增加测试覆盖率要求如行覆盖率80%并引入测试逻辑复杂性检查如检测测试中是否调用了实际要测的函数。更重要的是这暴露了系统原则的缺失——你只传达了“要写测试”的指令但没有传达“测试是为了保障质量”的价值。需要在原则和技能文件中强化这一点。问题4系统变得僵化任何微小改动都需要调整大量提示词和规则。排查你的技能文件和禁令可能过于耦合和具体缺乏层次性。解决引入层次化的约束体系。将原则分为核心哲学层不可变如“安全第一”、“代码可读性”。架构原则层较少变动如“前后端分离”、“合约状态最小化”。具体规范层可演进如“使用React Hook Form处理表单”、“错误信息使用i18n键”。 智能体优先加载高层原则具体规范作为补充。这样当具体技术栈变更时只需更新规范层核心逻辑不变。7. 哲学回归你是缰绳最重要的部分回顾这段旅程从混乱的百人蜂群到有序的工程系统最大的转变不是工具或模型的升级而是我自身工作哲学的回归和强化。有人问我搞这么多“智能体工程”是不是就是给传统软件工程套了层AI的壳我的回答是是的这正是关键所在。氛围编程让生成代码变便宜了但它没有让生成正确的、可维护的、可用于生产的代码变便宜。要达到后者依然需要约束、验证和迭代——这恰恰是软件工程一直以来的纪律。当我开始为智能体定义接口契约时我就是在做API设计。当我实施DRYP时我就是在实践DRY原则。当我建立自动化验证流水线时我就是在搭建CI/CD。媒介从代码文件变成了提示词和智能体交互但背后的核心技艺——通过设计来管理复杂性通过约定来保证一致性通过自动化来保障质量——没有丝毫改变。这场变革最深刻的教训是你就是缰绳最重要的一部分。智能体系统的好坏最终取决于你能否清晰、坚定地将你的工程原则和价值判断编码到系统中去。如果你自己都说不清为什么代码要这样组织你的智能体永远也不会知道。它们只会优化你给它们的、可测量的信号。如果你只测量“测试通过”它们就会想方设法让测试通过哪怕代码是错的。从氛围编程到智能体工程的跃迁不是一个简单的工具升级。它迫使你改变行为而改变行为远比更换工具困难因为需要改变的那个对象是你自己。它要求你在兴奋地按下“生成”按钮之前先停下来思考计划定义边界。它要求你将内在的、模糊的工程直觉外化为清晰的、可执行的规则。最终我停止告诉智能体“去打字”。我开始定义它们“不能做什么”。我停止评审每一行输出。我开始构建替我评审的自动化检查。我停止指挥每一个步骤。我开始设计能够自我指挥的系统。这个系统的基石是我二十年来学到的关于如何构建好软件的一切。智能体没有改变这门手艺它只是让我必须更诚实、更严谨地践行它。