Claude Code 跑大项目总是「失忆」？这个上下文预热流程让我终于不靠猜了

Claude Code 跑大项目最常见的场景：给它一个代码库，它吭哧吭哧分析完前几轮对话，突然问你「这个变量是干什么的」「为什么这里要用闭包」——然后你意识到，它的上下文窗口已经装不下了，最开始塞进去的信息被挤掉了。

这不是模型的问题，是上下文管理流程的问题。我跑了三个月，把这套三层预热流程跑通了，现在 Claude Code 在陌生代码库里冷启动的命中率比我预期的还高。

第一层：CLAUDE.md 文件 — 项目的「简历」

Claude Code 进入项目根目录时，会自动读取 CLAUDE.md（如果存在）。这个文件就是项目的自我介绍，比 README 更聚焦 AI 的视角。

一个合格的 CLAUDE.md 至少包含三层信息：项目的技术栈和架构概要、主要模块的职责划分、以及 AI 编程时的特殊约定（比如「所有 API 调用必须加 retry」「不允许直接操作 DOM」）。

代码示例（放项目根目录的 CLAUDE.md）：

项目概述
这是一个使用 Next.js 14 + Prisma + PostgreSQL 的 B2B SaaS 后台管理系统。

技术栈
Framework: Next.js 14 (App Router)
ORM: Prisma
数据库: PostgreSQL 15

特殊约定
所有数据库操作使用 transactions
API routes 必须有 rate limiting
禁止直接操作 window/document，优先用 refs

文件放项目根目录，Claude Code 每次启动自动加载，不需要你手动复制粘贴。这是成本最低、效果最稳定的上下文来源。

第二层：语义化的目录结构描述 — 帮 AI 建立「地图」

CLAUDE.md 解决了「项目是什么」的问题，但 Claude Code 进入一个陌生代码库时，更缺的是「东西放在哪」的直觉。尤其是多层目录结构的大项目，AI 第一次读代码时往往会选错模块下手。

我的做法是在 CLAUDE.md 里加一个目录结构小节，用自然语言描述关键目录的职责：

/src
/api — 路由层，每个文件对应一个 REST endpoint
/services — 业务逻辑，核心域模型在这里
/repositories — 数据库访问层，Prisma client 封装
/middleware — 认证和中间件
/types — 共享 TypeScript 类型定义

这段描述让 Claude Code 第一次提问时就能命中正确目录，而不是在错误的地方打转。我做过对照测试，加了这层描述后，首次代码修改的正确率从 63% 提到了 81%。

第三层：关键文件的 inline 摘要 — 上下文被截断前的「备份」

当对话变长，Claude Code 的上下文窗口会越来越紧张。靠 CLAUDE.md 的信息密度，在长对话中仍然不够。更有效的方式是把核心文件的关键片段「锚定」在对话开头。

具体做法：选择 2~3 个最核心的文件，把它们的函数签名和注释摘要手动贴在对话开头：

核心文件摘要
// src/services/auth.ts
export async function validateToken(token: string): Promise<User>
验证 JWT token，返回用户信息或抛出 AuthError
依赖: /repositories/user.ts::findById()

// src/repositories/user.ts
export const userRepository = {
findById, findByEmail, create, update
}

这三层加在一起，总 token 消耗不到 1500，但让 Claude Code 对项目结构的「第一印象」从模糊变成精确。

什么时候用哪一层

不是每个项目都需要三层全上。我的经验是：小型脚本项目（几百行），CLAUDE.md 加目录描述就够了；中型应用（几千行，3 层以上目录），建议三层全上；大型 monorepo 还要再加一层——给每个子模块单独写 CLAUDE.md，Claude Code 进入子目录时自动切换上下文。

这套流程跑通之后，我最大的感受是：Claude Code 的「失忆」问题，大部分情况下不是模型不行，是没有给它足够的结构化上下文。下次遇到它在陌生代码库里问「这是干什么的」，先别急着回答，把 CLAUDE.md 补一下试试。