The Agile Manifesto's Biggest Mistake Just Became Obvious
The Manifesto authors were right in 2001. They're wrong now.
Working Software Over Comprehensive Documentation
Every developer knows this line. Most treat it like gospel.
But we fucked up the interpretation.
"Over" became "instead of." Documentation became the enemy. Comments became code smell. "Self-documenting code" became the excuse for empty READMEs.
I've watched senior engineers leave companies and take all the context with them. I've seen teams spend two hours explaining what ten minutes of writing could have documented. I've onboarded onto codebases where understanding anything required three weeks of archaeological digging through Slack.
We made documentation shameful. Like admitting your code wasn't clean enough.
Then AI happened.
Your AI Is Illiterate
Ask Claude about your undocumented codebase. Watch it guess:
"Looking at your code, it seems like this might be handling user authentication, but I can't be certain about the session management strategy..."
It's doing what every new developer does. Except it can't ping you on Slack.
Now watch what happens with context:
"Based on your JWT refresh rotation pattern and stateless session requirement, here's the implementation..."
One knows. One guesses.
Guess which one writes better code.
The Thing Nobody Gets
Every time you explain your project to ChatGPT, you're writing documentation.
Every. Single. Time.
You write "We use JWT tokens with refresh rotation" in a prompt. The AI uses it once. Then it's gone.
Tomorrow you'll write the same thing again.
That's not avoiding documentation. That's writing disposable documentation. Over and over.
Documentation IS Working Software Now
Here's what changed: AI reads everything.
Not skims. Not glances. Reads. Every word. Every time.
When I put three markdown files in .context/:
What we're building
How it's structured
Our patterns and rules
My AI writes correct code immediately. No guessing. No back-and-forth. No "is this what you meant?"
That documentation isn't ABOUT working software. It IS working software. It executes. It produces code. It ships features.
The Manifesto said working software over comprehensive documentation because humans wouldn't read docs.
AI only reads docs.
We're Writing Documentation Anyway
You explain your architecture in every debugging session. You describe your patterns in every feature request. You clarify your constraints in every code review with AI.
You're already writing comprehensive documentation. You're just throwing it away after each conversation.
That's like writing code in a REPL and never saving it.
The Sacred Cow Is Dead
In 2001, documentation was write-only. Nobody read it. It went stale. It slowed teams down.
The Manifesto authors were right to kill it.
In 2025, documentation is executable. AI reads it. Uses it. Needs it.
Fighting documentation now is like fighting version control in the 90s. You're clinging to a world that doesn't exist anymore.
Here's What Actually Works
Stop writing documentation for humans. Start writing context for AI.
.context/
├── project.md # What you're building
├── architecture.md # How it's structured
├── methods.md # Your patterns
└── rules.md # Your constraintsOne hour of setup. Then your AI knows:
Your authentication approach
Your data patterns
Your naming conventions
Your architectural decisions
It stops guessing. Starts knowing.
The Developers Who Get This Will Win
Not because they're smarter. Not because they have better AI. Because they give AI better context.
They'll ship faster. With fewer bugs. With consistent patterns.
While you're still explaining your project for the 50th time.
The Manifesto Needs an Update
Not a rewrite. An update.
From: "Working software over comprehensive documentation"
To: "Working software THROUGH comprehensive context"
Because comprehensive context IS working software when machines can execute it.
The Manifesto authors solved for human readers who wouldn't read.
We're solving for AI readers that read everything.
Different world. Different rules.