第 05 章

记忆 AGENTS.md

说一次，记住一辈子——让 AI 永远懂你的项目

记忆文件是项目写给 AI 的"入职手册"

命令和工具都学会了。这一章进入第一个让 AI 真正理解你项目的关键机制 —— 记住规则，一次写入永久生效。

重复的交代

每次开新会话，都要把项目规则重新说一遍

技术栈交代一遍又一遍

"我们用 React 18 + TypeScript""测试用 vitest""包管理用 pnpm"——每次新会话都要从头说。

编码规范讲完又忘

"注释用中文""提交信息用 conventional commits""不要用 any"——AI 在当前会话记得，关掉就忘。

项目背景反复解释

"这是内部管理系统""接口都在 src/api 下""鉴权走 cookie"——这些背景信息消耗大量对话篇幅。

记忆系统解决的就是这个问题：把这些稳定的、跨会话的信息写进一个文件，AI 每次启动都会自动读它。你说一次，它记一辈子。

AGENTS.md

项目根目录下的一个 Markdown 文件，AI 的入职手册

AGENTS.md 是 Qoder CLI 默认读取的项目记忆文件。放在项目根目录，里面用 Markdown 写清楚这个项目的规则、约定、架构——AI 每次在这个项目启动，都会先读它。

说白了，它就像你给新同事写的"项目入职手册"：技术栈是什么、代码怎么组织、提交流程怎样、有哪些坑要避。AI 读了它，就不再是"新人"了。

my-project/
├── AGENTS.md      ← 项目记忆文件
├── src/
├── package.json
└── ...

和对话上下文的区别：对话内容只在一个会话里有效；AGENTS.md 里的内容对所有未来会话永久有效，直到你修改它。

/init 生成

让 AI 自己读项目，帮你写出第一版记忆

不用手写——Qoder CLI 能自动分析项目并生成 AGENTS.md。在一个还没有记忆文件的项目里运行：

/init

（CLI 扫描 package.json、目录结构、配置文件，
 自动生成 AGENTS.md 的初稿）

生成的内容通常包括：项目简介、技术栈、常用命令、目录结构、关键约定。你可以基于它再手动修改完善。

不要直接照搬 AI 生成的版本：它只看到代码，看不到你的隐性约定（比如"不要用 moment，用 dayjs"）。生成后一定要人工 review，补充团队才知道的规则。

/memory 管理

记忆不止一份，三级各有分工

用 /memory 命令打开记忆管理界面，可以看到三级记忆：

级别	位置	作用范围	适合放什么
用户级	`~/.qoder/`	你的所有项目	个人偏好（注释风格、编辑器习惯）
项目级	`项目/AGENTS.md`	整个团队、本项目	技术栈、规范、架构（随 Git 提交共享）
本地级	`项目/.qoder/settings.local.json`	只有你、本项目	本地路径、个人实验配置（不提交）

最常见的实践：项目级记忆随 Git 提交，全团队共享同一份"入职手册"；本地级记忆放你个人的实验配置，加进 .gitignore 不污染团队。

# 快捷写入

对话中用 `#` 开头，一句话追加进记忆

第 03 章提过的记忆模式，这里展开讲。当你发现某条规则应该长期生效，不用退出对话去编辑文件，直接在输入框用 # 开头：

# 本项目用 pnpm，禁止使用 npm 或 yarn
# 提交前必须运行 pnpm lint 和 pnpm test
# src/legacy 目录的代码不要动，正在废弃

每条都会被追加到项目的 AGENTS.md。下次启动 AI 自动遵守。

什么时候用 `#`

对话中突然意识到"这条该永久记住"
快速记录一条规则，不想切到编辑器
补充 AI 反复犯错的地方

什么时候用 `/memory`

系统整理、重新组织记忆结构
查看和编辑各级记忆
初始化一个全新项目

该写什么

好的记忆文件，写的是"稳定的规则"，不是"临时的任务"

技术栈与版本

技术栈：React 18 + TypeScript 5
构建：Vite 5
测试：Vitest

常用命令

安装依赖：pnpm install
启动开发：pnpm dev
跑测试：pnpm test
构建：pnpm build

编码规范

注释统一用中文
不用 any，必要时用 unknown
函数名用驼峰，组件名用帕斯卡

项目结构与边界

src/api 接口层
src/components 通用组件
src/legacy 待废弃，勿改
状态管理统一用 zustand

工作流约定

提交前跑 lint 和 test
分支命名：feat/fix/ chore
PR 必须有描述和测试说明

已知陷阱

注意：登录回调在 Safari 有 bug
config.ts 里的 KEY 不要提交
DB 迁移必须先备份

不该写什么

记忆不是垃圾桶，写太多反而让 AI 抓不住重点

以下内容不要写进 AGENTS.md：

临时任务和待办

"今天要修登录 bug""下周重构 user 模块"——这些是会话级的事，写进对话或 TODO，不是永久记忆。完成后就没用了，留在记忆里是噪音。

敏感信息

API Key、数据库密码、Token——绝对不要写进会提交到 Git 的项目级记忆。要用密钥就用环境变量。

容易过期的细节

"目前依赖版本是 1.2.3"——这种会随时间失效，AI 读 package.json 就知道，不必记。

冗长的大段文字

记忆要精炼成条目。大段散文式描述会让 AI 难以提取关键规则。

判断标准：问自己"这条信息半年后还有效吗？"——是，写进记忆；否，放进对话或 TODO。

自动与手动

两种记忆来源，配合使用

自动记忆

Qoder CLI 在工作中可能自动积累一些项目知识（如发现常用命令、识别出的模式），存进自动记忆入口。

优点：无需你动手；缺点：可能不准，需要定期 review。

用 /memory 查看自动记忆，删除不准的条目。

手动记忆

你主动写进 AGENTS.md 的规则——通过 /init、/memory 或 # 模式。

优点：精准、可控；缺点：需要你花时间维护。

这是记忆系统的主体，团队规范主要靠它。

推荐策略：以手动记忆为主（团队规范、技术栈、约定），自动记忆为辅（让 AI 补充你没想到的）。定期用 /memory 清理过时内容。

排错指南

记忆相关的高频问题

AI 不遵守记忆里的规则

原因：规则写得太模糊，或和其他规则冲突；也可能文件位置不对没被读到。修复：用 /memory 确认条目存在；把模糊规则改具体（"注释用中文"→"所有函数注释用中文，JSDoc 格式"）。

新会话没读到记忆

原因：记忆文件不在项目根目录，或文件名拼错（必须是 AGENTS.md）。修复：确认路径和文件名；启动目录就是项目根。

记忆文件越来越大

原因：累积了太多过时条目。修复：定期 review，删除一次性任务、过期的版本号；保持精炼条目化。

团队同步问题

原因：本地级记忆被误提交，或项目级记忆没提交。修复：项目级 AGENTS.md 进 Git；本地级配置加进 .gitignore。

动手练习

给你的项目建立一份有用的记忆

练习 1：自动生成初稿

在一个真实项目里运行 /init
查看生成的 AGENTS.md，评估哪些准确、哪些要改

练习 2：补充团队规则

用 # 模式追加 3 条你的项目特有的规则
比如包管理器、测试命令、禁区目录

练习 3：验证生效

清空会话（/clear）后重启
问 AI"我们项目用什么包管理器"
它应该不查文件就能答对——说明记忆生效了

本章回顾

带走的三个核心认知

AGENTS.md 是入职手册

项目根目录的记忆文件，AI 每次启动自动读取，跨会话永久生效。

三级记忆分工

用户级（个人偏好）、项目级（团队共享）、本地级（个人实验）。

只写稳定规则

技术栈、规范、架构、陷阱——临时任务和敏感信息不进记忆。

核心结论：记忆系统是 AI 从"临时助手"升级为"项目老手"的关键。一份好的 AGENTS.md，能让团队每个人（包括 AI）都对项目有同样的认知。

基础篇到此结束。接下来进入扩展篇——从第 06 章技能开始，你将学会把 AI 打造成一支专业团队。