Code Description Is Now the Bottleneck (Not the Code)

TL;DR

• Spec-Kit hit 90,000 stars in seven months because code description is now the slowest part of building.
• Writing the code is no longer the hard part. Telling the AI what to build clearly enough is.
• Builders shipping real systems need to get better at spec work, not just prompting.

Spec-Kit hit 90,000 stars in seven months. That's the signal. Code description is the new bottleneck, and the tools that solve it are growing faster than almost anything else in the dev stack.

Why Did Spec-Kit Grow So Fast?

Because the AI can write the code. It can't read your mind.

Spec-Kit solves a specific pain: documenting what code does so the AI has enough context to work with it accurately. That's not a glamorous problem. But it's the real one. Most builders have felt it. You hand Claude or Cursor a messy repo and the output degrades fast. The model doesn't know what's connected to what. Code description fills that gap. Spec-Kit growing this fast tells you the gap was enormous.

What Does This Mean for Builders Shipping Automation?

The craft is shifting from writing to describing, and most builders haven't caught up.

I ship voice AI agents and N8N workflows for Aussie service businesses. Finance brokers, insurance outfits, accounting firms. The build itself moves fast now. Claude Code can wire a Retell AI agent to GHL in a fraction of the time it used to take. But the part that still slows everything down? Getting the spec right before a single line runs. What should the agent say? Under what conditions? What happens when the call goes sideways? That's code description work, even when there's no code yet. This is exactly why Plan Mode is the cheapest phase of any automation build. You're solving the description problem before it becomes a build problem.

Where Does Code Description Actually Break Down?

It breaks at handover, at scope changes, and whenever someone new touches the system.

Here's where most teams feel the pain:

• A workflow built in N8N has no documentation. The next builder can't extend it without reverse-engineering it.
• A voice agent prompt made sense to the person who wrote it. Six weeks later, nobody remembers why a particular branch exists.
• A client asks for a change. The builder has to re-read the whole system before touching anything.
• The handover call turns into a two-hour archaeology session instead of a clean knowledge transfer.

Code description isn't just about AI tools reading your codebase. It's about humans understanding what was built. Both problems compound when you skip it. We bake description discipline into every handover. The offboarding kit we give clients includes prompts in plain text precisely because of this.

Is Code Description a Skill or a Tool Problem?

It's both. But the skill comes first.

Spec-Kit is a tool. It helps. But a tool won't fix unclear thinking. If you can't describe what a system should do in plain English, no amount of tooling saves the build. The developers and AI builders getting the best output from Claude Code right now aren't necessarily the fastest typists or the deepest prompt engineers. They're the ones who can write a clear, specific brief before they start. That's a writing skill. A thinking skill. And it's in short supply. The broader research on AI-assisted development from McKinsey consistently points at specification quality as a key driver of output quality. Not the model. Not the tool. The input.

What Should You Actually Change in Your Build Process?

Write the spec before you open the IDE. Every time.

That sounds obvious. Almost nobody does it consistently. Here's what it looks like in practice on my builds:

• Write what the system needs to do in plain English before any tooling opens.
• Define the edge cases explicitly. What happens when the call drops? When the CRM field is empty? When the lead says no?
• Document every workflow node's intent, not just its function. Future you will thank present you.
• Treat the spec as a deliverable, not a pre-task. It earns its own line on the project.

This is the same reason we charge for the handover call. Documentation and description work is real labour. It prevents the rebuild that costs three times as much.

Key Takeaways

• Spec-Kit's growth to 90,000 stars in seven months is a clear signal: code description is the current bottleneck in AI-assisted development.
• Writing code is no longer the hard part. Describing what you want, clearly enough for an AI to act on it reliably, is.
• Builder discipline around specs and documentation pays back on every handover, every change request, and every new system that gets bolted on.

If you're building automation for your business and your specs are more vibes than structure, let's fix that before it costs you. DM me AUDIT and I'll send you the five questions I ask before touching any new build.