Stop AI Creating Sprawling Documentation

The first thing AI wants to do is create documentation.

README files. Process guides. Comment blocks. Changelogs. Architecture documents. Style guides. Every conversation ends with “shall I create a document capturing this?”

I said yes to everything for the first month. I ended up with 200 files that nobody - including me - ever read.

The Default is Bloat

AI training data is full of enterprise patterns. Big teams need extensive documentation because context lives in people’s heads and people leave. Handover documents, onboarding guides, decision logs - all necessary when you’re coordinating dozens of humans.

I’m not coordinating dozens of humans. I’m a solo operator.

The patterns fire automatically. AI sees a gap and wants to fill it with a document. That instinct comes from training on codebases where documentation gaps caused real problems. But my gap isn’t the same as their gap. I learned that the hard way.

What Documentation Is Actually For

Here’s the test I apply every time: Does this document make the next conversation better?

Not “is this information useful?” Everything is potentially useful. That’s the trap.

The real question is whether THIS document, in THIS format, will load into context and actually improve AI output. If it won’t, it’s noise pretending to be signal.

The Optimal Number

I run a consultancy with AI. My entire operational wiki is about 40 files.

Not 400. Not 4,000. Forty. And that number isn’t sacred - it’s a symptom. A symptom of asking, every single time a file is proposed: does this earn its place?

When I find two documents that cover overlapping ground, I merge them. When content migrates to a finished asset (an ebook, a guide), I delete the draft wiki page. When a reference link points somewhere stale, I fix it or I remove it.

Zone Loading

Here’s what lean enables that sprawl can’t: practical retrieval.

I’ve organised my wiki by zone - client work, owned ventures, philosophy, operations. When I say “load client files,” AI loads 16 relevant documents. When I say “load venture files,” it loads 7 different ones.

This only works because I keep each zone tight. I tried this with a bloated file structure and I was loading noise, guessing at relevance, or spending more time finding things than doing things.

The structure serves the work. Bloat breaks the structure.

How to Say No

When AI offers to create documentation, I ask myself three questions:

“Will I load this in future sessions?”

If yes, I create it. If “maybe” or “probably not,” I don’t. The maybe-files are where signal goes to die.

“Does this duplicate something that already exists?”

AI doesn’t always know what I already have. It pattern-matches “this seems undocumented” and offers to fill the gap. But the gap might not exist - or it might be intentional. I’ve had AI offer to document things that were deliberately left out.

“Will this go stale?”

Anything with numbers, dates, or status will rot. “Current clients: 6” is a lie by next month. I either put it in a database where it stays true, or I don’t capture it at all.

The Active Discipline

Here’s what I tell Claude Code in my configuration:

Do not create .md files unless explicitly requested.

That’s prevention. But there’s also curation.

Every few weeks, I audit what exists. I find two files covering similar ground and I merge them. I find a wiki page whose content now lives in a finished ebook and I delete the wiki page. I find a link pointing to something I’ve renamed and I fix it.

This isn’t housekeeping. This is keeping the brain alive. AI memory doesn’t degrade gracefully - it has accurate context or it has confident wrongness. Stale documentation is brain damage dressed as thoroughness.

What Earns a Place

So what actually survives?

The Signal Compounds

Here’s what happens when I stay lean.

Every document matters, so I maintain every document. Maintenance is quick because there’s not much to maintain. I make updates because updates are easy.

The whole system stays true. AI loads context that’s current. Outputs improve because inputs are accurate. The compound effect works because nothing’s rotting underneath.

The discipline feels like sacrifice - all those documents I’m not creating. It’s not sacrifice. It’s protection. Protection of the signal that makes everything else work.

The optimal number of files - maintained. Not the maximum number - forgotten.