目录一、大多数失败不是提示词写坏了一三个流传最广的认知陷阱1、把模型当读心者2、把一次成功当成方法论3、把上下文窗口当成无限内存二一个可操作的判定问题三从一段话到一个系统两种工程的分野1、提示词工程在优化什么2、上下文工程在构建什么二、模型在生成之前到底看到了什么一上下文的完整解剖二注意力预算为什么塞得越多效果越差1、有限资源的三重约束2、最小高信号集合原则三编程场景的五类核心供给三、供给一架构——告诉它代码放哪里、动哪里、不许碰哪里一目录即边界二依赖方向与数据流动三负面清单与禁区四、供给二规范——只写它猜不到的规则一筛选原则偏离默认的才值得写二一个 Java 团队的规范样本1、红线级违反即阻塞1.1、异常与资源1.2、数据与并发1.3、敏感数据2、偏好级默认遵循三规范的载体与分层五、供给三命令——让它自己跑起来验证一精确到参数的命令而不是工具的名字二五分钟内跑完的快回路三环境一致性六、供给四业务规则——术语、口径与不变式一术语表一个词两个意思是最大的坑二口径与不变式三显式的禁止事项七、供给五验收标准——把「做对了」定义成机器可判定一从形容词到判据二验证链与失败回传1、把判定串成链2、失败信息也是上下文3、判据不能由被检验者自己出八、把五类供给组织起来分层、按需与长任务一项目级与任务级两层二一次委派该带上什么任务上下文包三选、组、管与即时检索四长任务的三种手段九、同一个需求的两种交付一个部分退款的对照实验一只有提示词的版本二带完整供给的版本三差距从哪里来十、从个人技巧到团队资产一上下文资产的载体与保鲜期二规格驱动企业级、领域级、项目级三度量与能力阶梯十一、边界与误区一过度供给也是一种失败二上下文替代不了判断三过期的上下文比没有更糟十二、结语你喂给 AI 的就是你对系统的理解程度参考资料干货分享感谢您的阅读过去两年里工程师们在提示词上倾注了大量心思背句式、攒模板、收藏「神咒语」。但就目前而言当我们认真复盘过几十次 AI 编程的失败案例就会发现一个反直觉的事实——绝大多数翻车与措辞无关。模型不是没听懂你的话而是根本不知道你的项目长什么样它不知道代码该放进哪个模块、不知道团队禁止捕获异常后静默吞掉、不知道金额必须用 BigDecimal、不知道跑哪条命令能验证自己写的东西对不对更不知道「退款成功」在你们的业务口径里意味着哪三张表要同时落账。这次我们要论证的是一个工程判断AI 编程的核心竞争力不在提示词而在上下文工程——把架构、规范、命令、业务规则和验收标准这五类信息以正确的分层、正确的粒度、正确的时机供给模型并用机器可判定的验证闭环收口。提示词只是这条供给链上最薄的一层包装纸。全文给出五类供给各自的编写方法、组织方式、一个完整的对照案例以及从个人技巧升级为团队资产的落地路径。一、大多数失败不是提示词写坏了一三个流传最广的认知陷阱1、把模型当读心者最常见的失败模式是这样的工程师在对话框里输入「帮我给订单服务加一个部分退款接口」模型流畅地生成了两百行代码——用了项目里根本不存在的工具类绕过了团队的统一异常体系金额字段用了 double退款状态直接 UPDATE 而没有走状态机。工程师的第一反应往往是「提示词写得不够好」于是加上「请遵循最佳实践」「请写出生产级代码」这类修饰。问题在于「最佳实践」是一个没有信息量的词。模型的训练语料里有几十万种互相冲突的「最佳实践」你的项目采用哪一种只存在于你的代码库、你的规范文档和你同事的脑子里。模型无法读取这三个地方的任何一个除非你把它们放进上下文。语言模型不会读心这是讨论一切 AI 编程问题的公理缺失的信息不会因为措辞恳切而凭空出现「垃圾进、垃圾出」在这里以一种更隐蔽的方式成立——不是你给了错误的信息而是你什么关键信息都没给模型只能用统计上最常见的猜测来填补空白而统计上最常见的写法几乎必然不是你们团队的写法。2、把一次成功当成方法论第二个陷阱是幸存者偏差。某次调整了提示词的语气或结构之后模型表现变好工程师便总结出「要用祈使句」「要先给角色设定」之类的经验。这类经验的问题不在于错而在于不可复现换一个任务、换一个模型版本、甚至只是换一天效果就消失了。原因很简单——那次成功的真正变量往往不是句式而是调整措辞时顺手多贴了一段相关代码或者把需求描述得更具体从而隐式补充了验收标准。把相关性当因果性是提示词玄学盛行的根源。真正可复现的变量是信息本身给了哪些代码、哪些约束、哪些判定标准。围绕这些变量做工程效果才能跨任务、跨模型地保持稳定。3、把上下文窗口当成无限内存第三个陷阱与前两个方向相反既然缺信息会失败那把整个仓库、所有文档、全部对话历史一股脑塞进去总行了吧上下文窗口从 8K 涨到 200K 再涨到百万级似乎鼓励了这种「全都要」的策略。但窗口大小和有效注意力是两回事。针对长上下文的检索类基准测试反复观测到一个现象业内称之为「上下文腐蚀」随着窗口内 token 数量增加模型从中准确召回信息的能力单调下降。这不是某个模型的缺陷而是 Transformer 架构的结构性约束——每个 token 要与其他所有 token 建立注意力关系n 个 token 意味着 n² 对关系窗口越长单对关系分到的注意力就越稀薄同时训练数据中短序列远多于长序列模型处理超长依赖的「经验」本来就少。把无关信息塞进窗口不是无害的冗余而是在直接稀释关键信息的权重。上下文必须被当成一种有限资源来管理它有预算、有边际递减、有挤占效应。二一个可操作的判定问题区分「提示词问题」和「上下文问题」有一个简单的试金石把你发给模型的全部内容原样打印出来交给一位从未接触过这个项目的资深工程师他能不能做对这个任务如果他做不对——不知道代码风格、不知道调用哪个内部服务、不知道怎么验证——那这就不是措辞问题任何提示词技巧都救不了因为完成任务所需的信息根本不在场。如果他能做对而模型做不对才轮到讨论表述方式、示例质量和模型能力。这个测试把一个玄学问题变成了一个可检查的清单问题也解释了为什么同一个模型在不同团队手里表现差距巨大差距不在咒语在供给。围绕这个试金石还能推出一个失败模式的二分法任务失败要么因为「模型拿到了全部必要信息但仍然做错」模型能力问题换模型或等模型进步要么因为「模型根本不可能从你给的信息里推出正确答案」供给问题改你自己的流程。实践中后者占绝对多数而且随着模型代际进步比例还在向后者倾斜——模型越强剩下的失败越是纯粹的供给失败。三从一段话到一个系统两种工程的分野1、提示词工程在优化什么提示词工程处理的对象是一段静态文本怎么措辞、怎么排版、怎么给角色设定、怎么安排少样本示例的顺序。它假设输入是固定的优化的是「同样的信息如何表述得让模型更容易理解」。这件事有价值但它是整个问题里最小的一环相当于在包装纸上做文章。2、上下文工程在构建什么上下文工程处理的对象是一个动态系统在每一次模型调用之前有一套机制负责决定「这一次模型应该看到什么」。这套机制要从代码库、文档、工具输出、对话历史、外部检索里选材按任务裁剪按格式组装并且随着任务推进不断更新。一个被业内广泛引用的定义把它概括为构建动态系统在正确的时机、以正确的格式向模型提供正确的信息和工具使任务「有可能被合理地完成」。两者的关系不是替代而是包含提示词工程是上下文工程的子集负责其中「指令层」的表述质量。当任务从单轮问答演进为多轮、长程、带工具调用的智能体协作表述质量的边际贡献迅速缩小而选材、裁剪、组装、更新这套系统能力的贡献迅速放大。可以用一组对照把分野说清楚前者优化一次调用的一段字符串后者运营一条贯穿任务全程的信息供给链前者的产出是话术可以收藏转发后者的产出是资产沉淀在仓库里随代码一起演化前者失败了只能重写一遍后者失败了有明确的排查路径——缺哪类信息、哪一层过期了、哪个环节格式不对。二、模型在生成之前到底看到了什么一上下文的完整解剖要管理上下文先要看清它的全貌。模型每生成一个 token 之前「看到」的内容远不止你刚敲进对话框的那句话而是一个分层的集合系统指令层定义模型行为边界的常驻指令——角色、总体规则、输出要求。在编程工具里这一层通常由工具厂商的内置指令加上团队的规则文件如仓库根目录的智能体说明文件共同构成。工具定义层模型可以调用哪些工具——读文件、跑命令、搜代码、查数据库——每个工具的名称、参数、返回格式。工具定义本身就占用上下文且直接决定模型能够自主获取哪些补充信息。示例与规格层少样本示例、接口契约、数据结构定义、验收标准。这一层回答「做对了长什么样」。检索内容层为本次任务动态拉取的材料——相关源码文件、报错日志、文档片段、依赖的接口定义。对话历史层本次会话累积的往返内容包括之前的工具调用结果。这一层增长最快也最容易变成噪声的来源。输出契约层对响应格式的约束——JSON Schema、diff 格式、结构化字段。这六层加起来才是模型的「所见」。提示词工程只经营其中一层的表述上下文工程经营全部六层的内容、比例与时序。很多莫名其妙的失败把这六层逐一检查一遍就能定位系统指令与任务指令互相矛盾、工具定义模糊导致模型选错工具、检索层贴了三个版本的旧代码、历史层残留着早已作废的方案讨论。二注意力预算为什么塞得越多效果越差1、有限资源的三重约束把上下文当成有限资源有三个具体的约束需要牢记。其一是容量上限这是硬约束但通常最不重要因为在撞到上限之前效果早就劣化了。其二是注意力稀释n² 的注意力矩阵意味着信息密度随长度下降关键约束淹没在大段无关代码里时模型「看到了但没注意到」。其三是干扰效应过期的方案讨论、失败的尝试记录、多个版本的同一段代码同时在场时模型可能采信错误的那一份——上下文内部的一致性比数量重要得多。2、最小高信号集合原则由此得出上下文工程的第一原则寻找能最大化期望产出的最小高信号 token 集合。注意「最小」修饰的是噪声而不是信息量——该给的架构、规范、判据一个都不能少不该给的重复、过期、无关内容一个都不该有。落到操作上是三个动作给之前问「模型缺了这条信息会不会做错」不会做错就不给给的时候选摘要而不是全文、选签名而不是实现、选一个典范示例而不是十个边角案例给完之后随任务推进清理——已经采纳的方案其讨论过程就该出场了。三编程场景的五类核心供给上面的分层是从模型视角看结构。换到工程师视角真正要回答的问题是为了让模型在我的项目里干活我必须准备哪几类信息把大量实践收敛之后答案稳定在五类架构——代码放哪里、模块怎么分工、数据怎么流动、哪些地方不许碰。它决定模型「在哪里动手」。规范——团队偏离语言默认约定的所有规则异常怎么处理、金额用什么类型、线程池怎么建、日志怎么脱敏。它决定模型「以什么姿势动手」。命令——精确到参数的构建、测试、检查命令。它决定模型「怎么验证自己」。业务规则——领域术语、数据口径、状态机、不变式、禁止事项。它决定模型「理解任务本身」。验收标准——机器可判定的完成定义哪些测试要过、哪些行为不能变、哪些指标要达标。它决定「什么叫做完了」。这五类供给覆盖了一个新任务从理解到交付的全部信息需求也构成本文第三到第七章的主线。它们有一个共同特征全部是模型猜不到、只有你的团队才拥有的私有知识。模型的代际进步会持续提升它利用这些信息的能力但永远不会替你生产这些信息——这正是上下文工程作为一种工程师核心技能的护城河所在。三、供给一架构——告诉它代码放哪里、动哪里、不许碰哪里一目录即边界模型进入一个陌生仓库时的第一个问题和新同事一样这堆目录各自负责什么如果答案需要读完全部代码才能得出那么无论人还是模型都会犯错。架构供给的第一件事是把「目录到职责」的映射显式写出来一行一条接口层目录只放路由与参数校验必须薄业务逻辑一律下沉到服务层服务层目录承载业务规则不允许直接触碰持久化细节数据访问层目录负责所有数据库交互对上暴露仓储接口公共组件目录只放无业务语义的纯工具。这份映射的价值在于它同时回答了「改哪里」和「不改哪里」。「给订单加一个字段」这个任务在映射清晰的仓库里模型能推出要动实体、迁移脚本、DTO 和映射器四处在映射缺失的仓库里模型可能直接在控制器里拼 SQL——不是它蠢是没有任何信息告诉它这样不行。二依赖方向与数据流动比目录更深一层的是依赖规则哪些模块可以依赖哪些模块方向是否允许逆转。「领域层不依赖基础设施层」「外部 SDK 的类型不允许出现在核心业务模型的签名里」「跨模块调用必须走显式契约而不是直接引用对方内部类」——这类规则在人类团队里靠代码评审维护在 AI 参与的团队里必须前置写进上下文因为模型生成代码的速度让事后评审的拦截成本变得不可接受。数据流动同样值得一段简短描述一个典型请求从入口到落库经过哪几站异步链路上消息从哪里发出、被谁消费、失败了走哪条补偿路径。有了这张图模型在插入新逻辑时才知道应该挂在哪一站而不是在任意一站硬塞。三负面清单与禁区架构供给里性价比最高的部分是负面清单明确列出不许碰的东西。自动生成的代码目录不许手改数据库迁移脚本一旦合并不许修改只许追加遗留模块维持同步风格不许顺手改成异步配置密钥文件不许读取也不许提交。负面约束的优先级高于正面描述因为违反它的代价通常不可逆而模型在缺少禁令时的默认行为是「顺手优化」——它见过的开源代码都鼓励它这么做。一个值得采纳的经验法则每当你在评审中对生成代码说出「这里不能这么写」就把这句话变成负面清单的一条。三个月之后这份清单就是你的团队独有的、任何通用模型都不具备的架构知识。四、供给二规范——只写它猜不到的规则一筛选原则偏离默认的才值得写规范文档最常见的失败方式是照抄一份通用编码规范——「变量命名要有意义」「函数要短」「要写注释」。这些内容模型早就从训练数据里学会了写进上下文纯属消耗注意力预算。规范供给的筛选原则只有一条只写你的团队与语言默认约定不同的地方以及模型在没有指引时大概率会做错的地方。每一条规范都在和其他信息竞争注意力。一份两千行的完整规范手册效果通常不如两百行的「偏离清单」。判断一条规则该不该写的方法很直接让模型在没有这条规则的情况下做十次同类任务如果它有三次以上做出了你不想要的选择写如果它十次都做对了删。二一个 Java 团队的规范样本用一个真实形态的 Java 后端团队规范来展示「偏离清单」长什么样。它分成两档红线级违反即阻塞合并偏好级供模型默认遵循。1、红线级违反即阻塞1.1、异常与资源禁止空 catch捕获必须处理或带上下文重抛禁止用异常做流程控制finally 块禁止 returnIO 与数据库资源必须用 try-with-resources 关闭。这四条针对的都是模型高频生成的「看起来能跑」的代码——空 catch 在生成代码里的出现率高得惊人因为大量训练语料里的示例代码就是这么偷懒的。1.2、数据与并发金额一律 BigDecimal禁止 float/double 参与金额运算集合声明用接口类型可能返回空的方法用 Optional 或注解标明。并发侧禁止 Executors 工厂方法线程池必须显式配置核心参数阻塞队列必须指定容量禁止业务代码里临时创建线程池。1.3、敏感数据手机号、身份证、银行卡号禁止明文进日志必须走统一脱敏工具API 响应中的敏感字段必须加脱敏注解密钥凭据禁止硬编码一律走凭据管理服务。这一档规则的特殊性在于违反的后果是合规事故而不只是缺陷因此除了写进上下文还必须配静态扫描兜底——上下文负责让模型第一次就写对扫描负责万一没写对时拦住。2、偏好级默认遵循单行不超过 120 字符、KR 大括号风格、UTF-8 与 LF、测试方法命名采用「方法名_条件_期望结果」格式、测试遵循准备-执行-断言三段式。偏好级规则的共同点是违反了不出事故但增加评审摩擦写清楚之后模型的产出可以直接过格式关省下的评审注意力可以集中到逻辑上。三规范的载体与分层规范写在哪里决定了它会不会被读到、会不会过期。目前业内收敛出的载体是仓库根目录的智能体说明文件不同工具生态叫法不同有的叫 AGENTS.md有的叫 CLAUDE.md有的用规则目录配合子目录级的局部规则根文件写全局约定模块目录里的局部文件写该模块的特殊规则工具在进入对应目录工作时自动叠加。分层带来两个好处。其一是粒度匹配支付模块的幂等规则没必要让所有任务都背着。其二是就近维护模块负责人改自己目录下的规则文件不需要走全局文档的评审流程。此外还有一条被反复验证的实践这份文件不必从零手写让模型通读现有代码自动起草、人工核对修订成本低且不容易遗漏「团队自己都没意识到的约定」。唯一的纪律是它必须与仓库现状一致——一条描述已废弃写法的规范比没有规范更有害。五、供给三命令——让它自己跑起来验证一精确到参数的命令而不是工具的名字「跑一下测试」对人是有效指令对模型不是。它不知道该用 Maven 还是 Gradle、该带哪个 profile、单测和集成测试怎么分开跑、跑单个测试类的语法是什么。命令供给要求把这些写成可直接执行的形态编译检查用哪条命令带哪些参数跳过什么全量单测怎么跑单跑一个测试类怎么写格式化与静态检查分别是哪条本地起服务依赖哪个容器编排文件、起来之后健康检查地址是什么。精确命令的价值不只是省去模型猜测更在于它把「验证」这个动作变成模型可以自主执行的闭环环节。一个拿到精确命令的模型可以写完代码自己编译、自己跑测试、自己看报错、自己修把原本需要人工往返五轮的过程压缩成一轮委派;一个没有命令供给的模型只能把未经验证的代码交回来把验证成本原封不动留给你。二五分钟内跑完的快回路命令供给有一个隐含的质量要求验证回路必须快且稳定。如果全量测试要四十分钟模型和人一样就会跳过验证如果测试结果时好时坏验证就失去判定力。因此命令供给往往倒逼团队做两件基建把验证分层——秒级的编译与格式检查、分钟级的核心单测、按需的集成测试让模型默认跑前两层以及清理不稳定的测试——在人类团队里偶发红的测试只是烦人在模型自主循环里它会直接把修复循环带进死胡同因为模型会试图「修好」一个本来就随机失败的测试。三环境一致性命令能跑的前提是环境一致。JDK 版本、构建工具版本、依赖的中间件容器、必需的环境变量——这些要么写进说明文件要么更好地固化成一条初始化命令。一个值得注意的细节是模型执行环境里的失败信息会原样进入上下文环境性报错端口占用、容器未启动、版本不符与真实代码缺陷混在一起时模型的归因能力会显著劣化经常把环境问题「修复」成代码改动。环境一致性投资的回报之一就是让进入上下文的每一条报错都值得认真对待。六、供给四业务规则——术语、口径与不变式一术语表一个词两个意思是最大的坑业务规则供给的第一件事不是写规则而是统一语言。企业系统里最贵的缺陷往往源于同一个词的两种理解「订单金额」是含运费还是不含「用户数」是注册口径还是活跃口径「退款完成」是指资金指令已发出还是渠道回执已确认人类同事靠几个月的耳濡目染消化这些歧义模型只有你写下来的那几行。一份合格的术语表为每个核心概念给出定义、计算口径、与相近概念的区别、对应到哪张表哪个字段。它不需要覆盖所有名词只需要覆盖「曾经引起过争论」的名词——和规范的筛选原则一样写模型以及新同事猜不到的部分。二口径与不变式比术语更进一步的是系统必须永远成立的性质也就是不变式账户余额等于所有已入账流水之和库存扣减量不超过可用量同一订单的退款总额不超过实付金额状态机只允许沿定义的边迁移不存在从「已关闭」直接到「已发货」的路径。不变式是业务规则里最值得优先供给的部分原因有二。第一它是模型生成代码时最容易破坏又最难自查的东西——一段单独看完全正确的退款代码可能因为没有校验累计退款额而破坏第三条不变式任何单元测试都发现不了。第二不变式天然具备机器化潜力能写成数据库约束的写成约束能写成断言的写成断言能做成在线巡检的做成巡检。写成文字的不变式约束模型的生成写成代码的不变式兜住漏网之鱼两层缺一不可。三显式的禁止事项业务侧同样需要负面清单而且比技术侧更需要因为业务禁令往往完全无法从代码里推断营销优惠不允许与员工内购叠加已开票订单的金额字段冻结任何修正走红冲重开某些地区的用户数据不允许出该地区的存储边界灰度期间新逻辑只对白名单租户生效。这类规则的共同点是「不写就等于不存在」——模型不可能从任何通用知识里推出你们的开票流程它只会写出一段逻辑自洽但违反财务纪律的代码。把业务禁令显式化的过程往往还有一个副产品团队自己会发现相当一部分「规则」其实从未被清晰定义过两个资深成员的理解并不一致。这类发现的价值超出 AI 编程本身。七、供给五验收标准——把「做对了」定义成机器可判定一从形容词到判据「修复注册页的问题」「优化查询性能」「提升代码质量」——这类验收描述的共同点是使用了形容词而不是判据。模型面对形容词只能自由发挥然后由你在评审时凭感觉打分双方都在猜。验收标准供给的核心动作是把每一个形容词翻译成可判定的陈述「优化查询性能」翻译成「订单列表接口在十万数据量下 P95 延迟从 800 毫秒降到 300 毫秒以内现有全部测试保持通过」「修复注册问题」翻译成「新增的重复邮箱注册测试通过、原有测试无回归、注册接口的响应结构不变、代码变更范围限于注册相关模块」。一条合格的验收标准同时回答四件事新行为的正确性怎么证明新增哪些测试、旧行为的完整性怎么保证哪些既有测试与契约不能变、变更的范围边界在哪里允许改哪些目录、非功能要求是什么性能、兼容、安全。四件事都可判定之后「做完了」就从一个主观声明变成了一个机器可以出具的结论。二验证链与失败回传1、把判定串成链单条判据要串成一条自动化验证链才能发挥全部价值编译与类型检查、格式与静态扫描、新增测试、既有回归、契约比对、变更范围检查逐级执行任何一级失败即停。这条链在人类工作流里叫 CI在 AI 工作流里它的角色升级了——它不再只是「合并前的门禁」而是模型自主工作循环的组成部分模型每完成一轮生成就跑链链的输出决定下一步。2、失败信息也是上下文验证链的输出质量直接影响修复循环的效率因为失败信息会回传进上下文成为下一轮生成的输入。「测试失败了」是最差的回传「重复邮箱测试失败期望返回 409 与错误码 EMAIL_EXISTS实际返回 500堆栈显示唯一索引冲突未被捕获相关代码在注册服务第 87 行」是最好的回传——它几乎把修复方案递到了模型手里。这解释了为什么断言信息、错误消息、日志规范这些「软性」工程习惯在 AI 时代突然变成硬资产它们的读者从值班工程师扩展到了每一轮生成循环。3、判据不能由被检验者自己出一条必须遵守的独立性原则验收标准的制定不能委托给执行任务的同一个模型实例。让模型自己写需求、自己写测试、自己判通过会得到一个逻辑闭环但可能整体偏航的系统——测试完美通过但测的是它自己理解的需求。判据要么来自人要么来自独立的规格来源要么至少来自一个拿到不同上下文的独立评审过程。生成可以外包判定权不能。八、把五类供给组织起来分层、按需与长任务一项目级与任务级两层五类供给不是每次任务都全量出场。有效的组织方式是分成两层。项目级上下文相对稳定、跨任务复用架构映射、规范偏离清单、命令手册、术语表与不变式。它们沉淀在仓库的规则文件与文档里由工具自动装载。任务级上下文一事一配本次要动的代码、相关的接口契约、复现问题的日志、本次的验收标准、允许修改的范围。它们由发起任务的人或上游流程临时组装。两层的分界线是变化频率。把任务级信息写进项目级文件会让文件迅速膨胀腐化把项目级信息每次手工重贴则既低效又容易版本漂移。大量团队的上下文管理问题归根结底是把两层混在了一起。二一次委派该带上什么任务上下文包任务级上下文可以标准化成一份「委派清单」发起任务前逐项核对目标与背景为什么做相关代码与配置的精确位置而不是整个仓库涉及的接口或数据契约如果是缺陷修复附上报错日志与复现步骤预期行为与验收标准允许修改的文件或目录范围已经尝试过但无效的方案。最后一项经常被忽略但价值极高不写「已试过的死路」模型大概率会把那条死路再走一遍因为那往往正是统计上最顺手的路径。委派清单的本质是把「一个靠谱同事接手任务前会问你的问题」提前答完——这也是检验清单完备性的方法找一次失败的委派看模型缺的信息是不是清单上没覆盖的项。三选、组、管与即时检索组装上下文的操作可以归纳为三个动词。选从可用信息的全集中挑出本次相关的最小集合宁可先窄后补不可先宽后删。组按稳定优先的顺序排列——系统指令与规范在前、契约与示例居中、本次任务与最新状态在后并用清晰的分节让模型知道每一段是什么。管随任务推进维护窗口内容清掉已完成阶段的中间产物纠正已被推翻的假设。「选」这一步有一个重要的现代变体不再由人预先打包全部材料而是给模型配上搜索与读取工具让它按需自取——先搜索定位、再读取相关文件、随理解加深逐步拓展。这种「即时检索」模式利用了代码库自身的结构信号目录层级、命名约定、文件时间戳都是信息避免了预打包的两个缺陷打包者的理解偏差和材料的即时过期。实践中的最优解通常是混合式规则文件与核心契约预先装载保证下限其余材料由模型即时探索获取。四长任务的三种手段当任务时长超过单个上下文窗口的承载能力——大型重构、跨模块迁移、长时间调试——需要三种额外手段。压缩接近窗口上限时把历史往返蒸馏成高保真摘要保留架构决策、未解决问题与关键实现细节丢弃冗余的工具输出用摘要重启窗口继续。结构化笔记让模型把进度、决策与待办持久化到窗口之外的文件里跨窗口恢复时先读笔记——相当于给模型配了工作日志。子任务拆分主流程只保留全局计划与各子任务的结论摘要每个子任务在干净的独立窗口里完成探索用几千 token 的结论换取几万 token 的探索空间实现关注点隔离。三种手段各有适用面多轮往返密集的任务先用压缩有清晰里程碑的迭代任务靠笔记可并行探索的研究型任务用子任务。共同的底层逻辑仍然是那条第一原则——让每个窗口里只装当下最高信号的内容。九、同一个需求的两种交付一个部分退款的对照实验一只有提示词的版本需求给订单服务增加部分退款能力。第一种做法把功夫全花在措辞上「你是一位资深 Java 架构师请为订单服务实现一个高质量、生产级的部分退款接口注意异常处理和边界情况遵循最佳实践。」模型的产出在通用标准下无可指摘接口定义清晰、参数校验完整、注释详尽。但放进真实项目里逐项检查金额用了 BigDecimal 但舍入模式与团队约定不符自己 new 了一个响应包装类而没有用统一返回体退款直接更新订单状态字段绕过了项目的状态机组件没有幂等控制同一笔退款请求重试会重复出账没有校验累计退款额不得超过实付金额这条不变式调用支付渠道的远程请求被包在数据库事务里测试 Mock 掉了全部依赖断言只验证了「方法被调用过」。七个问题没有一个源于模型能力不足——每一个都源于一条它无从知道的私有约束。二带完整供给的版本第二种做法在发起前组装了任务上下文包。项目级部分由仓库规则文件自动装载目录职责映射、异常与金额红线、状态机组件的使用约定、测试规范与禁 Mock 清单。任务级部分手工组装退款相关的现有代码位置订单实体、状态机定义、支付渠道客户端、已有的全额退款实现——特别标注「部分退款应参照此实现的模式」业务规则四条——累计退款额不超实付、已开票订单需先红冲、退款状态机的合法迁移路径、资金指令必须走异步确认而不是同步等待验收标准五条——新增的部分退款测试与幂等重试测试通过、既有全额退款测试零回归、接口响应结构与错误码符合附上的契约、变更范围限于订单与退款两个模块、事务边界内不得出现远程调用静态检查断言。同一个模型的产出发生了质变参照全额退款的既有模式复用了状态机与幂等组件金额处理与团队约定一致远程调用移到事务提交之后由事件驱动测试用真实数据库容器跑断言覆盖了不变式。人工评审从「逐行找错」变成「确认判据是否完备」一轮通过。三差距从哪里来两个版本的提示词长度相差不到十倍产出质量的差距却是「不可合并」与「一轮通过」的差距。逐项归因会发现第二个版本的每一处正确都能对应到供给清单里的某一条状态机的正确使用来自架构映射与参照实现金额与事务的正确处理来自规范红线不变式的校验来自业务规则测试的有效性来自验收标准与禁 Mock 清单。模型没有变聪明是任务从「不可能做对」变成了「有可能做对」。这正是那个判定问题的实证版本第一个版本的全部输入交给一位陌生的资深工程师他同样会踩中那七个坑——所以那从来不是模型的问题。十、从个人技巧到团队资产一上下文资产的载体与保鲜期个人层面的上下文工程是技巧团队层面的上下文工程是资产管理。资产按「会不会过期」排优先级可执行的检查测试、静态规则、契约校验永不过期因为过期即报错它们是最保值的上下文载体类型与结构接口定义、Schema、状态机代码随代码强制同步同样高度保值仓库内的规则文件需要季度级巡检纪律是「描述与现状不符的条目当场删除或修正」散文式文档设计文档、术语表保鲜期最短只保留仍在引起争论的部分。优先级的含义是一条约束如果能往上层载体迁移就应该迁移——能写成静态检查的规范不要停留在规则文件里能写成契约测试的接口约定不要停留在文档里。载体越靠上上下文的供给就越接近「自动且必然正确」。二规格驱动企业级、领域级、项目级在组织规模上上下文供给正在演化成一种被称为规格驱动开发的研发范式把需求、约束与验收固化成明确、可验证、可演进、机器可读的规格作为人与 AI 之间的共同契约语言再从规格出发生成计划、代码与测试。企业级实践中规格进一步分层——企业级规格承载全公司统一的安全合规与技术底线领域级规格承载各业务域的组件版本与集成约定项目级规格承载具体需求的功能定义、接口契约、数据结构与验收要求三层显式注入逐层收窄。这个方向值得关注的原因在于它改变了「规范执行力」的经济学过去写规范靠人自觉遵守执行率随团队规模衰减现在规范直接变成每次生成的输入与每次验收的判据写一次每一次生成都生效。约束与控制从管理成本变成了基础设施。三度量与能力阶梯怎么知道团队的上下文工程做得好不好三个可观测的信号一次通过率——委派出去的任务不经人工返工直接通过验证链的比例它综合反映五类供给的完备度返工归因分布——每次返工标注原因是缺架构、缺规范、缺命令、缺业务规则还是缺验收标准分布告诉你该补哪类资产新人与新模型上手时间——一个高质量的上下文资产库对新加入的人类工程师和新接入的模型同样有效这两个时间会同步缩短它是资产质量最诚实的代理指标。个人能力也有一条清晰的进阶路径从只会单轮提问到会附带相关材料到能写出稳定的项目级规则文件到能为任务组装完整上下文包并定义机器可判定的验收到能为团队设计分层规格与验证基础设施最终到能够运营长程多智能体任务的上下文经济。每一级的跃迁都不依赖新模型发布而依赖对自己系统理解的加深。十一、边界与误区一过度供给也是一种失败上下文工程不是「写更多文档」。每一条进入窗口的信息都在消耗注意力预算供给过度的症状和供给不足一样明确规则文件长到模型开始忽略其中的条目示例多到互相冲突历史保留到模型采信过期方案。治理手段是回到第一原则做减法——定期用「删掉这条会不会出错」来审计每一条常驻上下文答案是否的立即删除。信息的完备性和窗口的整洁度是两个都要守住的目标守住的方法是把完备性交给分层与即时检索把整洁度交给筛选与清理。二上下文替代不了判断五类供给解决的是「让模型有可能做对」不解决「确认它做对了」和「错了谁负责」。验收标准再完备覆盖的也只是已知的判定维度不变式再多写下来的也只是已经被认识到的性质。生产系统里总有一层正确性只存在于资深工程师的直觉里——某个改动「感觉会影响峰值时段的锁竞争」——这层直觉恰恰是还没来得及或还没有能力显式化的上下文。上下文工程的长期方向是持续把直觉显式化但在任何一个时点上显式化都是不完备的最后一道判定与担责必须留给人。三过期的上下文比没有更糟没有规则文件时模型按通用惯例行事产出至少内部一致带着过期规则文件时模型会认真地执行错误——按已废弃的目录结构放文件、调用已下线的内部服务、遵守已放松的旧限制。而且这类错误比通用错误更难被发现因为它「看起来符合规范」。因此上下文资产必须有明确的维护责任与巡检节奏规则文件要随重构一起改就像测试随代码一起改一样。一个实用的机制是把规则文件的关键断言也做成可执行检查规则说「接口层不依赖持久层」就配一条架构测试架构变了测试先红规则文件的更新就不会被遗忘。十二、结语你喂给 AI 的就是你对系统的理解程度把全文收拢成一条主线AI 编程的效果上限不由提示词的修辞决定而由五类供给的质量决定——架构告诉它在哪里动手规范告诉它以什么姿势动手命令让它能验证自己业务规则让它理解任务验收标准定义什么叫做完。这五类信息全部是私有知识模型的每一次代际进步都在提升利用它们的能力却永远无法替你生产它们。这件事最深刻的地方在于一个镜像关系为模型组装上下文的过程就是把你对系统的理解显式化的过程。说不清目录职责是因为边界本来就模糊写不出不变式是因为口径从未统一给不出验收判据是因为「做对了」一直靠感觉。上下文工程逼着团队补上这些欠账而补上之后受益的不只是模型——新同事、评审者、值班工程师读的是同一份资产。从这个角度看上下文工程不是伺候 AI 的新杂务而是软件工程「把隐性知识变成显式资产」这条老路在新工具下的加速。模型会一代代更换这份资产会一直增值。参考资料The New Skill in AI is Not Prompting, Its Context Engineering — Philipp SchmidEffective context engineering for AI agents — Anthropic EngineeringThe rise of context engineering — LangChain BlogContext engineering — Simon WillisonAGENTS.md 开放规范给编码智能体的仓库说明文件AGENTS.md Spec: Recommended Sections 与多工具生态对比 — Morph12-Factor Agents构建可靠 LLM 应用的原则含 Own Your Context Window— Dex HorthyClaude Code Best Practices — Anthropic Engineering从「对话式编程」到「规格驱动」民生银行企业级 AI 研发范式重构实践 — SegmentFault为什么上下文工程会取代提示词工程 — 51CTO 博客Harness Engineering真正决定 AI 编程效率的不只是模型 — 51CTO 博客spec-kitGitHub 开源的规格驱动开发工具包Vibe Coding 中文工程实践项目架构模板与质量门禁