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?”

Say yes to everything and within a month you’ll have 200 files nobody reads.

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.

You’re not coordinating dozens of humans.

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 your gap isn’t the same as their gap.

What Documentation Is For

Here’s the test: Does this document make the next conversation better?

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

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

Good documentation:

• Gets loaded and used
• Changes AI behaviour
• Survives more than a week without going stale
• Fits in context alongside the actual work

Bad documentation:

• Gets created and forgotten
• Says things AI already knows
• Contains metrics that rot
• Competes with working files for context space

The Optimal Number

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

Not 400. Not 4,000. The optimal number for what I need.

That number isn’t sacred - it’s a symptom. A symptom of asking, every time a file is proposed: does this earn its place?

When two documents cover overlapping ground, I merge them. When content migrates to a finished asset (an ebook, a guide), the draft wiki page gets deleted. When a reference link points somewhere stale, it gets fixed or removed.

Maintenance is the discipline. Not just resisting new files, but actively consolidating what exists.

Zone Loading

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

My wiki is organised 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 each zone stays tight. Try this with 400 files and you’re loading noise, guessing at relevance, or spending more time finding than doing.

The structure serves the work. Bloat breaks the structure.

How to Say No

When AI offers to create documentation, ask:

“Will I load this in future sessions?”

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

“Does this duplicate something that exists?”

AI doesn’t always know what you 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.

“Will this go stale?”

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

The Active Discipline

Here’s what I tell Claude Code:

Do not create .md files unless explicitly requested.

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

Every few weeks, I audit what exists. Two files covering similar ground? Merge them. A wiki page whose content now lives in a finished ebook? Delete the wiki page. A link pointing to something renamed? 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 survives?

Voice and tone - How you talk to clients. This changes AI output dramatically and rarely needs updating.

Methodology - How you do the work. The steps, the principles, the non-negotiables.

Positioning - Who you are, who you serve, what you believe. The stuff that makes generic AI output specific to you.

Lookup tables - Quick reference that prevents repetitive explanation. Client list, service tiers, common commands.

That’s roughly it. Everything else is either operational state (belongs in a database) or ephemeral (belongs in the conversation, not a file).

The Signal Compounds

Here’s what happens when you stay lean.

Every document matters, so every document gets maintained. Maintenance is quick because there’s not much to maintain. Updates happen 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 you’re not creating. It’s not. It’s protection. Protection of the signal that makes everything else work.

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