# Claude Code上下文工程：从CLAUDE.md到会话管理全链路实战
## 概述
本教程面向已掌握Claude Code基本操作的初中级开发者，系统讲解Claude Code的上下文工程体系——从CLAUDE.md多层配置、自动记忆、AGENTS.md协作，到会话恢复、上下文压缩、Git Worktree并行开发，帮助你构建"永不失忆"的AI编程工作流。
**适合人群**：有1-3个月Claude Code使用经验，经常遇到"AI忘记上下文"、"长会话性能下降"、"多项目配置混乱"等问题的开发者。
**学习目标**：
- 理解Claude Code五层上下文架构，精准控制AI行为
- 掌握CLAUDE.md的分层配置与最佳实践
- 学会会话管理、上下文压缩、并行开发的完整工作流
---
## 前置条件
- 已安装Claude Code CLI（`npm install -g @anthropic-ai/claude-code`）
- Node.js 18+ 环境
- 基本Git操作能力
- 至少有一个真实项目可供练习
---
## 第一章：理解Claude Code的五层上下文架构
Claude Code并不是每次对话都"从零开始"。它拥有一套精心设计的分层上下文系统，每一层都有不同的作用域和生命周期。
### 1.1 五层架构全景
```
┌─────────────────────────────────────────────┐
│ Layer 5: System Prompt │ ← Anthropic内置，不可修改
├─────────────────────────────────────────────┤
│ Layer 4: Global CLAUDE.md │ ← ~/.claude/CLAUDE.md
│ (跨项目通用偏好) │
├─────────────────────────────────────────────┤
│ Layer 3: Project CLAUDE.md │ ← 项目根目录/CLAUDE.md
│ (项目级规范和指令) │
├─────────────────────────────────────────────┤
│ Layer 2: Directory CLAUDE.md │ ← 子目录/CLAUDE.md
│ (模块/包级定制指令) │
├─────────────────────────────────────────────┤
│ Layer 1: Auto Memory │ ← ~/.claude/memory/
│ (会话中自动/手动记录的持久记忆) │
└─────────────────────────────────────────────┘
```
### 1.2 各层加载顺序与优先级
Claude Code启动时按以下顺序加载上下文：
```mermaid
flowchart TD
A[启动 claude] --> B[加载 System Prompt
内置工具定义与安全规则]
B --> C[加载 Global CLAUDE.md
~/.claude/CLAUDE.md]
C --> D[加载 Project CLAUDE.md
项目根目录]
D --> E[扫描 Directory CLAUDE.md
当前工作子目录的所有父级]
E --> F[加载 Auto Memory
~/.claude/memory/*.md]
F --> G[恢复会话上下文
如果使用 --continue/--resume]
G --> H[就绪，等待用户输入]
style B fill:#ff6b6b,color:#fff
style C fill:#ffa502,color:#fff
style D fill:#2ed573,color:#fff
style E fill:#1e90ff,color:#fff
style F fill:#a55eea,color:#fff
style G fill:#747d8c,color:#fff
```
**关键规则**：
- **下层覆盖上层**：如果Project CLAUDE.md与Global CLAUDE.md冲突，Project级别生效
- **所有层级累加**：不冲突的指令会在所有层级生效
- **Directory级支持嵌套**：从根目录到当前目录，每一级都可以有CLAUDE.md
### 1.3 查看当前加载的上下文
在Claude Code会话中，使用内置命令检查上下文状态：
```bash
# 在Claude Code交互模式中输入
> /context
# 或者通过状态栏查看当前Token使用情况
# 底部状态栏会显示: "Context: 12.4K/200K tokens"
```
---
## 第二章：Global CLAUDE.md — 你的个人编程人格
### 2.1 创建与位置
```bash
# 确保目录存在
mkdir -p ~/.claude
# 创建全局配置文件
# 路径: ~/.claude/CLAUDE.md
```
### 2.2 推荐配置模板
```markdown
# Global Preferences
## 语言与风格
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释
- 使用中文标题和描述，代码/命令保持原文
## 代码风格
- TypeScript: 使用严格模式，优先函数式组件
- Python: 遵循PEP 8，类型注解全覆盖
- 优先使用 const，避免 var
- 单文件不超过 300 行
## 工作流规则
- 始终先读取文件再编辑，不要盲目修改
- 修改代码后主动运行测试验证
- 不要自动 git commit，只在明确要求时执行
- 优先编辑现有文件而非创建新文件
## 禁止事项
- 不要提交 .env、credentials 等敏感文件
- 不要添加不必要的注释或文档
- 不要引入未请求的新依赖
```
### 2.3 最佳实践
**做**：
- 放通用偏好（语言、风格、个人工作流）
- 放跨项目的禁止事项
- 保持精简（50行以内，每个Token都算数）
**不做**：
- 不要放项目特定配置（应放Project CLAUDE.md）
- 不要放会频繁变更的内容
- 不要写长篇大论的说明
### 2.4 常见问题
**Q: Global CLAUDE.md在所有项目都生效吗？**
A: 是的，包括临时目录。适合放"不要自动commit"这类通用规则。
**Q: 文件编码有要求吗？**
A: 必须使用UTF-8编码。
---
## 第三章：Project CLAUDE.md — 项目级AI契约
### 3.1 核心结构
一个完善的Project CLAUDE.md应包含以下模块：
```markdown
# 项目名称: my-saas-app
## 技术栈
- Next.js 15 (App Router)
- TypeScript 5.4 (strict mode)
- Prisma ORM + PostgreSQL
- Tailwind CSS + shadcn/ui
- Vitest + Playwright
## 项目结构
```
src/
├── app/ # Next.js App Router页面
├── components/ # React组件
│ ├── ui/ # shadcn/ui基础组件（不要修改）
│ └── features/ # 业务组件
├── lib/ # 工具函数和共享逻辑
├── server/ # 服务端逻辑
└── tests/ # 测试文件
```
## 关键命令
- `npm run dev` — 启动开发服务器
- `npm run build` — 生产构建
- `npm run test` — 运行单元测试
- `npm run test:e2e` — 运行E2E测试
- `npm run lint` — ESLint检查
- `npm run db:migrate` — 数据库迁移
- `npm run db:seed` — 填充测试数据
## 代码规范
- 组件文件用 PascalCase: `UserProfile.tsx`
- 工具函数用 camelCase: `formatDate.ts`
- 测试文件与源文件同目录: `UserProfile.test.tsx`
- API路由用 kebab-case: `api/user-profile/route.ts`
## 架构决策
- Server Components为默认，只在需要交互时使用 Client Components
- 数据获取通过Server Actions，不使用客户端fetch
- 使用Zod做运行时类型校验
- 错误处理统一使用 error.tsx 边界
## 禁止事项
- 不要修改 src/components/ui/ 下的文件（shadcn/ui管理）
- 不要在客户端组件中直接访问数据库
- 不要使用 any 类型
- 不要创建新的环境变量（复用现有的）
```
### 3.2 高级技巧：模块化拆分
对于大型项目，可以用`@import`语法引用外部文件：
```markdown
# Project: enterprise-dashboard
## 核心指令
@import ./docs/ai-conventions/coding-style.md
@import ./docs/ai-conventions/architecture.md
@import ./docs/ai-conventions/database-rules.md
## 技术栈
- React 19 + Vite
- ...
```
### 3.3 Directory级CLAUDE.md实战
在复杂项目的关键子目录放置CLAUDE.md，提供局部的精确指导：
```
my-saas-app/
├── CLAUDE.md ← 项目级配置
├── src/
│ ├── components/
│ │ ├── CLAUDE.md ← 组件开发规范
│ │ └── ui/
│ │ └── CLAUDE.md ← "不要修改此目录文件"
│ ├── server/
│ │ └── CLAUDE.md ← 服务端安全规则
│ └── tests/
│ └── CLAUDE.md ← 测试编写规范
```
**示例：`src/components/CLAUDE.md`**
```markdown
# 组件开发规范
## 创建新组件前检查
1. 确认 shadcn/ui 没有现成组件可复用
2. 确认 features/ 目录下没有类似组件
3. 参考 README.md 中的组件清单
## 组件模板
- 使用函数声明（不用箭头函数）
- Props接口定义在组件文件顶部
- 导出使用命名导出（不用default export）
```
**示例：`src/server/CLAUDE.md`**
```markdown
# 服务端安全规则
## 绝对禁止
- 在API路由中直接使用SQL字符串拼接
- 在日志中输出用户密码或Token
- 跳过中间件认证检查
## 必须遵守
- 所有数据库查询通过Prisma Client
- 敏感操作记录审计日志
- 响应数据使用select限制字段，不返回完整记录
```
---
## 第四章：Auto Memory — 让AI拥有持久记忆
### 4.1 自动记忆机制
Claude Code拥有两种互补的记忆系统：
| 特性 | CLAUDE.md | Auto Memory |
|------|-----------|-------------|
| 加载时机 | 会话启动时 | 会话启动时 |
| 谁来编写 | 你手动维护 | AI自动/手动创建 |
| 作用域 | 按文件位置决定 | 全局（跨项目） |
| 生命周期 | 随项目/全局 | 永久，直到手动删除 |
| 适合内容 | 规则、规范 | 决策记录、偏好发现 |
### 4.2 触发记忆写入
在对话中明确要求Claude记住某些内容：
```
# 方式1：直接指令
> 记住：这个项目使用 pnpm 而不是 npm
# 方式2：使用斜杠命令
> /remember 项目使用prisma而不是typeorm做ORM
# 方式3：在对话总结时要求记忆
> 这次重构完成了用户模块的迁移，
> 记住：UserService已经从Class改为了函数式风格
```
### 4.3 手动管理记忆文件
```bash
# 查看记忆目录
ls ~/.claude/memory/
# 典型文件结构
# ~/.claude/memory/
# ├── preferences.md ← 个人偏好
# ├── project-decisions.md ← 项目决策记录
# └── lessons-learned.md ← 经验教训
```
**最佳实践 — 记忆文件内容模板**：
```markdown
# preferences.md
- 偏好使用函数式编程风格
- 喜欢用describe/it而非test()写测试
- 项目commit信息用中文
- 偏好ES Modules而非CommonJS
# project-decisions.md
- [2026-05-28] my-saas-app: 选用Prisma替代TypeORM，因为类型安全更好
- [2026-05-29] my-saas-app: API层采用tRPC而非REST，减少类型重复
- [2026-05-30] shared: 所有项目统一使用pnpm + turborepo
```
### 4.4 记忆清理策略
```bash
# 定期审查记忆（建议每月一次）
cat ~/.claude/memory/*.md
# 删除过时记忆
rm ~/.claude/memory/outdated-decision.md
# 或者让Claude帮你清理
> 回顾 ~/.claude/memory/ 目录下的所有记忆文件，
> 删除与当前项目无关或已经过时的条目
```
---
## 第五章：AGENTS.md — 团队协作的上下文标准
### 5.1 CLAUDE.md vs AGENTS.md
2026年，AI编程工具生态正在收敛到一个共同模式：项目根目录放一个Markdown文件，为AI提供上下文。Claude Code使用`CLAUDE.md`，OpenAI Codex使用`AGENTS.md`。
**兼容性策略**：同时维护两个文件，确保Claude Code和Codex用户都能获得完整上下文。
```mermaid
flowchart LR
A[AGENTS.md
Codex/GitHub Copilot] -->|读取| C[AI Agent]
B[CLAUDE.md
Claude Code] -->|读取| C
D[.cursorrules
Cursor] -->|读取| E[Cursor IDE]
F[推荐策略:
维护统一源文件] --> G[用脚本同步
AGENTS.md ↔ CLAUDE.md]
style F fill:#2ed573,color:#fff
style G fill:#2ed573,color:#fff
```
### 5.2 双文件同步方案
```bash
#!/bin/bash
# sync-ai-config.sh — 同步AI配置文件
# 以CLAUDE.md为主文件，自动生成AGENTS.md
if [ -f "CLAUDE.md" ]; then
# 复制并添加Codex特有的header
echo "# This file is auto-synced from CLAUDE.md" > AGENTS.md
echo "# Last synced: $(date)" >> AGENTS.md
echo "" >> AGENTS.md
tail -n +1 CLAUDE.md >> AGENTS.md
echo "✅ AGENTS.md synced from CLAUDE.md"
fi
```
---
## 第六章：会话管理 — 永不断线的AI协作
### 6.1 三种会话恢复方式
```mermaid
flowchart TD
A[需要恢复之前的会话] --> B{场景选择}
B -->|刚退出
想继续| C[--continue
恢复最近一次会话]
B -->|找特定
历史会话| D[--resume
交互式选择历史会话]
B -->|知道
会话ID| E[--resume SESSION_ID
精确恢复指定会话]
C --> F[完整恢复对话历史
+ 文件状态快照]
D --> F
E --> F
F --> G{会话是否完整?}
G -->|是| H[继续工作]
G -->|上下文被压缩| I[检查关键决策
是否被保留]
I --> H
style C fill:#2ed573,color:#fff
style D fill:#1e90ff,color:#fff
style E fill:#a55eea,color:#fff
```
### 6.2 --continue：延续上次对话
```bash
# 最简单的恢复方式，自动加载最近的会话
claude --continue
# 带新提示恢复，相当于在原对话末尾追加
claude --continue "继续完成用户认证模块的测试"
# 也可以用简写
claude -c
```
### 6.3 --resume：选择历史会话
```bash
# 交互式列出历史会话，用方向键选择
claude --resume
# 也可以用简写
claude -r
# 如果知道会话ID，直接指定
claude --resume abc123def456
```
交互式选择界面示例：
```
? Select a session to resume:
❯ 2026-05-31 09:15 "重构用户模块" (1h 23m ago)
2026-05-30 16:42 "添加支付集成" (16h ago)
2026-05-30 11:08 "修复登录Bug #234" (1d ago)
2026-05-29 14:30 "数据库Schema迁移" (2d ago)
```
### 6.4 会话命名最佳实践
```bash
# 启动时给会话命名（使用--session-name）
claude --session-name "feat/user-auth"
# 在会话中也可以命名
# 使用 /name 命令
> /name feat/user-auth
```
命名规范建议：
```
feat/xxx ← 新功能开发
fix/xxx ← Bug修复
refactor/xxx ← 代码重构
docs/xxx ← 文档更新
test/xxx ← 测试编写
infra/xxx ← 基础设施变更
```
### 6.5 检查点机制
Claude Code在对话过程中自动创建检查点（checkpoint），保存文件状态快照：
```bash
# 查看当前会话的检查点列表
> /checkpoints
# 回滚到指定检查点
> /undo # 回滚最近一次变更
# 查看会话历史中的文件变更
> /diff
```
### 6.6 常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `--continue`报错"No previous session" | 从未在此项目创建过会话 | 正常，直接启动新会话 |
| 恢复会话后AI"忘记"之前的内容 | 上下文压缩已触发 | 检查CLAUDE.md是否包含关键决策 |
| 会话列表为空 | 会话存储在项目本地 | 确保在正确的项目目录运行 |
| 长会话响应变慢 | Token接近200K上限 | 使用`/compact`手动压缩或启动新会话 |
---
## 第七章：上下文压缩 — 突破Token限制
### 7.1 自动压缩机制
Claude Code拥有200K Token的上下文窗口。当Token使用接近上限时（约95%，即190K Token），会自动触发上下文压缩：
```mermaid
sequenceDiagram
participant U as 用户
participant CC as Claude Code
participant CM as 压缩管理器
Note over U,CM: 正常对话阶段
U->>CC: 写代码 / 读文件 / 运行命令
CC->>CC: Token计数持续增长
Note over CC: Token达到~190K (95%)
CC->>CM: 触发自动压缩
CM->>CM: 保留: 系统提示 + CLAUDE.md + 最近10轮对话
CM->>CM: 压缩: 早期对话历史 → 摘要
CM-->>CC: 压缩完成，释放Token空间
Note over U,CM: 压缩后继续对话
U->>CC: 继续工作（无感知）
```
### 7.2 手动控制压缩
```bash
# 在对话中手动触发压缩
> /compact
# 带自定义提示的压缩（指导AI保留什么）
> /compact 保留所有关于数据库Schema的讨论和决策
# 通过环境变量控制压缩阈值
export CLAUDE_CODE_AUTO_COMPACT_THRESHOLD=0.8 # 在80%时触发
```
### 7.3 压缩友好型对话策略
**策略一：关键决策及时写入CLAUDE.md**
```
# 不好的做法：只在对话中讨论
> 我们用Redis做缓存吧，TTL设5分钟...
# 好的做法：讨论后写入持久层
> 确认使用Redis做缓存，TTL=300s。
> 请把这个决策写入CLAUDE.md的"架构决策"部分
```
**策略二：用"里程碑总结"保护关键信息**
```
# 每完成一个重要阶段，要求AI做总结
> 现在我们完成了用户模块重构，请总结：
> 1. 做了哪些变更
> 2. 关键决策及理由
> 3. 待办事项
> 把总结写入 ~/.claude/memory/milestone-user-module.md
```
**策略三：拆分长会话**
```bash
# 与其用一个超长会话做所有事
# 不如按阶段拆分
# 会话1：分析和规划
claude --session-name "plan/user-module-refactor"
# 会话2：执行重构（带前序上下文）
claude --session-name "refactor/user-module" \
-p "读取plan/user-module-refactor的决策记录，开始执行重构"
# 会话3：测试和验证
claude --session-name "test/user-module" \
-p "验证用户模块重构后的测试覆盖"
```
---
## 第八章：Git Worktree — 并行开发的终极武器
### 8.1 为什么需要Worktree
当你在Claude Code中同时处理多个任务时，会遇到一个核心矛盾：一个Claude Code会话只能在一个目录下工作。Git Worktree解决了这个问题——它允许你在同一个仓库中同时检出多个分支到不同目录。
```mermaid
flowchart TD
A[主仓库: main分支
~/projects/my-app] --> B[Worktree 1: feat/auth
~/.claude/worktrees/auth]
A --> C[Worktree 2: fix/payment-bug
~/.claude/worktrees/payment]
A --> D[Worktree 3: docs/api-v2
~/.claude/worktrees/docs]
E[Claude Session 1
在Worktree 1工作] -.-> B
F[Claude Session 2
在Worktree 2工作] -.-> C
G[Claude Session 3
在Worktree 3工作] -.-> D
style E fill:#ff6b6b,color:#fff
style F fill:#1e90ff,color:#fff
style G fill:#2ed573,color:#fff
```
### 8.2 在Claude Code中使用Worktree
```bash
# 方式1：使用Claude Code内置的Worktree支持
# 在会话中输入
> /worktree
# 或在启动时指定
# Claude Code会自动创建隔离的worktree
```
```bash
# 方式2：手动管理Git Worktree（更灵活）
# 从main创建新分支的worktree
cd ~/projects/my-app
git worktree add ../my-app-auth feat/auth
git worktree add ../my-app-payment fix/payment-bug
# 在不同终端启动独立的Claude Code会话
# 终端1
cd ~/projects/my-app-auth && claude --session-name "feat/auth"
# 终端2
cd ~/projects/my-app-payment && claude --session-name "fix/payment"
```
### 8.3 Worktree工作流最佳实践
```bash
# 1. 按功能创建worktree
git worktree add ../feature-branch feature/xxx
# 2. 启动Claude Code开发
cd ../feature-branch && claude
# 3. 完成后合并回主仓库
cd ~/projects/my-app
git merge feature/xxx
# 4. 清理worktree
git worktree remove ../feature-branch
```
### 8.4 并行Agent模式
使用Claude Code的Task工具（Subagent）实现更高级的并行开发：
```
# 在主会话中分派并行子任务
> 使用并行子Agent完成以下任务：
> Agent 1: 在 src/api/ 目录下实现用户CRUD接口
> Agent 2: 在 src/tests/ 目录下编写对应的测试用例
> Agent 3: 更新 src/db/schema.prisma 添加User模型
>
> 三个Agent同时工作，互不干扰
```
Claude Code会自动为每个子任务创建独立的Agent实例，它们各自拥有独立的上下文空间，避免相互干扰。
---
## 第九章：完整实战 — 为真实项目配置上下文工程
### 9.1 项目场景
假设你正在开发一个TypeScript全栈SaaS应用，需要为整个团队配置完整的上下文工程体系。
### 9.2 第一步：配置全局层
```bash
# ~/.claude/CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences
## 语言与风格
- 默认中文回复，代码注释英文
- 简洁明了，避免冗余
## 通用规则
- 始终先读取文件再编辑
- 修改后主动运行测试
- 不自动commit
- 优先编辑而非新建文件
- 不提交敏感文件
## 跨项目代码风格
- TypeScript strict mode
- 优先函数式风格
- 文件不超过300行
EOF
```
### 9.3 第二步：配置项目层
```bash
# 项目根目录
cd ~/projects/my-saas-app
cat > CLAUDE.md << 'EOF'
# Project: SaaS Dashboard
## 技术栈
- Next.js 15 (App Router, Server Components)
- TypeScript 5.4 (strict)
- Prisma + PostgreSQL
- Tailwind CSS + shadcn/ui
- Vitest + Playwright
- pnpm (monorepo with turborepo)
## 项目结构
```
apps/
├── web/ # Next.js前端
├── api/ # Hono API服务
└── admin/ # 管理后台
packages/
├── shared/ # 共享类型和工具
├── ui/ # 共享组件库
└── config/ # 共享配置
```
## 关键命令
- `pnpm dev` — 启动所有服务
- `pnpm build` — 构建检查
- `pnpm test` — 运行所有测试
- `pnpm lint` — 代码检查
- `pnpm db:migrate` — 数据库迁移
## 架构决策
- Server Components为默认选择
- 数据获取用Server Actions
- Zod做运行时校验
- 统一错误边界处理
## 禁止事项
- 不修改 packages/ui/ (独立发布)
- 不使用 any 类型
- 不在客户端直连数据库
- 不新增环境变量
EOF
```
### 9.4 第三步：配置目录层
```bash
# API服务目录
cat > apps/api/CLAUDE.md << 'EOF'
# API Service Rules
## 路由规范
- RESTful风格，资源用复数名词
- 每个路由文件对应一个资源
- 使用Hono的中间件链处理认证、日志
## 安全规则
- 所有路由必须经过auth中间件
- 响应数据使用select限制字段
- 敏感操作记录审计日志
## 测试
- 每个路由至少2个测试: 成功+失败
- 使用vitest的describe/it结构
EOF
# 前端应用目录
cat > apps/web/CLAUDE.md << 'EOF'
# Web Frontend Rules
## 组件规范
- 默认Server Component
- 需要交互时标记'use client'
- Props接口定义在文件顶部
- 使用命名导出
## 样式规范
- 优先使用Tailwind类
- 复杂样式用cn()合并
- 响应式优先移动端
EOF
```
### 9.5 第四步：初始化记忆系统
```bash
mkdir -p ~/.claude/memory
cat > ~/.claude/memory/project-decisions.md << 'EOF'
# Project Architecture Decisions
## 2026-05-28: 选择Hono替代Express
- 理由：更好的TypeScript支持和Edge Runtime兼容性
- 影响：API层全部使用Hono的API风格
## 2026-05-29: Prisma替代Drizzle
- 理由：团队更熟悉Prisma，迁移工具更成熟
- 影响：所有数据库操作通过Prisma Client
## 2026-05-30: Monorepo结构确定
- 工具：turborepo + pnpm workspaces
- 布局：apps/ + packages/ 两层结构
EOF
```
### 9.6 第五步：创建同步脚本
```bash
cat > scripts/sync-ai-config.sh << 'SCRIPT'
#!/bin/bash
# 同步CLAUDE.md到AGENTS.md，确保多AI工具兼容
PROJECT_ROOT="$(git rev-parse --show-toplevel)"
sync_file() {
local src="$1"
local dst="$2"
if [ -f "$src" ]; then
{
echo "# Auto-synced from CLAUDE.md"
echo "# Updated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""
cat "$src"
} > "$dst"
echo " ✅ $dst synced"
fi
}
echo "🔄 Syncing AI config files..."
sync_file "$PROJECT_ROOT/CLAUDE.md" "$PROJECT_ROOT/AGENTS.md"
find "$PROJECT_ROOT" -name "CLAUDE.md" -not -path "*/node_modules/*" | while read -r f; do
dir=$(dirname "$f")
sync_file "$f" "$dir/AGENTS.md"
done
echo "✨ Done!"
SCRIPT
chmod +x scripts/sync-ai-config.sh
```
### 9.7 最终项目结构验证
```bash
# 完整的上下文工程文件布局
tree -a -I 'node_modules|.git' --charset=ascii ~/projects/my-saas-app/ -P '*CLAUDE.md|AGENTS.md|memory*'
# 预期输出：
# .
# |-- CLAUDE.md ← 项目级AI配置
# |-- AGENTS.md ← Codex兼容（自动同步）
# |-- apps/
# | |-- api/
# | | |-- CLAUDE.md ← API服务规范
# | | +-- AGENTS.md
# | +-- web/
# | |-- CLAUDE.md ← 前端组件规范
# | +-- AGENTS.md
# |-- packages/
# |-- scripts/
# | +-- sync-ai-config.sh ← 同步脚本
# +-- ~/.claude/
# |-- CLAUDE.md ← 全局配置
# +-- memory/
# +-- project-decisions.md ← 决策记忆
```
---
## 第十章：上下文工程工作流全景图
```text
flowchart TB
subgraph 启动阶段
S1[打开终端] --> S2[cd 进入项目目录]
S2 --> S3{恢复旧会话?}
S3 -->|是| S4[claude --resume]
S3 -->|否| S5[claude --session-name feat/xxx]
S4 --> S6[上下文加载完成]
S5 --> S6
end
subgraph 工作阶段
S6 --> W1[Claude读取多层CLAUDE.md]
W1 --> W2[按规范执行任务]
W2 --> W3{重要决策?}
W3 -->|是| W4[写入CLAUDE.md或Memory]
W3 -->|否| W5[继续工作]
W4 --> W5
W5 --> W6{需要并行任务?}
W6 -->|是| W7[使用Task工具分派子Agent]
W6 -->|否| W8{Token接近上限?}
W7 --> W8
W8 -->|是| W9[/compact 手动压缩]
W8 -->|否| W2
W9 --> W2
end
subgraph 收尾阶段
W2 --> E1{任务完成?}
E1 -->|是| E2[总结关键决策]
E2 --> E3[更新CLAUDE.md]
E3 --> E4[写入Memory]
E4 --> E5[退出会话]
end
style S4 fill:#2ed573,color:#fff
style S5 fill:#1e90ff,color:#fff
style W4 fill:#ffa502,color:#fff
style W7 fill:#a55eea,color:#fff
style W9 fill:#ff6b6b,color:#fff
```
---
## 第十一章：上下文工程检查清单
每次启动新项目时，使用以下检查清单确保上下文工程到位：
### 项目启动检查
- [ ] `~/.claude/CLAUDE.md` 存在且包含个人偏好
- [ ] 项目根目录有 `CLAUDE.md`，包含技术栈、命令、规范
- [ ] 关键子目录有各自的 `CLAUDE.md`
- [ ] `~/.claude/memory/` 目录已创建
- [ ] 如果团队使用Codex，`AGENTS.md` 已同步
- [ ] 会话命名规范已确定
### 日常维护检查（每周）
- [ ] 审查 `~/.claude/memory/` 下的记忆是否过时
- [ ] 确认 CLAUDE.md 中的命令仍然有效（构建、测试等）
- [ ] 清理已完成任务相关的临时记忆
- [ ] 更新架构决策记录
### 会话管理检查
- [ ] 会话已命名（`/name` 或 `--session-name`）
- [ ] 重要决策已写入持久层（CLAUDE.md或Memory）
- [ ] Token使用量定期检查（状态栏）
- [ ] 长任务使用 `/compact` 主动管理上下文
---
## 第十二章：常见陷阱与排错指南
### 陷阱1：CLAUDE.md过大
**症状**：每次启动慢，Token消耗高，AI忽略部分指令
**解决方案**：
```bash
# 检查文件大小
wc -l CLAUDE.md
# 如果超过100行，考虑拆分到子目录CLAUDE.md
# 将详细规范移到子目录
mv detailed-api-rules → apps/api/CLAUDE.md
mv detailed-frontend-rules → apps/web/CLAUDE.md
```
### 陷阱2：记忆污染
**症状**：AI在项目A中使用项目B的约定
**解决方案**：
```bash
# 审查全局记忆
grep -r "项目B的约定" ~/.claude/memory/
# 项目特定的决策应该写在项目CLAUDE.md，
# 而不是全局memory中
```
### 陷阱3：压缩后丢失关键信息
**症状**：长会话中AI突然"忘记"之前的决策
**解决方案**：
```
# 在对话早期就要求AI记录重要决策
> 每当我们做出架构决策时，立即写入CLAUDE.md
# 定期手动压缩，保留关键内容
> /compact 保留所有Schema设计和API接口相关的讨论
```
### 陷阱4：Worktree冲突
**症状**：多个Worktree的分支merge时出现大量冲突
**解决方案**：
```bash
# 确保每个Worktree操作不同的文件区域
# 在CLAUDE.md中明确划分职责
# apps/web/CLAUDE.md
echo "本模块只操作 apps/web/ 下的文件" >> apps/web/CLAUDE.md
# apps/api/CLAUDE.md
echo "本模块只操作 apps/api/ 下的文件" >> apps/api/CLAUDE.md
```
---
## 实战案例：一个完整的上下文工程项目模板
以下是一个可以直接复制使用的中型项目上下文配置：
```markdown
# ~/.claude/CLAUDE.md (Global - 30行)
---
默认中文回复。代码注释英文。
TypeScript strict mode。函数式优先。
先读后改。改后跑测。不自动commit。
不提交敏感文件。不新建文件除非必要。
```
```markdown
# ~/project/CLAUDE.md (Project - 60行)
---
# 项目: taskflow-app
技术栈: Next.js 15 + TypeScript + Prisma + PostgreSQL
包管理: pnpm
测试: vitest + playwright
关键命令:
- pnpm dev | build | test | lint | db:migrate
架构: App Router + Server Actions + Zod校验
禁止: 不用any | 不改ui/目录 | 不直连数据库
```
```markdown
# ~/project/src/features/CLAUDE.md (Directory - 15行)
---
每个功能一个文件夹: components + actions + types + test
Server Component优先 | 需要交互才用Client Component
Props用interface | 导出用命名导出
```
这个三层结构的总Token消耗约800-1000 Token，仅占200K上下文窗口的0.5%，却能提供精确的行为指导。
---
## 延伸阅读
- [Claude Code官方文档 - Memory系统](https://code.claude.com/docs/en/memory) — 完整的记忆系统参考
- [Claude Code官方文档 - 会话管理](https://code.claude.com/docs/en/sessions) — 会话恢复、命名、历史
- [Claude Code官方文档 - Worktree](https://code.claude.com/docs/en/worktrees) — Git Worktree并行开发
- [Claude Code官方文档 - Checkpointing](https://code.claude.com/docs/en/checkpointing) — 检查点与回滚
- [Claude Code Changelog](https://code.claude.com/docs/en/changelog) — 最新版本更新
---
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营类型 | Claude Code进阶训练营、AI编程效率提升营 |
| 建议教学时长 | 3小时（含实操练习） |
| 实操占比 | 60%（文件配置 + 会话管理 + Worktree） |
| 前置知识要求 | Claude Code基本操作、Git基础 |
| 课后练习建议 | 为自己的真实项目配置完整的三层CLAUDE.md + Memory系统 |
---
## 参考来源
1. [How Claude remembers your project - Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方CLAUDE.md与Auto Memory完整参考文档
2. [CLAUDE.md vs AGENTS.md vs MEMORY.md - Amit Ray](https://amitray.com/claude-md-vs-agents-md-memory-md-skills-md-context-md-guide-2026/) — AI配置文件层级体系对比分析
3. [Claude Code & Agent Memory: Best Practices for 2026 - Orchestrator](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — 分层记忆架构深度解读与最佳实践
4. [Context Compaction Research - badlogic/gist](https://gist.github.com/badlogic/cd2ef65b0697c4dbe2d13fbecb0a0a5f) — 上下文压缩机制跨工具对比研究
5. [Claude Code --continue and --resume Guide](https://pasqualepillitteri.it/en/news/366/claude-code-continue-resume-guide) — 会话恢复与管理的完整实战指南
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
