记忆系统与 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.ts
export const get = <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
}

前端解析示例

// 成功时直接返回 data
const result = await api.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 配合——构建智能开发助手（待写）