floorplan

Floorplan

你会在代码库根目录生成 floorplan/：一份应用平面图，让初次接触的人能像看系统图一样读懂应用。每张卡片都显示一个易懂的名称和一句话描述，下方以小字显示实际路径。

• 你编写： architecture.json（子系统、模块、流程）和 descriptions/*.json（为每个文件和路由提供名称与描述）。
• 自动生成： graph.json 和 index.html。

脚本会处理机械性工作：查找代码库、解析导入和路由、将 HTTP 调用匹配到端点，以及布局和渲染。你的工作是只有代码读者才能完成的部分：判断各项内容是什么，并清楚地说明。

现有地图： !node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || true 参数：$ARGUMENTS

已有地图？请刷新，而不是从头开始

如果上方状态显示已有地图，不要从头开始。运行：

node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>

它会重新扫描，将内容指纹与上次构建进行比较，并自动处理相关记录，不消耗令牌：

• 将描述保留给已移动或重命名的文件和端点；
• 删除已删除文件的条目；
• 对导出内容或路由发生变化的条目标记 review 注释（函数体内部的编辑不计入）；
• 重新构建；
• 输出变更内容和简短的 NEXT 列表。

只执行 NEXT 要求的事项：

• 为新加入 “unassigned” 的目录添加 glob；
• 运行 describe.mjs（第 6 步），现在它只会为新增和标记的项目生成工作表；
• 如果变更较大，检查模块摘要和流程。

经过几小时工作后进行一次常规刷新，通常只会有少量工作表条目。然后标记近期工作（第 7 步），并展示地图和报告（第 8 步）。务必展示地图，即使没有任何变更也要展示：用户要求查看他们的平面图。

工作流（首次运行）

如果提供了参数，代码库根目录就是该参数；否则使用当前目录。它可以是单个代码库，也可以是包含多个代码库的普通文件夹（前端 + 后端 + 基础设施等）。扫描器会查找其中所有 git 代码库，并跳过重复的工作树。

1. 扫描。 node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root> 它会写入 floorplan/.cache/scan.json 并输出摘要：代码库、包含代码行数的代码树、入口点、最重的目录→目录导入边、跨代码库的 HTTP 调用→路由匹配项、外部包和主机。根据摘要开展工作。不要读取 scan.json，它很大。

2. 阅读约定。 阅读 references/schema.md（architecture.json 格式）和 references/choosing-boundaries.md（如何将代码库划分为一张好的地图）。

3. 适度探索。 阅读 README、清单文件（package.json、pyproject、go.mod、docker-compose、部署配置）和入口点，然后浏览每个候选子系统的 1–2 个文件，直到能为每个子系统写出一句话摘要。你要了解的是系统的整体结构，而不是进行代码审查。

4. 编写 floorplan/architecture.json。 目标：

   • 3–9 个顶层节点；
   • 每个大型节点下有 3–12 个子节点；
   • glob 覆盖 90% 以上的代码文件；
   • 为代码实际交互的数据库和第三方服务创建外部节点；
   • 只为扫描器无法识别的内容添加边（队列、cron、webhook、通过环境变量配置的 URL 进行的跨服务调用）；
   • 用 1–3 个流程说明系统的主要工作；
   • 添加一个 tour：包含 3–8 个讲解站点，用于“从这里开始”导览（见下文）。

   每个节点都需要有 summary。 受众。 打开这张地图的人通常是应用的所有者，往往是借助 AI 制作应用的非技术开发者。除非用户要求面向开发者的地图，否则请将 "audience" 留空或设为 "everyone"，并用通俗易懂的语言编写每个 project.summary、节点的 label/summary 以及文件/路由说明（参见 references/writing-descriptions.md 中的“Plain language”）。使用简短标签，例如“主服务”，而不是“商店 API（Flask）”。卡片上会显示路径和方法/URL，因此说明只需写清该项的用途。

   导览。 添加 "tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }]，并按新手应当查看的顺序设置站点：应用是什么、用户会使用哪些应用、主服务、外部服务，最后以一个重要屏幕的文件收尾。标题和备注要用通俗易懂的语言，让从未读过代码的人也能看懂。第一个引导流程会自动添加在末尾，名称为“查看真实请求”。如果没有导览，系统会根据节点摘要和第一个流程生成一个，因此请确保摘要写得好，并且至少有一个流程。

5. 构建并修复。 node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> 该命令会验证所有内容并指出每个问题（“是否想输入……”，未分配的文件目录、含义不明确的 glob）。修复问题并重新构建，直到构建通过且未分配文件占比低于约 10%。

   Floorplan 创建的内容都不会被提交。 floorplan/ 中有自己的 .gitignore，会忽略整个目录，因此不会触及项目中受 Git 跟踪的文件。如果 Git 已经在跟踪其中的文件，构建会打印用于取消跟踪的 git rm -r --cached 命令；请将该命令转交给用户，而不要自行运行。

   每次构建还会在项目的 CLAUDE.local.md 中保留一个带标记的简短区块。CLAUDE.local.md 是 Claude Code 的个人项目备注，不会提交，并且会像 CLAUDE.md 一样在会话开始时加载。该区块会告知之后在此处运行的 Claude Code 会话地图已经存在，以及如何使用 floorplan/query.mjs 查找信息，让它们从地图开始，而不是从头搜索代码。构建会将 CLAUDE.local.md 添加到仓库的本地忽略列表（.git/info/exclude，而非 .gitignore）。它只会重写自己的区块；如果旧版本将区块放在 CLAUDE.md 中，则会将其移出。若要选择不使用此功能，请传入 --no-claude-md，或在 CLAUDE.local.md 中写入 ``。

6. 描述每个文件和路由。 node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root> 该命令会为每个模块生成一份工作表（floorplan/.cache/worksheets/<key>.md）以及一份待填写的框架文件（floorplan/descriptions/<key>.json）。每份工作表都包含每个文件（文档字符串、定义、使用项和引用方）以及每个路由（处理程序、文档字符串）的摘要，足以在不打开文件的情况下描述大多数文件。

   • 请先阅读 references/writing-descriptions.md。
   • 文件超过约 150 个： 如果有可用的并行子 Agent，请将工作表分配给它们，每个负责约 100–150 个文件，并按领域分组（后端路由、服务、脚本、测试、UI）。为每个子 Agent 提供其工作表键、代码库根目录和编写指南，并要求它仅编辑自己的 descriptions/<key>.json 文件，且保持键不变。
   • 较小的代码库： 自行完成。

   然后重新构建。构建结果会报告 DESCRIPTIONS files X/Y · routes X/Y。两项都要达到 100%：重新运行 describe.mjs，它只会列出仍缺少说明的内容。

7. 标记近期工作。 地图会突出显示刚完成的工作：相关卡片会带有绿色的“已更改”/“新增”标签，包含这些卡片的部分会显示“已更改 N 项”，悬停时会显示你的备注，而 近期工作 按钮会将它们排列在同一张板上。每次创建和每次更新时都要执行此操作，因为它会替换之前的高亮内容。 node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root> 它会列出自上一张地图以来的更改、未提交的更改和近期提交，并将每项匹配到它所在的卡片。原因 由你来说明：

   • 哪些内容算在内。 本次对话中由你或你的子 Agent 完成的工作是主要依据。参考你对这些工作的了解。如果你在本次对话中没有做任何工作（新会话），则使用 recent.mjs 显示的、显然仍在进行中的内容：未提交的更改和最新提交。如果没有任何内容，写入 { "tasks": [] }，以清除旧的高亮。
   • 写入 floorplan/recent-work.json。 用户每提出一项请求，就对应一个任务：title（2–5 个词）、request（用用户自己的话简短描述其请求）、summary（用 1–2 句话说明为此完成了什么工作、目前进展如何，并包含任何已删除的内容，因为已删除的文件无法高亮）。然后添加 items：发生更改的卡片，以文件路径、节点 ID 或 "METHOD /path" 表示，并附上 change（"new" 或 "changed"）和 note。
   • 每条备注都要回答“这与用户的请求有什么关系？” 用一两句通俗的话说明这张卡片上改了什么，以及为什么用户的请求需要这项更改。例如：“现在能捕获地址先在变量中构造的 Web 请求，因此订单和库存页面此前没有显示任何服务器调用的问题得到了解决。”而不是“添加了 flattenTemplates 和 variableUse 辅助函数”。
   • 突出重要内容。 选择本次请求中行为发生变化的文件和端点，通常为 3–15 项。除非测试和顺带修改本身就是重点，否则跳过它们。包含已更改端点的文件可以同时列出文件和端点。
   • 除非受众是开发者，否则不要使用代码中的术语。 备注中绝不要写入机密信息。

   格式：references/schema.md#recent-work。然后运行 build.mjs。它会报告 RECENT WORK N card(s) highlighted，并对地图上不存在的引用发出警告。

8. 展示后再汇报。 每次创建或更新平面图后，都要将其展示给用户： node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>

   • 它会在后台启动地图的服务器（或复用已为此地图运行的服务器），并在浏览器中打开地图。已打开的标签页会在原处重新加载，而不会另开新标签页。
   • 它会输出 URL、Ask 是否可用（是否找到 Claude Code CLI），以及如何停止服务器。最后一个标签页关闭几小时后，服务器也会自动停止。
   • 如果你有应用内浏览器或预览工具，请传入 --no-open，并在其中打开输出的 URL，这样地图就会显示在对话旁边。
   • 如果这是用户无法访问 127.0.0.1 的远程或无头机器，请跳过 open.mjs，并告知用户在自己的机器上运行 node floorplan/serve.mjs，或者提供 Claude 应用的方案（第 9 步）。 然后报告。先提供 URL，再用用户的语言在 3–5 行内描述你梳理出的架构，包括任何意外情况：循环依赖、臃肿文件、闲置区域、耦合的子系统。务必提及高严重性健康问题（graph.health；构建输出和 graph.json 都会列出这些问题）。硬编码的密码/密钥，以及任何人都能通过其更改数据的端点，都是所有者需要了解的事项。绝不要重复秘密值。说明 architecture.json 和 descriptions/ 都可以由他们编辑；继续投入更多工作后，他们只需说“更新平面图”，系统就会重新读取发生变化的内容。请直接告诉他们这些话，不要用斜杠命令：作为插件安装时，命令是 /floorplan:floorplan；作为个人技能时，命令是 /floorplan。首次运行时，用一行说明地图及其供未来会话使用的备注（在 CLAUDE.local.md 中）不会纳入 git.md，以便未来会话使用这张地图。更新时，先说明针对用户要求做了哪些更改（这些内容会在近期工作下突出显示）。

9. 打开地图并提问

地图上有一个悬浮的提问栏。用户输入问题后，Claude 会用文字和一个答案面板作答：相关卡片、卡片之间的连接、每张卡片的备注，以及可选的分步讲解。有两种方式可为其提供支持。两种方式的界面相同。

• Claude Code CLI（推荐）。 地图的服务端（floorplan/serve.mjs，由第 8 步中的 open.mjs 启动）会在 http://127.0.0.1:4378 上提供地图；若该端口已被占用，则使用下一个可用端口。每个问题都会在代码库中运行用户的 claude CLI，并使用只读工具（通过 floorplan/query.mjs 查询地图，以及通过 Read/Grep/Glob 检索源代码），因此答案可以引用实际代码。脚本会在 PATH 或 ~/.local/bin 中查找 claude；--claude <path> 可覆盖该路径，--model <name> 可指定模型（open.mjs 会传递这两个参数）。用户也可以随时自行运行 node floorplan/serve.mjs；若要停止后台运行的服务端，可运行 node floorplan/serve.mjs --stop。

• Claude 应用。 如果你在 Claude 应用中运行（可使用 Artifact 工具），可以提出发布地图，让用户在其中打开地图，并使用自己的 Claude 账户提问。此时答案仅来自地图（名称、描述、连接、端点），而非源代码；提问栏也会提示安装 CLI 以获得更好的体验。发布步骤如下：

  1. node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifact。此命令会生成 floorplan/artifact.html，其中不包含该机器的绝对路径。
  2. 使用 Artifact 工具发布该文件，设置 capabilities: {"sample": {}}，并在后续发布时保持相同的文件路径，以确保 URL 不变。
  3. 每次刷新后，都要使用 --artifact 重新构建并重新发布。

  发布会将地图（路径、名称、描述、结构）上传到用户的私人 claude.ai 账户，而不是上传源代码。执行此操作前，请先说明这一点。

• 两种方式都不具备： 仍可直接在浏览器中打开 floorplan/index.html。提问栏会说明所需条件。

这张地图还会自动提供哪些信息

• 健康状况。 标题栏中的按钮会显示重要问题的数量。点击后会打开一份通俗易懂的问题清单，列出扫描发现的问题：

  • 密码和 API 密钥直接写在代码中，或已提交的 .env 文件中；
  • 无需登录即可让任何人修改或读取数据的端点（包括把登录检查写在路由定义行上方的情况）；
  • 没有被使用的文件；
  • 超过约 1,000 行的文件，AI 很难安全地编辑这类文件。

  每个问题都有 在地图中显示（高亮相关文件和端点，并附上说明）和 使用 Claude 修复（生成可直接粘贴的提示词，指出确切文件和行号，并说明安全的修复方法）选项。扫描和构建时，scripts/lib/health.mjs 会计算这些信息；它不会存储机密值，只记录文件、行号和脱敏提示。请将其视为快速自动检查，而非安全审计。

• 屏幕。 构建过程会通过 scripts/lib/screens.mjs 检测应用的屏幕（Next.js、React Router、Vue、SvelteKit、Remix、Nuxt、Astro、Expo、Angular、TanStack）。它还会梳理每个屏幕后面的内容：组件、发起的请求、响应这些请求的服务端代码和数据，以及外部服务。点击 屏幕 按钮，用户即可从熟悉的页面开始探索。

• 从这里开始。 首次打开时会播放一分钟的导览，也可以从标题栏重新播放。它会使用你的 tour，或者自动生成导览。

• 默认使用通俗语言。 连接类型会显示为“使用”“Web 请求”“后台任务”。常见技术术语会加下划线，悬停即可查看说明。筛选器 → 显示技术细节 会切换为开发者术语并显示导出项。

用户还可以通过 流程 → 请求新流程，让 Claude 追踪某个功能并生成分步流程（例如“退款如何退回客户的银行卡？”）。使用 serve.mjs 时，这些流程会保存到 floorplan/custom-flows.json；每次构建都会将它们纳入地图中（若步骤指向已删除的代码，会发出警告并移除该步骤）。请将此文件视为用户内容：刷新时保留，除非收到要求，否则不要编辑。

备注

• 路径相对于代码库根目录，并使用正斜杠。在多仓库根目录中，路径会以仓库文件夹开头，例如 api-service/src/**。
• 描述中的路由键必须与工作表打印的内容完全一致，格式为 "METHOD /full/path"。
• 查看器会从 CDN 加载布局引擎（ELK）和字体。若要让输出可离线使用，请将 elk.bundled.js（elkjs 0.9.x）放入 ${CLAUDE_SKILL_DIR}/assets/vendor/，构建过程便会将其内联。
• HTTP 边会通过匹配调用位置中的 URL 字符串（包括先存入变量的 URL、嵌套模板字符串，以及会添加路径前缀的简短同文件辅助函数）与路由定义（Flask、FastAPI、Express、Next.js、Spring、Go 等）建立，并解析 blueprint/router 前缀、包含嵌套挂载。请将这些信息视为强提示。如果缺少重要的服务间连接，请将其添加为显式边。
• 不要手动编辑 graph.json 或 index.html；每次构建都会重新生成它们。