# AI-assisted code comprehension Using AI agents to understand code rather than just generate it. This counters the [[Cognitive debt]] risk of agentic workflows: if agents write code you don't review, your understanding of your own system decays. Two main techniques: ## Linear walkthroughs Have the agent read source code and produce a structured, sequential explanation of how it works. Useful for getting oriented with unfamiliar codebases, revisiting your own code after time has passed, or understanding code that was "vibe coded" quickly without deep attention. The key to good walkthroughs is having the agent include actual code snippets (extracted via shell commands, not hallucinated) alongside commentary. This grounds the explanation in reality rather than the model's approximation of the code. ## Interactive explanations Go beyond static explanation by having the agent build dynamic visualizations that illuminate algorithmic behavior. [[Simon Willison]] demonstrated this by asking an agent to build an animated HTML page showing word-cloud placement in real time: each word attempts placement, collision detection runs, and the spiral-search mechanism becomes visible. This transforms opaque algorithms into intuitive understanding. A written description of "Archimedean spiral placement with collision detection" is abstract. An animation showing it happen builds genuine comprehension. ## When to use - After an agent generates complex code you need to maintain - When onboarding to an unfamiliar codebase - When revisiting code you wrote months ago - When the implementation uses techniques outside your expertise The goal isn't to understand every line. It's to understand enough to confidently reason about behavior, plan changes, and debug failures; to keep [[Cognitive debt]] manageable. ## References - https://simonwillison.net/guides/agentic-engineering-patterns/linear-walkthroughs/ - https://simonwillison.net/guides/agentic-engineering-patterns/interactive-explanations/ ## Related - [[Cognitive debt]] - [[Agentic Engineering]] - [[AI Agents]] - [[Code is cheap, quality is not]] - [[Simon Willison]]