用这个提示词，教会AI理解你的整个项目

发表于 阅读次数： Waline： 本文字数： 1.8k 阅读时长 ≈ 7 分钟
AI 编程助手总是在你的大项目里“重复造轮子”？核心原因是它缺少全局上下文。我分享一个用了很久的 Prompt，能让 AI 自己为代码库生成一份 README “说明书”，辅助解决“失忆”问题。告别无效沟通，让你的 AI 变成真正懂项目的队友。

作为一名cursor的重度用户，在差不多连续订阅一年之后，它几乎成为了我在编码过程中不可或缺的助手。

但是，就像跟任何队友协作一样，沟通的质量决定的协作的效率。

尽管已经使用cursor快一年了，但是还从来没有写过任何关于cursor的博客。

今天分享一个我自己用了好几个月的Prompt，它可以帮助AI（不一定是cursor，任何AI IDE都可以）更好地理解你的代码（库）。

问题的根源： AI的“代码失忆症”

如果你也经常使用cursor、github copilot、trae这种AI IDE工具，应该会有一个感受：当代码库大一些之后，AI就很难比较完整地理解整个代码库。明明有一个现成的模块，AI还是会自己重写一个。

这就是AI coding过程中“上下文缺失”问题，我称之为AI的“代码失忆症”。

当代码规模变大，文件和模块增多，AI就像一个只被告知了当前任务、但不了解整个项目的新同事。

它不了解整个项目的架构，不知道我们已经已经积累了哪些“轮子”，导致它会重复造轮子，甚至会提出与原先设计理念相违背的方案。

我自己经常遇到这个问题，后来就想到可以给AI提供一份项目说明书：用AI生成一个文档，详细地列出来当前代码库有哪些文件，每个文件有哪些内容。这样，AI通过阅读这个文档就能掌握整个代码库的情况。

完整的Prompt如下，它的核心目标就是指导AI为指定的目录生成或者更新一份结构化的README文档。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
为指定的目录生成/更新README.md文件，文件内容需要包含以下部分：

1. 项目概述
    简要介绍项目的核心功能、主要特性

2. 技术栈
    按照前端、后端、数据库、开发工具等分类总结技术栈(不需要注明具体版本)

3. 项目架构
    说明项目的整体架构设计、模块间关系、数据流向

4. 目录结构
    以目录树形式详细说明各目录和重要文件的用途，突出核心业务逻辑文件

5. 核心文件说明
    重点介绍以下类型的文件：
    - 项目入口文件和配置文件
    - 核心业务逻辑实现
    - 数据模型和API接口
    - 关键组件和服务模块


生成或更新README.md时的具体要求：

准确性要求：
1. 必须实际阅读文件内容来了解功能，严禁基于文件名猜测
2. 对已存在的README内容进行全面校验，识别并更新过时信息
3. 使用工具验证目录结构的准确性，确保没有遗漏或错误的文件引用
4. 对现有文件重新阅读和分析，因为内容可能已经更新

内容要求：
5. 使用纯文本（markdown）格式，避免emoji和装饰性符号
6. 内容要既准确又简洁，避免冗余描述
7. 面向不同技术水平的读者，提供必要的背景说明
8. 重点突出项目的独特设计和技术亮点
9. 忽略.venv、dist、node_modules、.git等目录

结构要求：
10. 保持逻辑清晰的层次结构
11. 确保各部分内容的关联性和完整性

这个Prompt有两个重点：

  1. 禁止猜测：明确要求 AI 必须实际阅读文件内容，杜绝基于文件名进行猜测。
  2. 保持更新：要求 AI 校验并更新过时信息，确保这份文档是准确的。

我的使用经验

用了cursor之后，我在自己的sideproject中比较喜欢使用Monorepo模式，也就是把所有的代码都放在一个代码库中，前端、后端、插件、桌面端都在一起，这样方便AI整体理解代码。

所以我的项目结构大致是这样的：

1
2
3
4
5
6
.project_root
├── backend    ## 后端代码
├── desktop    ## 桌面端
├── extension  ## 插件
├── frontend   ## 前端
└── README.md

由于整个代码库比较大，所以我会让AI遵循上面的Prompt为每一个一级子目录（如backend、frontend）生一个README文件。

生成的README文件大致是下面这样的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Language Leap Backend

## 1. 项目概述

本项目是 Language Leap 语言学习应用的后端服务，基于 FastAPI 构建。核心功能包括：

- **用户认证与管理**: 提供基于 JWT 的安全用户注册、登录和信息管理功能。
- xxxxxxxxx

## 2. 技术栈

- **后端框架**: FastAPI, Uvicorn, Gunicorn
- xxxxxxxxx

## 3. 项目架构

项目采用经典的分层架构设计，确保代码的高内聚、低耦合，易于维护和扩展。

1.  **API 层 (`app/api`)**: 作为最外层，负责处理所有传入的 HTTP 请求。它使用 FastAPI 的路由和 Pydantic 模型进行请求校验和响应格式化。此层不包含任何业务逻辑，仅作为 HTTP 接口的适配器，调用服务层来完成具体任务。

2.  xxxxxxxxx

## 4. 目录结构

backend/
├── app/                          # 主应用代码
│   ├── main.py                      # FastAPI应用入口和中间件配置
│   ├── api/                      # API路由层 (Controller)
│   │   └── stats.py                 # 学习统计API
│   ├── core/                     # 核心配置和基础设施
│   │   └── security.py              # 安全与认证模块 (JWT, Passlib)
│   ├── models/                   # 数据模型层 (ORM)
│   │   └── user.py                  # 用户数据模型
│   └── services/                 # 业务逻辑与外部服务集成层 (Service)
│       ├── collection_service.py    # 场景包核心业务逻辑

## 5. 核心文件说明

### 应用入口与配置

- **`run.py`**: 开发环境服务器启动脚本，使用 `uvicorn` 启动 FastAPI 应用，并开启热重载。
- xxxxxxxxx

顺带推广一下，上面案例中的Language Leap是我自己开发的一个学习英语的工具。

整个README分为5个部分：项目概述、技术栈、项目架构、目录结构和核心文件说明。

其中最重要的是目录结构（一个目录树） 和 核心文件说明。这两个部分就像一张高清地图，精确地告诉AI：

  • 项目里有哪些”路“（文件和目录）？
  • 每条”路“通向哪里（文件的具体作用）？
  • 哪些是”主干道“（核心逻辑）？

当我要开发一个新功能，或者排查一个复杂的 Bug 时，我只需将对应模块的 README.md 内容作为上下文喂给 AI。从我这几个月的使用经验来看，效果会有很明显的提升。

成本与平替工具

这种深度分析代码库的操作，对于大模型 token的消耗也是非常惊人的，我月初使用claude sonnet4 thinking模型生成后端和前端的README花了差不多4美金。

对于这种一次性的、长上下文的文档生成操作，我找到了两个可以平替的工具：阿里的Qwen code和Gemini CLI。

这两个工具都提供了充足的免费额度和超长的上下文窗口（百万级 Token），足以处理一个大型模块的代码。虽然在日常编码的交互体验上，我依然更偏爱 Cursor ，但在执行这种“重型”文档生成任务时，切换到这些免费工具也是不错的选择。