architecture-map

架构地图

把一个代码库变成一处可以漫步的地方：一座等距视角的城市，每栋建筑都是真实子系统，其大小反映实际权重；每条线都是代码中实际存在的调用路径；每个移动的点都是应用实际发送的有效负载。

唯一规则

说明文字、分组和流程由人编写。数量、覆盖情况和几何布局通过测量得出。

扫描器无法判断某个子系统用途是什么，而人也无法始终如一地准确维护文件数量。这个页面的所有优点都源于这条规则——包括它不会腐朽这一点，因为只有在人类认领了其余部分后，“未映射文件”才有意义。

不要试图机械地生成由人编写的部分。阅读代码并描述它。这就是这项工作的内容，也是它之所以是一项技能而非代码生成脚本的原因。

开始之前

阅读 references/authoring.md。其中介绍了文风、原型词汇，以及优秀和糟糕节点说明的完整示例。只有在需要手动微调占地面积或边缘路径时，才阅读 references/geometry.md。

步骤 1 — 检测

根据代码库回答以下问题。不要提问。

问题	查看位置
框架和路由器	package.json、app/ 与 pages/ 或 src/routes/、vite.config、next.config、remix.config
设计令牌	全局样式表中的 --* 自定义属性；tailwind.config；任何 tokens/theme 模块
暗色模式机制	.dark 类、[data-theme] 或 prefers-color-scheme
测试运行器	package.json 脚本、vitest.config、jest.config
包管理器	锁文件
Monorepo	workspaces、pnpm-workspace.yaml、turbo.json
现有地图	之前的 architecture.config.json — 如果存在，则这是一次更新

然后运行提议器，初步了解代码库结构。它与此文件位于同一位置，而不在你要绘制地图的代码库中，因此请先解析其路径：

SKILL_DIR — 包含此 SKILL.md 的目录绝对路径，由你的运行环境在加载此文件时报告。该路径因工具而异（~/.claude/skills/architecture-map、~/.codex/skills/architecture-map、~/.agents/skills/architecture-map、插件缓存或项目本地的 .claude/skills/…）。请替换为实际路径；不要依赖环境变量。

node "$SKILL_DIR/scripts/propose-coverage.mjs" --root . --target 22

它会返回带有文件数量和总行数的目录簇，以及建议的分组。将其视为草稿，而非答案——它知道代码在哪里，却不知道代码做什么。

步骤 2 — 恰好提出四个问题

把问题放在一起提出——如果你的运行环境支持结构化提问调用（Claude Code：AskUserQuestion），就使用该调用；否则发送一条带编号的消息——之后不受打扰地继续工作。不要一次只问一个问题。

1. 地图应该放在哪里？ 建议 /~/architecture——~ 这个路径段表示“内部工具”，并会与实际路由分开排序。也提供 /architecture 和 /internal/architecture 两个选项。
2. 地图应该覆盖哪些内容？ 整个代码库 / 仅源码 / 单个包。如果是 Monorepo，请合理预选。
3. 设计系统。 说明检测到的内容——“Tailwind v4 搭配 CSS 自定义属性”——并提供选项：使用现有设计系统，或使用捆绑的中性色板。
4. 附加选项。 是否将新鲜度检查接入 CI？是否将同步操作加入 predev/prebuild？是否包含版本历史下拉菜单？

步骤 3 — 安装核心组件

将 $SKILL_DIR/assets/core/、assets/stores/ 和 assets/components/ 复制到代码库中你们约定的路径下（例如 src/architecture/）。除 React 外，这些组件不依赖其他依赖项，并且能通过 strict 类型检查。

然后在代码库根目录创建 architecture.config.json：

{
  "coverage": "src/architecture/coverage.json",
  "output": "src/architecture/measured.generated.ts",
  "sources": ["src/**/*.{ts,tsx}", "scripts/**/*.mjs"],
  "ignore": ["next-env.d.ts"]
}

将 $SKILL_DIR/scripts/architecture-sync.mjs 复制到代码库自己的 scripts/ 目录，并添加 "architecture:sync": "node scripts/architecture-sync.mjs"。

适配主题

仅编辑 components/theme.ts。将每个语义名称指向仓库的设计令牌：

export const paint = {
  surface: 'var(--tsc-background)',
  border: 'var(--tsc-foreground-tertiary)',
  accent: 'var(--tsc-brand)',
  // …
}

如果仓库没有设计系统，就保留默认值——它们定义了 --am-* 回退值，可以独立使用。除本文件外，绝不要在任何地方使用宿主令牌。

第 4 步——编写图谱

这是实际的工作。编写 graph.ts，导出 GROUPS、NODES、EDGES、 FLOWS 和 INTRO，并使用 core/types.ts 中的类型。

分组——划分为 4–7 个区域，名称要符合团队的日常说法：“入口与控制”、 “像素管线”、“外部世界”。不要用“utils”或“lib”。

节点——以 15–25 个为目标。对于每个节点，阅读实际文件并编写：

• whatItDoes——用通俗语言写一到两句话，不用术语
• howItsBuilt——说明有意思的设计决策，而非依赖列表
• role——用于流程说明的简短名词短语，例如“会话关卡”
• files——读者可以打开的真实路径

使用 core/layout.ts 推导 archetype、params、height 和 footprint：

const { archetype, params } = deriveArchetype(measure)
const height = deriveHeight(measure)
const footprints = packLayout(inputs, GROUPS.map((g) => g.id))

如果人工调整过某个 footprint，就保留它——合并时优先采用编写好的值。

边——只添加真实的调用和数据路径。如果无法指出发起调用的代码，就不要画这条线。如果某条路线会穿过建筑，则添加 via 路径点。

流程——编写 3–6 个流程，每个都是按顺序排列的边 ID 列表，并带有载荷名称。这些是页面上的动词，也是新手首先会点击的内容。通过追踪真实路径来确定：登录、主要的创建/读取循环、耗时的后台任务。

覆盖范围——编写 coverage.json，确保每个源文件恰好归属一次。以 $ 开头的键是备注。嵌套目录必须优先于父目录时，使用 priority。然后：

node scripts/architecture-sync.mjs

持续迭代，直到未映射项为零，或者剩余项确实不属于系统。

第 5 步——挂载

为检测到的框架创建路由——参见 references/frameworks.md。 只导入一次 keyframes.css。从图谱模块传入 ArchitectureData， 并从生成文件传入 UNCLAIMED。

如果路由是公开的，请添加 robots: noindex：这是通过链接分发的工具，不是搜索结果。

第 6 步——验证，然后坦诚说明

1. 执行类型检查和 lint。
2. 运行 node scripts/architecture-sync.mjs --check——必须通过。
3. 运行应用并亲自查看。截屏检查：建筑之间没有重叠，没有边穿过立面，每个流程都能从头到尾运行，侧栏和地图对高亮内容的显示一致。
4. 如果仓库支持两种主题，都要检查。

然后直接告诉用户：

几何形状和测量值是正确的——它们是推导出来的。**文字说明是初稿。**我阅读了代码，但“这个子系统做什么”最容易在一次编写中出错。编辑 graph.ts 即可；其他内容无需改动。

不要把平庸的文字藏在看似可靠的地图后面，却不说明这一点。

更新现有地图

如果存在 architecture.config.json，说明这是一次更新。绝不要覆盖已有内容。

1. 运行同步。新数字会写入生成文件；其他内容不会变动。
2. 查看 UNCLAIMED。每个条目要么是地图尚未说明的子系统，要么是现有模块的匹配模式过于狭窄。
3. 对于真正新增的子系统：追加一个带有推导几何信息和初拟文字说明的节点，并扩展 coverage.json。现有节点的文字说明、占地范围和边都必须原样保留。
4. 报告新增了什么，以及哪些内容保持不变。

规模

超过约 25 栋建筑后，地图就会变得难以阅读。提议器会将最小的同级节点折叠到拥有更大 glob 范围的父节点中——分区仍然完整，只是图示变得更简洁。如果仓库确实需要更多节点，就按包逐个绘制，而不是把所有内容都缩小。

不要做的事

• 不要绘制无法追溯到代码中某个调用的边。
• 不要使用等宽字体排版正文。等宽字体用于代码和路径。
• 不要导入宿主仓库的 Button 或 Dropdown——地图自带这些组件。
• 不要手动填写文件数量。扫描器就是用来做这件事的。
• 不要编造听起来不错的流程。若无人能在源码中找到某个流程的依据，那么页面就是在自信地撒谎。