企业官网建设流程全解析

上下文工程这个词，最近在 AI 编码助手的使用者里出现频率越来越高。我见过不少朋友，花了一大把时间去搜安装配置教程，git 环境、Node.js、Maven、Python 一个个装好，编辑器里的扩展也配上了，结果打开项目问 AI 一句“帮我看看这个模块怎么优化”，得到的回答却像在说另一个项目。问题通常不在模型能力，而在上下文工程。AI 编码助手能写出多好的代码，不取决于你给它那句提示词写得多花哨，而取决于它启动之后能“看见”多少有效信息，以及这些信息是怎么组织、筛选、更新、传达到它面前的。

1. 上下文工程在 AI 编码助手里到底解决了什么问题

1.1 提示词工程管的是“说”，上下文工程管的是“看”

以前用聊天式 AI，大家讨论的是提示词工程：把需求描述得足够清晰，告诉模型角色、目标、输出格式，让它稳定产出。但把同样思路搬到 AI 编码助手里，很快就会碰壁。编码助手每一次补全、每一次对话，模型看到的绝不仅是你刚打出的那句请求，它还会看到当前文件内容、光标位置、编辑器里打开的其他文件、被检索出来的代码片段、终端里的报错、当前的 git 差异，甚至整个团队的代码规范。

这就带来一个关键变化：你光会“说”没有用，你还得让它“看到”。同一个请求“帮我把这个函数修好”，如果只丢一句话进去，模型不知道你的技术栈、不知道依赖版本、不知道项目里已有的同名工具方法、不知道这次改动的边界。但如果你把函数定义、调用方、测试、报错信息、相关模块约定都放进去，输出质量完全是两个级别。所以上下文工程更像是在搭一个“信息工作台”，目标是保证模型每次生成前，桌面上摆着它真正需要的资料。

1.2 为什么编码助手比聊天助手更依赖上下文工程

聊天助手的上下文通常就是当前对话历史，信息密度低、结构简单。代码库则完全不同，它是一个动态的、互相引用的、动辄上万文件的信息空间。变量、函数、类、模块之间的依赖关系散落在不同文件里，模型上下文窗口又有限，根本不可能把整个仓库一次性装进去。这时候只能做取舍：哪些文件被索引，哪些目录被忽略，哪些报错信息会附加进来，哪些规范会生效。

所以配置 AI 编码助手，本质不是“调参数”，而是在设计一套上下文筛选和排序机制。你可以让项目里最核心的模块优先出现在检索结果里，也可以把大量无关构建产物彻底排除在外。这种机制一旦建立，AI 编码助手才是真正“接入”了项目；否则它永远只是一个会说漂亮话的代码生成器，对工程本身一无所知。

2. 四层上下文配置的整体框架与依赖关系

2.1 四层划分：指令、仓库、工具、规范

我在实际项目里把上下文配置拆成了四层，每一层对应不同来源的信息，也对应不同的问题和配置位置。

为什么要分成四层而不是三层五层？因为这些信息的来源性质差异很大，刷新频率也不同。指令层相对静态，项目改了技术栈才需要更新；仓库层需要索引定期增量同步；工具层是秒级变化的实时状态；规范层则要跟着团队节奏走版本。把它们拆开，好处是出了问题可以直接定位：是哪一层没有覆盖到，还是某一层配置和另一层打架。

2.2 上下文预算：配置的本质是资源分配

上下文窗口是稀缺资源，这个约束很多新手没有意识到。模型处理能力有限，四层配置都会消耗“预算”。指令层写太长，留给真实代码的位置就少；仓库层召回太多无关文件，模型容易被垃圾信息带偏；工具层塞进一大段终端日志，同样会稀释注意力。所以我常跟团队说一句话：上下文工程就是上下文预算管理。

配置时要有成本意识。每个希望模型“看见”的信息，先问自己一句：它对当前任务是否必要？能不能用更短的形式表达？例如不要把几百行构建日志整个贴进去，而是提取关键报错行、退出码、相关调用栈。四层之间也不是孤立的。指令层能引导工具层去执行什么操作，仓库层检索结果需要工具层补充当前调用状态，规范层约束前几层最终产出的风格。缺了任何一层，都可能出现“理解了指令却找不到代码”“找到了代码却不符合规范”的情况。

3. 第一层：会话指令与任务上下文配置

3.1 指令应该放在哪里：从系统提示词到项目规则文件

第一层配置解决的是“模型知不知道自己在哪个项目里干活”。最稳妥的做法，是把项目的技术栈、常用命令、目录约定写进一个模型启动会话时就会自动读取的文件。以我常用的一个节奏为例，项目根目录放一个AGENTS.md，覆盖三块内容：项目一句话简介；常用命令（安装依赖、跑测试、构建）；关键目录和核心模块的功能说明。

不同 AI 编码助手的规则文件名字不一样，有的叫.cursorrules，有的读CLAUDE.md，有的支持copilot-instructions.md，但核心逻辑一致：凡是会自动加载进模型的仓库内文件，都是第一层配置的理想载体。需要留意的是这类文件一般有加载优先级，项目级规则通常只在当前仓库生效。如果你希望所有项目都带上某些基础习惯，那就放到编辑器或工具的用户级自定义指令里，不要写在某个仓库内。

3.2 我总结的任务简报模板

除了项目级规则，会话级任务上下文同样重要。每次发起一个复杂任务，我很少只丢一句话，而是先给出一份简短的“任务简报”。模板大概是这样的：

背景：订单模块的退款逻辑有 bug，线下环境测试时金额不一致。 目标：定位金额不一致的根因，并给出最小修复方案。 约束：改动不能影响优惠券分摊逻辑；不改变数据库表结构。 相关文件：src/order/refund.ts、tests/order/refund.test.ts 要求：先给出排查计划，再逐步修改，每步运行测试。

这个模板能够把模型每次决策需要的基础信息都放进上下文，效果比“帮我看看退款 bug 怎么修”好很多。模型不再需要反复猜测需求边界，也不会盲目动手。很多时候模型输出跑偏，真不是模型不行，而是上下文里根本没有这些边界条件。

3.3 配置指令时的三个反直觉结论

第一，指令不是越多越好。一个塞满冗长架构文档的规则文件，会给模型制造很高的认知负担。它可能只关注最后出现的那段内容，或者最长的一大段文字，而把真正重要的约定忽略掉。我现在会把规则文件限制在 30 到 60 行左右，超过的内容拆成独立文档，再在AGENTS.md里写一句“遇到某类任务先去读docs/rules/xx.md”。

第二，条件句式比祈使句更容易被遵循。写“当修改 API 时，必须在src/services中新增请求函数”，比写“要遵守服务层规范”有效得多。模型对具体触发条件比抽象口号更敏感。

第三，规则文件要像代码一样放进版本库，并定期 review。团队里某个人随手加了一条很随意的规则，可能导致 AI 生成风格突然变化。规则文件本质是给模型看的“程序”，它需要测试、需要迭代，也需要和代码同步维护。

4. 第二层：仓库索引与代码检索上下文配置

4.1 让助手“看见”整个代码库，而不是你粘给它的片段

第二层配置负责回答“项目里有什么”。很多 AI 编码助手并不是把代码全部塞进窗口，而是先通过索引构建一个可检索的代码图谱。新建项目后，它会扫描文件、分析符号、切分代码块、生成向量表示。之后你提问时，它先从索引里召回一批和当前问题相关的代码片段，再拼进上下文。

理解这一点很重要：配置仓库层，本质是在配置检索系统，而不是配置拷贝工具。如果项目里已经有现成的函数，AI 助手指却重写了一个同名功能，大概率不是模型偷懒，而是它根本没检索到你的既有代码，或者索引建立得不对。这种问题靠换模型解决不了，只能回头优化索引和检索逻辑。

4.2 索引范围控制：该排除什么比该包含什么更重要

索引配置里最该花心思的是排除规则，而不是引入规则。我见过不少项目，默认索引把node_modules、dist、build、.git、vendor、大型 lock 文件、二进制文件全部扫了进去。这些内容体积大，召回到上下文后更是灾难。

有一个真实案例：前端项目没有排除dist目录，里面存着打包后的压缩 bundle。AI 助手检索某个工具函数时，召回结果里既有源码片段又有压缩产物，模型直接迷失方向，生成的修改建议也完全不能用。后来把dist加入忽略列表并重建索引，问题立刻消失。不同的工具有不同配置方式，有的是直接遵守.gitignore，有的提供独立的 Ignore 列表。你需要花三分钟找到这个入口，这是第二层配置最关键的一步。

4.3 检索上下文的使用姿势：手动引用与自动召回

索引建好并不代表配置结束，日常使用时的“检索姿势”也很重要。我的原则是：能手动引用的核心文件，不要完全依赖自动召回。比如要改payment.ts，那就把payment.ts和它的主要调用方手动引用进来，再让助手去自动检索周边代码。自动召回适合开放式问题，比如“项目里有没有处理日期的工具”，适合让模型自己去翻；但涉及具体改动时，手动引用更可控。

还要熟悉自己所用工具里“重新建立索引”的入口。修改了.gitignore或升级工具大版本之后，旧索引可能还停留在之前的状态，导致搜索不到新文件。另外要注意检索结果的排序受模型和切片策略影响，会出现看似相关但实际不对应的情况，这时候不要硬撑着和模型争论，直接把正确文件引用进去，效率最高。

5. 第三层：工具链与编辑器状态上下文配置

5.1 实时上下文的来源

第三层解决的是“现在发生了什么”。它主要来自编辑器状态：当前打开的文件、光标位置、选中文本、其他打开的标签页；也来自语言服务诊断、终端输出、命令执行结果、git 差异和代码审查状态。这类信息变化非常快，但恰恰是 AI 编码助手最稀缺的输入。

很多工具默认会自动附加当前文件的内容，但这不一定是你想要的。我碰到过助手自动引用一个无关的配置文件，反而忽略了真正要改的业务模块。所以你需要花点时间检查工具栏的自动引用策略。如果默认行为是“自动附加所有打开的文件”，遇到大项目时上下文很快会被撑爆，建议改成手动引用或只附加当前活动标签页。

5.2 配置工具权限与 MCP 的边界

现在不少 AI 编码助手已经支持执行命令，或者通过 MCP 连接外部系统。这是第三层最有价值但也最有风险的部分。我的配置原则是：默认最小权限，逐项授权。允许它执行项目内的pnpm test、pnpm build，不代表允许它跑系统级命令；允许读取构建日志，不代表允许它自动上传文件或者修改全局配置。

工具层的配置示意大概是这样的，具体字段不同工具会不一样：

{ "tools": { "run_command": { "allowedPrefixes": ["pnpm test", "pnpm build", "node scripts/"] }, "read_terminal": true, "mcpServers": ["local-git"] } }

如果你接入了 MCP server，一定要确认服务器来源。不要因为图方便，就把一个来路不明的 MCP 地址写进配置，它可以读取你本地的私有代码甚至把内容发给外部服务。定期翻一翻助手的工具调用日志，也是好习惯，看到超出预期的行为就立刻收窄权限。

5.3 编译报错场景下的上下文投喂实操

举一个高频场景：编译报错，你想让 AI 修复。直接把一整屏错误日志丢给它，效果通常不好。更实用的做法是组织一个“诊断包”，至少包含四个要素：报错消息中的关键行和错误码、对应的文件路径与函数签名、这个函数最近有没有被改过（git log 摘要）、你期望的正确行为是什么。

比如我遇到“Vue 项目里ref类型报错：No overload matches this call”时，不会只贴报错，还会补充：位置在checkout.ts第 23 行，最近一次提交改动了这里的金额计算逻辑，我怀疑是类型收窄问题。把这些信息喂进去以后，AI 给出靠谱修复方案的概率会非常高。如果你还希望助手自己跑命令，那就要给它执行测试的权限，并让它读取输出。不过建议保留人工确认步骤，不要让它在无人监督的状态下连续改多个文件，否则真的会把项目改坏。

6. 第四层：团队规范与流程上下文配置

6.1 版本化、收敛、可复现的团队配置

个人配置可以随意，团队配置必须像代码一样被管理。第四层的目标是把规范上下文放进仓库，写清楚什么时候生效，并且允许所有人 review。比如可以在仓库里维护这样一个结构：

.rules/ general.md frontend.md backend.md commit-message.md AGENTS.md

AGENTS.md作为入口文件，简单写明每个规范文件的用途，对应的详细规则放在独立文件里。支持路径匹配规则的工具，还可以配置backend/**只加载backend.md，前端目录同理。这样每个文件都不长，但合在一起能覆盖整个团队的核心约定。

团队配置一旦失效，最常见的原因是没人维护。规则文件和源码一样，会随着项目演进而过时。新成员加入时如果直接照抄旧规则，AI 编码助手生成的东西就可能与现状脱节。所以要给它分配一个 owner，和代码 review 一样推进更新。

6.2 规范文件的目录设计与优先级

如果所有规范都堆在一个文件里，模型遵循起来很困难，所以我建议按“通用—框架—模块”三层拆分。通用规则包含语言基础风格、变量命名、注释要求；框架规则包含组件写法、目录结构；模块规则只针对特定业务模块，比如订单、支付、用户中心。通用规则写在最前面，模块规则越靠近任务越好。

还要明确优先级。用户级自定义指令和项目级规则冲突时，项目级规则应该赢。但模型有时候会犹豫，所以可以在规则文件开头写一句：“如果与其他规则冲突，以本文件为准，除非涉及安全或权限要求。”这句能减少大量随机行为。

另外，规范不要写成“代码要清晰、注释要完整”这种无法验证的句子，要写成模型能判断的形式。“组件 props 使用 TypeScript 类型定义，禁止使用any；公共函数必须写 JSDoc；接口返回统一为{ code, message, data }。” 模型对可验证的约束响应明显更好。

6.3 流程上下文：把提交、评审、收录进助手的工作流

第四层不只是代码风格，还包括流程。提交信息模板、PR 描述模板、issue 关联方式都可以通过规则文件交给模型。比如在commit-message.md里定义：

提交信息格式：<type>(<scope>): <subject> type 只能取 feat / fix / refactor / docs / style / test / chore scope 为模块名，subject 不超过 50 字 关联 issue：在正文末尾加 #issue

这样每次让助手生成 commit message，输出的格式都会很稳定。PR 描述也一样，把模板写到规则文件里，让助手基于 git diff 生成“改动说明、影响范围、测试方式”三个小节。团队里的规则一旦更新，走 review 流程，避免出现互相矛盾的指令。否则过了两个月，规则文件又长又乱，AI 编码助手的表现也会跟着飘忽不定。

7. 分层配置落地排查与我的实操心得

7.1 从“输出不对”反推是哪一层出了问题

四层配置都上手以后，遇到问题一定要按层次定位，不要急着换模型或者改提示词。这里有一套我很常用的症状映射，可以先判断哪一层有异常：如果助手反复问“你们项目用什么包管理器”“测试命令是什么”，那第一层指令没配好；如果它生成的函数完全没有用项目里已有的工具类，第二层仓库索引或检索有问题；如果它不知道你刚改了什么代码、找不到当前报错，第三层工具上下文没接上；如果代码风格、命名、提交信息不符合团队规范，第四层规范没配置好或者规则没被加载。

不过要注意，实际问题往往不是单层导致的。比如助手“造轮子”，可能同时因为仓库索引没建好和指令层没有告诉它现有模块的位置。所以定位到某一层后，还要顺手看一下前后两层有没有相关信息缺失。

7.2 配置验证的五个检查点

配置完成后不要直接开始开发，先跑一轮验证，我一般会检查五点。第一，开新会话，问一句“请总结一下这个项目是做什么的、有哪些常用命令”，看模型能不能答出规则文件里的信息。第二，用检索式问题问“项目里有没有做金额计算的工具”，看能不能命中正确文件。第三，故意制造一个编译错误，看模型是基于实时错误回答还是凭空猜测。第四，让模型生成一条 git commit message，看是否符合团队模板。第五，打开工具的 prompt 或 trace 日志，检查实际送给模型的上下文里有没有你配置的内容。

前四点都过了，说明配置大体生效。如果第五点过不了，那前面的表现只能算运气好。一些工具会提供“查看本次请求发送给模型的内容”的调试入口，建议有空就点开看看，那是理解上下文工程最快的途径。

7.3 一些容易踩的坑和必须守住的底线

最后说几个我踩过的坑。第一，上下文污染远比“缺少上下文”常见。为了保险，把整个设计文档、整个项目目录、几百行日志全塞给模型，结果关键信息被淹没在无关内容里。宁可少给，也要给高密度信息。

第二，规则文件里不要放任何密钥、token、密码或者内网地址。AGENTS.md会进入模型上下文，也可能随仓库被分发出去，这是咱们做配置时最容易忽视的泄露面。第三，别给 AI 编码助手“无限执行命令”的权限。允许它构建、测试是合理的，允许自由改动文件要阶梯式放行，而且每一步尽量可回溯。

第四，配置需要渐进式迭代，不是一次装完就结束。我现在的习惯是每换一个大型仓库，就重新做一遍四层检查：看AGENTS.md是否过时、索引排除是否合理、工具权限是否收窄、团队规范是否生效。上下文工程这件事越往后越像维护一个持续变动的项目基础设施，它不需要一次做到完美，但需要你把它当成代码库的一部分来认真对待。