title: 记忆系统与 Agent 定制完全指南二记忆文件编写规范——怎么写一条好的记忆date: 2026-07-10category: 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 字段规则规则说明示例使用 kebab-case小写字母 短横线coding-preferences不超过 50 字符太长不好读database-connection-info✅唯一性不能有重复mysql-info和mysql-database-info算重复有意义的缩写可以用缩写但要清晰db-info不如database-info好的 namecoding-style-preferencedatabase-connection-infoui-framework-decisionteam-commit-convention不好的 nameinfo太模糊my-note无意义CodingStylePreferences没用小写1.2 description 字段规则一句话概括记忆内容使用 Claude 可能用到的检索关键词不要写太抽象的描述好的 description前端编码风格偏好箭头函数、const、单引号MySQL 数据库连接信息地址、端口、数据库名团队 Git 提交规范约定式提交 格式要求不好的 description一些信息太泛无法检索偏好太窄找不到相关记忆项目相关的内容太模糊1.3 metadata.type 字段4 种类型各有用途类型适用场景示例user用户个人偏好、习惯编码风格、命名偏好project项目相关信息技术栈、数据库、部署方式reference外部资源链接API 文档、设计稿地址feedback对 Claude 的纠正“不要用双引号”二、记忆正文的编写规范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 - **图表**ECharts2.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.tsexportconstgetT(url:string)service.get(url).then(resres.code200?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-case3.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 自检清单写完一条记忆后对照以下清单检查检查项通过标准name 唯一性没有其他记忆用相同 namedescription 清晰度一眼能看懂这条记忆是关于什么的结构化使用列表和标题不是大段文字有示例关键规则配有代码示例有原因重要规则解释了为什么不过时信息是最新的不是半年前的不冗余没有和其他记忆重复的内容5.2 常见错误❌ 错误 1description 太泛 description: 一些项目信息 → 无法被检索到 ❌ 错误 2正文是流水账 我们项目用 Vue然后用 TypeScript然后 Vite... → Claude 难以提取关键信息 ❌ 错误 3信息过时 数据库地址192.168.31.196:13306 → 实际已改为 192.168.31.200:3306 ❌ 错误 4存储敏感信息 数据库密码MyPssw0rd123 → 绝对不要 ❌ 错误 5过度细分 创建了 50 条记忆每条只记录一行信息 → 应该合并为 5-10 条综合记忆六、实战编写一条完整的记忆场景记住团队的 API 响应格式记住我们 API 统一返回 { code, message, data }分页的话 data 里有 list 和 totalClaude 生成记忆文件--- 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}前端解析示例// 成功时直接返回 dataconstresultawaitapi.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 配合——构建智能开发助手待写