## 概述
Claude Code的"记忆"远不止一个CLAUDE.md文件。它拥有**六层分层记忆架构**——从全局用户偏好到项目指令、从目录级规则到会话自动记忆，每一层都承载不同粒度的上下文。本教程将带你逐层拆解这套架构，通过一个真实项目实战，掌握从`~/.claude/`全局配置到`.claude/`项目目录、从`CLAUDE.md`到`rules/`、从`settings.json`权限到自动记忆的完整上下文工程链路。
**适用人群**：已安装Claude Code并完成至少一次对话的开发者，希望系统化理解和管理Claude Code的上下文行为。
---
## 前置条件
| 条件 | 说明 |
|------|------|
| Claude Code | 已通过`npm install -g @anthropic-ai/claude-code`安装 |
| Node.js ≥ 18 | Claude Code运行环境 |
| 一个真实项目 | 任何有3个以上源文件的项目均可（本文用Node.js项目演示） |
| 基础命令行知识 | 能使用`ls`、`cat`、`mkdir`等命令 |
```bash
# 验证Claude Code已安装
claude --version
# 预期输出：claude-code/x.x.x (或类似版本号)
```
---
## 第一层：理解六层记忆架构
Claude Code的上下文不是"一坨文本"，而是一个精心设计的分层系统。Anthropic官方将其描述为"naively dropped into context"（直接注入上下文窗口），但实际使用中，理解每一层的加载优先级和作用范围至关重要。
```mermaid
graph TB
subgraph "Claude Code 六层记忆架构"
L1["第1层: 全局 ~/.claude/CLAUDE.md
跨项目用户偏好"]
L2["第2层: 项目根 ./CLAUDE.md
项目级指令"]
L3["第3层: 目录级 ./src/CLAUDE.md
子目录特定规则"]
L4["第4层: .claude/rules/*.md
模块化规则文件"]
L5["第5层: 会话记忆
auto-memory自动摘要"]
L6["第6层: 跨工具共享记忆
AGENTS.md / GEMINI.md"]
end
L1 --> L2 --> L3
L2 --> L4
L3 --> L5
L4 --> L5
L5 --> L6
style L1 fill:#e8f5e9
style L2 fill:#e3f2fd
style L3 fill:#fff3e0
style L4 fill:#fce4ec
style L5 fill:#f3e5f5
style L6 fill:#e0f7fa
```
**加载顺序**：Claude Code在每次会话启动时，按**全局 → 项目 → 目录**的层级读取CLAUDE.md，同时加载`.claude/rules/`下的所有规则文件。会话记忆在对话过程中动态写入，跨工具记忆则兼容Cursor、Copilot等多AI工具。
---
## 第二层：全局配置 — ~/.claude/ 目录
### 2.1 目录结构全景
```bash
~/.claude/
├── CLAUDE.md # 全局用户偏好（所有项目生效）
├── settings.json # 全局权限与MCP配置
├── credentials.json # 认证信息（不要手动编辑）
├── statsig/ # 遥测数据
├── projects/ # 每个项目的工作记忆
│ └── -home-user-myproject/
│ └── CLAUDE.md # 项目特定会话记忆
├── skills/ # 全局Skills
├── commands/ # 全局自定义命令
└── memory/ # 跨会话记忆存储
```
### 2.2 编写全局CLAUDE.md
全局CLAUDE.md定义你的**个人编码风格**和**跨项目通用偏好**：
```bash
# 创建或编辑全局CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences
## Language & Style
- 默认使用中文回复，代码注释可用英文
- 回复简洁明了，避免冗长解释
## Code Style
- 使用TypeScript strict模式
- 优先函数式编程，避免不必要的class
- 变量命名用camelCase，文件名用kebab-case
- 所有函数必须有返回类型注解
## Testing
- 新功能必须包含单元测试
- 使用vitest作为测试框架
- 测试文件命名: *.test.ts
## Git
- commit message使用conventional commits格式
- 不要自动commit，只在明确要求时执行
- 不要自动git add
EOF
```
**关键原则**：全局CLAUDE.md应该只放**真正的跨项目偏好**。项目特定的架构决策、依赖版本、API约定应该放在项目级CLAUDE.md中。
### 2.3 settings.json权限配置
`~/.claude/settings.json`控制Claude Code的**行为权限**：
```json
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(npx tsc --noEmit)",
"Read",
"Glob",
"Grep"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)",
"Bash(npm publish)"
]
},
"autoCompact": true,
"compactThreshold": 80000
}
```
**`allow`数组**中的工具调用将自动执行，不再弹出确认；**`deny`数组**中的操作会被直接拒绝。`autoCompact`启用上下文自动压缩，`compactThreshold`设置触发压缩的token阈值。
---
## 第三层：项目级配置 — ./CLAUDE.md 与 .claude/ 目录
### 3.1 快速初始化
```bash
# 进入你的项目目录
cd ~/my-project
# 使用Claude Code内置的/init命令生成CLAUDE.md
claude
# 在Claude Code交互界面中输入:
> /init
```
`/init`命令会自动扫描项目结构、读取`package.json`/`tsconfig.json`等配置文件，生成一份初始CLAUDE.md。这是**起点而非终点**——你需要根据实际需求持续迭代。
### 3.2 编写高质量项目CLAUDE.md
一份好的项目CLAUDE.md应该回答四个问题：**这个项目是什么？怎么跑？怎么测？有什么约定？**
```markdown
# MyProject - E-Commerce API
## 项目概述
Node.js + Fastify + PostgreSQL的电商后端API服务。
使用TypeScript严格模式，遵循分层架构。
## 技术栈
- Runtime: Node.js 22
- Framework: Fastify 5.x
- ORM: Drizzle ORM
- Database: PostgreSQL 16
- Testing: Vitest + Supertest
## 项目结构
```
src/
├── routes/ # API路由定义
├── services/ # 业务逻辑层
├── repositories/ # 数据访问层
├── middleware/ # 中间件
├── schemas/ # 请求/响应验证schema
└── utils/ # 工具函数
```
## 常用命令
- `npm run dev` — 启动开发服务器（端口3000）
- `npm test` — 运行全部测试
- `npm run test:watch` — 监听模式运行测试
- `npm run db:migrate` — 执行数据库迁移
- `npm run db:seed` — 填充测试数据
## 编码约定
- 所有API路由必须有对应的schema验证
- Service层不直接依赖Fastify实例
- 错误处理使用AppError类，不要throw原生Error
- 数据库查询在repository层完成，service层不写SQL
- 日志使用Fastify内置logger，不用console.log
## 禁止事项
- 不要修改migrations目录中已有的迁移文件
- 不要在routes层写业务逻辑
- 不要引入新的ORM（统一使用Drizzle）
```
### 3.3 目录级CLAUDE.md — 精细化控制
当一个项目足够复杂时，你可以在**子目录**放置CLAUDE.md，为该目录下的文件提供特定上下文：
```bash
# 为数据库层提供额外上下文
cat > src/repositories/CLAUDE.md << 'EOF'
## Repository层规则
- 所有查询使用Drizzle query builder
- 复杂查询（JOIN超过3张表）必须写注释说明
- 分页查询统一使用paginate()工具函数
- 不要使用raw SQL，除非性能要求极高且有注释说明
- 每个Repository类必须有对应的interface
EOF
# 为测试目录提供上下文
cat > src/__tests__/CLAUDE.md << 'EOF'
## 测试规则
- 使用describe/it结构组织测试
- 每个测试文件对应一个源文件
- 测试数据使用factory函数生成，不要硬编码
- 集成测试使用testcontainers启动PostgreSQL
- Mock只在外部服务边界使用，不要mock内部模块
EOF
```
**加载机制**：当Claude Code读取`src/repositories/user.repo.ts`时，会同时加载项目根CLAUDE.md和`src/repositories/CLAUDE.md`，两层指令合并生效。
---
## 第四层：模块化规则 — .claude/rules/
当CLAUDE.md变得过长时，`.claude/rules/`目录提供了**模块化拆分**的方案：
```bash
# 创建rules目录
mkdir -p .claude/rules
```
### 4.1 按职责拆分规则文件
```bash
# API设计规则
cat > .claude/rules/api-design.md << 'EOF'
---
description: Rules for API endpoint design
globs: ["src/routes/**"]
All API endpoints must:
1. Define request/response schemas using TypeBox
2. Use proper HTTP status codes (201 for creation, 204 for deletion)
3. Include authentication middleware for protected routes
4. Return consistent error format: { error: string, code: string, details?: any }
5. Support pagination for list endpoints with ?page&limit query params
EOF
# 数据库规则
cat > .claude/rules/database.md << 'EOF'
---
description: Database and migration rules
globs: ["src/repositories/**", "drizzle/**"]
Database conventions:
- All tables must have: id (uuid), created_at, updated_at columns
- Use UUID v7 for primary keys
- Soft delete using deleted_at column, never hard delete
- Index all foreign key columns
- Migration files are immutable once merged to main
EOF
# 安全规则
cat > .claude/rules/security.md << 'EOF'
---
description: Security best practices
globs: ["src/**"]
Security requirements:
- Never log sensitive data (passwords, tokens, PII)
- Use parameterized queries only (Drizzle handles this)
- Validate all input at route layer
- Hash passwords with bcrypt (cost factor 12)
- JWT tokens expire in 15 minutes, refresh tokens in 7 days
EOF
```
### 4.2 frontmatter中的globs字段
注意每个规则文件顶部的`---`区域：
```yaml
---
description: 规则描述（必填）
globs: ["匹配的文件路径模式"]
---
```
- **description**：必填，Claude Code用此判断规则是否相关
- **globs**：可选，指定规则在编辑哪些文件时生效。省略则全局生效
这意味着当Claude Code编辑`src/routes/users.ts`时，只会加载`api-design.md`和`security.md`，而不会加载`database.md`——**精确控制上下文窗口消耗**。
---
## 第五层：会话记忆 — Auto Memory
### 5.1 自动记忆的工作原理
Claude Code在对话过程中会**自动写入**会话记忆。当你完成一个复杂任务后，Claude Code会在后台生成摘要，存储到`~/.claude/projects/`目录下：
```bash
# 查看自动记忆存储位置
ls ~/.claude/projects/
# 典型路径结构：
# ~/.claude/projects/-home-user-myproject/CLAUDE.md
```
### 5.2 手动管理会话记忆
```bash
# 在Claude Code会话中，使用/memory命令管理记忆
> /memory
# 查看当前项目记忆内容
# 你可以编辑、删除或添加记忆条目
```
你也可以直接编辑记忆文件来添加**长期生效的知识**：
```bash
# 编辑项目记忆
vim ~/.claude/projects/-home-user-myproject/CLAUDE.md
```
```markdown
## 项目记忆 (Auto-generated + Manual)
### 已解决的问题
- 2026-05-20: Drizzle ORM的joins语法在v0.38有变化，使用db.select().from(a).leftJoin(b, eq(a.id, b.aId))
- 2026-05-22: Fastify 5的schema验证必须在route options中定义，不能单独.register
### 架构决策
- 选择Drizzle而非Prisma，因为更好的类型推断和性能
- 使用plugin模式组织路由，每个domain一个plugin
### 已知的坑
- PostgreSQL的JSONB查询需要显式类型转换
- testcontainers启动慢，CI中需要30秒预热
```
### 5.3 上下文窗口管理策略
Claude Code的上下文窗口是**有限资源**。当对话过长时，性能会下降。以下是管理策略：
```mermaid
graph LR
A[会话开始] --> B{上下文是否充足?}
B -->|是| C[正常对话]
B -->|否| D[自动压缩
autoCompact]
D --> E[保留关键信息
丢弃历史细节]
E --> C
C --> F{任务完成?}
F -->|否| B
F -->|是| G[重要知识写入
项目记忆]
style D fill:#fff3e0
style G fill:#e8f5e9
```
**实操建议**：
| 策略 | 操作 | 效果 |
|------|------|------|
| 启用自动压缩 | `settings.json`中设`autoCompact: true` | 上下文过长时自动摘要 |
| 控制CLAUDE.md长度 | 项目CLAUDE.md控制在100行以内 | 减少每次加载的token |
| 使用rules分片 | 将规则拆到`.claude/rules/` | 只加载相关规则 |
| 及时开新会话 | 复杂任务拆成多个会话 | 避免上下文污染 |
| 写入项目记忆 | 完成后总结关键知识 | 跨会话持久化 |
---
## 第六层：跨工具共享记忆
### 6.1 兼容其他AI工具的配置文件
现代开发团队可能同时使用Claude Code、Cursor、GitHub Copilot等多个AI工具。通过在项目根目录放置多个配置文件，可以让所有工具共享核心上下文：
```bash
my-project/
├── CLAUDE.md # Claude Code专用（最丰富）
├── AGENTS.md # GitHub Copilot / Codex
├── .cursorrules # Cursor（或.cursor/rules/）
├── GEMINI.md # Gemini CLI
├── .windsurfrules # Windsurf
└── .github/copilot-instructions.md # GitHub Copilot另一种方式
```
### 6.2 实战：统一指令源
维护多个文件容易不同步。推荐策略是**以CLAUDE.md为主源**，其他文件通过符号链接或引用指向它：
```bash
# 方案1：符号链接（最简单）
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md .cursorrules
# 方案2：精简版（推荐）
# AGENTS.md只保留跨工具通用的部分
cat > AGENTS.md << 'EOF'
# Shared AI Instructions
> Full project instructions in CLAUDE.md
## Code Style
- TypeScript strict mode
- Functional style preferred
- camelCase for variables, kebab-case for files
## Testing
- Vitest for unit tests
- All new features require tests
## Architecture
- Layered: routes → services → repositories
- See CLAUDE.md for complete details
EOF
```
---
## 实战案例：为一个真实项目搭建完整上下文工程
现在让我们将六层记忆架构整合到一个完整的实战案例中。假设我们有一个电商API项目需要从零配置Claude Code的上下文系统。
### Step 1：创建项目结构
```bash
mkdir ~/shop-api && cd ~/shop-api
npm init -y
npm install fastify drizzle-orm pg
npm install -D typescript vitest @types/pg drizzle-kit
# 创建.claude目录结构
mkdir -p .claude/rules
mkdir -p src/routes
mkdir -p src/services
mkdir -p src/repositories
mkdir -p src/__tests__
```
### Step 2：生成初始CLAUDE.md
```bash
claude
# 在交互界面中输入:
> /init
# Claude Code会自动分析package.json和项目结构
```
### Step 3：迭代优化CLAUDE.md
将自动生成的CLAUDE.md优化为以下内容：
```markdown
# ShopAPI - 电商后端服务
## 一句话概述
Fastify + Drizzle ORM + PostgreSQL的RESTful电商API。
## 开发命令
- `npm run dev` — 开发服务器 localhost:3000
- `npm test` — 运行所有测试
- `npm run db:push` — 推送schema到数据库
- `npm run db:studio` — 打开Drizzle Studio
## 架构
严格三层架构：Routes → Services → Repositories
- Routes：HTTP处理、请求验证、响应格式化
- Services：业务逻辑、事务编排
- Repositories：数据库CRUD、SQL查询
## 编码规范
- 所有async函数必须处理错误（try/catch或Result类型）
- Repository方法返回`Promise`而非`Promise`
- 禁止在Service层直接import数据库实例
- 路由使用Fastify plugin模式注册
## 禁止
- 不要生成mock数据文件到src/目录
- 不要引入class-validator（使用TypeBox）
- 不要在routes中写SQL
```
### Step 4：创建模块化规则
```bash
cat > .claude/routes-rules.md << 'RULES'
---
description: Route layer conventions
globs: ["src/routes/**"]
---
## Route Rules
- Every route file exports a FastifyPluginAsync
- Use shorthand methods: app.get(), app.post(), etc.
- Schema validation with TypeBox in route options
- Error responses use reply.code().send() pattern
- Group related routes in one file (e.g., users.ts has GET/POST/PUT/DELETE /users)
RULES
cat > .claude/testing-rules.md << 'RULES'
---
description: Testing conventions
globs: ["src/__tests__/**", "**/*.test.ts"]
---
## Test Rules
- Use describe/it structure with meaningful descriptions
- Integration tests start with "should" verbs
- Factory functions for test data in helpers/test-factories.ts
- Each test file is independent (no shared mutable state)
- Use beforeAll for database setup, afterAll for cleanup
RULES
```
注意：上面的规则文件也可以放在`.claude/rules/`目录下（推荐做法）。
### Step 5：验证配置生效
```bash
# 启动Claude Code
claude
# 测试上下文加载
> 你知道这个项目的技术栈和架构吗？
# 预期：Claude Code会准确描述Fastify + Drizzle + PostgreSQL三层架构
# 测试规则生效
> 帮我在src/routes/products.ts创建一个GET /products路由
# 预期：生成的代码会遵循以下规则：
# 1. 使用FastifyPluginAsync导出
# 2. 包含TypeBox schema验证
# 3. 调用Service层而非直接查数据库
# 4. 使用app.get()简写形式
```
### Step 6：迭代改进
在使用过程中持续迭代：
```mermaid
graph TD
A[使用Claude Code开发] --> B{AI生成代码
是否符合预期?}
B -->|是| C[继续开发]
B -->|否| D[分析偏差原因]
D --> E{是CLAUDE.md
缺少信息吗?}
E -->|是| F[补充到CLAUDE.md
或rules/]
E -->|否| G{是规则不够
具体吗?}
G -->|是| H[细化规则描述
添加示例]
G -->|否| I[考虑是否需要
会话记忆补充]
F --> C
H --> C
I --> J[写入项目记忆
~/.claude/projects/]
J --> C
style F fill:#e3f2fd
style H fill:#fff3e0
style J fill:#e8f5e9
```
---
## .claude/目录完整结构参考
实战完成后的完整目录结构：
```
.claude/
├── rules/ # 模块化规则
│ ├── api-design.md # API设计规则
│ ├── database.md # 数据库规则
│ ├── security.md # 安全规则
│ ├── routes-rules.md # 路由层规则
│ └── testing-rules.md # 测试规则
├── settings.json # 项目级权限配置
├── commands/ # 自定义斜杠命令
│ └── debug.md # /debug 命令
└── skills/ # 项目级Skills
~/.claude/
├── CLAUDE.md # 全局偏好
├── settings.json # 全局权限
├── projects/
│ └── -home-user-shop-api/
│ └── CLAUDE.md # 项目会话记忆
└── skills/ # 全局Skills
```
项目根目录：
```
shop-api/
├── CLAUDE.md # 项目主指令
├── AGENTS.md # 跨工具共享
├── .claude/ # Claude Code配置目录
├── src/
│ ├── CLAUDE.md # src级通用规则
│ ├── routes/
│ │ └── CLAUDE.md # 路由层特定规则
│ ├── services/
│ │ └── CLAUDE.md # 服务层特定规则
│ ├── repositories/
│ │ └── CLAUDE.md # 仓储层特定规则
│ └── __tests__/
│ └── CLAUDE.md # 测试规则
├── package.json
└── tsconfig.json
```
---
## 常见问题与解决方案
### Q1：CLAUDE.md写了但Claude Code不遵守？
**原因**：通常是CLAUDE.md内容过于宽泛。例如"写好代码"这种指令没有可操作性。
**解决**：用具体的、可验证的规则替代抽象原则。
```markdown
# ❌ 无效写法
写干净的代码，遵循最佳实践。
# ✅ 有效写法
- 所有函数必须有返回类型注解
- 函数体不超过30行，超过则拆分
- 错误使用AppError类，不要throw new Error()
- 禁止使用any类型
```
### Q2：上下文窗口不够用？
**解决方案**：
1. 启用`autoCompact`（在settings.json中）
2. 将CLAUDE.md精简到100行以内
3. 将详细规则移到`.claude/rules/`并设置globs，只在使用相关文件时加载
4. 复杂任务拆分成多个会话
### Q3：全局CLAUDE.md和项目CLAUDE.md冲突？
**优先级规则**：**项目级覆盖全局级**。如果全局说"用jest"，项目说"用vitest"，Claude Code会遵循vitest。
建议：全局CLAUDE.md只放**真正跨项目**的偏好（语言、回复风格），项目特定的技术选型全部放在项目CLAUDE.md中。
### Q4：rules/目录的globs不生效？
**检查项**：
1. frontmatter格式正确（三个短横线包围）
2. globs模式使用相对于项目根的路径
3. 文件扩展名`.md`正确
```yaml
# ✅ 正确格式
---
description: Route conventions
globs: ["src/routes/**"]
---
# ❌ 错误格式（缺少---）
description: Route conventions
globs: ["src/routes/**"]
```
### Q5：多个AI工具的配置文件如何同步？
**推荐策略**：
- **单一源策略**：以CLAUDE.md为唯一真实源，AGENTS.md等文件用符号链接
- **分层策略**：CLAUDE.md包含完整指令，AGENTS.md包含精简版通用部分
- **CI校验**：在CI中添加检查，确保AGENTS.md的关键内容与CLAUDE.md一致
---
## 上下文工程清单：六层配置速查
| 层级 | 文件位置 | 作用范围 | 最佳用途 |
|------|----------|----------|----------|
| L1 全局 | `~/.claude/CLAUDE.md` | 所有项目 | 个人编码风格、语言偏好 |
| L2 项目 | `./CLAUDE.md` | 当前项目 | 技术栈、架构、命令、约定 |
| L3 目录 | `./src/**/CLAUDE.md` | 子目录 | 层级特定规则（如测试约定） |
| L4 规则 | `.claude/rules/*.md` | 按globs匹配 | 模块化细粒度规则 |
| L5 会话 | `~/.claude/projects/` | 跨会话 | 已解决问题、架构决策 |
| L6 跨工具 | `AGENTS.md` / `.cursorrules` | 多AI工具 | 通用指令共享 |
---
## 训练营适用性评估
| 维度 | 说明 |
|------|------|
| **适合训练营类型** | AI辅助开发训练营、DevOps效率训练营、团队工程规范训练营 |
| **预计教学时长** | 2-3小时（含动手练习） |
| **难度等级** | 中级（需要Claude Code基础使用经验） |
| **前置课程** | Claude Code入门安装教程 |
| **后续课程** | Skill开发实战、MCP服务器开发、自动化Hooks |
| **实操比例** | 70%实操 + 30%理论 |
| **团队适配性** | 高 — CLAUDE.md和rules可以作为团队代码规范的AI强制层 |
---
## 参考来源
1. [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — Anthropic官方上下文工程方法论，定义了CLAUDE.md注入机制和分层策略
2. [Claude Code & Agent Memory: Best Practices for 2026](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — Claude Code分层记忆架构深度解析，六层模型的原始出处
3. [The Complete .claude Directory Guide for Claude Code](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — .claude目录完整结构参考，涵盖settings.json、rules、skills、commands等子系统
4. [Claude Code Memory Levels Explained: 6 Layers](https://www.mindstudio.ai/blog/claude-code-memory-levels-explained-6-layers-claude-md-cross-tool-shared-memory) — 六层记忆架构从Level 1到Level 6的渐进式解读
5. [Awesome CLAUDE.md — GitHub](https://github.com/josix/awesome-claude-md) — 公开项目中优秀CLAUDE.md文件集合，包含多行业多框架的实战模板
> [!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 等场景全覆盖。
