claude-reflect

一个针对 Claude Code 的自学习系统，能够捕捉修正并发现工作流模式——将其转化为永久记忆和可重用技能。

它的作用

1. 从修正中学习

当你纠正 Claude（“不，用 gpt-5.1 而不是 gpt-5”）时，它会永远记住这一点。

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  你纠正       │ ──► │  挂钩捕获       │ ──► │  /reflect 添加   │
│  Claude Code    │     │  到队列         │     │  到 CLAUDE.md    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
      (自动)            (自动)            (手动审核)

2. 发现工作流模式（v2 中的新功能）

分析你的会话历史，找出可以转化为可重用命令的重复性任务。

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  你的过去      │ ──► │ /reflect-skills │ ──► │   生成          │
│  会话          │     │ 寻找模式        │     │   /commands      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
    (68 次会话)         (AI 驱动)            (由你批准)

示例：你曾 12 次询问“检查我的生产力”→ 建议创建 /daily-review。

核心特性

特性	作用
永久记忆	修正会同步到 CLAUDE.md — Claude 在不同会话间都能记住
技能发现	从你的历史中找到重复模式 → 生成命令
多语言支持	AI 能理解任何语言的修正
技能提升	在 /deploy 过程中的修正会直接提升部署技能

安装

# 添加市场
claude plugin marketplace add bayramannakov/claude-reflect

# 安装插件
claude plugin install claude-reflect@claude-reflect-marketplace

# 重要提示：重启 Claude Code 以激活插件

安装完成后，请 重启 Claude Code（退出并重新打开）。随后挂钩将自动配置，命令即可使用。

首次运行？ 当你第一次运行 /reflect 时，系统会提示扫描过去的会话以获取学习内容。

先决条件

• 已安装 Claude Code CLI
• Python 3.6+（大多数系统已自带）

平台支持

• macOS：完全支持
• Linux：完全支持
• Windows：完全支持（原生 Python，无需 WSL）

命令

命令	描述
/reflect	处理待处理的学习内容，并进行人工审核
/reflect --scan-history	扫描所有过去的会话，查找遗漏的学习内容
/reflect --dry-run	预览更改而不实际应用
/reflect --targets	显示检测到的配置文件（CLAUDE.md、AGENTS.md）
/reflect --review	显示带有置信度分数和衰减状态的待处理列表
/reflect --dedupe	查找并合并 CLAUDE.md 中相似条目
/reflect --include-tool-errors	将工具执行错误也纳入扫描范围
/reflect-skills	从重复模式中发现潜在技能
/reflect-skills --days N	分析最近 N 天的内容（默认为 14 天）
/reflect-skills --project <path>	分析特定项目
/reflect-skills --all-projects	扫描所有项目以寻找跨项目模式
/reflect-skills --dry-run	预览模式而不生成技能文件
/skip-reflect	忽略所有待处理的学习内容
/view-queue	查看待处理的学习内容，但不进行处理

工作原理

两阶段流程

阶段 1：捕获（自动）

挂钩会自动运行，检测并排队修正：

挂钩	触发条件	目的
session_start_reminder.py	会话开始	显示待处理学习提醒
capture_learning.py	每次提示	检测修正模式并将其排队
check_learnings.py	压缩前	备份队列并通知用户
post_commit_reminder.py	Git 提交后	提醒在完成工作后运行 /reflect

阶段 2：处理（手动）

运行 /reflect 来审查并应用待处理的学习内容到 CLAUDE.md 中。

检测方法

Claude-reflect 使用 混合检测方法：

1. 正则表达式模式（实时捕获）

在会话过程中快速匹配模式，检测以下内容：

• 修正：“不，用 X” / “不要用 Y” / “实际上……” / “那不对”
• 正面反馈：“完美！” / “完全正确” / “很棒的方法”
• 显式标记：“记住：” — 置信度最高

2. 语义 AI 验证（在 /reflect 运行时）

当你运行 /reflect 时，AI 驱动的语义过滤器会：

• 多语言支持 — 能理解任何语言的修正
• 更高的准确率 — 过滤掉正则表达式误报
• 更干净的学习内容 — 提取简洁、可操作的语句

例如：西班牙语修正“no, usa Python”即使不符合英语模式，也能被正确检测到。

每个捕获的学习内容都有一个 置信度分数（0.60–0.95）。最终分数取正则表达式和语义置信度中的较高值。

人工审核

当你运行 /reflect 时，Claude 会显示一个汇总表格，提供以下选项：

• 应用 - 接受该学习内容并添加到 CLAUDE.md
• 修改后再应用 - 先修改学习内容文本
• 跳过 - 不应用此学习内容

多目标同步

经批准的学习内容会被同步到：

• ~/.claude/CLAUDE.md（全局 — 应用于所有项目）
• ./CLAUDE.md（项目专用）
• ./**/CLAUDE.md（子目录 — 自动发现）
• ./.claude/commands/*.md（技能文件 — 当修正与技能相关时）
• AGENTS.md（如果存在 — 与 Codex、Cursor、Aider、Jules、Zed、Factory 等兼容）

运行 /reflect --targets 可查看哪些文件会被更新。

技能发现

运行 /reflect-skills 来发现你对话中可能成为可复用技能的重复模式：

/reflect-skills                 # 分析当前项目（最近14天）
/reflect-skills --days 30       # 分析最近30天
/reflect-skills --all-projects  # 分析所有项目（较慢）
/reflect-skills --dry-run       # 预览模式而不生成文件

功能：

• AI驱动检测 — 使用推理而非正则表达式来寻找模式
• 语义相似性 — 能够识别不同表述中的相同意图
• 项目感知 — 按项目对模式进行分组，并建议正确的存放位置
• 智能分配 — 询问每个技能应该放在哪个项目或全局目录下
• 生成技能文件 — 在 .claude/commands/ 中创建技能草稿

工作原理：

该工具通过语义分析你的会话历史来发现模式。它能够识别出表达相同意图的不同说法：

会话1: “查看我今天的生产力”
会话2: “今天下午我的专注度如何？”
会话3: “检查我的ActivityWatch数据”
会话4: “评估我的工作时长”

Claude会这样推理：“这4个请求具有相同的意图——查看生产力数据。其工作流程是：获取时间追踪数据 → 对活动进行分类 → 计算专注度得分。这非常适合作为 /daily-review 技能。”

示例输出：

════════════════════════════════════════════════════════════
发现的技能候选
════════════════════════════════════════════════════════════

从68次会话中发现了2个潜在技能：

1. /daily-review（高）— 来自 my-productivity-tools
   → 使用时间追踪数据查看生产力
   证据：15次类似请求
   学到的修正：”使用本地时区”，“聊天应用也算工作”

2. /deploy-app（高）— 来自 my-webapp
   → 带预检步骤部署应用
   证据：10次类似请求
   学到的修正：”一定要先跑测试”

════════════════════════════════════════════════════════════

我应该生成哪些技能？
> [1] /daily-review，[2] /deploy-app

每个技能应该创建在哪里？
┌──────────────────────┬─────────────────────────┐
│ /daily-review        │ my-productivity-tools   │
│ /deploy-app          │ my-webapp               │
└──────────────────────┴─────────────────────────┘

已创建的技能：
  ~/projects/my-productivity-tools/.claude/commands/daily-review.md
  ~/projects/my-webapp/.claude/commands/deploy-app.md

生成的技能文件示例：

---
description: 带预检步骤部署应用
allowed-tools: Bash, Read, Write
---

## 上下文
部署脚本位于 ./scripts/deploy/

## 你的任务
将应用部署到指定环境。

### 步骤
1. 运行测试套件
2. 构建生产资源
3. 部署到目标环境
4. 验证部署状态

### 守护机制
- 始终在部署前运行测试
- 周五绝不部署到生产环境
- 检查是否有未完成的迁移

---
*由 /reflect-skills 根据10次会话模式生成*

技能改进路由

当你在使用某个技能时纠正Claude（例如 /deploy），这些纠正信息可以被反馈回技能文件本身：

用户：/deploy
Claude：[未经测试就部署]
用户：“不对，部署前一定要先跑测试”

→ /reflect 检测到这与 /deploy 相关
→ 提供将学习内容添加到 .claude/commands/deploy.md 的选项
→ 技能文件更新，加入新步骤

这样一来，技能会随着时间不断变得更智能，而不仅仅是 CLAUDE.md 文件。

升级

从 v2.0.x 或更早版本升级

如果你在更新后遇到“检测到重复的钩子文件”或“没有这样的文件或目录”等错误，你需要清除插件缓存。这是由于 Claude Code 已知的缓存问题所致：

• #14061 — /plugin update 不会失效缓存
• #15369 — 卸载不会清除缓存文件

# 1. 卸载插件
claude plugin uninstall claude-reflect@claude-reflect-marketplace

# 2. 清除两个缓存（必须！）
rm -rf ~/.claude/plugins/marketplaces/claude-reflect-marketplace
rm -rf ~/.claude/plugins/cache/claude-reflect-marketplace

# 3. 完全退出 Claude Code（重启终端或关闭应用）

# 4. 重新安装
claude plugin install claude-reflect@claude-reflect-marketplace

标准更新

对于正常更新（无缓存问题的情况）：

# 使用 Claude Code 中的 /plugin 菜单
/plugin
# 选择 “立即更新” 以更新 claude-reflect

卸载

claude plugin uninstall claude-reflect@claude-reflect-marketplace

文件结构

claude-reflect/
├── .claude-plugin/
│   └── plugin.json         # 插件清单（自动注册钩子）
├── commands/
│   ├── reflect.md          # 主命令
│   ├── reflect-skills.md   # 技能发现
│   ├── skip-reflect.md     # 跳过队列
│   └── view-queue.md       # 查看队列
├── hooks/
│   └── hooks.json          # 插件安装时自动配置
├── scripts/
│   ├── lib/
│   │   ├── reflect_utils.py      # 共享工具
│   │   └── semantic_detector.py  # AI驱动的语义分析
│   ├── capture_learning.py       # 钩子：检测纠正
│   ├── check_learnings.py        # 钩子：预压缩检查
│   ├── post_commit_reminder.py   # 钩子：提交后提醒
│   ├── compare_detection.py      # 比较正则表达式与语义检测
│   ├── extract_session_learnings.py
│   ├── extract_tool_errors.py
│   ├── extract_tool_rejections.py
│   └── legacy/                   # Bash脚本（已弃用）
├── tests/                  # 测试套件
└── SKILL.md                # Claude 的技能上下文

功能

历史扫描

首次使用 claude-reflect？运行：

/reflect --scan-history

这将扫描你过去的所有会话，找出你曾经做出的纠正，以免丢失安装前的学习内容。

智能过滤

Claude 会过滤掉：

• 问题（不是纠正）
• 一次性任务指示
• 特定上下文的请求
• 模糊或不可操作的反馈

只有可复用的学习内容才会被保留。

重复检测

在添加学习内容之前，系统会检查现有的 CLAUDE.md 内容。如果发现类似内容，你可以：

• 合并到现有条目
• 替换旧条目
• 跳过重复内容

语义去重

随着时间推移，CLAUDE.md 可能会积累许多相似的内容。运行 /reflect --dedupe 可以：

• 找到语义上相似的条目（即使措辞不同）
• 提出整合后的版本
• 清理冗余的学习内容。

例如：

修改前：
  - 复杂任务使用 gpt-5.1
  - 推理任务优先使用 gpt-5.1
  - gpt-5.1 更适合解决难题

修改后：
  - 复杂推理任务使用 gpt-5.1

小贴士

1. 使用明确的标记来标注重要的学习内容：

   记住：Python 项目始终使用 venv
   

2. 在 Git 提交后运行 /reflect - 钩子会提醒你，但最好养成习惯。

3. 在新机器上进行历史扫描 - 当设置新的开发环境时：

   /reflect --scan-history --days 90
   

4. 项目级与全局级 - 模型名称和通用模式应放在全局；项目特有的约定则保留在项目的 CLAUDE.md 文件中。

5. 每月发现技能 - 每月运行 /reflect-skills --days 30，以找出可能遗漏的自动化机会。

6. 技能会变得更智能 - 当你在使用某个技能时纠正 Claude 的错误时，可以通过 /reflect 将修正反馈回该技能文件本身。

7. 延长会话保留时间 - 默认情况下，Claude Code 会在 30 天后删除本地会话。由于 claude-reflect 依赖会话历史来进行 /reflect --scan-history 和 /reflect-skills 操作，因此可以在 ~/.claude/settings.json 中将其延长：

   { "cleanupPeriodDays": 99999 }
   

贡献

欢迎提交 Pull 请求！请先阅读贡献指南。

许可证

MIT

claude-reflect 快速上手指南

claude-reflect 是一个专为 Claude Code 设计的自学习系统。它能自动捕获你对 AI 的纠正指令，将其转化为永久记忆（写入 CLAUDE.md），并能分析历史会话模式，自动生成可复用的技能命令。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 核心依赖：已安装 Claude Code CLI。
• 运行环境：Python 3.6+（大多数现代操作系统默认已包含）。
• 支持平台：
  • macOS（完全支持）
  • Linux（完全支持）
  • Windows（完全支持，使用原生 Python，无需 WSL）

安装步骤

通过 Claude Code 插件市场进行安装，操作简单快捷：

1. 添加市场源

   claude plugin marketplace add bayramannakov/claude-reflect
   

2. 安装插件

   claude plugin install claude-reflect@claude-reflect-marketplace
   

3. 激活插件（重要） 安装完成后，必须完全重启 Claude Code（退出并重新打开终端或应用），以便自动配置钩子（Hooks）和加载命令。

提示：首次运行 /reflect 时，系统会提示你扫描过去的会话以提取潜在的学习内容。

基本使用

安装重启后，插件会自动在后台运行。以下是两个最核心的使用场景：

1. 从纠正中学习 (Learn from Corrections)

当你在使用 Claude Code 时纠正它的错误，插件会自动捕获这些瞬间。

• 操作示例： 你在对话中输入："no, use gpt-5.1 not gpt-5" 或 "实际上，请使用 Python 而不是 Node.js"。
• 处理流程：
  1. 系统自动将纠正内容加入队列。
  2. 运行以下命令审查并应用这些知识：

     /reflect
     

  3. Claude 会展示待处理的纠正列表，你可以选择 Apply（应用）、Edit（编辑后应用）或 Skip（跳过）。
  4. 确认后的内容将被永久写入 CLAUDE.md，未来的会话中将不再犯同样错误。

2. 发现工作流模式 (Discover Workflow Patterns)

如果你反复执行类似的任务，插件可以帮你将其封装为专用命令。

• 操作示例： 假设你过去多次询问过“检查我的生产力数据”或“回顾今日工作重点”。
• 执行命令：

  /reflect-skills
  

• 结果： 系统会分析最近 14 天的会话历史，识别重复模式，并建议生成新的技能文件（例如 /daily-review）。你只需确认即可在 .claude/commands/ 目录下生成对应的命令文件，实现一键复用复杂工作流。

常用辅助命令

命令	说明
/view-queue	查看当前待处理的纠正队列，不进行处理
/reflect --dry-run	预览变更但不实际应用到文件
/reflect-skills --days 30	分析过去 30 天的会话以发现技能模式
/skip-reflect	丢弃所有排队等待的学习内容