How /insights turned repeated mistakes into CLAUDE.md rules, reusable Skills, and evidence-driven agent workflows
I no longer use Claude Code only to complete functions or fix isolated bugs.
Over the past few months, I have used it across Next.js and TypeScript product work, Swift and iOS release preparation, localization, payments, production debugging, open-source maintenance, and technical writing.
The tasks became more ambitious, but one problem became harder to see: I remembered why individual sessions succeeded or failed, yet I could not identify the patterns across dozens of them.
Then I ran:
/insights
Claude Code analyzed 178 of my 205 sessions, covering 1,412 messages across 43 days, from May 26 to July 15, 2026.
The report did not write any product code. It did something more useful: it showed me how I work with coding agents, where the collaboration repeatedly breaks down, and which temporary corrections should become permanent engineering rules.
The main value of /insights is not another usage dashboard. It is turning scattered session history into a workflow you can change and later verify.
What Claude Code Insights actually is
/insights is a built-in Claude Code command. Anthropic describes it as a way to generate a report that analyzes your sessions, including project areas, interaction patterns, and friction points.
In practice, my report tried to answer questions such as:
- What kinds of projects and tasks do I use Claude Code for?
- Do I ask it to debug, implement, review, or write?
- How do I frame requests and approve changes?
- Which collaboration patterns tend to produce strong outcomes?
- Which mistakes, tool failures, and incorrect assumptions keep returning?
- Which preferences belong in
CLAUDE.md? - Which repeated procedures should become Skills, Hooks, or agent workflows?
That makes Insights closer to an engineering retrospective about the human-agent system than a code-quality scanner.
It is also different from a team analytics dashboard. Analytics measures adoption, accepted lines of code, activity, and cost. Insights examines the behavior inside your sessions.
This distinction matters because some parts of the report are facts, while others are model-generated interpretations. “1,412 messages” is a reported count. “You interrogate before you authorize” is a behavioral summary. A claim that this pattern explains a higher satisfaction rate is an inference, not an audited conclusion.
Treating all three as equally certain would be a mistake.
The pattern it found in my work
The report described my default style as “interrogate first, authorize second.”
I rarely begin with “change the code.” I usually start with a diagnostic question:
- Why is the system deletion dialog using Chinese?
- Why can users select only the monthly plan?
- Why does this navigation transition look wrong?
- Is this CTA actually helping the page?
Only after Claude Code explains the root cause and shows evidence do I tell it to implement the fix.
The tool data supported that description: my use of Bash and Read was much higher than Write. I spent more effort investigating and verifying than generating new code.
That approach led to some of my best sessions. Simulator recordings exposed a first-frame navigation issue. Controlled experiments clarified an iOS system-language behavior. Browser screenshots revealed layout failures. curl and GitHub API calls replaced plausible explanations with observable evidence.
But the report also found the weakness: I had never fully encoded this method into the system.
Requirements such as “always run type checking,” “show a real screenshot for UI work,” and “verify platform behavior with a controlled experiment” still lived mostly in my head. I kept repeating them in new sessions.
Before Insights, I interpreted that as “Claude misunderstood this task.” After Insights, I saw a different problem: the collaboration contract had never been made persistent.
Failure pattern 1: a small fix becomes a refactor
One request was supposed to change four localized strings. Claude Code expanded it into a refactor of two switch blocks with twelve cases.
The code was not necessarily invalid. The direction and scope were wrong.
Another request asked for an annual payment option. Claude initially implemented a deep link, but I wanted an explicit annual-plan button. The first approach had to be rejected and rolled back.
Insights grouped these incidents as scope drift. My current approval gate for cross-file work is:
Before writing code, list the exact files you would change, what would change
in each file, and every user-visible behavior change. Wait for me to say “go.”
If the work touches more than five files, provide two viable approaches and
explain the trade-offs.
Implement only what I explicitly requested. If you notice adjacent warnings,
refactoring opportunities, or alternative solutions, list them separately and
wait for approval instead of implementing them.
This prompt does not make the model more intelligent. It adds a cheap decision point before an expensive diff exists.
Failure pattern 2: the first plausible explanation wins
While debugging a GitHub OAuth 400 error, one investigation path blamed the local proxy. Later evidence pointed to the Supabase provider configuration.
This is a familiar debugging failure. Once the first explanation sounds plausible, every subsequent command starts trying to confirm it instead of falsify it.
For problems that cross application code, configuration, infrastructure, and local tooling, I now prefer mutually exclusive hypotheses:
Use three parallel agents to investigate the GitHub OAuth 400 error.
Agent 1: inspect the application code and callback route.
Agent 2: call the Supabase auth endpoint directly with curl.
Agent 3: inspect the network and proxy path.
Each agent must report only its conclusion, the exact commands it ran, and the
raw evidence. Do not propose fixes yet. After all evidence is available, choose
the smallest fix that explains the observations.
Parallelism is not the goal. Killing incorrect branches quickly is the goal.
Each agent should own one hypothesis and have a clear falsification condition. Without that structure, “use multiple agents” can simply produce several confident opinions at once.
Failure pattern 3: reasoning replaces reproduction
My most valuable debugging sessions did not stop at reading code.
For UI and platform behavior, the evidence often existed outside the source files:
- A simulator recording revealed the first expanded frame of a navigation bar.
- A controlled simulator experiment clarified the language used by an iOS system dialog.
- A real HTTP response showed whether an upstream service was failing.
I converted that lesson into a reusable instruction:
Do not infer the cause yet. Reproduce the problem first.
Record the simulator, capture a browser screenshot, or call the endpoint with
curl to prove that the bug exists. Report exactly what you observed, then
propose a fix.
After the fix, repeat the same reproduction and show the before-and-after
evidence.
This moves verification from the end of the task to the entrance condition for root-cause analysis.
Failure pattern 4: repeated work never becomes a system
Across several sessions, I repeatedly performed the same App Store release checks:
- permission-purpose strings;
- hosted Terms, Privacy, and EULA URLs;
- hard-coded prices in paywalls;
- localization completeness across
.lprojfiles; - app icon assets;
- version and build-number increments;
- multilingual release notes based on the real Git diff.
Explaining this checklist from scratch every time wastes context and increases the chance of omission.
The report suggested converting it into a reusable release-audit Skill. The important improvement is not fewer keystrokes. It is running the same release gates every time and receiving evidence in a consistent format.
Where each Insight should go
Not every recommendation belongs in CLAUDE.md.
| Kind of recommendation | Best home | Example |
|---|---|---|
| Stable rule relevant to most sessions | CLAUDE.md |
Run type checking and tests before reporting completion |
| Repeatable multi-step procedure | Skill | App Store release audit |
| Deterministic action after an event | Hook | Run type checking after file edits |
| Independent investigation with isolated context | Subagent | Test code, configuration, upstream, and environment hypotheses |
This separation follows the roles described in Anthropic’s Claude Code extension documentation: CLAUDE.md supplies persistent context, Skills package reusable workflows, Hooks respond to lifecycle events, and Subagents run specialized loops in separate contexts.
Putting everything into one giant instruction file would create a different problem: more context, weaker relevance, and less predictable behavior.
What changed before and after Insights
There is an important evidence boundary here.
My material contains detailed evidence from the sessions before I adopted these recommendations. It also contains the report and the workflows I derived from it. It does not yet contain several weeks of post-adoption data.
I therefore cannot honestly claim that Insights has already reduced my rework by a certain percentage or saved a specific number of hours.
What has changed is concrete but narrower:
- A vague feeling about scope drift became an explicit approval rule.
- A wrong proxy hypothesis became a falsification-first debugging workflow.
- Repeated preferences became candidates for
CLAUDE.md. - A scattered release process became a Skill specification.
- Long tasks that previously died with the session now have staged checkpoints and written state.
The durable engineering effects still need to be measured.
In the next cycle, I can compare unrelated diff size, rollback frequency, repeated instruction count, evidence attached to root-cause claims, and recovery cost after interrupted sessions.
That is a more defensible before-and-after story than turning recommendations into fictional results.
A practical way to use /insights
The command is simple:
cd /path/to/your/project
claude
Then run:
/insights
The useful work begins after the report appears:
- Check the sample. Confirm the number of sessions and the time range. A few sessions can make an accident look like a habit.
- Read friction before praise. The flattering sections are easy to accept; recurring failures are more actionable.
- Separate counts from interpretations. Label what is measured, what is summarized, and what is inferred.
- Choose one to three changes. Do not redesign your entire agent workflow in one pass.
-
Put each change in the right mechanism. Use
CLAUDE.md, a Skill, a Hook, or a Subagent deliberately. - Define a verification metric. Decide what would prove that the change helped.
- Run Insights again later. Treat the first report as a baseline, not a verdict.
For long-running work, I would add one more rule: write findings, decisions, remaining tasks, and verification output to a file while the work is happening. Several of my sessions were interrupted by usage limits, output limits, or terminated background processes. A saved checkpoint makes interruption recoverable.
Limits worth keeping in mind
Insights can analyze what happened in the recorded sessions. It cannot automatically prove that the business outcome succeeded.
It may notice that you run tests frequently, but it cannot replace an audit of test quality. It may recommend parallel agents, but parallelism costs resources and is a poor fit for work with tight sequential dependencies.
Its interpretations can also be wrong. A report should generate hypotheses about your workflow, not become an unquestionable source of truth.
Finally, review the report before sharing it. Session-derived reports and screenshots may expose project names, file paths, customer information, endpoints, tokens, account details, or unreleased products.
The real benefit
The most useful sentence in my report was not that I was “good at debugging.” It was the implication behind the evidence: I had developed a repeatable way of working with coding agents, but I had not yet encoded it into a system the tools could execute consistently.
That is where /insights becomes valuable.
It turns “Claude sometimes goes off track” into named failure modes. It turns repeated corrections into persistent rules. It turns recurring tasks into reusable workflows. And it gives you a baseline for checking whether the next version of your process is actually better.
Generate the report once for awareness. Run it again later for evidence.
Top comments (1)
The facts-vs-inferences split earns its place - most session retros never separate the two. On the 27 skipped sessions: they are probably not random. If those are crashed or abandoned sessions, that is exactly where the worst collaboration failures live, which would make the corpus /insights sees survivorship-biased toward sessions that at least ran to completion. I'd spot-check a few excluded ones by hand before trusting the pattern summaries.
On the encode-into-CLAUDE.md step: I would encode one rule per week, not the whole retro at once. Each rule you add is a permanent context cost on every future session, and the only way to know a rule earns that cost is to watch whether the correction it replaces actually stops appearing in transcripts. Batch-adding ten rules gives you a bloated CLAUDE.md and no signal about which of the ten did the work.