【译】深度解析：Claude Code 的 /insights 命令是如何工作的

诺顿
4 阅读12分钟

原文链接：www.zolkos.com/2026/02/04/…

Claude Code 中的 /insights 命令会生成一份全面的 HTML 报告，分析你在所有 Claude Code 会话中的使用模式。它的设计目的是帮助你理解你与 Claude 的交互方式、哪些地方运作良好、哪里存在摩擦，以及如何改进你的工作流程。

它的输出真的很酷，我鼓励你尝试一下并仔细阅读！

命令： /insights

描述： "生成一份分析你的 Claude Code 会话的报告"

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

但它底层到底发生了什么？让我们追踪整个流程。

分析流水线

insights 生成是一个多阶段过程：

  1. 收集 所有来自 ~/.claude/projects/ 的会话日志
  2. 过滤 掉 agent 子会话和内部操作
  3. 提取元数据 从每个会话中提取（tokens、使用的工具、持续时间等）
  4. 运行 LLM 分析 从会话转录中提取"facets"（定性评估）
  5. 聚合 所有会话数据
  6. 生成洞察 使用多个专门的提示词
  7. 渲染 一个交互式 HTML 报告

facets 会被缓存到 ~/.claude/usage-data/facets/，这样后续运行会更快。

第一阶段：会话过滤与元数据提取

在进行任何 LLM 调用之前，Claude Code 会处理你的会话日志以提取结构化元数据。

会话被过滤排除：

  • Agent 子会话（以 agent- 开头的文件）
  • 内部 facet 提取会话
  • 用户消息少于 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 - 你的初始消息
  • summary - 简短会话摘要

第二阶段：转录摘要（针对长会话）

如果会话转录超过 30,000 字符，它会被分成 25,000 字符的片段，每个片段在 facet 提取之前先进行摘要。

转录摘要提示词

Summarize this portion of a Claude Code session transcript. Focus on:
1. What the user asked for
2. What Claude did (tools used, files modified)
3. Any friction or issues
4. The outcome

Keep it concise - 3-5 sentences. Preserve specific details like file names,
error messages, and user feedback.

TRANSCRIPT CHUNK:

第三阶段：Facet 提取

这是核心的定性分析。对于每个会话（每次运行最多处理 50 个新会话），Claude 分析转录以提取结构化的"facets"——对发生事情的定性评估。

模型： Haiku（快速、经济高效） 最大输出 tokens： 4096

Facet 提取提示词

Analyze this Claude Code session and extract structured facets.

CRITICAL GUIDELINES:

1. **goal_categories**: Count ONLY what the USER explicitly asked for.
   - DO NOT count Claude's autonomous codebase exploration
   - DO NOT count work Claude decided to do on its own
   - ONLY count when user says "can you...", "please...", "I need...", "let's..."

2. **user_satisfaction_counts**: Base ONLY on explicit user signals.
   - "Yay!", "great!", "perfect!" → happy
   - "thanks", "looks good", "that works" → satisfied
   - "ok, now let's..." (continuing without complaint) → likely_satisfied
   - "that's not right", "try again" → dissatisfied
   - "this is broken", "I give up" → frustrated

3. **friction_counts**: Be specific about what went wrong.
   - misunderstood_request: Claude interpreted incorrectly
   - wrong_approach: Right goal, wrong solution method
   - buggy_code: Code didn't work correctly
   - user_rejected_action: User said no/stop to a tool call
   - excessive_changes: Over-engineered or changed too much

4. If very short or just warmup, use warmup_minimal for goal_category

SESSION:
<session transcript is inserted here>

RESPOND WITH ONLY A VALID JSON OBJECT matching this schema:
{
  "underlying_goal": "What the user fundamentally wanted to achieve",
  "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": "One sentence describing friction or empty",
  "primary_success": "none | fast_accurate_search | correct_code_edits | good_explanations | proactive_help | multi_file_changes | good_debugging",
  "brief_summary": "One sentence: what user wanted and whether they got it"
}

目标类别

类别描述
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

摩擦类别

类别描述
misunderstood_requestClaude 理解错误
wrong_approach目标正确，解决方法错误
buggy_code代码不能正常工作
user_rejected_action用户对工具调用说 no/stop
claude_got_blockedClaude 卡住了
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有效的调试

第四阶段：聚合分析

一旦所有会话数据和 facets 被收集，它们会被聚合并通过多个专门的分析提示词处理。

模型： Haiku 每个提示词最大输出 tokens： 8192

传递给分析提示词的数据

每个分析提示词接收聚合统计数据：

{
  "sessions": "<总会话数>",
  "analyzed": "<有 facets 的会话数>",
  "date_range": { "start": "", "end": "" },
  "messages": "<总消息数>",
  "hours": "<总持续时长（小时）>",
  "commits": "<git commits 数>",
  "top_tools": "[使用最多的 8 个工具]",
  "top_goals": "[最多的 8 个目标类别]",
  "outcomes": { "结果分布" },
  "satisfaction": { "满意度分布" },
  "friction": { "摩擦类型计数" },
  "success": { "成功类别计数" },
  "languages": { "语言使用计数" }
}

加上文本摘要：

  • SESSION SUMMARIES： 最多 50 个简要摘要
  • FRICTION DETAILS： 最多 20 个来自 facets 的摩擦详情
  • USER INSTRUCTIONS TO CLAUDE： 最多 15 条用户重复给 Claude 的指令

4.1 项目领域分析

Analyze this Claude Code usage data and identify project areas.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "areas": [
    {
      "name": "Area name",
      "session_count": N,
      "description": "2-3 sentences about what was worked on and how Claude Code was used."
    }
  ]
}

Include 4-5 areas. Skip internal CC operations.

4.2 交互风格分析

Analyze this Claude Code usage data and describe the user's interaction style.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "narrative": "2-3 paragraphs analyzing HOW the user interacts with Claude Code.
               Use second person 'you'. Describe patterns: iterate quickly vs
               detailed upfront specs? Interrupt often or let Claude run?
               Include specific examples. Use **bold** for key insights.",
  "key_pattern": "One sentence summary of most distinctive interaction style"
}

4.3 什么工作得好

Analyze this Claude Code usage data and identify what's working well for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence of context",
  "impressive_workflows": [
    {
      "title": "Short title (3-6 words)",
      "description": "2-3 sentences describing the impressive workflow or approach.
                      Use 'you' not 'the user'."
    }
  ]
}

Include 3 impressive workflows.

4.4 摩擦分析

Analyze this Claude Code usage data and identify friction points for this user.
Use second person ("you").

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence summarizing friction patterns",
  "categories": [
    {
      "category": "Concrete category name",
      "description": "1-2 sentences explaining this category and what could be
                      done differently. Use 'you' not 'the user'.",
      "examples": ["Specific example with consequence", "Another example"]
    }
  ]
}

Include 3 friction categories with 2 examples each.

4.5 建议与改进

这是最长的提示词，提供可操作的建议：

Analyze this Claude Code usage data and suggest improvements.

## CC FEATURES REFERENCE (pick from these for features_to_try):

1. **MCP Servers**: Connect Claude to external tools, databases, and APIs via
   Model Context Protocol.
   - How to use: Run `claude mcp add <server-name> -- <command>`
   - Good for: database queries, Slack integration, GitHub issue lookup,
     connecting to internal APIs

2. **Custom Skills**: Reusable prompts you define as markdown files that run
   with a single /command.
   - How to use: Create `.claude/skills/commit/SKILL.md` with instructions.
     Then type `/commit` to run it.
   - Good for: repetitive workflows - /commit, /review, /test, /deploy, /pr,
     or complex multi-step workflows

3. **Hooks**: Shell commands that auto-run at specific lifecycle events.
   - How to use: Add to `.claude/settings.json` under "hooks" key.
   - Good for: auto-formatting code, running type checks, enforcing conventions

4. **Headless Mode**: Run Claude non-interactively from scripts and CI/CD.
   - How to use: `claude -p "fix lint errors" --allowedTools "Edit,Read,Bash"`
   - Good for: CI/CD integration, batch code fixes, automated reviews

5. **Task Agents**: Claude spawns focused sub-agents for complex exploration
   or parallel work.
   - How to use: Claude auto-invokes when helpful, or ask "use an agent to explore X"
   - Good for: codebase exploration, understanding complex systems

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "claude_md_additions": [
    {
      "addition": "A specific line or block to add to CLAUDE.md based on workflow
                   patterns. E.g., 'Always run tests after modifying auth-related files'",
      "why": "1 sentence explaining why this would help based on actual sessions",
      "prompt_scaffold": "Instructions for where to add this in CLAUDE.md.
                          E.g., 'Add under ## Testing section'"
    }
  ],
  "features_to_try": [
    {
      "feature": "Feature name from CC FEATURES REFERENCE above",
      "one_liner": "What it does",
      "why_for_you": "Why this would help YOU based on your sessions",
      "example_code": "Actual command or config to copy"
    }
  ],
  "usage_patterns": [
    {
      "title": "Short title",
      "suggestion": "1-2 sentence summary",
      "detail": "3-4 sentences explaining how this applies to YOUR work",
      "copyable_prompt": "A specific prompt to copy and try"
    }
  ]
}

IMPORTANT for claude_md_additions: PRIORITIZE instructions that appear MULTIPLE TIMES
in the user data. If user told Claude the same thing in 2+ sessions (e.g.,
'always run tests', 'use TypeScript'), that's a PRIME candidate - they shouldn't
have to repeat themselves.

IMPORTANT for features_to_try: Pick 2-3 from the CC FEATURES REFERENCE above.
Include 2-3 items for each category.

4.6 未来展望（未来机会）

Analyze this Claude Code usage data and identify future opportunities.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "intro": "1 sentence about evolving AI-assisted development",
  "opportunities": [
    {
      "title": "Short title (4-8 words)",
      "whats_possible": "2-3 ambitious sentences about autonomous workflows",
      "how_to_try": "1-2 sentences mentioning relevant tooling",
      "copyable_prompt": "Detailed prompt to try"
    }
  ]
}

Include 3 opportunities. Think BIG - autonomous workflows, parallel agents,
iterating against tests.

4.7 趣味结尾（难忘时刻）

Analyze this Claude Code usage data and find a memorable moment.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "headline": "A memorable QUALITATIVE moment from the transcripts - not a statistic.
               Something human, funny, or surprising.",
  "detail": "Brief context about when/where this happened"
}

Find something genuinely interesting or amusing from the session summaries.

第五阶段：概览摘要

最后一次 LLM 调用会生成一个执行摘要，将所有内容串联起来。这个提示词接收之前生成的所有洞察作为上下文。

概览提示词

You're writing an "At a Glance" summary for a Claude Code usage insights report
for Claude Code users. The goal is to help them understand their usage and
improve how they can use Claude better, especially as models improve.

Use this 4-part structure:

1. **What's working** - What is the user's unique style of interacting with Claude
   and what are some impactful things they've done? You can include one or two
   details, but keep it high level since things might not be fresh in the user's
   memory. Don't be fluffy or overly complimentary. Also, don't focus on the
   tool calls they use.

2. **What's hindering you** - Split into (a) Claude's fault (misunderstandings,
   wrong approaches, bugs) and (b) user-side friction (not providing enough
   context, environment issues -- ideally more general than just one project).
   Be honest but constructive.

3. **Quick wins to try** - Specific Claude Code features they could try from the
   examples below, or a workflow technique if you think it's really compelling.
   (Avoid stuff like "Ask Claude to confirm before taking actions" or "Type out
   more context up front" which are less compelling.)

4. **Ambitious workflows for better models** - As we move to much more capable
   models over the next 3-6 months, what should they prepare for? What workflows
   that seem impossible now will become possible? Draw from the appropriate
   section below.

Keep each section to 2-3 not-too-long sentences. Don't overwhelm the user.
Don't mention specific numerical stats or underlined_categories from the
session data below. Use a coaching tone.

RESPOND WITH ONLY A VALID JSON OBJECT:
{
  "whats_working": "(refer to instructions above)",
  "whats_hindering": "(refer to instructions above)",
  "quick_wins": "(refer to instructions above)",
  "ambitious_workflows": "(refer to instructions above)"
}

SESSION DATA:
<aggregated statistics JSON>

## Project Areas (what user works on)
<project_areas results>

## Big Wins (impressive accomplishments)
<what_works results>

## Friction Categories (where things go wrong)
<friction_analysis results>

## Features to Try
<suggestions.features_to_try results>

## Usage Patterns to Adopt
<suggestions.usage_patterns results>

## On the Horizon (ambitious workflows for better models)
<on_the_horizon results>

第六阶段：报告生成

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

统计仪表板：

  • 总会话数、消息数、持续时间、tokens
  • Git commits 和 pushes
  • 活跃天数和连续使用天数
  • 峰值活动时段

可视化：

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

叙述部分：

  • 项目领域及描述
  • 交互风格分析
  • 什么工作得好（令人印象深刻的工作流程）
  • 摩擦分析及具体示例
  • CLAUDE.md 添加建议
  • 功能探索建议
  • 未来展望机会
  • 趣味难忘时刻

流水线伪代码

以下是各阶段的连接方式：

function generateInsights():
    // Stage 1: Load and filter sessions
    sessions = loadSessionLogs("~/.claude/projects/")
    sessions = sessions.filter(s =>
        !isAgentSession(s) &&
        !isInternalSession(s) &&
        s.userMessageCount >= 2 &&
        s.durationMinutes >= 1
    )

    // Extract metadata from each session
    metadata = sessions.map(extractMetadata)

    // Stage 2 & 3: Extract facets (with caching)
    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])

    // Stage 4: Aggregate and analyze
    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)

    // Stage 5: Generate executive summary
    insights.at_a_glance = callLLM(AT_A_GLANCE_PROMPT, aggregated + insights)

    // Stage 6: Render HTML report
    html = renderReport(aggregated, insights)
    saveFile("~/.claude/usage-data/report.html", html)

    return insights

数据存储

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

Facets 按会话缓存，因此多次运行 /insights 只会分析新会话。

技术细节

设置值
模型Haiku
每个提示词最大 tokens8192
每次运行分析的会话数最多 50 个新会话
转录大小限制30,000 字符
摘要分块大小25,000 字符

隐私考虑

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

Facet 提取关注的是你交互中的模式，而不是你代码的内容：

  • 你请求什么类型的任务
  • 你如何回应 Claude 的输出
  • 工作流程中哪里出现摩擦
  • 你使用哪些工具和功能

获得更好洞察的技巧

  1. 定期使用 Claude Code - 更多会话 = 更丰富的分析
  2. 给予反馈 - 说"谢谢"或"那不对"，这样满意度可以被追踪
  3. 不要过度过滤自己 - 自然的使用模式会揭示最有用的洞察
  4. 定期运行 - 每月检查一次，看看你的模式如何演变
avatar
文章
阅读
粉丝