给 AI 提供项目上下文

新项目刚开始时，你可以直接说“帮我加一个登录页”，AI 大概率能猜到你要什么。项目一大，情况就变了：目录里有历史代码，有约定，有不能碰的模块，还有一些只在团队里口口相传的规则。

如果这些背景不告诉 AI，它只能靠搜索和猜测。猜对时很顺，猜错时就会出现熟悉的问题：文件放错目录、重复造工具函数、绕开已有封装、改了不该改的接口。

项目上下文就是把这些“做事前应该知道的东西”整理给 AI。

先区分短期上下文和长期上下文

短期上下文是当前这次对话需要的信息。比如你这次要修登录错误，就给登录页、auth 请求、错误日志、相关接口文件。任务结束后，这些信息不一定还需要出现。

长期上下文是项目里持续有效的规则。比如技术栈、目录分层、命名习惯、API 响应格式、哪些目录不能随便改。这些适合写进 README、架构说明或 Cursor Rules。

不要把两者混在一起。你把一次 bug 的日志写进 Rules，后面每次对话都会带着这段无关信息；你把稳定的目录约定只放在某次聊天里，换一个聊天 AI 又忘了。

新项目：先让 AI 建立地图

刚打开一个项目时，不要急着让 AI 直接改。先让它读结构，形成一张粗略地图：

请先理解这个项目结构，不要修改文件。

请输出：
- 主要技术栈
- 入口文件在哪里
- 前端页面、后端接口、共享工具分别放在哪里
- 当前项目里已有的命名和分层习惯
- 如果我要新增一个“用户资料编辑”功能，大概会涉及哪些目录

如果项目有 README，先引用 README；如果 README 太旧，就直接说明“README 可能不完整，请以当前文件结构为准”。这句话很有用，能避免 AI 被过期文档带偏。

你也可以让 AI 生成一份项目说明草稿，然后自己删改：

根据当前项目结构，帮我生成一份给 Cursor 使用的项目上下文说明。
要求短一点，只保留会影响代码生成的约定。
不要写产品愿景，不要写历史背景。

这份说明可以放进 .cursor/rules/project-overview.mdc，也可以先放在项目文档里。关键是你要 review 一遍，别把 AI 猜错的内容沉淀成长期规则。

大项目：不要一次喂整个仓库

大项目最容易犯的错是：任务还没说清楚，就先让 AI “看一下整个项目”。上下文窗口有限，文件越多，注意力越散。

更好的方式是按任务选上下文：

我要修复“修改邮箱后用户资料页仍显示旧邮箱”的问题。

请先只看这些上下文：
@src/pages/profile
@src/modules/user
@src/lib/api/user.ts

目标：
- 找出资料页数据没有刷新的原因
- 不改登录、注册、权限模块
- 如果需要更多文件，请先说明原因

这段提示词里有一个重要句子：“如果需要更多文件，请先说明原因”。它会让 AI 在扩大范围前停一下，而不是直接把半个项目翻出来一起改。

当你不知道入口在哪里，可以先用 Ask 模式让 AI 搜索和解释，不要直接进入 Agent 修改：

我不熟悉这个项目。
请帮我找“用户资料页保存邮箱”的调用链。
只输出相关文件和函数，不要修改代码。

找到调用链后，再把任务收窄给 Agent。

哪些信息值得放进项目上下文

值得长期保留的信息，应该是稳定、重复、会影响 AI 决策的内容。

比如：

• 技术栈和关键版本范围
• 目录职责，例如页面、组件、接口、工具函数分别放哪里
• 命名规则，例如 hook、service、schema、test 文件怎么命名
• API 响应格式和错误处理方式
• 状态管理、数据请求、表单处理的统一方案
• 不能随便改的边界，例如迁移脚本、公共 SDK、兼容旧版本的接口

一个最小项目上下文可以这样写：

# Project Context

This is a Next.js + TypeScript app.

Directory conventions:
- Page routes live in `src/app/`.
- Shared UI components live in `src/components/`.
- API client functions live in `src/lib/api/`.
- Domain types live in `src/types/`.

Coding conventions:
- Do not call `fetch` directly in React components.
- Keep API response handling inside `src/lib/api/`.
- Prefer existing UI components before creating new ones.
- Do not change public API response fields unless the task explicitly asks for it.

它不长，但能影响很多生成结果：文件放哪里、请求怎么写、什么时候不能改接口。

哪些信息不该放

不相关的信息会污染上下文。AI 不会因为你给得多就更懂项目，它只会背着更多噪音工作。

这些内容通常不适合放进长期上下文：

• 某一次线上事故的完整复盘
• 已经过期的产品路线
• 和当前代码无关的会议记录
• 大段接口文档原文
• 临时实验分支的设计想法
• “代码要优雅、清晰、可维护”这类没有操作细节的话

如果某份文档很重要，但很长，不要整篇塞进 Rules。可以写一句索引：

支付相关改动必须先阅读 `docs/payment-contract.md`。
不要在未确认回调签名规则前修改支付回调逻辑。

真正需要做支付任务时，再用 @file 把那份文档加入当前对话。

一个搭配方式

假设你在做一个 SaaS 项目，长期上下文可以放这些：

项目使用 Next.js + TypeScript。
租户隔离字段是 tenantId，所有服务端查询都必须带 tenantId。
API 请求统一放在 `src/lib/api/`。
不要在页面组件中直接访问数据库。

当前任务上下文再补具体材料：

@src/app/settings/team/page.tsx
@src/modules/team
@src/lib/api/team.ts

我要给团队设置页增加“邀请成员”功能。
要求：
- 保持现有 tenantId 校验方式
- 复用已有 Modal 组件
- 不改 billing 模块

长期上下文负责告诉 AI “这个项目平时怎么做事”，短期上下文负责告诉它 “这次具体看哪里、别碰哪里”。两者配合好，Cursor 才不需要每次从零猜。

让上下文保持可维护

项目上下文不是写一次就结束。每当你发现 AI 反复犯同一个错，就问一句：这是临时任务没说清，还是项目规则没有沉淀？

如果是临时任务，下次 prompt 写清楚就行。如果是项目规则，比如“所有接口都要返回 { data, error }”，就应该进 Rules 或 README。

我建议每隔一段时间删一删 Rules。删掉过期约定，改掉含糊句子，保留真正会影响生成结果的内容。上下文越干净，AI 越容易做对当前这一步。

给 AI 提供项目上下文

AI 能不能理解你的项目，取决于它看到的材料是否足够准确。新项目里，它不知道你的目录打算怎么长；大项目里，它可能看得到很多文件，却不知道哪些才是当前约定。

给 AI 提供项目上下文，不是把所有东西都塞进聊天框，而是把“长期稳定的信息”和“这次任务需要的信息”分开处理。

新项目：先给它一个方向

刚开始搭项目时，你可以让 AI 帮你建结构，但不能只说“做一个 SaaS 项目”。这个描述太宽，AI 会按它见过的模板生成一套东西，未必适合你。

更好的方式是先给项目边界：

我要做一个面向个人开发者的订阅制工具站。

技术栈：
- Next.js + TypeScript
- Tailwind CSS
- PostgreSQL

第一阶段只做：
- 登录
- 项目列表
- 新建项目
- 订阅状态展示

暂时不要做：
- 团队协作
- 管理后台
- 多语言

请先设计目录结构和核心页面，不要直接写完整业务代码。

这段上下文把“项目是什么”“先做什么”“不要做什么”说清楚了。AI 更容易给出可执行的第一版，而不是生成一个看起来很完整、实际上维护不动的骨架。

大项目：先让它读地图

在已有项目里，AI 最缺的不是代码，而是地图。它需要知道入口在哪里、模块怎么分层、哪些文件是旧实现、哪些文件是现在应该参考的写法。

你可以先让它做一次只读梳理：

@README.md
@src

请先帮我理解这个项目结构。
重点回答：
- 应用入口在哪里
- 页面、组件、接口请求分别放在哪
- 新增一个用户设置页大概要改哪些位置
- 哪些目录看起来像历史遗留，先不要动

不要修改文件。

如果项目很大，不建议一上来 @src。可以先给 README、路由目录和一个典型模块。等它回答后，再补具体文件。

短期上下文和长期上下文

短期上下文是这次对话需要的信息。比如当前 bug 的报错、目标文件、你刚刚做过的尝试。它适合放在聊天里，任务结束后就可以忘掉。

长期上下文是项目稳定约定。比如技术栈、目录结构、命名规范、测试要求、不能随便改的公共接口。它适合放在 README、项目文档或 .cursor/rules/*.mdc 里。

一个项目可以这样分：

长期上下文：
- 项目用 Next.js App Router
- API 请求统一走 src/lib/api
- UI 组件优先复用 src/components/ui
- 不直接在页面里访问数据库

短期上下文：
- 这次要修订单页分页
- 错误现象是第 2 页仍显示第 1 页数据
- 相关文件是 orders 页面、useOrders hook、orders API

不要把短期任务写进 Rules。比如“这周要重做订单页”放进长期规则，过两周就会变成误导信息。

该放什么

值得提供给 AI 的上下文通常有这些：

• 技术栈和关键版本，比如 Next.js、Vue、FastAPI、数据库类型
• 目录结构，尤其是页面、组件、接口、模型分别放哪
• 项目自己的约定，比如错误响应格式、权限判断位置
• 当前任务的相关文件和错误信息
• 一个质量好的同类实现，让 AI 有样板可参考
• 不能动的边界，比如公开 API、数据库 schema、老页面兼容逻辑

如果你让 AI 新增一个“导出 CSV”功能，可以这样给：

@src/modules/users
@src/lib/csv.ts

这个项目的后端接口按 controller -> service -> repository 分层。
请参考 users 模块，新增用户导出 CSV 的能力。

约束：
- 不改现有列表接口
- 数据量可能超过 10 万行，不能一次性全部放进内存
- CSV 工具函数优先复用 @src/lib/csv.ts

这比“帮我加导出功能”稳定得多。

不该放什么

上下文太多会污染判断。下面这些信息通常不适合直接塞进去：

• 和当前任务无关的目录
• 很长的历史会议记录或开发日志
• 已经过期的方案讨论
• 你自己也不确定对不对的猜测，却没有标注“只是猜测”
• 密钥、token、内部账号、生产数据库连接串

安全信息尤其不要给。AI 不需要真实密钥才能帮你写配置读取逻辑，用占位符就够了。

DATABASE_URL=postgres://user:password@localhost:5432/app
STRIPE_SECRET_KEY=sk_test_xxx

如果它需要理解环境变量，给变量名和用途，不给真实值。

一个项目说明模板

你可以在新聊天开始时贴一个短版项目说明，也可以把稳定部分整理到 README 或 Rules：

项目背景：
这是一个给开发者使用的 AI 学习网站，内容用 VitePress 管理。

技术栈：
- VitePress
- Markdown 文档
- TypeScript 配置

目录约定：
- docs/ 存放页面正文
- docs/app-dev/ 是 AI 应用开发路线
- docs/vibe-coding/ 是 AI 编程工具路线

写作约束：
- 面向已有编程基础的开发者
- 页面要像课程正文，不要只列提纲
- 不要写没有来源的具体产品能力

本次任务：
请补齐某个占位页面，保留现有导航结构。

这份说明不长，但足够让 AI 不至于把课程站写成个人博客，也不会误改配置。

让 AI 自己复述一遍

在重要任务开始前，可以先让 AI 复述它理解的项目上下文：

在开始修改前，请先用 5 行以内复述你对这个项目结构和本次任务边界的理解。
如果有不确定的地方，先问我，不要直接假设。

这个步骤看起来慢，实际能省掉很多返工。只要复述里出现偏差，你就能在改文件之前纠正它。

项目上下文不是一次性整理完的。每做几轮，你会发现哪些规则反复出现，把它们沉淀到长期文档里；临时任务结束后，就让它们留在聊天里，不要带进下一次。