{"slug": "understanding-is-the-new-bottleneck", "title": "Understanding Is the New Bottleneck", "summary": "Geoffrey Litt argued at the AI Engineer conference in July 2026 that understanding code written by AI agents remains crucial for effective collaboration, proposing techniques like code explainer docs, quizzes, and interactive micro-worlds to maintain human comprehension and creative participation in AI-assisted development.", "body_md": "### July 2026\n\n# Understanding is the new bottleneck\n\nThis is a written version of a talk I gave at the\n[AI Engineer](https://www.ai.engineer/)\nconference in July 2026, also shared as\n[a tweet thread.](https://x.com/geoffreylitt/status/2072522251300409556)\n\n**Hot take: I think it's still important to understand the code that our agents write!**\n\nIn this talk I'll explain why that's the case, and show some ideas for how to efficiently understand code. Alright, let's dive in.\n\nAgents are writing more and more code for us, and we all know it's getting harder to keep up.\n\nBut the good news is: there are many ways to understand code! Reading diffs line by line is not the only way.\n\nMost of this talk will be about techniques I have found helpful to understand systems my agents are building:\n\n- Code explainer docs\n- Quizzes to check my understanding\n- Micro-worlds that I can play with to understand the system\n\nBut first we have to ask a more basic question…\n\n## Why understand?\n\n**Why? Why understand?**\n\nAren't we supposed to be taking ourselves out of the loop now, and letting the agents loop themselves? As the agents get smarter, doesn't it become less important for us to be in the details?\n\nI think many people — even those who are pro-understanding — have a slightly incorrect answer to this question!\n\nOne possible answer: we understand *to verify*. We check the agent's work, we see if it's correct.\n\nCorrect can mean many things: does it match the spec, is it well architected… but it's fundamentally a thumbs-up / thumbs-down question.\n\nHere's the thing: the agents are getting better and better at verifying their own work. And this is good! I like it when my agent doesn't make mistakes.\n\nBut hmm. Where does that leave us humans?\n\n**That's where another answer comes in: we can understand to participate.**\n\nYou can learn what the agent is doing to make sure you can be an active participant in the creative process. Here's why this matters…\n\nIt's never just one loop! A project is many, many loops with the agent.\n\nAnd the understanding you have of the system is part of your ability to come up with the next idea to evolve it.\n\nYou need a rich set of concepts in your mind to think creatively and fluently about how to move something forward. If you're lacking that fluency, your ability to participate in the project is meaningfully limited.\n\nBy the way, this relates closely to the idea of [cognitive debt](https://margaretstorey.com/blog/2026/02/09/cognitive-debt/), popularized by Margaret Storey and [Simon Willison](https://simonwillison.net/).\n\nIt's like tech debt: you can get away with not understanding what's going on in the short term, but it'll bite you eventually.\n\nOK, so fine, understanding matters.\n\nBut this raises the next question: *how*? **How do we build this human understanding when we're working with AI and moving fast?**\n\nWell, turns out this is not the first time anyone has ever thought about how to communicate understanding. I think we can look to education as an inspiration. Can we steal the best ideas ever invented for education and apply them to this problem?\n\n## Technique 1: Explanations\n\nToday I want to share three techniques that show how we can attempt this.\n\nFirst: explanations. What makes a good explanation?\n\nWhenever an agent finishes some work, it's an opportunity for an explanation — an artifact.\n\nMost naively, we can read a code diff: the raw material that changed.\n\nBut what if we ask:\n\n**What would the best explanation be?** If you had a team — human or AI — that really sweat the details of explaining something well to you, how would that feel?\n\nHere's one answer. I made a skill called [/explain-diff](https://gist.github.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524), which I use every day and many coworkers have found valuable.\n\nIt outputs thoughtfully structured code explainers as HTML, markdown, or Notion docs. Notion is a good place for collaborating on and discussing these explainers as a team. (Disclaimer: I work at Notion so I'm biased.)\n\nLet's see what's in one of these explainers, using an example of editing the perspective of a video game.\n\nFirst principle: **teach me background info!**\n\nBefore we even get to what changed, help me understand what was already there. In this case, teach me about the game engine.\n\nSecond principle: **intuition before details.**\n\nBefore any code, it states the goal — “make the garden feel three-dimensional with 2D drawing tricks” — and explains related concepts, like what isometric projection is.\n\nAll of this builds my intuition for the essence of the change. It's catching me up as the human so I can be an equal participant in understanding.\n\nYou can also build intuition with **interactive figures**.\n\nHere I'm understanding the isometric perspective by dragging rocks around the garden and watching their coordinates move.\n\n(This is using a new feature Notion just shipped: you can now embed interactive HTML inside pages.)\n\nWe finally get to the code. But a typical diff is a pile of files edited in alphabetical order with no explanation.\n\nA “literate diff” as I call it is structured as prose — walking through the changes in a sensible order, with surrounding explanation and embedded code snippets. Faster to review than a raw diff.\n\nThe end result of all of this is a nice explainer packet. I still read the code diff but I always read this first.\n\nSometimes I'll print these out and take them to the café — less distracting.\n\nIt's beautifully ironic: AI turns an interactive activity into a static paper report I can focus on deeply :)\n\nThere's only one problem: reading is hard work 😅\n\nAs [Andy Matuschak says: “books don't work”](https://andymatuschak.org/books/)! It's too easy to fool yourself into thinking you did the reading when you really didn't retain or understand.\n\nHow do we fix this? I took inspiration from Andy and Michael Nielsen's work on [embedding spaced repetition quizzes in essays](https://quantum.country/).\n\nI do something similar with my code explainers now. At the bottom of an explainer there's an interactive quiz — five questions about the change — and I try to answer them.\n\nMy rule: I won't send code to others until I can pass the quiz, and I do the same when reviewing others' code.\n\n**A quiz is a speed regulator.** Working with AI, it's easy for the loop to run faster than the speed of human understanding.\n\nThe quiz is a counterbalancing force: I mechanically ask “do I actually understand?” so that I can remain a full creative participant.\n\nOK, so that's explain-diff. [Here's the skill if you want it](https://gist.github.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524): two variants that output either HTML or a Notion page.\n\n## Technique 2: Micro-worlds\n\nNext idea: micro-worlds. This one's inspired by the visionary educator Seymour Papert.\n\nPapert had this beautiful idea he called *living in Mathland*: if you want to learn math, live in Mathland — just like if you want to learn French, you go live in France. Could we build an environment where children learn math naturally, as a consequence of their curiosity?\n\nSo how do we apply that to code? **Can we make worlds you inhabit and naturally intuit how the system works and how it's changing?**\n\nLast year I was coding a Prolog interpreter and struggling to intuit what was happening inside.\n\nI worked with an agent to build this debugger, which let me step through the execution of my logic language — scrub through time, see what's on the stack and which rules are evaluated at each step. I could even leave comments for myself (“nice, we correctly applied that rule”).\n\nThere's a big difference between making a tool *for me* to debug and letting the agent debug — doing it myself is how I develop understanding along the way.\n\nAnother example. I was migrating my personal website from one framework to another, and Claude wrote a script that did it. But it was very hard to review: I wasn't familiar with the new framework, and all I could say was “I guess that looks about right.”\n\nSo I asked Claude to make me a video game — a command center where I do the port myself, step by step, watching the visible effects and the file tree evolve. It produced a UI where I click buttons to run the port step by step, with my old site and new site running side by side.\n\nIn this command center I watched the new site come to life incrementally. That left me with a similar understanding to doing it by hand — but much faster, because the whole experience was laid out for me.\n\nThe point here is that agents can write bits of code that help us humans understand other code.\n\nThis is a big deal!\n\n## Technique 3: Shared spaces\n\nAlright, last technique: shared spaces. So far this has all been about understanding solo… but **when you're working on a team, you need to understand together.**\n\nWhen you and someone else hold the same mental model, you can communicate efficiently. You have a shared vocabulary that evokes the same images, so you can jam and riff and have creative conversations. Without those shared structures, those conversations are much harder.\n\nI'm really excited about creating shared environments where teams build that understanding together. It's kinda what Notion is all about too.\n\nRecently in Notion we've been shipping tons of new features for humans and agents to work together, so your whole team develops a shared understanding instead of each working in a silo.\n\nOne tiny example: you can now run Claude and Cursor agents in Notion. I do a lot of my coding that way now.\n\nAnd when those agents make a technical plan in Notion, it's in a collaborative page by default, so I can comment on it with my team and discuss immediately. Thinking together, not alone!\n\n## The point was always to augment\n\nAlright, let's wrap up. Today we've covered some techniques that were about understanding code… but actually I think this is a much bigger issue.\n\nIt's still important for humans to understand how things work *in general*! **Not just to verify, but to participate.**\n\nAnd surprise surprise, this is not a new idea. It harkens back to the very origins of our field of computing…\n\n50 years ago Alan Kay envisioned that computers could be a new medium, better than the book, for teaching people — especially kids — how to think about the world.\n\nIn this picture, it might look like these kids are watching YouTube on an iPad, but they're not. They're playing an interactive game and editing the code as they play it to get a better understanding of physics. This was 50 years ago!!\n\nAnd now hopefully you understand [this meme](https://x.com/geoffreylitt/status/2071362040346955777).\n\nThe point was always to *augment*, not just automate.\n\nIt's beautiful that AI now makes creating simulations so accessible… Having AI teach us is one of the greatest possibilities computing has ever opened up.\n\nThis makes me very optimistic about the future!\n\n**If we build the right tools, we can now understand the world better than we ever could before.** We don't have to merely take ourselves out of the loop, we can get *deeper in the loop* too. It's up to us.\n\n*FIN*\n\n## Related reads\n\nIf you enjoyed this talk, you might like these other posts I've written about human-AI collaboration:\n\n-\n[Enough AI copilots! We need AI HUDs](/2025/07/27/enough-ai-copilots-we-need-ai-huds)— \"anyone serious about designing for AI should consider non-copilot form factors that more directly extend the human mind...\" -\n[AI-generated tools can make programming more fun](/2024/12/22/making-programming-more-fun-with-an-ai-generated-debugger)— \"Instead, I used AI to build a custom debugger UI… which made it more fun for me to do the coding myself...\" -\n[Code like a surgeon](/2025/10/24/code-like-a-surgeon)— \"identify and delegate the secondary grunt work tasks, so you can focus on the main thing that matters.\"", "url": "https://wpnews.pro/news/understanding-is-the-new-bottleneck", "canonical_source": "https://www.geoffreylitt.com/2026/07/02/understanding-is-the-new-bottleneck.html", "published_at": "2026-07-04 16:51:57+00:00", "updated_at": "2026-07-04 17:20:16.285116+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools", "ai-research"], "entities": ["Geoffrey Litt", "Margaret Storey", "Simon Willison", "AI Engineer", "Notion"], "alternates": {"html": "https://wpnews.pro/news/understanding-is-the-new-bottleneck", "markdown": "https://wpnews.pro/news/understanding-is-the-new-bottleneck.md", "text": "https://wpnews.pro/news/understanding-is-the-new-bottleneck.txt", "jsonld": "https://wpnews.pro/news/understanding-is-the-new-bottleneck.jsonld"}}