Context Engineering实战：4个文件让AI编程助手真正读懂你的项目

问题出在哪

用Claude Code或Cursor写代码，前几周感觉效率翻倍。但用了三个月后，你会发现一个反复出现的问题：AI生成的代码不遵守你的项目规范。它不知道你上季度把REST换成了GraphQL，不知道你废弃了那个认证库，也不知道你的架构师刻意把每个服务控制在500行以内。

这不是模型能力的问题。GPT-4o、Claude 4、Gemini 2.5——底层推理能力都够用。问题在于上下文。每次新会话，AI都从零开始。你的项目规范、架构决策、踩过的坑，它一概不知。

2025年中，Anthropic和Sourcegraph的工程师给这个问题起了名字：Context Engineering（上下文工程）。2026年，越来越多的团队在实际项目中用上了这套做法。

Packmind今年1月的调查：91%的工程团队用了至少一种AI编程工具，但在同时用6个以上工具的团队里，只有28%的人对代码质量有信心。差距不在工具，在上下文。

Context Engineering 和 Prompt Engineering 有什么区别

很多人把这两个概念搞混。简单说：

Prompt Engineering管的是一句话怎么写。你调整措辞、加few-shot示例、换个语气，目标是让单次交互的输出更准。

Context Engineering管的是整个信息管道。你设计AI在每次推理时能看到什么——系统提示词、检索到的文档、对话历史、工具定义、长期记忆。Phil Schmid在2025年中说过：这是"在正确的时间，以正确的格式，给模型正确的信息和工具"。

判断你在做哪一个，看改动方向：改措辞、换形容词，还是Prompt Engineering；改检索逻辑、调上下文窗口管理、重新编排记忆层，就已经进了Context Engineering。

Sourcegraph 7.0的文档把Context Engineering拆成四根支柱，我在项目中验证过，好用：

  1. 指令层：系统提示词，定义角色、约束、输出格式
  2. 检索层：从向量数据库、文件系统、SQL按需拉取事实
  3. 记忆层：短期的对话历史 + 跨会话的长期偏好
  4. 工具层：AI可调用的函数定义和返回结果

随便哪层出问题，输出都会跑偏。好消息是第1层和第2层用几个文件就能搞定，不需要搭基础设施。

4个文件搞定项目级Context Engineering

下面是我在项目中用的方案。不用向量数据库，不用RAG管道，4个配置文件就能让AI把你的项目规范"记住"。

文件1：CLAUDE.md（Claude Code专用）

放在项目根目录，Claude Code每次启动自动读取。

# CLAUDE.md ## 项目概述 后端API服务，Python 3.12 + FastAPI，部署在AWS Lambda上。 数据库用PostgreSQL 16，ORM用SQLAlchemy 2.0。 ## 代码规范 - 函数命名：snake_case，不超过30个字符 - 类命名：PascalCase - 每个函数必须有type hints，包括返回值 - 禁止使用 `from module import *` - 异常处理：自定义异常类，不允许裸except ## 架构决策 - API层只做参数校验和响应包装，业务逻辑放service层 - service层之间不互相调用，需要共享逻辑提到common/ - 每个service文件不超过400行，超了就拆 ## 测试要求 - 测试文件放在同目录的tests/下 - 用pytest，不用unittest - mock外部依赖，不mock内部函数 - 每个公开函数至少2个测试用例（正常+异常） ## 踩坑记录 - SQLAlchemy 2.0的Session不要用旧版的query()语法，用select() - FastAPI的Depends不能放在函数体内做条件判断 - Lambda冷启动优化：把import放在函数外层

要点就一个：具体。别写"遵循clean architecture原则"，AI读了跟没读一样。写"service层不超过400行""mock外部依赖不mock内部函数"，这些才是它能照做的指令。

文件2：.cursorrules（Cursor专用）

Cursor读的是根目录的.cursorrules文件。格式和CLAUDE.md类似，但Cursor对结构化指令的响应更好：

# .cursorrules ## 技术栈 - Frontend: React 19 + TypeScript 5.8 + Tailwind CSS 4 - State: Zustand (不用Redux) - 路由: React Router 7 - 请求: 用原生fetch + 自定义的useApi hook，不装axios ## 组件规范 - 组件文件用PascalCase命名：UserProfile.tsx - 每个组件一个文件夹：组件代码 + index.ts + 测试 + 样式 - Props必须定义interface，命名为{ComponentName}Props - 不用forwardRef，用新的ref prop语法（React 19） ## 禁止事项 - 禁止any类型，用unknown替代 - 禁止在组件内定义接口请求函数，统一放services/ - 禁止直接操作DOM，用ref - 禁止使用class组件 ## 文件结构 src/ ├── components/ # 通用UI组件 ├── features/ # 按业务功能划分的模块 ├── hooks/ # 自定义hooks ├── services/ # API请求 ├── stores/ # Zustand stores ├── types/ # 类型定义 └── utils/ # 工具函数

文件3：.github/copilot-instructions.md（GitHub Copilot专用）

GitHub在2025年底给Copilot加了这个配置入口，很多人还不知道。

# Copilot Instructions 本项目是一个电商后台管理系统。 生成代码时遵守以下规则： 1. 所有金额字段用Decimal类型，不用float 2. 时间字段统一用UTC，显示时再转时区 3. 分页接口统一用cursor-based分页，不用offset 4. 日志用structlog，不用print或logging模块 5. 数据库迁移用Alembic，每个migration文件要有注释说明改了什么

文件4：CONVENTIONS.md（通用型）

不管用什么工具，这个文件都有用。在系统提示词里加一句"先读CONVENTIONS.md再开始工作"就行。

# CONVENTIONS.md ## Git规范 - 分支命名：feature/xxx, fix/xxx, refactor/xxx - commit message格式：type(scope): description - 每个PR不超过500行改动，超了拆 ## 代码审查标准 - 新增函数必须有文档字符串 - 新增API端点必须同步更新OpenAPI schema - 性能敏感操作（数据库查询、文件IO）必须记录耗时日志 ## 部署流程 - main分支自动部署到staging - 打tag后手动审批部署到production - 数据库migration和代码部署分开执行

实测效果：用Context文件前后对比

我拿一个3万行的FastAPI项目做了对比测试。任务：让AI新增一个订单导出接口。

没有CLAUDE.md时： - AI用了from sqlalchemy.orm import Session和旧版query语法（项目已经切到SQLAlchemy 2.0的select） - 异常用了裸except - 没写类型标注 - 测试文件放在了根目录的tests/而不是同目录下 - 手动修改：花了25分钟纠正

有CLAUDE.md后： - 自动用select语句 - 异常用了项目自定义的OrderExportError - 完整的type hints - 测试放在正确位置，覆盖了正常和异常两条路径 - 手动修改：3分钟，只调了一个查询条件

AI的推理能力没变，变的只是上下文。

三个常见的坑

1. 写太多

CLAUDE.md超过2000字，AI反而容易忽略后面的内容。Anthropic的文档提到过"context rot"——上下文越长，模型对其中信息的召回准确率越低。保持在500-1000字。规范太多就拆成多个文件，主文件里用路径引用。

2. 太抽象

"遵循SOLID原则"写了等于没写。AI需要的是"service层之间不互相调用""每个函数不超过50行"——可执行的具体规则。

3. 不更新

三个月前写的上下文文件，项目已经迭代了好几轮。文件里写着"用axios"，但你上个月换成了原生fetch。过期的上下文比没有上下文更糟，因为AI会很自信地按照错误的规范写代码。

建议把上下文文件的更新放进Sprint Review：每个迭代结束花10分钟检查一遍，把新的架构决策同步进去。

往后走：从文件到系统

4个文件是起点，够用但不够强。你的团队有十几个仓库的话，每个仓库维护一份上下文文件会变成负担。

AWS今年在Bedrock AgentCore里上线了AWS Context，从数据库、Slack、文档、邮件自动建知识图谱给Agent用。Sourcegraph 7.0做了代码级上下文索引。Packmind提出了ContextOps，把上下文的创建和分发当基础设施管。

但对大多数团队来说，这些平台级方案还早。先把那4个文件写好、保持更新，已经能盖住80%的上下文问题。

可以今天就做的事

  1. 在项目根目录建一个CLAUDE.md（或.cursorrules或copilot-instructions.md，看你用什么工具）
  2. 花20分钟把项目的技术栈、代码规范、架构决策、踩坑记录写进去
  3. 让AI根据这个文件生成一个函数，看看是不是自动遵守了你的规范
  4. 下个Sprint Review时检查一遍，更新过期的内容

20分钟写完，后面每次AI交互都少花纠错时间。别让AI猜，直接告诉它。