@base <https://addyosmani.com/blog/comprehension-debt/> .
@prefix schema: <https://schema.org/> .
@prefix owl: <https://www.w3.org/2002/07/owl#> .

<#article> a schema:Article ;
  schema:headline "Comprehension Debt - the hidden cost of AI generated code."@en ;
  schema:name "Comprehension Debt - the hidden cost of AI generated code."@en ;
  schema:datePublished "2026-03-14" ;
  schema:inLanguage "en" ;
  schema:url <https://addyosmani.com/blog/comprehension-debt/> ;
  schema:publisher <#addy-osmani-site> ;
  schema:author <#addy-osmani> ;
  schema:about
    <#comprehension-debt>,
    <#cognitive-debt>,
    <#agentic-engineering>,
    <#speed-asymmetry>,
    <#review-bottleneck>,
    <#false-confidence>,
    <#conceptual-inquiry>,
    <#passive-delegation>,
    <#deterministic-verification>,
    <#specification-limit>,
    <#measurement-gap>,
    <#regulation-horizon> ;
  schema:articleSection
    "There is a speed asymmetry problem here"@en,
    "I love tests, but they aren't a complete answer"@en,
    "Lean on specs, but they're also not the full story."@en,
    "Learn from history"@en,
    "There's a bit of a measurement gap here too"@en,
    "The regulation horizon is closer than it looks"@en,
    "What comprehension debt actually demands"@en ;
  schema:abstract """The article argues that excessive reliance on AI-generated code creates a hidden gap between what exists in a codebase and what humans genuinely understand, and that this gap compounds like debt."""@en ;
  schema:articleBody """Addy Osmani argues that AI coding tools create comprehension debt when code is produced faster than teams can meaningfully review and understand it. Unlike technical debt, this problem often hides behind clean diffs, passing tests, and strong velocity metrics. The post draws on Anthropic research showing weaker comprehension outcomes under passive AI delegation, argues that tests and specs cannot substitute for genuine understanding, and claims that the scarce resource in AI-heavy software teams becomes the engineer who truly understands system behavior and architectural context. The article also warns that current organizational metrics fail to capture this risk and that regulated domains will eventually force stronger comprehension discipline."""@en ;
  schema:hasPart
    <#part-definition>,
    <#part-speed>,
    <#part-tests>,
    <#part-specs>,
    <#part-measurement>,
    <#part-regulation>,
    <#part-demands> ;
  schema:mentions
    <#defined-terms>,
    <#argument-howto>,
    <#faq-1>, <#faq-2>, <#faq-3>, <#faq-4>, <#faq-5>,
    <#faq-6>, <#faq-7>, <#faq-8>, <#faq-9>, <#faq-10>,
    <#anthropic>,
    <#margaret-anne-storey>,
    <#simon-willison>,
    <#dora-metrics>,
    <#ai-coding-agents> .

<#addy-osmani-site> a schema:Blog ;
  schema:name "AddyOsmani.com"@en ;
  schema:url <https://addyosmani.com/> ;
  schema:publisher <#addy-osmani> .

<#addy-osmani> a schema:Person ;
  schema:name "Addy Osmani"@en ;
  schema:url <https://addyosmani.com/> ;
  schema:jobTitle "Software Engineer"@en .

<#anthropic> a schema:Organization ;
  schema:name "Anthropic"@en ;
  schema:url <https://www.anthropic.com/> .

<#margaret-anne-storey> a schema:Person ;
  schema:name "Margaret-Anne Storey"@en .

<#simon-willison> a schema:Person ;
  schema:name "Simon Willison"@en ;
  schema:url <https://simonwillison.net/> .

<#dora-metrics> a schema:DefinedTerm ;
  schema:name "DORA metrics"@en ;
  schema:description """Deployment and delivery performance metrics that the article uses as examples of output measures that can look healthy while comprehension quietly deteriorates."""@en .

<#ai-coding-agents> a schema:SoftwareApplication, schema:Product ;
  schema:name "AI coding agents"@en ;
  schema:applicationCategory "AI software development assistant"@en ;
  schema:description """The class of tools the article discusses as accelerating code generation beyond human review capacity."""@en .

<#comprehension-debt> a schema:DefinedTerm ;
  schema:name "Comprehension debt"@en ;
  schema:description """The hidden gap between how much code exists in a system and how much of it any human genuinely understands, especially under heavy AI code generation."""@en .

<#cognitive-debt> a schema:DefinedTerm ;
  schema:name "Cognitive debt"@en ;
  schema:description """A closely related label for the same phenomenon, emphasizing the burden placed on memory, reasoning, and team-level understanding."""@en .

<#agentic-engineering> a schema:DefinedTerm ;
  schema:name "Agentic engineering"@en ;
  schema:description """The article's context for comprehension debt: software work where AI systems generate or transform substantial amounts of code on behalf of engineers."""@en .

<#speed-asymmetry> a schema:DefinedTerm ;
  schema:name "Speed asymmetry"@en ;
  schema:description """The imbalance where AI produces code far faster than human reviewers can critically audit and understand it."""@en .

<#review-bottleneck> a schema:DefinedTerm ;
  schema:name "Review bottleneck inversion"@en ;
  schema:description """The article's argument that review used to be educational and quality-enhancing, but AI turns it into a throughput problem because output volume overwhelms reviewers."""@en .

<#false-confidence> a schema:DefinedTerm ;
  schema:name "False confidence"@en ;
  schema:description """The dangerous signal pattern where clean code, passing tests, and high output create the illusion of system health despite declining understanding."""@en .

<#conceptual-inquiry> a schema:DefinedTerm ;
  schema:name "Conceptual inquiry"@en ;
  schema:description """The article's preferred AI usage mode: using models to ask questions, explore tradeoffs, and support thinking rather than delegating implementation blindly."""@en .

<#passive-delegation> a schema:DefinedTerm ;
  schema:name "Passive delegation"@en ;
  schema:description """The usage pattern of telling AI to 'just make it work,' which the article says harms comprehension and skill formation more than active inquiry."""@en .

<#deterministic-verification> a schema:DefinedTerm ;
  schema:name "Deterministic verification"@en ;
  schema:description """The family of checks such as unit tests, integration tests, static analysis, linters, and formatters that the article considers useful but insufficient."""@en .

<#specification-limit> a schema:DefinedTerm ;
  schema:name "Specification limit"@en ;
  schema:description """The article's argument that even detailed natural-language specs cannot capture all implicit implementation decisions or eliminate the need to understand produced code."""@en .

<#measurement-gap> a schema:DefinedTerm ;
  schema:name "Measurement gap"@en ;
  schema:description """The absence of common engineering metrics that capture how much of a codebase teams actually understand rather than merely produce or test."""@en .

<#regulation-horizon> a schema:DefinedTerm ;
  schema:name "Regulation horizon"@en ;
  schema:description """The article's claim that highly regulated domains will not accept 'the AI wrote it and we did not fully review it' as a credible post-incident explanation."""@en .

<#defined-terms> a schema:DefinedTermSet ;
  schema:name "Defined terms for Comprehension Debt"@en ;
  schema:hasPart
    <#comprehension-debt>,
    <#cognitive-debt>,
    <#agentic-engineering>,
    <#speed-asymmetry>,
    <#review-bottleneck>,
    <#false-confidence>,
    <#conceptual-inquiry>,
    <#passive-delegation>,
    <#deterministic-verification>,
    <#specification-limit>,
    <#measurement-gap>,
    <#regulation-horizon> ;
  schema:isPartOf <#article> .

<#part-definition> a schema:WebPageElement ;
  schema:name "What comprehension debt is"@en ;
  schema:position 1 ;
  schema:about <#comprehension-debt>, <#false-confidence> ;
  schema:text """The article defines comprehension debt as the hidden gap between code volume and real human understanding, a problem that often stays invisible until a critical change or incident."""@en .

<#part-speed> a schema:WebPageElement ;
  schema:name "The speed asymmetry problem"@en ;
  schema:position 2 ;
  schema:about <#speed-asymmetry>, <#review-bottleneck> ;
  schema:text """The article argues that AI now generates code faster than senior engineers can critically review it, turning review from a quality gate into a throughput problem."""@en .

<#part-tests> a schema:WebPageElement ;
  schema:name "Why tests are not enough"@en ;
  schema:position 3 ;
  schema:about <#deterministic-verification>, <#conceptual-inquiry>, <#passive-delegation> ;
  schema:text """Tests help but cannot specify unseen failures, validate every changed assumption, or replace understanding of why behavior changed in the first place."""@en .

<#part-specs> a schema:WebPageElement ;
  schema:name "Why specs are not the full story"@en ;
  schema:position 4 ;
  schema:about <#specification-limit> ;
  schema:text """The article argues that natural-language specs cannot encode every implementation choice and that a spec detailed enough to replace review would nearly become the program itself."""@en .

<#part-measurement> a schema:WebPageElement ;
  schema:name "The measurement gap"@en ;
  schema:position 5 ;
  schema:about <#measurement-gap>, <#dora-metrics> ;
  schema:text """Velocity, PR count, and coverage metrics may all look healthy while comprehension erodes, because organizations rarely measure actual understanding."""@en .

<#part-regulation> a schema:WebPageElement ;
  schema:name "The regulation horizon"@en ;
  schema:position 6 ;
  schema:about <#regulation-horizon> ;
  schema:text """The article predicts that AI-generated code in healthcare, finance, and government will eventually face regulatory scrutiny that demands real human understanding and accountability."""@en .

<#part-demands> a schema:WebPageElement ;
  schema:name "What comprehension debt demands"@en ;
  schema:position 7 ;
  schema:about <#comprehension-debt>, <#conceptual-inquiry> ;
  schema:text """The post concludes that teams must optimize for understanding what they ship, not just for generating more code or collecting more green checks."""@en .

<#argument-howto> a schema:HowTo ;
  schema:name "How the article builds the comprehension debt argument"@en ;
  schema:about <#comprehension-debt>, <#regulation-horizon> ;
  schema:isPartOf <#article> ;
  schema:step <#step-1>, <#step-2>, <#step-3>, <#step-4> ;
  schema:description """The article moves from definition, to review dynamics, to the limits of tests and specs, and finally to organizational and regulatory consequences."""@en .

<#step-1> a schema:HowToStep ;
  schema:name "Define the hidden debt"@en ;
  schema:position 1 ;
  schema:text "The post first names comprehension debt as the difference between code that exists and code that people truly understand."@en ;
  schema:isPartOf <#argument-howto> .

<#step-2> a schema:HowToStep ;
  schema:name "Show why AI worsens review dynamics"@en ;
  schema:position 2 ;
  schema:text "AI output volume exceeds meaningful review capacity, so previously educational review habits stop functioning as reliable quality gates."@en ;
  schema:isPartOf <#argument-howto> .

<#step-3> a schema:HowToStep ;
  schema:name "Reject tests and specs as complete substitutes"@en ;
  schema:position 3 ;
  schema:text "The article argues that verification and specification are necessary but cannot cover unimagined failures or all implicit implementation decisions."@en ;
  schema:isPartOf <#argument-howto> .

<#step-4> a schema:HowToStep ;
  schema:name "Reframe the job around understanding"@en ;
  schema:position 4 ;
  schema:text "The conclusion is that the core engineering task remains understanding what was built, why it behaves as it does, and whether its implicit decisions are sound."@en ;
  schema:isPartOf <#argument-howto> .

<#faq-1> a schema:Question ;
  schema:name "What is comprehension debt?"@en ;
  schema:text "What is comprehension debt?"@en ;
  schema:acceptedAnswer <#faq-1-answer> ;
  schema:isPartOf <#article> .
<#faq-1-answer> a schema:Answer ;
  schema:text "It is the hidden gap between how much code exists in a system and how much of that code any human genuinely understands."@en ;
  schema:isPartOf <#article> .

<#faq-2> a schema:Question ;
  schema:name "Why is comprehension debt harder to see than technical debt?"@en ;
  schema:text "Why is comprehension debt harder to see than technical debt?"@en ;
  schema:acceptedAnswer <#faq-2-answer> ;
  schema:isPartOf <#article> .
<#faq-2-answer> a schema:Answer ;
  schema:text "Because code can look clean, tests can stay green, and delivery metrics can improve while actual understanding silently degrades."@en ;
  schema:isPartOf <#article> .

<#faq-3> a schema:Question ;
  schema:name "What is the speed asymmetry problem?"@en ;
  schema:text "What is the speed asymmetry problem?"@en ;
  schema:acceptedAnswer <#faq-3-answer> ;
  schema:isPartOf <#article> .
<#faq-3-answer> a schema:Answer ;
  schema:text "AI can generate code faster than humans can critically evaluate it, so review becomes a throughput problem rather than a deep understanding process."@en ;
  schema:isPartOf <#article> .

<#faq-4> a schema:Question ;
  schema:name "Why are tests not a complete answer?"@en ;
  schema:text "Why are tests not a complete answer?"@en ;
  schema:acceptedAnswer <#faq-4-answer> ;
  schema:isPartOf <#article> .
<#faq-4-answer> a schema:Answer ;
  schema:text "Tests only validate what people thought to specify, and they cannot determine whether broad behavior changes or mass test updates are actually justified."@en ;
  schema:isPartOf <#article> .

<#faq-5> a schema:Question ;
  schema:name "Why are detailed specs not enough either?"@en ;
  schema:text "Why are detailed specs not enough either?"@en ;
  schema:acceptedAnswer <#faq-5-answer> ;
  schema:isPartOf <#article> .
<#faq-5-answer> a schema:Answer ;
  schema:text "Because implementation still involves countless implicit decisions, and a spec complete enough to replace review would approach the complexity of the program itself."@en ;
  schema:isPartOf <#article> .

<#faq-6> a schema:Question ;
  schema:name "What kind of AI use preserves understanding better?"@en ;
  schema:text "What kind of AI use preserves understanding better?"@en ;
  schema:acceptedAnswer <#faq-6-answer> ;
  schema:isPartOf <#article> .
<#faq-6-answer> a schema:Answer ;
  schema:text "The article points to conceptual inquiry, where developers use AI to ask questions and explore tradeoffs rather than delegate implementation passively."@en ;
  schema:isPartOf <#article> .

<#faq-7> a schema:Question ;
  schema:name "What does the Anthropic study contribute to the argument?"@en ;
  schema:text "What does the Anthropic study contribute to the argument?"@en ;
  schema:acceptedAnswer <#faq-7-answer> ;
  schema:isPartOf <#article> .
<#faq-7-answer> a schema:Answer ;
  schema:text "It provides empirical evidence that passive AI code generation can reduce comprehension scores, especially in debugging, even when task completion time stays similar."@en ;
  schema:isPartOf <#article> .

<#faq-8> a schema:Question ;
  schema:name "Why does the article say senior engineers become more valuable under heavy AI use?"@en ;
  schema:text "Why does the article say senior engineers become more valuable under heavy AI use?"@en ;
  schema:acceptedAnswer <#faq-8-answer> ;
  schema:isPartOf <#article> .
<#faq-8-answer> a schema:Answer ;
  schema:text "Because the scarce capability becomes system-level judgment: knowing which behaviors are load-bearing and which changes are quietly dangerous."@en ;
  schema:isPartOf <#article> .

<#faq-9> a schema:Question ;
  schema:name "What is the measurement gap?"@en ;
  schema:text "What is the measurement gap?"@en ;
  schema:acceptedAnswer <#faq-9-answer> ;
  schema:isPartOf <#article> .
<#faq-9-answer> a schema:Answer ;
  schema:text "It is the absence of standard organizational metrics that capture real understanding rather than output volume, coverage, or velocity."@en ;
  schema:isPartOf <#article> .

<#faq-10> a schema:Question ;
  schema:name "What practical demand does comprehension debt impose on teams?"@en ;
  schema:text "What practical demand does comprehension debt impose on teams?"@en ;
  schema:acceptedAnswer <#faq-10-answer> ;
  schema:isPartOf <#article> .
<#faq-10-answer> a schema:Answer ;
  schema:text "Teams must treat genuine understanding of shipped behavior as non-negotiable instead of assuming that passing tests or clean diffs are enough."@en ;
  schema:isPartOf <#article> .