Karpathy’s Advice for Understanding AI: Ask for Clearer Writing, Diagrams, HTML—and Video
Andrej Karpathy's [new X post](https://x.com/karpathy/status/2105819303471976479) makes a useful distinction: faster AI work does not automatically make that work easier for people to understand. As models take on longer tasks, the human's ability to inspect the result can become the limiting step. His proposed response is to ask models for better **representations of their output**, not merely more words.
Karpathy points to four possibilities: writing inspired by Simplified Technical English (STE), diagrams and images, interactive HTML pages, and bespoke explainer videos. He does **not** present a controlled experiment or rank these formats by effectiveness. His attached image summarizes [ASD-STE100](https://www.asd-ste100.org/), an established controlled-language standard; the graphic is not a diagram of his four suggestions. His remark about getting partway toward STE should not be read as a claim of standards compliance.
What should a developer actually request?
Choose the least elaborate format that helps answer the reviewer's question. Clear prose works for a small change or decision. A diagram helps when call paths, state transitions, or ownership are hard to follow. A self-contained HTML explainer can be useful when a reviewer needs to explore several scenarios. Video may help teach a visual or temporal workflow, but it is slower to produce, harder to search and diff, and usually unnecessary for a pull-request review.
Here are three prompts to adapt:
**1. An evidence-first PR handoff**
> Explain this PR for a reviewer using short, direct sentences and consistent terms inspired by Simplified Technical English. State the behavior before and after the change. List the affected files and exact symbols, tests run and not run, and remaining risks. Link each non-obvious claim to a file or test. Do not claim ASD-STE100 compliance or invent evidence.
**2. A diagram for a complicated flow**
> Read the authentication flow in this repository. Produce a Mermaid sequence diagram from request to response. Label nodes with actual functions or files. Separate relationships confirmed in the code from assumptions, cite the relevant paths, and list anything you could not verify. Keep the diagram small enough to review beside the source.
**3. An interactive explainer when text is not enough**
> Make a single, self-contained HTML page that explains the three failure paths of this job queue. Include a scenario selector, the relevant state changes, and links to the source files. Use no external scripts, network calls, analytics, or secrets. Label simulated behavior as illustrative, not as a test result. Also provide a short text summary for reviewers who will not open the page.
A reusable skill idea
This suggests an **explain-for-review skill** for a coding agent—not a tool Karpathy announced. It could trigger after a substantial PR, architecture change, or incident investigation. First collect the diff, tests, traces, and source links. Then generate a short handoff in plain language; add a diagram only if relationships are the obstacle, or a self-contained HTML view only if readers need to explore alternatives. Finish with confirmed facts, inferences, unverified claims, and a reviewer checklist. OpenAI's [skills documentation](https://developers.openai.com/plugins/concepts/skills) describes how such repeatable instructions can be packaged for an agent; the workflow here is our editorial proposal.
The key safeguard is simple: a convincing diagram or video is still an explanation, **not verification**. Keep it tied to inspectable code and tests, and do not give an explainer access to credentials or production data merely to make it more impressive.