How I Stopped Getting Surprised by My Own Code

TL;DR

• I use OpenSpec for major feature work, paired with GitHub CLI wrapper skills that auto-create tickets as I go.
• Explore mode asks hard questions before any code is written, so the team shares a common understanding upfront.
• Proposal, design, and specs get written and read before development starts, so nothing gets discovered mid-build.
• End result: code review stops being full of surprises, because every decision was already discussed and documented.
• For context management in Claude Code, use /clear between unrelated tasks and /compact (run proactively at 40-50% usage) when staying on related work.
• OpenSpec-style workflows pair especially well with /clear after each task, since specs and tasks live on disk, not in the chat.

I want to talk about something that changed how I build features. It's not a fancy tool. It's a process. And once I started using it, my code quality stopped being a gamble.

Here's the short version. I use a framework called OpenSpec for any major feature work. I also wired up GitHub CLI with some small wrapper skills, so proper tickets get created as I go. Together, these two things fixed a problem I didn't even know I had.

Let me walk you through it.

The problem with jumping straight into code

I've always been a planner. Before I write code, I like to think it through. But once AI coding tools entered the picture, that discipline slipped. It was easy to just describe the feature and let the AI generate code. Planning happened in my head, if at all, not on paper.

That works, sort of. But it also means the AI is making dozens of small decisions on my behalf, with half the picture in its head. The effect isn't something I discover days later. It's immediate. The output looks fine at first glance, but then I'm going back and forth, correcting it, rewriting chunks of it. And just like that, the efficiency I was chasing is gone.

What OpenSpec changes

OpenSpec forces a different order of operations. Before any code gets written, there's an explore step. This step asks questions. A lot of questions. It grills you on edge cases, on what "done" actually means, on things you assumed were obvious but never said out loud.

This feels slow at first. It isn't. It's the fastest part of the whole process, because it happens before you've written a single line you might throw away.

By the end of explore mode, there's a shared understanding. Not just in my head. Written down.

Then comes the next part: proposal, design, specs. This is where the plan gets documented properly. I read it before development starts. Not skim it. Read it.

This one habit changes everything downstream. Because now, when I sit down to write code, I already know what I'm building and why. There's no mid-development detour where I realize I misunderstood the requirement. That conversation already happened, on paper, before the first commit.

Why this actually improves code quality

Here's the part I didn't expect. Code quality went up, and it wasn't because I suddenly got better at writing code. It's because nothing about the feature was a surprise anymore.

Every decision in the code traces back to something we discussed and wrote down first. The reviewer isn't guessing why I did something. I'm not guessing either, three days later, when I forget my own reasoning.

Good process beats good memory. Every time.

The GitHub CLI piece

The second half of my setup is smaller but just as useful. I configured GitHub CLI and built a few wrapper skills around it. Now, whenever I work on a feature, proper tickets get created automatically as part of the flow.

This means the paper trail isn't extra work I have to remember to do. It just happens. The proposal becomes a ticket. The ticket tracks the work. Nobody has to go dig through commit messages later to figure out what happened and why.

Managing context while you work

One more thing I learned along the way, and it matters if you're using something like Claude Code alongside this kind of workflow.

Claude Code resends your whole conversation history with every message you send. So the cost isn't just about what you're asking right now. It's about everything that came before it. A tiny question late in a long session can cost as much as your entire first task, just from re-sending all that old context.

There are two commands that help here: /clear and /compact.

/clear wipes the conversation completely. Fresh start. Use this when you're moving to work that has nothing to do with what you just did.

/compact summarizes the conversation instead of dropping it. Use this when you're still on related work, but the context window is getting big. And don't wait until it auto-fires near the limit. Run it earlier, somewhere around 40-50% context usage. The summary comes out better, because the model still remembers everything clearly at that point.

Here's the thing worth knowing: whatever lives only in the chat disappears on /clear. Whatever lives in files on disk, like your CLAUDE.md or your rule files, gets reloaded automatically. So durable project knowledge should live in those files, not in your memory of "I told Claude about this earlier."

Why this pairs so well with OpenSpec

This is where it clicks into place. In an OpenSpec-style setup, the specs and task breakdowns already live on disk. They're the source of truth, not the conversation.

That means clearing context after every task isn't risky here. It's actually a great fit, maybe even better than in a typical workflow. You lose nothing real, because the thing that matters was never sitting in the chat. It was already written down.

Small, well-scoped tasks make this even easier. There's less need for the AI to remember something from three tasks ago. And if a task only works because it remembers something that was never written anywhere, that's not a reason to keep the context around. That's a sign the spec itself is missing something. Fix the spec, not your memory of the conversation.

One catch to watch: re-reading your spec and task files on every clear has a cost too. Keep those files scoped tightly instead of dumping everything into one giant doc.

And if you've got a batch of small, related tasks that benefit from some shared short-term consistency, like matching style or sequencing, that's not worth writing into the spec. Use /compact between those instead of a full /clear.

The bottom line

Explore first. Write the plan down. Read it before you build. Let tickets get created as a side effect, not an afterthought. And manage your context around your files, not your memory.

None of this is complicated. It's just order. But that order is the whole reason my code review conversations got boring again, in the best possible way.