Claude Code 用户反馈记忆（Feedback Memory）完全指南：如何记录成功与失败，让 Agent 持续对齐你的工作方式-平芜编程栈

文档
提示工程
人工智能

【免费下载链接】claude-code-system-prompts

All parts of Claude Code's system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.

项目地址：https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts

点击查看免费下载

导读

在 Claude Code 的持久化记忆体系中，「用户反馈记忆（feedback memory）」是一类专门保存用户对工作方式指引（guidance）的记忆：它记录“该做什么”与“不该做什么”，让 Agent 在后续会话中保持连贯、贴合项目的工作方式。本指南以 system-prompt-memory-description-of-user-feedback.md 为核心，结合仓库中记忆体系的配套文档（memory-instructions、feedback-memory-save-guidance、feedback-memory-body-structure 等），系统讲解反馈记忆的定义、记录时机、正文结构与团队记忆冲突处理，读完即可掌握如何让 Claude Code 从你的纠正与认可中持续学习。

一、什么是用户反馈记忆

根据 system-prompt-memory-description-of-user-feedback.md 中的定义：

Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project.

用户反馈记忆是“用户就如何开展工作给出的指引”，它同时包含两类信息：

要避免的事（what to avoid）：用户纠正过的错误做法；
要保持的事（what to keep doing）：用户验证过、希望继续沿用的做法。

它是记忆类型中非常重要的一类，应当既读又写——因为只有持续读写反馈记忆，Agent 才能在后续会话中保持与用户期望一致的连贯性（coherent）与响应性（responsive），始终贴合用户在项目中的工作方式。

反馈记忆在记忆类型体系中的位置

在 Claude Code 的文件化记忆（file-based memory）体系中，每条记忆是一个独立的文件、保存一条事实，并在 frontmatter 中声明类型：

--- name: <short-kebab-case-slug> description: <one-line summary, used to decide relevance during recall> metadata: type: user | feedback | project | reference --- <the fact; for feedback/project, follow with **Why:** and **How to apply:** lines. Link related memories with [[their-name]].>

上述格式出自 system-prompt-memory-instructions.md。可以看到metadata.type一共有四类：user（用户记忆）、feedback（反馈记忆，即本文主题）、project（项目记忆）、reference（参考记忆）。其中只有feedback与project两类要求在正文中追加Why:与How to apply:两行，并可用[[their-name]]语法关联其他记忆。

与反馈记忆相近但不同的另一类是项目记忆。根据 system-prompt-team-project-memory-description.md：

Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history.

项目记忆记录的是“正在推进的工作、目标、计划、缺陷或事故”，它们从代码或 git 历史中无法直接推导出来。反馈记忆则聚焦于“工作方式”，二者关注点不同：项目记忆回答“项目在做什么、为什么这么做”，反馈记忆回答“用户希望我怎么做”。

反馈记忆与一般记忆的定位差异

system-prompt-memory-persistence-scope.md 进一步界定了记忆的整体定位：

Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.

记忆是多种持久化机制中的一种，其核心特征是可被未来会话召回；仅对当前会话有用的信息不应写入记忆。反馈记忆同样遵循这一原则——它保存的是在未来的项目中依然适用的工作方式指引，而不是某一次会话的临时上下文。

二、为什么要同时记录失败与成功

反馈记忆定义中特别强调了一个容易踩坑的陷阱：

Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.

如果只记录纠正（failure/corrections），Agent 确实能避免过去的错误，但同时会带来两个负面后果：

逐渐偏离用户已验证的做法（drift away from approaches the user has already validated）——用户明确认可过的方案、风格、流程没有被固化，Agent 反而会在后续会话中偏离它们；
变得过度谨慎（grow overly cautious）——只知“不做错事”，而不知“该坚持什么”，导致行为趋于保守、畏手畏脚。

因此，正确的做法是双向记录：失败的纠正要记，成功的确认同样要记。这样反馈记忆才能完整刻画“用户希望的工作方式”，而不是仅仅成为一张“禁忌清单”。

什么时候该记录：纠正与确认都要捕捉

system-prompt-feedback-memory-save-guidance.md 给出了明确的记录时机：

Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Includewhyso you can judge edge cases later.

具体触发场景包括：

触发类型	典型用户话术	记录要点
纠正（Corrections）	“no not that”“don't”“stop doing X”	保存该做法应避免的原因与替代做法
确认（Confirmations）	“yes exactly”“perfect, keep doing that”，或毫无异议地接受一个不寻常的选择	保存该非显然做法值得坚持的原因

文档特别提醒：纠正容易察觉，确认则更安静（quieter）——要主动留意。用户接受一个不寻常的选择、或者简短肯定某个做法时，往往不会长篇大论，但恰恰是这些“安静的确认”最容易流失，需要 Agent 有意识地捕捉。

无论哪种情况，保存的应是对未来会话仍然适用的内容，尤其是那些令人意外、或从代码中无法显而易见的指引；并且必须包含why，以便日后判断边界情况。

一个反直觉的识别方法：确认比纠正更值得留意

从保存时机文档可以看出，绝大多数 Agent 能自然捕捉到显式纠正（“别这么做”），但确认信号常常被忽略。以下行为都属于值得落盘的“确认”：

用户说“yes exactly”“perfect, keep doing that”；
用户对一个不寻常的选择（unusual choice）没有提出异议；
用户对某次验证方式、提交风格、PR 流程、工具选择表示认可。

这些场景的共同特征是：用户没有直接“下命令”，而是通过默许/肯定来背书某种做法。它们正是what to keep doing的记忆来源。

三、反馈记忆的正文结构：Rule + Why + How to apply

反馈记忆并非简单的一句话笔记。system-prompt-feedback-memory-body-structure.md 对正文结构有明确要求：

Lead with the rule itself, then aWhy:line (the reason the user gave — often a past incident or strong preference) and aHow to apply:line (when/where this guidance kicks in). Knowingwhylets you judge edge cases instead of blindly following the rule.

标准的正文结构为三段式：

规则本体（the rule itself）：开门见山写出该条指引的核心内容，例如“提交信息必须遵循 Conventional Commits 格式”“重构时先跑完整测试套件再改动”；
Why: 行：记录用户给出的原因——通常是某次过去的事故（a past incident）或强烈的偏好（strong preference）；
How to apply: 行：说明这条指引在何时、何地生效，即它的适用范围与触发条件。

--- name: conventional-commits-for-releases description: Use Conventional Commits format for all commit messages in this project metadata: type: feedback --- Always use Conventional Commits format for commit messages. **Why:** A past release was broken because a breaking change was hidden in a generic "fix" message; the user wants release notes generated from commit history. **How to apply:** For every commit in this repository, choose a type prefix (feat/fix/docs/refactor/...) and append a BREAKING CHANGE footer when the change is not backward compatible. Link related memories with [[commit-policy]].

文档明确指出为什么需要Why:行：了解原因才能判断边界情况，而不是盲目照搬规则（Knowingwhylets you judge edge cases instead of blindly following the rule）。例如，若用户当初要求“不要用某个库”是因为一次特定版本的安全问题，当该库修复后，知道 Why 的 Agent 就能在边界情况下做出正确判断，而不是永远机械规避。

四、保存前必查：与团队反馈记忆的冲突处理

用户反馈记忆定义的最后一部分，是保存前的一道强制检查：

Before saving a private feedback memory, check that it doesn't contradict a team feedback memory — if it does, either don't save it or note the override explicitly.

保存私有（private）反馈记忆之前，必须先检查它是否与**团队反馈记忆（team feedback memory）**相矛盾。若存在矛盾，处理方式只有两种：

不保存该条私有记忆；
显式标注覆盖（note the override explicitly），即明确记录这条私有指引是团队指引的一个例外。

这一机制防止了两种记忆体系之间的互相抵消：团队反馈记忆代表了团队层面的统一工作方式，私有反馈记忆则可能源于某个用户的个人偏好。若二者冲突，直接写入私有记忆会让后续会话在两个矛盾指引之间摇摆；而显式标注覆盖，则让 Agent 在召回时能理解“此条为团队规则的特例”。

从仓库的记忆体系文档可以推断（见 system-prompt-team-memory-index-pointer-instructions.md），团队记忆同样采用索引文件机制，与私有记忆体系并存：

**Step 2** — add a pointer to that file in ${TEAM_MEMORY_INDEX_LOCATION}. Each entry should be one line, under ~150 characters: `- Title — one-line hook`. The index has no frontmatter. Never write memory content directly into the index.

即：记忆文件与索引文件是分离的——记忆内容写在独立文件中，索引文件只保存一行条目（- Title — one-line hook，约 150 字符以内，无 frontmatter），索引只用于定位，绝不在索引中直接写记忆内容。这保证了即使团队与私有两套记忆并存，召回与检索也能保持有序。

五、落地实践：如何让反馈记忆真正生效

5.1 反馈记忆写入后的索引登记

根据 system-prompt-memory-index-pointer-instructions.md，每写一条记忆文件，都需要在索引中登记一行指针：

**Step 2** — add a pointer to that file in ${INDEX_LOCATION_DISPLAY}. `${INDEX_FILE}` is an index, not a memory — each entry should be one line, under ~150 characters: `- Title — one-line hook`. It has no frontmatter. Never write memory content directly into `${INDEX_FILE}`.

要点归纳：

索引文件本身不是记忆，不要给它加 frontmatter；
每个条目一行，控制在约 150 字符内，格式为- 标题 — 一句话提示（hook）；
永远不要直接把记忆正文写进索引。

5.2 可复用流程的纠正：同步更新项目技能

system-prompt-project-skill-upkeep-for-feedback-memory.md 提供了一条进阶实践：当反馈记忆源自可复用步骤的纠正（如如何验证、如何提交、如何开 PR、如何使用某个项目技能）时，应把同样的纠正折叠进驱动该步骤的项目技能（.claude/skills/<name>/SKILL.md）——做一次精简、通用的修改，让下一个会话无需提示即可做对。

该文档同时给出了三条边界规则：

只编辑已有技能文件，绝不新建——新建的项目技能会静默遮蔽同名内置技能（a new project skill silently shadows a same-named built-in skill）；
唯一例外是 verify 技能——因为项目如何验证是项目特有的，可将验证类纠正写入最贴近所覆盖代码的.claude/skills/verify/SKILL.md：仓库级纠正放仓库根目录，仅适用于某子树的纠正放该子树目录（如ios/.claude/skills/verify/SKILL.md）；若该文件不存在，可以创建；
每条纠正只存在于一个技能文件中——放在作用域最近的那一个，绝不在更广作用域重复。

5.3 记忆保存的排除项意识

system-prompt-memory-save-exclusions.md 以## What NOT to save in memory开头，提示存在一类“即使用户要求也不应写入记忆”的信息类别。在实际使用反馈记忆时，应同时保持对排除项的敏感，避免把本不该持久化的内容混入记忆体系。

六、小结：反馈记忆的黄金法则

结合定义文档与仓库配套文档，可以将用户反馈记忆的实践提炼为四条黄金法则：

双向记录：失败纠正要记，成功确认更要记。只记纠正会让 Agent 偏离已验证的做法并变得过度谨慎（见 system-prompt-memory-description-of-user-feedback.md）；
识别安静的确认：“yes exactly”“perfect, keep doing that”、对不寻常选择的无异议接受，都是值得落盘的确认信号（见 system-prompt-feedback-memory-save-guidance.md）；
三段式正文：规则本体 +Why:（判断边界情况的依据）+How to apply:（生效时机与范围）（见 system-prompt-feedback-memory-body-structure.md）；
保存前查冲突：私有反馈记忆若与团队反馈记忆矛盾，要么不保存，要么显式标注覆盖（见 system-prompt-memory-description-of-user-feedback.md）。