Stop Guessing. Run `/insights`.

Most people use Claude Code like a fast typist: prompt, wait, fix, repeat. It works until it does not. You start seeing the same patterns. Bugs that look fixed but are not. Debugging loops that go nowhere. Small mistakes that quietly cost 20 minutes at a time.

The problem isn't Claude. It's how we work with it.

You're not being observed. You're being reflected.

/insights doesn't run in real time. It doesn't interrupt your workflow or fix anything for you. You run it and it looks back. It analyzes how you've been working and generates a report from your usage history.

It's not a mirror for your code. It's a mirror for your behavior.

What it showed me

The report did not reveal anything new. It surfaced things I was already doing but ignoring.

First, I was repeating myself. The same commit and push flow, over and over. Not a big problem on its own, but constant repetition adds friction. So I defined it once and stopped thinking about it.

Second, I was trusting too quickly. Claude would say "fixed" and I would move on. Except the fix did not converge or something else broke right after. The issue was not code quality. It was lack of verification. So I added a simple rule. If a fix fails after two attempts, stop. Explain what failed. Propose a different approach. Do not keep pushing the same idea.

Third, and more importantly, I was not controlling the agent enough. Claude was not making random mistakes. It was following my instructions exactly. A small typo from me led to changes in the wrong place. That was not a model problem. It was a control problem. So I added a guardrail. Before making any edit, it must state the exact file and component, reference the bug report and wait for confirmation.

That one change removed a surprising amount of wasted time.

The shift

The biggest change wasn't technical. It was mental.

Stop treating Claude like a helper. Start treating it like a system.

Guardrails that actually worked

These weren't theoretical. They came directly from patterns the report exposed.

First, confirm before changing anything. Instead of "fix this," require the agent to explain what it plans to change and where, then wait. This forces clarity before action and avoids silent misalignment.

Second, kill debugging loops early. Two failed attempts is enough. After that, the system should stop and propose alternatives instead of retrying the same path. This breaks the "try again" spiral that burns time without progress.

Third, make the agent verify its own work. Before, Claude would fix something and I would check it. Now, it fixes, runs validation and then reports. For example:

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx tsc --noEmit 2>&1 | head -20"
      }
    ]
  }
}

Errors surface immediately instead of later, when they're harder to trace.

Finally, remove repetition wherever possible. If you're doing something more than once, define it clearly:

Updated /push command:

# If upstream is already set:
git push

# If NO upstream is set:
git push -u origin <current-branch-name>

If push fails due to remote changes:

git pull --rebase
git push

Less typing. Fewer mistakes. Less context switching.

What /insights is really for

This isn't about optimization. It's about awareness. You think you're working one way, but the report shows what's actually happening.

It highlights where you waste time, where you trust too early, where your instructions break things and where your process is incomplete. It doesn't judge. It just makes the patterns visible.

How to use it

Keep it simple. Run /insights, ignore most of the output and focus on two or three patterns that matter. Add guardrails. Adjust how you work.

That's enough.

When to run it

Not daily. Not constantly. Run it after a phase of work, after a few weeks, or when things start to feel slow. It needs enough history to be useful.

Final thought

Most people try to improve outputs by refining prompts. Better wording. Better instructions. That helps, but it's not where the real leverage is.

The leverage comes from improving the system around the agent. /insights shows you where that system is weak. Fix that and everything else gets easier.