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:
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.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.
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.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.Recent work: the model annotates which cards it just changed and why.
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.
| Question | Where the map pays off | Where 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 hand | Dynamic 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 app | Descriptions 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 walkthrough | An 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 request | The agent explains its own change, so self-justification goes unchecked |
| Do we understand it? | Lowers the cost of building a mental model | Recognising 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:
Stale descriptions. Refresh flags a description only when a file's signature changes, so a rewritten function body with the same exports keeps its old explanation.
Unmarked inference. Scripted edges and model-added connections render the same way, so readers can't tell fact from guess.
Self-reporting. Recent work is the agent's own account of why each change serves the request, with no independent check.
False assurance. The Health check is, in its own words, a check and not an audit; a clean panel can read as "secure".
Blueprint drift. A PRD blueprint becomes a map once code exists, but nothing diffs the plan against what was built.
Cost on large repos. Every file and endpoint gets a model description; the docs give no token or time figures beyond "a few minutes for a small app".
Before relying on a Floorplan map:
Spot-check five descriptions against the code, picking files whose bodies changed recently.
Ask which edges came from the scan and which from
architecture.json.Treat Ask answers about blast radius as hypotheses and confirm with tests.
Have a person explain one flow from memory after reading the map, then compare with the code.
Keep the map out of git (the default) or version it deliberately, so nobody mistakes an old map for the current one.
Related entries
R012 AI crash projects for public good: cites evidence that people who learned a library with AI scored worse unaided, the core worry behind comprehension debt.
R017 Elephant-Goldfish Model: a doc-alone comprehension test by fresh reviewers; the opposite remedy, checking understanding instead of supplying it.
R016 Do humans still need to check AI's facts?: when a person must check model output, which is the question every map description raises.
R020 The model proposes, the harness enforces: trust the deterministic part; Floorplan's scripted edges fit, its prose doesn't.
R028 auto-ontology-mcp: the same split, with deterministic scanning and validation on the server and naming left to the model.