R037 · AI's effect on people › Comprehension debt

Floorplan: a generated map as a fix for comprehension debt

Read the original

comprehension-debtcode-visualizationai-built-softwarehuman-learningagent-harnesshuman-oversight

Floorplan is an MIT-licensed Claude Code and Codex plugin that scans a codebase with deterministic scripts, has the model name and describe every part, and renders a zoomable local HTML map. It is a useful navigation aid, but as an answer to comprehension debt it is a foil: it hands you the model's account of the system, not your own.

What it is

Stanislav Beliaev's post (2026-11-11) shares Hayden Smith's Floorplan (v0.7.3, MIT) with the framing: "AI writes code faster than anyone can review it" and fewer people can explain how the app works. Beliaev is sharing it, not its author.

The pipeline splits deterministic work from model work:

  1. Scan (scan.mjs, plain Node, no dependencies, no tokens): finds every git repo under a folder, extracts imports, exported definitions and doc comments, server endpoints (Express, FastAPI, Django, Spring, Go, Axum and others), outbound requests (fetch, axios, requests), and content fingerprints.

  2. Match requests to endpoints across repos, resolving router prefixes and learning each client's base path. The docs say plainly that this is pattern matching, not a compiler, so some links are missed.

  3. Describe: the model writes architecture.json (parts, outside services, connections the scan can't see such as queues and webhooks, flows, a tour), then names and describes every file and endpoint from per-part worksheets that quote short files and endpoint bodies so placeholders are visible.

  4. Build validates the model's output, warns on jargon in owner-facing mode, runs a Health check (keys in code, open Supabase tables or Firebase rules, fakeable Stripe webhooks, unauthenticated endpoints), detects screens, and writes a self-contained index.html.

  5. Recent work: the model annotates which cards it just changed and why.

  6. Refresh re-reads only files whose content or signature (exports, endpoints, doc comments) changed; edits inside function bodies don't flag a description for review.

It also has an Ask bar (questions answered by the CLI with read access to the code) and a blueprint mode that draws the same map from a PRD before code exists. Default audience is the app's owner, "without reading the code"; a developer view is a toggle.

Why it's a foil to comprehension debt

Comprehension debt is the gap between how much code a team ships and how much of it anyone understands. The usual remedy is to keep humans doing the understanding: review, explain-back tests, writing the design before the code. Floorplan bets the other way: let the model do the understanding and give people a map of its conclusions.

QuestionWhere the map pays offWhere it can't stand in for understanding
What talks to what?Import and request-to-endpoint edges are scripted, so they are mostly facts, and cross-repo tracing is hard to do by handDynamic dispatch, queues and config-built URLs are filled in by the model or missed, and the map doesn't mark which edges are guessed
What does this part do?Plain-language names cut onboarding time; owners get a vocabulary for the appDescriptions are model prose, so the reader trades reading code for trusting a summary of it
What will this change break?Ask bar answers with a mini-map and walkthroughAn answer is a claim, not a test; blast radius still needs tests or a type checker
What did the agent just do?Recent work board ties changed cards to the requestThe agent explains its own change, so self-justification goes unchecked
Do we understand it?Lowers the cost of building a mental modelRecognising a map is not the same as being able to reason about the system; "without reading the code" can deepen the debt while making it feel paid

The useful reading: the scripted half (scan, matching, Health) shrinks comprehension debt because it is checkable. The model-written half moves the debt from the code to the map, unless someone checks the map.

Failure modes and a review checklist

Failure modes:

Before relying on a Floorplan map:

Sources

Connections

See R037 on the knowledge map

Part of the Research notes on nowucca.com. Figures and claims are the source's own unless the summary says otherwise.