DEV Community: Simon Wang

I Made AI Study My Codebase Before Writing a Single Line

Simon Wang — Sat, 14 Feb 2026 22:47:39 +0000

Cover Image Photo by Vitaly Gariev on Unsplash

4 practices for building context that survives between sessions

Adding "because" to corrections helps AI apply principles within a session. But sessions end. Tomorrow, AI starts fresh.

What if AI already knew your project's patterns at the start of every session?

That's what this article is about: building context that persists.

Bootstrap: Have AI Read Your Code First

Before you write any instructions manually, let AI do the initial work.

An example prompt I might use for illustration purpose:

Read through this codebase. What patterns do you see that I'd probably correct you on if you got them wrong? Focus on:

Custom types we use instead of standard library types

Architecture boundaries (what shouldn't call what)

External service constraints (rate limits, costs, timeouts)

Conventions that appear consistently across files

Format each pattern as: "[Do X] because [Y]"

AI scans your code and surfaces patterns. Not everything it finds will be right. But it gives you a starting point, faster than writing from scratch.

A note on AI-generated "because" statements: The bootstrap prompt asks AI to hypothesize reasons for patterns it observes in your actual code files, not guess from generic training data. But these are still inferences, and some will be wrong. Treat the output as a first draft. When a "because" doesn't match reality, correct it. The exercise of reviewing and fixing these explanations often surfaces conventions you hadn't explicitly articulated.

Where this works best: Private codebases with conventions AI hasn't seen in training. For popular open-source projects, AI might already "know" the patterns from training data, making the bootstrap less revealing.

Set expectations: This isn't "set and forget." The instruction file is a living document. New patterns emerge, old ones become obsolete. Budget 10 minutes monthly to review and prune. The payoff is fewer repeated corrections, not zero corrections.

What comes back might look like (examples are illustrative, not from any real codebase):

- Use `process[Entity]Data` naming for transformation functions because the codebase follows this pattern consistently
- Keep domain logic in /src/domain because it's separated from infrastructure for testing
- Add retry with backoff on auth service calls because comments mention cold-start latency issues
- Use repository interfaces because the codebase follows dependency injection patterns

Review this. Keep what's accurate. Discard what's wrong or outdated. Edit what's almost right.

This is your initial instruction file. Save it somewhere your AI tool can access:

Cursor/Claude Code: Add to .cursorrules, CLAUDE.md, or project instructions (loads automatically each session)
ChatGPT: Save to Custom GPT instructions (loads automatically) or paste at session start (manual)
Claude Projects: Add to project knowledge (loads automatically)
Other tools: Keep in a file you can reference when starting new sessions

The trade-off: A detailed instruction file eats context window every session. Start lean (key patterns only) and expand as you identify what actually reduces corrections. If it grows past ~1000 words, consider splitting by module.

The Instruction File

Every AI tool has somewhere to put persistent context:

Cursor: Project rules, .cursorrules file, or AGENTS.md
Claude: Projects with custom instructions
Copilot: Custom instructions in settings
ChatGPT: Custom instructions or memory

The specific mechanism matters less than having ONE place where project context lives and loads automatically.

What goes in this file:

Naming Conventions

- Use `process[Entity]Data` for transformation functions because this is 
  the established pattern across all data processing modules
- Prefix internal API routes with `/internal/` because our gateway uses 
  this to block external access

External Service Constraints

- Add retry with exponential backoff on auth service calls because the 
  service has 2-3 second cold-start latency after idle periods
- Cache geocoding responses for 24 hours because the upstream API charges 
  $0.005 per call and has 200ms latency
- Set 5-second timeouts on inventory checks because the warehouse API 
  occasionally hangs

Architecture Boundaries

- Don't add repository calls in domain functions because this layer gets 
  reused in the offline-first mobile app where there's no database
- Keep the pricing calculator stateless because this service runs as a 
  Lambda and state doesn't persist between invocations

Learned from Incidents

- Validate phone numbers with libphonenumber because we support international 
  formats and need carrier data for SMS routing
- Log the full request before calling the payment gateway because we've 
  lost debugging context when their API times out

Notice: every pattern has "because." The reasoning is what makes these transferable, not just rules to follow blindly.

What This Applies To

This approach works with AI tools that support persistent instructions: Cursor rules, Claude Projects, Copilot custom instructions, and similar. You need somewhere to store context that loads automatically at session start.

For pure autocomplete without instruction file support, the bootstrap and capture practices still help you think clearly about patterns, even if you can't feed them back to the tool directly.

Capturing New Patterns

Your instruction file will grow over time. The source: corrections you make during work.

If you've adopted the "because" habit from the companion article, you're already generating good candidates. The signal that something belongs in the instruction file: you've corrected the same thing twice.

First correction: maybe a one-off. Second correction: it's a pattern. Save it.

The workflow:

You correct AI with "because" during a session
The correction helps within that session
If you make the same correction again (same session or different), copy it to the instruction file
Now it loads automatically in future sessions

Don't try to anticipate everything. Let the file grow from actual corrections. What you actually correct is more valuable than what you think you might correct.

Per-Task Review: Ask Before Generating

Bootstrap creates your initial file. Capturing grows it over time. But there's a third practice that catches misunderstandings before they become code.

Before significant generation, ask AI what it found.

The prompt:

Before you generate this, tell me: what patterns in the relevant code would you follow? What constraints would you respect?

AI shows its working. You review before it generates, not after.

This catches:

Patterns AI noticed that you didn't intend to follow
Constraints AI missed that you expected it to catch
Conflicts between patterns that need resolution

Example:

You ask AI to add a new payment method. Before it generates, you ask what patterns it would follow.

AI responds: "I'd use the PaymentError wrapper, batch API calls, and follow the existing repository pattern in PaymentRepository."

You notice: "Actually, this new provider doesn't have rate limits. Don't batch. And we're trying to move away from the repository pattern for new code, use the port/adapter pattern instead."

You've prevented two wrong guesses before they became code to review and correct.

This is deliberate discovery: actively surfacing AI's assumptions before acting on them.

Maintenance

The instruction file isn't precious. It evolves.

I review mine roughly monthly. Not on a rigid schedule, just when I notice it's been a while or when corrections start repeating.

What I look for:

Outdated patterns: We migrated off Stripe. Remove those constraints.
Conflicts: Two patterns that contradict each other. Resolve or clarify scope.
Bloat: Is the file getting long enough that AI might ignore parts? Split or prioritize.
Missing context: Patterns I've corrected repeatedly that aren't in the file yet.

The goal isn't a perfect document. It's a living reference that makes AI more useful over time.

Example: My Instruction File Structure

Here's a simplified version of how I organize mine:

# Project Context for AI

## About This Project
Brief description: what it does, main technologies, team conventions.

## Naming Conventions
- Use `process[Entity]Data` for transformation functions because...
- Prefix internal routes with `/internal/` because...

## External Services
- Auth service: retry with backoff, cold-start latency
- Geocoding API: cache 24h, $0.005/call
- Warehouse API: 5s timeout, occasionally hangs

## Architecture Rules
- Domain layer: no infrastructure dependencies
- Services: stateless (Lambda deployment)
- New code: port/adapter pattern, not repository

## Domain Requirements
- Validate phones with libphonenumber (international + carrier)
- Log before external calls (debugging context)

## Current Migrations (Temporary)
- Moving from repository pattern to port/adapter
- Old code uses X, new code should use Y

## Still Figuring Out
- Best way to handle cross-service transactions
- Whether to split this into multiple services

The "Still Figuring Out" section is important. It tells AI where you don't have answers yet, so it doesn't confidently apply a pattern that you're still questioning.

The System

Four practices that build on each other:

Bootstrap: AI reads codebase, creates initial instruction file
Capture: Save "because" corrections that repeat
Review: Ask AI what patterns it found before generating
Maintain: Monthly light-touch review

You don't need all four to start. Bootstrap once, then capture as you work. Add per-task review for complex generations. Maintain when the file feels stale.

This is my system. Yours will look different. The principles transfer: give AI the context it needs, and keep that context current.

Why Explaining Your AI Corrections Makes Them Stick

Simon Wang — Sat, 14 Feb 2026 22:44:12 +0000

Cover Image Photo by Scott Graham on Unsplash

A habit that turned repetitive frustration into one-time fixes

"Rename this to processUserData because we use process[Entity]Data pattern for all transformation functions."

That single word, "because," reduced how often I correct AI in a session.

Not across sessions. AI doesn't remember those (I will discuss this in next article). But within a single session, adding "because" to my corrections changed how AI applied them.

Here's why that matters.

Why AI Guesses

AI tools are designed to act on available information rather than ask clarifying questions. That's what makes them fast and fluid. You don't get peppered with "Did you mean X or Y?" every time you ask for something.

The tradeoff: AI guesses. Sometimes the guess is wrong, and you correct it.

But here's what I missed at first: when you correct AI, it guesses again. It has to infer what you meant by the correction.

"Rename this to processUserData" could mean:

You want this specific function renamed
You follow a naming convention for all transformers
You're matching an existing pattern in the codebase
You just prefer it that way for no particular reason

Without knowing which, AI picks whichever seems most likely based on its training.

The Default: Match to General Patterns

LLM is fundamentally a pattern-matching system, but it matches against patterns from its training data, not your specific codebase. Without more context, AI defaults to what it's seen most often across millions of codebases.

If you say "rename to processUserData," AI applies the change where you pointed. When you ask it to create the next transformation function, it might name it handleOrderInfo or convertProductData, matching common patterns from its training, not your local convention.

The problem: when your correction reflects a local pattern (your naming conventions, your architectural constraints, your domain rules), AI has no way to distinguish it from a one-off preference. You may end up correcting the same underlying issue in different places, wondering why AI "didn't learn."

It did learn. It learned you wanted that one function renamed. It didn't learn that you follow a convention, because you didn't tell it.

The Fix: Add "Because"

"Because" changes AI's interpretation.

"Rename this to processUserData" is a one-off request. Apply here, with no signal about where else it applies.

"Rename this to processUserData because we use process[Entity]Data pattern for all transformation functions" is a convention with scope. Apply to all transformation functions in this module.

The difference in the same session:

Correction	AI's Interpretation	What Happens Next
"Rename this to `processUserData`"	One-off rename	Applies to that function. Next transformer gets named `handleOrderInfo` or whatever feels natural.
"Rename to `processUserData` because we use `process[Entity]Data` for all transformers"	Naming convention	Applies to that function AND next transformer gets named `processOrderData` consistently.

"Because" tells AI: this isn't arbitrary. Here's when it applies.

Same-Session Examples

Without "because":

You: "Add retry logic here."

AI applies: Retry on this specific call.

Later in the session, when AI writes another call to the same service, it might not include retry—especially if you've moved on to other code.

With "because":

You: "Add retry with exponential backoff because the auth service has 2-3 second cold-start latency after being idle."

AI now has context: This service is unreliable after idle periods. When it writes the next auth service call, it's much more likely to add retry logic because it understands the problem you're solving.

Without "because":

You: "Validate this phone number."

AI applies: Basic format validation on this input.

Later, AI handles another phone input with minimal validation.

With "because":

You: "Validate with libphonenumber because we support international formats and need carrier lookups for SMS routing."

AI now has context: Phone handling in this system needs international support and carrier data. It's more likely to use libphonenumber consistently because it understands the domain requirements.

The pattern: "because" gives AI local information it can't infer from its training. Your naming conventions, internal service constraints, and domain-specific requirements are unique to your system. Without "because," AI matches against general patterns from its training data, plus limited context in current session, not your codebase's patterns.

What This Applies To

This habit works with chat-based AI tools: ChatGPT, Claude, Copilot Chat, Cursor, and similar. You're having a conversation, and your corrections shape the rest of that conversation.

For pure autocomplete tools (basic Copilot suggestions), you can't "correct with because" directly. There, code comments and instruction files matter more, that's a different workflow.

Results also vary by model. AI tools with stronger reasoning may generalize better even without explicit "because." The habit helps across tools, but don't expect identical results everywhere.

The Habit

When you correct AI, add "because."

That's the whole habit. No setup required. No files to create. No tools to configure.

Next time AI does something you need to fix:

Don't just say what to change
Add why

If you don't know why, that's useful information too. Maybe it IS just a preference. But if there's a reason (architecture, security, external constraints, past incidents), say it.

The test: does AI apply the principle appropriately elsewhere in the same session? If yes, the "because" worked. If not, maybe the reasoning needs to be clearer, or maybe AI's context window has moved on.

Try It

Your next AI coding session:

Work normally until you need to correct something
Add "because" with your reasoning
Notice if AI applies the principle to other code in the session

No commitment. No system to adopt. Just one word.

If it helps, keep doing it. If it doesn't, you've lost nothing.

This habit helps within a session. If you want patterns to persist across sessions, that requires something more: an instruction file that loads at session start. I'll cover that in a follow-up article.

Ralph Loop Is Innovative. I Wouldn’t Use It for Anything That Matters

Simon Wang — Thu, 29 Jan 2026 06:29:46 +0000

Cover Image Photo by Ivan N on Unsplash

The outsourcing disaster pattern I’m seeing again, and three questions before you adopt it

I've seen this pattern before. Ralph Loop shipped a $50,000 project for $297 in API costs. By every metric executives track (shipping speed, test passage, API costs), this is success. The story is everywhere. The innovation is genuine.

But there's a mechanism I'm worried about, one that mirrors outsourcing's failures. Parts 1 and 2 of this series addressed code we understand inadequately. This part examines code generated without human presence, and why I wouldn't bet on it for production systems.

The $297 Success Story

The results are genuinely impressive. At a Y Combinator hackathon, teams used Ralph Loop to ship six production repositories overnight. Geoffrey Huntley, the pattern's creator, used it to build an entire programming language called CURSED through extended autonomous iteration. A project that would have cost $50,000 in developer time was completed for $297 in API calls.

Ralph Loop is elegantly simple: a bash while loop that feeds your prompt to Claude Code, waits for the response, then feeds it back again. When the AI thinks it's done, a stop hook blocks the exit and forces another iteration. This continues until tests pass, a completion signal is detected, or you hit a maximum iteration count. There are now multiple Claude Code plugins that make adoption even easier.

The genius is in context management. Each iteration starts fresh, re-reading specifications and current file state. Progress persists in your files and git history, not in the AI's context window. When context fills up, the next iteration gets a clean slate. The AI picks up where it left off because the work is in the codebase, not in conversation memory.

This is genuine innovation. It solves real problems with context limitations and AI's tendency to stop at "good enough." Teams using it report extraordinary productivity gains.

But there's something the success metrics don't capture.

What Success Metrics Miss

Ralph Loop optimizes for outcomes you can observe: tests pass, code ships, API costs stay low.

It doesn't measure what happens when someone needs to understand the code.

When AI iterates thirty times overnight to solve a problem, no human witnessed the journey. The code works. But the decisions made during iterations 1 through 29? Gone. Why approach A was tried before approach B? No explanation exists. LLMs don't produce records of their reasoning.

The trade isn't speed for quality. The code quality might be fine. It compiles. It runs.

The trade is speed for understanding.

Accumulated traditional technical debt you can map and repay. But what happens when your organization accumulates debt it doesn't know how to map? More on that shortly.

The Outsourcing Parallel

The outsourcing wave of 2000-2010 made similar promises: cut costs dramatically, get overnight development while you sleep, focus on core competencies while others handle the implementation.

The success stories were everywhere. According to industry analyses and retrospectives, companies reported up to 60% cost reductions. Entire products shipped while executives slept.

Then Phase 2 hit.

Communication overhead exploded. Knowledge transfer failed. Bug fixes took significantly longer because the offshore team lacked context for how features fit together. Requirements got lost in translation. The hidden costs emerged: rework from misunderstandings, debugging without context, the slow realization that no one in-house understood critical systems anymore.

The correction came through pain, not foresight. "Insourcing" became a trend. "Hybrid models" emerged as the practical middle ground: outsource well-defined, isolated tasks while keeping a core team who understands the system. Heavy investment in documentation and knowledge transfer became mandatory, not optional.

Some companies never recovered. They had outsourced past the point of no return. By the time they recognized the problem, no internal team remained who understood their own systems. They faced costly rewrites of code that worked perfectly fine, because working code you can't maintain is a liability, not an asset.

Ralph Loop is in Phase 1. The success stories dominate. If the pattern holds, Phase 2 is coming.

Why Outsourcing's Fix Won't Work Here

Here's where the parallel breaks down.

Outsourcing preserved knowledge somewhere: in the vendor's team. The knowledge wasn't in your building, but it existed. People understood the code. You could ask them questions. When vendor staff changed, there was at least a handoff process, however imperfect.

Ralph Loop preserves knowledge nowhere.

The AI has no persistent memory of its reasoning process. When the loop completes, no explanation of why the code works the way it does exists. Not in any human, not in any system. It's not that knowledge transferred poorly. It's that knowledge was never created.

Call it outsourcing to amnesia.

The corrections that worked for outsourcing can't transfer:

Retained core teams? There's no human in the Ralph Loop to retain. The whole point is autonomous operation while developers do other work or sleep.

Better documentation during development? We'll examine this objection in detail, but AI can't document its reasoning in the way humans can. More on this shortly.

Selective outsourcing for defined tasks? Possibly, but this limits Ralph Loop to contexts where understanding doesn't matter. The value proposition was autonomous work on real problems, not just throwaway scripts.

Hybrid models keeping critical work in-house? There's no equivalent "in-house" for AI iterations. The human is either in the loop (defeating the autonomy) or not (accepting the knowledge gap).

The fix that worked for outsourcing required humans preserving understanding somewhere in the system. Ralph Loop's architecture explicitly removes humans from the loop. The correction mechanism doesn't exist.

"Can't We Just Make AI Document?"

A reasonable objection: add a documentation step to each iteration. AI explains what it did and why. Store it in a log file. Now we have a reasoning trail.

This misunderstands both how LLMs work and what documentation actually does.

AI explanations aren't AI reasoning.

When you ask Claude "why did you write this code?", you get post-hoc rationalization. The AI generates a plausible-sounding explanation after the fact. It's not a trace of actual decision process. LLMs don't maintain a queryable record of their generation process. Research shows these explanations correlate weakly with actual generation causes. You're documenting a plausible story, not the real cause.

Volume defeats purpose.

Thirty iterations of explanations produces thousands of words of documentation per task. Who reads it? Not the developer who wanted autonomous overnight work. They're sleeping or doing other things. Not the code reviewer with thirty PRs in their queue. Not the future maintainer skimming for the one paragraph that matters. Documentation without readers is noise, not knowledge.

The most valuable knowledge can't be captured.

Could structured prompting force AI to generate decision trees at each iteration? Perhaps, but the output would still be post-hoc rationalization, not actual reasoning traces.

The critical knowledge is what alternatives were considered, what trade-offs were evaluated, why approach X was chosen over Y and Z. LLMs don't track "considered alternatives" internally. When you prompt for them, you get made-up answers that sound plausible but weren't actually weighed during generation.

The efficiency trade-off kills the value proposition.

Ralph Loop's value is autonomy: ship while you sleep, minimal human involvement. Meaningful documentation requires human verification. Is this explanation accurate? Does it capture the real reasoning? Once you're verifying AI's explanations, you're back in the loop. You've reinvented "coding with AI assistance," which already exists without the elaborate loop infrastructure.

Yes, you can add "documentation updated" to your success criteria. But documentation generated after 30 iterations is summary, not reasoning trace.

The fundamental problem:

Documentation is a transfer mechanism. It moves knowledge from one human to another, or from past-self to future-self. Ralph Loop's problem is knowledge non-creation. No human ever understood the code because no human was there when the decisions were made. There's nothing to transfer.

You can add documentation or keep autonomous efficiency. If you add enough documentation to genuinely preserve understanding, you've eliminated the autonomy. If you keep the autonomy, the documentation is unverified noise providing false confidence.

Pick one.

Knowledge That Was Never Created

The distinction that matters: Ralph Loop's problem is knowledge non-creation, not knowledge loss.

With AI-assisted coding, a developer is at least present. They might not fully understand every line (that's the comprehension debt problem from Parts 1 and 2), but they have the opportunity to pause, question, and learn. The prevention strategies exist because there's a human in the loop who could apply them.

When Ralph Loop generates code, no human is present during generation. The AI doesn't "understand" in the way humans do. It predicts tokens. When the loop completes, understanding doesn't exist anywhere. Not in any human (none were present). Not in any accessible form (the AI produces code, not explanations of its reasoning).

Better documentation or knowledge management can't solve this. There's nothing to transfer. The knowledge gap can't be recovered through effort because there's nothing to recover.

Consider debugging. Normally, debugging human-written code is also learning. You discover the original developer's reasoning: "Ah, they structured it this way because..." Ralph Loop code has no original reasoning to discover. You're not reverse-engineering intent. You're inventing intent, creating a mental model that never existed, hoping it matches what the code actually does.

That's a fundamentally different cognitive task. And it's much harder.

Why Your Safeguards Won't Work Here

This knowledge non-creation is why the strategies from Part 2 change character when applied to Ralph Loop.

In Part 1 of this series, I explored the comprehension debt crisis: the widening gap between code we ship with AI assistance and code we actually understand. Part 2 covered prevention strategies: comprehension scoring, selective acceptance, forcing understanding through explanation.

Those articles assumed knowledge existed somewhere initially. A developer used AI assistance, but they were present during generation. They could score their comprehension. They could force themselves to explain. The practices worked because a human was in the loop who could potentially understand. They just needed the discipline to actually do so.

Ralph Loop breaks that assumption.

You can apply Part 2's strategies to Ralph Loop output. Score your comprehension. Force yourself to explain. Reject code you don't understand. The strategies work.

But they change character. Applied during AI-assisted development, they're prevention (integrated into your workflow, low cost per decision). Applied after Ralph Loop completes, they're remediation (a separate review phase for code that already exists).

Prevention is already hard (Parts 1 and 2 covered why). Remediation is harder. When the code already exists and works, carving out time to deeply understand it feels like a luxury. The code ships. Understanding never happens.

And even if you commit to thorough remediation, you face a time paradox: deeply understanding a large Ralph Loop output could take longer than writing the code incrementally with AI assistance. When you're present during generation, understanding is distributed across the work. After Ralph Loop completes, you're reverse-engineering a large volume of code all at once. The cognitive load is higher, the chunks are bigger, and the efficiency gain that justified using Ralph Loop disappears.

The Capability Loss Pattern

Teams adopt Ralph Loop for understandable reasons. The incentives are clear: ship faster, spend less, work autonomously. What's observable (code ships, builds succeed, costs are low) all favors adoption. What's unobservable (debugging burden, maintenance difficulty, future costs) all opposes it.

This is rational response to available information. Add competitive pressure between teams (those not using Ralph Loop appear slower) and you get race-to-the-bottom dynamics even when risks are understood. The visible costs are immediate and measurable. The hidden costs are delayed and hard to quantify.

But the pattern I've seen before isn't just accumulated debt. Debt implies eventual repayment. The deeper risk is organizational capability loss.

The success stories rarely include six-month maintenance reports. The pattern is new enough that long-term data is scarce, and what exists hasn't been published. Adoption is outpacing evidence. That's precisely the danger.

Play out the scenario: Ralph Loop becomes standard practice. Senior engineers who remember writing and understanding code leave or retire. New engineers join who've only worked with AI-generated codebases. The organization slowly loses the ability to understand its own systems. Eventually, no one remembers that understanding was once possible.

This happened with aggressive outsourcing. Companies outsourced until no internal capability remained. When they needed to insource, they couldn't. Nobody understood the systems well enough to bring them back. They faced massive rewrites of functioning code, or lived with systems no one could safely modify.

With Ralph Loop, if the pattern repeats, the timeline compresses. Outsourcing's capability loss took years. AI-generated codebases could become incomprehensible in months. The debt wouldn't just accumulate. You'd be losing the ability to repay it.

When the Trade-off Might Be Acceptable

Despite my skepticism, Ralph Loop isn't always the wrong choice. Some contexts genuinely don't require long-term understanding:

Prototypes you'll delete after validating the concept. If you're testing feasibility, not building for production, speed matters more than comprehension. Throw it away when you're done. Actually throw it away; don't let it creep into production.

Genuinely throwaway code. Scripts with known expiration dates. One-time data migrations. Tools you'll delete next month.

Legacy code you're planning to sunset. If you're building a replacement system, let Ralph Loop maintain the old one while you focus on the new. The code's days are numbered anyway.

Well-isolated modules with comprehensive tests. If the boundary is clear, the tests are exhaustive, and you can treat it as a black box indefinitely, understanding matters less. (But be honest about whether this actually describes your situation.)

When you have time to study the output. Ralph Loop overnight, then spend the next day reading and understanding the code before it matters. This works if you actually do it, but most teams under deadline pressure skip the study phase.

Geoffrey Huntley, who created Ralph Loop, emphasizes that "operator skill matters." His methodology includes Plan.md files for specifications and Agents.md files to capture learnings across iterations. These help, but they capture intent and observed failures, not the AI's iteration-by-iteration reasoning. The prompt quality determines the outcome. Clear specifications, explicit success criteria, proper test coverage: these aren't optional decorations. They're mandatory safety mechanisms.

Ralph Loop is a power tool. Power tools require skill, and the consequences of misuse aren't immediately visible.

When the Trade-off Matters Most

The test is simple: if you'd eventually want a human to explain this code to a new team member, I'd be cautious about Ralph Loop.

This includes:

Core business logic. The code that makes your product your product. The algorithms, workflows, and domain rules that differentiate you. This needs long-term maintenance by humans who understand it.

Security-sensitive code. Authentication, authorization, payment processing, data handling. You need an audit trail of decisions, not just a working implementation.

Team codebases. Code that multiple people need to understand and modify. The knowledge gap multiplies with each person who didn't witness creation.

Systems expected to live for years. If this codebase will still exist in 2030, someone will need to understand it. Will anyone be able to?

Three Questions Before Deploying

Outsourcing's correction came through pain. Companies didn't change practices because of thought leadership articles warning them. They changed because projects failed, systems broke, and debugging became impossible. The lessons were learned organization by organization, often after significant damage.

If Ralph Loop follows the same pattern (and I think it might), the correction will come the same way. Warnings will be dismissed as Luddism. Teams will adopt because visible metrics favor it. The hidden costs will emerge gradually, then suddenly. Some organizations will learn from others' experience. Many will insist on learning from their own.

Ralph Loop works. The code ships, tests pass, projects complete. But three months from now, can anyone maintain what shipped?

Speed without understanding is borrowing from your future self. Ralph Loop makes the borrowing invisible, the interest rate hard to estimate, and the debt structure unclear.

I could be wrong. Maybe the pattern won't repeat. Maybe the costs will be manageable. But I've seen enough similar mechanisms create delayed costs that I wouldn't bet production code on it.

That's not an argument against ever using it. It's an argument for using it consciously, in contexts where the debt won't matter, and being honest about which contexts those actually are.

If you wouldn't hire a contractor to build a load-bearing wall while you slept, hand you keys, and say "it's structurally sound but I can't explain why," apply the same skepticism here.

Before using Ralph Loop (or before deploying its output), ask:

Does this codebase have a short, defined lifespan?
Do automated tests catch architectural mistakes, not just syntax errors?
Will someone review and understand the output before it matters?

If any answer is "no" or "I don't know," proceed with caution.

If your team is evaluating autonomous AI coding patterns, bring these three questions to your next architecture meeting. The conversation is worth having before the costs become clear.

AI revealed that typing was never the actual bottleneck. Understanding was. How much AI slop code do you think is actually because of this? https://dev.to/thesystemistsimon/50-faster-code-0-better-understanding-the-comprehension-debt-crisis-2eap

Simon Wang — Sun, 25 Jan 2026 12:01:38 +0000

Simon Wang

Jan 23

AI Writes Code 50% Faster. You Understand It 0% Better. It’s Called Comprehension Debt.

#ai #coding #comprehension #technicaldebt

Comments

13 min read

Managing Comprehension Debt: How to Stop Shipping AI Code You Don't Understand

Simon Wang — Sun, 25 Jan 2026 08:19:48 +0000

Cover Image Photo by Vitaly Gariev on Unsplash

A scoring system and team practices that make invisible debt visible before it compounds

You ship AI code you don't understand. Your team does too. That's comprehension debt—and it's accumulating faster than you think.

Part 1 explored why this happens. This article covers how to stop it: a scoring system and team practices that make invisible debt visible before it compounds.

This Only Works If...

These practices require organizational support to maximize the gain: changing metrics, accepting short-term velocity drops, creating psychological safety. In my analysis of AI adoption patterns, only 5-10% of organizations successfully implement systematic change.

Three ways to use this guide:

High-performing org? Implement directly.
Building change capacity? Use as the vision to advocate upward.
Org resists all change? Focus on building change capacity first. These practices won't overcome organizational resistance.

Individual practices don't overcome organizational barriers. But within organizations that can change, these are the practices that matter.

What Actually Works

The challenge is using AI without sacrificing the understanding that makes code maintainable.

Every technique in this article serves one principle: make incomprehension visible before code ships, not after.

What You Control

Individual developers face real constraints: velocity metrics, sprint commitments, competing with peers. These practices acknowledge those constraints while building understanding where it matters most.

1. Score your comprehension. This sounds bureaucratic, but it takes five seconds and changes behavior. Before accepting AI-generated code, rate your understanding on a simple scale. A score of 5 means you could teach this to a colleague right now. A 4 means you understand the design decisions and could modify confidently. A 3 means you get the main approach but would need time on edge cases. A 2 means you know what it does but not why it's structured this way. A 1 means you have no idea how this works.

When you force yourself to assign a number, you can't pretend you understand something you don't.

Don't use this as enforcement (that creates career risk). Use it as debt tracking. Scores of 1-2 are comprehension debt you're consciously taking. Document it:

# Comprehension score: 2
# I don't fully understand the caching eviction strategy here.
# AI generated this based on "implement LRU cache" prompt.
# Future maintainer: review LRU vs LFU tradeoffs before modifying.

Over time, notice your patterns. If you consistently ship API endpoint code at score 2, you're building understanding debt in an area you touch frequently. That's data you can act on.

2. Apply understanding selectively. You can't deeply understand everything. Core infrastructure, security, and payment processing should require score 3+ before shipping. Boilerplate, test scaffolding, and configuration can ship at score 2 (you understand the pattern even if you didn't write every line). Prototypes and throwaway code can ship at score 1 (you're explicitly trading understanding for speed).

The key is conscious choice. The problem isn't comprehension debt existing, it's accumulating it unconsciously in systems that will live for years.

3. Force comprehension through writing. After accepting AI-generated code, write 2-3 sentences explaining why it's structured that way:

"This uses a token bucket rate limiter because we need burst tolerance (user can make 10 requests instantly but limited to 100/hour overall). Alternative would be sliding window (stricter but more complex to implement)."

If you can't write this explanation, you don't understand it well enough. The writing forces clarity. No teammate coordination required. This works async, at your own pace, with zero career risk.

The reality of time pressure. These practices slow you down. That's the point. Comprehension debt accumulates because we prioritize speed over understanding. The practices that prevent it require consciously choosing understanding over velocity, at least some of the time.

The pressure to ship is real. But the velocity you gain from AI is borrowed from future maintenance capacity. Teams shipping fast with heavy AI assistance often hit a wall after 6-12 months. Velocity metrics look great initially. Then every feature takes longer than estimated because teams spend half their time understanding code they shipped months earlier.

Teams adopting these practices may see initial velocity drops. But predictability improves dramatically. The choice isn't between fast with AI or slow without AI. It's between fast now and slow later, or slightly slower now and consistently fast ongoing.

When to Accept the Debt

Sometimes comprehension debt is the right trade-off. But make it a conscious trade-off, not a default. Like traditional technical debt, it's a tool. The question is: Are you taking it consciously or unconsciously?

Accept comprehension debt when:

You're prototyping. Speed matters more than understanding. You might throw this code away. Score 1-2 is fine, just don't let the prototype become production.
The code is genuinely temporary. If it has a known sunset date, comprehension debt is acceptable risk.
You're in spike mode. Learning whether an approach is viable matters more than understanding every implementation detail.

Don't accept comprehension debt when:

This is core infrastructure. Authentication, payment processing, data integrity, understand these deeply before shipping.
You're building for long-term maintenance. If this code will be modified frequently, comprehension debt compounds into impossibility.
You're the only person who knows the domain. Your departure creates a succession crisis (remember Sam's story from Part 1).

The difference between traditional technical debt and comprehension debt: Traditional technical debt is conscious ("I'm taking shortcuts in code structure"). Comprehension debt is usually unconscious ("I shipped code I don't understand"). Make it conscious. Document it. Track it. Review it quarterly: "Where did we accumulate comprehension debt? Was it worth it?"

Once you're comfortable tracking your own comprehension, the team-level gaps become visible. You'll notice when code reviews miss understanding, when estimates ignore comprehension time, when retrospectives skip the "do we understand what we shipped?" question. That's when these practices become relevant.

What You Can't Do Alone

These practices require some organizational support but work within existing constraints. You don't need executive approval to start.

1. Change code review culture. This is the highest-leverage team practice. Reviews should verify understanding, not just correctness. A reviewer should be able to say "I understand why this is structured this way," not just "LGTM." Authors should expect to explain design choices, not just show passing tests. And "I don't understand this" becomes a valid reason to block a PR, not just "this has bugs."

Start with one reviewer modeling this consistently. Cultural shifts begin with consistent individual behavior.

2. Build understanding into estimates. This is the most practical lever managers have. Don't estimate AI-assisted tasks at AI speed. Estimate at "AI + comprehension" speed. A feature that takes 3 hours with AI should be estimated as 5 hours. The extra 2 hours is for understanding, documentation, and explanation. Frame it to product as "investing in maintainability," not "going slower."

Track this over 2-3 months. Show that features estimated this way have lower post-launch maintenance costs. That's your business case.

3. Track maintenance burden by comprehension score. When a bug takes 2 days to fix because nobody understood the code, note: "This was originally shipped at comprehension score 1." After 3 months, you'll have data showing that score-1 code has 3x the maintenance cost. That's evidence for changing practices, not just appeals to principle.

4. Create psychological safety for knowledge gaps. Teams won't surface comprehension debt if it's career-risky. Never punish "I don't fully understand this." Reward surfacing gaps early, before they cause outages. Model vulnerability: "I don't understand this either, let's learn together." This is cultural, not structural. You control team culture even if you don't control company metrics.

5. Protect your team from velocity comparison. When asked "Why does your team ship slower than Team B?", have data ready:

"Our maintenance costs are 40% lower"
"Our feature modification time is 2x faster"
"Our bugs-per-feature rate is half theirs"

You're not slower. You're investing differently. But you need data to make this argument.

6. Monthly comprehension retrospectives. Managers create the space; teams run it without managers present. Once a month, the team asks privately: "What code did we ship that nobody fully understands? Which gaps should we fix vs. consciously accept? Are we accumulating debt faster than we're paying it down?" This must be psychologically safe. No blame. No performance review material.

Starting Small

Start with individual awareness. Use the comprehension scale on your own work for a month or two before proposing team changes. When you have data showing patterns (where you consistently score low, which areas have higher maintenance burden), you have credibility to suggest experiments.

Pick one high-risk area, try "score 3+ required" for that area only, and track results. Let evidence drive expansion, not enthusiasm.

If your organization won't move beyond individual practice, you've still improved. Conscious tracking beats unconscious accumulation.

What You're Actually Choosing

The social contract of software development used to be simple: if you wrote it, you understood it. The act of writing guaranteed comprehension.

AI broke that guarantee. Now you can ship code you don't understand. This isn't AI's fault; it's a tool. The question is whether we adapt our practices to maintain understanding or whether we let comprehension debt accumulate until codebases become unmaintainable.

For developers who learned to code with AI assistance, this contract never existed. If you're in this position, you face a unique challenge: building understanding retroactively while continuing to produce. The practices in this article (explanation confidence scoring, delayed explanation, deliberate manual coding for core logic) aren't just about preventing debt. They're about building the foundational understanding that earlier generations developed by necessity.

Teams struggle with this. The temptation to accept everything AI suggests is strong. The velocity gains are real. Management loves the metrics. But six months later, the team can't move fast because they don't understand their own codebase.

Comprehension debt is more dangerous than traditional technical debt because it's invisible. Your tests pass. Your users are happy. Your velocity metrics look great. But your team is accumulating a maintenance bomb. When it explodes, you'll discover you've been shipping code without understanding.

The GitClear data shows the symptoms: more churn, less refactoring, more time fixing recent code. The Uplevel data shows the bug rate climbing. These aren't future predictions. This is happening now, in production systems, across the industry.

The uncomfortable truth is that AI can make us more productive, but only if we resist its most seductive feature: the ability to ship code faster than we can understand it. The 10x engineer in the AI era isn't the one who accepts every suggestion. It's the one who accepts only what they comprehend.

This means saying no to velocity. It means taking time to understand. It means treating "I don't fully understand this" as a blocking issue, not a nice-to-have. It means changing code review culture from "does it work?" to "do we understand it?"

In five years, we'll look back on this moment as critical. Either we learned to maintain understanding while using AI, or we built unmaintainable systems at unprecedented scale. The difference will be whether we valued understanding over velocity.

Your codebase is accumulating comprehension debt right now. Every AI-generated function you don't fully understand. Every pattern you copied without grasping why. Every algorithm that works but you can't explain. It compounds silently until someone needs to modify the code.

Then you'll discover the cost of shipping faster than you can comprehend.

Research Citations

Oregon State University Study (2025):
Qiao, Y., Hundhausen, C., Haque, S., & Shihab, M. I. H. (2025). Comprehension-performance gap in GenAI-assisted brownfield programming: A replication and extension. ArXiv preprint arXiv:2511.02922.

GitClear Analysis:
GitClear. (2024). Coding on Copilot: 2023 Data Suggests Downward Pressure on Code Quality.

Uplevel Research:
Uplevel. (2024). Analysis of GitHub Copilot Impact on Developer Productivity and Code Quality.

AI Writes Code 50% Faster. You Understand It 0% Better. It’s Called Comprehension Debt.

Simon Wang — Fri, 23 Jan 2026 04:45:25 +0000

Cover Image Photo by Vitaly Gariev on Unsplash

The invisible cost that metrics don’t capture

You shipped 2,000 lines of authentication code you don't understand.

Not because you're junior. Not because the code is bad. Because GitHub Copilot wrote it in 30 seconds and you accepted it without building mental models.

Tests passed. Code review passed. Production's fine. Eight months, zero bugs.

But now you need to add OAuth support, and you're staring at code that works perfectly but you can't modify safely. You're reverse-engineering your own work.

This is comprehension debt. And the gap between your code's velocity and your comprehension is growing exponentially.

What the Research Shows

Researchers at Oregon State University quantified this precisely. In a controlled study, 18 computer science graduate students completed brownfield programming tasks (adding features to codebases they didn't write). Half used GitHub Copilot, half didn't. (The study used students, but the pattern matches what practitioners report in professional settings.)

The results revealed the core of comprehension debt. Students using Copilot completed tasks nearly 50% faster and passed significantly more tests. Major productivity gains. But when researchers measured actual code comprehension (could they explain how the code worked, modify it effectively, debug issues), the scores were identical. Nearly 50% faster output. Zero comprehension gain.

The researchers observed what they called "a fundamental shift in how developers engage with programming." The workflow changed from "read codebase → understand system → implement feature" to "describe need → accept AI suggestion → move on." That missing struggle (those hours debugging, those moments of confusion) is where understanding builds.

In exit interviews, students using Copilot reported feeling productive but uncertain. They shipped working code but worried they didn't understand how or why it worked. This is comprehension debt forming in real-time: output without comprehension.

How This Plays Out in Real Teams

This pattern plays out consistently. Consider an authentication system built by a senior developer with 10 years experience. Comprehensive test coverage. Clean code that follows all team standards. Passed code review by two other senior developers. In production for eight months. Zero bugs reported.

Everyone did their job correctly. The problem isn't incompetence or poor practices.

The problem: Nobody, including the senior developer who built it, can explain why it's designed this way. Why token buckets over sliding windows? Why this specific refresh token strategy? Why these database queries?

The universal response: "I don't know. GitHub Copilot suggested it, tests passed, it works."

This isn't a story about a bad team. It's about good teams making rational individual decisions that produce collective disaster.

Now the team needs to add OAuth support. They're staring at 2,000 lines of code nobody ever understood. Not because they lacked discipline. Because the incentives made understanding optional and velocity mandatory.

About These Stories

The scenarios in this article are composite illustrations, combining common patterns observed across AI adoption experiences. While the names and specific details are constructed, the dynamics they illustrate are real and representative. If you recognize your team in these patterns, you're not alone. These patterns emerge reliably because of how AI changes the relationship between writing and understanding code.

What Comprehension Debt Is

For fifty years, writing code and understanding code were the same activity. You couldn't write code without understanding it. The act of typing forced comprehension. You thought through the logic, considered edge cases, debugged the mental model.

AI broke that coupling.

You can now accept a 200-line function from Copilot in thirty seconds. You scan it, looks reasonable, tests pass, you ship it. But you didn't write it line by line. You didn't think through every branch. You didn't consider why this approach over alternatives.

The code works perfectly. It's just you might not fully understand it.

That gap between "code that works" and "code I understand" is comprehension debt. And it compounds faster than traditional technical debt.

Traditional technical debt is code you understand but know is wrong. A quick hack, a shortcut, a placeholder you meant to fix. It's conscious. You took the debt deliberately (usually for speed). When it breaks, you know where to look because you understand the implementation.

Comprehension debt is code that works but you don't understand why. It's unconscious accumulation. You didn't mean to take this debt; it just happened while you were moving fast with AI assistance. When it breaks, you can't easily fix it because you don't understand the implementation. You have to reverse-engineer your own codebase.

This pattern plays out consistently. AI-generated code ships faster. Velocity metrics look great. Everyone's happy. Six months later, the original author leaves or moves to another project. The team inherits working code they can't modify safely. They're paralyzed by fear of breaking something they don't understand.

The debt isn't visible in code reviews. The code looks fine (often better than what the team would write manually). It passes tests. It follows conventions. But nobody on the team has the deep understanding that comes from building something from scratch.

How Comprehension Debt Differs From Legacy Code

If this sounds familiar, it should. Developers have always had to read code they didn't write. Every codebase has modules nobody fully understands. This is the legacy code problem.

But comprehension debt is different in three critical ways.

First, the starting point. Legacy code becomes hard to understand over time. Someone understood it when they wrote it. Comprehension debt starts with code nobody fully understood, not even the person who "wrote" it.

Second, the velocity. Legacy code accumulates gradually as authors leave and memories fade. Comprehension debt accumulates instantly, with any AI suggestion accepted without deep comprehension.

Third, the preventability. Legacy code is hard to prevent: people leave, memories fade, codebases age. Comprehension debt is preventable at creation. Before you ship AI-generated code, you can choose to understand it.

Fourth, the recoverability. Legacy code leaves an evolutionary trail. Git history shows how code grew from simple to complex, one decision at a time. Commit messages explain why changes were made. PR discussions capture alternatives considered. When you inherit legacy code, you have archaeology tools (git log, git blame, PR reviews) to reconstruct understanding.

AI-generated code appears fully formed. One commit. Two thousand lines. Git history shows what appeared, not why it's designed this way. The commit message says "Add authentication" but not why token buckets over sliding windows, why this refresh strategy, why these specific database queries. Git blame points to the developer who accepted AI suggestions, but they can't explain the reasoning because they never made those decisions. The AI did, and AI doesn't write commit messages explaining its probabilistic choices.

Legacy code loses understanding over time, but leaves a trail to recover it. AI-generated code never builds understanding, and leaves no trail to reconstruct it. The evolutionary scaffolding that normally helps you understand "why this approach over alternatives" doesn't exist. Understanding wasn't just lost; it was never captured anywhere.

The symptoms look similar: "I need to modify code I don't understand." But the solution timing is different. Legacy code requires ongoing maintenance to prevent understanding loss. Comprehension debt requires conscious practice at creation to build understanding in the first place.

How AI Creates Comprehension Debt

Comprehension debt accumulates through four mechanisms in codebases using AI coding assistants extensively.

The first mechanism is autocomplete acceptance. Copilot suggests a complete function. You scan it, logic looks right, variable names make sense, handles obvious edge cases. You accept it. Thirty seconds reviewing what would have taken thirty minutes to write. But you verified correctness without absorbing design decisions. Six months later, you need to modify it and realize you never understood why it was structured that way.

The second mechanism is black box solutions. You describe a problem to Claude or ChatGPT. It generates a working solution. You test it, it works, you ship it. But you don't understand the algorithm or why this approach over others. Ask AI for a caching strategy and you'll get an LRU cache with eviction policies. The code works. But do you understand when LRU is right versus LFU or random eviction? Or did you just ship "a caching solution that works"?

The third mechanism is pattern copying without context. AI suggests patterns from its training data. The pattern works in other contexts. It might even be best practice somewhere. But is it right for your codebase? Does it fit your architecture? Does it align with your team's conventions? Teams can accumulate five different error handling patterns because AI suggests slightly different approaches in different files. Each pattern works fine. But nobody chose a consistent approach. The codebase becomes internally inconsistent and nobody knows why.

The fourth mechanism is understanding lag. This one is subtle but deadly. Code generation outpaces comprehension. Pre-AI, you might ship five features per month. Your understanding grew at five features per month because you built each one, so you understood each one. With AI, you might ship twelve features per month. But your comprehension still grows at five features per month. That's the rate at which you can deeply understand complex systems. The gap is seven features per month that you shipped but don't fully understand.

After a year, you have 84 features in your codebase that you shipped but never fully absorbed. That's comprehension debt accumulating at scale.

Why Good Teams Still Accumulate Comprehension Debt

The practices that prevent comprehension debt are obvious: understand code before shipping, enforce comprehension in code review, document design decisions. Every experienced developer knows this.

So why does comprehension debt accumulate even in good teams?

Because the forces that create comprehension debt aren't about individual failures. They're about systemic incentives that make accumulation rational, even inevitable, despite everyone knowing better.

The Velocity Measurement Trap

Your sprint dashboard shows story points shipped. Your team's performance is measured by features delivered. Comprehension isn't measured because it's invisible.

When a developer uses AI and ships 50% faster, they look productive. When they slow down to understand deeply, they look inefficient. Even if you personally value understanding, your manager sees velocity metrics. And velocity is how teams are compared, how performance reviews are written, how promotions are decided.

The result: Even if you want to enforce understanding, organizational pressure pushes toward accepting AI code quickly. "Why did this take so long?" is a question developers face. "Do you fully understand this?" is not.

The Delayed Cost Problem

AI's benefits are immediate: 50% faster shipping, features delivered this sprint, velocity metrics that look great today.

Comprehension debt's costs are delayed: maintenance burden in six months, debugging difficulty next quarter, modification paralysis next year. Those costs appear in different sprints, attributed to different people, blamed on "legacy code" rather than creation practices.

The developer who accepts AI code without understanding gets credit for velocity. The developer who inherits that code six months later gets blamed for slow delivery. The system rewards creating debt and punishes paying it.

Sprint retrospectives celebrate velocity. Nobody celebrates "we shipped slower but built deep understanding that will pay off in six months." That's not how teams are measured.

The Tragedy of the Commons

Comprehension debt is a tragedy of the commons problem. The commons is codebase maintainability. Each developer makes individually rational choices that collectively destroy maintainability.

Individual developer's calculation:

Time to understand deeply: 5 hours
Benefit to me: Minimal (I might not modify this code again)
Cost to me: Manager unhappy about slow delivery, missed sprint commitment
Rational choice: Accept without full understanding

Multiply this by 20 developers making this same rational choice across 20 modules. Collective result: Nobody can maintain the codebase. But no individual developer made an irrational choice given their incentives.

This is why "just understand code before shipping" doesn't work. It assumes individual discipline can overcome systemic incentives. It can't. Not sustainably.

The False Confidence Feedback Loop

Tests pass. Code review approves. The code works in production. Every signal says "success."

There's no feedback signal that comprehension debt is accumulating. Unlike technical debt (where code quality degradation is visible) or security debt (where vulnerabilities can be scanned), comprehension debt is completely invisible until someone needs to modify the code.

By the time you discover comprehension debt (when modification is needed), it's too late. The debt is already accumulated. The cost is high.

This creates a false confidence loop: Ship fast with AI → Everything works → Ship faster → More comprehension debt → Everything still works → Until suddenly modification becomes impossibly expensive.

When It Breaks

When Transitions Reveal the Gap

Comprehension debt's most visible consequence appears when key people leave.

When Sam, the tech lead, announced a family relocation with two weeks' notice, the team scrambled to prepare. Sam had shepherded them through six months of AI adoption: reviewing hundreds of Copilot suggestions, building out the architecture, making the codebase what it was. The code worked beautifully. Tests passed. Customers were happy.

Then Raj arrived as Sam's replacement and asked standard onboarding questions: "Why did we choose this authentication pattern? What alternatives did you consider? How does the payment flow handle edge cases?"

The team couldn't answer. Not because Sam had hoarded knowledge (Sam had been collaborative and communicative throughout). But because those architectural decisions had never been made by a human in the traditional sense. Sam had evaluated and accepted AI suggestions, but the reasoning for why those patterns worked lived in neither documentation nor human memory. Sam had understood enough to judge the suggestions as "good enough," but not enough to explain the full reasoning behind them.

Forty percent of the codebase was AI-generated. Raj spent three months reconstructing architectural context that no one had explicitly created. What looked like a succession planning failure was actually an comprehension debt crisis. The knowledge gap existed not because people failed to document, but because there was less explicit human reasoning to document in the first place.

The team eventually recovered. Raj forced systematic documentation of every design decision going forward (not just what was built, but why alternatives were rejected). The process made code reviews slower but rebuilt the shared understanding the team needed. The silver lining: the team became more resilient to future transitions. But it cost three months of leadership capacity on archaeology that should have been architecture.

If your most experienced AI-using team member left tomorrow, could the rest of the team maintain the codebase? What percentage was human-decided versus AI-suggested-and-accepted?

Comprehension Debt Compounds During Growth

Comprehension debt doesn't just affect individuals; it compounds across teams, especially during growth.

One organization doubled their engineering team from six to twelve while adopting AI. The original six engineers understood their AI-generated codebase moderately well (maybe 8 out of 10 on a comprehension scale). They could explain most decisions, debug most issues, and maintain most features.

They hired Sarah and David, who learned from the original six. But Sarah and David's understanding landed around 6 out of 10. They'd learned "use AI, ship fast" without the foundational context of why certain patterns mattered. Still functional, but shallower.

When Sarah and David mentored the next wave of hires (Priya and Miguel), the knowledge degraded further. Priya and Miguel learned from people who were themselves still learning. Their understanding: roughly 4 out of 10. They knew how to use the tools, but not why things worked the way they did.

By the third generation of hires (Lisa and Carlos, who learned from Priya and Miguel), understanding had dropped to 2 out of 10. Lisa and Carlos shipped code they described as "mystery boxes." When asked to explain their implementations, they'd shrug: "It works. The AI generated it. Tests pass."

Six months later, both Lisa and Carlos left. Their exit interviews cited "not being good enough." The reality: they were talented engineers placed in an impossible situation. The system had accumulated comprehension debt faster than it could transfer knowledge. This isn't a story about individual failure; it's about what happens when systems scale during disruption.

Key takeaway: Don't scale your team while accumulating comprehension debt. Each knowledge transfer generation loses understanding.

This isn't theoretical. GitClear published data from analyzing code written with GitHub Copilot across multiple organizations. They found increased "code churn" (code modified shortly after being written), more copy-pasted code, and less refactoring. This pattern is consistent with comprehension debt, though the data doesn't isolate the cause.

They also found developers spend less time refactoring and more time fixing recent code. The pattern suggests teams are shipping code faster but understanding it worse. The technical debt isn't in code quality; the generated code is often fine. The debt is in comprehension.

Uplevel's research found developers using AI coding assistants introduced more bugs into production. The data doesn't isolate why, but the pattern is consistent with accepting code without fully understanding it.

These aren't productivity gains. These are productivity illusions. You ship faster but maintain slower. The velocity appears in sprint metrics. The cost appears in six-month maintenance windows.

This is the compounding problem. Comprehension debt doesn't just accumulate in the code you ship today. It degrades the knowledge across your team over time, making every future developer less effective. The velocity gains from AI come with an understanding cost that multiplies across team generations.

The question isn't whether comprehension debt will accumulate, with AI tools, it's inevitable. The question is whether we'll accumulate it consciously or unconsciously, whether we'll manage it strategically or let it manage us.

One Thing You Can Do Today

Before we get to systematic solutions in Part 2, here's one practice you can start immediately: Before accepting AI-generated code, ask yourself one question: "Could I explain to a colleague why this code is designed this way?"

If the answer is no, you have two choices: spend time understanding it, or don't ship it.

This simple gate catches comprehension debt at the source. It won't solve the organizational pressures that created this problem, but it gives you agency while we work on systemic solutions.

In my next article, I'll share what high-performing organizations do differently: practices that address the root causes while acknowledging real constraints (career risk, velocity pressure, organizational resistance). These aren't universal solutions, 95% of organizations struggle with any systematic change, and these practices won't overcome that. But for organizations with change capacity, or those building it explicitly, this is the path that research suggests works.

But first: do you recognize this pattern in your own codebase? How much of your team's code would pass the "can you explain why it's structured this way?" test? That's where the work begins.

Why This Is Hard

The comprehension debt crisis exemplifies a broader pattern I explored in "Thirty Years, Five Technologies, One Failure Pattern: From Lean to AI." That article documents how 95% of AI transformations fail, not because of technical limitations, but because organizational systems aren't designed to integrate systematic change.

The same barriers that prevented Lean Manufacturing adoption (2% success rate), Agile transformations (70% failure rate), and Electronic Health Records integration (96% adoption, zero improvement in clinician burnout) are now blocking AI adoption. Organizations measure velocity but not understanding. They reward speed over comprehension. They optimize for existing metrics even when those metrics conflict with new practices.

This means there's no easy fix. If your organization has struggled with any systematic change to how work gets done (Lean, Agile, DevOps, test-driven development), that pattern will repeat here. Comprehension debt is a symptom. Organizational change capacity is the root cause.

My next article won't pretend to solve the organizational problem, that requires executive commitment, incentive restructuring, and years of culture change that only 5-10% of organizations achieve. What I will share is what practitioners and teams can do within current constraints: harm reduction practices that slow the accumulation, build evidence for change, and protect understanding where you have control.

It's not transformation. It's survival. But sometimes survival buys you time to build the case for transformation.

Research Citations

Oregon State University Study (2025):

Qiao, Y., Hundhausen, C., Haque, S., & Shihab, M. I. H. (2025). Comprehension-performance gap in GenAI-assisted brownfield programming: A replication and extension. ArXiv preprint arXiv:2511.02922.

GitClear Analysis:

GitClear. (2024). Coding on Copilot: 2023 Data Suggests Downward Pressure on Code Quality.

Uplevel Research:

Uplevel. (2024). Analysis of GitHub Copilot Impact on Developer Productivity and Code Quality.

Note: Originally published on ITNEXT: https://itnext.io/50-faster-code-0-better-understanding-the-comprehension-debt-crisis-78d99c0cbc0c

Complexity Can't Be Eliminated. It Can Only Be Moved.

Simon Wang — Fri, 23 Jan 2026 04:09:33 +0000

Cover Image Photo by Sunder Muthukumaran on Unsplash

Six patterns that determine where complexity lives in your codebase — and how to choose consciously

A senior engineer made our API faster by caching responses. Query time dropped 80%. We celebrated.

Two months later, the cache was stale. Data was wrong. Users complained. We spent weeks debugging cache invalidation.

The speed didn't come from nowhere. The complexity didn't disappear. We just moved it.

This pattern behaves like a conservation law from physics. Not perfectly, but close enough to be useful.

Why Complexity Relocates (Not Disappears)

In physics, certain quantities can't be created or destroyed. Only transformed or moved. Energy conservation says energy can't be created or destroyed, only converted (chemical to kinetic, kinetic to heat). Momentum conservation says total momentum stays constant in a closed system. Mass conservation says mass doesn't appear or disappear, just rearranges.

These aren't guidelines. They're laws. You can't violate them. You can only work within them.

Software has something similar: essential complexity (the inherent difficulty your problem requires) can only move, not disappear. Larry Tesler famously called it "Conservation of Complexity": complexity can't be eliminated, only moved. UX designers know Tesler's Law intimately. But while this principle is well-recognized in design circles, software architects rarely discuss it explicitly or apply it systematically.

I've noticed we treat "simplification" as if we're eliminating complexity rather than relocating it. We don't measure both sides of the trade. We don't name what's actually being relocated.

This isn't quite like physics conservation laws, where total energy stays exactly constant. Software complexity can increase or decrease. But there's a pattern, and a floor.

Every problem has essential complexity, what Fred Brooks called the inherent difficulty of what you're trying to solve. Authentication must verify identity. Distributed systems must coordinate. These requirements create complexity that can only relocate, or be eliminated by dropping features entirely. You can't design it away.

Then there's accidental complexity, from how we implement solutions. Poor abstractions, unnecessary indirection, tech debt. This can be eliminated through better design.

When net complexity increases (code drops 40%, config grows 60%, net +20%), you're seeing accidental complexity added during relocation. When complexity genuinely disappears (deleting 500 lines of dead code), you're removing accidental complexity that never contributed to solving the problem.

The pattern: essential complexity moves. Accidental complexity varies. And there's a floor: you can't simplify below essential complexity without losing functionality.

To be precise: when we say "complexity relocates," we mean essential complexity (the irreducible difficulty of your problem domain). You can't simplify a tax calculation system below the complexity of the tax code itself. You can only choose where that essential complexity lives in your architecture.

This explains why some systems resist simplification. You're not fighting bad design. You're hitting essential complexity. The question shifts: Where should this essential complexity live to minimize total cost?

When you "simplify" a system, you're not eliminating complexity. You're relocating it. When you make a decision configurable instead of hardcoded, you haven't reduced the number of decisions. You've moved where the decision happens. When you cache data, you haven't eliminated the work of keeping data fresh. You've transformed query complexity into cache invalidation complexity.

Understanding relocation patterns changes how you think about software design. You stop asking "how do I eliminate this complexity?" and start asking "where do I want this complexity to live?"

Six patterns emerge consistently. We'll call them relocation patterns that behave like conservation laws. Not physics-perfect, but strong enough to guide architectural decisions.

The Six Patterns

Pattern 1: Complexity Relocation

The caching story is a perfect example. Before caching, we had high query complexity: every request hit the database, queries were slow, load was high. Cache management complexity was zero because we didn't have a cache. After caching, query complexity dropped dramatically. Requests were fast, database load was low. But cache management complexity exploded. We now had staleness issues, invalidation logic, consistency problems, memory pressure.

Total complexity didn't decrease. We moved it from "slow queries" to "cache management." The system felt simpler in one dimension and more complex in another. The essential complexity of data consistency didn't disappear. It moved from query time to cache invalidation. But if your cache implementation is inefficient, you've added accidental complexity on top.

I've learned you can't eliminate complexity. You can only move it. The question isn't "how do I make this simpler?" The question is "where should this complexity live?"

Consider adding an abstraction layer. Before abstraction, you have high duplication complexity: the same database query logic appears in twenty places. But you have low abstraction complexity because there's no layer to understand. After creating an ORM, duplication complexity drops to near zero. Database logic lives in one place. But abstraction complexity rises. Now you need to understand the ORM, its query builder, its caching behavior, its transaction handling.

You didn't reduce total complexity. You traded duplication complexity for abstraction complexity. The essential complexity of database operations remains. You just centralized where it lives. Whether abstraction adds accidental complexity depends on design quality.

Whether that's a good trade? Depends on your context. For a system with many developers, centralizing complexity in an abstraction that a few people deeply understand might be better than distributing complexity across the codebase where everyone encounters it. For a tiny system with two developers, the abstraction might not be worth it: the duplication is manageable, the abstraction is overhead.

This is why "simplification" is such a loaded term. When someone says "let's simplify this," what they usually mean is "let's move complexity from where it bothers me to somewhere else." (Which, to be fair, is sometimes exactly what you want.) But recognize you're relocating complexity, not eliminating it.

Where can complexity go? You can push it to infrastructure: move complexity from application code to Kubernetes, but now you need to understand Kubernetes. You can push it to configuration: move complexity from code to config files, but now configuration management becomes complex. You can push it to runtime: use dynamic dispatch instead of explicit wiring, but behavior becomes harder to trace. You can push it to operations: microservices simplify individual services but operational complexity explodes.

The complexity goes somewhere. It doesn't vanish. Choose consciously where you want it to hurt least.

Pattern 2: Knowledge Relocation

Knowledge can't be reduced, only relocated. You can't reduce what needs to be known about a system. You can only change where that knowledge lives.

Take abstraction layers again: before adding an ORM, knowledge about database queries is distributed across every function that touches the database. After adding an ORM, that knowledge concentrates in the ORM layer. Total knowledge hasn't decreased. You still need to understand how queries work, how connections are managed, how errors are handled. You've just relocated the knowledge.

This creates a trade-off. Distributed knowledge means each piece is simple: local context is enough to understand what's happening. But finding patterns is hard because knowledge is scattered. Global understanding requires synthesizing information from many places.

Concentrated knowledge means finding answers is easy: look in the abstraction layer. But each piece is more complex: the ORM is harder to understand than any individual query was. Which distribution is better depends on your team, your system, your change patterns.

When a new developer asks where logic lives, I can say "check the ORM" instead of "check twenty controllers." Same knowledge needed, better location. But now that developer needs to understand the ORM's complexity.

I've seen teams struggle with this trade-off. A microservices architecture distributes knowledge across service boundaries. Each service is simpler to understand in isolation, but understanding cross-service workflows requires mental synthesis of multiple codebases. A monolith centralizes that knowledge. You can trace a request end-to-end in one codebase, but the concentration makes the monolith harder to navigate.

The knowledge exists either way. The question is: where does it hurt least? If you have autonomous teams, distributing knowledge across service boundaries might work. If you have frequent cross-cutting changes, centralizing knowledge in a monolith might be better. You're not reducing knowledge. You're choosing where developers encounter it.

Pattern 3: Decision Relocation

Decisions can't be eliminated. Every decision must be made somewhere. Moving where decisions happen doesn't reduce total decisions.

Consider configuration. You have a decision: "Which database connection string to use?" You can make it in code: if environment equals production, use this connection; otherwise use that one. Or you can make it in config: read from environment variable or config file. Same decision. Different location. Someone still decides what the database URL is. The decision moved from code to configuration. It didn't disappear.

The choice of where to make decisions has consequences. Compile-time decisions mean fast runtime but slow development: changing behavior requires changing code. Runtime decisions mean slow runtime but fast iteration: change config and restart. Configuration-time decisions mean flexible behavior but configuration becomes complex: now you have configuration management, templating, validation. Convention-based decisions mean simple explicit code but you must learn the conventions. "Magic" behavior that's invisible until you know the pattern.

I've debugged systems where configuration grew so complex it became code by another name. YAML files with conditionals, includes, variable substitution. Essentially a programming language without the tooling. The decisions didn't decrease; they just moved to a less maintainable place.

The reverse is also true. Hard-coding decisions in code means every environment difference requires a code change. I've seen teams with many if-statements checking environment variables because they never moved decisions to configuration. Same total decisions, worse location.

Feature flags are the modern version of this trade-off. You move decisions from deploy time (merge to production) to runtime (toggle in a dashboard). This gives you safety and speed. You can deploy dark and enable gradually. But you pay in testing complexity: with N flags, you have 2^N possible system states. Three flags mean eight configurations to test. Ten flags mean 1,024. The decision didn't disappear. It multiplied.

Pick where decisions happen based on who needs to change them and how often. If operators need to change behavior without deploying code, configuration makes sense. If developers need to understand decision logic during debugging, code makes sense. If the decision rarely changes, hard-coding might be fine. You're not reducing decisions. You're choosing who makes them and when.

Pattern 4: Failure Mode Transformation

Failure modes can't be eliminated. They can only be transformed. You can't eliminate how systems fail. You can only trade failure modes you understand for failure modes you don't.

Moving from synchronous to asynchronous is classic. Synchronous systems fail with timeouts, deadlocks, resource exhaustion when threads block. Asynchronous systems fail with message loss when queues drop messages, ordering issues when messages arrive out of sequence, partial failures when some operations complete and others don't. You traded known failures for different failures. Total failure surface area might even increase.

I've debugged async message loss that took days to track down. With sync systems, timeouts show up immediately in logs. I'm not saying one is better. I'm saying they fail differently, and you're choosing which failure mode you'd rather debug.

The same pattern appears everywhere. Move from monolith to microservices? You trade in-process call failures (immediate stack traces) for network call failures (distributed tracing, timeouts, partial failures). Move from SQL to NoSQL? You trade constraint violations (database enforces referential integrity) for data inconsistency (application must enforce integrity).

I've watched teams adopt new technologies expecting them to be "more reliable," then spend months learning their failure modes. The new system wasn't less reliable. It just failed differently. And the team's existing monitoring, debugging practices, and mental models were all tuned to the old failure modes.

This doesn't mean you shouldn't go async, or adopt microservices, or use NoSQL. It means recognize the trade-off. You're not eliminating failure modes: you're choosing which failure modes you'd rather handle. Maybe async failures are easier to handle in your context. Maybe you have better tools for debugging message loss than deadlocks. Maybe your team has experience with distributed systems failure modes. That's a valid trade. Just don't pretend the old failure modes disappeared: they transformed into new ones. And plan to invest in learning how the new system fails.

Pattern 5: Testing Burden Relocation

Testing burden can't be reduced, only relocated. You can't reduce what needs to be tested. You can only move where testing happens.

Type systems are the clearest example. Without static types, you need more runtime tests because type verification happens at runtime: tests must verify both types and logic. With static types, you need fewer runtime tests because type verification happens at compile time: tests verify logic only, types are checked by the compiler.

Testing effort didn't disappear. It moved from runtime tests to compile-time checks. The shift has trade-offs. Compile-time verification gives faster feedback: you know about type errors before running code. But it adds compilation overhead and can't test runtime-only behaviors like "does this API actually return the structure we expect?" Runtime testing gives slower feedback but tests actual system behavior. Same amount of verification work. Different timing.

The same pattern appears with integration vs. unit tests. Heavy integration testing means you verify actual system behavior but tests are slow and brittle. Heavy unit testing with mocks means tests are fast and isolated but you need integration tests anyway to verify the mocks match reality. The testing burden didn't change. You're choosing between "test real interactions slowly" and "test mock interactions quickly plus verify mocks match."

I've seen teams swing between extremes. All integration tests: comprehensive but painfully slow, so developers avoid running them. All unit tests with mocks: fast but brittle when mocks drift from reality, leading to "tests pass but production fails." The burden exists either way.

The question is: where do you want verification to happen? Early in development (static types, unit tests, compile-time checks) or late in deployment (runtime tests, integration tests, production monitoring)? Each approach has different feedback loops and different failure modes. You're not reducing testing. You're choosing when you discover problems and how much machinery you need to discover them.

Pattern 6: Assumption Visibility Trade-off

Assumptions can't be eliminated, only made explicit or implicit. You can't reduce assumptions. You can only change their visibility.

An implicit assumption looks like this: a function expects user.email to exist and be a string. The code just calls user.email.lower() and hopes. An explicit assumption documents it: add type hints, add null checks, add validation. Same assumption: user must have an email that's a string. Now it's visible instead of hidden.

Implicit assumptions are cheaper to write but expensive to debug. When they're violated, you get cryptic errors: AttributeError: 'NoneType' has no attribute 'lower'. You have to trace back to figure out the assumption. Explicit assumptions are expensive to write but cheap to debug. When they're violated, you get clear errors: ValueError: User must have email. Total cost is conserved. You're choosing when to pay it: upfront with explicit checks, or later when debugging implicit assumptions.

The same trade-off appears with API contracts. Implicit contracts mean less documentation, less validation code, faster development. But when clients violate expectations, you get runtime failures that are hard to diagnose. Explicit contracts mean more upfront work (OpenAPI specs, request validation, comprehensive error messages) but violations are caught immediately with clear feedback.

I've debugged production issues that took hours to diagnose because assumptions were buried deep in code. "Why does this fail for some users but not others?" Eventually you discover an implicit assumption: the code assumes users have an email, but imported users from legacy systems don't. The assumption existed either way. It just wasn't visible until it broke.

The question is: where do you want to pay the cost? Write explicit checks upfront (slower development, clearer debugging) or deal with implicit assumptions when they break (faster development, cryptic failures)? Neither reduces the total assumptions in your system. You're choosing whether to document them in code or discover them during debugging.

Why These Patterns Matter

Once I understood these relocation patterns, how I approached design changed completely. When someone proposes "simplifying" the system, the first question should be: "Where does the complexity go?" It doesn't disappear. It moves. The proposal might still be good: maybe the new location is better. But recognize it's a trade, not an elimination.

This doesn't mean simplification is impossible. You can absolutely reduce total complexity:

Delete dead code: If code contributes nothing to requirements (truly dead), removing it eliminates complexity. No relocation.

Use better abstractions: Replace 50 lines of manual logic with 1-line library call. The library maintains complexity, but amortized across thousands of users, your system's complexity drops.

Remove accidental complexity: Decouple unnecessarily entangled components. Clean up tech debt. Simplify overly complex solutions.

The key: These eliminate accidental complexity. Essential complexity (what the problem inherently requires) is what relocates, not eliminates.

Common examples: "Let's use microservices to simplify development." Where does complexity go? From code organization to service coordination. You trade monolith complexity for distributed system complexity. "Let's add caching to speed things up." Where does complexity go? From query performance to cache management. You trade slow queries for invalidation logic. "Let's make the API more flexible." Where does complexity go? From API code to API consumers. You trade server complexity for client complexity.

These might all be good decisions. But they're trades, not improvements in absolute terms. Microservices might be the right trade if you have the team size and tooling to handle distributed systems. Caching might be right if query performance is your bottleneck and you can handle invalidation. Flexible APIs might be right if you have sophisticated clients and want to iterate server-side less often.

The key is naming what's being relocated and choosing where you want it to live. Before changing anything, identify the relocating quantity: Is this complexity? Where will it move? Is this knowledge? Where will it concentrate? Is this a decision? Where will it happen instead?

How to Work With These Patterns

Where should complexity live? Where will it hurt least?

Example: API design. You can have a complex API with simple client code, or a simple API with complex client code. Neither eliminates complexity: they distribute it differently. Complex API means server handles edge cases, versioning, validation. Clients just call simple methods. Simple API means server provides primitive operations. Clients compose them to handle edge cases.

I've worked with APIs that do everything (clients love it, server team drowns) and APIs that provide primitives (clients write boilerplate but have control). Same complexity, different distribution.

The complexity is conserved. Where should it live? If you have many clients, push complexity to the API: pay the cost once, save it N times. If you have few clients and a rapidly changing server, simple API with complex client code might work fine.

Choose your trades consciously. You can't eliminate conserved quantities. But you can choose better locations. Moving complexity from the hot path to the cold path is usually good: cache invalidation runs less often than queries. Moving complexity from novices to experts is often good: let experienced developers handle the abstraction so junior developers use a simpler interface. Moving complexity from many places to one place is often good: centralize knowledge even if that one place becomes more complex.

But measure both sides. When you move complexity, measure both the source and destination. Code complexity decreased 40%, configuration complexity increased 60%, net result is +20% total complexity. If you only measure one side, you'll think you eliminated complexity. You didn't: you relocated it, and it grew. Measure what you gained and what you paid.

Accept that some things don't simplify. If you keep trying to simplify something and complexity keeps showing up elsewhere, maybe the system has inherent complexity. Some problems are just complex. No architectural cleverness eliminates their complexity. You can only distribute it more or less well. Recognizing irreducible complexity lets you stop fighting it and start managing it.

What Actually Lasts

But step back from the code for a moment. If everything eventually gets rewritten or deleted, what's the point of these choices?

The answer: some things outlast the code. Patterns last. Design patterns outlive implementations. Separation of concerns, dependency injection, event-driven architecture: these patterns transfer across rewrites. The specific code gets replaced but the patterns persist. When you're choosing where complexity lives, you're really choosing patterns. Those patterns will outlast the code.

Understanding lasts. Understanding the domain outlives the code. How the business works, what users need, why systems interact: this knowledge compounds over time. The code gets rewritten but understanding remains. When you're deciding where knowledge should live, invest in shared understanding. Documentation rots but team knowledge grows.

Tests as specification last. Tests document expected behavior. They outlive implementations. When you rewrite, tests preserve requirements while code changes. The investment in test quality pays off when refactoring or replacing code. Tests preserve intent: what should this system do?

Team culture lasts. How your team writes, reviews, and maintains code outlasts any particular codebase. Quality standards, review practices, testing discipline: these transfer to the next system. When you're working with these relocation patterns, you're building patterns of thinking that persist beyond the current code. Invest in culture. It compounds.

The liberation comes from seeing these patterns. Once you understand that complexity relocates rather than disappears, you stop looking for solutions that eliminate it. You look for solutions that put complexity where it belongs. You measure both sides of the trade. You name what's being relocated and choose where it lives. And you invest in what actually lasts: patterns, understanding, and culture. While accepting that code is temporary.

These relocation patterns aren't limitations. They're reality. You can't violate them. But you can work with them. And working with them is better than pretending they don't exist.

Note: Originally published on ITNEXT: https://itnext.io/complexity-cant-be-eliminated-it-can-only-be-moved-d122f7952715