I’ve Been Using Claude Code Wrong for Months!

After nearly few years of using Claude Code as my primary development tool, I can tell you, the way most developers use it is fundamentally broken — and the fix is simpler than you think.

The typical workflow goes like this:

type a prompt → Claude spits out code → fix the errors → repeat.

Some go further, chaining agentic loops and MCP servers. But for anything non-trivial, both approaches collapse into a mess of half-baked changes that break things in ways you won’t notice until production.

The root problem? Letting Claude write code before it — or you — truly understands the plan.

That’s the core principle. Separating thinking from typing is the most important discipline in AI-assisted development.

Here’s the full workflow:

The research.md file is your review surface. Read it. Verify Claude actually understood the system. Correct misunderstandings before any planning happens. Garbage in, garbage out.

If you've seen a clean implementation of something similar in an open-source repo, paste that code alongside your plan request. Claude works dramatically better from a concrete reference than designing from scratch.

After Claude writes the plan, open it in your editor and add inline notes directly into the document. These correct assumptions, reject bad approaches, inject domain knowledge, or add constraints Claude couldn't know about.

"The markdown file is a shared mutable state between you and Claude. You think at your own pace, annotate precisely where something is wrong, and re-engage without losing context."

Why does this work?

Three rounds of annotation can transform a generic plan into one that fits perfectly into your existing system. Claude excels at understanding code and proposing solutions — but it doesn't know your product priorities, your users' pain points, or the engineering trade-offs you're willing to make. The annotation cycle is how you inject that judgment.

By the time you say "implement it all," every decision has already been made and validated. Implementation should be boring. The creative work happened in the annotation cycles. Execution is just mechanics.