Understanding is the new bottleneck in coding with AI agents

In a talk given at the AI Engineer conference in July 2026 and later published as a blog post, the author argues that even as AI agents write more and more code, people still need to understand what those agents build. The obvious reason would be verification: checking whether the code matches the spec or is well architected, a thumbs up or thumbs down question. But the author points out that agents themselves are getting better and better at verifying their own work, which raises the question of what is left for the human. The author's answer is participation, not verification: understanding what an agent is doing is what lets a person stay an active creative partner in a project, since a real project is many loops with an agent rather than one pass, and understanding a system is part of what lets someone keep coming up with the next idea that moves it forward. The author likens failing to do this to 'cognitive debt', an idea credited to Margaret Storey and Simon Willison: skipping understanding works in the short term, the way unpaid technical debt does, but it eventually costs you.

The talk sets out three techniques for building that understanding, borrowed from education. The first is explanations: whenever an agent finishes work, the author treats it as a chance to generate an explainer rather than just reading a raw diff. The author built a skill called /explain-diff, described as used every day and valued by 'many coworkers', that outputs a structured explainer as HTML or as a Notion page (the author works at Notion and names this as a possible source of bias). An explainer teaches background context before the change itself, states the goal in plain language, and only then walks through a 'literate diff': the edits reordered into a narrative with embedded code and explanation, rather than a raw pile of files in alphabetical order. Using an example of changing the camera perspective of a video game, the author shows an explainer that first teaches the existing game engine, then introduces isometric projection with an interactive figure the reader can drag to build intuition before any code appears; the figure itself is built with a Notion feature for embedding interactive HTML in pages. Because reading alone does not guarantee retention, each explainer ends with a five-question comprehension quiz, an idea the talk credits to Andy Matuschak and Michael Nielsen's joint work on embedding spaced-repetition quizzes in essays, alongside Matuschak's own point, quoted in the talk, that 'books don't work'. The author's stated rule is never to send code to others, or approve someone else's, until personally passing the quiz; /explain-diff itself, in its HTML and Notion-page variants, is offered to anyone who wants it.

The second technique is micro-worlds, an idea the talk traces to educator Seymour Papert's notion of 'living in Mathland': if you want to learn math, live in a world built around math, the way you would move to France to learn French. Applied to code, the author built, with an agent's help, a debugger for a Prolog interpreter written last year, allowing the author to step through execution, scrub through time, inspect the stack and the rule being evaluated at each step, and leave comments along the way. A second example: when migrating a personal website between frameworks, Claude wrote the migration script, but the result was hard to review because the author was unfamiliar with the new framework and, by the author's own account, could only say 'I guess that looks about right.' So the author asked Claude to build a step-by-step command center, a small interactive tool for running the port one step at a time while watching the old and new sites evolve side by side, producing an understanding close to doing the migration by hand but far faster.

The third technique, shared spaces, moves from individual to team understanding: a team that holds the same mental model can riff and build on ideas together, which requires shared structures. The author points to recent Notion features that let people and agents build that shared understanding together, including running Claude and Cursor as agents inside Notion, and having an agent's technical plan land in a collaborative Notion page by default so a team can comment on it and discuss it right away. The talk closes by widening the argument beyond code: citing Alan Kay's vision, 50 years before the talk, of computers as a new medium, better than the book, for teaching people, especially children, how to think about the world, the author argues that the point of these tools was always to augment human understanding, not just automate tasks away, and that with the right tools people can now understand the world better than they ever could before.

Key facts

The talk lays out three techniques for understanding agent-written code: AI-generated explainer documents, interactive micro-world debugging tools, and shared team workspaces.
The /explain-diff skill, output as HTML or a Notion page, ends every code explainer with a five-question comprehension quiz.
The author's stated rule: never send code to others, or approve someone else's, until personally passing that quiz.
When Claude's script migrated the author's site to a new framework, Claude also built a step-by-step 'command center' UI so the author could review the port by watching the old and new sites side by side.
The 'cognitive debt' idea framing the whole argument is credited to Margaret Storey and Simon Willison.

Why it matters

The core claim is that as agents write more of a project's code, the traditional reason to look closely at it, checking whether it is correct, is fading: the author notes that agents themselves are getting better at verifying their own work. What is left for a person, the argument goes, is not inspection but participation: understanding a system well enough to keep coming up with the next idea that moves it forward, since a real project is many loops with an agent rather than one pass. Skipping that understanding is framed as accruing 'cognitive debt', an idea the talk credits to Margaret Storey and Simon Willison: it costs nothing at first, the way unpaid technical debt does, and then it does. The talk widens the stakes past code entirely, closing on Alan Kay's vision, stated 50 years before the talk, of computers as a teaching medium for children better than the book; the author's summary is that the point of these tools was always to augment human understanding, not just automate work away.

Who it affects

Anyone whose day-to-day work is now reviewing or steering code an agent wrote, rather than writing it line by line. The author describes /explain-diff as a skill used every day, one that 'many coworkers' have also found valuable. The third technique, shared spaces, extends the argument from individuals to teams that need a common mental model to build on each other's ideas; the Notion-integration material, including running Claude and Cursor as agents inside Notion pages, applies most directly to teams already using that product, which is also where the author works.

How to use it

Three concrete techniques are described. First, /explain-diff, a skill that turns an agent's finished work into a structured explainer: background first, then a 'literate diff' narrating the changes, then interactive figures where useful, and a closing five-question quiz. It comes in two output variants, HTML or a Notion page. Second, purpose-built micro-world tools: the author had an agent build a debugger to step through a Prolog interpreter's execution, and separately had Claude build a step-by-step 'command center' for reviewing a framework migration (the source names neither the old nor the new framework) by watching both sites run side by side. Third, shared team workspaces: Notion now runs Claude and Cursor as agents inside pages and drops an agent's technical plan into a collaborative page by default for the team to discuss.

How solid is it

This is a first-person conference talk turned blog post, not a study: the case for each technique rests on the author's own anecdotes (the Prolog debugger, the site-migration command center, daily use of /explain-diff) rather than on measured results. No comprehension score, error count, or time-saved figure is given for any of the three techniques. Several of the ideas that frame the argument are credited to named people (Margaret Storey and Simon Willison for cognitive debt, Andy Matuschak and Michael Nielsen for spaced-repetition quizzes, Seymour Papert for 'living in Mathland'), but the piece gives no employer or affiliation for any of them, so their credentials cannot be checked from the text alone.

Risks and caveats

The author discloses a direct conflict of interest, working at Notion while describing Notion's features favorably. The text does not say which model or agent generated the /explain-diff explainers, the quiz questions, or the Prolog debugger; Claude is named only for the two site-migration examples and the mention of Notion running Claude and Cursor as agents inside pages. Beyond 'July 2026', no calendar date is given for either the blog post or the AI Engineer conference talk it is based on, and no location or attendance figures for that conference appear either.

“The point was always to augment, not just automate.”

— the author of the talk