Reflect System 是一个用于 Claude Code 的自我学习系统，它能让 AI 助理从您的纠正中永久学习，不再重复相同的错误。通过模式识别，它会将您的反馈（纠正、赞同、建议）自动转化为可复用的技能知识，并支持版本控制和安全回滚。

1. 系统要求

在安装前，请确保您的环境满足以下条件：

  • Claude Code CLI：已安装并配置好。
  • Python：版本 3.8 或更高。
  • Git：用于版本控制和备份。
  • 操作系统：主要在 macOS 和 Linux 上测试，Windows 环境未经官方测试。
  • 依赖：pyyaml 库（用于解析技能文件）。

2. 安装步骤

2.1 克隆仓库

首先，将仓库克隆到您的本地机器：

1
2
git clone https://github.com/haddock-development/claude-reflect-system.git
cd claude-reflect-system

2.2 复制技能到 Claude Code 目录

将核心的 reflect 技能和示例技能 python-project-creator 复制到 Claude Code 的技能目录中：

1
2
3
4
5
6
# 创建技能目录（如果不存在）
mkdir -p ~/.claude/skills

# 复制技能
cp -r reflect ~/.claude/skills/
cp -r python-project-creator ~/.claude/skills/

2.3 安装 Python 依赖

Reflect 系统需要 pyyaml 库来处理技能文件：

1
pip install pyyaml

或者，如果您使用 uv 或 pip3：

1
2
3
uv pip install pyyaml
# 或
pip3 install pyyaml

2.4 验证安装

在 Claude Code 中，输入以下命令检查系统状态：

1
/reflect-status

如果看到配置信息，则说明安装成功。

3. 核心概念与使用流程

3.1 基本工作流

  1. 与 Claude 协作：像往常一样使用 Claude Code，让它生成代码或执行任务。
  2. 发现并纠正错误：当 Claude 使用了错误的方式（例如用了 pip 而您希望用 uv）时，直接给出纠正指令。
  3. 触发学习（核心步骤）：在会话中运行 /reflect 命令。
  4. 审核并应用更改：系统会显示检测到的模式和将要修改的技能文件（diff）。输入 A 批准更改，系统会创建带时间戳的备份并更新技能文件。
  5. 永久生效：在未来的会话中，Claude 会优先使用您纠正过的方式。

3.2 三种学习信号与置信度

系统会根据您的反馈类型，将其归类为不同的置信度等级，并更新到技能文件的相应部分：

信号类型 置信度 触发模式示例 技能文件更新位置
纠正 (Correction) HIGH (高) “不要用 X，用 Y”、”永远不要做 X”、”总是检查 Y” ## Critical Corrections (关键纠正)
赞同 (Approval) MEDIUM (中) “是的，完美！”、”这样很好”、”完全正确” ## Best Practices (最佳实践)
观察/建议 (Observation) LOW (低) “你考虑过…吗？”、”关于…” ## Considerations (考量事项)

3.3 核心命令

命令 功能 说明
/reflect 手动触发学习 分析当前会话中的交互，检测学习信号，并提示您应用更改。
/reflect-on 开启自动学习 启用会话结束时的自动反射。Claude 会在会话结束时自动运行学习流程。
/reflect-off 关闭自动学习 禁用自动反射，恢复手动模式。
/reflect-status 查看当前状态 显示反射系统的配置，包括当前模式（手动/自动）、技能列表等。

4. 安全与版本控制

Reflect System 设计了多重安全机制，确保学习过程可控、可逆：

  • 自动备份：每次应用更改前，系统会在 ~/.claude/skills/{技能名}/.backups/ 目录下创建带时间戳的备份文件。
  • Git 集成：每次学习都会被记录为一个 Git 提交，您可以通过 git log 查看完整的历史变更。
  • 审核流程（手动模式）：在应用更改前，系统会显示详细的差异对比（diff），由您确认后才会写入。
  • 自动回滚：如果在更新过程中发生错误（如 YAML 格式错误），系统会自动回滚更改，保持技能文件完好。

5. 示例：Python 项目创建器的学习过程

仓库中包含了 python-project-creator 作为示例技能，展示了学习过程：

  1. 初始状态：该技能默认使用 pip 和 unittest。
  2. 您的纠正：当 Claude 使用 pip 时，您指出 “No, always use uv instead of pip!”。
  3. 运行 /reflect：系统检测到高置信度纠正，生成更新。
  4. 审核并应用：您批准更改后，技能文件被更新，明确指示使用 uv 和 pytest。
  5. 未来行为：在后续会话中，Claude 将始终使用 uv 和 pytest 来创建 Python 项目。

6. 常见问题排查

问题 可能原因 解决方案
/reflect 命令未找到 技能未正确复制到 ~/.claude/skills/ 目录 确认路径是否正确，并检查 Claude Code 是否重新加载了技能。
pyyaml 导入错误 Python 环境中未安装 pyyaml 执行 pip install pyyaml 或 uv pip install pyyaml。
/reflect 无法检测到纠正 反馈信息不够明确，或模式未匹配 使用更明确的纠正句式，如 “不要用 X，请用 Y”。也可在 extract_signals.py 中自定义模式。
学习后技能未生效 技能文件更新但 Claude Code 未重新加载 尝试重启 Claude Code 会话，或检查技能文件是否已正确修改。
Git 提交失败 技能目录不是 Git 仓库或 Git 未安装 确保 ~/.claude/skills/ 是一个 Git 仓库（或执行 git init），并确保 Git 已安装。

7. 最佳实践与建议

  • 从手动模式开始：初学者建议先使用 /reflect 手动触发学习，以便完全理解系统的运作方式和变更内容。
  • 提供明确、具体的纠正：反馈越具体（如 “使用 uv pip install 而不是 pip install“），系统检测的准确率越高。
  • 定期审查 Git 历史：通过 git log 查看学习记录，有助于理解系统是如何演变的，并方便进行团队知识共享。
  • 团队协作：可以将 ~/.claude/skills/ 目录作为 Git 仓库共享，让团队成员同步学习成果，形成团队级别的知识积累。

8. 总结

Claude Reflect System 通过将您的反馈转化为永久知识，解决了 AI 助手“遗忘”的痛点。

核心使用路径：

  1. 安装：克隆仓库，将 reflect 和示例技能复制到 ~/.claude/skills/，并安装 pyyaml。
  2. 日常使用：正常使用 Claude Code，当出现错误纠正后，运行 /reflect。
  3. 审核与应用：查看系统检测到的更改，批准后即可永久生效。
  4. 进阶：熟悉后可开启 /reflect-on 自动学习模式，并自定义模式检测规则。

建议您先跟随项目中的 Python Project Creator 示例进行一次完整的“纠正-学习”循环，以直观理解其工作方式。

项目地址：https://github.com/haddock-development/claude-reflect-system