简单直接的回答是:绝对不要把它们全部塞进每次对话中。
如果把“项目概览”、“文件结构”和“开发规范”这些大文档都放入 CLAUDE.md 或每次自动加载,你的单次对话 Token 消耗可能会瞬间飙升到 1万甚至3万+ ,导致成本极高且 AI 变得非常卡顿。
我们需要采用分层加载策略,根据文档的“通用性”和“使用频率”来决定如何处理。
📂 1. 这些文档的分类与处理建议
你可以把这些文档分为三类,分别对待:
🏷️ 第一类:通用规则(放入 CLAUDE.md 或 AGENTS.md)
- 内容:最核心的开发规范(如“必须使用 TypeScript”、“变量命名用驼峰”、“禁止 console.log”)、AI 的角色定义(“你是一个资深前端专家”)、输出格式要求(“代码要带 AI-GEN-BEGIN 标记”)。
- 处理方式:常驻内存。
- 理由:这些规则适用于 100% 的场景,且内容很短(通常 < 500 Token),放入
CLAUDE.md是划算的,能保证 AI 始终如一地遵守你的基本要求。
🗺️ 第二类:项目结构与概览(按需加载)
-
内容:
ARCHITECTURE.md(架构图)、ROADMAP.md(路线图)、详细的DIRECTORY_STRUCTURE.md(目录结构说明)。 -
处理方式:按需加载。
-
理由:你并不是每次都要改架构。只有当你进行新功能开发、重构或询问整体架构时,才需要这些信息。
-
操作建议:
- 保持这些文件在项目根目录。
- 当需要时,在 Cursor 的输入框中直接输入
@ARCHITECTURE.md,或者把文件拖入对话框。 - 不要让 Agent 自动扫描它们。
📜 第三类:详细开发规范(外部检索/MCP)
-
内容:极其详细的 UI 组件规范(如“按钮的 10 种状态”)、API 接口文档(Swagger 导出的巨长 JSON)、特定业务逻辑的长篇大论(如“支付流程的 50 个步骤”)。
-
处理方式:外部化/工具化。
-
理由:这些内容太长了,塞进 Prompt 会把 AI “撑死”。
-
操作建议:
- API 文档:如果可能,将其封装为 MCP Server 或 Tool。当 AI 需要调用 API 时,它会自动去查工具文档,而不是把几万字的文档塞进上下文。
- UI 规范:通常只需要把设计 Token(颜色、间距变量)放在
CLAUDE.md里即可,具体的视觉稿让设计师看,不用喂给 AI。
🚀 2. 推荐的工作流(Workflow)
为了在保持 AI “聪明”的同时不烧钱,建议你采用如下流程:
🔎 阶段一:提问前的“预热”
在开始一个具体的编码任务前,先花一点 Token 让 AI “熟悉环境”。
你的指令:
“我们开始开发一个新功能。请先阅读以下基础文档以了解项目背景:@ARCHITECTURE.md@DIRECTORY_STRUCTURE.md。请确认你已理解,并等待我的下一步指令。”
- 此时消耗:较高(读取了大文档),但只发生一次。
🏗️ 阶段二:具体任务执行
在接下来的连续对话中,AI 已经“记住”了刚才读过的架构文档。只要你不开启新的聊天窗口,它会基于之前的上下文进行推理。
你的指令:
“根据刚才的架构,帮我在这个模块写一个 API 接口。”
“在这个目录下生成组件。”
- 此时消耗:正常。因为架构文档已经在“短期记忆”(上下文窗口)里了,不需要重新传输。
🧹 阶段三:清理与隔离
如果你要开始一个完全不相关的新任务(比如从后端转去写文档),建议开启一个新的聊天窗口。
- 理由:避免旧的上下文(如后端代码)占用新的 Token 配额。
📌 3. 总结:怎么放最划算?
| 文档类型 | 放置位置 | 加载时机 | Token 消耗 | 适用场景 |
|---|---|---|---|---|
| 核心规范 | CLAUDE.md | 每次自动 | 低 (固定税) | 所有对话 |
| 项目概览 | 根目录 .md | 手动拖入 | 中 (按需) | 架构设计、新模块开发 |
| 详细文档 | 本地/外部 API | 工具调用 | 极低 | 需要查阅具体参数时 |
| 代码片段 | 编辑器 Tab | 自动/选中 | 低-中 | 日常编码、Bug 修复 |
一句话建议:
把 CLAUDE.md 当作 AI 的 “入职手册” (放最基本的要求),把具体的 “项目说明书” (架构/概览)留到开会(新任务开始)时再给它看。