ai-mistake-recorder

name	ai-mistake-recorder
description	记录 AI 犯错或可改进点，生成可复用的学习资产。支持两种模式：(1) 当前会话 - 会话结束时触发，引导用户回顾本次会话中的纠正和可改进点；(2) 指定会话 - 通过 session_id 或 JSONL 文件路径分析历史会话。存储位置：D:\desktop\quackDocs\my_notes\ai_mistake\（index.md 索引 + records.md 实体）。触发词：记录错误、记录问题、AI 错误记录、会话总结、记录教训、record mistakes。

AI 错误记录器

将 AI 犯错的过程转化为可复用的学习资产。

存储位置

• 目录：D:\desktop\quackDocs\my_notes\ai_mistake\
• 索引文件：index.md — 列出所有错误条目（日期、简要描述、分类）
• 实体文件：records.md — 每个错误的完整记录

触发时机

• 当前会话：会话结束前调用，回顾本次会话中的所有纠正和可改进点
• 指定会话：通过 session_id 或 JSONL 文件路径分析历史会话

会话分析脚本

使用 scripts/analyze_session.py 提取会话内容为纯文本：

# 通过 session_id 分析
python scripts/analyze_session.py <session_id> [--tool-call-result] [--output-md FILE]

# 通过 JSONL 文件路径分析
python scripts/analyze_session.py --path <path_to_jsonl> [--tool-call-result] [--output-md FILE]

参数说明：

• session_id：会话 UUID（与 --path 二选一）
• --path：直接指定 JSONL 文件路径
• --config-dir DIR：Claude 配置目录，默认 ~/.claude
• --tool-call-result：显示工具调用详情（调用输入 + 返回结果）
• --output-md FILE：将输出保存为 Markdown 文件（不指定文件名时自动生成）

使用场景：

• 分析当前会话：直接回顾对话内容
• 分析历史会话：先运行脚本提取纯文本，再基于提取内容记录错误

执行流程

1. 确定会话来源

• 当前会话：直接进入回顾流程
• 指定会话：运行 analyze_session.py 提取会话内容，基于提取结果记录

2. 引导回顾

询问用户本次会话中是否有需要记录的错误或可改进点。

2. 收集错误信息

对每个错误/可改进点，收集：

• 简要描述：一句话概括错误
• 场景：在什么情况下发生的
• AI 的做法：AI 实际做了什么
• 正确做法：应该怎么做
• 原因分析：为什么会出现这个问题
• 建议：如何避免类似问题
• 分类：单例使用 / spec 解读 / 代码风格 / 架构理解 / 工具使用 / 其他

3. 写入记录

追加到 records.md：

## YYYY-MM-DD HH:MM — 会话：<会话主题>

### 错误 N：<简要描述>
- **场景**：<场景描述>
- **AI 的做法**：<AI 的实际行为>
- **正确做法**：<正确的做法>
- **原因分析**：<为什么会出现这个问题>
- **建议**：<如何避免类似问题>
- **分类**：<分类>

### 本次会话总结
- 记录错误数：N
- 主要问题类型：<分类1>、<分类2>
- 建议更新的规则：<如果有值得转化为项目规则的建议>

追加到 index.md：

| YYYY-MM-DD | <错误简述> | <分类> | [详情](records.md#YYYY-MM-DD-HHMM) |

4. 输出总结

显示本次记录的错误数量和主要问题类型。

分类体系

• 单例使用：错误地创建新实例而非使用已有单例
• spec 解读：自行发明规则而非遵循 spec
• 代码风格：不符合项目约定的写法
• 架构理解：对模块职责、依赖方向的误解
• 工具使用：错误地使用工具或 API
• 其他：不属于以上分类的错误

重要约束

1. 只记录，不自动更新规则：与 write-project-rules 分离，记录中包含"建议更新的规则"字段供后续手动触发
2. 轻量级分析：只记录错误 + 原因 + 建议，不做深度分析
3. 持续追加：每次记录追加到文件末尾，不修改历史记录