我和 Claude Code 聊了 605 句话，直到运行 /insights 才发现一直在做无用功

来源: 微信公众号（AI编程交流）
工具: Claude Code
发布平台: 程序员茄子（chenxutan.com）
标签: Claude Code, AI编程, insights, CLAUDE.md, 效率优化, 自定义Skills

引言

用 Claude Code 写代码这件事，最容易陷入一种错觉：感觉自己很熟练。

你打开终端、敲任务、看它跑、必要时纠正一下、commit、push。一天下来，几个功能上线，几个 bug 修掉，仿佛一切顺滑。

但如果有人问你：

• 过去一个月，你到底卡在了哪里？
• Claude 哪些地方一再跑偏？
• 你有多少次在做重复的指令？

大多数人答不上来。我也答不上来。

直到我在 Claude Code 里敲了 /insights。

/insights 是什么？

简单说，它是 Claude Code 自带的一个斜杠命令，会扫描你最近大约一个月的所有会话，生成一份 HTML 格式的"使用报告"。

它像一个一直坐在你旁边、看了你一个月工作的资深同事，给你做的一次复盘。

报告包含什么？

/insights 生成的报告会告诉你：

1. 你都在做什么类型的事 - 功能开发？Bug 修复？代码重构？文档编写？
2. 哪些事做得漂亮 - Claude 在哪些任务上表现优异
3. 哪些事在反复栽同一个跟头 - 你一再重复的错误模式
4. Claude 在哪些场合系统性地理解错你的意图 - 模型的能力边界
5. 最值钱的部分 - 根据你具体的工作模式：
   • 应该往 CLAUDE.md 里写什么
   • 应该建哪些自定义 Skills

我的 /insights 报告长什么样？

敲下 /insights 后，Claude Code 会生成一个 HTML 文件并在浏览器中打开。我的报告大概是这样的结构：

会话统计

总会话数：38 次
总对话轮次：605 轮
总 Token 消耗：约 1.2M tokens
平均会话长度：15.9 轮
最常用的命令：/fix, /commit, /review

高频任务分析

报告会用可视化图表展示你最高频的任务类型：

反复出现的错误模式

这是报告中最"打脸"的部分。它会列出：

模式 1：Python 环境混乱

• 出现次数：23 次
• 典型错误：直接用 python 或 pip 命令，而不是 venv 路径
• 结果：包装了错误的依赖版本，运行时报错

模式 2：API 分页参数不一致

• 出现次数：17 次
• 典型错误：有时用 limit/offset，有时用 page/page_size
• 结果：Claude 每次都要重新理解项目规范

模式 3：过度设计和范围蔓延

• 出现次数：14 次
• 典型错误：改一个小 bug，顺手重构了三个不相关的模块
• 结果：引入新 bug，review 耗时增加

模式 4：忘记 push

• 出现次数：31 次
• 典型错误：commit 完就结束会话，忘记 push
• 结果：代码只存在本地，CI/CD 没触发

报告给我的 4 条 CLAUDE.md 建议

最值钱的部分来了。/insights 根据我的高频错误模式，直接给出了针对性的 CLAUDE.md 建议：

1. 跑 Python 脚本和迁移时一律用 venv 路径

## Python 环境规范

- 所有 Python 脚本执行必须使用虚拟环境路径
- 正确示例：`./venv/bin/python script.py`
- 错误示例：`python script.py`（会用到系统 Python）
- 迁移命令也必须用 venv：`/venv/bin/python manage.py migrate`

为什么这条重要？ 我过去一个月里 23 次因为环境混乱导致的问题，全部可以通过这条规则避免。

2. API 端点统一用现有的 page/page_size 分页规范

## API 分页规范

- 统一使用 `page` + `page_size` 参数
- 禁止在项目中引入 `limit/offset` 或 `cursor` 等新分页方式
- 如需新增分页接口，参考现有 `/api/v1/users?page=1&page_size=20` 格式

为什么这条重要？ 17 次分页参数混乱，Claude 每次都要重新学习项目规范，浪费大量 token。

3. 改代码前先读现有代码理解约定

## 代码修改规范

- 修改任何代码前，必须先阅读相关模块至少 3 个文件
- 理解现有的命名约定、错误处理方式、日志格式
- 禁止"顺手重构"不相关的代码
- 修改范围严格限制在任务描述内，不得主动扩大范围

为什么这条重要？ 14 次过度设计，每次都引入了新 bug，review 时间增加 2-3 倍。

4. 改完代码默认执行 git add -A && git commit && git push

## Git 工作流

- 代码修改完成后，默认执行：`git add -A && git commit -m "描述" && git push`
- 除非用户明确说"先不 push"或"仅 commit"
- commit message 遵循 Conventional Commits 规范
- push 后检查 CI/CD 状态

为什么这条重要？ 31 次忘记 push，导致代码积压、CI 没跑、协作阻塞。

报告建议的自定义 Skills

/insights 不仅给出 CLAUDE.md 建议，还建议我创建几个自定义 Skills：

1. /push skill

建议理由：31 次会话都在做 commit + push

Skill 内容：

# /push Skill

当用户说"完成"或"搞定"时，自动执行：

1. git add -A
2. git status（展示给用户确认）
3. git commit -m "<由 Claude 生成的描述>"
4. git push
5. 检查远程 CI/CD 状态

如果用户说"提交到本地"，则只执行 1-3 步。

成本：创建不到一分钟
收益：接下来 30 次会话，每次省 10 秒 = 5 分钟

2. /review skill

建议理由：代码审查会话占比 15%，且成功率高达 92%

Skill 内容：

# /review Skill

对用户指定的代码进行深度审查：

1. 读取代码文件
2. 检查：
   - 是否符合项目规范（参考 CLAUDE.md）
   - 是否有明显的 bug 或边界问题
   - 是否有过度设计或范围蔓延
   - 测试覆盖率是否充足
3. 生成审查报告（markdown 格式）
4. 给出具体的修改建议

3. 用 hooks 在 commit 前自动跑校验

建议理由：很多 bug 都是基本问题，可以在 commit 前拦截

实现方式：

# .git/hooks/pre-commit
#!/bin/bash
python -m flake8 .
python -m pytest tests/

4. 用 headless mode 把跨多仓库的批量操作脚本化

建议理由：经常需要同时修改多个仓库的相似代码

怎么用好 /insights？

1. 把建议的 CLAUDE.md 条目真的复制进去

这是这条命令最违反直觉的地方——它给的建议不是泛泛的"你应该写好 CLAUDE.md"，而是基于你的真实犯错记录、按你的项目规范定制的具体语句。

不用就浪费了。

我花了 5 分钟，把那 4 条建议复制进 CLAUDE.md，立竿见影的效果：

• 第二天，Python 环境错误降为 0
• API 分页参数混乱降为 0
• 过度设计的情况减少了 80%

2. 报告里建议的自定义 Skills 一定要至少建一个试试

Skills 现在已经和自定义 slash commands 合并了，建一个 /push 的成本不到一分钟，但接下来的 30 次会话每次能省你 10 秒。

实际操作：

# 在 Claude Code 中
> /skill create push

# 按提示输入 skill 内容（可以直接从 /insights 报告中复制模板）
# 保存后，下次直接 /push 就能用

3. 每月跑一次 /insights

把它变成习惯，每个月月底跑一次，复盘这个月的工作模式，持续优化 CLAUDE.md 和 Skills。

我的实际效果

使用 /insights 前（过去一个月）

• 平均每个功能开发需要：18.5 轮对话
• Python 环境错误：23 次
• 分页参数混乱：17 次
• 忘记 push：31 次
• 过度设计导致返工：14 次

使用 /insights 后（最近一周）

• 平均每个功能开发需要：11.2 轮对话（减少 39%）
• Python 环境错误：0 次
• 分页参数混乱：0 次
• 忘记 push：1 次（第一次还没适应新流程）
• 过度设计导致返工：2 次（减少 86%）

时间节省：平均每天节省约 25 分钟，一个月就是 10 小时！

CLAUDE.md 最佳实践

通过 /insights 的复盘，我总结了几条 CLAUDE.md 的最佳实践：

1. 项目规范要具体，不要抽象

❌ 错误的写法：

# 代码规范
请遵循项目的代码规范。

✅ 正确的写法：

# 代码规范

## Python 环境
- 所有脚本必须用 `./venv/bin/python` 执行
- 禁止使用系统 `python` 或 `pip`

## API 设计
- 分页统一用 `page` + `page_size`
- 错误响应格式：`{"error": {"code": 400, "message": "..."}}`

## 命名约定
- 变量：snake_case
- 类：PascalCase
- 常量：UPPER_SNAKE_CASE
- 文件：kebab-case.py

2. 把高频错误写进去

/insights 报告里的"反复栽跟头"部分，每条都应该对应一条 CLAUDE.md 规则。

3. 定期更新

项目规范会变，CLAUDE.md 也要跟着变。每月跑一次 /insights，看看有没有新的错误模式需要补充。

自定义 Skills 创建指南

什么时候该建 Skill？

根据 /insights 的建议，以下情况适合建 Skill：

1. 高频重复任务：同一个操作你每次都要手动做（如 /push）
2. 多步骤流程：需要按顺序执行多个命令（如代码审查流程）
3. 项目特定操作：你的项目有特殊的部署、测试、发布流程

如何创建 Skill？

在 Claude Code 中：

> /skill create <skill-name>

# 按提示输入：
# - Skill 描述
# - 触发条件
# - 执行步骤
# - 注意事项

Skill 示例：/format-and-commit

# /format-and-commit Skill

## 描述
格式化代码并提交，适用于每次修改完代码后的标准化流程。

## 步骤
1. 运行格式化：`black . && isort .`
2. 运行 lint：`flake8 .`
3. 查看变更：`git diff`
4. 询问用户："是否提交？(y/n)"
5. 如果 y，执行：`git add -A && git commit -m "<描述>" && git push`

我们经常焦虑的事

我们经常焦虑 AI 进化太快、新功能学不过来。

但有时候，进化更慢的反而是我们自己的工作习惯。

/insights 这条命令的真正价值，是它把这件你不愿意主动复盘的事，做成了一份你不得不读完的报告。

为什么我们不愿意主动复盘？

1. 没有工具支持：以前只能靠记忆，很容易遗忘细节
2. 反馈周期太长：错误模式需要积累一段时间才能发现
3. 缺乏量化数据："感觉"自己很熟练，但没有数据支撑

/insights 解决了这三个问题：

• 自动扫描所有会话，无需手动记录
• 数据分析，模式识别，一个月的数据足够发现规律
• 量化展示：次数、占比、成功率、Token 消耗

其他 AI 编程助手有类似功能吗？

目前（2026年5月），类似的功能还比较少见：

Claude Code 的 /insights 是其差异化优势之一，体现了 Anthropic 对"AI 工具不仅要能干活，还要能帮用户成长"的理解。

小结

/insights 是 Claude Code 里最被低估的一个功能。

大多数人把它当成一个"花哨的报告生成器"，但实际上，它是提升 AI 编程效率的杠杆：

1. 发现问题：通过数据分析，找到你一再犯的错误模式
2. 给出方案：直接生成 CLAUDE.md 条目和 Skills 模板
3. 持续优化：每月跑一次，工作流越来越顺滑

关键要点：

• 把建议的 CLAUDE.md 条目真的复制进去
• 建议的自定义 Skills 至少建一个试试
• 把它变成习惯，每月跑一次

我们经常说"AI 让编程更高效"，但真正的效率提升，往往不在模型有多强，而在于我们用它用得有多聪明。

/insights 就是让我们变得更聪明的那面镜子。

本文首发于「程序员茄子」博客，原文链接：https://chenxutan.com