Claude Code 记忆与配置体系深度实战：从 CLAUDE.md 到六层记忆架构

graph TB
    A[新会话启动] --> B[上下文窗口为空]
    B --> C{加载记忆}
    C --> D[CLAUDE.md 层级]
    C --> E[Auto Memory]
    C --> F[Rules 规则文件]
    D --> D1[~/.claude/CLAUDE.md<br/>用户全局]
    D --> D2[项目根/CLAUDE.md<br/>项目共享]
    D --> D3[子目录/CLAUDE.md<br/>模块专属]
    D --> D4[CLAUDE.local.md<br/>个人不提交]
    E --> E1[.claude/memory/*.md<br/>主题记忆文件]
    F --> F1[.claude/rules/*.md<br/>路径规则]
    B --> G[会话对话]
    G --> H[自动记忆写入]
    H --> E1

# 全局偏好

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

## 编码习惯
- 优先使用函数式编程风格
- 变量命名使用 camelCase
- 始终添加 TypeScript 类型注解

## 通用规则
- 修改代码后主动运行测试
- 不要自动 commit，除非明确要求
- 不要提交 .env 等敏感文件

# 创建用户全局 CLAUDE.md
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局偏好
- 默认中文回复
- 修改后运行测试
- 不自动 commit
EOF

# 或使用 Claude Code 的 /memory 命令
# 在 Claude Code 中输入: /memory 然后添加内容

# 项目：电商平台 API

## 技术栈
- Runtime: Node.js 22 + TypeScript 5.8
- Framework: Fastify 5（注意：不是 Express）
- ORM: Drizzle ORM + PostgreSQL 16
- 测试: Vitest + Supertest
- 包管理: pnpm 9

## 项目结构
- `src/routes/` — API 路由（按领域分文件）
- `src/services/` — 业务逻辑层
- `src/db/schema/` — 数据库 Schema
- `src/middleware/` — 中间件
- `test/` — 测试文件镜像 src 结构

## 命令
- 开发: `pnpm dev`
- 构建: `pnpm build`
- 测试: `pnpm test`
- 单测: `pnpm test:unit`
- Lint: `pnpm lint`

## 编码规范
- 路由必须使用 Fastify schema validation
- Service 层不能直接访问 Fastify request/reply
- 数据库操作必须通过 Drizzle query builder
- 错误使用 AppError 类，禁止直接 throw new Error

## 架构决策
- API 版本化通过 URL 前缀: `/api/v1/`, `/api/v2/`
- 认证使用 JWT + Refresh Token 双令牌
- 文件上传使用 S3 预签名 URL

# 个人本地配置（不提交）

## 调试
- 当前在调试支付模块的并发问题
- 本地数据库端口: 5433（非默认）
- 使用 test_ 前缀的测试数据

## 临时偏好
- 详细输出 SQL 查询日志
- 跳过集成测试

# 确保 CLAUDE.local.md 不被提交
echo "CLAUDE.local.md" >> .gitignore

# src/workers/CLAUDE.md

## Worker 模块规范
- 所有 Worker 必须继承 BaseWorker 类
- 使用 BullMQ 队列，不用 Bull
- 重试策略: 最多 3 次，指数退避
- 必须实现 graceful shutdown
- 日志使用结构化 JSON 格式

## 命名约定
- 文件名: `{domain}.worker.ts`
- 类名: `{Domain}Worker`
- 队列名: `{domain}:{action}`

mkdir -p .claude/rules

<!-- .claude/rules/react-components.md -->
---
description: React 组件开发规则
globs: src/components/**/*.tsx
---

## React 组件规范
- 使用函数组件 + Hooks
- Props 必须定义 TypeScript interface
- 使用 React.memo 包裹纯展示组件
- 样式使用 Tailwind CSS 类名
- 组件文件名使用 PascalCase

<!-- .claude/rules/api-routes.md -->
---
description: API 路由开发规则
globs: src/routes/**/*.ts
---

## API 路由规范
- 必须定义 Fastify schema（request/response）
- 使用 rate-limit 插件
- 错误处理统一使用 setNotFoundHandler/setErrorHandler
- 路由注册在 src/routes/index.ts 统一导出

# 查看自动记忆目录
ls .claude/memory/
# 输出示例:
# architecture-decisions.md
# api-patterns.md
# debugging-notes.md

---
name: architecture-decisions
description: 项目架构决策记录
metadata:
  type: project
---

## 决策记录
- 2026-06-10: 选择 Fastify 替代 Express，原因是性能基准测试提升 40%
- 2026-06-08: 采用 Drizzle ORM 替代 Prisma，避免生成步骤和更好的 TypeScript 支持

# 在 Claude Code 会话中
> /memory
# 输入要记住的内容，Claude 会自动写入合适的记忆文件

// .claude/settings.json
{
  // ===== 权限配置 =====
  "permissions": {
    "allow": [
      // Bash 命令白名单
      "Bash(pnpm install)",
      "Bash(pnpm test)",
      "Bash(pnpm test:unit)",
      "Bash(pnpm lint)",
      "Bash(pnpm build)",
      "Bash(pnpm dev)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(docker compose *)",

      // 文件操作白名单
      "Read(*)",
      "Write(src/**)",
      "Edit(src/**)",
      "Edit(test/**)"
    ],
    "deny": [
      // 禁止写入的危险路径
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | bash*)"
    ]
  },

  // ===== 环境变量 =====
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost:5433/myapp_dev",
    "REDIS_URL": "redis://localhost:6379"
  },

  // ===== Hooks 配置 =====
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-bash-validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/post-format-check.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify.sh"
          }
        ]
      }
    ]
  },

  // ===== MCP 服务器 =====
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5433/myapp_dev"
      }
    }
  },

  // ===== 其他设置 =====
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "preferredNotifChannel": "iterm2"
}

graph LR
    A[工具调用请求] --> B{检查权限}
    B -->|在 allow 列表| C[自动执行]
    B -->|在 deny 列表| D[拒绝执行]
    B -->|未匹配任何规则| E[弹出确认]
    E -->|用户允许| F[执行 + 记住选择]
    E -->|用户拒绝| G[跳过]

{
  "permissions": {
    "allow": [
      // 精确匹配：只允许特定命令
      "Bash(git status)",

      // 通配符匹配：允许以某前缀开头的命令
      "Bash(pnpm test*)",

      // 路径通配符：允许操作特定目录下的文件
      "Write(src/**/*.ts)",
      "Edit(test/**/*.test.ts)",

      // 完全通配：允许该工具的所有操作（谨慎使用）
      "Read(*)"
    ]
  }
}

# 在 Claude Code 会话中
> /permissions
# 会打开交互式 UI，可以添加/删除/修改权限规则

# 临时允许特定命令
claude --allow "Bash(pnpm test)" --allow "Bash(pnpm lint)"

# 临时设置模型
claude --model claude-opus-4-8

# 一次性执行命令
claude -p "运行所有测试并报告结果" --allowedTools "Bash(pnpm test)"

sequenceDiagram
    participant U as 用户
    participant C as Claude Code
    participant H as Hook 脚本
    participant T as 工具

    U->>C: 输入指令
    C->>C: 决定调用工具
    C->>H: PreToolUse Hook
    H-->>C: approve / deny / 修改参数
    alt Hook 批准
        C->>T: 执行工具
        T-->>C: 返回结果
        C->>H: PostToolUse Hook
        H-->>C: 后处理完成
    else Hook 拒绝
        C-->>U: 报告被拒绝
    end

# 创建 hooks 目录
mkdir -p .claude/hooks

# .claude/hooks/pre-bash-validate.sh
#!/bin/bash
# 从 stdin 读取工具调用的 JSON 输入
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 阻止危险命令
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "drop database"
  "DROP TABLE"
  "truncate table"
  "sudo rm"
  ":(){:|:&};:"
  "mkfs"
  "dd if="
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "BLOCKED: 命令包含危险操作 '$pattern'"
    exit 1  # exit 1 = 阻止执行
  fi
done

# 阻止生产环境操作
if echo "$COMMAND" | grep -qi "prod\|production"; then
  echo "BLOCKED: 当前不允许操作生产环境"
  exit 1
fi

# 允许执行
exit 0

chmod +x .claude/hooks/pre-bash-validate.sh

# .claude/hooks/post-format-check.sh
#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 只在文件写入/编辑时触发
if [[ "$TOOL" == "Write" || "$TOOL" == "Edit" ]]; then
  # TypeScript/JavaScript 文件自动格式化
  if echo "$FILE_PATH" | grep -qE '\.(ts|tsx|js|jsx)$'; then
    pnpm prettier --write "$FILE_PATH" 2>/dev/null
    echo "Formatted: $FILE_PATH"
  fi

  # Python 文件自动格式化
  if echo "$FILE_PATH" | grep -qE '\.py$'; then
    ruff format "$FILE_PATH" 2>/dev/null
    echo "Formatted: $FILE_PATH"
  fi
fi

exit 0

# .claude/hooks/notify.sh
#!/bin/bash
INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Claude Code 任务完成"')

# macOS 通知
if [[ "$OSTYPE" == "darwin"* ]]; then
  osascript -e "display notification \"$MESSAGE\" with title \"Claude Code\""
fi

# Linux 通知
if [[ "$OSTYPE" == "linux"* ]]; then
  notify-send "Claude Code" "$MESSAGE" 2>/dev/null
fi

# iTerm2 通知（如果安装了 it2attention）
which it2attention &>/dev/null && it2attention fireworks

exit 0

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-bash-validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/post-format-check.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[✓] Claude Code 会话结束' >> .claude/session-log.txt"
          }
        ]
      }
    ]
  }
}

# 创建项目
mkdir -p ecommerce-api && cd ecommerce-api
git init

# 创建 Claude Code 配置目录结构
mkdir -p .claude/rules .claude/hooks .claude/memory

# 初始化 Claude Code
claude
# 在 Claude Code 中输入:
> /init
# Claude 会扫描项目并生成初始 CLAUDE.md

# 电商平台 API

## 技术栈
- Node.js 22 + TypeScript 5.8
- Fastify 5 + Drizzle ORM + PostgreSQL 16
- BullMQ + Redis 7（消息队列）
- pnpm 9 + Vitest

## 项目结构

## 命令
- `pnpm dev` — 开发服务器
- `pnpm build` — 生产构建
- `pnpm test` — 运行所有测试
- `pnpm test:unit` — 只跑单元测试
- `pnpm test:integration` — 只跑集成测试
- `pnpm lint` — ESLint 检查
- `pnpm db:generate` — 生成数据库迁移
- `pnpm db:migrate` — 执行迁移

## 编码规范
- 使用函数式风格，避免 class
- 错误使用 AppError，不要 throw new Error()
- 路由必须定义 Fastify schema validation
- Service 层不能直接依赖 Fastify request/reply
- 所有 async 函数必须处理错误

## 测试规范
- 单元测试: `test/**/*.test.ts`
- 集成测试: `test/**/*.integration.test.ts`
- 使用 `test()` 而非 `it()`
- Mock 外部依赖，不要 mock 内部模块

## 注意事项
- 不要修改 src/generated/ 目录（代码生成产物）
- 不要直接操作数据库，使用 Drizzle query builder
- 修改 Schema 后必须运行 `pnpm db:generate`
- API 必须有版本前缀 /api/v1/ 或 /api/v2/

# React 前端规则（如果项目有前端）
cat > .claude/rules/frontend.md << 'RULEEOF'
---
description: 前端 React 组件开发规则
globs: frontend/src/**/*.tsx
---

## 前端规范
- 使用 React 19 + Server Components
- 样式使用 Tailwind CSS v4
- 状态管理使用 Zustand
- 数据获取使用 TanStack Query v5
- 组件文件名 PascalCase.tsx
RULEEOF

# Worker 规则
cat > .claude/rules/workers.md << 'RULEEOF'
---
description: BullMQ Worker 开发规则
globs: src/workers/**/*.ts
---

## Worker 规范
- 继承 BaseWorker 类
- 队列命名: `{domain}:{action}`
- 重试: 最大 3 次，指数退避
- 必须实现 graceful shutdown
- 日志使用结构化 JSON
RULEEOF

# 数据库规则
cat > .claude/rules/database.md << 'RULEEOF'
---
description: 数据库 Schema 和迁移规则
globs: src/db/**/*.ts
---

## 数据库规范
- Schema 定义在 src/db/schema/
- 使用 Drizzle 的 pgTable 定义
- 所有表必须有 createdAt/updatedAt 字段
- 软删除使用 deletedAt 字段
- 索引命名: idx_{table}_{columns}
RULEEOF

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(pnpm *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git checkout *)",
      "Bash(docker compose *)",
      "Bash(node *)",
      "Bash(npx *)",
      "Read(*)",
      "Write(src/**)",
      "Write(test/**)",
      "Write(.claude/rules/**)",
      "Edit(src/**)",
      "Edit(test/**)"
    ],
    "deny": [
      "Write(.env*)",
      "Write(*.pem)",
      "Write(*.key)",
      "Write(terraform/**)",
      "Write(.github/workflows/**)",
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(DROP *)",
      "Bash(production *)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-bash-validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/post-format-check.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify.sh"
          }
        ]
      }
    ]
  }
}

# 添加到 .gitignore
cat >> .gitignore << 'EOF'

# Claude Code 个人配置
CLAUDE.local.md
.claude/settings.local.json
.claude/memory/
.claude/todos/
EOF

# 启动 Claude Code 并验证
claude

# 在 Claude Code 中执行以下验证：
> 列出你加载的所有记忆文件和规则
# Claude 应该显示：
# - ~/.claude/CLAUDE.md（用户全局）
# - ./CLAUDE.md（项目根）
# - .claude/rules/*.md（路径规则）
# - 确认 settings.json 已加载

> 创建一个新的 API 路由 /api/v2/products
# Claude 应该：
# - 使用 Fastify 而非 Express
# - 文件放在 src/routes/v2/
# - 定义 schema validation
# - 自动运行格式化 hook
# - 不触碰 .env 或其他禁止文件

graph TD
    A[CLAUDE.md 总内容] --> B{超过 200 行?}
    B -->|否| C[保持单文件即可]
    B -->|是| D[拆分为路径规则]
    D --> E[通用规则保留在 CLAUDE.md]
    D --> F[领域规则移到 .claude/rules/]
    D --> G[临时笔记用 /memory]

# 提交共享配置，忽略个人配置
git add CLAUDE.md .claude/rules/ .claude/settings.json .claude/hooks/
git commit -m "chore: add Claude Code configuration"

# 个人配置在 .gitignore 中排除
# CLAUDE.local.md
# .claude/settings.local.json
# .claude/memory/

// 企业管理员配置（通过管理平台下发）
{
  "permissions": {
    "deny": [
      "Bash(curl * | *sh)",
      "Bash(wget * | *sh)",
      "Bash(eval *)",
      "Write(/etc/*)",
      "Write(/var/*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/claude-security-audit.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "company-knowledge": {
      "command": "npx",
      "args": ["-y", "@company/mcp-knowledge-base"],
      "env": {
        "API_URL": "https://internal-api.company.com"
      }
    }
  }
}

flowchart TB
    subgraph 会话启动
        A[用户输入 claude] --> B[加载全局 CLAUDE.md]
        B --> C[加载项目 CLAUDE.md]
        C --> D[加载 CLAUDE.local.md]
        D --> E[加载路径规则 .claude/rules/]
        E --> F[加载自动记忆 .claude/memory/]
        F --> G[加载 settings.json]
        G --> H[注册 Hooks]
    end

    subgraph 对话过程
        H --> I[用户输入指令]
        I --> J[Claude 分析意图]
        J --> K{需要调用工具?}
        K -->|是| L[触发 PreToolUse Hook]
        L --> M{Hook 批准?}
        M -->|是| N[执行工具]
        M -->|否| O[报告拒绝]
        N --> P[触发 PostToolUse Hook]
        P --> Q[返回结果给 Claude]
        K -->|否| Q
        Q --> R[Claude 生成回复]
        R --> S{需要保存记忆?}
        S -->|是| T[写入 .claude/memory/]
        S -->|否| U[继续对话]
        T --> U
        U --> I
    end

    style A fill:#4A90D9,color:#fff
    style H fill:#7B68EE,color:#fff
    style N fill:#50C878,color:#fff
    style T fill:#FFD700,color:#333