DEV Community: David Silva

Comprehension Debt: The Hidden Cost of AI-Generated Code

David Silva — Sun, 17 May 2026 17:24:36 +0000

Comprehension Debt: The Hidden Cost of AI-Generated Code

"You're not a developer anymore. You're a reviewer of code you don't understand."

That line from The Serious CTO named something I’d been feeling but couldn’t articulate. With AI, the volume of code we ship has completely decoupled from the amount of code any human actually understands.

I call this comprehension debt — the gap between the code in our systems and the knowledge in our teams’ heads. And I believe it’s the most important kind of debt our industry has accumulated in the past two years.

It’s not technical debt

Ward Cunningham’s original “technical debt” was a conscious trade-off. Comprehension debt is different.

It isn’t deliberate.

It isn’t local.

And it doesn’t show up on any dashboard.

What the dashboards actually measure

DORA, Flow, and even the new AI Impact metrics all measure motion — speed, volume, acceptance rates, deployment frequency. None of them measure whether anyone on the team can still explain the code they shipped last quarter.

The standard answers fall short

More code review, more linters, more tests, and “future AI will fix it” don’t solve comprehension debt. They mostly create the illusion of safety.

What it looks like in practice

Fields nobody can explain, controllers with dead branches, 2am incidents where the on-call engineer can read the stack trace but can’t narrate the logic. Individually minor. Collectively, the new shape of legacy code — built at unprecedented speed.

What should we do instead?

I don’t have perfect answers yet, but I know the solution isn’t “more of the same.” We need to actively maintain comprehension as a first-class team property.

Originally published on my blog:

https://davidslv.uk/2026/05/17/comprehension-debt.html

What do you think?

Have you seen comprehension debt in your own teams? What (if anything) are you doing about it?

Your AI is Only as Good as the System You Give It (Most Engineers Get This Backwards)

David Silva — Thu, 07 May 2026 18:00:00 +0000

Every developer I know uses AI the exact same way:

Open ChatGPT or Claude.

Paste some code.

Explain their architecture from scratch.

Cross their fingers and hope for a useful answer.

It works… sort of.

Like Googling Stack Overflow in 2015 — you get something, you tweak it, and you move on.

But every single time, you start from zero.

The AI doesn’t know your architecture decisions.

It doesn’t remember the convention your team agreed on last month.

It has no idea you stopped using callbacks for cross-domain side effects.

It doesn’t know you.

So you repeat yourself. Every session. Every project. Every day.

Six months ago I got tired of it.

I stopped treating AI like a clever junior developer and started treating it like a senior team member — one that actually knows the system.

Here’s exactly how I built that system.

Most engineers use AI the same way. Open a chat. Type a question. Get an answer. Repeat.

The engineers getting disproportionate value from AI aren't better at prompting. They've built a better system around the AI. The difference isn't in how they ask — it's in what the AI already knows before they ask.

The Context Problem

AI without context produces confident, generic, and often wrong output.

Ask it to "write a service object" and you’ll get something syntactically correct that violates every convention your team has established. Ask it to "review this pull request" and it gives surface-level feedback that completely misses the architectural implications.

This isn’t an AI limitation.

It’s a systems problem.

You wouldn’t expect a new hire to be productive on day one without onboarding, codebase access, and decision context. Yet most engineers give their AI less context than they’d give an intern.

The fix isn’t better prompts.

The fix is better infrastructure.

Making Your Knowledge Machine-Readable

The first step has nothing to do with AI configuration. It’s about organizing your own knowledge so any tool (AI or otherwise) can navigate it.

I use the PARA method (Projects, Areas, Resources, Archives):

Projects — Active work with deadlines
Areas — Ongoing responsibilities
Resources — Reference material
Archives — Completed work

When your knowledge lives in structured directories with consistent naming and Markdown files, an AI agent can actually traverse and understand it. Architectural decisions, coding conventions, and team agreements become readable instead of living in Slack threads or someone’s head.

The investment isn’t in AI tooling.

It’s in the discipline of writing things down in a format that’s both human and machine-readable.

Giving the AI Project Context

Once your knowledge is organized, create a short project context document (usually 10–20 lines) for every active project.

This document acts as an operating manual for the AI. It includes:

What the project does
Key architecture decisions
Important conventions
Constraints and non-negotiables

Instead of explaining your architecture every time, you just point the AI at this file. The difference is immediate: it stops generating generic code and starts generating code that actually fits your system.

Ten minutes of writing saves hours of back-and-forth.

Codifying Your Workflows

Context tells the AI about your world.

Workflows tell it how you operate inside that world.

Write down your repeatable processes in plain Markdown:

How you run tests
How you deploy
How you create pull requests
How you write commit messages
How you review code

When these workflows are explicit, the AI can follow them exactly — not approximately. Your deployment checklist, code review rules, and architectural guardrails become repeatable.

This turns implicit senior knowledge into consistent, executable process.

Connecting to Your Tools

Stop copy-pasting.

Modern AI tools can connect directly to your GitHub, monitoring systems, error trackers, and CI pipelines. Every time you find yourself copying data into a chat, that’s a connection you should make.

The fewer manual steps, the more powerful the AI becomes.

Setting Guardrails

The more autonomy you give AI, the more important boundaries become.

Define hard rules:

Never commit credential files
Never run destructive database commands without confirmation
Never force-push to main
Respect engine boundaries

These guardrails let you give the AI more freedom safely — the same way good CI/CD pipelines protect production.

The Principle

AI amplifies whatever system you give it.

Give it no system and it amplifies chaos — confident, well-formatted chaos.

Give it structured knowledge, persistent context, codified workflows, tool connections, and clear guardrails, and it becomes one of the most valuable colleagues you have.

The engineers who will get the most out of AI in the coming years won’t be the best prompt engineers.

They’ll be the best systems engineers.

If you want a starting point, I’ve open-sourced my own template based on the PARA method:

→ ben-ai-system

What’s one piece of context you wish your AI already knew about your projects? Drop it in the comments.

The Tailwind Debate Isn't About CSS — It's About Abstraction Layers (And Why Most People Get It Wrong)

David Silva — Wed, 06 May 2026 19:44:15 +0000

Two posts appeared on Dev.to a few days ago. One titled "I Love Tailwind — Sorry Not Sorry." The other: "I Don't Like Tailwind — Sorry Not Sorry."

Same format. Opposite conclusions. Hundreds of comments. The community tearing itself apart over utility classes.

I've seen this fight before. So have you.

Microservices vs monoliths. Raw SQL vs ORMs. REST vs GraphQL. Vim vs Emacs if you've been around long enough. The technology changes. The argument doesn't.

It's always about the same thing: should you use primitives directly, or build an abstraction on top of them?

Tailwind gives you utility classes. Small, single-purpose, composable. That's the primitive layer. And at that level, it's genuinely well-designed. The design tokens are consistent. The naming conventions make sense. The build system strips what you don't use.

The problem isn't Tailwind. The problem is using the primitive layer as your application layer.

When your HTML looks like this:

<a class="mt-4 px-6 py-2 bg-blue-500 hover:bg-blue-700 text-white font-bold rounded-lg shadow-md transition-colors duration-200">example</a>

You haven't eliminated CSS complexity. You've moved it. It's the same information, scattered across templates instead of collected in stylesheets. At scale, those class strings become just as unreadable as the CSS they replaced. Arguably worse — because at least CSS has selectors that name things.

The teams that love Tailwind? They're not writing those class strings everywhere. They're using it as a foundation for component libraries. DaisyUI. Shadcn. Headless UI. They write the utility classes once, inside a component, and the rest of the application uses the component. The abstraction layer does the work.

This is the same principle as software architecture. You don't scatter database queries across your controllers. You build a model layer. You don't scatter HTTP calls across your views. You build a service layer. The primitive exists so you can build on top of it, not so you can use it directly in every file.

Microservices vs monoliths is the same argument at a different scale. Microservices are the primitives — small, single-purpose, independently deployable. Powerful at the infrastructure level. But if every feature requires coordinating five services, you haven't reduced complexity. You've distributed it. The teams that succeed with microservices are the ones that build the right abstraction layer on top: API gateways, service meshes, shared libraries, or — more often than the industry admits — they merge services back into a modular monolith and keep the boundaries without the network calls.

The pattern repeats because the underlying tension is real. Primitives give you power and flexibility. Abstractions give you readability and maintainability. You need both. The question is where the boundary sits.

Use Tailwind? Fine. Build components on top of it. Use microservices? Fine. Make sure the abstraction layer justifies the distribution cost. Use raw SQL? Fine. Wrap it in something that names what it does.

The tool is never the problem. The problem is mistaking the primitive layer for the finished architecture.

Every few years we have this argument again, wearing different clothes. The answer is always the same: build on top of your primitives. Don't scatter them everywhere.

Stop Rewriting Your Ruby on Rails Monolith as Microservices — Use Engines Instead (Here's How)

David Silva — Wed, 06 May 2026 12:54:31 +0000

This is an adapted excerpt from Chapter 1 of Modular Rails: Architecture for the Long Game, my book on building maintainable Ruby on Rails applications using Rails Engines.

"The goal of software architecture is to minimize the human resources required to build and maintain the required system."
-- Robert C. Martin, Clean Architecture

The Cost of Change Over Time

Every Software Engineer that uses Ruby on Rails has lived this story. The application starts small. A handful of models, a few controllers, a test suite that runs in seconds. Adding a feature is straightforward -- you create a model, write a migration, build a controller, add some views. The framework guides you. Convention over configuration. Life is good.

Then the application grows. The app/models directory fills up. The User model gains associations to everything. Service objects proliferate in app/services/. Someone introduces an app/interactors/ directory. Then app/queries/. Then app/decorators/. Each new directory is a well-intentioned attempt to manage complexity, but none of them create actual boundaries. Everything can still reference everything.

At this point, the cost of change starts to climb. Not linearly -- exponentially. A small change to the billing logic triggers test failures in the notification suite. A database migration for user preferences locks a table that the checkout flow depends on.

Let's make this concrete. You add a discount field to invoices -- a straightforward billing change:

$ bin/rails test test/models/billing/invoice_test.rb
# 3 tests, 3 assertions, 0 failures

$ bin/rails test
# 847 tests, 1203 assertions, 4 failures
# Failures in: notification_mailer_test.rb, report_generator_test.rb,
#              admin_dashboard_test.rb, webhook_handler_test.rb

Four failures in four files that have nothing to do with discounts. None of these files are in the billing/ directory. None of them showed up when you grepped for the code you changed. But they all reached into the invoice model directly, without going through any kind of boundary.

Now imagine the same change in a codebase where billing lives inside an engine:

$ cd engines/billing && bundle exec rspec
# 94 examples, 0 failures

$ cd ../.. && bundle exec rspec
# 312 examples, 0 failures

Zero collateral damage. The engine's boundary means billing tests only load billing code. If the billing tests pass, the change is safe.

This is not a Rails problem. This is an architecture problem. Or more precisely, it's the absence of architecture.

Conway's Law and Team Structure

In 1968, Melvin Conway observed that "any organization that designs a system will produce a design whose structure is a copy of the organization's communication structure."

If your team is structured as a single unit working on a single codebase with no internal boundaries, the application will reflect that: a single, undifferentiated mass where everything knows about everything.

But Conway's Law also works in reverse -- the "Inverse Conway Manoeuvre" (coined by Jonny LeRoy and Matt Simons in 2010, and later popularised by James Lewis and Martin Fowler). If you structure your codebase into well-bounded modules, each with a clear domain and interface, you create natural team boundaries. The billing engine has an owner. The notification engine has an owner. Changes to billing don't require coordination with the notification team because the engine boundary makes the coupling explicit and manageable.

In a Rails context, this means that your app/ directory structure isn't just a filing system. It's an organisational decision. And app/models/ with 200 files in it is an organisational decision that says "everyone works on everything, and good luck coordinating."

Deferring Decisions

Perhaps the most counterintuitive idea in software architecture comes from Robert C. Martin:

"A good architect pretends that the decision has not been made, and shapes the system such that those decisions can still be deferred or changed for as long as possible."

Here's what a deferred decision looks like in code. Your billing engine needs a payment gateway, but the right choice depends on which markets you'll launch in -- information you don't have yet:

# engines/billing/lib/billing.rb
module Billing
  mattr_accessor :payment_gateway, default: "Billing::Gateways::Stripe"
end

The business logic calls Billing.payment_gateway.constantize.new and never mentions Stripe, Adyen, or anyone else by name. When the business decides to expand into a market where Stripe isn't available, you write a new gateway class and change one line of configuration. No billing logic changes. No tests break.

That boundary is itself a deferred decision. By keeping billing isolated in an engine, you've deferred the decision about whether billing should be a separate service, a separate application, or remain part of the monolith. You can make that decision later, with more information, at lower cost.

This is the essence of good architecture: not making the perfect decision now, but structuring the system so that you can make the right decision later.

This was Chapter 1 of Modular Rails: Architecture for the Long Game. The book covers 18 chapters across four parts -- from Clean Architecture principles to extracting your first engine, testing strategies, team workflow, and the honest trade-offs most architecture books skip.

Get the book on Amazon UK · Amazon US · Learn more

I Built a Dungeon Crawler Game in Ruby (And It Actually Works)

David Silva — Sat, 22 Nov 2025 11:24:00 +0000

When I tell people I'm building a game in Ruby, I get looks.

"Ruby? For a game? Isn't that... slow?"

Fair question. Most game developers reach for C++, C#, or Unity. Ruby is for web apps, not games. Everyone knows this.

Except I've been building a roguelike – a procedurally generated dungeon crawler inspired by the 1980s classic Rogue – in Ruby for six months now, and it's been brilliant.

What I'm Building

Think classic dungeon crawler: ASCII graphics, procedurally generated mazes, turn-based movement, permadeath. Your character (@) navigates randomly generated dungeons, fighting monsters, collecting items, trying not to die.

It runs entirely in the terminal. No fancy graphics. Just pure game logic and procedural generation.

The Unconventional Choice

I'm not a game developer by training. I build web applications and APIs. So choosing Ruby for a game felt both natural and slightly mad.

But here's the thing: I wasn't building a AAA title. I was building a turn-based game that runs in the terminal. My bottleneck wasn't performance. It was understanding game architecture.

For that, Ruby's clarity was perfect.

Rapid Iteration Changed Everything

No compilation step. No waiting. Just change the code and run it.

I implemented four different maze generation algorithms: Binary Tree, Aldous-Broder, Recursive Backtracker, and Recursive Division. Here's how simple the Binary Tree algorithm looks:

class BinaryTree < AbstractAlgorithm
  def self.on(grid)
    grid.each_cell do |cell|
      has_north = !cell.north.nil?
      has_east = !cell.east.nil?

      if has_north && has_east
        cell.link(cell: rand(2) == 0 ? cell.north : cell.east, bidirectional: true)
      elsif has_north
        cell.link(cell: cell.north, bidirectional: true)
      elsif has_east
        cell.link(cell: cell.east, bidirectional: true)
      end
    end

    grid
  end
end

Look at that. grid.each_cell reads like English. The logic is clear: randomly connect each cell either north or east. I could tweak this, run it, see results immediately. No fuss.

When you're learning game architecture – which I was – this feedback loop is invaluable.

Components Stay Simple

The core of my game uses Entity-Component-System (ECS) architecture. Components should be pure data containers, and Ruby makes this trivial:

class PositionComponent < Component
  attr_reader :row, :column

  def initialize(row:, column:)
    super()
    @row = row
    @column = column
  end

  def set_position(row, column)
    @row = row
    @column = column
  end
end

That's my entire PositionComponent. No boilerplate. No getters and setters cluttering the code. Ruby's attr_reader handles it. Named parameters make it obvious what you're passing:

position = PositionComponent.new(row: 5, column: 10)

Compare this to languages where you need builder patterns just to maintain readability. Ruby gets out of your way.

What About Performance?

Let's be honest: Ruby isn't fast.

For my use case? Didn't matter. The game is turn-based. It waits for player input. The bottleneck is human reaction time, not Ruby's execution speed.

Maze generation on an 80×40 grid? Milliseconds. Entity queries with dozens of entities? Trivial. If I were building a real-time action game with hundreds of entities updating 60 times per second, Ruby would be the wrong choice.

But I wasn't. Context matters.

Developer Joy Matters Too

Here's what I didn't expect: Ruby made me happy while coding.

When I write entity.has_component?(:position), it reads like a question I'd ask a colleague. The code communicates intent clearly. I could focus on understanding ECS, event systems, and procedural generation rather than fighting with syntax.

When you're building something complex in your spare time, enjoyment matters. If I'd chosen a language I found frustrating, I might have abandoned the project.

The Result

The game now has procedurally generated mazes, an Entity-Component-System architecture, event-driven logging, command-based input handling, and 48 spec files of test coverage.

Not bad for a language supposedly "not meant for games."

Want the full story? I wrote a comprehensive article on my blog covering the complete architecture, testing strategy, and lessons learned: Why I Chose Ruby to Build a Roguelike Game

The code is open source on GitHub if you want to see how it all fits together.

P.S. – I documented this entire journey in a book: Building Your Own Roguelike: A Practical Guide. It walks through building this from scratch – the ECS pattern, event systems, maze generation algorithms, and everything you see in Vanilla Roguelike.

Thank you for reading,
David Silva