# Your Code Looks Professional. Can You Explain It?

AI-assisted programming broke the link between how sophisticated software looks and how well its authors understand it. A practical test for spotting comprehension debt in your own work.

Published: 2026-07-21
Tags: ai-engineering, engineering-practices, software-engineering, ai-agents, code-review, maintainability

---
## The pull request that looks perfect

Picture a pull request with clear layers, green unit and integration tests, structured logs, metrics, traces, typed inputs, and careful error handling. It looks better than most code written by hand, at least by me.

Now ask a different set of questions. Why was this architecture chosen? What requirement justified each layer? What behavior do those tests actually protect, and which ones only confirm what the implementation already does? What would break if you removed one component? Could the author rebuild the core of this system without asking the agent again? Could they debug it at 2 a.m. during a production incident while Claude Code is offline?

If the answers are thin, the pull request shows that the model can reproduce the signals of engineering maturity. It does not show that its author understands the system. This post offers a practical test for finding that gap in your own work.

This is the individual counterpart to [Code Review in the AI Era](/posts/code-review-in-the-ai-era-we-need-to-change/), which focuses on teams and process. Here the question is whether *you* understand the code in front of you.

## The correlation AI broke

Before generative AI, producing a sophisticated artifact usually required a long sequence of decisions, mistakes, and revisions. That process never guaranteed mastery: systems have always been copied, outsourced, and cargo-culted. It did, however, create a rough correlation between building the artifact and understanding it.

AI weakens that correlation. An agent can generate modules, architectural decisions, and whole file trees before anyone has formed a mental model of them. The change is not only speed: you can acquire the result without going through the process that once produced understanding as a byproduct.

Stack Overflow, libraries, frameworks, and outsourcing already let us use work we did not produce. Agents increase the scale and speed of that delegation.

Research on GitHub Copilot found that developers liked the tool yet struggled to understand, edit, and debug its output. A systematic review describes the same shift: AI assistance moves effort from writing code toward understanding, verifying, and integrating it. Fast implementation does not remove the work of building a mental model.

Ahmad calls this gap *comprehension debt*: the difference between what a team knows about its codebase and what it needs to know to maintain and change it. The 2026 study relies on student reflective diaries, so it does not establish that professional teams experience the same patterns at the same intensity. I use the concept here as a practical diagnostic, not a validated professional measure.

## The illusion of sophistication

Agents readily produce the signals we read as "well engineered." Those signals do not prove what we often infer from them.

| What we can observe | What it does not prove |
|---|---|
| The code compiles and the tests pass | That anyone understands the decisions |
| The architecture looks organized | That it matches the actual requirements |
| Documentation exists | That it describes the current system |
| Dashboards show metrics | That they would help during an incident |
| The pipeline runs and the deploy works | That the team can safely change the code |
| Errors are handled and inputs are typed | That the failure modes were actually considered |

These signals still matter. The mistake is treating their presence as evidence that someone understands the system.

Eye-tracking experiments found that model-generated code was rated about as readable as human-written code but received less visual attention. In security tasks, participants using an AI assistant produced less secure code while feeling more confident that it was safe. This fits the established pattern of automation bias: polished output can lower scrutiny when it should increase it.

## The five questions

"It works" and "it looks clean" are not enough. I use five questions to decide whether I understand a piece of software or merely possess its files. I derived them with an LLM from the research below and my own experience. They are a starting point, not a validated scale.

### Can I explain it?

- What problem does this component solve?
- How does data flow through the system?
- Which invariants must stay true for it to keep working?
- Where are the main boundaries and states?

### Can I modify it?

- Can I change a requirement without regenerating the whole solution?
- Do I know which components a change will touch?
- Can I preserve the important properties while I change the code?

### Can I diagnose it?

- Given a failure, do I know which hypotheses to investigate first?
- Can I map a symptom back to a component?
- Was the observability designed around real failure modes, or just switched on?

### Can I justify it?

- Why was this architecture chosen?
- Which alternatives were considered and rejected?
- Which requirement or constraint supports each decision?
- What trade-off was accepted?

### Can I reconstruct it?

- Can I reproduce the core of the solution without asking for the full code again?
- Can I rebuild the main flow from the requirements?
- Can I draw the architecture from memory?

People routinely believe they understand a mechanism in more depth than they do. That illusion often collapses when they must explain it in detail. Explaining a system aloud or in writing is a cheap way to find the edge of your knowledge.

You do not need a perfect score. Nobody understands every line of every codebase, including code written without AI. The pattern matters: if you can execute and describe a system but cannot justify or reconstruct it, the artifact has outrun your understanding.

## A scale of command

Understanding is not binary. The five questions suggest a scale of command:

| Level | Capability |
|---|---|
| 0: Execution | I can run the code |
| 1: Description | I can say, roughly, what it does |
| 2: Explanation | I can explain the components and the flow |
| 3: Modification | I can change the behavior safely |
| 4: Diagnosis | I can investigate failures and surprising results |
| 5: Justification | I can defend the decisions and compare alternatives |
| 6: Reconstruction | I can rebuild the core from the requirements |

AI makes it easy to sit at level 0 while holding an artifact that looks like level 6. Such systems were once expensive enough to imply that their authors had climbed much of the scale. Generated sophistication makes the artifact and its author's command separate measurements.

## Tests, docs, and observability can lie too

"Review your AI code" is incomplete advice. The tests, documentation, and observability used as evidence of quality can carry the same blind spots as the implementation.

When the same agent writes the implementation and its tests, it can reproduce the same wrong assumptions in both. The tests may confirm implementation details instead of requirements or cover lines without protecting behavior. Ask which important behaviors they demonstrate and which hypotheses they try to invalidate, not how many tests exist.

Generated documentation is not automatically organizational knowledge. A model can explain the code it produced without anyone on the team absorbing that explanation. Documentation becomes useful when people retrieve, challenge, and maintain it.

Generated observability is not automatically operational capability. Traces, dashboards, and structured logs help only when they answer operational questions: which failures do we expect, what does degradation look like, and what decision will someone make from a metric? A heavily instrumented system can still be opaque.

Asking the AI to explain the system does not close the gap. Access to an answer says nothing about whether you can use it under pressure, apply it to a novel case, or notice when it is wrong.

## What I do now

I rely on agents daily. The problem is not who typed the code, but whether generation outruns my ability to validate, absorb, and own it. Barke describes two modes of use: acceleration, where the developer already knows the intended solution, and exploration, where suggestions help define the solution. Acceleration is easier to absorb because the model speeds up an existing intention. Exploration demands more deliberate work to understand the criteria and mechanisms it introduces.

Ask for justifications, not descriptions. In review, I replace "what does this code do?" with "why was this chosen, and what was rejected?" Explaining code is easy for a model. Justifying its fit requires the project's actual requirements and constraints.

Write a prediction before running generated code. I note what I expect, which risks I see, how I will recognize success, and what would prove me wrong. This creates a mental model before a green checkmark can substitute for one. Cheap, immediate execution helps, but validation still requires judgment.

Do reconstruction tests. I sometimes draw a system without looking at the code, explain its main flow, change one rule, and diagnose a simulated failure. The exercise exposes what I only thought I understood.

Record decisions, not just results. Code rarely preserves why a choice was made. A short architecture decision record can retain the context, constraints, alternatives, consequences, and open questions.

## Conclusion

A pull request can compile, pass its tests, document itself, emit metrics, and reach production while one question remains unanswered: who can explain why it works, when it will fail, and how it should change?

Comprehension debt trades future understanding for present speed. Evaluate both the artifact and your command of it. If nobody can explain, modify, diagnose, justify, or reconstruct the system, the code's polish conceals debt instead of removing it.

## References

- Ahmad, M. O. (2026). *Comprehension Debt in GenAI-Assisted Software Engineering Projects*. [arXiv:2604.13277](https://arxiv.org/abs/2604.13277).
- Al Madi, N. (2022). *How Readable is Model-generated Code? Examining Readability and Visual Inspection of GitHub Copilot*. 37th IEEE/ACM International Conference on Automated Software Engineering. [doi:10.1145/3551349.3560438](https://dl.acm.org/doi/10.1145/3551349.3560438).
- Barke, S., James, M. B., & Polikarpova, N. (2023). *Grounded Copilot: How Programmers Interact with Code-Generating Models*. Proc. ACM Program. Lang. 7, OOPSLA1. [doi:10.1145/3586030](https://dl.acm.org/doi/10.1145/3586030).
- Ferdowsi, K., Huang, R., James, M. B., Polikarpova, N., & Lerner, S. (2024). *Validating AI-Generated Code with Live Programming*. CHI Conference on Human Factors in Computing Systems. [doi:10.1145/3613904.3642495](https://dl.acm.org/doi/10.1145/3613904.3642495).
- Kruchten, P., Nord, R. L., & Ozkaya, I. (2012). *Technical Debt: From Metaphor to Theory and Practice*. IEEE Software, 29(6), 18-21. [doi:10.1109/MS.2012.167](https://ieeexplore.ieee.org/document/6336722).
- Perry, N., Srivastava, M., Kumar, D., & Boneh, D. (2023). *Do Users Write More Insecure Code with AI Assistants?* ACM SIGSAC Conference on Computer and Communications Security. [doi:10.1145/3576915.3623157](https://dl.acm.org/doi/10.1145/3576915.3623157).
- Qiao, Y., Shihab, M. I. H., & Hundhausen, C. (2025). *A Systematic Literature Review of the Use of GenAI Assistants for Code Comprehension*. ACM Transactions on Computing Education. [doi:10.1145/3785366](https://dl.acm.org/doi/10.1145/3785366).
- Risko, E. F., & Gilbert, S. J. (2016). *Cognitive Offloading*. Trends in Cognitive Sciences, 20(9), 676-688. [doi:10.1016/j.tics.2016.07.002](https://pubmed.ncbi.nlm.nih.gov/27542527/).
- Rozenblit, L., & Keil, F. (2002). *The Misunderstood Limits of Folk Science: An Illusion of Explanatory Depth*. Cognitive Science, 26(5), 521-562. [doi:10.1207/S15516709COG2605_1](https://pubmed.ncbi.nlm.nih.gov/21442007/).
- Skitka, L. J., Mosier, K. L., & Burdick, M. (1999). *Does Automation Bias Decision-Making?* International Journal of Human-Computer Studies, 51(5), 991-1006. [doi:10.1006/ijhc.1999.0252](https://dl.acm.org/doi/abs/10.1006/ijhc.1999.0252).
- Tang, N., Chen, M., Ning, Z., et al. (2024). *A Study on Developer Behaviors for Validating and Repairing LLM-Generated Code Using Eye Tracking and IDE Actions*. IEEE Symposium on Visual Languages and Human-Centric Computing. [arXiv:2405.16081](https://arxiv.org/abs/2405.16081).
- Vaithilingam, P., Zhang, T., & Glassman, E. L. (2022). *Expectation vs. Experience: Evaluating the Usability of Code Generation Tools Powered by Large Language Models*. CHI Conference on Human Factors in Computing Systems Extended Abstracts. [doi:10.1145/3491101.3519665](https://dl.acm.org/doi/10.1145/3491101.3519665).