Stop AI Creating Sprawling Documentation
The first thing the system 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.
Solo operators need documentation that makes the system useful, not documentation that mimics enterprise overhead.The patterns fire automatically. The system 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 the system’s output. If it won’t, it’s noise pretending to be signal.
Good documentation:
- I load it and I use it
- It changes how the system behaves in my sessions
- It survives more than a week without going stale
- It fits in context alongside the actual work I’m doing
Bad documentation:
- I create it and I forget about it
- It says things the model already knows
- It contains metrics that rot the moment I write them down
- It competes with working files for context space
The Optimal Number
I run a consultancy with Claude Code. My entire operational wiki is 86 files.
Not 400. Not 4,000. Under a hundred. 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.
Maintenance is the discipline. Not just resisting new files, but actively consolidating what already exists.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,” the system 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 the system 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?”
The system 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 the system 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.
What Earns a Place
So what actually survives?
Voice and tone - How I talk to clients. This changes the system’s output dramatically and I rarely need to update it.
Methodology - How I do the work. The steps, the principles, the non-negotiables.
Positioning - Who I am, who I serve, what I believe. The stuff that makes generic output specific to me.
Lookup tables - Quick reference that prevents repetitive explanation. Client list, service tiers, common commands.
That’s roughly it. Everything else is either operational state (which belongs in a database) or ephemeral (which belongs in the conversation, not a file).
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. The system loads context that’s current. Outputs improve because inputs are accurate. The compound effect works because nothing’s rotting underneath.
Sprawl breaks compounding. Lean enables it.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.
Tony Cooper
Founder
Put My Crackerjack Digital Marketing Skills To Work On Your Next Website Design Project!
Get Started