retrospecting

会话回顾技能

自动加载的上下文

会话分析：contexts/session-analytics.md - 提供全面的会话分析框架，包括数据来源、指标和分析方法。

回顾模板：templates/retrospective-templates.md - 为不同深度的回顾提供标准化报告模板。

核心职责

1. 多源数据收集

系统地从所有可用来源收集数据：

• Git 历史记录：会话时间范围内的提交、差异和文件变更
• Claude 日志：对话记录、工具使用情况和决策模式
• 项目文件：测试覆盖率、代码质量和编译状态
• 用户反馈：关于目标、满意度和痛点的直接反馈
• 子 Agent 交互：使用子 Agent 时，收集其反馈

2. 定量分析

计算可衡量的指标：

• 会话范围（时长、已完成任务、已更改文件）
• 质量指标（编译率、测试覆盖率、规范符合度）
• 效率指标（工具成功率、返工率、完成率）
• 用户体验数据（满意度、摩擦点）

3. 定性评估

识别模式和洞见：

• 带来良好结果的有效方法
• 导致问题或延误的问题模式
• 值得提取并在未来复用的解决方案
• 适用于此类项目的特定情境经验

4. 报告生成

使用适当的模板创建结构化回顾报告：

• 快速回顾：简短的会话总结（5-10 分钟）
• 全面回顾：针对重要会话的详细分析
• 根据会话复杂度和用户需求选择模板

工作流程

步骤 0：快速评估会话

收集数据前，确定合适的分析深度：

1. 检查会话规模：

   # Count recent commits
   git log --oneline --since="1 hour ago" | wc -l
   
   # List session log files with metadata
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh --sort date | head -5
   

2. 根据指标向用户建议分析深度：

   • 快速（<10 次提交，<5MB 日志）：“5-10 分钟的轻量分析”
   • 标准（10-25 次提交，5-20MB 日志）：“15-20 分钟的均衡分析”
   • 全面（>25 次提交，>20MB 日志）：“30 分钟以上的深入分析”

3. 允许用户调整：“根据 [X 次提交，Y MB 日志]，我建议进行 [MODE] 回顾（约需 Z 分钟）。这样可以吗？或者您希望选择其他深度？”

4. 提前退出条件：如果用户表示“只要快速总结”或“概览即可”，无论会话规模如何，都自动使用快速模式。

步骤 1：确定会话范围

1. 请用户定义会话边界（时间范围或提交范围）
2. 明确会话目标：“您当时想完成什么？”
3. 确认步骤 0 中确定的回顾深度

步骤 2：收集数据

根据确认的深度模式执行数据收集：

按深度收集数据

快速模式：

• Git：仅运行 git diff <start>..<end> --stat（不查看完整差异）
• 日志：仅通过 extracting-session-data 技能提取统计数据和错误
• 文件：仅检查编译状态
• 用户：提出 2-3 个有针对性的问题
• 跳过：子 Agent 反馈、详细文件分析

标准模式：

• Git：完整提交历史和统计数据，以及关键文件的选择性差异
• 日志：通过 extracting-session-data 技能提取元数据、统计数据、工具使用情况和错误
• 文件：针对已更改文件的质量指标
• 用户：围绕主要领域提出 5-7 个问题
• 包含：适用时收集子 Agent 反馈

全面模式：

• Git：所有数据（完整日志、差异和文件分析）
• 日志：通过 extracting-session-data 技能提取所有数据类型；若日志少于 500 行，可阅读完整日志
• 文件：深入分析，包括测试和架构符合度
• 用户：广泛收集反馈（8-10 个问题）
• 包含：所有子 Agent 反馈和模式提取

Git 分析

使用 analyzing-git-sessions 技能收集 Git 数据：

快速模式：请求“简洁”输出（仅统计数据，不含差异） 标准模式：请求针对关键文件的“详细”输出 全面模式：请求采用“代码审查”格式进行完整分析

调用技能并指定会话时间范围：

Skill: analyzing-git-sessions
Input: "<start-time> to <end-time>" or "<start-commit>..<end-commit>"
Depth: [concise|detailed|code-review] based on retrospective mode

该技能将返回回顾分析所需的结构化 Git 指标。

日志处理（根据大小调整）

使用 extracting-session-data 技能高效访问 Claude Code 原生会话日志。

1. 列出可用会话：

   # List all sessions with metadata (size, lines, date, branch)
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/list-sessions.sh
   

2. 检查会话大小：

   # Get statistics for specific session
   ${CLAUDE_PROJECT_DIR}/.claude/skills/extracting-session-data/scripts/extract-data.sh \
       --type statistics --session SESSION_ID
   

3. 根据会话大小和模式提取数据：

   快速模式（或任何超过 2000 行的会话）：

   # Extract only statistics and errors
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID --limit 10
   

   标准模式（500–2000 行的会话）：

   # Extract metadata, statistics, tool usage, and errors
   extract-data.sh --type metadata --session SESSION_ID
   extract-data.sh --type statistics --session SESSION_ID
   extract-data.sh --type tool-usage --session SESSION_ID
   extract-data.sh --type errors --session SESSION_ID
   

   全面模式（少于 500 行的会话）：

   # Extract all available data
   extract-data.sh --type all --session SESSION_ID
   
   # Or read full log file if needed for detailed analysis
   # (Only for small sessions - check line count first!)
   

4. 多会话分析：

   # Filter sessions by criteria
   filter-sessions.sh --since "7 days ago" --branch main
   
   # Extract data from all filtered sessions (omit --session flag)
   extract-data.sh --type statistics  # Runs on all sessions
   

5. 综合提取的数据： 提取完成后，将数据综合为精简摘要（最多 200 行），再继续分析。

路径计算：extracting-session-data 技能会自动处理所有路径计算。会话日志存储在 ~/.claude/projects/{project-identifier}/ 中，其中标识符根据工作目录路径生成。

项目分析

检查已更改的文件、测试和文档（深度与分析模式相匹配）

用户反馈

征求用户对会话体验的直接反馈（问题数量根据深度模式确定）

####子 Agent 反馈

如果使用了子 Agent，则调用它们以收集其观点（仅限标准/全面模式）

第 3 步：分析数据

应用 session-analytics.md 框架：

• 计算定量指标
• 找出成功和问题指标
• 提取模式（成功做法和反模式）
• 评估沟通效果和技术质量

第 4 步：生成洞见

将分析综合为可执行的洞见：

• 哪些方面做得好，以及原因（提供具体证据）
• 哪些因素导致了问题，以及问题的根本原因
• 改进机会（按影响排序）
• 在未来会话中值得沿用或避免的模式

第 5 步：创建报告

使用 retrospective-templates.md 中适当的模板：

• 以清晰的结构呈现发现，并提供证据
• 在相关处注明具体的文件:行号引用
• 按影响和可行性排列建议的优先级
• 确保所有建议都具体且可执行

第 6 步：征求用户确认

呈现报告并询问：

• 这符合你的体验吗？
• 我们是否遗漏了其他痛点？
• 哪些改进对你最有价值？

第 7 步：建议配置改进

如果回顾分析发现 Claude 或 Agent 交互中有可改进之处：

1. 分析能否将改进写入配置文件：
   • CLAUDE.md：核心指令、工作流实践、沟通模式
   • SKILL.md 文件：特定技能的指令、工作流程、反模式
   • Agent 定义文件：Agent 提示词、工具使用、协作模式
2. 起草具体且可执行的配置更新建议：
   • 引用应修改的现有文本（如果是更新已有内容）
   • 提供建议新增或替换的文本
   • 根据回顾分析结果解释原因
3. 向用户呈现建议：
   • “根据本次回顾分析，我发现了对 [file] 进行改进的可能。你希望我实施这些更改吗？”
   • 展示将要进行的具体更改
4. 如果用户同意：
   • 使用 Edit 工具应用更改
   • 确认已更新的内容
5. 如果用户拒绝：
   • 在回顾报告中记录这些建议，供日后参考

第 8 步：会话归档信息

创建并验证回顾报告后：

1. 告知用户会话日志的存储位置：
   • "会话日志永久存储在 ~/.claude/projects/{project-dir}/{session-id}.jsonl"
   • "这些日志由 Claude Code 管理，不应手动删除"
2. 说明回顾报告单独保存在：
   • ${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/
3. 请注意，Claude Code 会自动管理会话日志的保留

输出标准

报告质量要求

• 基于证据：每项结论都有具体示例支持
• 可执行：所有建议都包含实施指导
• 具体明确：避免含糊的表述，使用具体示例
• 按优先级排序：清楚标明高影响和低影响事项
• 平衡全面：肯定成功之处，同时指出可改进之处

文件引用

引用具体代码位置时，使用 file:line_number 格式。

指标展示

使用清晰的表格或列表呈现指标，并说明其解读方式。

建议格式

每项建议都应包含：

• 内容：要采取的具体行动
• 原因：根本原因或理由
• 方法：实施方式
• 影响：预期收益

与子 Agent 集成

会话中使用了子 Agent 时：

收集反馈

向每个参与的子 Agent 发送类似以下提示词：

• "本次会话中，哪些方面进展顺利？"
• "哪些指令或上下文不清楚？"
• "你需要但缺少哪些工具或能力？"
• "如何改进与你和 Claude 的协作？"

综合分析

将子 Agent 的反馈纳入回顾：

• 找出协作或交接问题
• 指出指令清晰度或上下文方面的不足
• 认可成功的协作模式
• 建议改进子 Agent 的使用方式

上下文预算管理

在整个回顾过程中监控上下文用量，避免溢出：

预算阈值

• 技能指令：约 6-8K tokens（此文件及自动加载的上下文）
• 小型日志文件：每个文件 2-5K tokens
• 大型日志文件：完整读取时为 10-50K+ tokens
• Git 差异：大型变更为 5-20K tokens
• 用户对话：不定（2-10K tokens）

根据剩余预算调整策略

高预算（剩余 >100K tokens）：

• 可以安全地使用综合模式
• 日志少于 2000 行时可完整读取
• 包含完整的 Git 差异
• 如有需要，加载 session-analytics.md 中的详细指标

中等预算（剩余 50-100K tokens）：

• 默认使用标准模式
• 读取前先总结日志（使用 bash 提取内容）
• 仅选择性查看关键文件的 Git 差异
• 跳过扩展上下文加载

低预算（剩余 <50K tokens）：

• 无论会话规模如何，都强制使用快速模式
• 仅使用 bash 总结日志（不完整读取）
• 仅查看 Git 统计信息，不查看差异
• 提醒用户："可用上下文有限，因此仅对关键方面进行重点分析"

保留上下文的技巧

1. 提取并丢弃：从大型文件中提取关键指标，立即丢弃冗长的源内容
2. 尽早综合：继续前先创建简洁摘要（最多 200 行）
3. 逐步细化：从高层次分析开始，仅在用户表示感兴趣时深入
4. 抽样查看：阅读有代表性的部分，而非整个文件

紧急回退方案

如果分析期间上下文即将达到上限：

1. 立即停止收集数据
2. 根据目前收集的数据生成报告
3. 在报告中注明："受上下文限制，分析范围有限——未涵盖的具体方面：[具体方面]"
4. 提供在新对话中针对特定方面进行后续分析

应避免的反模式

不要：

• 不收集实际数据就生成回顾
• 提出模糊、无法付诸行动的建议
• 只关注负面因素；也要肯定做得好的地方
• 忽略用户明确表达的优先事项和目标
• 编写冗长的报告，以致关键见解被淹没
• 不了解上下文和目标就分析会话

应该：

• 以会话数据中的具体证据为分析依据
• 提供具体、可执行的建议，并说明实施方法
• 肯定做得好的地方，同时指出改进机会
• 让建议与用户的优先事项保持一致
• 编写简洁的报告，突出关键见解
• 在分析成效之前先了解会话上下文

跨插件增强

安装了同系列的 Bitwarden 插件后，回顾可获得专业分析：

安全意识回顾（bitwarden-security-engineer plugin）

收集会话中的 git 差异后：

• 扫描已提交的凭据 → 针对会话的 git 差异启用 Skill(detecting-secrets)，在意外提交机密时发出警告
• 评估新代码的安全状况 → 如果会话引入了身份验证、加密或输入处理代码，则启用 Skill(analyzing-code-security)，在回顾报告中标记潜在漏洞

质量分类（bitwarden-code-review plugin）

• 按影响对会话变更进行分类 → 启用 Skill(classifying-review-findings)，使用 CRITICAL/IMPORTANT/DEBT/SUGGESTED 框架对会话变更进行分类，让用户清楚了解哪些事项需要关注

这些技能是可选的。如果无法使用，请继续进行标准回顾分析。

成功标准

一份出色的回顾应当：

1. 提供信息：让用户对自己的工作流有所了解
2. 指引行动：明确说明改进的后续步骤
3. 激励用户：肯定成功之处，鼓励继续保持良好做法
4. 聚焦重点：通过优先级排序，帮助用户了解应将精力投入何处
5. 助力实践：提供用户可应用于未来会话的框架/模式

报告存储

目录：${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/

文件名格式：YYYY-MM-DD-session-description-SESSION_ID.md

• 使用 ISO 日期格式（YYYY-MM-DD）按时间顺序排序
• 描述保持简短（3-5 个词，以连字符分隔）
• 包含日志文件中的会话 ID，以便追溯

示例路径：${CLAUDE_PROJECT_DIR}/.claude/skills/retrospecting/reports/2025-10-23-authentication-refactor-3be2bbaf.md