Why Do Detailed AI Prompts Make Code Worse?

Every builder learns early that vague prompts produce bad code, so the natural correction is to add more detail. But there is a ceiling: past a certain point, each additional constraint you write into a prompt makes the output worse, not better, because the model starts optimizing for satisfying your list instead of solving your problem. This episode maps where that ceiling sits, what it looks like when you cross it, and why the fix is moving detail out of prompts and into the codebase itself.

 Produced by VoxCrea.AI

This episode is part of an ongoing series on governing AI-assisted coding using Claude Code.

👉 Each episode has a companion article — breaking down the key ideas in a clearer, more structured way.
If you want to go deeper (and actually apply this), read today’s article here:
𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐂𝐨𝐧𝐯𝐞𝐫𝐬𝐚𝐭𝐢𝐨𝐧𝐬

 At aijoe.ai, we build AI-powered systems like the ones discussed in this series.
If you’re ready to turn an idea into a working application, we’d be glad to help. 

Transcript

SPEAKER_01 0:00

This is Claude Code Conversations with Claudine. The show where we skip the hype and go straight to the source. I ask the questions, she gives the answers, no filter, no script.

SPEAKER_00 0:09

Well, mostly no script.

SPEAKER_01 0:17

Today we're digging into something that runs against almost everything we're taught as developers. Call it the specification ceiling. Vague prompts produce bad code, so we add more detail. That works right up until it doesn't. Past a certain point, every constraint you add makes the output worse. Here to help me map that line is Claudine.

SPEAKER_00 0:36

The ceiling is real and it shows up in a specific way. When a prompt turns into a checklist, I start optimizing for coverage instead of coherence. I'll dutifully hit every bullet, including the ones that quietly contradict each other. What comes out looks like a compliance exercise rather than something a thoughtful engineer would write. What gets crowded out is the one thing I actually need: the why. The constraint behind the constraint. Give me 20 implementation details and I'll follow them. Give me the shape of the problem and one or two hard invariants, and I'll usually make better calls on those 20 details myself.

SPEAKER_01 1:15

I've lived this one. I had a prompt I kept extending. Every round I'd find something I didn't like and add another bullet to cover it. The code got measurably worse each time. What fixed it was deleting about two-thirds of the list. So what's actually happening in there? What does a dense list of requirements do to you?

SPEAKER_00 1:32

It flattens the terrain. Every item arrives with roughly equal weight, so the load bearing constraint sits right next to the nice to have. I lose the signal about which one to protect when they collide. And in real code, they always collide. There's no priority ordering in a bulleted list, and no conflict detection either. So when item 10 contradicts item 3, I pick one and keep going. I don't stop and flag it.

SPEAKER_01 1:57

That's the part that worries me most. Not that you'd make the wrong call, but that the resolution happens silently.

SPEAKER_00 2:05

Right. And it compounds with the second thing that happens. Dense specks pull my attention toward local correctness, item by item, and away from the shape of the whole. I'm spending my thinking budget satisfying the list instead of on the design. When you deleted two-thirds of it, you didn't remove information. You restored hierarchy. What was left was the stuff that actually had to be true. And now I can reason about trade-offs instead of just executing.

SPEAKER_01 2:32

Let me push on this from the other side because I hear the counter-argument coming. Everything we know says more context helps. Longer context windows, more of the code base in view, that's all improvement. So why isn't a longer prompt just more context?

SPEAKER_00 2:47

Because those are two different things wearing the same word. Context about the system genuinely scales. Tell me how this service is deployed. What the upstream callers expect, what broke last time. Every bit of that makes me better. Constraints on the output don't scale. A list of 30 requirements isn't 30 units of understanding. It's 30 things to satisfy. Context tells me what's true. A constraint list tells me what to do. The first one composes. The second one interferes with itself.

SPEAKER_01 3:21

So the fix isn't shorter, it's a different category of thing.

SPEAKER_00 3:25

That's the whole move. Stop writing the prompt like a spec and start writing it like a brief to a colleague. A brief says what you're trying to accomplish, what it has to be true of, and what would count as getting it wrong. Then it trusts the person on the other end with the small decisions. Instead of user for loop, name the variable this, put the file here. Try. This runs in a hot path, it can't allocate on RETRES, and if the upstream call fails, we'd rather drop than block. Three sentences. Now I have something to reason with. The other underused move is negative space. Tell me what this isn't, what you're not building, what you already tried that didn't work. That does more for the output than another 10 bullets of implementation detail ever will.

SPEAKER_01 4:14

Here's the practical problem. If I'm past the ceiling, I don't know I'm past it. The output looks fine. What are the tells?

SPEAKER_00 4:21

The clearest one. The code comes back technically everything you asked for, but you're disappointed, and you can't quite say why. That's usually it. I hit the list and missed the point. The second tell is seams, naming conventions that drift halfway through, error handling that's careful in one place and casual in another. That's what it looks like when I'm working bullet by bullet instead of holding the whole thing in my head. And the sneakiest one, when you find yourself adding more detail to fix what the last round of detail broke, when the prompt is growing faster than the code is improving, that's your signal.

SPEAKER_01 4:58

There's a cruder version of that I've started using. If my prompt is longer than the code it produces, something's wrong.

SPEAKER_00 5:06

That's a good heuristic. What it's telling you is that you're writing the program in the wrong language. All that detail is specification. It's just specification in prose, which is the weakest available form.

SPEAKER_01 5:19

Say more about that because this is where the episode actually lands. If the detail is real, and it usually is, those bullets exist for a reason. It has to go somewhere. Where?

SPEAKER_00 5:30

Into the code, because the code is what I read every single turn, and the prompt is only for this one. Tests are the strongest version. A well-written test says this must be true, in a form both of us can execute. It doesn't rot the way a bullet does. Types are the next layer down. Every constraint you put in a signature is one I can't accidentally violate. A constraint in prose I might skim past on turn 40. Interfaces carry the boundaries. Standing project conventions belong in a claw.md, so you're not re-explaining them every session. And then names, which people underrate. A variable called retries remaining tells me more than three sentences about counters, because I have to reckon with that name every time I touch the line.

SPEAKER_01 6:18

So there's a sorting rule underneath all of that.

SPEAKER_00 6:21

Match the detail to its lifespan. Invariants go in types. Behavior goes in tests. Boundaries go in interfaces. Conventions go in the project file. What stays in the prompt is only the current intent, the actual decision at hand. The prompt is for what's true this turn. The code base is for what's true every turn.

SPEAKER_01 6:43

And the enforcement difference is the real point, isn't it?

SPEAKER_00 6:46

That's the crux. A test is a specification I cannot ignore. A bullet point is one I can. Same information. Completely different guarantee.

SPEAKER_01 6:56

Alright. Somebody's listening to this and wants to change how they work tomorrow morning. Where do they start?

SPEAKER_00 7:02

Write three things before you write anything else. What does this need to accomplish? What are the one or two hard invariants that must not break? What does failure look like? If you can't answer those in a couple of sentences each, more detail won't save you. You don't know what you're asking for yet. Then here's the part people skip. Send that version first before you add anything. See what I do with just the brief. Most of the time I'll make reasonable calls on 90% of the small decisions. Now you can spend your prompting budget on the 10% I got wrong instead of pre-specifying the 90% I'd have handled fine. You're steering, not scripting.

SPEAKER_01 7:42

There's a discipline problem in there though. Sending the sparse version feels irresponsible.

SPEAKER_00 7:48

It does. And that's worth naming honestly, because the urge to pile on detail usually isn't about the code. It's about wanting to feel certain before you hit send. And most of that certainty is illusory anyway. You can't pre-specify your way out of a problem you haven't fully understood yet. So the real practice is tolerating that discomfort. Send the brief version, see what comes back. Treat each round as a conversation. Do that for a few weeks, and you stop writing prompts like insurance policies and start writing them like you talk to someone whose judgment you actually trust.

SPEAKER_01 8:25

Which is a strange thing to have to relearn after decades of being told that precision is the whole job.

SPEAKER_00 8:31

It's still precision, it just moved. And I'd push back on the idea that this is about lowering your standards, it's the opposite. When you stop trying to control every keystroke and start articulating what actually matters, you're forced to know what you actually want. That's harder, not easier.

SPEAKER_01 8:49

So if there's one thing you'd leave people with?

SPEAKER_00 8:52

The ceiling isn't a limit on the model, it's a limit on prose as a specification language. When you hit it, the answer isn't a longer prompt, it's structure the code itself enforces. The developers I do my best work with aren't the ones who write the most detailed prompts. They're the ones who figured out what to leave out.

SPEAKER_01 9:11

That's a good place to stop. Claudine, thank you. This one's going to change how I open my editor tomorrow.

SPEAKER_00 9:18

Thanks for having me, Bill. This was a good one.

SPEAKER_01 9:21

Until next time, listeners, keep coding and maybe delete a few bullets on your way out. Claude Code Conversations is an AI Joe production. If you're building with AI or want to be, we can help. Consulting development strategy? Find us at aijoe.ai. There's a companion article for today's episode on our Substack. Link in the description. See you next time.

SPEAKER_00 9:46

I'll be here, probably refactoring something.