朝花夕拾
RSS 订阅
教程·阅读约 5 分钟·
AI 编码代理的上下文工程实战指南：让 Cursor、Claude Code 听懂你的项目

AI 编码代理的上下文工程实战指南：让 Cursor、Claude Code 听懂你的项目

从 CLAUDE.md 到 Skills，系统学习如何通过上下文工程让 AI 编码代理更精准地理解项目结构和编程偏好

原创。本文教你一套系统化的上下文工程方法：从 CLAUDE.md 到 Rules、Skills、MCP Server，逐层配置 AI 编码代理，让它写代码更准、更稳、更符合你的项目风格。

为什么需要上下文工程？

如果你用过 Cursor 或 Claude Code，很可能遇到过这种情况：你让它改一个文件，它把整个项目的代码风格改乱了。你要求它写测试，它按照自己的理解创建了一堆不需要的 mock。你告诉它「用 pnpm」，它每次都会先用 npm 试试。

这不是 AI 不够聪明，而是它不知道你项目的规矩。

AI 编码代理本质上是「无状态」的——每次对话开始时，它对你的项目一无所知。它知道 TypeScript 怎么写，但不知道你的团队约定类名用 PascalCase 还是 camelCase，不知道你的测试框架用的是 Vitest 还是 Jest，不知道你的 API 风格是 REST 还是 tRPC。

上下文工程（Context Engineering），就是主动告诉 AI 代理这些信息。Martin Fowler 网站上的定义很精炼：「策划模型能看到的内容，以获得更好的结果。」

这不是锦上添花，而是从「AI 能帮你写代码」到「AI 能写好你的代码」的关键一步。

—— 广告 ——

上下文的两层结构

AI 编码代理的上下文可以分为两层：

第一层：可复用的提示（指令 + 规则）

这一类是静态的文本内容，每次 AI 代理启动时自动加载。它告诉代理：

  • 指令（Instructions）：怎么做某件事。「写测试时优先用 integration test，不要 mock 外部服务」
  • 规则/护栏（Rules/Guardrails）：什么事不能做。「不要修改 .env 文件」「私有方法用 _ 前缀」

这两者的界限其实很模糊，但区分的价值在于：指令是「怎么做更好」，规则是「不能怎么做」。

第二层：上下文接口（代理可以主动获取更多上下文）

AI 代理不仅能读取初始加载的文本，还能主动去获取更多信息：

  • 工具（Tools）：内置能力，比如搜索文件、读目录结构、执行 shell 命令
  • MCP Server：通过 Model Context Protocol 连接外部系统的自定义工具（数据库、JIRA、浏览器）
  • Skills：按需加载的描述、文档、脚本，AI 认为相关时会自动读取

这两层不是替代关系，而是互补。第一层提供「全局默认值」，第二层提供「按需扩展能力」。

CLAUDE.md：项目的默认大脑

什么是 CLAUDE.md？

CLAUDE.md 是 AI 编码代理在项目启动时自动读取的 Markdown 文件。它的作用相当于「给 AI 的项目简介」——告诉 AI 这个项目用什么技术栈、有什么约定、怎么运行。

这个概念起源于 Claude Code，但现在已经被大部分主流 AI 编码工具采用：Cursor、GitHub Copilot 都支持类似机制。社区也在推动将其标准化为 AGENTS.md，让不同的 AI 工具共享同一套配置。

我在 CLAUDE.md 里放什么？

一个好的 CLAUDE.md 应该包含以下内容：

技术栈声明

code
# 项目
这是一个 Next.js 15 项目，使用 App Router。
- 包管理：pnpm
- 样式方案：Tailwind CSS v4
- UI 组件库：shadcn/ui
- 数据库：PostgreSQL via Prisma
- 测试：Vitest + Playwright

核心约定

code
# 编码约定
- 组件用箭头函数 + 显式 Props 类型
- 文件命名：kebab-case
- 路由组 (Route Group) 用 (marketing), (app), (auth)
- Server Component 优先，只在交互点加 "use client"
- API Route 放在 app/api/ 下
- 所有数据库查询走 Prisma Service 层，不直接在路由里写 SQL

常用命令

code
# 命令
- 开发：pnpm dev
- 构建：pnpm build
- 测试：pnpm test
- Lint：pnpm lint
- 数据库迁移：pnpm prisma:migrate

架构决策记录

code
# 架构决策
- 2026-01-15：从 tRPC 迁移到 Server Actions，减少样板代码
- 2026-03-01：引入 Drizzle ORM 替代 Prisma（查询性能提升 40%）

CLAUDE.md 的编写原则

不要写 AI 能自己推理出来的东西。 比如「JavaScript 是一种编程语言」——这种信息对 2026 年的 AI 编码代理来说是侮辱智商。

重点写「异常值」。 如果你们的命名规范是 snake_case（而行业标准是 camelCase），那必须写。如果你们用的框架有小众版本，必须写。

先少后多，迭代添加。 不需要在第一天就写一个 500 行的 CLAUDE.md。从 10 条核心规则开始，随着使用发现问题再补充。

Rules（规则文件）：精细控制的范围

CLAUDE.md 是全局生效的。但有些规则只对特定路径或文件类型生效，这时候就需要 Rules。

Rules 解决什么问题？

想象这个场景：你的项目同时包含前端 TypeScript 和后端 Python。对前端文件，你希望 AI 用 import type 而不是 import（Tree Shaking 优化）。对后端文件，你希望它用 from __future__ import annotations。

写在 CLAUDE.md 里？那前后端都生效，Python 文件里出现 import type 会很奇怪。

这时候 Rules 就派上用场了。你可以按路径或文件类型组织规则：

code
rules/
├── react-components.md    # 作用域：components/**/*.tsx
│   └─ "用 'use client' 仅当需要交互状态"
├── api-routes.md           # 作用域：app/api/**/route.ts
│   └─ "每个 API Route 都需要 rate limiting 和输入验证"
└── python-models.md        # 作用域：backend/**/*.py
    └─ "用 Pydantic v2 的 Field 做验证"

在 Cursor 中设置 Rules

Cursor 的设置路径：Cursor Settings > General > Rules for AI。这里有三个层级：

  1. 全局 Rules：适用于所有项目（例如「始终用 TypeScript strict mode」）
  2. 项目 Rules：在项目根目录的 .cursor/rules/ 下（例如「只在 pages 目录用 getServerSideProps」）
  3. 自动 Rules：AI 根据当前打开文件的上下文动态推断（不需要手动配置）

Rules 的优势在于精细化和可维护性。你可以把 50 条规则分散到 10 个文件里，每个文件只负责一个领域。当某个领域约定变化时，只改一个文件。

Context 工具：看到 AI 的「脑子里」

这是最容易被忽略但最有用的功能。所有主流编码工具都有查看当前上下文的命令：

工具命令功能
Claude Code/context显示当前的上下文大小、构成和关键文件
CursorCmd+I → @Files手动添加文件到上下文
GitHub Copilot#file / #codebase引用特定文件或整个代码库

为什么这很重要？ 因为如果你不确定 AI 知道什么，你就无法判断它的输出为什么有问题。

我见过的最常见的调试场景：开发者抱怨「AI 写错了」，打开上下文一看，发现它根本没读到关键文件的配置。不是 AI 的问题，是上下文不够。

定期检查上下文的习惯：每次交给 AI 一个复杂任务前，先执行 /context 确认它看到了哪些文件。如果关键文件不在上下文中，手动添加。

Skills：按需加载的知识库

Skills 是比 CLAUDE.md 更高级的上下文管理方式，2025 年末由 Claude Code 引入，现在 Cursor 也有类似功能。

Skills 和 CLAUDE.md 的区别

特性CLAUDE.mdSkills
加载方式每次会话自动加载AI 判断相关时按需加载
大小限制建议 1-2KB可容纳完整 API 文档
内容类型规则/约定文档/教程/参考
触发条件无（始终加载）AI 检测到相关主题

理解这个区别的关键：CLAUDE.md 是「高速公路上的限速标志」，每次上路都看到。Skills 是「路边的维修手册」，只有爆胎时才需要打开。

Skills 适合放什么内容？

  • 详细的 API 集成文档：比如 Stripe API 的完整调用流程
  • 复杂的业务逻辑说明：比如「订阅状态的有限状态机」
  • 团队特有的开发流程：比如「从 fork 到 PR 的完整步骤」
  • 环境特有的配置：比如 CI/CD pipeline 的结构和触发条件

Skills 的使用场景

例如你的项目集成了 Stripe，CLAUDE.md 只需要写一行：

code
支付: Stripe API，详见 Skills 中的 stripe-integration.md

然后在 Skills 目录下放一个 stripe-integration.md，包含完整的 webhook 处理流程、测试卡号、错误处理模式。

当 AI 需要处理支付相关功能时，它看到 CLAUDE.md 中的引用，就会自动加载 Skills 中的详细文档。如果它在处理 UI 组件，Stripe 的 Skills 永远不会加载——不浪费上下文空间。

MCP Server：连接外部世界

当上下文信息需要从外部系统实时获取时，MCP（Model Context Protocol）Server 是最佳选择。

什么时候需要 MCP？

  • 代码评审需要从 JIRA 读取 ticket 上下文
  • 构建时需要查询 GitHub Issue 状态
  • 测试时需要从数据库拉取最新的 schema 信息
  • 前端开发需要从 Figma 获取设计 token

一个典型的 MCP Server 示例

假设你想让 AI 代理能查询项目文档库：

code
from mcp.server import MCPServer
 
mcp = MCPServer("Project Docs")
 
@mcp.tool()
async def search_docs(query: str) -> str:
    """搜索项目内部文档"""
    # 调用内部文档搜索 API
    results = await docs_api.search(query)
    return format_results(results)
 
@mcp.resource("doc://{path}")
async def get_doc(path: str) -> str:
    """按路径获取文档内容"""
    content = await docs_api.get(path)
    return content

一旦配置了这个 MCP Server，AI 代理可以在需要时主动查询文档，而不需要你把整个文档库塞进上下文。

上下文管理的核心原则

原则一：够用就行

上下文不是越多越好。即使有了 200K 的上下文窗口，塞满噪音仍然会让 AI 变笨。每条规则都应该问自己：「没有这条规则，AI 第一次尝试的失败概率是多少？」如果概率很低（<10%），删掉。

原则二：渐进式构建

CLAUDE.md、Rules、Skills、MCP 这四层是有层级顺序的。建议从最顶层开始，每次只加一层，运行至少一周后再决定是否需要下一层：

  1. 第 1 周：只配 CLAUDE.md（项目基本规则）
  2. 第 2 周：添加 Rules（路径级精细控制）
  3. 第 3 周：添加 Skills（按需加载的文档库）
  4. 第 4 周：考虑 MCP（如果需要外部系统集成）

原则三：分享有价值，照搬无意义

网上有很多人分享自己的 CLAUDE.md 配置，看起来很壮观。但不要直接复制到你的项目里。原因有两个：

  1. 过度工程化：别人的配置针对的是他们的项目和 stack，90% 的规则对你没用
  2. 冲突风险：两个配置可能对同一个问题有不同约定，AI 无法判断哪个优先

如果有参考价值，应该消化吸收后只提取对你有用的几条。

从零开始的完整配置流程

让我用一个实际案例串起来。假设你有一个 Next.js + Tailwind + Prisma 的全栈项目，之前从未配置过 AI 上下文。

第一步：创建 CLAUDE.md

在项目根目录创建 CLAUDE.md：

code
# 项目概览
SaaS 应用：Next.js 15 (App Router) + Tailwind CSS v4 + Prisma + PostgreSQL
 
# 编码约定
- 组件：箭头函数 + 显式 Props 类型
- 文件名：kebab-case
- Server Component 优先，只在交互处加 'use client'
- API Routes：放在 app/api/ 下，所有输入用 Zod 验证
- 数据库：Prisma Service 模式（不直接在路由里查询）
- CSS：Tailwind utility class，不写自定义 CSS
 
# 常用命令
- 启动：pnpm dev
- 构建：pnpm build
- 测试：pnpm vitest
- DB Studio：pnpm prisma:studio
- 迁移：pnpm prisma:migrate dev

第二步：添加目录级 Rules

在 .cursor/rules/ 下创建：

code
# .cursor/rules/prisma-schema.md
- 只在 schema.prisma 中添加新模型
- 所有模型必须有 id (String, @id @default(cuid()))
- 用 createdAt/updatedAt 而不是 timestamps
- 关联用 @relation 显式声明外键
code
# .cursor/rules/redis-integration.md
- Redis 操作封装在 lib/redis/ 的 service 类中
- 不要直接在 API Route 中操作 Redis
- 缓存 key 命名：module:entity:id

第三步：检查上下文

在 Cursor 中按 Cmd+I，输入 / 确认 Rules 已生效。在 Claude Code 中执行 /context 查看加载的上下文大小。

第四步：迭代优化

使用一周后，观察 AI 最常在哪类任务上犯错，针对性地补充规则。不要把第一版搞得太完美，先跑起来再说。

写在最后

上下文工程不是一次性的设置，而是一个持续迭代的过程。随着项目增大、技术栈变化、AI 模型升级，你的上下文配置也需要更新。

一个简单自检标准：如果你发现 AI 连续三次在同一个问题上犯错（比如不断用 npm 而不是 pnpm），那说明你的上下文没覆盖到这个问题。补上它，问题就解决了。

上下文工程的价值不在于写了多长的配置文件，而在于让 AI 犯更少的低级错误。每多一条有效的规则，就少一次「居然又犯这种错」的叹气。

参考来源：Martin Fowler - Context Engineering for Coding Agents、Claude Code Documentation

AI编程上下文工程CLAUDE.mdCursorClaude Code编码代理
分享到
微博Twitter

© 2026 四月

原文链接：https://www.aprilzz.com/tutorials/ai-context-engineering-guide

相关文章

AI 编码代理的提示词工程实战指南

系统提示、任务描述、上下文管理——让 AI 编码代理产出高质量代码的提示词技巧，涵盖五种实战模式和大量可复用的提示模板。

AI 编程代理的「反压」验证体系：让你的代码代理学会自我审查

用编码代理写代码又不放心？这篇文章提供了完整的验证框架——从 lint 检查到评审代理到 PR 监控，七层机制让 AI 在提交前先把自己的问题修好

用 AI 编程工具写代码的五个实战原则：从能用到好用的距离

AI 编程助手已经成为日常工具，但很多人只停留在让它写代码的层面。这篇文章分享五个实战原则，帮你把 AI 从代码生成器变成真正的编程搭档。