I Understand My Code. I Just Don't Know It.

Jan 21, 2026

I can explain any feature in my codebases. I know what they do, why they exist, how they fit.

But ask me the function name? I’d have to search for it.

I understand my code. I just don’t know it.

When you write code yourself, understanding comes free. You build the mental model as you build the software. You remember the tricky parts because they were tricky. You know why that edge case exists because you spent two hours debugging it.

When agents write code, the code appears, but the texture doesn’t transfer. You reviewed it. You approved it. You shipped it. But you didn’t struggle with it.

It’s like knowing a city from a map vs knowing it from walking. You can give directions. You don’t know which streets have potholes.

For fifty years, writing code was the hard part. We optimized everything for production: better IDEs, faster compilers, higher-level languages.

Now production is cheap. Claude writes features in minutes. The constraint moved.

Consumption is the new bottleneck. Reading, reviewing, understanding. And in fast-moving teams, startups especially, high code velocity was already straining ownership. Agents make it worse.

Ownership isn’t just “can I explain it.” It’s “do I feel responsible for it.”

When you write code, you own it because you made it. You remember the trade-offs because you chose them. When an agent writes code, you approved it, but did you choose it? You reviewed it, but did you understand the alternatives?

Ownership doesn’t transfer to the agent. Agents don’t own anything. It just… evaporates.

I love the velocity. But I’m trying not to become a passenger in my own codebases.

So I built a tool. I don’t know if it works yet.

The idea: externalize the mental model. Capture the vocabulary of your system: the domains (nouns), capabilities (verbs), aspects (cross-cutting concerns), decisions (rationale). Not documentation for others. A map for yourself.

┌────────────────────────────────────────────────────────────────────┐
│  DOMAINS            │  CAPABILITIES        │  ASPECTS              │
│  (what exists)      │  (what it does)      │  (how it's governed)  │
├─────────────────────┼──────────────────────┼───────────────────────┤
│  □ Order            │  ◇ Checkout          │  ○ Auth               │
│  □ User             │  ◇ ProcessPayment    │  ○ Validation         │
│  □ Payment          │  ◇ SendNotification  │  ○ Retry              │
└─────────────────────┴──────────────────────┴───────────────────────┘

The decisions matter most. When the agent picks Stripe over Adyen, that choice evaporates unless you capture it. Three months later, you won’t remember there was a choice at all.

It’s called mental (GitHub). It’s early. I’m using it on itself.

I don’t know if externalized models can replace internalized understanding. Maybe the struggle is the point, and you can’t shortcut it. Maybe this is just documentation with better ergonomics.

But code velocity isn’t slowing down. Someone needs to try.