智能体编程的上下文工程：从Mise en Place哲学到高效AI编码实践

1. 从厨房到代码：为什么“备料”是智能体编程的第一性原理

如果你在厨房里待过，或者看过任何一档像样的烹饪节目，一定会对一个词印象深刻：Mise en Place。这是一个法语词，直译过来是“各就各位”，在烹饪界，它指的是一种工作哲学——在真正开火烹饪之前，把所有食材洗净、切配、称量好，分门别类地放在小碗里，工具也摆放就绪。厨师只需专注于烹饪本身，而无需在油锅冒烟时手忙脚乱地去找一颗蒜。

听起来很基础，对吧？但正是这个基础，区分了专业厨房的井然有序和家庭厨房的兵荒马乱。现在，让我们把这个概念平移到另一个看似毫不相干的领域：智能体编程。当我们在谈论让AI智能体去编写、调试、重构代码时，我们是否也陷入了“油锅冒烟才找蒜”的混乱？答案是，绝大多数时候，是的。

“Mise en Place for Agentic Coding”这个标题，正是将这种厨房里的“备料”哲学，提炼为一种严谨的上下文工程方法论。它不是在讲某个具体的AI模型或代码生成工具，而是在讲一个更底层、更决定成败的环节：我们如何为智能体准备“上下文”？这就像是为一位顶级厨师准备一个完美的备料台。你给智能体的上下文，就是它的“工作台”。台面是杂乱无章、堆满未处理的原始食材，还是井井有条、分门别类、随时可取的半成品，将直接决定它产出的“菜肴”（即代码）的质量、效率和可靠性。

这篇文章，就是写给那些已经尝过AI编码甜头，但也饱受其“幻觉”、上下文溢出、指令漂移之苦的开发者、技术负责人和AI应用架构师的。我们将深入拆解，为什么“有意识的准备”不是可选项，而是智能体编码时代的必选项。我会结合大量一线实战中的踩坑经验，告诉你如何系统性地构建你的“智能体备料台”，把看似玄学的“提示工程”，变成一套可重复、可评估、可优化的工程化流程。

2. 智能体编码的“油锅困境”：为什么上下文准备如此关键

在深入方法论之前，我们必须先理解我们面临的核心挑战。直接给智能体（比如ChatGPT、Claude、Cursor等）丢一个模糊的需求，然后指望它吐出完美的代码，这就像让一位厨师在堆满带泥土豆和整只鸡的台面上，30分钟内做出一道法式炖鸡——结果要么是灾难，要么厨师（智能体）会用自己的“想象力”（幻觉）来填补空白，比如用番茄酱代替红酒，因为你没告诉它需要红酒，而它“觉得”番茄酱可能也行。

2.1 智能体的“工作记忆”局限性

当前的AI编码智能体，无论其底层模型多么强大，都有一个无法回避的物理限制：上下文窗口。你可以把它想象成厨师工作台的面积。面积再大，也是有限的。当你在对话中不断追加需求、发送文件、进行调试时，这个“台面”很快就会被占满。更糟糕的是，模型对于长上下文中不同位置信息的“注意力”是不均匀的。早期的、中间的关键信息可能会被“遗忘”或稀释。

注意：这里说的“遗忘”不是真的丢失，而是指在模型生成下一个词时，那些信息对决策的影响权重降低了。这会导致智能体前后行为不一致，即“指令漂移”。

我曾在一个微服务重构项目中，让智能体基于一个复杂的领域模型接口生成实现类。一开始我提供了清晰的接口定义和业务规则。但在十几轮来回调试和优化后，智能体突然开始生成与最初业务规则相悖的代码。回溯上下文发现，最初的规则描述已经被淹没在大量调试日志和代码片段中，智能体的“注意力”已经完全被最近的错误信息所吸引。

2.2 “垃圾进，垃圾出”的放大效应

在传统编程中，一个模糊的需求可能导致开发者产出有偏差的代码，但开发者的人类常识和经验会起到一定的纠偏作用。然而，智能体极度依赖你输入的上下文质量。你给的上下文如果模糊、矛盾、信息不全（“垃圾进”），那么智能体不仅会产出有问题的代码（“垃圾出”），还会以一种极其自信且逻辑自洽的方式呈现出来，极具迷惑性。

例如，你只说：“写一个用户登录函数。” 智能体可能会生成一个仅验证用户名密码的简单函数。但你的真实上下文可能包括：需要集成OAuth 2.0、需要记录安全日志、需要防范暴力破解、需要返回特定的JWT令牌结构……这些缺失的“食材”，智能体不会主动去“市场”采购，它只会用台面上现有的东西（一个模糊的“登录”概念）来凑合。

2.3 调试成本的非线性增长

当智能体产出的代码基于一个糟糕的上下文时，调试会变得异常痛苦。因为你不仅要调试代码本身的语法或逻辑错误，更要先逆向工程出“智能体当时到底理解了什么”。这相当于你要先猜出厨师脑子里那个残缺的菜谱，才能知道为什么他往炖鸡里加了草莓。这种双重调试的认知负荷，常常比从头自己写代码还要高。

因此，“Mise en Place”的核心价值就在于：通过前置的、系统性的上下文准备，将智能体的“工作记忆”从存储和回忆原始、杂乱信息的负担中解放出来，让它100%的“算力”都聚焦于“烹饪”（即代码的推理、生成和组装）这一核心创造性任务上。这本质上是一种认知卸载，将人类擅长的规划、结构化、明确化工作，与AI擅长的模式匹配、代码生成工作，进行最优分工。

3. 构建你的“智能体备料台”：上下文工程的四大核心食材

理解了“为什么”，我们来看“怎么做”。一个专业的“智能体备料台”应该准备哪些“食材”？我将其归纳为四大类，它们共同构成了高质量上下文的基石。

3.1 食材一：清晰明确的任务规格说明书

这是你的“主菜食谱”。它必须超越自然语言的模糊描述，达到接近“机器可读”的精确度。

• 输入/输出契约：像写API文档一样明确。函数/模块的输入参数（名称、类型、约束、示例）、返回值（类型、结构、可能的状态）。例如，不只是“处理用户数据”，而是“输入：UserRegistrationForm对象（包含email, password, name字段，其中email需符合RFC 5322标准）；输出：ApiResponse对象，成功时包含userId和jwtToken，失败时包含errorCode和message。”
• 验收条件与边界案例：明确告诉智能体什么是“完成”。包括：
  • 正常流：主流程的成功场景。
  • 异常流：各种错误处理（网络超时、数据库连接失败、输入验证失败、权限不足等）。
  • 边界案例：空输入、极大/极小值、并发情况、数据一致性要求。
  • 非功能性需求：性能指标（如响应时间<100ms）、安全性要求（如密码必须加盐哈希）。
• “不要做什么”的负面清单：这往往比“要做什么”更重要。明确禁止的模式、已弃用的库、特定的实现方式（如“禁止使用eval()”，“避免全局变量”，“不要直接拼接SQL语句”）。

实操心得：我习惯用一个结构化的注释块来承载这些信息，直接作为给智能体的初始提示的一部分。这比在对话中零散描述要有效得多。

## 任务：创建用户积分扣除服务函数 **函数签名**: `deductUserPoints(userId: string, points: number, reason: string): Promise<DeductionResult>` **输入**: - `userId`: 用户ID，必须是存在的、状态为激活的用户。 - `points`: 扣除积分数，必须为正整数，且不大于用户当前可用积分。 - `reason`: 扣除原因，枚举值：['PURCHASE', 'REFUND', 'ADMIN_ADJUSTMENT', 'PENALTY']。 **输出**: - `success`: boolean。 - `remainingPoints`: number，扣除后的积分余额。 - `transactionId`: string，本次积分变动的唯一事务ID。 - `error`: string | null，失败时的错误信息。 **业务规则**: 1. 必须是原子操作：查询当前积分和扣除操作必须在同一个数据库事务中。 2. 需要记录完整的积分流水（`points_ledger`表），包含操作前余额、变动值、操作后余额、原因、时间戳。 3. 如果`userId`不存在或用户状态非激活，立即失败，错误码`USER_INVALID`。 4. 如果`points`超过可用积分，立即失败，错误码`INSUFFICIENT_POINTS`。 **禁止**: - 直接使用`UPDATE ... SET points = points - ?`而不做前置查询校验。 - 在函数内进行任何形式的HTTP调用或IO阻塞操作（日志除外）。

3.2 食材二：精选的代码范例与风格指南

这是你的“调味料和经典菜式样本”。智能体通过示例学习的速度和效果远超纯文本描述。

• 架构与模式范例：提供1-2个项目中类似模块的完整、简洁的代码文件。例如，如果要生成一个GraphQL Resolver，就提供一个现有的、设计良好的Resolver文件。这能传递项目整体的架构风格、分层逻辑、依赖注入方式等隐性知识。
• 代码风格片段：不是给一个通用的ESLint配置链接，而是提供具体的代码片段对比。
  • 好的例子：// 使用具名导出而非默认导出，// 错误处理使用Result模式而非try-catch遍地开花。
  • 坏的例子：// 避免：嵌套超过三层的回调函数。
• 领域特定语言：如果你的项目有自己的一些术语、工具函数或设计模式，提供它们的定义和用法。例如，“我们使用@Injectable()装饰器来自动处理依赖”，“查询数据库统一使用queryBuilder()工具函数，它内置了连接池管理和超时重试”。

踩坑经验：最初我只给智能体看“好”的代码，后来发现它有时会模仿一些过时的模式。现在我会有意准备一个“模式进化说明”，例如：“本项目早期使用X模式处理错误，但现在已全面迁移到Y模式。请参考service/authV2.ts而非service/auth.ts。”

3.3 食材三：精确的依赖与环境上下文

这是你的“厨具和灶台状态”。智能体需要知道在哪个“厨房”里工作。

• 技术栈清单：精确到主版本号。Node.js 18 LTS,TypeScript 5.0+,React 18,Prisma ORM 4.0+。避免只说“用最新的”。
• 关键依赖的API风格：如果你用了某个特定的库，说明你期望的用法。例如，“我们使用axios进行HTTP请求，并且已经配置了全局的请求拦截器添加JWT令牌，所以直接使用axios.get('/api/endpoint')即可，无需手动处理认证头。”
• 项目结构导航：用简短文字描述关键目录的作用。/src/models/存放Prisma生成的数据库模型和自定义的领域模型；/src/services/存放核心业务逻辑，每个文件对应一个领域服务；/src/api/routes/存放Express路由定义，它们只负责接收请求和返回响应，逻辑委托给service层。
• 运行时约束：代码将运行在什么环境？服务器less函数（有冷启动时间限制）？Docker容器（特定的Linux环境）？特定的云平台（如AWS Lambda，需要处理特定的环境变量）？

3.4 食材四：动态的会话状态与思维链锚点

这是你在烹饪过程中的“火候控制和尝味记录”。对于复杂的、多轮的任务，你需要管理对话本身。

• 思维链显式化：要求智能体在给出最终代码前，先输出其思考过程。例如，“请先分析需求，列出实现步骤和可能遇到的坑，然后再生成代码。” 这让你能中途纠正它的思路偏差，而不是等到代码生成后才发现问题。
• 关键决策记录：在多轮对话中，当你们共同做出一个重要技术决策时（比如“决定采用策略模式来解耦不同的支付方式”），用一句总结的话记录下来，并在后续提示中简要提及，作为“会话记忆锚点”。例如，“【决策记录】支付处理器采用策略模式，已定义PaymentStrategy接口。”
• 问题-解决方案对：在调试过程中，将已识别的问题和已验证的解决方案明确记录下来，避免智能体在后续步骤中重蹈覆辙或遗忘。这就像厨师在菜谱边上标注“上次盐放多了，这次减半”。

4. 实战演练：一个用户注册API的“备料”到“出锅”全流程

让我们通过一个具体的例子，看看如何应用这套方法论。假设我们要为一个已有后端项目添加一个用户注册API。

4.1 步骤一：准备“备料台”（编写上下文提示）

我不会直接打开AI对话窗口就开始打字。而是先创建一个临时的文档或注释，系统性地组装上下文。

# 智能体任务上下文：添加用户注册API ## 1. 项目上下文 - **项目类型**: Node.js + TypeScript后端服务，采用分层架构。 - **核心框架**: Express.js, Prisma ORM, JWT for auth. - **代码风格**: Airbnb ESLint基础，扩展规则见 `.eslintrc.js`。使用`async/await`，错误处理统一使用`try/catch`包裹，并在顶层中间件处理。 - **参考范例**: 请参考 `src/api/routes/auth/login.ts` 和 `src/services/authService.ts` 的现有模式。注意登录API的请求验证、错误响应格式。 ## 2. 任务规格说明书 **功能**: 实现用户注册端点。 **端点**: `POST /api/v1/auth/register` **请求体 (JSON)**: ```json { "email": "string, 必须符合邮箱格式，且唯一", "password": "string, 最小长度8位，必须包含字母和数字", "username": "string, 可选，如未提供则使用邮箱前缀" }

成功响应 (201 Created):

{ "success": true, "data": { "user": { "id": "uuid", "email": "string", "username": "string" }, "token": "JWT字符串，用于后续认证" } }

错误响应 (400 Bad Request):

• 邮箱格式无效:{ "success": false, "error": "INVALID_EMAIL_FORMAT" }
• 邮箱已存在:{ "success": false, "error": "EMAIL_ALREADY_EXISTS" }
• 密码强度不足:{ "success": false, "error": "WEAK_PASSWORD" }业务逻辑:

1. 验证请求体字段格式和强度。
2. 检查邮箱在User表中是否已存在。
3. 对密码进行加盐哈希（使用bcrypt，强度因子12）。
4. 创建新用户记录，写入数据库。
5. 生成JWT令牌（payload包含userId和email，有效期7天）。
6. 返回用户基本信息（不含密码哈希）和JWT令牌。非功能需求:

• 密码明文绝不可出现在日志中。
• 邮箱唯一性检查需考虑数据库并发注册情况（使用Prisma的create唯一约束，或先findUnique后create在事务中处理）。

3. 给智能体的明确指令

请按照以下步骤操作：

1. 首先，分析上述需求，并列出你认为的实现计划（1. 创建路由文件；2. 创建或更新服务层函数；3. 更新Prisma模型如果需要...）。
2. 然后，根据计划，先生成src/api/routes/auth/register.ts文件。
3. 接着，生成或修改src/services/userService.ts，添加createUser函数。
4. 最后，确保生成的代码遵循项目现有风格，并处理所有提到的错误情况。 请分步骤进行，在每个步骤后暂停，等待我的确认或反馈。

### 4.2 步骤二：执行与交互（“烹饪”过程） 将上述精心准备的上下文提示复制到AI对话中。由于上下文清晰，智能体通常能给出一个非常靠谱的实现计划。我会审阅这个计划，确保它和我的架构理解一致。 然后，让它按步骤生成代码。在每一步，我都会重点检查： * **路由文件**：是否正确地引入了依赖？错误处理中间件是否使用正确？响应格式是否符合规范？ * **服务层函数**：密码哈希的逻辑是否正确？是否考虑了并发？返回的数据结构是否匹配？ * **代码风格**：导入语句顺序、命名规范、异步处理方式是否与项目现有代码一致？ 如果在某一步发现偏差，例如它可能用了一个旧的验证库而不是我们项目正在使用的`Joi`，我会立即中断并纠正：“停。我们项目使用 `Joi` 进行请求验证，请参考 `login.ts` 中 `validateLoginRequest` 函数的写法，重写注册请求的验证逻辑。” ### 4.3 步骤三：验证与收尾（“摆盘”与“尝味”） 代码生成后，我的工作并未结束。 1. **静态检查**：将生成的代码放入IDE，运行ESLint和TypeScript编译器，检查是否有类型错误或风格问题。智能体有时会忽略一些边缘的类型定义。 2. **逻辑复查**：人工通读代码，特别是业务逻辑部分。检查密码哈希、唯一性约束处理、JWT生成等关键环节是否正确无误。 3. **集成测试**：编写或运行一个简单的集成测试（可以是手动调用，也可以是简单的测试脚本），验证API的完整流程。这是发现上下文理解偏差的最后一道防线。 4. **上下文归档**：如果这个任务模式具有可复用性（比如“添加一个标准的CRUD API”），我会将这次成功的“上下文提示”作为一个模板保存下来，下次类似任务只需做少量修改即可复用，极大提升效率。 ## 5. 高级技巧：应对复杂任务与避免常见陷阱 当任务从“炒个菜”升级为“筹办一场宴席”（例如，重构一个模块，或实现一个包含多个交互组件的功能）时，简单的线性提示就不够了。 ### 5.1 分治与迭代：不要试图一口吃成胖子 对于复杂任务，绝对不要试图在一个提示里解决所有问题。采用“分治”策略。 * **第一步：架构设计对话**。提示智能体：“我们需要实现一个带实时通知的任务管理系统。请先给出一个高层次的技术架构设计，包括主要模块、数据流和技术选型建议。” 基于它的建议进行讨论和修正，形成共识。 * **第二步：契约先行**。基于共识，让智能体先定义核心的接口（Interface）、类型（Type）和数据传输对象（DTO）。例如，“请根据上述设计，先定义 `Task`, `User`, `Notification` 的TypeScript接口，以及创建任务、更新任务状态的DTO类型。” * **第三步：模块化实现**。然后，按照模块逐个击破。“现在，请先实现 `TaskService` 的核心方法，包括 `createTask`, `assignTask`, `updateTaskStatus`。请确保它们符合你刚才定义的接口。” 每一轮都基于上一轮确定的、无歧义的“契约”进行，确保上下文像搭积木一样稳步构建，而不是推倒重来。 ### 5.2 幻觉检测与事实锚定 智能体的“幻觉”在复杂任务中尤为危险。对抗幻觉最有效的方法是“事实锚定”。 * **引用真实代码**：当讨论现有代码时，不要描述，而是直接粘贴相关代码片段。例如，不要说“我们的错误处理中间件是这么做的”，而是说“请看现有的错误处理中间件代码：`[粘贴代码]`，请确保新的API使用相同的方式。” * **要求提供出处**：当智能体给出一个建议或陈述一个关于你项目的事实时（比如“Prisma模型里有一个`createdAt`字段”），可以要求它：“请指出这个信息是基于我提供的上下文，还是你的通用知识？如果是基于我的上下文，请引用相关部分。” 这能迫使它检查自己的“记忆”，减少信口开河。 * **交叉验证**：对于关键逻辑，可以让智能体从不同角度实现两次，或者要求它解释代码的每一行在做什么。解释不通的地方，往往就是幻觉或错误所在。 ### 5.3 上下文的版本管理与迭代 一个项目的“备料台”不是一成不变的。随着项目演进、技术栈升级、最佳实践变化，你的上下文模板也需要迭代。 * **建立上下文库**：为不同类型的任务（CRUD API、数据迁移脚本、前端组件、配置部署文件）建立标准化的上下文模板。 * **记录失败案例**：当一次智能体交互因为糟糕的上下文而失败时，事后分析原因，并更新对应的上下文模板，补充当时缺失的关键信息或纠正误导性描述。 * **团队共享**：在团队中推广这种“备料”文化，并共享优化后的上下文模板。这能极大统一团队内AI辅助编码的输出质量，减少因个人提示风格差异导致的代码风格不一致问题。 ## 6. 工具化与未来展望：将方法论沉淀为工作流 最高效的实践，最终都会沉淀为工具或固化的工作流。 * **提示模板化**：使用像Cursor IDE的`.cursorrules`文件，或是将精心设计的提示保存为代码片段，在需要时快速插入。 * **上下文文件化**：为项目创建一个`AGENT_CONTEXT.md`文件，存放项目的技术栈摘要、代码风格公约、常用范例链接、以及常见任务的提示模板。新成员或新的智能体会话都可以以此为基础。 * **与开发流程集成**：在创建新的功能分支、或初始化一个新模块时，将“编写智能体上下文提示”作为开发流程的第一步，纳入代码审查的一部分。审查一个清晰的上下文提示，往往能提前发现很多需求歧义和设计缺陷。 “Mise en Place for Agentic Coding”远不止是一个酷炫的类比。它代表了一种思维模式的转变：从将AI智能体视为一个“许愿机”（输入模糊愿望，输出完美结果），转变为将其视为一个拥有强大执行力的“专业协作者”。而作为人类开发者，我们最核心、最不可替代的价值，就在于成为那个**专业的“备料师”**——通过深思熟虑的上下文工程，定义清晰的问题边界，提供精准的约束和素材，从而将智能体的能力引导向正确、高效、可靠的方向。 这个过程本身，就是对问题更深层次的思考和解构，它强迫你厘清需求、明确边界、审视架构。最终，即使没有智能体，经过这番“备料”思考后，你自己去实现代码的思路也会清晰数倍。这或许就是人机协同编程带给我们的、超越工具本身的额外奖赏：一种更严谨、更工程化的思维方式。