每次新开会话都要重新解释项目？跨项目的编码偏好总被忘记？本文教你用 Claude Code 的三层记忆体系，让 Agent 像你的老搭档一样丝滑工作。

你的 Claude Code 是不是"健忘"？

打开 Claude Code，开始一个新会话，然后你就得重复这些事：

"这个项目用的 Node.js 22，别用 CommonJS"
"数据库是 PostgreSQL，不是 MySQL"
"记得用 TypeScript strict mode"
"测试框架是 Vitest，不要写 Jest 代码"
"API 密钥在环境变量里，别硬编码"

每次新会话=重新解释一遍。 一天 5 个会话，一年就是 1000+ 次重复劳动。更糟糕的是，有时候忘了说某个约束，Claude Code 就开始"自由发挥"——生成了 Jest 测试代码、用了 require 而不是 import、或者搞错了数据库方言。

这不是 Claude Code 的问题——是你的记忆系统没配好。

Claude Code 有三层持久化记忆机制，从全局到项目到会话，一层比一层精细。这篇文章把这三层完整拆解，配可复制的配置模板。

三层记忆体系总览

┌─────────────────────────────────────────┐
│  层级1: ~/.claude/settings.json         │  全局配置
│  所有项目生效，放API密钥/全局Hook       │
├─────────────────────────────────────────┤
│  层级2: CLAUDE.md（项目根目录）         │  项目记忆
│  当前项目生效，放架构/规范/约定         │
├─────────────────────────────────────────┤
│  层级3: /memory 命令（会话内）          │  会话记忆
│  当前会话生效，放临时决策/上下文        │
└─────────────────────────────────────────┘

每一层解决不同的问题。三层组合使用，Claude Code 才能像你的 10x 工程师搭档一样工作。

第一层：settings.json — 全局配置底座

~/.claude/settings.json 是 Claude Code 启动时最先加载的配置文件。它定义跨所有项目的全局行为。

基础模板

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(yarn:*)",
      "Bash(node:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(echo:*)",
      "Read(*)",
      "Write(*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  },
  "env": {
    "OPENAI_API_KEY": "sk-xxx",
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

关键字段详解

permissions.allow — Claude Code 的 Auto-Allow 白名单。命令匹配这里的模式时，Claude Code 不会弹出确认框，直接执行。适合高频安全操作（git、npm、ls）。

permissions.deny — 黑名单。优先级高于 allow。rm -rf /* 这种危险操作永远不会自动执行。curl 和 wget 列入 deny 可以防止 Agent 在你不注意时下载远程内容。

env — 全局环境变量。注意：别把 API 密钥明文写在这里（尤其是代码仓库会被提交的情况）。更好的做法是：

{
  "env": {
    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
  }
}

这样 Claude Code 会从你的 shell 环境变量中读取，settings.json 里不留明文。

进阶：按模型切换配置

如果你有多个模型（Sonnet 日常+Opus 复杂任务），可以用 modelOverrides：

{
  "model": "claude-sonnet-4-20250514",
  "modelOverrides": {
    "claude-sonnet-4-20250514": {
      "maxTokens": 4096
    },
    "claude-opus-4-20250514": {
      "maxTokens": 8192
    }
  }
}

Hook 配置（全局生效）

settings.json 还支持全局 Hook，在每次工具调用前后执行自定义逻辑：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push:*)",
        "hooks": [{
          "type": "command",
          "command": "echo '⚠️  You are about to push to remote. Current branch:' && git branch --show-current"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.test.*)",
        "hooks": [{
          "type": "command",
          "command": "npx vitest run --reporter=dot $CLAUDE_TOOL_PARAMETERS 2>/dev/null || true"
        }]
      }
    ]
  }
}

全局 Hook 的典型用途：
- PreToolUse：git push 前确认、rm 操作二次确认、数据库写入前备份
- PostToolUse：文件生成后自动跑测试、代码写入后自动格式化

第二层：CLAUDE.md — 项目记忆核心

CLAUDE.md 是 Claude Code 记忆体系的核心。它放在项目根目录，Claude Code 每次启动会话时自动加载。

基础模板（全栈项目）

# Project: [项目名]

## Tech Stack
- Frontend: React 19 + TypeScript 5.7 + Vite 6
- Backend: Node.js 22 + Fastify 5
- Database: PostgreSQL 16 + Prisma ORM
- Testing: Vitest + Playwright
- Package Manager: pnpm
- CI/CD: GitHub Actions

## Code Conventions
- Use `import`/`export` syntax (ESM), never `require`
- TypeScript strict mode ON
- File naming: `kebab-case.ts` for modules, `PascalCase.tsx` for components
- Tests co-located: `src/utils/foo.ts` → `src/utils/foo.test.ts`
- Prefer `async/await` over raw Promises
- Error handling: throw typed errors, never `console.error` for production code

## Architecture Rules
- API routes: `src/routes/[resource]/[action].ts`
- Business logic: `src/services/[resource].ts` — no HTTP concerns
- Database access: ONLY through Prisma client in `src/lib/prisma.ts`
- NEVER import PrismaClient outside of `src/lib/`

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
- DB push: `pnpm db:push`

## Current Context
- Working on: User authentication flow refactor
- Branch: `feat/oauth-refactor`
- Known issues: Rate limiting not yet implemented

模板2：一人创业项目（极简版）

# [产品名] — 一人公司全栈项目

## Stack
Next.js 15 + TypeScript + Tailwind CSS + Supabase + Vercel

## Non-negotiables
- NEVER add a dependency without asking. I'm the one paying for build minutes.
- Mobile-first CSS. Desktop is secondary.
- All API routes must have rate limiting. I can't afford a bill shock.
- Keep bundle < 200KB gzipped. Lighthouse score > 90.

## Financial Context (READ THIS FIRST)
- Monthly infra budget: $50 (Vercel Pro + Supabase Free)
- Every new API call = cost. Cache aggressively.
- User authentication = Supabase Auth (free tier). No custom auth.

这个模板的核心不同：加入了财务约束。一人公司不能像大厂一样随意加依赖和 API 调用，CLAUDE.md 就是 Claude Code 的"预算意识"。

模板3：微服务项目

# Monorepo: [平台名]

## Services
| 服务 | 目录 | 端口 | 数据库 | 负责人 |
|------|------|------|--------|--------|
| api-gateway | `svc/gateway` | 3000 | — | @alice |
| user-service | `svc/user` | 3001 | PostgreSQL | @bob |
| order-service | `svc/order` | 3002 | PostgreSQL | @bob |
| notification | `svc/notif` | 3003 | Redis | @alice |

## Inter-service Rules
- Communication: gRPC only (no REST between services)
- Auth: JWT propagated via gRPC metadata
- NEVER call another service's database directly — use gRPC
- Shared types: `packages/types/`

## Testing Per Service
- Unit: minimum 80% coverage per service
- Integration: at least one e2e scenario per endpoint
- Contract tests between services required before merge

CLAUDE.md 编写黄金法则

用命令式语气。不要写 "we use TypeScript"，写 "Use TypeScript strict mode"。Agent 更容易理解指令而非描述。
分层级。## Tech Stack → ## Code Conventions → ## Rules，从宏观到微观。
Non-negotiables 放最前面。Agent 读 CLAUDE.md 时注意力递减，最重要的约束要最先出现。
每次变更都更新。CLAIDE.md 过时比没有更糟糕。项目架构变了但 CLAUDE.md 没更新 = Agent 基于错误前提工作。
保持 < 300 行。太长 Claude Code 会截断或注意力涣散。如果超过 300 行，考虑拆分为多个 .claude/rules/*.md 文件（Claude Code 1.0.27+ 支持）。

第三层：/memory 命令 — 会话级上下文

/memory 是 Claude Code 的会话内记忆功能。它让 Agent 在当前会话中记住你告诉它的临时信息。

使用场景

场景1：纠正 Agent 的错误理解

你：这个项目用的是 pnpm，不是 npm
Claude Code：明白了。

[5分钟后]
Claude Code 执行：npm install react-router

你：/memory Use pnpm for all package management commands
Claude Code：✅ Memory saved. I'll use pnpm for all package operations.

场景2：临时技术决策

你：我们先做 MVP，不用考虑生产级错误处理。快速原型优先。
Claude Code：了解。

[写了 200 行代码后]
Claude Code：[开始写 try-catch 和错误边界]

你：/memory MVP mode: skip production error handling. Focus on happy path only.
Claude Code：✅ Memory saved. Happy path only, no error handling.

场景3：当前工作状态

你：/memory Current task: refactor user service from Express to Fastify.
      Files done: routes.ts. Files remaining: middleware.ts, handlers.ts, tests.
Claude Code：✅ Memory saved. I know where we are.

/memory 与 CLAUDE.md 的分工

	CLAUDE.md	/memory
持久性	跨会话永久	当前会话
内容类型	项目规范、架构、约定	临时决策、当前进度、纠偏
更新频率	项目变更时	随时
适用场景	"这个项目永远用 TypeScript"	"今天我们先跳过测试"

经验法则：如果一条规则在当前项目存活超过2天，把它从 /memory 移到 CLAUDE.md。

三层联动的实战案例

假设你在做一个 SaaS 产品，技术栈是 Next.js + Supabase。以下是完整配置：

`~/.claude/settings.json`

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Read(*)",
      "Write(*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(npm:*)"
    ]
  }
}

注意：Bash(npm:*) 在 deny 里——因为我们用 pnpm，npm 的任何操作都要被拦截。

`CLAUDE.md`

# SaaSly — SaaS Boilerplate

## Stack
Next.js 15 (App Router) + TypeScript + Tailwind + Supabase + Stripe

## Golden Rules
- pnpm ONLY. npm/yarn are forbidden.
- Server Components by default. `'use client'` only when absolutely needed.
- Database queries: use Supabase server client in Server Components. No client-side DB.
- Environment variables: NEXT_PUBLIC_ prefix for client, no prefix for server.

## Architecture
- `app/` — routes and layouts (App Router)
- `components/` — shared UI components
- `lib/` — utils, supabase client, stripe
- `actions/` — server actions

## Cost Constraints
- Supabase free tier: 500MB DB, 2GB bandwidth
- Vercel Pro: $20/mo
- Avoid unnecessary API routes — prefer Server Actions

会话中

Claude Code：[开始写代码]

你：我们今天的目标是搭好 landing page 和 signup flow。
    /memory Today's scope: landing page + signup only. 
    No dashboard, no settings, no billing yet.

Claude Code：✅ Memory saved. Landing page + signup flow only.

你：[10分钟后]
    这里 landing page 的 CTA 按钮，先用 `#` 占位链接，后端还没好。
    /memory All CTA buttons link to "#" for now. Don't create actual routes.

Claude Code：✅ Got it. Placeholder links only.

常见错误和修复

错误1：settings.json 里加太多 allow 规则

// ❌ 危险
{
  "permissions": {
    "allow": ["Bash(*)", "Write(*)"]
  }
}

这让 Claude Code 可以执行任何命令、写入任何文件。Agent 一旦产生幻觉后果不堪设想。

// ✅ 正确：最小权限原则
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(pnpm:*)",
      "Bash(ls:*)",
      "Bash(npx vitest:*)"
    ]
  }
}

错误2：CLAUDE.md 只写技术栈，不写约束

# ❌ 信息量太低
This is a Next.js project.

Claude Code 知道什么是 Next.js。你需要告诉它的是这个特定项目的约束。

# ✅ 有约束才算配置
- Use App Router, never Pages Router
- All images must use next/image with explicit width/height
- No client-side data fetching — use Server Components

错误3：把 API 密钥写在 CLAUDE.md 里

CLAUDE.md 通常会被 git 提交。API 密钥放 settings.json 的 env 字段（不提交），或从 shell 环境变量读。

错误4：永远不清理 /memory

/memory 会在会话中持续积累。10 轮对话后 Agent 的记忆里可能有 8 条过时信息。定期用 /memory（空命令）列出所有记忆，手动清理。

总结：记忆系统的正确打开方式

你要做的事	放哪里	为什么
API 密钥	`settings.json` → `env`	全局生效，不提交 Git
危险命令拦截	`settings.json` → `permissions.deny`	全局安全底线
项目技术栈	`CLAUDE.md`	每个项目不同
编码规范	`CLAUDE.md`	持久生效
当前工作上下文	`/memory`	会话级别，随时调整
临时决策	`/memory`	存活期 < 2 天

核心原则：settings.json 管安全，CLAUDE.md 管知识，/memory 管状态。三层分开，各司其职。

把这套配置好，Claude Code 从一个"每次都要重新教的实习生"变成了一个"记得你所有偏好的老搭档"。配置只需要 30 分钟，但能省下未来每一周、每一个项目、每一个会话的重复劳动。

AI创业 #ClaudeCode #Agent工坊 #一人公司 #AI编程 #配置指南 #开发效率