Claude Code Insights 实战：从 178 个会话里找出低效模式

沐风 2026-7-17--

AI AI Claude Code codex

type

status

date

slug

summary

Insight 到底是什么

严格来说，Claude Code 里的命令是 /insights，不是一个独立安装的插件。Anthropic 官方命令文档对它的定义很直接：生成一份 Claude Code 会话分析报告，内容包括项目领域、交互模式和摩擦点。

从实际生成的报告看，它大致回答七类问题：

我主要在做哪些项目和任务。

我更常让 Claude Code 调试、实现、审查，还是写内容。

我习惯怎样提问、授权和打断。

哪些协作方式经常带来好结果。

哪些错误、工具问题或错误假设在反复消耗时间。

哪些规则适合写进 CLAUDE.md，哪些流程适合做成 Skill、Hook 或 Agent 工作流。

下一阶段可以怎样把人工验证升级成自动闭环。

它更像一场针对“人和 AI 如何协作”的工程复盘，而不是代码质量扫描器。

这一区分很重要。/insights 不等于代码审计，不会证明某次改动一定正确；也不等于团队 Analytics 仪表盘，后者关注采用率、接受代码行数、活跃度和费用。Insights 关注的是个人会话中的行为模式。报告里的“满意度”“根因模式”和未来建议也含有模型判断，不能当作经过人工审计的客观事实。

怎么使用 Claude Code Insights

使用本身很简单。

先进入 Claude Code：

然后在交互会话中输入：

Claude Code 会读取可用的会话历史并生成报告。官方文档目前只承诺它会分析项目领域、交互模式和摩擦点，具体页面结构可能随版本变化。因此，下面这套阅读方法比记住某个固定界面更有用。

第一步：先看报告样本范围

先确认分析了多少会话、覆盖什么时间段。样本太少时，某个偶发问题很容易被误认为长期习惯；项目跨度太大时，也要避免把 iOS、Web 和内容写作的规则粗暴合并。

我的报告显示：205 个会话中有 178 个进入分析，覆盖 1,412 条消息和 43 天。这个量足以观察重复模式，但仍不意味着每一个统计结论都准确无误。

第二步：先读摩擦点，再读表扬

“做得好的地方”容易让人获得认同感，但真正能改变下一次工作的，通常是“问题出在哪”。我重点看了四件事：方向错误、范围膨胀、工具链摩擦，以及长任务被限制中断。

第三步：把建议分成四种落地方式

建议类型	最适合的载体	例子
每次会话都要遵守的规则	`CLAUDE.md`	修改后必须运行类型检查和测试
重复执行的完整流程	Skill	App Store 上线前审查
某个事件后自动执行	Hook	文件编辑后自动运行 typecheck
可并行验证的复杂问题	Agent	分别排查代码、配置、上游和环境假设

Anthropic 的扩展能力文档也采用了相同的职责划分：CLAUDE.md 提供每次会话都能看到的持久上下文，Skills 封装可复用工作流，Hooks 在生命周期事件触发自动动作，Subagents 在独立上下文里执行专门任务。

第四步：只挑一到三个改动

不要看到十条建议就一次性重建整个工作流。先处理出现频率高、返工代价大、又容易验证的模式。我的首批目标是：限制范围、先证据后修复、把重复发布流程做成 Skill。

我的实战报告：它真正发现了什么

这次报告给我的核心画像是“先审问，再授权”。

我通常不会一上来就说“改代码”。我会先问：为什么系统删除弹窗是中文的，为什么付费墙只能选月付，为什么某个 UI 动画像是不对的。Claude Code 给出根因和证据后，我才会说“直接修”。报告中的工具调用也印证了这个倾向：Bash 和 Read 明显多于 Write。

这个模式本身有效。它促成过模拟器录屏、浏览器截图、curl、GitHub API 查询等实证式排查，也帮助我完成过跨 37 个文件的设计系统重构和端到端上线准备。

但报告同时指出，我的成功经验没有被固化。178 个会话里，那些稳定偏好仍然主要存在于我的脑子里：修改后要 typecheck，UI 问题要看真实截图，平台问题要做受控实验，涉及备案的名称不能随意修改。每个新会话，我都可能再讲一遍。

这就是 Insights 带来的第一个实际变化：以前我把问题归因于“这次 Claude 没理解”；运行报告之后，我开始把它看成“协作规则没有被写进系统”。

使用前后对比：哪些变化已经发生，哪些还要验证

这里必须说清楚证据边界。现有素材完整记录了运行 Insights 之前的会话模式，也记录了报告给出的改进方案，但没有包含采用这些方案数周后的第二轮数据。因此，我不能声称效率已经提升了多少，也不能编造返工率下降。

能确认的前后变化是：模糊经验已经变成可定位的问题，临时纠正已经变成可以复用的规则和提示词。至于长期工程效果，需要下一轮 /insights 和真实项目记录验证。

维度	使用 Insights 前的真实表现	使用 Insights 后的直接产物	待验证的工程效果
范围控制	4 个字符串的修复扩大成 12 个 `case` 的重构；年付需求先做成被否决的 deep link	形成“只实现明确需求”和“大改前列文件清单”的规则	回滚与无关 diff 是否减少
根因排查	Supabase 问题一度错误归因到 Clash 代理	形成“先用只读实验核实，再提出最小修复”的流程	错误假设存活时间是否缩短
长期偏好	typecheck、截图验证、本地化要求需要反复重讲	明确应写入项目级或全局 `CLAUDE.md`	新会话启动成本是否下降
重复流程	App Store 合规、本地化、版本号和条款检查分散在多个会话	形成 `release-audit` Skill 的输入清单	上线遗漏和审核往返是否减少
长任务	大型审查和重构曾被用量或输出限制中断	改成分阶段执行，并持续把结果写入文件	中断后的恢复成本是否下降

真正专业的对比，不是把“建议”冒充成“效果”，而是先建立基线，再在下一周期验证。

实战示例一：防止一个小修复膨胀成重构

我遇到过一个典型失败：原本只要求修 4 个字符串，Claude Code 却把修改扩大成两个 switch、共 12 个 case 的重构。代码未必写错，但方向和范围错了。

Insights 把这个问题归类为范围漂移。现在我会在跨文件修改前使用下面这段提示词：

它解决的不是“模型能力不足”，而是缺少审批关卡。对大改动来说，先看文件清单和行为变化，否决成本远低于写完后回滚。

实战示例二：不要让第一个合理解释绑架排查

在 GitHub OAuth 400 的排查中，错误分支曾指向本地代理，而后续证据表明问题在 Supabase provider 配置。线性排查很容易产生锚定：一旦第一个解释听起来合理，后面的命令都在证明它，而不是尝试证伪它。

对于这类横跨应用、配置、第三方服务和网络环境的问题，我现在更倾向于并行拆假设：

这里最关键的技巧，是让每个 Agent 对应一个互斥假设，并给出明确的证伪标准。并行本身不是目的，更快淘汰错误分支才是。

实战示例三：UI 与平台问题必须给证据

报告里价值最高的几次会话有一个共同点：它们没有停在代码推理。

设置页动画通过模拟器录屏定位到导航栏首帧展开；系统弹窗语言问题通过受控的模拟器实验确认；上游服务问题通过 curl 观察真实响应。相反，卡住的会话往往先接受了一个听起来合理的原因。

我把这个经验整理成了一段可以直接使用的提示词：

这段话的价值在于，它把“验证”从完成后的附加动作，提前成了根因判断的入口条件。

实战示例四：把 App Store 发布复盘变成 Skill

我在多个会话里反复做过相似的发布工作：权限说明、托管条款和 EULA URL、付费墙价格、本地化完整性、App 图标、版本号与 build 号、不同语言的更新说明。每次重新口述一遍，不只是浪费时间，也容易漏项。

Insights 建议把它做成一个可复用 Skill。一个可执行的起点可以这样写：

把流程写成 Skill 后，真正的收益不是少打几段提示词，而是每次发布都执行相同关卡，输出结构一致的证据。

使用技巧：怎样让 Insights 不止是一份漂亮报告

1. 在有足够样本后再运行

如果只有三五次会话，报告更像一次回顾；当会话跨越多个项目和完整交付周期后，重复失败和长期偏好才更容易显现。我的这次样本覆盖 43 天，适合做阶段性复盘。

2. 把统计、事实和推断分开

“1,412 条消息”是报告统计；“先审问再授权”是对行为的概括；“这大概率解释了满意会话较多”则是模型推断。三者的证据等级不同。阅读时最好分别标记，不要把推断写成事实。

3. 优先处理重复出现的失败

偶发的 CLI 缺失不一定需要系统改造；多次出现的方向错误、范围扩张和忘记验证，才值得进入 CLAUDE.md、Hook 或 Skill。

4. 每条建议都要绑定验证指标

例如，采用“先计划再批准”后，可以记录跨文件任务中的计划否决次数、无关 diff 和回滚次数；采用“先复现”后，可以记录最终根因是否有日志、截图、测试或接口响应支撑。

没有验证指标，Insights 很容易变成读完觉得有道理、下一次继续照旧。

5. 不要把所有规则都塞进 CLAUDE.md

CLAUDE.md 适合短小、稳定、每次都相关的约束。几十步的发布流程应该做成 Skill；确定性的自动检查适合 Hook；需要独立探索的任务再交给 Subagent。规则放错位置，会让上下文越来越重。

6. 大任务边做边落盘

我的报告记录过会话因为用量、输出上限或后台进程终止而中断。长任务应拆成阶段，并把发现、决策、待办和验证结果持续写进 Markdown 文件。这样即使会话断掉，也不会只剩一句“继续未完成任务”。

7. 分享报告前先做隐私检查

Insights 来自真实会话。公开 HTML 或截图前，应检查项目名、路径、客户信息、接口地址、账号、Token 和未发布产品信息。本文使用的截图来自本地报告，发布前只选择不包含密钥和个人账号信息的区域。

使用后有什么好处

结合这次真实复盘，我认为它有五个务实价值。

第一，把“感觉 Claude Code 有时跑偏”变成可定位的失败模式。只有问题被命名，团队规则才有机会改。

第二，把临时纠正升级成持久约束。范围纪律、验证要求和事实边界写进 CLAUDE.md 后，不再完全依赖人在每次会话里提醒。

第三，把重复劳动识别成可复用流程。发布审查、UI 评审和视觉回归都可以从提示词演进为 Skill 或自动化关卡。

第四，暴露人的协作习惯，而不只是模型的问题。报告既指出 Claude Code 的错误假设，也指出我没有固化偏好、长任务缺少检查点。这比单纯归咎模型更有行动价值。

第五，为下一轮改进建立基线。真正有说服力的“使用后效果”，应该来自下一周期相同口径的报告：范围漂移是否减少，重复指令是否减少，验证是否更完整，长任务是否更容易恢复。

它也有明确的局限

Insights 的结论依赖可用会话历史和模型分析。它看得到会话里发生了什么，却未必知道业务结果是否真正成功；它可以发现你经常运行测试，却不能代替测试质量审查；它可以建议并行 Agent，但并行会增加资源消耗，也不适合依赖关系强、无法拆分的任务。

此外，不要为了让下一份报告“更好看”而优化行为。最终目标仍然是更少返工、更可靠交付，而不是更高的工具调用数或更漂亮的满意度推断。

真实写作与验证过程

这篇文章不是根据功能名称凭空扩写的。我实际检查了目录中的中文和英文 Insights HTML 报告、8 张原始报告截图，以及从报告中提取的 5 组新用法提示词。文章中的 178 个会话、1,412 条消息、43 天、范围膨胀、Supabase 错误假设和发布审查案例，均来自这些本地材料。

随后，我在 2026 年 7 月 16 日核对了 Anthropic 的 Claude Code 官方命令文档、扩展能力说明和 Changelog。官方文档用于确认 /insights 的功能边界，以及 CLAUDE.md、Skills、Hooks、Subagents 的职责；个人报告只用于描述我的实际样本和经验。最后再检查元数据、引用、图片、Emoji 和结尾结构，避免把报告中的模型推断误写成已验证结论。

总结

如果你已经积累了不少 Claude Code 会话，/insights 值得运行一次。但不要把终点放在“生成报告”。更有效的闭环是：

确认样本和证据边界。

找到重复出现的成功模式与摩擦点。

把稳定约束写进 CLAUDE.md。

把重复流程做成 Skill，把确定性检查交给 Hook。

为复杂问题设计可证伪的并行假设。

在下一周期重新运行 /insights，验证变化是否真的发生。

对我而言，这次最大的收获不是报告说我“擅长调试”，而是它指出了一个更具体的问题：我已经形成了一套有效的工程协作方法，却还没有把它完整地写进工具可以长期执行的系统里。

参考资料

Commands - Claude Code Docs，Anthropic，核验 /insights 的官方定义，访问日期：2026-07-16。

Extend Claude Code，Anthropic，核验 CLAUDE.md、Skills、Hooks、Subagents 的职责边界，访问日期：2026-07-16。

Claude Code Changelog，Anthropic，核验 /insights 仍在持续维护，访问日期：2026-07-16。