记忆系统与 Agent 定制完全指南（二）：记忆文件编写规范

title: 记忆系统与 Agent 定制完全指南（二）记忆文件编写规范——怎么写一条好的记忆
date: 2026-07-10
category: AI 开发工具
tags: [Claude Code, Memory, 记忆文件, 编写规范, Markdown]

记忆系统与 Agent 定制完全指南（二）：记忆文件编写规范

一条好的记忆 = 清晰的结构 + 准确的信息 + 可检索的描述。本篇教你怎么写出一条高质量的记忆文件，让 Claude 准确理解、高效检索。

前言

记忆系统的核心是文件。每条记忆就是一个 Markdown 文件，存放在~/.claude/projects/<project-id>/memory/目录下。

写得好，Claude 下次对话就能准确引用。写得差，Claude 要么不理解，要么用错地方。

本篇的核心目标：教你写出一条 Claude 真正"听得懂"的记忆。

一、记忆文件的标准结构

每个记忆文件由三部分组成：

--- name: <短横线命名的唯一标识> description: <一句话描述这条记忆的内容> metadata: type: user | project | reference | feedback --- <记忆正文>

1.1 name 字段

规则：

好的 name：

• coding-style-preference
• database-connection-info
• ui-framework-decision
• team-commit-convention

不好的 name：

• info（太模糊）
• my-note（无意义）
• CodingStylePreferences（没用小写）

1.2 description 字段

规则：

• 一句话概括记忆内容
• 使用 Claude 可能用到的检索关键词
• 不要写太抽象的描述

好的 description：

• 前端编码风格偏好：箭头函数、const、单引号
• MySQL 数据库连接信息：地址、端口、数据库名
• 团队 Git 提交规范：约定式提交 + 格式要求

不好的 description：

• 一些信息（太泛，无法检索）
• 偏好（太窄，找不到相关记忆）
• 项目相关的内容（太模糊）

1.3 metadata.type 字段

4 种类型，各有用途：

二、记忆正文的编写规范

frontmatter 下面是记忆的正文。正文才是 Claude 实际读取的内容。

2.1 结构化优于段落

❌ 差的写法： 我平时写代码喜欢用 const 而不是 let，也不用 var。 函数喜欢用箭头函数的形式。字符串用单引号，最后要加分号。 缩进是 2 空格。 ✅ 好的写法： ## 变量声明 - 使用 `const` 声明常量 - 不使用 `let`（除非需要重新赋值） - 绝对不使用 `var` ## 函数风格 - 优先使用箭头函数：`const fn = () => {}` - 不使用 function 声明：`function fn() {}` ## 字符串 - 使用单引号：`'hello'` - 模板字符串例外：`` `hello ${name}` `` ## 分号 - 语句末尾必须加分号 `;` ## 缩进 - 2 空格，不使用 Tab

为什么：结构化的内容 Claude 更容易解析和引用。

2.2 用列表代替长段落

❌ 差的写法： 我们的项目用 Vue 3 做前端，TypeScript 做类型系统， Vite 做构建工具，Element Plus 做 UI 库，Pinia 做状态管理， Vue Router 做路由，Axios 做 HTTP 请求，ECharts 做图表。 ✅ 好的写法： ## 前端技术栈 - **框架**：Vue 3 + Composition API - **语言**：TypeScript - **构建**：Vite - **UI 库**：Element Plus - **状态管理**：Pinia - **路由**：Vue Router - **HTTP**：Axios - **图表**：ECharts

2.3 包含上下文和原因

❌ 差的写法： 使用 POST 代替 GET 查询接口。 ✅ 好的写法： ## API 请求方法 - **查询接口使用 POST**（不是 GET） - 原因：查询条件可能很长，GET 的 URL 有长度限制 - 示例：`POST /api/users`，参数放在 body 中 - 例外：简单的分页查询（只有 pageNum/pageSize）可以用 GET - **修改/新增接口使用 POST/PUT/DELETE** - 新增：POST - 修改：PUT - 删除：DELETE

为什么：Claude 不仅需要知道"做什么"，还需要知道"为什么"，这样它在遇到边界情况时才能做出正确的判断。

2.4 提供代码示例

## API 响应格式 所有接口统一返回： ```json { "code": 200, "message": "success", "data": { ... } }

前端封装示例

// src/utils/http.tsexportconstget=<T>(url:string)=>service.get(url).then(res=>res.code===200?res.data:Promise.reject(res.message))

## 三、不同类型记忆的编写示例 ### 3.1 user 类型记忆 ```markdown --- name: coding-style-preference description: 前端编码风格偏好：const、箭头函数、单引号、分号 metadata: type: user --- ## 变量声明 - 始终使用 `const`，不用 `let` 或 `var` ## 函数 - 优先箭头函数：`const fn = () => {}` - 不使用 function 声明 ## 字符串 - 单引号 `'hello'` - 模板字符串例外 ## 分号 - 语句末尾加分号 ## 缩进 - 2 空格 ## 命名约定 - 变量/函数：camelCase - 组件：PascalCase - 常量：UPPER_SNAKE_CASE - 文件：kebab-case

3.2 project 类型记忆

--- name: project-tech-stack description: 项目技术栈：Vue 3 + TypeScript + Vite + Element Plus + Spring Boot metadata: type: project --- ## 前端 | 技术 | 版本 | 用途 | |------|------|------| | Vue | 3.4+ | 框架 | | TypeScript | 5.x | 类型系统 | | Vite | 5.x | 构建工具 | | Element Plus | 2.x | UI 组件库 | | Pinia | 2.x | 状态管理 | | Axios | 1.x | HTTP 客户端 | ## 后端 | 技术 | 版本 | 用途 | |------|------|------| | Spring Boot | 2.7.x | 框架 | | Dubbo | 2.7.8 | RPC 框架 | | MyBatis-Plus | 3.5.x | ORM | | MySQL | 8.0 | 数据库 | | Redis | 7.x | 缓存 |

3.3 feedback 类型记忆

--- name: feedback-api-path-format description: API 路径格式反馈：应以 /api 开头，版本号放路径中 metadata: type: feedback corrected: 2026-07-05 --- ## 问题 之前生成的 API 路径格式不正确： - 错误：`/users/list` - 正确：`/api/v1/users` ## 纠正 所有 API 路径必须以 `/api` 开头，版本号放在路径中： - `/api/v1/users` - `/api/v1/devices` - `/api/v1/reports` ## 为什么重要 团队后端规范规定所有接口以 `/api` 开头， 前端 Axios 的 baseURL 配置为 `/api`， 如果不一致会导致请求被拦截。

3.4 reference 类型记忆

--- name: api-documentation-url description: Apifox API 文档地址：https://xxx.apifox.cn metadata: type: reference --- ## API 文档 - **平台**：Apifox - **地址**：https://xxx.apifox.cn - **项目**：金坛管理系统 - **更新频率**：每次接口变更后 24 小时内 ## Swagger - **地址**：http://localhost:8080/swagger-ui.html - **注意**：仅本地开发环境可用

四、记忆文件的命名与组织

4.1 文件命名

~/.claude/projects/<project-id>/memory/ ├── MEMORY.md ← 索引（必须） ├── coding-style-preference.md ← 编码风格 ├── project-tech-stack.md ← 技术栈 ├── database-info.md ← 数据库信息 ├── deployment-guide.md ← 部署指南 ├── team-conventions.md ← 团队约定 └── feedback-api-format.md ← 反馈记录

命名规则：

• 使用 kebab-case
• 以类型或主题开头
• 不超过 50 字符

4.2 MEMORY.md 索引

# 记忆索引 ## 编码偏好 - [编码风格偏好](coding-style-preference.md) — const、箭头函数、单引号 - [TypeScript 偏好](typescript-preference.md) — 严格模式、noImplicitAny ## 项目信息 - [技术栈](project-tech-stack.md) — Vue 3 + Spring Boot - [数据库信息](database-info.md) — MySQL 8.0 连接信息 - [部署指南](deployment-guide.md) — Docker + Nginx ## 团队约定 - [Git 提交规范](team-conventions.md) — 约定式提交 ## 反馈记录 - [API 路径格式](feedback-api-format.md) — 必须以 /api 开头

索引规则：

• 按分类分组
• 每行一个记忆
• 格式：- [标题](文件名.md) — 简要说明
• 按字母或类别排序

五、记忆的质量检查

5.1 自检清单

写完一条记忆后，对照以下清单检查：

5.2 常见错误

❌ 错误 1：description 太泛 description: 一些项目信息 → 无法被检索到 ❌ 错误 2：正文是流水账 我们项目用 Vue，然后用 TypeScript，然后 Vite... → Claude 难以提取关键信息 ❌ 错误 3：信息过时 数据库地址：192.168.31.196:13306 → 实际已改为 192.168.31.200:3306 ❌ 错误 4：存储敏感信息 数据库密码：MyP@ssw0rd123 → 绝对不要！ ❌ 错误 5：过度细分 创建了 50 条记忆，每条只记录一行信息 → 应该合并为 5-10 条综合记忆

六、实战：编写一条完整的记忆

场景：记住团队的 API 响应格式

记住：我们 API 统一返回 { code, message, data }，分页的话 data 里有 list 和 total

Claude 生成记忆文件：

--- name: api-response-format description: API 统一响应格式：{ code, message, data }，分页包含 list 和 total metadata: type: project --- ## 标准响应格式 ```json { "code": 200, "message": "success", "data": { ... } }

分页响应格式

{"code":200,"message":"success","data":{"list":[...],"total":100}}

错误响应格式

{"code":400,"message":"参数错误：用户名不能为空","data":null}

前端解析示例

// 成功时直接返回 dataconstresult=awaitapi.getUserList()// result 已经是 data 部分// 分页数据const{list,total}=result

## 七、这一章的核心心得 1. **结构胜于段落**——列表和标题让 Claude 更容易解析 2. **description 决定检索命中率**——写得越好，Claude 越容易找到 3. **示例胜过千言万语**——代码示例让 Claude 知道"怎么做" 4. **解释"为什么"**——Claude 理解了原因，遇到边界情况不会出错 5. **定期清理**——过时的记忆比没有记忆更糟糕 6. **不要存敏感信息**——密码、Token 永远不要写入记忆文件 ## 八、下一步 学会了编写记忆文件，接下来我们看 Claude **如何在对话中检索和使用记忆**。同样的记忆，写法不同，效果可能差很多——因为 Claude 的检索是基于 description 的。 下一篇我们学习记忆的检索与使用。 --- *系列目录：* 1. ~~初识记忆系统——什么是记忆？为什么需要记忆？~~ 2. ~~记忆文件编写规范——怎么写一条好的记忆~~ ← 本篇 3. 记忆的检索与使用——Claude 如何在对话中调用记忆（待写） 4. 自定义 Agent 开发（一）——Agent 的定义与结构（待写） 5. 自定义 Agent 开发（二）——Agent 的工具与权限（待写） 6. Agent 编排与调度（待写） 7. Agent 与工具的深度集成（待写） 8. 记忆系统与 Agent 配合——构建智能开发助手（待写）