CLAUDE.md 配置与上下文管理

第三章我们学会了用 /init 生成 CLAUDE.md，但自动生成的内容只覆盖了基础信息。这一章我们深入 CLAUDE.md 的完整配置语法，以及 Claude Code 最关键的机制——上下文窗口管理。

CLAUDE.md 完整配置项

CLAUDE.md 是一个 Markdown 文件，放在项目根目录。Claude Code 启动时会自动读取它，将其内容注入到系统提示词中。这意味着你在 CLAUDE.md 中写的内容，相当于在每次对话开头都告诉 Claude 一遍。

正因为这个机制，CLAUDE.md 内容会占用上下文窗口的 token 配额。写多了浪费空间，写少了信息不足。合理的 CLAUDE.md 应该在 200-500 行之间。

项目描述

项目描述应该用 2-3 句话说清楚项目是做什么的：

# 项目名称

电商后台管理系统，支持商品管理、订单处理和用户权限控制。
基于 Next.js 14 App Router 构建，采用 BFF 架构模式。

为什么要写项目描述？当你向 Claude 提出"帮我加个导出功能"时，如果它知道这是个后台管理系统，就会按照后台管理系统的 UI 风格和业务逻辑来设计功能，而不是泛泛地给一个通用方案。

技术栈声明

技术栈声明帮助 Claude 正确选择工具和框架。格式自由，建议按类别组织：

## 技术栈
- 框架: Next.js 14 (App Router)
- UI: shadcn/ui + Tailwind CSS 3.x
- 状态管理: Zustand
- 数据获取: TanStack Query v5
- 后端: Next.js API Routes + Prisma + PostgreSQL
- 测试: Vitest + Playwright
- CI/CD: GitHub Actions

明确技术栈的好处：当你要求"加一个表单"时，Claude 知道用 shadcn/ui 的 Form 组件而不是自己写一套，状态管理用 Zustand 而不是 Redux，数据提交用 TanStack Query 的 useMutation 而不是 fetch。

编码规范

编码规范是 CLAUDE.md 中最能提升代码质量的部分。把你团队的实际规范写进去：

## 编码规范
- 组件文件使用 PascalCase: `UserProfile.tsx`
- 工具函数文件使用 camelCase: `formatDate.ts`
- 使用 named export，不使用 default export
- CSS 类名顺序: 布局 -> 样式 -> 状态 (Tailwind)
- 错误处理使用 Result 模式，不抛异常
- API 路由结构: app/api/[resource]/route.ts
- 数据库字段使用 snake_case，代码中使用 camelCase 转换

这些规范越具体越好。比如"不抛异常"比"做好错误处理"有用得多——前者是可执行的规则，后者是模糊的建议。

常用命令注册

注册项目常用命令可以让 Claude Code 在需要时直接执行，不需要你一步步教它：

## 命令
- dev: npm run dev
- build: npm run build
- test:vitest: npm run test -- --run
- test:e2e: npx playwright test
- lint: npm run lint
- type-check: npx tsc --noEmit
- db:migrate: npx prisma migrate dev
- db:seed: npx prisma db seed
- format: npx prettier --write .

当你说"帮我跑一下 lint"时，Claude Code 会根据这里注册的命令执行 npm run lint 并读取输出。如果你没有注册，它可能会问"你的 lint 命令是什么"。

目录结构与关键文件

## 目录结构
- app/ - Next.js App Router 页面和 API 路由
- components/ui/ - 基础 UI 组件 (shadcn/ui)
- components/features/ - 业务组件
- lib/ - 工具函数和公共逻辑
  - db.ts - Prisma 客户端
  - api-client.ts - 前端 API 调用封装
- store/ - Zustand 状态管理
- prisma/schema.prisma - 数据库模型定义
- tests/ - 测试文件
- playwright.config.ts - E2E 测试配置

上下文窗口机制

理解上下文窗口是高效使用 Claude Code 的关键。

什么是上下文窗口

Claude Code 每次对话都在一个固定大小的"上下文窗口"中进行。这个窗口存放着会话中的所有信息：

• 系统提示词（含 CLAUDE.md 内容）
• 你发送的消息
• Claude 的回复
• 读取的文件内容
• 命令执行输出
• 文件 diff

不同模型的上下文窗口大小不同：

tokens 是 Claude 处理文本的基本单位。1 个 token 约等于 0.75 个英文单词或 0.5 个汉字。所以 32K tokens 大约对应 24K 英文单词或 16K 汉字。

窗口满了会怎样

当上下文窗口被填满时，Claude Code 会触发 窗口压缩 机制。表现形式：

1. Claude 的回复中可能会出现 [compact] 标记
2. 对话历史会被压缩，丢失部分早期细节
3. Claude 可能不再记得对话刚开始时的上下文

什么时候触发压缩

以下情况最容易导致上下文窗口溢出：

• 读取了大文件：一个 2000 行的 TypeScript 文件约 6000-8000 tokens
• 执行了多次命令：每次命令输出都存入上下文
• 对话轮次太多：超过 20-30 轮对话后，历史记录占用显著
• 文件修改 diff 累积：每次修改的 diff 都保存在上下文中

以下是一个上下文占用的实际案例：

当累计达到模型限制时，压缩就开始了。

/compact 压缩策略与最佳实践

手动压缩

当你发现 Claude 响应变慢或开始遗漏上下文时，手动执行：

> /compact

执行后，Claude 会：

1. 总结当前对话的关键信息
2. 丢弃早期的对话细节
3. 保留系统提示、CLAUDE.md 配置、未应用的文件修改
4. 生成一份摘要替代被丢弃的对话历史

压缩后的上下文占用通常会减少 50-70%。

自动压缩

在 .claude/settings.json 中设置：

{
  "context": {
    "autoCompact": true,
    "compactThreshold": 0.8
  }
}

compactThreshold 表示当上下文使用率达到 80% 时自动触发压缩。默认是开启的。

主动管理上下文的技巧

1. /clear 重置会话：如果话题已经完全变了方向，用 /clear 清空会话比 /compact 更彻底。

2. 分批处理大文件：不要一次性读取整个大文件，可以先让 Claude 列出文件结构，再有针对性地读取特定函数：

> 看看 src/utils/helpers.ts 的文件结构
> 帮我看看第 50-80 行的 validateEmail 函数逻辑

3. /add-dir 有节制使用：每添加一个目录，索引信息都会占用上下文。

4. CLAUDE.md 精简优化：定期审查 CLAUDE.md，移除过时的信息。比如某个工具已经不再使用了，对应的命令配置就应该删掉。

5. 拆分复杂任务：一个需要修改 10 个文件的重构任务，拆成 2-3 个会话分步完成，每个会话用 /clear 重置，比在一个会话中做完更稳定。

大项目上下文管理进阶

对于包含数百个文件的大型项目，单靠 CLAUDE.md 不足以让 Claude 理解全貌。以下是进阶策略：

关键文件白名单

在 CLAUDE.md 中列出最关键的文件路径，引导 Claude 优先关注：

## 关键文件
- prisma/schema.prisma - 数据库模型定义，所有查询都依赖此结构
- lib/api-types.ts - 前后端共享的类型定义
- store/index.ts - 全局状态定义
- app/api/[[...routes]]/route.ts - API 路由入口

分层描述

对于复杂项目，提供分层描述可以让 Claude 快速定位问题范围：

## 架构分层
- 展示层: app/ + components/ (React Server Components 优先)
- 数据层: lib/queries/ (Prisma 查询)
- API 层: app/api/ (Next.js Route Handlers)
- 外部集成: lib/integrations/ (第三方 API 调用)

下次当你报告"列表页面加载太慢"时，Claude 会根据分层描述优先查看数据层的查询实现，而不是在展示层绕圈子。

通过这些配置和管理技巧，即使是上万文件的大型项目，你也能让 Claude Code 保持高效工作。下一章我们聚焦权限与安全配置，让 Claude Code 在安全的轨道上运行。