Claude Code六层记忆架构实战：从CLAUDE.md到Auto Memory

会话启动 → 加载记忆文件（全局/项目/规则） → 注入上下文 → Claude开始推理 → 用户发送第一条消息

# 全局偏好

## 语言与风格
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释

## 代码风格
- 优先使用 TypeScript，避免 any 类型
- 使用函数式编程风格，减少可变状态
- 变量命名使用 camelCase，常量使用 UPPER_SNAKE_CASE

## 通用规则
- 始终先读取文件再编辑，不要盲目修改
- 不要自动 commit，只在明确要求时执行
- 修改代码后主动运行测试验证

# 项目指令

## 技术栈
- Node.js 22, TypeScript 5.4, PostgreSQL 16
- 使用 ESM 模块，不用 CommonJS
- ORM 使用 Drizzle，不用 Prisma
- 包管理器：pnpm

## 代码架构
- Controller 层：`/src/controllers/`
- Service 层：`/src/services/` — 所有业务逻辑在这里
- 禁止在 Controller 中直接写数据库查询
- 所有 API 响应使用统一格式 `{ code, data, message }`

## 测试
- 使用 Vitest，不用 Jest
- 测试文件放在源文件旁边：`*.test.ts`
- 每个 exported 函数至少一个单元测试
- Mock 所有外部 HTTP 调用

## Git 规范
- commit message 格式：`type(scope): description`
- 类型：feat, fix, refactor, test, docs, chore

my-monorepo/
├── CLAUDE.md              # 全项目通用规则
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md      # 前端专属规则
│   ├── backend/
│   │   └── CLAUDE.md      # 后端专属规则
│   └── shared/
│       └── CLAUDE.md      # 共享库规则

# 前端模块规则

## 框架与工具
- Next.js 15 App Router
- Tailwind CSS v4，禁止使用 inline style
- 状态管理使用 Zustand

## 组件规范
- 所有组件使用 `"use client"` 或 `"use server"` 显式标记
- Props 使用 TypeScript interface 定义
- 组件文件名使用 PascalCase

# 本地个人配置

- 我prefer详细的错误处理和日志
- 调试时使用 console.log 而非 debugger
- 优先使用 vim 键位操作的编辑器模式

my-project/
├── CLAUDE.md                  # 入口文件，只做导入
├── .claude/
│   ├── code-style.md          # 代码风格规则
│   ├── architecture.md        # 架构规则
│   ├── testing.md             # 测试规范
│   └── security.md            # 安全策略
├── src/
└── tests/

# 项目指令

@.claude/code-style.md
@.claude/architecture.md
@.claude/testing.md
@.claude/security.md

# 代码风格

- TypeScript strict mode，零 any
- 使用 const 优先于 let，禁止 var
- 函数必须包含 JSDoc 注释
- 单文件不超过 300 行
- import 排序：内置模块 → 第三方 → 项目内部

# 安全规则

- 禁止日志输出敏感用户数据
- 所有用户输入必须验证和消毒
- SQL 查询必须使用参数化，禁止字符串拼接
- 密钥只从环境变量读取，永远不硬编码
- API 接口必须实现 rate limiting

---
paths:
  - "tests/**/*.py"
  - "test_*.py"
---

# Python 测试规范

- 使用 pytest，不用 unittest
- 测试函数名以 `test_` 开头
- 使用 `@pytest.fixture` 管理测试依赖
- Mock 使用 `unittest.mock.patch`

---
paths:
  - "src/components/**/*.tsx"
  - "src/app/**/*.tsx"
---

# 前端组件规范

- 使用 Server Components 为默认
- 只有需要交互的组件才标记 `"use client"`
- Props 通过 interface 定义，导出类型
- 使用 `cn()` 工具函数合并 Tailwind 类名

~/.claude/projects/my-project/memory/
├── MEMORY.md              # 主索引文件，每次会话加载前200行
├── debugging.md           # 调试经验记录
├── api-conventions.md     # API设计决策
└── patterns.md            # 代码模式记录

> 记住我们使用 pnpm 而不是 npm
> 保存到记忆：API 测试需要本地 Redis 实例
> 记录：staging 环境使用端口 3001

# Project Memory

## Build & Run
- Build: `pnpm build`
- Dev server: `pnpm dev` (port 3000)
- Tests: `pnpm test` (Vitest)
- Lint: `pnpm lint`

## Architecture
- Express + TypeScript backend
- PostgreSQL via Drizzle ORM
- Auth: JWT with refresh token rotation
- API prefix: `/api/v1/`

## Common Issues
- DB migrations: `pnpm db:migrate` before testing
- CORS: frontend must be on localhost:5173
- See debugging.md for resolved issues

# 列出所有项目的记忆文件
ls ~/.claude/projects/

# 查看特定项目的主记忆文件
cat ~/.claude/projects/my-project/memory/MEMORY.md

# 查看特定主题文件
cat ~/.claude/projects/my-project/memory/debugging.md

// ~/.claude/settings.json
{
  "autoMemoryEnabled": false
}

// .claude/settings.json
{
  "autoMemoryEnabled": false
}

fullstack-app/
├── CLAUDE.md                        # 入口：导入所有规则
├── CLAUDE.local.md                  # 本地个人偏好
├── .claude/
│   ├── settings.json                # 项目设置
│   └── rules/
│       ├── api-design.md            # API设计规范（通用）
│       ├── react-components.md      # React组件规范
│       ├── database.md              # 数据库操作规范
│       ├── python-scripts.md        # Python脚本规范
│       └── deployment.md            # 部署相关规范
├── packages/
│   ├── api/
│   │   └── CLAUDE.md               # API模块专属规则
│   └── web/
│       └── CLAUDE.md               # 前端模块专属规则
└── scripts/

# Fullstack App 项目指令

## 技术栈
- Monorepo: pnpm workspaces
- API: Express 5 + TypeScript + Drizzle ORM
- Frontend: React 19 + Vite + Tailwind CSS v4
- Database: PostgreSQL 16

## 通用规则
- 所有代码使用 TypeScript strict mode
- 包管理器：pnpm（禁止 npm 或 yarn）
- 测试框架：Vitest
- commit message: conventional commits

@.claude/rules/api-design.md
@.claude/rules/database.md
@.claude/rules/deployment.md

---
paths:
  - "packages/web/src/**/*.tsx"
  - "packages/web/src/**/*.ts"
---

# React 组件规范

- 使用函数组件 + Hooks，禁止 class 组件
- Props 使用 interface 定义并导出
- 状态管理：组件内用 useState，跨组件用 Zustand
- 样式：Tailwind CSS，禁止 inline style
- 组件拆分粒度：单文件不超过 200 行

---
paths:
  - "scripts/**/*.py"
---

# Python 脚本规范

- Python 3.12+
- 使用 uv 管理依赖
- 类型注解：所有函数参数和返回值
- 日志使用 logging 模块，不用 print

# API 模块规则

## 目录结构
- `routes/` — 路由定义
- `controllers/` — 请求处理
- `services/` — 业务逻辑（核心）
- `repositories/` — 数据库操作
- `middleware/` — 中间件

## API 设计
- RESTful 风格
- 统一响应格式：`{ code: number, data: T, message: string }`
- 错误处理：使用自定义 AppError 类
- 验证：Zod schema 验证所有输入

> /memory

📋 Memory Files Loaded:
  ✅ ~/.claude/CLAUDE.md (Global)
  ✅ ~/projects/fullstack-app/CLAUDE.md (Project)
  ✅ .claude/rules/api-design.md (Rule)
  ✅ .claude/rules/database.md (Rule)
  ✅ packages/api/CLAUDE.md (Directory)
  ✅ Auto Memory: MEMORY.md (200 lines loaded)

🔄 Auto Memory: ON

# ✅ 好的规则写法
- 使用 Vitest，不用 Jest
- 测试文件放在源文件旁边：`*.test.ts`
- 每个 exported 函数至少一个单元测试

# ❌ 差的规则写法
- 在这个项目中，我们团队经过讨论决定采用Vitest作为我们的测试框架，
  因为它比Jest更快，而且对ESM有更好的支持。我们希望所有的测试文件
  都能放在对应的源文件旁边...

# .gitignore
CLAUDE.local.md        # 个人本地偏好，不提交
.claude/settings.local.json  # 本地设置，不提交

# 以下应该提交到Git
# CLAUDE.md
# .claude/rules/*.md
# .claude/settings.json（项目级设置）

# 查看所有项目记忆
ls -la ~/.claude/projects/

# 查看特定项目的记忆文件
find ~/.claude/projects/my-project/memory/ -name "*.md" -exec wc -l {} +

# 查看总行数
wc -l ~/.claude/projects/my-project/memory/MEMORY.md

# Step 1: 创建项目级 CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目指令

## 技术栈
- [填写你的技术栈]

## 架构
- [填写关键架构决策]

## 规范
- [填写代码规范]

@.claude/rules/security.md
@.claude/rules/testing.md
EOF

# Step 2: 创建规则目录和文件
mkdir -p .claude/rules

cat > .claude/rules/security.md << 'EOF'
# 安全规则
- 所有用户输入必须验证
- SQL 使用参数化查询
- 密钥从环境变量读取
- 禁止日志输出敏感数据
EOF

cat > .claude/rules/testing.md << 'EOF'
---
paths:
  - "tests/**"
  - "**/*.test.ts"
  - "**/*.test.py"
---

# 测试规范
- 每个 exported 函数至少一个测试
- Mock 所有外部依赖
- 测试命名：should_预期行为_when_条件
EOF

# Step 3: 配置 .gitignore
echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore

# Step 4: 验证记忆加载
claude
# 在Claude Code会话中输入:
# /memory
# 确认所有文件被正确加载

📋 Memory Files:
  ✅ ~/.claude/CLAUDE.md (Global, 23 lines)
  ✅ ./CLAUDE.md (Project, 15 lines)
  ✅ .claude/rules/security.md (Rule, 4 lines)
  ✅ .claude/rules/testing.md (Rule, conditional)
  ✅ Auto Memory: enabled

# ~/.claude/CLAUDE.md
## 通用 API 项目规则
- TypeScript strict mode
- Vitest for testing
- Conventional commits
- Error handling: custom error classes

---
paths:
  - "**"
---

# Agent 约束
- 禁止删除任何文件（必须经用户确认）
- 禁止修改 .env 文件
- 禁止执行 git push 或 git reset --hard
- 每次文件修改不超过 5 个文件时需报告