/insights 命令之一个AI教练的故事

⚠️ 版本说明 ：本文所讨论的 /insights 命令是指 Claude Code 在 v2.x 版本 中提供的 HTML 报告生成功能 ，其处理流程包含 7 个阶段 ：Session Collection、Metadata Extraction、Facet Extraction、Data Aggregation、Insight Generation、Suggestion Generation 和 HTML Rendering。本文使用的 claude-insights 命令行工具为 v1.4.3，相关最佳实践基于该版本。

想象一下，你是一位职业围棋选手，每天和AI对弈。一个月后，你的AI对手突然开口说：

"老兄，复盘一下你这一个月的落子习惯------你每次中盘战斗前都不看局部气数，我记录到17次类似错误。要不要我把纠正方案写下来，下次你自己就能注意到？"

这就是 Claude Code 的 /insights 命令。它不是普通的命令，而是藏在终端里的AI教练。

先看效果（新手实操指南）

在了解原理之前，不妨先亲手体验一下，整个流程仅需几步：

准备工作：

订阅 Claude Pro 或更高版本
确保 Claude Code 已安装并更新到最新版（npm install -g @anthropic-ai/claude-code）
至少有几周的使用历史------数据越丰富，洞察越精准

步骤一：运行命令

bash 复制代码

# 启动 Claude Code
claude

# 在 Claude Code 交互界面中输入
/insights

如果命令报错，用 Ctrl+C 关闭并重新打开 Claude Code 再试。

步骤二：获取报告。Claude 会扫描你近30天的使用记录，通常输出类似这样的过程信息：

text 复制代码

[OK] Analyzing 47 sessions from the last 30 days...
[OK] Extracting metadata and patterns...
[!!] 3 friction patterns detected
[OK] Generating personalized CLAUDE.md rules...
[>>] Building interactive HTML report...
[OK] Report saved to ~/.claude/usage-data/report.html

报告会自动在浏览器中打开。

步骤三：善用外部工具进一步挖掘 。如果你希望将洞察自动转化为可执行的配置，可以使用 claude-insights CLI 工具：

bash 复制代码

# 安装（全局安装）
npm install -g claude-insights

# 自动检测报告并直接应用到项目
claude-insights analyze --apply

# 或等待报告生成后再分析（适合配合 /insights 一起使用）
claude-insights analyze --wait --apply

这个工具会自动将报告中的摩擦点转化为 CLAUDE.md 规则和自定义技能。

步骤四：将建议写入 CLAUDE.md 。将报告中"Existing CC Features to Try"部分生成的建议复制到你的项目根目录下的 CLAUDE.md 文件中。CLAUDE.md 是 Claude Code 在每次会话启动时首先读取的文件，将其作为持久化的项目知识库。

步骤五（可选）：设置自定义技能 。如果报告建议了 Custom Skills，将对应的 YAML 格式的技能定义粘贴到 Claude Code 中并说 Set up this skill，Claude 会自动为你创建。之后用 / 加技能名即可一键触发。

💡 进阶技巧：

每月运行一次 /insights，随着你的编程习惯改善，Claude 会不断给出新的建议

如果某个项目近期让你困扰，可以单独在该项目内运行 /insights，获得项目专属的建议

使用 claude-insights diff 对比不同月份的报告，直观看到自己的进步

原理篇：七步揭秘一个指令如何洞察你的习惯

当你输入 /insights 时，背后是一套完整的七步数据分析流水线 ，融合了定量指标计算和定性语义分析。整个流程的完整时序图如下：

第一步：数据采集------时光穿梭机

Claude Code 会在 ~/.claude/projects/ 目录下默默记录所有会话 ，包含每一次对话的完整轨迹。执行 /insights 时，它会扫描近30天的日志，同时自动过滤掉一些噪声------比如内部子代理（agent-*）产生的会话、少于2条用户消息的短暂会话、以及持续时间不足1分钟的会话。

💡 技术小贴士 ：这些会话日志以 .jsonl 格式存储。每条会话记录保存了完整的消息流转、工具调用记录、文件变更等元信息，是你与AI交互的数字"脚印"。

第二步：元数据提取------数据解剖师

对于每个符合条件的会话，系统会提取出结构化的定量指标：

typescript 复制代码

// 伪代码示意：会话元数据结构
interface SessionMetadata {
  sessionId: string;
  startTimestamp: Date;
  duration: number;           // 会话持续时长
  messageCount: number;       // 消息总数
  tokenUsage: {
    input: number;
    output: number;
  };
  toolsUsed: string[];        // 调用了哪些工具
  programmingLanguages: string[];
  gitActivity: {
    commits: number;
    pushes: number;
  };
  linesOfCode: {
    added: number;
    removed: number;
  };
  filesModified: string[];
}

这是整套系统中最精妙的一步。单纯看指标远远不够------一个会话可能消息多、时间长、改了一堆文件，但这些并不能告诉你"用户是否真的满意"。

因此，系统会用一个轻量级 LLM 模型（Claude Haiku）对每一个会话做定性分析 ，评估：

用户情绪：用户在这个过程中是愉悦、焦躁，还是平静？
Agent 表现：Claude 自己给出了什么水平的回答？
挫败度：用户是否遭遇了反复试错或无效沟通？
目标达成度：会话的核心目标是否实现？

这些定性评估结果会被缓存在 ~/.claude/usage-data/facets/ 目录下。这也是为什么 /insights 第二次运行比第一次快很多 ------因为 facets 被缓存了，无需重新让 Haiku 逐会话分析。

💡 技术小贴士 ：facets 本质上是会话的语义特征向量，类似于给每个会话打了几个"情感标签"。这些标签是后续模式识别的基础。

第四步：数据聚合------融合的艺术

定量的元数据和定性的 facets 评估被合并到一个统一的数据集中。这一步的关键在于为每个会话建立多维度画像 ------既有冷冰冰的数字指标，也有温热的情绪标签。

python 复制代码

# 伪代码示意：数据聚合
aggregated_data = []
for session in sessions:
    # 从缓存或 Haiku 获取该会话的 facet
    facet = load_or_compute_facet(session.id)
    # 合并元数据与定性评估
    enriched_session = {
        **session.metadata,
        'sentiment': facet.user_sentiment,
        'performance': facet.agent_performance,
        'frustration': facet.frustration_level,
        'goal_achieved': facet.goal_achieved
    }
    aggregated_data.append(enriched_session)

第五步：洞察生成------找规律的艺术

当所有会话都成为带有情感标签的数据点之后，系统开始在跨会话维度 上寻找模式：

趋势分析：用户使用某类工具的频次是上升还是下降？
优势识别：哪些类型的任务总是顺利搞定？
问题领域：哪些场景反复出现挫败感？

第六步：建议生成------量身定做的教练

系统根据跨会话分析的结果，生成个性化的 CLAUDE.md 规则 。这些规则是基于你在多个会话中重复出现的指令模式 生成的，而不是通用的模板。

例如，如果你在多个会话中都说过"不要用 Tailwind 的默认颜色，用我们项目的主题变量"，系统会归纳出这样一条规则写入 CLAUDE.md：

text 复制代码

This project uses TypeScript with a custom shadcn/ui dark theme.
ALWAYS use the initialized theme tokens instead of arbitrary Tailwind color classes.

第七步：HTML 渲染------可视化的报告

所有洞察和建议被组装成一个交互式 HTML 报告，包含图表、可视化面板和可导航的章节。报告保存在 ~/.claude/usage-data/report.html，并自动在浏览器中打开。

报告内容详解

打开这份 HTML 报告，你会发现它被精心划分成以下几个核心板块：

1. What You Work On（你的工作全景）

以卡片形式展示你使用 Claude Code 的每一个项目，附带会话数量和工作摘要。同时还提供：你最常请求 Claude 做什么、Claude 调用了哪些工具、你主要使用的编程语言、会话类型分布等统计数据。

2. Impressive Things You Did（亮点回顾）

系统识别出你做得好的那些会话，总结出值得继续保持的优秀习惯。

3. Where Things Go Wrong（痛点分析）

这是报告中最有价值的部分。系统会列出反复出现的摩擦模式，比如：

Claude 忽略你的指令
Claude 产出有 bug 的代码
Claude 采用了错误的技术方案

每一个摩擦模式都会附带具体的会话示例，方便你定位问题。

4. Existing CC Features to Try（立即可用的优化方案）

针对痛点模式，系统会生成可直接复制到 CLAUDE.md 的规则 ，每条规则都附带了"为什么这条规则对你有用"的个性化解释。

5. New Ways to Use Claude Code（新技能推荐）

报告会基于你的使用习惯，建议你启用一些你还不知道的功能，比如：

自定义 Slash Commands
专用 Subagents
Claude Code Hooks

6. On The Horizon（进阶思考方向）

报告的最后部分，Claude 会提出一些关于"如何重新思考你与 AI 协作方式"的高级建议，帮助你从普通用户升级为真正的"AI 超级用户"。

最佳用法：从读报告到自动化落地

仅仅看报告是不够的。翻译摩擦模式为 CLAUDE.md 规则和自定义技能是繁琐的手工工作，大多数开发者会直接跳过这一步。以下是专业级的最佳实践：

🎯 最佳实践一：让建议自动化落地

使用 claude-insights CLI 工具将报告一键转化为可执行文件：

bash 复制代码

npx claude-insights analyze ~/.claude/usage-data/report.html --apply

这条命令会生成以下输出文件：

输出文件	内容说明
`insights-todo.md`	按优先级排列的任务清单，附带步骤、时间估算和预期改进效果
`CLAUDE.md-additions.md`	按模块（General/CSS/Testing/Debugging）组织好的可粘贴规则
`.claude/settings-insights.json`	从报告中提取的 Hook 配置
`.claude/skills/*.SKILL.md`	每个摩擦模式生成一个自定义技能文件，包含触发条件、执行步骤、规则和验证清单
`insights-README.md`	每个文件的放置位置指南

工具的内部实现采用三阶段流水线：

Parse ：使用 cheerio 库解析 HTML 报告，提取统计数据、项目领域、摩擦分类与示例、CLAUDE.md 建议及理由等结构化数据。
Analyze：对每个摩擦模式生成带 YAML frontmatter 的技能文件（触发条件来自实际摩擦示例）；用词汇重叠评分匹配摩擦模式与 CLAUDE.md 建议；交叉引用工作流模式生成建议启动提示；从具体失败示例构建验证清单；按影响程度生成优先级待办事项（摩擦派生任务为高优先级）。
Generate ：将输出文件写入指定目录，自动创建 .claude/skills/ 结构。

🎯 最佳实践二：持续追踪改进效果

bash 复制代码

# 每月运行一次，追踪变化
claude-insights history                    # 查看历史分析记录
claude-insights diff 2026-01-15 2026-02-15 # 对比两个月的改进

🎯 最佳实践三：团队级洞察聚合

bash 复制代码

# 合并团队成员的多个报告，识别共同的摩擦模式
claude-insights team report_alice.html report_bob.html -o ./team-output

🎯 最佳实践四：配合 Watch Mode 无缝工作流

在 Claude Code 中运行 /insights 的同时，在另一个终端窗口中运行：

bash 复制代码

claude-insights analyze --wait 600 --apply

这会让 claude-insights 等待报告生成完毕（最长 600 秒），然后自动分析并应用到项目。

🎯 最佳实践五：过滤误报

bash 复制代码

# 如果某个摩擦模式实际上是误报（比如你想保留的行为）
claude-insights annotate --false-positive "CSS Issues"
# 后续分析会将其过滤掉

🎯 最佳实践六：技能审计

claude-insights 从 v1.4 版本开始支持技能审计功能：

bash 复制代码

# 验证所有 SKILL.md 文件是否符合官方最佳实践
claude-insights skill audit

# 自动修复所有可修复的问题
claude-insights skill audit --fix

# 以 JSON 格式输出，方便集成到 CI 流程
claude-insights skill audit --json

🎯 最佳实践七：CLAUDE.md 是持续优化的核心

CLAUDE.md 是 Claude Code 在每次会话启动时首先读取的文件，它作为持久化的项目知识库，决定了 Claude 能否理解你的项目。2026 年的社区共识是：CLAUDE.md 已经不再是可选配置，它的重要性堪比 .gitignore。

务必定期更新 。将 /insights 生成的建议规则持续迭代进 CLAUDE.md，形成 "使用 → 复盘 → 优化 → 再使用" 的正向循环。

总结

环节	一句话概括
`/insights`	你的 AI 教练，帮你复盘过去 30 天与 AI 的协作模式
七步原理	采集→元数据→Facet定性→聚合→洞察→建议→HTML
报告价值	找痛点、定规则、学新招、升格局
落地工具	`claude-insights` 将报告一键转化为可执行的规则、技能和待办
最佳实践	自动化落地 + 持续追踪 + 团队聚合 + CLAUDE.md 迭代

下次当你输入 /insights 时，记住它不只是一个命令，而是你通往"AI 超级用户"的大门。一个优秀 AI 助手的进化速度，取决于你从它身上学到什么。这份报告不只是分析你，更是在帮你成为更好的开发者。

/insights 命令之一个AI教练的故事

先看效果（新手实操指南）

原理篇：七步揭秘一个指令如何洞察你的习惯

第一步：数据采集------时光穿梭机

第二步：元数据提取------数据解剖师

第三步：Facet 提取------AI的情绪分析师（核心）

第四步：数据聚合------融合的艺术

第五步：洞察生成------找规律的艺术

第六步：建议生成------量身定做的教练

第七步：HTML 渲染------可视化的报告

报告内容详解

1. What You Work On（你的工作全景）

2. Impressive Things You Did（亮点回顾）

3. Where Things Go Wrong（痛点分析）

4. Existing CC Features to Try（立即可用的优化方案）

5. New Ways to Use Claude Code（新技能推荐）

6. On The Horizon（进阶思考方向）

最佳用法：从读报告到自动化落地

🎯 最佳实践一：让建议自动化落地

🎯 最佳实践二：持续追踪改进效果

🎯 最佳实践三：团队级洞察聚合

🎯 最佳实践四：配合 Watch Mode 无缝工作流

🎯 最佳实践五：过滤误报

🎯 最佳实践六：技能审计

🎯 最佳实践七：CLAUDE.md 是持续优化的核心

总结