博客文章
Claude Code 配置指南：三层记忆 + 四层执行
Claude Code 每次会话都是全新上下文，没有配置就没有记忆。本文把官方文档翻了几遍后总结出完整配置体系：记忆层三层（CLAUDE.md、Rules、Auto Memory），执行层四层（Skills、MCP、Hooks、Agents），一篇看全。
Claude Code 配置指南：三层记忆 + 四层执行
前言
先说三个你可能遇到过的场景。
-
AI 用废弃 API
-
AI 不懂项目架构
-
跨会话失忆
每次新会话，前面说过的全忘光。
上次对话：花了10分钟告诉 AI，项目资源加载统一用
AssetLoader.load()，不要直接用resources.load()。下次对话：AI 又在写
resources.load("hero", ...)了。
根本原因只有一个：Claude Code 每次会话都是全新的上下文，没有配置就没有记忆。
要解决这个问题，需要一套系统性的配置体系——不只是写一个 CLAUDE.md 扔进去就完事了。我最近把ClaudeCode的文档翻了好几遍。
总结下来分成两部分：
- 记忆层：（三层）
- CLAUDE.md 全局记忆 （需要精简）
- Rules 规则记忆 （解决上下文臃肿）
- Auto Memory 自动记忆 （自动记录）
- 执行层：（四层）
- Skills 重复性流程
- MCP 外部工具扩展
- Hooks 自动执行
- Agents 专业技能
第一部分：三层记忆
这一部分解决的是「AI 知道什么」的问题——会话开始前，哪些信息已经在 AI 的上下文里。
查看命令
/context
第1层：CLAUDE.md
放在项目根目录（或 .claude/CLAUDE.md）的 Markdown 文件，每次 Claude Code 启动时自动读取。
三种作用域：
| 位置 | 作用域 | 用途 |
|---|---|---|
./CLAUDE.md |
项目级 | 团队共享，随代码仓库提交 |
~/.claude/CLAUDE.md |
用户级 | 个人偏好，跨所有项目生效 |
| 系统级路径 | 全组织 | IT 统一下发（我们用不到这层） |
游戏项目里写什么
四类内容，每类都有具体示例。
a. 引擎版本约束 — 明确告诉 AI 用的是哪个版本，避免写出废弃 API：
## 项目概述
基于 Cocos Creator 3.8.8 的 2D 射击游戏。
- 禁止使用已移除 API：cc.loader、cc.Class
b. 框架模块映射表 — 告诉 AI 有哪些自研模块。注意路径列写普通文本，不用 @ 语法（下面会解释原因）：
## 框架模块
| 需求 | 使用模块 | 规范文件 |
|------|---------|---------|
| UI 窗口 | bit-ui → Window 基类 | `.claude/rules/ui-module.md` |
| ECS 逻辑 | bit-ecs → Component/System | `.claude/rules/ecs-workflow.md` |
| 事件通信 | bit-event → GlobalEvent | `.claude/rules/event-module.md` |
| 资源加载 | bit-assets → AssetLoader | `.claude/rules/assets-module.md` |
c. 核心架构约束：
## 代码规范
- 禁止跨模块直接调用，事件通信必须通过 Event
- 禁止使用 any 类型
d. 项目关键路径：
## 项目关键路径
| 路径 | 说明 |
|------|------|
| `assets/script/` | 游戏脚本 |
| `assets/script/ecs/` | ECS 组件和系统 |
怎么写才有效
指令要写到「可以验证」的程度，模糊的要求 AI 会自由发挥：
| ✅ 好的 | ❌ 不好的 |
|---|---|
| 使用 2 空格缩进 | 正确格式化代码 |
提交前运行 npm test |
测试你的改动 |
脚本文件放在 assets/script/ |
保持文件组织有序 |
禁止使用 any 类型 |
注意类型安全 |
越具体，AI 遵守得越稳定。
为什么要精简
CLAUDE.md 内容在每次会话开始时全量注入上下文窗口。文件越长，消耗的 token 越多，AI 对后半段内容的遵守度越低。
官方建议每个 CLAUDE.md 控制在 200 行以内；实操建议 50-100 行。超出部分有两个出路：拆到 Rules 文件（第2层），或用 @path 语法引用外部文件。
@path 语法专项说明
CLAUDE.md 支持用 @路径 语法导入外部文件（最大5跳），常见用途：
查看 @README 了解项目概述，查看 @package.json 了解可用的 npm 命令。
关键：@path 引用的文件在启动时立即全量展开加载，与 CLAUDE.md 本身同时进入上下文。
适合用 @path 引用的内容：每次会话都需要的文档（README、package.json、个人偏好文件）。
不适合用 @path 引用 Rules 文件，原因看这张表：
| 机制 | 加载时机 | 加载条件 | 适合放什么 |
|---|---|---|---|
@path 引用 |
启动时立即加载 | 无条件，每次都加载 | 每次都需要的文档 |
Rules paths frontmatter |
按需加载 | AI 处理匹配路径的文件时 | 场景化的代码规范 |
如果在映射表里用 @.claude/rules/ecs-workflow.md，ECS 规则会在每次启动时全量加载，哪怕你在写 UI 代码——Rules 按需加载的优势完全失效。映射表里的路径用普通文本就好。
第2层：Rules — 动态注入的规范
CLAUDE.md 只是告诉 AI「有哪些规范」，但完整的规范内容（ECS 组件怎么写、UI 窗口怎么写）全部塞进去就太长了，而且写 ECS 代码时根本不需要看 UI 规范。Rules 解决的是「按场景动态注入」的问题。
工作原理：
- 文件放在
.claude/rules/目录 - 头部 YAML frontmatter 声明触发路径（glob 模式）
- 当会话中首次遇到匹配路径的文件时触发注入，并在当前会话内持续生效——不是启动时加载，也不是每次工具调用都重新注入
- 没有
paths字段的 Rules 文件 = 全局生效，等同于 CLAUDE.md 的补充
完整示例 — ecs-workflow.md：
---
paths:
- "assets/script/ecs/**/*.ts"
---
# ECS 工作流
## 开发顺序
1. 先写 Component（定义数据结构）
2. 再写 System（定义处理逻辑）
## 规范
- Component 只存储数据，禁止包含业务逻辑
- Component 必须实现 reset() 方法
- System 禁止存储持久状态
- 装饰器解构：const { ecsclass, ecsprop } = ecs._ecsdecorator
CLAUDE.md vs Rules 分工：
| 内容类型 | 放哪里 | 理由 |
|---|---|---|
| 引擎版本约束 | CLAUDE.md | 全局有效 |
| 框架模块索引表 | CLAUDE.md | 全局索引，帮 AI 找到对应 Rules |
| ECS 组件/系统写法 | Rules | 只写 ECS 代码时需要 |
| UI 窗口规范 | Rules | 只写 UI 代码时需要 |
| 命名规范、代码质量 | Rules | 写 .ts 代码时通用，适合用 @path |
CLAUDE.md 写「有什么、用什么」，Rules 写「怎么写」。
第3层：Auto Memory — AI 自己写的学习笔记
前两层都是你手动写的。Auto Memory 是 Claude Code 在对话过程中主动保存的跨会话记忆，你不用写任何东西，AI 自己决定什么值得记录。类比：AI 自己的工作笔记本。
和 CLAUDE.md 的核心区别：
| CLAUDE.md | Auto Memory | |
|---|---|---|
| 谁写 | 你 | Claude |
| 内容 | 规范和指令 | 学习到的经验和偏好 |
| 适合记什么 | 框架约定、代码规范 | 构建命令、调试经验、个人习惯 |
| 加载方式 | 全量加载 | MEMORY.md 索引加载（前200行） |
存储位置： ~/.claude/projects/<项目路径>/memory/
MEMORY.md：入口索引，每次会话自动加载 前 200 行- 其他
.md文件：按主题拆分的详细笔记，Claude 按需读取
使用方式：
- 查看已记录的内容：
/memory命令 - 让 AI 记住某件事：直接说「记住，我们项目的构建命令是 npm run build:dev」
- 让 AI 写入 CLAUDE.md 而不是 Auto Memory：说「把这条加到 CLAUDE.md」
AI 什么时候会主动记录
Auto Memory 不是每次对话都写入，AI 会判断这条信息「对未来的对话有没有用」。通常会触发记录的情况：你纠正了它的某个做法（「不是这样用的，应该……」）、你告诉它项目特有的约定、你指出了一个反复出现的错误。日常的问答、代码生成，AI 一般不会主动写入。
第二部分：四层执行
Skills — 把固定流程封装成一句命令
Skills 是告诉 AI 应该怎么做流程——告诉 AI 按这些步骤执行
以 /create-window ShopWindow Shop 为例，这一句命令背后 AI 自动完成 4 个步骤：
- 读取 FGUI 工程 XML 文件，提取所有节点名称和类型
- 按类型映射表（
<button>→GButton、<text>→GTextField）生成属性声明 - 套用 Window 基类模板，加上
@uiclass、@uiprop装饰器 - 写入到正确目录
生成的代码：
import { UI, FGUI } from "../header";
const { uiclass, uiclick, uiprop } = UI._uidecorator;
@uiclass("Window", "Shop", "ShopWindow")
export class ShopWindow extends UI.Window {
@uiprop private _btn_close: FGUI.GButton;
@uiprop private _btn_buy: FGUI.GButton;
@uiprop private _txt_title: FGUI.GTextField;
protected onInit(): void {
this.type = UI.WindowType.Normal;
}
@uiclick
private onCloseSelf(): void {
this.removeSelf();
}
@uiclick
private onBuy(): void {
}
}
什么情况下值得封装成 Skills（满足 2-3 条就做）：
- 频率高：这个任务一周会做几次
- 步骤固定：每次流程相同，不需要灵活判断（需要灵活判断的更适合 Agents）
- 容易出错：手动做容易遗漏或写错
- 每次要解释：触发前都要给 AI 交代一遍流程
文件放哪：官方原生路径 .claude/commands/<command-name>.md，头部 YAML 配置触发名称、参数说明，正文是执行步骤。
---
description: 从 FGUI XML 生成窗口代码，用法：/create-window <窗口名> <包名>
allowed-tools: Read, Write, Glob, Grep
---
## 步骤
1. 读取 FguiCreator3.8/assets/$ARGUMENTS[1]/$ARGUMENTS[0].xml
2. 提取节点结构，生成 Window 子类代码
3. 写入 assets/script/UI/ 目录
MCP
我这里是把MCP当成了一个私有框架的知识库
把框架的 .d.ts 类型声明文件向量化，构建本地可搜索的知识库。AI 遇到不确定的 API 时，自动调用 MCP 工具查签名。
MCP Server 配置在项目根目录的 .mcp.json 或用户级 ~/.claude/mcp.json 里，Claude Code 启动时自动读取并连接。
Hooks
三个事件节点：
| 事件节点 | 触发时机 | 适合做什么 |
|---|---|---|
PreToolUse |
AI 调用工具之前 | 拦截、提醒 |
PostToolUse |
AI 调用工具之后 | 检查、自动修复 |
Stop |
AI 完成一轮对话后 | 通知、总结 |
配置在 .claude/settings.json 的 hooks 字段，matcher 指定触发工具，command 是要执行的命令：
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "bash .claude/hooks/tsc-check.sh" }]
}],
"Stop": [{
"matcher": "*",
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"任务完成\" with title \"Claude Code\"'" }]
}]
}
}
我目前在用的三个 Hook：
1. 系统通知
Claude Code 需要用户授权时、任务完成时，发送 macOS 系统卡片通知并播放提示音。跑长任务时不用一直盯着终端，听到声音再回来确认。
{
"hooks": {
"Notification": [{
"hooks": [{
"type": "command",
"command": "bash ~/.claude/hooks/notification.sh"
}]
}]
}
}
2. 代码规范检查
每次 AI 写入或编辑文件后，自动跑 eclint 检查代码风格（缩进、换行、编码等），
{
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "bash .claude/hooks/eclint-check.sh" }]
}]
}
3. 自动触发 Review Agent
AI 写完代码后，自动调度 game-reviewer Agent 做架构合规检查——不用每次手动说「帮我 review 一下」。
{
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "bash .claude/hooks/trigger-review.sh" }]
}]
}
这个 Hook 和 Agents 配合使用：AI 写代码 → Hook 触发 → Review Agent 审查 → 发现问题 → AI 自动修复。
Hook 脚本如何和 AI 交互
Hook 脚本的 stdout 输出会作为反馈注入 AI 的上下文。把检查结果 echo 出来，AI 就能直接看到并响应——这是 Hooks 能形成闭环的关键机制。
和 Rules 的协作：Rules 是第一道防线（让 AI 尽量一次写对），Hooks 是兜底（写完自动检查，有问题自动修复）。
Agents
和 Skills 的区别：
| Skills | Agents | |
|---|---|---|
| 本质 | 步骤固化的 SOP | 有专业知识的子 AI |
| 执行方式 | 按预定步骤顺序执行 | 自主分析、判断、决策 |
| 适合场景 | 步骤清晰的重复任务 | 需要推理判断的复杂任务 |
| 典型例子 | 创建窗口、生成组件 | 代码 review、架构分析 |
| 上下文 | 和主对话共享上下文 | 独立上下文，不占主对话 |
游戏项目两个典型场景：
场景一：代码 review
不是检查「有没有 console.log」（Hooks 能做这个），而是判断「这个 System 缓存了组件引用，违反了 ECS 无状态原则」。这需要理解项目架构、掌握领域规范、具备推理能力——这是 Hooks 做不到的。
场景二：探索型任务
扫描整个项目输出所有窗口、ECS 组件、系统的汇总表。如果在主对话里做，几十个文件的内容会塞满上下文，后续对话质量下降。派给 Agent 在独立上下文里扫描，只返回最终结果，主对话保持干净。
Agent 定义文件放在 .claude/agents/ 目录，头部 YAML frontmatter 定义名称、描述、使用的模型，正文是系统提示——告诉这个 Agent 它的专业身份、检查标准、输出格式。
以 game-reviewer 为例，定义文件大致是这样：
---
name: game-reviewer
description: 游戏代码审查员，审查 ECS/UI 代码的架构合规性。写完 assets/script/ 下的 TypeScript 文件后自动触发。
model: claude-sonnet-4-5
---
你是 bit-framework 游戏项目的代码审查员，精通 Cocos Creator 3.8.8 + ECS 架构 + FairyGUI。
审查重点：
- ECS 规范：Component 是否只存储数据，System 是否存储了持久状态
- 事件规范：跨模块通信是否通过 GlobalEvent，销毁时是否清理了监听
- 类型规范：是否有 any 类型，访问修饰符是否完整
按 Critical / Important / Suggestion 分级输出问题，只报告置信度高的问题。
description 字段里写清楚触发条件，主 AI 就能在写完对应文件后自动调度这个 Agent 做 review——不需要你每次手动说「帮我 review 一下」。
调用方式：在 Agent 的 description 字段写明触发条件，主 AI 会在合适时机自动调度；你也可以在对话中直接说「用 game-reviewer 帮我 review 这段代码」。不过我这里是通过 Hooks 自动触发。这个描述就可以写一个匹配不到的。