Let's be honest. We don't read code anymore.
AI writes it. We skim it. We ship it. Maybe we glance at the diff in a PR review, maybe we don't. The era of reading every line of code in your codebase is over, and pretending otherwise is just performative engineering.
And honestly? That's fine. You don't need to read every line. You never really did.
But here's what's not fine — most of us have dropped below the minimum threshold of understanding. We've stopped reading the code, and along with it, we've lost something far more important than the "what" or the "how."
We've lost the why.
The "Why" Is the Only Thing That Matters
Think about your codebase right now. You probably know what it does — it's an API, a dashboard, a pipeline. You might even know how certain parts work — this service calls that service, data flows from here to there.
But can you answer these?
- Why is the auth service separate from the main API?
- Why did we pick Postgres over Mongo for this particular data model?
- Why does this request go through three middleware layers before hitting the handler?
- Why is this config hardcoded instead of environment-driven?
These are the questions that matter when things break at 2 AM. When a new hire asks "why is it like this?" and you realize you have no idea. When a security auditor asks why data flows through a particular path and you're guessing.
The "what" and "how" — those are recoverable. You can read the code, trace the flow, figure it out. But the "why" is almost never in the code itself.
Where the "Why" Actually Lives
Here's the uncomfortable truth: the reasoning behind most architectural decisions in your codebase exists in one of these places:
- A Slack thread from 18 months ago that nobody can find
- A meeting that was never recorded
- The head of an engineer who left the company
- A compliance requirement that was communicated verbally
- A PR description that says "refactored auth module" with no further context
The code implies the why, but you need context to read between the lines. Without that context, you're just looking at the outcome of a decision with no way to trace it back.
And here's what makes this worse in 2026: AI-generated code doesn't even have a "why."
When Claude or Copilot writes a function, there was no design decision. There was no tradeoff discussion. There was a prompt, and there was output. The code works, but the reasoning layer — the intent — was never there to begin with. It was in the developer's head when they wrote the prompt, and it evaporated the moment they hit Enter.
"Just Write Better Commit Messages"
I know what you're thinking. I thought it too.
The obvious solution: capture the "why" in commit messages. You can even put it in your CLAUDE.md or agent rules — "always include the reason behind the change in commit messages." Discipline your team to do the same.
feat: split auth into separate service
Why: Compliance team requires auth logs to be isolated from
application logs for SOC2 audit trail. Shared DB made this
impossible without query-level filtering.
That's beautiful. That's exactly what a commit message should look like.
But here's the problem — we don't read commit messages either.
Be honest. When was the last time you ran git log and actually read through commit messages to understand why something is the way it is? We barely read code anymore. We're definitely not reading commit history.
Commit messages, PR descriptions, ADRs, design docs — they're all write-only mediums. People write them (sometimes), but nobody goes back to read them when it matters. The "why" gets captured but never retrieved.
The problem isn't capture. It's retrieval.
The Knowledge Tiers
So if we've accepted that we don't read code, and we've accepted that the "why" is the hardest thing to recover — what's the minimum you actually need to know?
Here's how I think about it:
Must Know (you're dangerous without this):
- System boundaries — what are the services, what owns what
- Data flow — how does a request travel through the system
- Auth model — who can access what and how
- Integration points — what external systems do we depend on
Should Know (you're effective with this):
- Key design decisions and the reasoning behind them
- Database schema and why it's structured that way
- Error handling strategy — what happens when things fail
- The constraints that shaped the architecture (compliance, scale, team size)
Can Look Up (don't waste brain space):
- Implementation details of individual functions
- Utility code and helpers
- Specific algorithm choices
- Configuration specifics
Don't Need:
- Line-by-line understanding of every file
The critical insight: the "Must Know" and "Should Know" tiers are almost entirely about the why, not the what. You need to know why the system boundaries are where they are. Why data flows this way and not that way. Why the database schema looks like this.
The Real Test
Here's a simple test for whether you understand your codebase at the level that matters:
Can you explain why it's built this way — without opening the code?
Not what it does. Not how it works. Why this architecture. Why these tradeoffs. Why this database, this queue, this separation of concerns.
If you can't, you're below the line. And that's where most of us are right now, if we're honest about it.
The "Why" Needs to Be Surfaced, Not Just Stored
The real solution isn't writing better docs or more disciplined commit messages — though those help. The real solution is making the "why" available at the point where you need it.
Not buried in git history. Not scattered across Slack. Not locked in someone's head. But surfaced, structured, and accessible when you're actually making decisions about the code.
This is what I've been building with Revibe. It analyzes your codebase and reconstructs the architectural reasoning — the system boundaries, the design decisions, the "why" behind the structure. Not by reading your Slack (it can't), but by reading the code deeply enough to surface what's implicit.
It's not perfect. No tool can fully recover intent that was never documented. But it gets you above that minimum threshold — the point where you can answer "why is it built this way?" with something better than "I don't know, it was like this when I got here."
The Engineer's New Job
We've accepted that AI writes code. Fine.
But someone still needs to own the "why." Someone needs to know why the system is shaped the way it is, why these tradeoffs were made, why this architecture and not another.
That someone is you. And the uncomfortable truth is that as AI takes over more of the writing, the "why" layer is disappearing even faster — because AI doesn't have intent. It has instructions.
The engineer's job is shifting. It's no longer "write the code." It's "maintain the why."
And if you can't do that, it doesn't matter how good your AI agent is at writing code. You don't understand your codebase at the level that matters.
Revibe helps you understand any codebase — architecture, design decisions, and the reasoning behind the code. Try it free.
