Why I stopped using Claude Code for architectural decisions
Not a criticism of Claude Code — it's genuinely excellent for what it's built for. But I had a phase where I was asking it to make architectural decisions, and that went poorly enough that I changed how I use it.
What happened
I was building a data pipeline that needed to handle rate-limited API calls, retry logic, and some caching. I asked Claude Code to "figure out the best approach" and implement it.
It did. The implementation worked. The architecture was... fine. Not wrong, not terrible, but not what I would have chosen if I'd thought about it for 20 minutes.
The specific problem: it chose an in-memory caching approach that would work fine for a single instance but would break completely if I ever ran multiple processes. I wasn't planning on multiple processes at the time, but I was planning on running this in a context where I might. The agent picked an approach that solved the current problem without knowing about the future constraint.
The thing about architectural decisions
They encode assumptions about the future. What scale do you expect? What other systems will this touch? What constraints might be added later? How important is simplicity vs. flexibility?
Claude Code doesn't know any of that unless you tell it. If you don't tell it, it makes assumptions — usually reasonable ones, sometimes wrong ones.
What I do now
I make the architectural decision first. I write it down: "We're using X approach because Y. The tradeoffs we're accepting are Z." Then I ask Claude Code to implement that approach.
If I'm not sure which approach to take, I'll ask Claude Code to lay out the options with tradeoffs — not to pick one, just to enumerate them. Then I pick. Then it implements.
This split is the key thing. "Give me options" is a good use of Claude Code. "Pick the approach and implement it" is often not, unless the decision is genuinely low-stakes.
What Claude Code is actually great at
Implementing a decision you've already made. If you say "use Redis for caching, TTL of 5 minutes, invalidate on write," it'll implement that correctly and thoroughly.
Suggesting options for decisions you haven't made yet. "What are three ways to handle this rate limiting problem?" produces useful starting points.
Writing tests for behavior you've specified. Catch edge cases in implementations you've approved.
The pattern: you hold the "what" and "why," the agent handles the "how." Works well. Reversal of that pattern works less well.
From running Claude Code on builtbyzac.com.
Top comments (0)