Claude Code六层记忆体系与个性化配置深度实战

graph TB
    subgraph "Claude Code 六层记忆架构"
        L1["第1层: System Prompt<br/>内置系统指令"]
        L2["第2层: ~/.claude/CLAUDE.md<br/>用户全局偏好"]
        L3["第3层: 项目根目录/CLAUDE.md<br/>团队共享规范"]
        L4["第4层: 子目录/.claude/CLAUDE.md<br/>模块级上下文"]
        L5["第5层: Auto-Memory<br/>~/.claude/projects/记忆文件"]
        L6["第6层: Cross-Tool/AGENTS.md<br/>跨工具共享标准"]
    end
    L1 --> L2 --> L3 --> L4 --> L5 --> L6
    style L1 fill:#e8f5e9
    style L2 fill:#fff3e0
    style L3 fill:#e3f2fd
    style L4 fill:#f3e5f5
    style L5 fill:#fce4ec
    style L6 fill:#e0f7fa

# 确保 ~/.claude 目录存在
mkdir -p ~/.claude

# 创建全局 CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

## Language & Style
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释
- 代码/命令保持原文，说明用中文

## Coding Preferences
- 前端项目优先使用 TypeScript
- 后端API优先使用 Python FastAPI
- 测试框架优先使用 Vitest (前端) / pytest (后端)
- Git commit message 使用 Conventional Commits 规范

## Safety Rules
- 不要自动 git commit，只在明确要求时执行
- 始终先读取文件再编辑
- 不要提交 .env 等敏感文件
- 修改代码后主动运行测试验证
EOF

# 在任意项目目录启动 Claude Code，然后输入：
claude
# 进入对话后输入：
# "我的编码偏好是什么？"
# Claude 会准确复述你配置的内容

# 在你的项目根目录
cd ~/my-project

cat > CLAUDE.md << 'EOF'
# Project: My E-Commerce Platform

## Tech Stack
- Frontend: Next.js 14 + TypeScript + Tailwind CSS
- Backend: Python 3.12 + FastAPI + SQLAlchemy 2.0
- Database: PostgreSQL 16
- Cache: Redis 7
- Queue: Celery + RabbitMQ

## Project Structure

## Code Conventions
- API 路由使用 RESTful 风格，版本化: /api/v1/
- 所有 API 必须有对应的 Pydantic schema 验证
- 数据库迁移使用 Alembic，禁止手动修改表结构
- 前端组件使用函数式组件 + Hooks
- 状态管理使用 Zustand，不用 Redux

## Testing Requirements
- 后端测试覆盖率目标: 80%
- 每个 API endpoint 必须有集成测试
- 前端使用 Testing Library + MSW mock

## Common Commands
- `make dev` - 启动开发环境
- `make test` - 运行所有测试
- `make lint` - 代码检查
- `make migrate` - 执行数据库迁移
EOF

graph LR
    subgraph "项目目录结构"
        A["~/project/CLAUDE.md<br/>项目全局规范"]
        B["~/project/frontend/.claude/CLAUDE.md<br/>前端模块规范"]
        C["~/project/backend/.claude/CLAUDE.md<br/>后端模块规范"]
        D["~/project/backend/api/.claude/CLAUDE.md<br/>API模块规范"]
    end
    A --> B
    A --> C
    C --> D
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#f3e5f5

# 前端模块
mkdir -p ~/my-project/frontend/.claude
cat > ~/my-project/frontend/.claude/CLAUDE.md << 'EOF'
# Frontend Module Context

## Component Guidelines
- 使用 Server Components 为默认，只有需要交互时才用 'use client'
- 组件文件命名: PascalCase.tsx
- 自定义Hook文件命名: useCamelCase.ts
- 样式使用 Tailwind，禁止内联style属性

## Known Issues
- Next.js 14 的 revalidatePath 在某些场景下不生效，使用 router.refresh() 替代
- Zustand persist middleware 与 SSR 冲突，需要使用 dynamic import
EOF

# 后端模块
mkdir -p ~/my-project/backend/.claude
cat > ~/my-project/backend/.claude/CLAUDE.md << 'EOF'
# Backend Module Context

## API Design Rules
- 所有 endpoint 必须有 OAuth2 Bearer Token 认证
- 错误响应使用统一格式: {"error": {"code": "XXX", "message": "..."}}
- 分页使用 cursor-based pagination，不用 offset
- 响应时间超过500ms的查询必须加缓存

## Database Rules
- 禁止使用 SELECT *，必须明确列出字段
- 所有时间字段使用 UTC，前端负责时区转换
- 软删除使用 deleted_at 字段，不用 is_deleted 布尔值
EOF

~/.claude/projects/<project-hash>/
  MEMORY.md              # 索引文件：每个记忆文件一行摘要
  conventions.md         # 项目编码约定
  architecture.md        # 架构决策记录
  lessons-learned.md     # 犯过的错误和教训
  open-threads.md        # 未完成的工作线程
  user-preferences.md    # 用户偏好记录

# Memory Index

- [编码约定](conventions.md) — 项目编码风格和命名规范
- [架构决策](architecture.md) — 重大架构选择和原因
- [经验教训](lessons-learned.md) — 犯过的错误和纠正记录
- [开放线程](open-threads.md) — 未完成任务和待讨论事项
- [用户偏好](user-preferences.md) — 用户表达的个人偏好

# 首先找到你项目的记忆目录
# Claude Code 会根据项目路径生成 hash
# 可以通过在项目中运行 claude 然后输入 "你把记忆存储在哪个目录？" 来确认

# 创建记忆目录（示例路径）
MEMORY_DIR="$HOME/.claude/projects/-home-user-my-project/memory"
mkdir -p "$MEMORY_DIR"

# 创建索引文件
cat > "$MEMORY_DIR/MEMORY.md" << 'EOF'
# Memory Index

- [编码规范](coding-standards.md) — 项目编码风格和命名规范
- [架构决策](architecture-decisions.md) — 重大技术选型和架构选择
- [经验教训](lessons-learned.md) — 犯过的错误和纠正方案
- [开放线程](open-threads.md) — 未完成的工作和待确认事项
- [用户偏好](user-preferences.md) — 用户的个人编码偏好
EOF

# 编码规范记忆
cat > "$MEMORY_DIR/coding-standards.md" << 'EOF'
---
name: coding-standards
description: 项目编码风格和命名规范
metadata:
  type: project
---

# 编码规范

- Python 函数使用 snake_case 命名
- TypeScript 接口使用 PascalCase，以 I 开头
- 数据库表名使用 snake_case 复数形式
- API endpoint 使用 kebab-case

**Why:** 团队代码审查中反复出现命名不一致问题
**How to apply:** 创建新文件或函数时，先查阅此规范再命名
EOF

# 经验教训记忆
cat > "$MEMORY_DIR/lessons-learned.md" << 'EOF'
---
name: lessons-learned
description: 犯过的错误和纠正方案
metadata:
  type: feedback
---

# 经验教训

## 2026-06-10: Alembic迁移顺序问题
- **错误**: 直接修改了已提交的迁移文件，导致团队其他成员数据库不一致
- **纠正**: 已提交的迁移文件禁止修改，只能创建新的迁移来修正
- **相关**: [[coding-standards]]

## 2026-06-08: NextJS SSR hydration mismatch
- **错误**: 在 Server Component 中使用了 Date.now()，导致客户端hydration不匹配
- **纠正**: 时间相关操作必须在 Client Component 中执行，或通过 props 传入
EOF

# 在Claude Code对话中
# 查看当前记忆状态
> "你现在有哪些记忆文件？"

# 手动添加记忆
> "记住：这个项目的数据库密码字段始终使用 bcrypt 哈希，不要用 MD5"

# 纠正行为并自动记录
> "你刚才用了 var 声明变量，记住这个项目一律使用 const/let，禁止 var"

# 查看特定记忆
> "你在 lessons-learned.md 中记录了什么？"

flowchart TD
    A[会话开始] --> B[加载 MEMORY.md 索引]
    B --> C[按需加载相关 Topic Files]
    C --> D[正常工作]
    D --> E{犯错被纠正?}
    E -->|是| F[写入 lessons-learned.md]
    E -->|否| G{发现新模式?}
    G -->|是| H[更新对应 Topic File]
    G -->|否| I{会话结束?}
    F --> I
    H --> I
    I --> J[精简过时记忆]
    J --> K[更新 MEMORY.md 索引]
    K --> A

    style A fill:#e8f5e9
    style F fill:#fce4ec
    style H fill:#fff3e0
    style K fill:#e3f2fd

cat > ~/my-project/AGENTS.md << 'EOF'
# Agent Instructions

## Build & Test
- Build: `make build`
- Test: `make test`
- Lint: `make lint`

## Code Style
- Python: Follow PEP 8, use type hints
- TypeScript: Strict mode, no any types
- Commits: Conventional Commits format

## Architecture
- Monorepo with frontend/ and backend/
- API versioning: /api/v1/
- Database: PostgreSQL with Alembic migrations

## Safety
- Never drop database tables in production
- Always use parameterized queries
- Never commit .env files
EOF

graph TB
    subgraph "settings.json 配置层级"
        S1["企业管理级<br/>（由管理员统一下发）"]
        S2["用户全局级<br/>~/.claude/settings.json"]
        S3["用户项目级<br/>~/.claude/projects/.../settings.json"]
        S4["项目共享级<br/>.claude/settings.json"]
        S5["本地覆盖级<br/>.claude/settings.local.json"]
    end
    S1 --> S2 --> S3 --> S4 --> S5
    style S1 fill:#ffcdd2
    style S2 fill:#fff3e0
    style S3 fill:#e8f5e9
    style S4 fill:#e3f2fd
    style S5 fill:#f3e5f5

# 用户全局设置 — 定义基础安全策略
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(make test*)",
      "Bash(python -m pytest*)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Bash(wget * | bash)"
    ]
  }
}
EOF

# 项目级设置 — 项目特定的权限
mkdir -p ~/my-project/.claude
cat > ~/my-project/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker compose up*)",
      "Bash(docker compose down*)",
      "Bash(make migrate*)",
      "Bash(make seed*)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/myproject_dev"
  }
}
EOF

# 本地覆盖 — 个人开发环境特定配置（不提交Git）
cat > ~/my-project/.claude/settings.local.json << 'EOF'
{
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/myproject_local"
  }
}
EOF

# 确保本地配置不被提交
echo ".claude/settings.local.json" >> ~/my-project/.gitignore

{
  "permissions": {
    "allow": [
      "Bash(git *)",           // 允许所有 git 命令
      "Bash(npm run test*)",   // 允许测试相关命令
      "Bash(npm run lint*)",   // 允许 lint 相关命令
      "Bash(npx tsc --noEmit)", // 允许类型检查
      "Bash(docker compose *)", // 允许 docker compose 操作
      "Read(*)",               // 允许读取任何文件
      "Write(src/**)"          // 允许写入 src 目录下的文件
    ],
    "deny": [
      "Bash(sudo *)",          // 禁止 sudo
      "Bash(chmod 777*)",      // 禁止危险权限修改
      "Write(.env*)",          // 禁止修改环境变量文件
      "Write(**/secrets/**)"   // 禁止修改 secrets 目录
    ]
  }
}

# 在项目 .claude/settings.json 中添加 hooks 配置
cat > ~/my-project/.claude/settings.json << 'EOFJSON'
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(make *)",
      "Read(*)"
    ]
  },
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "bash .claude/hooks/save-session-summary.sh"
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "bash .claude/hooks/log-tool-usage.sh",
        "matcher": "Write|Edit"
      }
    ]
  }
}
EOFJSON

mkdir -p ~/my-project/.claude/hooks

# 会话结束时的摘要保存脚本
cat > ~/my-project/.claude/hooks/save-session-summary.sh << 'SCRIPT'
#!/bin/bash
# 记录会话结束时间
TIMESTAMP=$(date +"%Y-%m-%d %H:%M")
echo "- 会话结束于 $TIMESTAMP" >> .claude/session-log.md
SCRIPT
chmod +x ~/my-project/.claude/hooks/save-session-summary.sh

# 文件修改日志脚本
cat > ~/my-project/.claude/hooks/log-tool-usage.sh << 'SCRIPT'
#!/bin/bash
# 读取 stdin 中的工具调用信息
INPUT=$(cat)
FILE=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path','unknown'))" 2>/dev/null || echo "unknown")
TIMESTAMP=$(date +"%Y-%m-%d %H:%M")
echo "- [$TIMESTAMP] 修改文件: $FILE" >> .claude/file-changes-log.md
SCRIPT
chmod +x ~/my-project/.claude/hooks/log-tool-usage.sh

shop-platform/
├── CLAUDE.md                          # 第3层：项目共享记忆
├── AGENTS.md                          # 第6层：跨工具兼容
├── .claude/
│   ├── settings.json                  # 项目权限配置
│   ├── settings.local.json            # 本地覆盖（不提交Git）
│   └── hooks/
│       ├── save-session-summary.sh    # 会话结束Hook
│       └── log-tool-usage.sh         # 操作日志Hook
├── frontend/
│   ├── .claude/
│   │   └── CLAUDE.md                  # 第4层：前端模块上下文
│   └── ...
├── backend/
│   ├── .claude/
│   │   └── CLAUDE.md                  # 第4层：后端模块上下文
│   └── ...
~/.claude/
├── CLAUDE.md                          # 第2层：用户全局偏好
├── settings.json                      # 用户全局权限
└── projects/
    └── -home-user-shop-platform/
        └── memory/
            ├── MEMORY.md              # 记忆索引
            ├── coding-standards.md    # 编码规范
            ├── architecture.md        # 架构决策
            ├── lessons-learned.md     # 经验教训
            └── user-preferences.md    # 用户偏好

#!/bin/bash
# claude-code-setup.sh — 一键配置 Claude Code 完整记忆体系
# 使用方法: bash claude-code-setup.sh /path/to/your/project

PROJECT_DIR="${1:-$(pwd)}"
PROJECT_NAME=$(basename "$PROJECT_DIR")

echo "🧠 为项目 $PROJECT_NAME 配置 Claude Code 记忆体系..."

# === 第2层：用户全局偏好 ===
mkdir -p ~/.claude
if [ ! -f ~/.claude/CLAUDE.md ]; then
  cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

## Language
- 默认使用中文回复，代码注释用英文
- 代码/命令保持原文，说明用中文

## Coding Style
- TypeScript strict mode
- Python type hints required
- Conventional Commits

## Safety
- 不要自动 git commit
- 始终先读取文件再编辑
- 不要提交敏感文件
- 修改代码后主动运行测试
EOF
  echo "✅ 创建全局 CLAUDE.md"
fi

# === 用户全局权限 ===
if [ ! -f ~/.claude/settings.json ]; then
  cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(python -m pytest*)",
      "Read(*)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /)"
    ]
  }
}
EOF
  echo "✅ 创建全局 settings.json"
fi

# === 第3层：项目级 CLAUDE.md ===
cat > "$PROJECT_DIR/CLAUDE.md" << EOF
# Project: $PROJECT_NAME

## Tech Stack
- 在此处填写你的技术栈

## Project Structure
- 在此处描述项目结构

## Code Conventions
- 在此处定义编码规范

## Common Commands
- 在此处列出常用命令
EOF
echo "✅ 创建项目 CLAUDE.md"

# === 项目权限配置 ===
mkdir -p "$PROJECT_DIR/.claude"
cat > "$PROJECT_DIR/.claude/settings.json" << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(docker compose *)"
    ]
  }
}
EOF
echo "✅ 创建项目 settings.json"

# === AGENTS.md 跨工具兼容 ===
cat > "$PROJECT_DIR/AGENTS.md" << 'EOF'
# Agent Instructions

## Build & Test
- 在此处填写构建和测试命令

## Code Style
- 在此处定义通用代码风格

## Safety
- 在此处定义安全规则
EOF
echo "✅ 创建 AGENTS.md"

# === 第5层：Auto-Memory 记忆系统 ===
# 生成项目路径hash（简化版本）
PROJECT_HASH=$(echo -n "$PROJECT_DIR" | sha256sum | cut -c1-16)
MEMORY_DIR="$HOME/.claude/projects/-${PROJECT_HASH}/memory"
mkdir -p "$MEMORY_DIR"

cat > "$MEMORY_DIR/MEMORY.md" << 'EOF'
# Memory Index

- [编码规范](coding-standards.md) — 项目编码风格和命名规范
- [架构决策](architecture.md) — 重大技术选型和架构选择
- [经验教训](lessons-learned.md) — 犯过的错误和纠正方案
- [用户偏好](user-preferences.md) — 用户的个人编码偏好
EOF

# 创建空Topic Files
for topic in coding-standards architecture lessons-learned user-preferences; do
  cat > "$MEMORY_DIR/${topic}.md" << EOF
---
name: ${topic}
description: ${topic} 记忆文件
metadata:
  type: project
---

# ${topic}

（此文件将在使用过程中由Claude自动填充）
EOF
done
echo "✅ 创建记忆系统 ($MEMORY_DIR)"

# === .gitignore 更新 ===
if [ -f "$PROJECT_DIR/.gitignore" ]; then
  if ! grep -q ".claude/settings.local.json" "$PROJECT_DIR/.gitignore"; then
    echo -e "\n# Claude Code local settings\n.claude/settings.local.json" >> "$PROJECT_DIR/.gitignore"
  fi
else
  echo ".claude/settings.local.json" > "$PROJECT_DIR/.gitignore"
fi
echo "✅ 更新 .gitignore"

echo ""
echo "🎉 配置完成！你的 Claude Code 现在具备："
echo "  📝 全局用户偏好（跨项目生效）"
echo "  📋 项目共享规范（团队协作）"
echo "  🔒 安全权限体系（防止误操作）"
echo "  🧠 自动记忆系统（跨会话学习）"
echo "  🔗 跨工具兼容（AGENTS.md）"
echo ""
echo "下一步：在项目目录运行 'claude' 开始使用"

cd ~/shop-platform
claude

# 验证1：检查记忆加载
> "请列出你当前加载的所有CLAUDE.md文件的内容摘要"

# 验证2：检查偏好识别
> "我的全局编码偏好是什么？"

# 验证3：检查权限生效
> "运行 sudo apt update"  
# 预期：被deny规则拦截

# 验证4：检查自动记忆
> "记住：这个项目的所有API返回都必须包含request_id字段"
# 然后关闭会话，重新打开
> "关于API返回你记住了什么？"
# 预期：能回忆起刚才的要求

# 在 Topic File 的 frontmatter 中添加优先级
---
name: critical-security-rules
description: 安全相关的重要规则
metadata:
  type: feedback
  priority: critical
---

# 安全规则

- 所有用户输入必须经过验证和清洗
- 禁止在日志中记录敏感信息

# 提交项目级配置到Git
git add CLAUDE.md AGENTS.md .claude/settings.json
git commit -m "feat: add Claude Code memory and permission configuration"

graph LR
    subgraph "开发者工作流"
        A["CLAUDE.md<br/>Claude Code 专属"]
        B["AGENTS.md<br/>跨工具通用"]
        C[".cursorrules<br/>Cursor 专属"]
        D[".github/copilot<br/>Copilot 专属"]
    end

    B --> A
    B --> C
    B --> D

    E["统一编码规范<br/>统一安全规则<br/>统一构建命令"] --> B

    style B fill:#e0f7fa
    style E fill:#fff9c4

# 错误示范：在CLAUDE.md中写教程
CLAUDE.md (500行，包含完整的React教程)

# 正确示范：只写规则
CLAUDE.md (50行，精炼的规则和命令)

# 错误示范
file-a.md 引用 [[file-b]]
file-b.md 引用 [[file-a]]
# 导致上下文窗口浪费

# 正确示范
使用 MEMORY.md 作为单一索引，避免直接交叉引用

# 危险示范
{
  "permissions": {
    "allow": ["Bash(*)"]  // 允许所有命令
  }
}

# 安全示范
{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(npm test*)",
      "Read(*)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf *)"
    ]
  }
}

flowchart TB
    Start["启动 Claude Code"] --> LoadGlobal["加载 ~/.claude/CLAUDE.md<br/>用户全局偏好"]
    LoadGlobal --> LoadProject["加载 项目/CLAUDE.md<br/>项目共享规范"]
    LoadProject --> LoadSub["加载 子目录/.claude/CLAUDE.md<br/>模块级上下文"]
    LoadSub --> LoadMemory["加载 MEMORY.md + Topic Files<br/>自动记忆系统"]
    LoadMemory --> LoadSettings["加载 settings.json<br/>权限配置"]
    LoadSettings --> Ready["🚀 准备就绪"]

    Ready --> Work["正常工作"]
    Work --> Decision{需要权限?}
    Decision -->|已allow| AutoExec["自动执行"]
    Decision -->|已deny| Reject["拒绝执行"]
    Decision -->|未配置| AskUser["询问用户"]

    AutoExec --> Work
    Reject --> Work
    AskUser --> Work

    Work --> Error{犯错被纠正?}
    Error -->|是| SaveMemory["写入 Auto-Memory"]
    Error -->|否| End{会话结束?}
    SaveMemory --> End
    End -->|是| HookRun["运行 Stop Hooks"]
    HookRun --> Save["保存会话摘要"]
    Save --> Done["✅ 会话结束<br/>记忆已持久化"]

    style Start fill:#e8f5e9
    style Ready fill:#c8e6c9
    style Done fill:#a5d6a7
    style SaveMemory fill:#fce4ec
    style Reject fill:#ffcdd2