13 上下文管理的进阶实践

使用 Claude Code 一段时间后，我发现一个有趣的现象：有时候 Claude 能准确理解我的项目结构，有时候又完全答非所问。

后来我明白了，这都和上下文管理有关。在第7章我们初步接触了 .claudeignore，但实际使用中还有很多门道。

上下文的奥秘

**上下文（Context）**简单来说，就是 Claude Code 在处理你的请求时，所参考的项目信息：

  • 项目结构（目录和文件组织）
  • 文件内容（相关源代码）
  • 依赖关系（模块间的引用）
  • 技术栈（使用的框架和工具）

上下文充足 = 准确的回答

1
2
3
4
# 有充足上下文
claude "在用户模块中添加邮箱验证功能"
# Claude 知道用户模块在哪里，使用什么框架
# 能生成符合项目风格的代码

上下文不足 = 模糊的回答

1
2
3
4
# 缺少上下文
claude "添加邮箱验证"
# Claude 不知道你的技术栈、项目结构
# 只能给出通用建议

Claude Code 如何加载上下文

Claude Code 的工作流程是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
你输入命令
    ↓
扫描项目目录
    ↓
根据配置选择文件
    ↓
读取文件内容
    ↓
分析依赖关系
    ↓
构建上下文窗口
    ↓
发送给 API

默认情况下，Claude Code 会：

  1. 扫描目录结构，识别项目类型
  2. 加载配置文件（package.json、requirements.txt 等）
  3. 读取源代码文件
  4. 分析 import/require 关系

你可以用调试模式查看当前上下文：

1
claude --debug "当前项目的上下文是什么？"

.claudeignore 的高级用法

.claudeignore 是控制上下文的关键。我在实践中积累了一些技巧。

基础回顾

1
2
3
4
# 基本格式
node_modules/
*.log
.env

高级模式匹配

通配符模式

1
2
3
4
5
6
7
8
9
10
11
12
# 匹配所有日志文件
*.log
*.log.*

# 匹配临时文件
*.tmp
*.bak
*~

# 匹配特定扩展名
*.min.js
*.min.css

目录模式

1
2
3
4
5
6
7
8
9
10
11
12
13
# 忽略整个目录
node_modules/
__pycache__/
dist/
build/

# 忽略嵌套目录
**/node_modules/
**/__pycache__/

# 忽略特定路径
src/temp/
tests/fixtures/

否定模式（保留特定文件）

1
2
3
4
5
6
7
8
# 忽略所有 .js 文件，但保留示例
*.js
!examples/*.js
!*.example.js

# 忽略 node_modules，但保留特定包
node_modules/
!node_modules/my-package/

实战配置模板

Web 项目配置

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
# 依赖
node_modules/
bower_components/
vendor/

# 构建产物
dist/
build/
out/
.next/
.nuxt/

# 缓存
.cache/
.parcle-cache/
.eslintcache

# 环境和密钥
.env
.env.local
.env.*.local
*.key
*.pem
secrets/

# 日志和临时
*.log
npm-debug.log*
yarn-debug.log*
pids
*.pid
*.seed

# IDE 和编辑器
.vscode/
.idea/
*.swp
*.swo
.DS_Store

# 测试覆盖率
coverage/
.nyc_output/

Python 项目配置

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
# 字节码
__pycache__/
*.py[cod]
*$py.class

# 虚拟环境
venv/
env/
.venv/

# 分发和构建
build/
dist/
*.egg-info/

# 测试和覆盖率
.pytest_cache/
.coverage
htmlcov/
.tox/

# Jupyter
.ipynb_checkpoints/
*.ipynb

# 数据库
*.db
*.sqlite

Monorepo 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 全局忽略
node_modules/
dist/
*.log

# 但保留特定包的源代码
!packages/*/src/

# 忽略文档包
packages/docs/
packages/website/

# 保留核心包的测试
!packages/core/tests/

Token 优化的实战经验

Token 是 API 计费的基本单位：

  • 1 Token ≈ 0.75 个英文单词
  • 1,000 Tokens ≈ 750 个英文单词
  • 中文消耗约是英文的 2-3 倍

成本计算：输入 Token × 单价 + 输出 Token × 单价

我的优化技巧

精简上下文

1
2
3
4
5
# ❌ 加载整个项目
claude "重构用户模块"

# ✅ 只加载相关文件
claude --add-dir ./src/modules/user "重构用户模块"

分批处理

1
2
3
4
5
6
# ❌ 一次性处理大文件
cat large-file.js | claude "解释这段代码"

# ✅ 分段处理
sed -n '1,100p' large-file.js | claude "解释第1-100行"
sed -n '101,200p' large-file.js | claude "解释第101-200行"

使用摘要

1
2
3
4
5
# 先获取概览
claude "总结这个项目的主要模块和功能"

# 再针对具体模块
claude "详细解释用户认证模块的实现"

避免重复

1
2
3
4
5
6
# ❌ 重复提供相同信息
claude "使用 Python Flask 框架..."
claude "还是使用 Python Flask 框架..."

# ✅ 建立项目上下文后，直接提问
claude "添加用户登录功能"

监控 Token 使用

1
2
3
4
5
6
# 查看使用统计
claude --debug "你的问题"
# 输出包含：
# - 使用的 Token 数量
# - 上下文大小
# - 响应时间

大型项目的上下文管理

对于大型项目，我总结了几种有效的策略。

模块化工作流

1
2
3
4
5
6
7
8
9
# 1. 切换到目标模块
cd src/modules/user

# 2. 只加载当前模块
claude --add-dir . "重构这个模块"

# 3. 完成后切换到下一个模块
cd ../payment
claude --add-dir . "添加新功能"

分层上下文

1
2
3
4
5
6
7
8
# 第一层：项目级（配置、架构）
claude --add-dir ./config "解释项目架构"

# 第二层：模块级（具体实现）
claude --add-dir ./src/modules "分析模块依赖"

# 第三层：文件级（细节实现）
claude "优化这个函数"

增量加载

1
2
3
4
5
6
# 开始时只加载核心文件
claude --add-dir ./src/core "理解核心架构"

# 根据需要逐步添加
claude --add-dir ./src/utils "添加工具函数上下文"
claude --add-dir ./src/api "添加 API 层上下文"

微服务架构

对于微服务项目，每个服务独立管理：

1
2
3
4
5
6
7
# 服务 A
cd services/auth
claude --add-dir . "开发认证服务"

# 服务 B
cd services/user
claude --add-dir . "开发用户服务"

隐私和安全

必须排除的敏感信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# API 密钥和凭据
.env
*.key
*.pem
*.cert
credentials/
secrets/

# 用户数据
users/
database/
backups/

# 日志（可能包含敏感信息）
logs/
*.log

# 配置文件（包含密码）
config/prod/
config/production/

数据脱敏

1
2
3
4
5
# ❌ 直接使用真实数据
cat database.sql | claude "优化查询"

# ✅ 使用脱敏数据
cat database.sample.sql | claude "优化查询"

我的实战案例

案例 1：优化 Node.js 项目

问题：项目响应慢，Token 消耗大

分析过程：

1
2
3
# 检查上下文大小
claude --debug "当前上下文"
# 发现 node_modules 被部分加载

解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
cat > .claudeignore << 'EOF'
# 依赖
node_modules/
**/node_modules/

# 构建产物
dist/
build/

# 只保留源代码
!src/
EOF

效果：

  • 上下文大小减少 80%
  • 响应速度提升 3 倍
  • Token 消耗降低 70%

案例 2：Python 数据分析项目

项目结构：

1
2
3
4
5
6
7
8
project/
├── data/           # 原始数据（大文件）
├── notebooks/      # Jupyter 笔记本
├── src/
│   ├── etl/        # 数据清洗
│   ├── analysis/   # 分析模块
│   └── viz/        # 可视化
└── reports/        # 生成的报告

配置 .claudeignore：

1
2
3
4
5
6
7
8
9
10
11
# 大数据文件
data/
*.csv
*.parquet

# Jupyter（已执行）
.ipynb_checkpoints/
*.ipynb

# 生成的报告
reports/

使用方式：

1
2
3
4
5
6
7
# ETL 模块
cd src/etl
claude --add-dir . "优化数据清洗流程"

# 分析模块
cd ../analysis
claude --add-dir . "添加新的分析方法"

案例 3：Monorepo 微服务

配置策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 依赖（所有包）
**/node_modules/

# 构建产物
**/dist/
**/build/

# 前端特定（当处理后端时）
packages/web/
packages/mobile/

# 但保留共享代码
!packages/shared/src/

工作流：

1
2
3
4
5
6
7
# API 服务
cd services/auth
claude --add-dir ../../packages/shared --add-dir . "开发认证功能"

# 独立处理每个服务
cd ../user
claude --add-dir ../../packages/shared --add-dir . "开发用户功能"

优化前后的对比

指标 优化前 优化后 提升
上下文大小 150K tokens 30K tokens 减少 80%
响应时间 15s 5s 减少 67%
Token 成本 $0.50/请求 $0.15/请求 减少 70%
准确性 85% 92% 提升 8%

我的最佳实践

应该做的

定期审查 .claudeignore

1
2
# 每月检查一次
cat .claudeignore

按需加载上下文

1
2
# 只加载需要的目录
claude --add-dir ./target-dir "..."

使用项目模板

1
2
# 为不同项目类型准备模板
cp .claudeignore.web .claudeignore

监控使用情况

1
2
# 定期检查 Token 使用
claude --debug "..."

不应该做的

忽略所有文件

1
2
# ❌ 这样会失去上下文能力
*

硬编码路径

1
2
3
4
5
# ❌ 不灵活
/home/user/project/node_modules/

# ✅ 使用相对路径
node_modules/

过度优化

1
2
3
# ❌ 排除太多会影响准确性
src/**/*.test.js
**/*.md

高级技巧

上下文预热

1
2
# 在开始工作前预热上下文
claude "熟悉这个项目的结构和代码风格"

上下文切换

1
2
3
4
5
6
# 保存当前上下文状态
claude "总结当前模块的关键信息"

# 切换到新模块
cd ../new-module
claude "基于之前的总结，理解新模块的关系"

上下文复用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 创建上下文文件
cat > context.md << 'EOF'
# 项目上下文

## 技术栈
- 框架：React 18 + TypeScript
- 状态管理：Zustand
- 样式：Tailwind CSS

## 代码规范
- 使用函数组件
- 命名约定：camelCase
- 组件文件：PascalCase
EOF

# 使用上下文
cat context.md | claude "基于这些规范创建新组件"

常见问题

Q: 上下文太大怎么办？

使用分阶段策略：

1
2
3
4
5
# 第一阶段：概览
claude "总结项目结构"

# 第二阶段：聚焦
claude --add-dir ./target "深入分析"

Q: 如何处理共享代码？

明确包含共享目录：

1
claude --add-dir ./shared --add-dir ./service "..."

Q: .gitignore 和 .claudeignore 的区别？

  • .gitignore：控制 Git 版本控制
  • .claudeignore：控制 AI 上下文

两者可以不同：

1
2
3
4
5
# .gitignore
package-lock.json  # 不提交到 Git

# .claudeignore
# package-lock.json  # 但可以给 AI 看（了解依赖）

总结

上下文管理是使用 Claude Code 的核心技能之一：

  • 上下文充足 = 准确的回答
  • 合理配置 .claudeignore = 提升效率
  • Token 优化 = 降低成本
  • 模块化管理 = 应对大型项目

掌握这些技巧后，你会发现 Claude Code 的效率大幅提升。

下一步，让我们学习提示词工程。

相关资源

继续加油！