Skip navigation
Another example. I was migrating my personal website from one framework to another, and Claude wrote…
0:00 / 0:23

Another example. I was migrating my personal website from one framework to another, and Claude wrote…

Geoffrey Litt

@geoffreylitt26K followers

Visit on X
145 likesDownloadOriginal post

17,950 views

Another example. I was migrating my personal website from one framework to another, and Claude wrote a script that did it — something like this. 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." So 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. In 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. 28/

38 Comments

Comments from the original post on X (Twitter)

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Last year I was coding a Prolog interpreter and struggling to intuit what was happening inside. I 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"). There'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. 27/

    65 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    (Apparently twitter has a 25-tweet limit for the thread composer. I'm just gonna keep replying here with more slides until I have to board my flight!! 26 and onward!)

    45 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Papert 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? So 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? 25/

    57 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Next idea: micro-worlds. This one's inspired by the visionary educator Seymour Papert. 24/

    46 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    OK, so that's explain-diff. Here's the skill if you want it: two variants that output either HTML or Notion page. 23/

    199 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    I think of this as a speed regulator. Working with AI, it's easy for the loop to run faster than the speed of human understanding. The quiz is a counterbalancing force: I mechanically ask "do I actually understand?" so that I can remain a full creative participant. 22/

    75 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    I 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. My rule: I won't send code to others until I can pass the quiz, and I do the same when reviewing others' code. 21/

    81 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    There's only one problem: reading is hard work 😅 As @andy_matuschak says: "books don't work"! It's too easy to fool yourself into thinking you did the reading when you really didn't retain or understand. How do we fix this? I took inspiration from Andy and @michael_nielsen 's work on embedding spaced repetition quizzes in essays. 20/

    71 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    The end result of all of this is a nice explainer packet. I still read the code diff but I always read this first. Sometimes I'll print these out and take them to the café — less distracting. It's beautifully ironic: AI turns an interactive activity into a static paper report I can focus on deeply :) 19/

    78 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    We finally get to the code. But a typical diff is a pile of files edited in alphabetical order with no explanation. A "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. 18/

    63 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    You can also build intuition with interactive figures. Here I'm understanding the isometric perspective by dragging rocks around the garden and watching their coordinates move. This is using a new feature Notion just shipped today actually, you can now embed interactive HTML inside pages. 17/

    72 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Second principle: intuition before details. Before 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. All 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. 16/

    58 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    First principle: teach me background info! Before we even get to what changed, help me understand what was already there. In this case, teach me about the game engine. 15/

    60 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Here's one answer. I made a skill called /explain-diff, which I use every day and many coworkers have found valuable. It 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) Let's see what's in one of these explainers, using an example of editing the perspective of a video game. 14/

    94 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    But what if we ask: 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? 13/

    52 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Whenever an agent finishes some work, it's an opportunity for an explanation — an artifact. Most naively, we can read a code diff: the raw material that changed. 12/

    48 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    Today I want to share three techniques that show how we can attempt this. First: explanations. What makes a good explanation? 11/

    70 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    OK, so fine, understanding matters. But this raises the next question: how? How do we build this human understanding when we're working with AI and moving fast? Well, 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 to this problem?? 10/

    64 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    BTW, this relates closely to the idea of Cognitive Debt popularized by Margaret Storey and @simonw. It'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. 9/

    160 likes

  • Geoffrey Litt's profile picture

    @geoffreylitt

    It's never just one loop! A project is many, many loops with the agent. And the understanding you have of the system is part of your ability to come up with the next idea to evolve it. You 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. 8/

    207 likes