luxsolari-dev

The Moment

I stared at a function I had supposedly written twenty minutes earlier.

It compiled. The tests passed. The logic was correct. And I could not, for the life of me, explain why it was structured that way.

I'm a backend developer with over six years of professional experience. I build systems for a living. I think I know what good architecture looks like and what bad architecture smells like.

And yet there I was, reading my own code like a stranger's handwriting.

The code was fine. I was the problem.

The Creep

If you've used agentic AI coding tools with any regularity, you've probably felt it too.

Not immediately. It creeps. You ship a feature faster than you ever have. You ride the wave through a second feature, a third. The velocity is intoxicating. Your commit graph looks like a heartbeat monitor on caffeine.

And then one day something breaks. You open the file. The code looks foreign. You recognize the patterns — you approved every one of them — but the understanding that should come with authorship isn't there. You can see what the code does. You cannot feel why.

The intuition is hollow.

I didn't have a word for this until I read two pieces that hit me like a freight train.

Anthropic ran a study. Randomized controlled trial, 52 software engineers, half with AI, half without. The AI-assisted group scored 17% lower on comprehension assessments — nearly two letter grades. The largest gap? Debugging. You know, the skill you need most when things go sideways at 3 AM and the AI isn't in the room.

Then Addy Osmani named the thing: comprehension debt. The growing gap between how much code exists in your system and how much of it any human being genuinely understands. Unlike technical debt, which announces itself by making everything slower, comprehension debt is invisible. The codebase looks clean. The tests are green. Velocity is up. And nobody can explain why anything works.

Sound familiar?

But here's the part that saves this from being another "AI bad" post: the Anthropic study also found that developers who engaged cognitively — asked follow-up questions, requested explanations, posed conceptual queries while coding independently — retained knowledge at nearly the same level as those who wrote everything by hand.

The tool doesn't destroy understanding. Passive delegation does.

That distinction changed everything for me.

The Binary Trap

The discourse around AI and coding has exactly two camps.

Camp one: AI is a superpower, embrace it, let it do the heavy lifting, resistance is futile. Camp two: AI is a crutch, real developers write their own code, get off my lawn.

Both are wrong, and they're wrong in the same way. They treat AI assistance as an on/off switch. Use it or don't. Trust it or don't. Delegate or don't.

But that's not how work actually works.

Writing a batch processing script in a language you've used for six years is not the same as implementing a state machine in a language you started learning last month. Shipping a payment service that handles real money is not the same as building a personal game that crashes to desktop. Grinding through a deadline is not the same as a weekend learning session where the whole point is the struggle.

You don't need a switch. You need a slider.

Actually, you need three.

Three Axes

Every task I touch with AI sits somewhere on three independent axes. The rules I follow don't change — but their intensity shifts depending on where a given task lands.

Mastery — how well do I know this?

When mastery is high, AI accelerates what I can already reason about. I can review generated code critically because I have the mental models to catch when something is off. When mastery is low, the same acceleration silently bypasses the learning I need to do.

The pain of getting stuck — chasing a bug through unfamiliar territory, reading documentation that doesn't quite click, staring at a type error that makes no sense — that pain is the tuition. Skip it, skip the education.

This is the axis the Anthropic study illuminated most clearly. The engineers who delegated everything learned nothing. The engineers who struggled, failed, asked questions, then used AI to check their understanding? They learned almost as much as those who had no AI at all.

The struggle isn't the obstacle. The struggle is the curriculum.

Consequence — what breaks if I'm wrong?

A production payment service that silently miscalculates is not the same as a personal game that crashes to desktop. Consequence determines how much comprehension you must have before something ships — not as a nice-to-have, but as a gate.

This is where Osmani's argument hits hardest. When AI-generated code runs in production, "the AI wrote it and we didn't fully review it" doesn't hold up in a post-mortem. The higher the stakes, the less you can afford to not understand what you're shipping.

Intent — am I shipping or learning?

These aren't always opposed, but when time is limited, one wins. A deadline-driven feature at work demands output. A weekend C++ session demands growth. The danger is letting output mode become the default, because output mode feels productive even when it's quietly eroding the skills that make future output possible.

This is the axis most people never think about explicitly. We default to output. The deadline is real, the task is in front of us, the AI is right there offering to make it fast.

Growth mode requires a conscious decision to slow down. And slowing down, in a culture that worships velocity, feels like failure.

It isn't.

Six Rules, Always On

These principles govern every AI-assisted interaction across all my projects. None of them ever turns off. What changes is intensity — and the three axes tell me where to set each dial.

1. I own the SDLC. AI handles implementation, but every architectural decision goes through me. Nothing gets built without me understanding what it does and why. When I'm learning, this is maximum. When I'm expert but accountable for production, still maximum — different reason. When I'm scripting a throwaway batch job, the dial relaxes. But the awareness that I'm relaxing it is the point.

2. Explain before building. For any non-trivial change, the plan comes first. What are we doing, why, what alternatives were considered. This is the exact interaction pattern the Anthropic study found most protective against comprehension loss — asking "why this approach?" forces cognitive engagement that passive delegation skips.

3. No black boxes. If I can't explain why something is structured a certain way, comprehension debt is accumulating. This is the canary. The moment I catch myself unable to explain code that was just written "with" me, that's the signal to stop and go back.

4. Phases ship working software. Every increment ends with something that builds, runs, and works. No partial states. This one barely slides. Broken intermediate states create confusion regardless of context.

5. Leave room for me to code. If a task is educational enough that I want to take a crack at it, AI steps aside. Reviews, debugs, answers questions — but doesn't take the keyboard. Here's the tell: when I feel the urge to skip this rule, that urge itself is the signal to honor it. If I'm avoiding coding something because it feels tedious or hard, that's often exactly the thing I need to do myself.

6. Prefer readable over clever. Idiomatic is fine. Obscure is not. Every clever line is a future comprehension tax paid by the next person who reads it, and that person is almost always future-me.

Installing This in Your Head (and Your Tools)

These aren't theoretical. I bake them into every project through a document that any AI assistant reads before writing a single line of code. It includes the three axes, the six rules, and explicit mode-switch signals:

"Let me try this" → AI steps aside, mentor mode. "Just do it" → Output mode, be efficient. "Walk me through this" → Growth mode, teach thoroughly. "What are the tradeoffs?" → Present alternatives honestly.

I've published this as a skill — a self-contained document you can drop into Claude Code, CLAUDE.md files, Cursor, VS Code, custom instructions, whatever your setup is. It's not specific to any tool or language. It just works.

For Claude Code in particular, I published it as a installable plugin you may grab from here. For other tools, feel free to adapt it from my plugin repo, here.

The Uncomfortable Part

I use AI coding tools every day. Claude Code, Copilot, the whole stack. I think they're the most powerful force multiplier most developers will ever encounter.

I also think they can hollow you out if you let them.

Not through malice. Through convenience. The path of least resistance is delegation, and delegation without comprehension is just borrowing understanding from your future self at a rate you can't see. One day the bill comes due and you're staring at your own code like a stranger's handwriting.

Three questions before every task. Mastery, consequence, intent. Not a checklist — a reflex. A way of keeping the tool in service of you instead of the other way around.

Guess I'll keep asking "why is it like this?" before I ask "can you build this?"

My future self will thank me. Probably.