深度解析：Claude Code /insights 命令的运作机制

原文：Deep Dive: How Claude Code's /insights Command Works
作者：

Trent Zolkos

深度解析：Claude Code /insights 命令的运作机制

Claude Code 的 /insights 命令能生成一份详尽的 HTML 报告，全盘分析你在所有会话中的使用习惯。该报告能帮你复盘与 Claude 的交互模式：哪些做法效果好，哪里存在卡点 (friction)，以及如何优化工作流。

输出的报告效果非常惊艳，强烈推荐大家试一试并通读全文！

命令： /insights

描述： “生成 Claude Code 会话分析报告”

输出： 交互式 HTML 报告，保存于 ~/.claude/usage-data/report.html

但其底层运作机制究竟如何？让我们来拆解整个处理流程。

分析流程

洞察生成是一个多阶段流程：

  1. 收集：抓取 ~/.claude/projects/ 下的所有会话日志
  2. 过滤：剔除智能体 (Agent) 子会话和内部操作
  3. 提取元数据：解析每个会话的 Token 用量、工具使用情况、时长等
  4. LLM 分析：从会话记录中提取定性的“特征维度” (facets)
  5. 聚合：汇总所有会话数据
  6. 生成洞察：使用多个专用 Prompt 进行深度分析
  7. 渲染：生成交互式 HTML 报告

提取出的特征维度会缓存在 ~/.claude/usage-data/facets/ 中，以加快后续运行速度。

第一阶段：预处理与元数据提取

调用 LLM 前，Claude Code 会先处理会话日志，提取结构化元数据。

过滤规则如下：

  • 智能体子会话（文件名以 agent- 开头）
  • 内部特征提取会话
  • 用户消息少于 2 条的会话
  • 时长短于 1 分钟的会话

提取的关键数据：

  • session_id - 唯一标识符
  • start_time - 会话开始时间
  • duration_minutes - 持续时长
  • user_message_count - 用户消息数
  • input_tokens / output_tokens - Token 用量
  • tool_counts - 工具使用频率
  • languages - 基于文件后缀检测到的编程语言
  • git_commits / git_pushes - Git 活动
  • user_interruptions - 打断 Claude 的次数
  • tool_errors - 工具报错及分类
  • lines_added / lines_removed / files_modified - 代码变更统计
  • uses_task_agent / uses_mcp / uses_web_search / uses_web_fetch - 功能使用统计
  • first_prompt - 初始 Prompt
  • summary - 简短会话摘要

第二阶段：长对话摘要

若会话记录超过 30,000 字符，系统会将其切分为 25,000 字符的片段，并在提取特征前对每个片段进行摘要。

摘要 Prompt

总结 Claude Code 会话记录的这一部分。重点关注：
1. 用户要求做什么
2. Claude 做了什么（使用的工具、修改的文件）
3. 任何卡点或问题
4. 最终结果

保持简洁——3-5 句话。保留具体细节，如文件名、错误信息和用户反馈。

TRANSCRIPT CHUNK:

第三阶段：特征提取 (Facet Extraction)

这是定性分析的核心环节。针对每个会话（每次运行最多分析 50 个新会话），Claude 会分析记录并提取结构化的“特征维度”——即对发生情况的定性评估。

模型： Haiku（快速且经济） 最大输出 Token： 4096

特征提取 Prompt

分析此 Claude Code 会话并提取结构化特征。

关键准则：

1. **goal_categories（目标类别）**：仅统计用户*明确*要求的任务。
   - 不统计 Claude 自发的代码库探索
   - 不统计 Claude 自行决定要做的工作
   - 仅统计用户说 "can you...", "please...", "I need...", "let's..." 的情况

2. **user_satisfaction_counts（用户满意度）**：仅基于明确的用户信号。
   - "Yay!", "great!", "perfect!" → happy（开心）
   - "thanks", "looks good", "that works" → satisfied（满意）
   - "ok, now let's..." (无抱怨继续) → likely_satisfied（可能满意）
   - "that's not right", "try again" → dissatisfied（不满意）
   - "this is broken", "I give up" → frustrated（受挫）

3. **friction_counts（卡点统计）**：具体指出问题所在。
   - misunderstood_request: Claude 理解错误
   - wrong_approach: 目标正确，但方法错误
   - buggy_code: 代码无法运行
   - user_rejected_action: 用户拒绝或停止工具调用
   - excessive_changes: 过度设计或改动过多

4. 若会话极短或仅为预热，goal_category 记为 warmup_minimal

SESSION:
<在此插入会话记录>

仅返回符合此模式的有效 JSON 对象：
{
  "underlying_goal": "用户根本上想要达成什么",
  "goal_categories": {"category_name": count, ...},
  "outcome": "fully_achieved（完全实现） | mostly_achieved（大部分实现） |
              partially_achieved（部分实现） | not_achieved（未实现） |
              unclear_from_transcript（记录中不明确）",
  "user_satisfaction_counts": {"level": count, ...},
  "claude_helpfulness": "unhelpful（无助） | slightly_helpful（略有帮助） | moderately_helpful（中等帮助） | very_helpful（非常有帮助） | essential（不可或缺）",
  "session_type": "single_task（单任务） | multi_task（多任务） | iterative_refinement（迭代优化） | exploration（探索） | quick_question（快速问答）",
  "friction_counts": {"friction_type": count, ...},
  "friction_detail": "一句话描述卡点，无则留空",
  "primary_success": "none | fast_accurate_search（快速精准搜索） | correct_code_edits（正确代码编辑） | good_explanations（良好解释） | proactive_help（主动帮助） | multi_file_changes（多文件协作） | good_debugging（高效调试）",
  "brief_summary": "一句话总结：用户想要什么以及是否得到了"
}

目标类别 (Goal Categories)

类别 描述
debug_investigate 调试/排查
implement_feature 功能实现
fix_bug Bug 修复
write_script_tool 编写脚本/工具
refactor_code 代码重构
configure_system 系统配置
create_pr_commit 创建 PR/Commit
analyze_data 数据分析
understand_codebase 理解代码库
write_tests 编写测试
write_docs 编写文档
deploy_infra 部署/基建
warmup_minimal 缓存预热（极短会话）

满意度层级

frustrated（受挫） → dissatisfied（不满意） → likely_satisfied（可能满意） → satisfied（满意） → happy（开心） → unsure（不确定）

结果分类

not_achieved（未实现） → partially_achieved（部分实现） → mostly_achieved（大部分实现） → fully_achieved（完全实现） → unclear_from_transcript（不明确）

卡点分类 (Friction Categories)

类别 描述
misunderstood_request Claude 理解错误
wrong_approach 目标正确，但方法错误
buggy_code 代码无法运行
user_rejected_action 用户拒绝工具调用
claude_got_blocked Claude 卡壳/受阻
user_stopped_early 用户提前停止
wrong_file_or_location 编辑了错误的文件/位置
excessive_changes 过度设计或改动过多
slow_or_verbose 太慢或太啰嗦
tool_failed 工具调用失败
user_unclear 用户需求不明确
external_issue 外部/环境问题

Claude 帮助程度

unhelpful → slightly_helpful → moderately_helpful → very_helpful → essential

会话类型

类型 描述
single_task 专注单一任务
multi_task 单次会话处理多项任务
iterative_refinement 来回迭代优化
exploration 探索/理解代码库
quick_question 简短问答

主要成功类别

类别 描述
none 无显著成功
fast_accurate_search 快速精准的代码搜索
correct_code_edits 准确的代码修改
good_explanations 清晰的解释
proactive_help 超出预期的主动建议
multi_file_changes 成功协调多文件编辑
good_debugging 高效调试

第四阶段：聚合与分析

收集完所有会话数据和特征后，系统会聚合数据，并通过多个专用 Prompt 进行深度分析。

模型： Haiku 最大输出 Token： 每个 Prompt 8192

传递给分析 Prompt 的数据

每个 Prompt 都会接收聚合后的统计数据：

{
  sessions: <总会话数>,
  analyzed: <包含特征的会话数>,
  date_range: { start, end },
  messages: <总消息数>,
  hours: <总时长（小时）>,
  commits: <git 提交数>,
  top_tools: [使用率前 8 的工具],
  top_goals: [前 8 个目标类别],
  outcomes: { 结果分布 },
  satisfaction: { 满意度分布 },
  friction: { 卡点类型统计 },
  success: { 成功类别统计 },
  languages: { 语言使用统计 }
}

以及文本摘要：

  • SESSION SUMMARIES（会话摘要）： 最多 50 个简短摘要
  • FRICTION DETAILS（卡点详情）： 最多 20 个来自特征维度的卡点细节
  • USER INSTRUCTIONS TO CLAUDE（用户指令）： 最多 15 条用户重复给出的指令

4.1 项目领域分析 (Project Areas)

分析此 Claude Code 使用数据并识别项目领域。

仅返回有效的 JSON 对象：
{
  "areas": [
    {
      "name": "领域名称",
      "session_count": N,
      "description": "用 2-3 句话描述做了什么工作以及如何使用 Claude Code。"
    }
  ]
}

包含 4-5 个领域。忽略 Claude Code 内部操作。

4.2 交互风格分析 (Interaction Style)

分析此 Claude Code 使用数据并描述用户的交互风格。

仅返回有效的 JSON 对象：
{
  "narrative": "用 2-3 段话分析用户*如何*与 Claude Code 交互。
               使用第二人称 'you'。描述模式：是快速迭代还是预先提供详细规范？
               是经常打断还是让 Claude 跑完？
               包含具体例子。用 **粗体** 标记关键洞察。",
  "key_pattern": "一句话总结最独特的交互风格"
}

4.3 亮点分析 (What Works Well)

分析此 Claude Code 使用数据，找出对该用户行之有效的做法。
使用第二人称 ('you')。

仅返回有效的 JSON 对象：
{
  "intro": "1 句话背景介绍",
  "impressive_workflows": [
    {
      "title": "简短标题（3-6 个词）",
      "description": "2-3 句话描述令人印象深刻的工作流或方法。
                      使用 'you' 而非 'the user'。"
    }
  ]
}

包含 3 个令人印象深刻的工作流。

4.4 卡点分析 (Friction Analysis)

分析此 Claude Code 使用数据，找出该用户的卡点。
使用第二人称 ('you')。

仅返回有效的 JSON 对象：
{
  "intro": "1 句话总结卡点模式",
  "categories": [
    {
      "category": "具体的类别名称",
      "description": "1-2 句话解释此类问题，以及可以做哪些改变。
                      使用 'you' 而非 'the user'。",
      "examples": ["带有后果的具体例子", "另一个例子"]
    }
  ]
}

包含 3 个卡点类别，每个类别 2 个例子。

4.5 改进建议 (Suggestions & Improvements)

这是最长的 Prompt，旨在提供可执行的建议：

分析此 Claude Code 使用数据并提出改进建议。

## CC 功能参考（从这里挑选 features_to_try）：

1. **MCP Servers**：通过模型上下文协议 (Model Context Protocol) 连接外部工具、数据库和 API。
   - 用法：运行 `claude mcp add <server-name> -- <command>`
   - 适用场景：数据库查询、Slack 集成、GitHub issue 查找、连接内部 API

2. **Custom Skills（自定义技能）**：你定义的 Markdown 文件，包含可复用的 Prompt，通过单个 /command 运行。
   - 用法：创建 `.claude/skills/commit/SKILL.md` 并写入指令。
     然后输入 `/commit` 运行。
   - 适用场景：重复性工作流——/commit, /review, /test, /deploy, /pr，
     或复杂的多步工作流

3. **Hooks（钩子）**：在特定生命周期事件自动运行的 Shell 命令。
   - 用法：添加到 `.claude/settings.json` 的 "hooks" 键下。
   - 适用场景：自动格式化代码、运行类型检查、强制规范

4. **Headless Mode（无头模式）**：从脚本和 CI/CD 中非交互式地运行 Claude。
   - 用法：`claude -p "fix lint errors" --allowedTools "Edit,Read,Bash"`
   - 适用场景：CI/CD 集成、批量代码修复、自动审查

5. **Task Agents（任务智能体）**：Claude 衍生出专注的子智能体进行复杂探索或并行工作。
   - 用法：Claude 会在有帮助时自动调用，或者你要求 "use an agent to explore X"
   - 适用场景：代码库探索、理解复杂系统

仅返回有效的 JSON 对象：
{
  "claude_md_additions": [
    {
      "addition": "基于工作流模式，建议添加到 CLAUDE.md 的具体行或代码块。
                   例如，'修改 auth 相关文件后始终运行测试'",
      "why": "基于实际会话，用 1 句话解释为什么这会有帮助",
      "prompt_scaffold": "关于添加到 CLAUDE.md 何处的说明。
                          例如，'添加在 ## Testing 部分下'"
    }
  ],
  "features_to_try": [
    {
      "feature": "来自上述 CC 功能参考的功能名称",
      "one_liner": "功能简介",
      "why_for_you": "基于你的会话，为什么这对*你*有帮助",
      "example_code": "可复制的实际命令或配置"
    }
  ],
  "usage_patterns": [
    {
      "title": "简短标题",
      "suggestion": "1-2 句话总结",
      "detail": "3-4 句话解释这如何适用于*你的*工作",
      "copyable_prompt": "可复制尝试的具体 Prompt"
    }
  ]
}

关于 claude_md_additions 的重要提示：优先考虑在用户数据中*多次*出现的指令。
如果用户在 2 个以上的会话中告诉 Claude 同样的事情（例如 '总是运行测试'，
'使用 TypeScript'），那就是首选候选项——绝不要让用户重复自己。

关于 features_to_try 的重要提示：从上述 CC 功能参考中挑选 2-3 个。
每个类别包含 2-3 个条目。

4.6 未来展望 (On The Horizon)

分析此 Claude Code 使用数据并识别未来机会。

仅返回有效的 JSON 对象：
{
  "intro": "关于 AI 辅助开发演进的 1 句话",
  "opportunities": [
    {
      "title": "简短标题（4-8 个词）",
      "whats_possible": "2-3 句关于自主工作流的宏大描述",
      "how_to_try": "1-2 句提及相关工具的话",
      "copyable_prompt": "可尝试的详细 Prompt"
    }
  ]
}

包含 3 个机会。要把眼光放长远 (Think BIG)——自主工作流、并行智能体、针对测试进行迭代。

4.7 趣味彩蛋 (Fun Ending)

分析此 Claude Code 使用数据并找到一个难忘的时刻。

仅返回有效的 JSON 对象：
{
  "headline": "来自记录的一个难忘的*定性*时刻——不是统计数据。
               人性化的、有趣的或令人惊讶的事情。",
  "detail": "关于此事发生时间/地点的简短背景"
}

从会话摘要中发掘真正有趣或好玩的内容。

第五阶段：概览总结 (At a Glance)

最后的 LLM 调用会生成一份高管摘要 (Executive Summary)，将所有内容融会贯通。此 Prompt 会接收之前生成的所有洞察作为上下文。

概览 Prompt

你正在为 Claude Code 用户撰写一份"概览"总结。
目标是帮助他们理解自己的使用情况，并提升使用 Claude 的效果，
特别是随着模型能力的提升。

使用以下 4 部分结构：

1. **What's working（行之有效之处）** - 用户与 Claude 交互的独特风格是什么？
   他们完成了哪些有影响力的事？可以包含一两个细节，但保持高层级，
   因为用户可能记不太清了。不要空洞恭维，也不要关注具体的工具调用。

2. **What's hindering you（阻碍你之处）** - 分为 (a) Claude 的错（误解、
   方法错误、Bug）和 (b) 用户端的卡点（上下文不足、环境问题——理想情况下
   比单个项目更通用）。要诚实但具有建设性。

3. **Quick wins to try（速赢策略）** - 他们可以尝试的具体 Claude Code 功能
   （来自下方示例），或者如果你认为非常有说服力的某种工作流技巧。
   （避免像"行动前让 Claude 确认"或"预先打出更多上下文"这类平庸建议。）

4. **Ambitious workflows for better models（进阶工作流）** - 
   随着未来 3-6 个月模型能力的大幅提升，他们应该准备什么？
   现在看似不可能但即将成为可能的工作流有哪些？从下方相应部分汲取灵感。

每部分保持 2-3 句，不要太长。不要让用户感到负担。
不要提及下方会话数据中的具体数字或下划线类别。使用教练的口吻。

仅返回有效的 JSON 对象：
{
  "whats_working": "...",
  "whats_hindering": "...",
  "quick_wins": "...",
  "ambitious_workflows": "..."
}

SESSION DATA:
<聚合统计 JSON>

## Project Areas (what user works on)
<项目领域结果>

## Big Wins (impressive accomplishments)
<亮点分析结果>

## Friction Categories (where things go wrong)
<卡点分析结果>

## Features to Try
<改进建议结果>

## Usage Patterns to Adopt
<使用模式结果>

## On the Horizon (ambitious workflows for better models)
<未来展望结果>

第六阶段：报告生成

所有收集的数据和 LLM 生成的洞察最终被渲染成一份交互式 HTML 报告。

统计仪表盘：

  • 总会话数、消息数、时长、Token 数
  • Git 提交和推送
  • 活跃天数和连胜纪录 (Streaks)
  • 高峰活动时段

可视化图表：

  • 每日活动图表
  • 工具使用分布
  • 编程语言细分
  • 满意度分布
  • 结果追踪

叙述部分：

  • 项目领域及描述
  • 交互风格分析
  • 行之有效之处（令人印象深刻的工作流）
  • 卡点分析及具体案例
  • 值得尝试的 CLAUDE.md 补充建议
  • 值得探索的功能
  • 未来机遇
  • 趣味难忘时刻

流程伪代码

各阶段的连接逻辑如下：

function generateInsights():
    // 阶段 1: 加载并过滤会话
    sessions = loadSessionLogs("~/.claude/projects/")
    sessions = sessions.filter(s =>
        !isAgentSession(s) &&
        !isInternalSession(s) &&
        s.userMessageCount >= 2 &&
        s.durationMinutes >= 1
    )

    // 从每个会话提取元数据
    metadata = sessions.map(extractMetadata)

    // 阶段 2 & 3: 提取特征（带缓存）
    facets = {}
    for session in sessions:
        cached = loadCachedFacet(session.id)
        if cached:
            facets[session.id] = cached
        else:
            transcript = session.transcript
            if transcript.length > 30000:
                transcript = summarizeInChunks(transcript)

            facets[session.id] = callLLM(FACET_EXTRACTION_PROMPT + transcript)
            saveFacetToCache(session.id, facets[session.id])

    // 阶段 4: 聚合与分析
    aggregated = aggregateAllData(metadata, facets)

    insights = {}
    insights.project_areas = callLLM(PROJECT_AREAS_PROMPT, aggregated)
    insights.interaction_style = callLLM(INTERACTION_STYLE_PROMPT, aggregated)
    insights.what_works = callLLM(WHAT_WORKS_PROMPT, aggregated)
    insights.friction = callLLM(FRICTION_PROMPT, aggregated)
    insights.suggestions = callLLM(SUGGESTIONS_PROMPT, aggregated)
    insights.on_the_horizon = callLLM(ON_THE_HORIZON_PROMPT, aggregated)
    insights.fun_ending = callLLM(FUN_ENDING_PROMPT, aggregated)

    // 阶段 5: 生成高管摘要
    insights.at_a_glance = callLLM(AT_A_GLANCE_PROMPT, aggregated + insights)

    // 阶段 6: 渲染 HTML 报告
    html = renderReport(aggregated, insights)
    saveFile("~/.claude/usage-data/report.html", html)

    return insights

数据存储

路径 用途
~/.claude/projects/<hash>/ 会话日志
~/.claude/usage-data/facets/<session-id>.json 缓存的特征数据
~/.claude/usage-data/report.html 生成的报告

特征按会话缓存，因此多次运行 /insights 仅分析新增会话。

技术细节

设置 值
模型 Haiku
每个 Prompt 最大 Token 8192
每次运行分析会话数 最多 50 个新会话
记录大小限制 30,000 字符
摘要分块大小 25,000 字符

隐私说明

所有分析均通过 Anthropic API 在本地进行。你的会话数据保留在本地机器上——HTML 报告也在本地生成，是否分享完全由你决定。

特征提取仅关注交互模式，而非代码内容：

  • 你要求的任务类型
  • 你如何回应 Claude 的输出
  • 工作流中的卡点位置
  • 你使用了哪些工具和功能

获取更佳洞察的技巧

  1. 多用 Claude Code - 会话越多，分析越丰富
  2. 提供反馈 - 多说“thanks”（谢谢）或“that's not right”（不对），以便系统追踪满意度
  3. 保持自然 - 最真实的使用习惯才能揭示最有用的洞察
  4. 定期运行 - 每月检查一次，查看使用模式的演变
See all posts