Your Claude Wrote a Spec. My Claude TLDR'd It.

I’m reading more markdown than code lately. That’s not an exaggeration. Between implementation plans, design specs, PR descriptions, and review comments, the volume of text flowing through my team has exploded — and most of it was written by an LLM.

Here’s how it works now. I ask Claude to write a spec. It produces two thousand words of detailed markdown, organized into sections I didn’t ask for, covering edge cases I haven’t thought about, making decisions I didn’t make. I skim it, maybe read the first couple paragraphs carefully, and submit it as a PR or paste it into a discussion. On the other end, my colleague’s Claude summarizes it and writes a response. That response comes back to me — another wall of text. My Claude summarizes that. Back and forth. Machines writing to machines, with humans in the middle pretending to be in the loop.

We’ve replaced conversations with document exchanges that nobody fully reads.

Volume

Claude thinks it’s being paid by the word. Ask it a simple question and you get five paragraphs with headers. Ask it to write a plan and you get an implementation guide covering error handling strategies you never discussed, logging approaches nobody agreed on, and deployment steps that don’t match how your team actually ships code.

That’s fine if you read it, edit it, and own it before sharing. Most people don’t.

I built a tool recently for our internal support team — it touched a bunch of systems and one of the things it did was submit credit card refunds. We have a very specific refund format that our data pipelines depend on to correlate refunds back to the original purchase. Pretty important. Claude invented the refund format. Just made one up, buried it on page twelve of a twenty-page implementation plan, and it looked plausible enough that nobody questioned it. We submitted test refunds with the invented format, and the result was broken data that our data team had to go clean up.

If I had actually read the spec — the whole spec — I would’ve checked the format with the data team before writing any code. But it was twenty pages. I read the parts I thought mattered and skimmed the rest. The format was in the rest.

So that’s the failure mode. Not that the AI is wrong (though it was). It’s that the AI is confidently detailed about things that haven’t been discussed, and that confidence is buried in so much text that you miss it.

Obligation

Every line your LLM generates creates an obligation for someone else to read it. When you paste Claude’s output into a PR description or a Slack thread, you’re implicitly saying “I read this and I’m putting my name on it.” A human writing a spec keeps it short because writing is work. Claude doesn’t have that constraint — it fills the page because filling the page is free.

Your reviewer has to parse all of it. Your teammate has to figure out which parts you actually decided and which parts Claude hallucinated into the gaps. Your tech lead has to figure out whether the architectural choices on page seven reflect real decisions or plausible-sounding defaults. That’s a lot of work to put on someone, especially when you didn’t do it yourself.

I’ve watched people paste Claude’s responses directly into review comments without fully reading them. I get it — it’s a rational response to being overwhelmed by the volume. But now we’ve got AI talking to AI through a chain of humans who are mostly just passing messages along. That’s not collaboration. That’s a game of telephone where nobody’s listening.

(I’m aware of the irony of writing a blog post about too much text. I thought about making this one a haiku but I don’t think “Claude writes too much / I didn’t read the spec though / data team is mad” would land the same way.)

What I Do Instead

I still use Claude for a lot of this work. But I’ve changed how.

Keep it short. I tell Claude up front: three paragraphs max, no headers, no implementation details I haven’t discussed yet. If I need a spec, I write the decisions myself and let Claude fill in the syntax. Not the other way around.

Replace details with questions. When Claude wants to describe how error handling should work, I tell it to replace that section with a question: “How should we handle failures here?” That forces the discussion to happen between humans instead of being pre-answered by a model that doesn’t know our codebase’s history. Keep in mind — Claude will confidently fill every gap you leave open. If you don’t want it making decisions, you have to explicitly tell it not to.

Set scope before generating. I tell Claude what’s in scope and what isn’t before asking it to produce text. “Write a plan for the API changes only. Don’t cover deployment, monitoring, or testing — we’ll discuss those separately.” Otherwise you get the twenty-page plan and the invented refund format.

Read everything before submitting. This sounds obvious. It wasn’t, for a while — the whole point of the tool is speed, and reading a two-page spec carefully is slow. But if I can’t read it, I shouldn’t send it. That’s the rule now.

The Rule

Same principle as code review: if a PR is too big to review, it’s too big to merge. If a spec is too long for you to carefully read before submitting, it’s too long.

I think the instinct right now is to let Claude generate and then deal with the consequences. The better instinct is to constrain the generation so there are fewer consequences to deal with. Shorter documents, more questions instead of pre-made decisions, and an understanding that detail isn’t free just because generating it was.

Your Claude can write ten pages. Read them first — or tell it not to.