企业官网建设流程全解析

目录

一、大多数失败不是提示词写坏了

（一）三个流传最广的认知陷阱

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 块禁止 return；IO 与数据库资源必须用 try-with-resources 关闭。这四条针对的都是模型高频生成的「看起来能跑」的代码——空 catch 在生成代码里的出现率高得惊人，因为大量训练语料里的示例代码就是这么偷懒的。

1.2、数据与并发

金额一律 BigDecimal，禁止 float/double 参与金额运算；集合声明用接口类型；可能返回空的方法用 Optional 或注解标明。并发侧：禁止 Executors 工厂方法，线程池必须显式配置核心参数；阻塞队列必须指定容量；禁止业务代码里临时创建线程池。

1.3、敏感数据

手机号、身份证、银行卡号禁止明文进日志，必须走统一脱敏工具；API 响应中的敏感字段必须加脱敏注解；密钥凭据禁止硬编码，一律走凭据管理服务。这一档规则的特殊性在于违反的后果是合规事故而不只是缺陷，因此除了写进上下文，还必须配静态扫描兜底——上下文负责让模型第一次就写对，扫描负责万一没写对时拦住。

2、偏好级：默认遵循

单行不超过 120 字符、K&R 大括号风格、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, It's Context Engineering — Philipp Schmid
• Effective context engineering for AI agents — Anthropic Engineering
• The rise of "context engineering" — LangChain Blog
• Context engineering — Simon Willison
• AGENTS.md 开放规范：给编码智能体的仓库说明文件
• AGENTS.md Spec: Recommended Sections 与多工具生态对比 — Morph
• 12-Factor Agents：构建可靠 LLM 应用的原则（含 Own Your Context Window）— Dex Horthy
• Claude Code Best Practices — Anthropic Engineering
• 从「对话式编程」到「规格驱动」：民生银行企业级 AI 研发范式重构实践 — SegmentFault
• 为什么上下文工程会取代提示词工程 — 51CTO 博客
• Harness Engineering：真正决定 AI 编程效率的，不只是模型 — 51CTO 博客
• spec-kit：GitHub 开源的规格驱动开发工具包
• Vibe Coding 中文工程实践：项目架构模板与质量门禁