floorplan
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFloorplan
Floorplan
You produce at the codebase root: a floorplan of the app that someone new can read like a system diagram. Every card shows a human name and a one-line description, with the real path in small type underneath.
floorplan/- You write: (subsystems, modules, flows) and
architecture.json(a name and description for every file and route).descriptions/*.json - Generated: and
graph.json.index.html
The scripts do the mechanical work: finding repos, parsing imports and routes, matching HTTP calls to endpoints, layout and rendering. Your job is the part only a reader of the code can do: deciding what things are and saying so plainly.
Existing map: !
Arguments: $ARGUMENTS
node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || trueIn Codex (or any agent that left the two lines above unfilled): in every command here means this skill's folder, the one holding this SKILL.md, so use its path. Run from the codebase root yourself to see whether a map exists, and take the path and from the user's request. The scripts notice they're running under Codex, so the map's Ask bar and "Fix with" prompts use Codex.
${CLAUDE_SKILL_DIR}node <that folder>/scripts/status.mjs--refresh你会在代码库根目录生成 :一份新用户也能像阅读系统图一样理解的应用平面图。每张卡片都显示一个人类可读的名称和一行描述,并在下方以小字号显示真实路径。
floorplan/- 你编写: (子系统、模块、流程)和
architecture.json(每个文件及路由的名称和描述)。descriptions/*.json - 生成: 和
graph.json。index.html
脚本负责所有机械性工作:查找仓库、解析 import 和路由、将 HTTP 调用与端点匹配、布局和渲染。你的工作是只有代码读者才能完成的部分:判断各个事物是什么,并用直白的方式说明。
Existing map: !
Arguments: $ARGUMENTS
node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || true在 Codex 中(或任何未填充上述两行的 Agent):本文每条命令中的 都指此 skill 所在的文件夹,也就是包含此 SKILL.md 的目录,因此请使用它的实际路径。从代码库根目录自行运行 ,查看是否已有地图,并从用户请求中获取路径和 。脚本会检测自己是否运行于 Codex,因此地图的 Ask 栏和“Fix with”提示会使用 Codex。
${CLAUDE_SKILL_DIR}node <that folder>/scripts/status.mjs--refreshNothing built yet? Draw a blueprint
尚未构建任何内容?绘制蓝图
If the user wants to plan something they haven't built ("here's my PRD", "I want to build an app that…", a long description of a system), make a blueprint: the same map, planned from their document instead of scanned from code. Use this path when there's no code for the system yet, even if the folder holds other things. If the code exists, make a normal map.
- Read the input. A PRD file, a pasted message, or a document they point you at. Ask 2–3 questions only if something fundamental is open (who uses it, web or mobile, does anyone sign in, does money change hands); otherwise decide and record it as an assumption.
- Read references/blueprint.md, then references/schema.md for architecture.json.
- Write : every planned file and endpoint, what each screen calls, which outside services and data each part uses, who may use each endpoint, your assumptions and the open questions. If the PRD is only in the chat, save it as
floorplan/plan.jsonand use that asdocs/prd.md, so the map and later questions can refer back to it.source - Write as for a code map (parts, external nodes for the services and data plan.json names, 1–3 flows for the PRD's main user stories, a tour), with globs covering the planned paths. Plain language for everyone, as in step 4 below.
floorplan/architecture.json - Run , then build.mjs (step 5 below). Fix what they report until both are clean. Skip describe.mjs and recent.mjs: names and descriptions come from plan.json. A blueprint adds no notes to CLAUDE.local.md, since there's no code to look up yet.
node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root> - Show it with open.mjs (step 8).
- Report (instead of step 8's report): the URL; the shape of the system in 3–5 lines; the stack you chose; your main assumptions; and the design review's questions and warnings. Tell them each part has Build this with Claude (or Codex) for a ready request to build just that part; that they can switch the map's Ask bar to Change and ask for additions or changes ("also plan out refunds"), and the map redraws with what changed highlighted (the design review's Resolve on the map fills in such a request, so open questions just need their answer); that plan.json and architecture.json are theirs to edit or to ask you to change; and that the map stays out of git.
To change a blueprint, edit plan.json and architecture.json and run , which redraws it from plan.json. Once the code exists and the user wants a map of it, run , then carry on as for a refresh. plan.json stays where it is.
refresh.mjsrefresh.mjs <root> --from-code如果用户想规划尚未构建的内容(例如“这是我的 PRD”“我想构建一个……的应用”,或一段较长的系统描述),请制作一份蓝图:使用同一种地图形式,但依据文档进行规划,而不是扫描代码。当目标系统尚无代码时,即使文件夹中还有其他内容,也应采用此路径。如果代码已经存在,则制作普通地图。
- 读取输入。 可以是 PRD 文件、粘贴的消息,或用户指定的文档。只有在存在根本性的未决事项时才询问 2–3 个问题(谁会使用它、Web 还是移动端、是否需要登录、是否涉及资金往来);否则自行决定并将其记录为假设。
- 阅读 references/blueprint.md,然后阅读 references/schema.md,了解 的格式。
architecture.json - 编写 :列出每个计划中的文件和端点、每个屏幕调用什么、各部分使用哪些外部服务和数据、谁可以使用每个端点,以及你的假设和待解决问题。如果 PRD 只存在于聊天记录中,请将其保存为
floorplan/plan.json并用作docs/prd.md,这样地图和后续问题都能引用它。source - 按照代码地图的方式编写 :包含各个部分、为
floorplan/architecture.json中所命名服务和数据创建的外部节点、针对 PRD 主要用户故事的 1–3 条流程,以及一段导览;使用 glob 覆盖计划中的路径。按照下述第 4 步的要求,使用所有人都能理解的直白语言。plan.json - 运行 ,然后运行
node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs <root>(见第 5 步)。修复它们报告的问题,直到两者均无错误。跳过build.mjs和describe.mjs:名称与描述来自recent.mjs。蓝图不会向plan.json添加任何注释,因为此时还没有可供查询的代码。CLAUDE.local.md - 使用 展示蓝图(见第 8 步)。
open.mjs - 报告(替代第 8 步中的报告):提供 URL;用 3–5 行说明系统形态;说明所选技术栈;列出主要假设;以及设计审查提出的问题和警告。告诉用户,每个部分都带有 Build this with Claude(或 Codex),可据此生成仅构建该部分的现成请求;他们也可以将地图的 Ask 栏切换到 Change,并提出新增或修改要求(例如“也规划一下退款流程”),地图会重新绘制并高亮变化(设计审查中的 Resolve on map 会填写这类请求,因此待解决问题只需提供答案);和
plan.json可由用户自行编辑,也可以要求你代为修改;地图不会进入 git。architecture.json
要修改蓝图,请编辑 和 ,然后运行 ,它会根据 重新绘制蓝图。代码创建完成且用户需要代码地图时,运行 ,随后按照刷新流程继续处理。 会保留在原位置。
plan.jsonarchitecture.jsonrefresh.mjsplan.jsonrefresh.mjs <root> --from-codeplan.jsonA map already exists? Refresh it instead
地图已经存在?改为刷新
If the status above shows an existing map, don't start over. Run:
node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>It re-scans, compares content fingerprints against the last build, and does the bookkeeping without spending tokens:
- carries descriptions over to moved or renamed files and endpoints;
- drops entries for deleted files;
- flags entries whose exports or routes changed with a note (edits inside function bodies don't count);
review - rebuilds;
- prints what changed and a short NEXT list.
Do only what NEXT asks:
- add globs for new directories that landed in "unassigned";
- run describe.mjs (step 6), which now only produces worksheets for the new and flagged items;
- check module summaries and flows if the change was large.
A typical refresh after a few hours of work is a handful of worksheet entries. Then mark recent work (step 7), and show it and report (step 8). Always show it, even when nothing changed: the user asked to see their floorplan.
如果上述状态显示已有地图,不要从头开始。运行:
node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>它会重新扫描代码,将内容指纹与上次构建结果进行比较,并完成 bookkeeping,同时不消耗 token:
- 将描述沿用到移动或重命名的文件及端点;
- 移除已删除文件的条目;
- 标记 export 或路由发生变化的条目,并附带 备注(函数体内部的修改不算);
review - 重新构建;
- 打印变更内容及一份简短的 NEXT 列表。
只执行 NEXT 中要求的内容:
- 为新出现且位于“unassigned”中的目录添加 glob;
- 运行 (第 6 步),此时它只会为新增和被标记的条目生成工作表;
describe.mjs - 如果变更规模较大,检查模块摘要和流程。
工作数小时后进行一次典型刷新,通常只会涉及少量工作表条目。然后标记近期工作(第 7 步),并展示地图和报告(第 8 步)。即使没有任何变化,也始终展示地图:用户明确要求查看平面图。
Workflow (first run)
工作流(首次运行)
The codebase root is the argument if one was given, otherwise the current directory. It may be a single repo, or a plain folder holding several repos (frontend + backend + infra, and so on). The scanner finds every git repo under it and skips duplicate worktrees.
-
Scan.It writes
node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root>and prints a summary: repos, a code tree with LOC, entrypoints, the heaviest directory→directory import edges, HTTP call→route matches across repos, external packages and hosts. Work from the summary. Don't read scan.json, which is large.floorplan/.cache/scan.json -
Read the contract. Read references/schema.md (the architecture.json format) and references/choosing-boundaries.md (how to carve a codebase into a good map).
-
Explore just enough. Read READMEs, manifests (package.json, pyproject, go.mod, docker-compose, deploy configs) and entrypoints, then skim 1–2 files per candidate subsystem until you can write a one-sentence summary for each. You're after the shape of the system, not a code review.
-
Write. Aim for:
floorplan/architecture.json- 3–9 top-level nodes;
- 3–12 children under each big one;
- globs covering more than 90% of code files;
- external nodes for the databases and third-party services the code really talks to;
- edges only for what the scan can't see (queues, cron, webhooks, cross-service calls through env-configured URLs);
- 1–3 flows that explain the system's main jobs;
- a : 3–8 narrated stops for the "Start here" tour (see below).
tour
Every node needs a.summaryAudience. The people opening this map are usually the app's owners, often non-technical builders who made it with AI. Unless the user asks for a developer-facing map, leaveunset or set it to"audience", and write every"everyone", nodeproject.summary/label, and file/route description in plain language (see "Plain language" in references/writing-descriptions.md). Use short labels like "Main server" rather than "Shop API (Flask)". Paths and method/URL stay visible on the cards, so descriptions only need to say what the thing is for. And say what the code does today, not what its names suggest: when a part is mostly placeholders, its summary says so ("Say what it does today" in references/writing-descriptions.md).summaryTour. Add, with stops in the order a newcomer should see them: what the app is, the apps people use, the main server, outside services, and ending on an important screen's file. Write titles and notes in plain words for someone who has never read the code. The first guided flow is added at the end automatically as "watch a real request". Without a tour, one is built from node summaries and the first flow, so good summaries and at least one flow matter."tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }] -
Build and fix.It validates everything and names each problem ("did you mean …", files unassigned by directory, ambiguous globs). Fix and rebuild until it's clean and unassigned is under ~10%. Two warnings are worth one more pass:
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root>names a part whose label or summary uses developer words (reword it as suggested), and a part that "holds N files and no smaller parts" lists the folders it could be split along.plain language:Nothing Floorplan makes is committed.holds its ownfloorplan/that ignores the whole folder, so the project's tracked files aren't touched. If git already tracks files there, the build prints the.gitignorecommand to untrack them; pass it on to the user rather than running it.git rm -r --cachedA note for future sessions, only if the user wants one. In Claude Code, the build can keep a short marked block in the project's, Claude Code's personal, uncommitted project notes, which load at session start like CLAUDE.md. The block tells future Claude Code sessions here that the map exists and how to look things up in it withCLAUDE.local.md, so they start from the map instead of searching the code from scratch. Because it changes how later sessions work, the build never adds it on its own: it reportsfloorplan/query.mjs, and you offer it in your report (step 8). Only when the user says yes, runCLAUDE.LOCAL.MD not added. Once the block exists, every build keeps it current. The build addsnode ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --claude-mdto the repo's local ignore list (CLAUDE.local.md, not.git/info/exclude), rewrites only its own block, and moves the block out of.gitignoreif an older version put it there. To remove it, the user deletes the block, or putsCLAUDE.mdin CLAUDE.local.md to keep it from coming back. Under Codex the build skips this: Codex has no personal, uncommitted notes file (AGENTS.md is shared with the team), so don't add one there either.<!-- floorplan:off --> -
Describe every file and route.This writes one worksheet per module (
node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root>) and a skeleton to fill in (floorplan/.cache/worksheets/<key>.md). Each worksheet holds a digest of every file (docstrings, definitions, what it uses, and the files that import it, send it web requests or name it) and every route (handler, docstring), and quotes the code of each route it lists and the whole of very short files (secrets masked). That's enough to describe most files without opening them.floorplan/descriptions/<key>.json- Read references/writing-descriptions.md first, especially "Say what it does today": describe what the quoted code does, say so plainly when it's a placeholder, and don't claim who runs or uses something unless the worksheet or the code shows it.
- More than ~150 files: split the worksheets across parallel subagents if you have them, ~100–150 files each, grouped by area (backend routes, services, scripts, tests, UI). Give each one its worksheet keys, the codebase root and the writing guide, and tell it to edit only its own files and keep the keys unchanged.
descriptions/<key>.json - Smaller codebases: do it yourself.
Then rebuild. The build reports. Get both to 100%: re-run describe.mjs and it lists only what's still missing.DESCRIPTIONS files X/Y · routes X/Y -
Mark recent work. The map highlights what was just worked on: those cards get a green "Changed"/"New" tag, the parts containing them show "N changed", hovering shows your note, and a Recent work button lays them out on one board. Do this on every make and every update, because it replaces the previous highlights.It lists what changed since the previous map, uncommitted changes and recent commits, each matched to the card it appears as. The why comes from you:
node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root>- What counts. Work done in this conversation, by you or your subagents, is the main source. Lean on what you know about it. If you did nothing here (a fresh session), use what recent.mjs shows that is clearly in flight: uncommitted changes and the latest commits. If there's nothing, write so old highlights clear.
{ "tasks": [] } - Write . Use one task per thing the user asked for:
floorplan/recent-work.json(2–5 words),title(what they asked, in their words, shortened; leave itrequestwhen nobody asked here, as when working from commits, because the map shows it as "You asked: …"),""(1–2 sentences on what was done toward it and where it stands, including anything deleted, since deleted files can't be highlighted). Then addsummary: the cards that changed, as a file path, node id oritems, with"METHOD /path"(changeor"new") and a"changed".note - Every note answers "how does this relate to what they asked for?" In one or two plain sentences, say what changed on this card and why the request needed it. For example, write "Now catches web requests whose address is built up in a variable first, which is why the orders and inventory screens were showing no server calls." Not "Added flattenTemplates and variableUse helpers".
- Highlight what mattered. Pick the files and endpoints whose behaviour changed for this request, usually 3–15. Skip tests and drive-by edits unless they're the point. A file with a changed endpoint can list both the file and the endpoint.
- Keep the code's words out unless the audience is developers. Never put secrets in notes, and never invent example values: say only what the code shows.
Format: references/schema.md#recent-work. Then run build.mjs. It reportsand warns about refs that aren't on the map.RECENT WORK N card(s) highlighted - What counts. Work done in this conversation, by you or your subagents, is the main source. Lean on what you know about it. If you did nothing here (a fresh session), use what recent.mjs shows that is clearly in flight: uncommitted changes and the latest commits. If there's nothing, write
-
Show it, then report. Whenever you make or update a floorplan, finish by putting it in front of the user:
node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>- It starts the map's server in the background (or reuses the one already running for this map) and opens it in their browser. Tabs that are already open reload in place instead of a new one opening.
- It prints the URL, whether Ask works (the Claude Code CLI or Codex was found), and how to stop the server. The server also stops on its own a couple of hours after the last tab closes.
- In Codex, run open.mjs outside the sandbox (ask for escalated permissions): the server has to keep running after the command ends, and Ask needs the network to reach Codex. If that isn't allowed, give the user to run in their own terminal from the codebase root.
node floorplan/serve.mjs - If you have an in-app browser or preview tool, pass and open the printed URL there instead, so the map appears right beside the conversation.
--no-open - If this is a remote or headless machine where the user can't reach 127.0.0.1, skip open.mjs and tell them to run on their own machine, or offer the Claude app route (step 9).
node floorplan/serve.mjs
Then report. Give the URL, then describe the architecture you mapped in 3–5 lines, in the user's language, including anything surprising: cycles, god-files, dead areas, coupled subsystems. Always mention the high-severity Health items (; the build output and graph.json list them). Hard-coded passwords/keys and endpoints anyone can change data through are things the owner needs to hear about. Also pass on any check the build marks withgraph.healthunder!(like no endpoints found in code that runs a server): that check had nothing to look at, so a short Health list there isn't a clean bill of health. Never repeat a secret's value. When the build'swhat was checkedline shows many docs or config files, say in one line that the map shows only the kinds of file it names (code, unlessNOT MAPPEDsays otherwise), so a small map isn't taken for a scan that missed things, and that you can add them. Say thatincludeandarchitecture.jsonare theirs to edit, and that after more work they can just ask to "update the floorplan", which re-reads only what changed. Give them those plain words rather than a command: in Claude Code the plugin's command isdescriptions/(/floorplan:floorplanas a personal skill), and in Codex it's/floorplan. On a first run, mention in one line that the map stays out of git. In Claude Code, when the build said$floorplan, end by asking once whether future Claude Code sessions in this project should use the map: you'd add a short note to their personal, uncommitted CLAUDE.local.md. Add it (CLAUDE.LOCAL.MD not added) only on a yes, and don't ask again on later updates if they said no. On an update, start with what changed for what they asked (it's highlighted under Recent work).build.mjs <root> --claude-md
如果用户提供了代码库根目录,则以该目录为根;否则使用当前目录。它可以是单个仓库,也可以是一个包含多个仓库的普通文件夹,例如 frontend、backend 和 infra。扫描器会发现其下的每个 git 仓库,并跳过重复的 worktree。
-
扫描。它会写入
node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root>并打印摘要:仓库、包含 LOC 的代码树、入口点、最重的目录到目录 import 边、跨仓库的 HTTP 调用到路由匹配,以及外部包和主机。根据摘要开展工作。不要读取floorplan/.cache/scan.json,因为它很大。scan.json -
阅读约定。 阅读 references/schema.md(格式)和 references/choosing-boundaries.md(如何将代码库划分为一张优质地图)。
architecture.json -
只探索必要内容。 阅读 README、清单文件(、
package.json、pyproject、docker-compose、部署配置)和入口点,然后每个候选子系统浏览 1–2 个文件,直到能为每个子系统写出一句话摘要。你的目标是理解系统形态,而不是进行代码审查。go.mod -
编写。 建议:
floorplan/architecture.json- 3–9 个顶层节点;
- 每个大型节点下有 3–12 个子节点;
- 使用 glob 覆盖超过 90% 的代码文件;
- 为代码实际访问的数据库和第三方服务创建外部节点;
- 仅在扫描无法发现的地方添加边,例如队列、cron、webhook,以及通过环境变量配置 URL 完成的跨服务调用;
- 使用 1–3 条流程解释系统的主要工作;
- 提供 :为“Start here”导览设置 3–8 个带解说的停靠点(见下文)。
tour
每个节点都需要提供。summary受众。 打开这张地图的人通常是应用的所有者,往往是使用 AI 构建产品的非技术型开发者。除非用户要求面向开发者的地图,否则请将留空或设为"audience",并使用直白语言编写所有"everyone"、节点project.summary/label以及文件和路由描述(见 references/writing-descriptions.md 中的“Plain language”)。使用“主服务器”这样的简短标签,而不是“商店 API(Flask)”。卡片上仍会显示路径和 method/URL,因此描述只需说明组件的用途。描述代码当前的实际行为,而不是根据名称推测行为:当某部分主要由占位内容组成时,其摘要应如实说明(见 references/writing-descriptions.md 中的“Say what it does today”)。summary导览。 添加,停靠点按新用户应了解的顺序排列:应用是什么、用户使用哪些应用、主服务器、外部服务,最后停在一个重要屏幕对应的文件上。标题和备注应使用普通用户能理解的措辞,即使他们从未读过代码。系统会在最后自动添加第一条引导流程,名称为“watch a real request”。如果没有导览,系统会根据节点摘要和第一条流程自动构建,因此高质量的摘要和至少一条流程非常重要。"tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }] -
构建并修复。它会验证所有内容,并指出每个问题,例如“did you mean …”、按目录划分后尚未分配的文件,以及含义模糊的 glob。修复问题并重新构建,直到无错误且 unassigned 低于约 10%。有两类警告值得再检查一遍:
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root>表示某个部分的标签或摘要使用了开发者术语(请按照建议改写);另一个警告表示某部分“holds N files and no smaller parts”,并列出可以继续拆分的目录。plain language:Floorplan 生成的内容不会被提交。包含自己的floorplan/,会忽略整个目录,因此不会触碰项目已跟踪的文件。如果 git 已经跟踪了该目录中的文件,构建过程会打印.gitignore命令;请把它告知用户,而不要自行运行。git rm -r --cached仅为未来会话保留备注,且仅在用户需要时。 在 Claude Code 中,构建过程可以在项目的中保留一小段带标记的内容。CLAUDE.local.md是 Claude 的个人、未提交项目备注,会在会话启动时像CLAUDE.local.md一样加载。该内容会告诉未来的 Claude Code 会话:此项目已有地图,以及如何使用CLAUDE.md在地图中查找信息,从而从地图开始工作,而不是每次都从头搜索代码。由于它会改变后续会话的工作方式,构建过程绝不会自行添加:它会报告floorplan/query.mjs,你应在报告(第 8 步)中向用户提供此选项。只有当用户明确同意时,才运行CLAUDE.LOCAL.MD not added。一旦该内容存在,之后每次构建都会保持其更新。构建过程会将node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --claude-md添加到仓库的本地忽略列表(CLAUDE.local.md,而不是.git/info/exclude),只重写自己管理的内容块;如果旧版本曾将其写入.gitignore,还会把该内容块移出CLAUDE.md。如需移除,用户可以删除该内容块,或加入CLAUDE.md,防止其再次出现。在 Codex 下,构建过程会跳过此步骤:Codex 没有个人未提交备注文件,AGENTS.md 是团队共享文件,因此同样不要添加。<!-- floorplan:off --> -
描述每个文件和路由。它会为每个模块编写一份工作表(
node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root>),并生成需要填写的骨架(floorplan/.cache/worksheets/<key>.md)。每份工作表包含所有文件的摘要(docstring、定义、使用内容,以及导入这些文件、向其发送 Web 请求或提到这些文件的文件)和所有路由(handler、docstring),还会引用其列出的每条路由的代码,以及所有很短文件的完整内容(敏感信息会被遮蔽)。这些信息足以让你在不逐个打开文件的情况下描述大多数文件。floorplan/descriptions/<key>.json- 先阅读 references/writing-descriptions.md,尤其是“Say what it does today”:描述所引用代码的实际行为;当代码只是占位实现时应如实说明;除非工作表或代码明确显示,否则不要断言谁会运行或使用某项功能。
- 超过约 150 个文件时: 如果有并行子 Agent,将工作表按区域拆分给它们处理,每个 Agent 约负责 100–150 个文件,例如 backend 路由、服务、脚本、测试和 UI。为每个 Agent 提供其工作表 key、代码库根目录和编写指南,并要求它只编辑自己的 文件,同时保持 key 不变。
descriptions/<key>.json - 较小的代码库: 由你自行完成。
随后重新构建。构建报告会显示。两项都要达到 100%;再次运行DESCRIPTIONS files X/Y · routes X/Y,它只会列出仍然缺失的内容。describe.mjs -
标记近期工作。 地图会突出显示刚刚处理过的内容:这些卡片会带有绿色“Changed”或“New”标签,包含它们的区域会显示“N changed”,悬停时可看到你的备注,“Recent work”按钮会将它们排列在同一看板上。每次创建和更新时都应执行此操作,因为它会替换之前的高亮。它会列出自上次生成地图以来发生的变化、未提交修改和近期 commit,并将每项匹配到其对应卡片。变化背后的原因需要由你补充:
node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root>- 判定标准。 本次对话中由你或子 Agent 完成的工作是主要依据,应优先利用你已经掌握的信息。如果本次没有进行任何工作(新会话),使用 明确显示的进行中事项:未提交修改和最新 commit。如果没有可标记内容,则写入
recent.mjs,以清除旧的高亮。{ "tasks": [] } - 编写 。 用户每提出一项要求,就对应一个 task:
floorplan/recent-work.json(2–5 个词)、title(用户原话经过缩短后的要求;如果没人提出要求,例如根据 commit 标记时,则留为request,因为地图会显示为“You asked: …”)、""(用 1–2 句话说明为此完成了什么以及当前状态,包括任何已删除内容,因为已删除文件无法高亮)。然后添加summary:发生变化的卡片,可以是文件路径、节点 id 或items,并设置"METHOD /path"(change或"new")和"changed"。note - 每条备注都要回答“这与用户的要求有什么关系?” 用一两句直白的话说明该卡片发生了什么变化,以及为什么用户的要求需要这项变化。例如,可以写:“现在能够捕获地址先通过变量拼接而成的 Web 请求,因此订单和库存屏幕之前没有显示服务器调用。”不要只写“新增了 flattenTemplates 和 variableUse 辅助函数”。
- 突出重要内容。 选择行为因本次要求而变化的文件和端点,通常为 3–15 个。除非测试或顺带修改本身就是重点,否则应跳过它们。文件中的端点发生变化时,可以同时列出该文件和端点。
- 除非受众是开发者,否则不要使用代码中的措辞。 备注中绝不能包含密钥,也绝不能虚构示例值:只陈述代码能够证明的内容。
格式参见 references/schema.md#recent-work。然后运行。它会报告build.mjs,并警告地图中不存在的引用。RECENT WORK N card(s) highlighted - 判定标准。 本次对话中由你或子 Agent 完成的工作是主要依据,应优先利用你已经掌握的信息。如果本次没有进行任何工作(新会话),使用
-
展示地图,然后报告。 每次创建或更新 floorplan 时,最后都要将地图展示给用户:
node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>- 它会在后台启动地图服务器,或复用已为该地图运行的服务器,并在浏览器中打开。已经打开的标签页会原地刷新,而不是再打开一个新标签页。
- 它会打印 URL、Ask 是否可用(是否找到 Claude Code CLI 或 Codex),以及如何停止服务器。最后一个标签页关闭约几小时后,服务器也会自动停止。
- 在 Codex 中,请在 sandbox 外运行 (请求提升权限):服务器必须在命令结束后继续运行,Ask 也需要网络访问 Codex。如果无法提升权限,请让用户自行运行
open.mjs。node floorplan/serve.mjs - 如果有应用内浏览器或预览工具,请传入 ,改为在预览工具中打开输出的 URL,让地图直接显示在对话旁边。
--no-open - 如果处于用户无法访问 127.0.0.1 的远程或无头机器上,请跳过 ,并告知用户在自己的机器上运行
open.mjs,或者提供 Claude app 路径(第 9 步)。node floorplan/serve.mjs
然后报告。先提供 URL,再用用户的语言用 3–5 行描述所映射的架构,包括所有意外发现:循环依赖、god-files、废弃区域、过度耦合的子系统。务必提及所有高严重度的 Health 项目(;构建输出和graph.health会列出这些项目)。硬编码的密码或密钥,以及任何人都能修改数据的端点,都是应用所有者必须了解的问题。还应转述构建结果中在graph.json下标记what was checked的检查,例如“在运行服务器的代码中未找到端点”:这表示检查没有可分析的对象,因此 Health 列表很短并不代表系统完全健康。绝不能重复任何密钥的值。当构建结果的!行显示大量文档或配置文件时,应用一句话说明地图只显示其命名的那类文件(默认是代码,除非NOT MAPPED有其他设置),因此不要把较小的地图误认为扫描遗漏,并说明可以手动添加这些文件。告知用户,include和architecture.json可由他们自行编辑;完成更多工作后,他们只需要求“update the floorplan”,系统便只会重新读取发生变化的部分。使用普通措辞而不是命令来介绍:在 Claude Code 中,插件命令是descriptions/(/floorplan:floorplan是个人 skill);在 Codex 中则是/floorplan。首次运行时,用一句话说明地图不会进入 git。在 Claude Code 中,如果构建报告$floorplan,最后应询问一次:未来的 Claude Code 会话是否应使用这张地图;如果用户同意,你会在其个人、未提交的CLAUDE.LOCAL.MD not added中添加一段简短备注。只有在用户同意后才运行CLAUDE.local.md;如果用户已经拒绝,后续更新时不要再次询问。更新时,应先说明针对用户要求发生了哪些变化,这些内容会在 Recent work 下高亮显示。build.mjs <root> --claude-md
9. Opening the map and asking questions
9. 打开地图并提出问题
The map has a floating Ask bar. The user types a question, and the agent answers with text plus an answer board: the relevant cards, the connections among them, a note on each card, and an optional step-by-step walkthrough. There are two ways to power it. The UI is the same either way.
-
Claude Code CLI or Codex (best). The map's server (, started by open.mjs in step 8) serves it at http://127.0.0.1:4378, or the next free port. Each question runs on the user's own sign-in, in the codebase, read-only, so answers can cite real code:
floorplan/serve.mjs- Claude Code: with the map (via
claude -p) plus Read/Grep/Glob on the source. The server findsfloorplan/query.mjson PATH or inclaude.~/.local/bin - Codex: in Codex's read-only sandbox, with nothing saved to their Codex history. The server finds
codex execon PATH, or the CLI that comes with the Codex app.codex
It uses the agent that built the map, and falls back to the other if that one isn't installed.forces one,--engine claude|codexor--claude <path>points at an unusual install,--codex <path>picks the model, and--model <name>the editor Open in editor opens, over architecture.json's--editor <name or link>(open.mjs passes all of these through). Users can also runeditorthemselves at any time, and stop a background one withnode floorplan/serve.mjs.node floorplan/serve.mjs --stop - Claude Code:
-
Claude app. If you're running in the Claude app (the Artifact tool is available), offer to publish the map so they can open it there and ask questions on their own Claude account. Answers then come from the map only (names, descriptions, connections, endpoints), not the source, and the Ask bar shows a hint to install the CLI for a better experience. To publish:
- . This writes
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifactwithout the machine's absolute path.floorplan/artifact.html - Publish that file with the Artifact tool, , and keep the same file path for later publishes so the URL stays stable.
capabilities: {"sample": {}} - After each refresh, rebuild with and republish.
--artifact
Publishing uploads the map (paths, names, descriptions, structure), not the source code, to their private claude.ai account. Say that before you do it. -
Neither:still opens directly in a browser. The Ask bar explains what's needed.
floorplan/index.html
地图带有一个悬浮 Ask 栏。用户输入问题后,Agent 会以文本和一个答案看板作答:看板上包含相关卡片、卡片之间的连接、每张卡片的备注,以及可选的分步讲解。共有两种驱动方式,界面完全相同。
-
Claude Code CLI 或 Codex(推荐)。 地图服务器(,由第 8 步的
floorplan/serve.mjs启动)会通过 http://127.0.0.1:4378 或下一个空闲端口提供地图。每个问题都会在用户的登录身份下、基于代码库以只读方式运行,因此答案可以引用真实代码:open.mjs- Claude Code: 使用 ,并通过
claude -p提供地图,同时允许在源代码上使用 Read/Grep/Glob。服务器会在 PATH 或floorplan/query.mjs中查找~/.local/bin。claude - Codex: 在 Codex 的只读 sandbox 中运行 ,不会向用户的 Codex 历史记录保存任何内容。服务器会查找 PATH 中的
codex exec,或 Codex app 自带的 CLI。codex
它会使用构建地图时所用的 Agent;如果该 Agent 未安装,则回退到另一个。可强制选择引擎,--engine claude|codex或--claude <path>可指定特殊安装位置,--codex <path>可选择模型,--model <name>可指定 Open in editor 打开的编辑器,并覆盖--editor <name or link>中的architecture.json设置(editor会透传所有这些参数)。用户也可以随时自行运行open.mjs,并使用node floorplan/serve.mjs停止后台服务器。node floorplan/serve.mjs --stop - Claude Code: 使用
-
Claude app。 如果你运行在 Claude app 中(可以使用 Artifact tool),可以提供发布地图的选项,让用户在自己的 Claude 账户中打开地图并提出问题。此时答案仅来自地图中的信息(名称、描述、连接关系、端点),不会读取源代码;Ask 栏会提示安装 CLI,以获得更好的体验。要发布:
- 。这会生成不包含本机绝对路径的
node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifact。floorplan/artifact.html - 使用 Artifact tool 发布该文件,设置 ,并保持相同的文件路径供后续发布使用,以确保 URL 稳定。
capabilities: {"sample": {}} - 每次刷新后,使用 重新构建并重新发布。
--artifact
发布操作会上传地图内容(路径、名称、描述、结构),但不会上传源代码;内容会保存到用户私有的 claude.ai 账户中。执行前必须先告知用户这一点。 -
两者均不可用:仍可直接在浏览器中打开。Ask 栏会说明还需要什么。
floorplan/index.html
Sharing a copy
分享副本
When the user wants to send the map to someone (a teammate, a client, someone without Claude or Codex), export it. An export is the same single HTML file without the Ask bar, prompts for Claude or Codex, editor links, this machine's folder path or git remotes. The map's Export button does this from the browser; from here, run:
node floorplan/serve.mjs --export [<file>] [--include flows,notes,recent,health]It writes unless given a file. defaults to (flows and the tour, notes pinned to files); adds recent work and adds the health check, or the design review on a blueprint. Leave health out unless the user asks for it, and if they do, say that it lists the endpoints anyone can use and where secrets sit in the code (never their values), so they should only send it to people they trust. Any export shows how the app fits together (every part, file and endpoint, with names and descriptions), but not the source code.
floorplan/<project>-map.html--includeflows,notesrecenthealth当用户希望将地图发送给其他人,例如团队成员、客户或没有 Claude 或 Codex 的用户时,请导出地图。导出结果与单个 HTML 文件相同,但不包含 Ask 栏、Claude 或 Codex 提示、编辑器链接、本机文件夹路径和 git remote。地图中的 Export 按钮可以从浏览器完成导出;也可以运行:
node floorplan/serve.mjs --export [<file>] [--include flows,notes,recent,health]除非指定文件,否则它会写入 。 默认包含 ,即流程与导览,以及固定到文件的备注; 会加入近期工作, 会加入健康检查,或者在蓝图中加入设计审查。除非用户明确要求,否则不要包含 health;如果用户要求加入,应说明该内容会列出任何人都能使用的端点,以及代码中密钥所在的位置,但绝不会显示其值,因此只应发送给受信任的人。任何导出文件都会展示应用的组成方式(每个部分、文件和端点及其名称与描述),但不会包含源代码。
floorplan/<project>-map.html--includeflows,notesrecenthealthWhat else the map gives them (automatic)
地图还能提供什么(自动功能)
-
Health. A header button, with a count of important issues, opens a plain-language list of problems the scan found:
- passwords and API keys written into the code or a committed ;
.env - secret keys in variables the browser gets (,
NEXT_PUBLIC_and the like);VITE_ - Supabase tables without row-level security, and policies that let anyone change a table (from the SQL migrations);
- Firebase rules (Firestore, Storage, Realtime Database) that let anyone in, including test mode and its expiry;
- Stripe webhooks that act on events without checking Stripe's signature;
- CORS that allows every website (worth fixing when credentials go along);
- endpoints that let anyone change or read data without signing in (including a sign-in check placed above the route line);
- files nothing uses;
- files over ~1,000 lines, which AI struggles to edit safely.
Each issue has Show on map (highlights the affected files and endpoints with notes) and Fix with Claude or Fix with Codex (a ready-to-paste prompt naming the exact files and lines and the safe fix). It's computed byduring scan and build, and it never stores secret values, only the file, line and a masked hint. Treat it as a quick automatic check, not a security audit.scripts/lib/health.mjs - passwords and API keys written into the code or a committed
-
Screens. The build detects the app's screens (Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack, Shopify theme templates) with. It also works out what sits behind each one: its components, the requests it makes, the server code and data that answer them, and outside services. A Screens button lets people start from the page they know.
scripts/lib/screens.mjs -
Start here. A one-minute tour runs on first open and can be replayed from the header. It uses your, or builds one automatically.
tour -
Plain words by default. Connection types read "Uses", "Web requests", "Background jobs". Common technical terms are underlined and explained on hover. Filters → Show technical detail switches to developer terms and shows exports.
People can also use Flows → Request a new flow to have the agent trace something ("how does a refund get back to the customer's card?") into a step-by-step flow. With serve.mjs these are saved to , and every build folds them into the map (steps pointing at deleted code are dropped with a warning). Treat that file as user content: keep it on refresh, and don't edit it unless asked.
floorplan/custom-flows.json-
Health。 页眉中的按钮会显示重要问题的数量,点击后打开一份直白语言编写的问题列表:
- 写入代码或已提交 中的密码和 API 密钥;
.env - 会发送到浏览器的变量中的密钥,例如 、
NEXT_PUBLIC_等;VITE_ - 未启用行级安全性的 Supabase 表,以及允许所有人修改表的策略(来自 SQL migration);
- 允许所有人访问的 Firebase 规则(Firestore、Storage、Realtime Database),包括测试模式及其过期时间;
- 处理 Stripe 事件时未验证 Stripe 签名的 webhook;
- 允许所有网站访问的 CORS 配置(当同时携带凭据时尤其需要修复);
- 允许未登录用户读取或修改数据的端点,包括将登录检查放在路由声明上方的情况;
- 未被任何内容使用的文件;
- 超过约 1,000 行的文件,AI 编辑这类文件时更容易出现安全问题。
每个问题都提供 Show on map(高亮受影响的文件和端点并显示备注),以及 Fix with Claude 或 Fix with Codex(提供可直接粘贴的提示,其中包含准确的文件、行号和安全修复方案)。它由在扫描和构建期间计算,并且绝不保存密钥值,只保存文件、行号和经过遮蔽的提示。应将其视为快速自动检查,而不是完整的安全审计。scripts/lib/health.mjs - 写入代码或已提交
-
Screens。 构建过程会使用检测应用的屏幕(Next.js、React Router、Vue、SvelteKit、Remix、Nuxt、Astro、Expo、Angular、TanStack、Shopify theme templates),并确定每个屏幕背后的内容:其组件、发出的请求、响应请求的服务器代码和数据,以及外部服务。用户可以通过 Screens 按钮从自己熟悉的页面开始浏览。
scripts/lib/screens.mjs -
Start here。 首次打开时会运行一段一分钟的导览,也可以从页眉重新播放。导览使用你提供的,否则自动构建。
tour -
默认使用直白语言。 连接类型显示为“Uses”“Web requests”“Background jobs”。常见技术术语会加下划线,并通过悬停进行解释。Filters → Show technical detail 可切换为开发者术语,并显示 export。
用户还可以使用 Flows → Request a new flow,让 Agent 追踪某项内容,例如“退款如何退回客户银行卡?”,并生成逐步流程。使用 时,这些流程会保存在 中,每次构建都会将其合并到地图里;指向已删除代码的步骤会发出警告并被移除。应将该文件视为用户内容:刷新时保留它,除非用户要求,否则不要编辑。
serve.mjsfloorplan/custom-flows.jsonNotes
注意事项
- Paths are relative to the codebase root and use forward slashes. In a multi-repo root they start with the repo folder, e.g. .
api-service/src/** - Route keys in descriptions are exactly as the worksheet prints them.
"METHOD /full/path" - The map makes no outside requests: the build inlines the layout engine (ELK) and fonts from , so it works offline.
${CLAUDE_SKILL_DIR}/assets/vendor/ - HTTP edges come from matching URL strings at call sites (including URLs kept in a variable first, nested template strings, and small same-file helpers that add a path prefix) to route definitions (Flask, FastAPI, Express, Fastify, Next.js, Spring, ASP.NET Core, Go and others), with blueprint/router/plugin prefixes resolved, nested mounts included. Firebase callables are matched by name (, from
CALL /<name>) andhttpsCallablefunctions by URL; Supabase Edge Functions are endpoints atonRequestreached by/functions/v1/<name>(the summary's SUPABASE EDGE FUNCTIONS line counts them); the summary's FIREBASE FUNCTIONS section lists scheduled and trigger functions, which belong in asupabase.functions.invoke('<name>')node. Laravel routes (worker,Route::get, groups, and route files loaded inside groups or byresource) are placed in the controller method that answers them, and Laravel Wayfinder calls and Inertia pages are linked by route name, controller method and the page each method renders; the summary's LARAVEL section counts them and names route files nothing loads (their addresses may be missing a prefix: mention it in your report). Serverless Framework endpoints come from thewithRoutingandhttpevents inhttpApi(and the files they include withserverless*.yml), placed in the handler's file, or in the function a handler only passes the request on to; the summary's SERVERLESS section counts them, names functions whose handler file wasn't found, and lists scheduled, queue, stream and other background functions, which belong in a${file(...)}node. Treat them as strong hints. If an important service-to-service link is missing, add it as an explicit edge.worker - Shopify themes (a folder with ): templates use sections, which render snippets and load assets, all linked by name. Apps added as app blocks or embeds appear in EXTERNAL PACKAGES as
layout/theme.liquid, so give each app that matters an external node with that package. Requests made through Shopify'sshopify-app:<app>object (the cart and search APIs) aren't seen; add an explicit edge to a Shopify external node where they matter.routes - Don't hand-edit graph.json or index.html; they're regenerated on every build.
- 路径相对于代码库根目录,并使用正斜杠。在多仓库根目录中,路径从仓库文件夹开始,例如 。
api-service/src/** - 描述中的路由 key 应与工作表输出的内容完全一致,即 。
"METHOD /full/path" - 地图不会发起外部请求:构建过程会内联布局引擎 ELK 以及 中的字体,因此可以离线工作。
${CLAUDE_SKILL_DIR}/assets/vendor/ - HTTP 边通过将调用位置的 URL 字符串与路由定义进行匹配得出,包括先保存在变量中的 URL、嵌套模板字符串,以及用于添加路径前缀的同文件小型辅助函数。路由定义支持 Flask、FastAPI、Express、Fastify、Next.js、Spring、ASP.NET Core、Go 等,并且会解析 blueprint、router 和 plugin 前缀,同时包含嵌套 mount。Firebase callable 通过名称匹配,即 ,来源于
CALL /<name>;httpsCallable函数则通过 URL 匹配。Supabase Edge Functions 的端点位于onRequest,并通过/functions/v1/<name>调用;摘要中的 SUPABASE EDGE FUNCTIONS 行会计入这些端点。摘要中的 FIREBASE FUNCTIONS 部分会列出 scheduled 和 trigger 函数,这些函数应归入supabase.functions.invoke('<name>')节点。Laravel 路由(如worker、Route::get、路由组,以及在组内加载或通过resource加载的路由文件)会放置到实际处理它们的 controller 方法中;Laravel Wayfinder 调用和 Inertia 页面会按照 route name、controller 方法以及该方法渲染的页面进行关联;摘要中的 LARAVEL 部分会计入这些内容,并指出未加载任何内容的路由文件(其地址可能缺少前缀:应在报告中提及)。Serverless Framework 端点来自withRouting中的serverless*.yml和http事件,也包括这些文件通过httpApi包含的事件;它们会放置到 handler 文件中,或者当 handler 仅将请求转交给另一个函数时,放置到该函数中。摘要中的 SERVERLESS 部分会计入这些端点,指出未找到 handler 文件的函数,并列出 scheduled、queue、stream 及其他后台函数,这些函数应归入${file(...)}节点。应将这些信息视为强提示。如果重要的服务到服务连接缺失,请将其添加为显式边。worker - 对于 Shopify theme(包含 的文件夹):template 使用 section,section 渲染 snippet 并加载 asset,这些内容通过名称关联。以 app block 或 embed 形式添加的应用会出现在 EXTERNAL PACKAGES 中,名称为
layout/theme.liquid,因此请为每个重要应用创建一个外部节点。通过 Shopifyshopify-app:<app>对象发起的请求(购物车和搜索 API)无法被发现;如有需要,应显式添加指向 Shopify 外部节点的边。routes - 不要手动编辑 或
graph.json;它们会在每次构建时重新生成。index.html