architecture-map

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture map

架构地图

Turn a repository into a place you can walk around: an isometric city where every building is a real subsystem sized by its real weight, every line is a call path that exists in the code, and every moving dot is a payload the app actually ships.

将代码仓库转化为一个可“漫游”的场景：一座等距视角的城市，每栋建筑对应真实子系统，大小由实际代码量决定；每条线路对应代码中存在的调用路径；每个移动的点对应应用实际传输的负载。

The one rule

核心原则

Prose, groups and flows are authored. Counts, coverage and geometry are measured.

No scanner can say what a subsystem is for, and no human can keep file counts honest. Every good property of this page falls out of that line — including the fact that it does not rot, because "unmapped files" is only meaningful once a human has claimed the rest.

Do not try to generate the authored half mechanically. Read the code and write about it. That is the work, and it is why this is a skill rather than a codegen script.

描述文字、分组和流由人工编写；数量、覆盖范围和几何尺寸由工具测算。

扫描工具无法说明子系统的用途，而人类无法保证文件数量的准确性。本工具的所有优势都源于这一原则——包括它不会“过时”，因为只有当人类已经标记了其余文件后，“未映射文件”才具有实际意义。

不要尝试通过机械方式生成人工编写的部分。请阅读代码并撰写相关描述。这是核心工作，也是本工具为何是一项技能而非代码生成脚本的原因。

Before you start

开始之前

Read

references/authoring.md

. It has the voice, the archetype vocabulary, and worked examples of good and bad node prose. Read

references/geometry.md

only if you need to hand-tune footprints or edge routes.

阅读

references/authoring.md

，其中包含写作风格、原型词汇，以及优秀和糟糕节点描述的示例。仅当需要手动调整布局或路径时，才阅读

references/geometry.md

。

Step 1 — Detect

步骤1 — 检测

Answer these from the repo. Do not ask.

Question	Where to look
Framework and router	`package.json` , `app/` vs `pages/` vs `src/routes/` , `vite.config` , `next.config` , `remix.config`
Design tokens	global stylesheet for `--*` custom properties; `tailwind.config` ; any `tokens` / `theme` module
Dark mode mechanism	`.dark` class, `[data-theme]` , or `prefers-color-scheme`
Test runner	`package.json` scripts, `vitest.config` , `jest.config`
Package manager	lockfile
Monorepo	`workspaces` , `pnpm-workspace.yaml` , `turbo.json`
Existing map	a previous `architecture.config.json` — if present, this is an update

Then run the proposer to get a first read of the shape. It lives beside this file, not in the repo you are mapping, so resolve its path first:

SKILL_DIR
— the absolute path of the directory containing this SKILL.md, which your harness reported when it loaded this file. It differs per tool (
~/.claude/skills/architecture-map
,
~/.codex/skills/architecture-map
,
~/.agents/skills/architecture-map
, a plugin cache, or a project-local
.claude/skills/…
). Substitute the literal path; do not rely on an environment variable.

bash

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

It returns directory clusters with file counts and line totals, plus suggested groups. Treat it as a draft, not an answer — it knows where code is, not what it does.

从仓库中获取以下信息，无需询问用户。

问题	查看位置
框架与路由	`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`
包管理器	锁文件
单体仓库	`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/…
）。请替换为实际路径，不要依赖环境变量。

bash

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

它会返回包含文件数量和代码行数的目录集群，以及建议的分组。请将其视为草稿而非最终答案——它只知道代码的位置，不知道代码的用途。

Step 2 — Ask exactly four questions

步骤2 — 提出四个明确问题

Ask them together — in one structured-question call if your harness has one (Claude Code:

AskUserQuestion

), otherwise as a single numbered message — then work uninterrupted. Do not drip-feed them one at a time.

Where should it live? Recommend
```
/~/architecture
```
— a
```
~
```
segment reads as "internal tool" and sorts away from real routes. Offer
```
/architecture
```
and
```
/internal/architecture
```
.
What should it cover? Whole repo / source only / one package. Preselect sensibly if it is a monorepo.
Design system. State what you detected — "Tailwind v4 with CSS custom properties" — and offer: use it, or the bundled neutral palette.
Extras. Wire the freshness check into CI? Add the sync to
```
predev
```
/
```
prebuild
```
? Include the version-history dropdown?

将这些问题一次性提出——如果你的工具支持结构化提问（如Claude Code的

AskUserQuestion

），则使用该功能；否则作为一条编号消息发送——然后不间断地开展工作。不要逐个提问。

地图应部署在何处？ 推荐
```
/~/architecture
```
——
```
~
```
段表示“内部工具”，会与实际路由区分开。同时提供
```
/architecture
```
和
```
/internal/architecture
```
作为备选。
地图应覆盖哪些范围？ 整个仓库 / 仅源码 / 单个包。如果是单体仓库，请合理预设选项。
设计系统。说明你检测到的内容——如“Tailwind v4 搭配CSS自定义属性”——并提供选项：使用仓库的设计系统，或使用内置的中性配色方案。
额外功能。是否将新鲜度检查接入CI？是否将同步操作添加到
```
predev
```
/
```
prebuild
```
脚本？是否包含版本历史下拉菜单？

Step 3 — Install the core

步骤3 — 安装核心组件

Copy

$SKILL_DIR/assets/core/

assets/stores/

and

assets/components/

into the repo under the path you agreed (e.g.

src/architecture/

). These are dependency-free apart from React, and typecheck under

strict

Then write

architecture.config.json

at the repo root:

json

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

Copy

$SKILL_DIR/scripts/architecture-sync.mjs

into the repo's own

scripts/

and add

"architecture:sync": "node scripts/architecture-sync.mjs"

将

$SKILL_DIR/assets/core/

、

assets/stores/

和

assets/components/

复制到仓库中你已确认的路径下（如

src/architecture/

）。这些组件除React外无其他依赖，且支持

strict

模式下的类型检查。

然后在仓库根目录创建

architecture.config.json

：

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"

到

package.json

的脚本中。

Adapt the theme

适配主题

Edit

components/theme.ts

only. Point each semantic name at the repo's tokens:

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

If the repo has no design system, leave the defaults — they define

--am-*

fallbacks and work standalone. Never reach for a host token anywhere except this file.

仅编辑

components/theme.ts

。将每个语义名称指向仓库的设计令牌：

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

如果仓库没有设计系统，请保留默认值——它们定义了

--am-*

回退属性，可独立运行。切勿在此文件之外引用宿主仓库的令牌。

Step 4 — Author the graph

步骤4 — 编写图谱

This is the real work. Write

graph.ts

exporting

GROUPS

NODES

EDGES

FLOWS

and

INTRO

, typed by

core/types.ts

Groups — 4–7 neighborhoods, named the way the team talks: "Entry & control", "The pixel pipeline", "Outside world". Not "utils" and "lib".

Nodes — aim for 15–25. For each, read the actual files and write:

```
whatItDoes
```
— one or two sentences, plain language, no jargon
```
howItsBuilt
```
— the interesting decision, not a dependency list
```
role
```
— a short noun phrase for the flow captions: "the session gate"
```
files
```
— real paths a reader can open

Derive

archetype

params

height

and

footprint

with

core/layout.ts

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

Keep a hand-written footprint if a human already tuned one — the merge prefers the authored value.

Edges — real call and data paths only. If you cannot point at the code that makes the call, do not draw the line. Add

via

waypoints when a route would otherwise cut through a building.

Flows — 3–6, each an ordered list of edge ids with a payload name. These are the page's verbs and the first thing a newcomer presses. Find them by tracing real paths: sign-in, the main create/read loop, the expensive background job.

Coverage — write

coverage.json

so every source file is claimed exactly once.

-prefixed keys are notes. Use

priority

when a nested directory must win over its parent. Then:

bash

node scripts/architecture-sync.mjs

Iterate until it reports zero unmapped, or until what remains genuinely is not part of the system.

这是核心工作。编写

graph.ts

文件，导出

GROUPS

、

NODES

、

EDGES

、

FLOWS

和

INTRO

，类型由

core/types.ts

定义。

分组 —— 4-7个片区，使用团队日常交流的名称：如“入口与控制”、“像素流水线”、“外部交互”。不要使用“工具库”或“通用库”这类名称。

节点 —— 目标为15-25个。对于每个节点，请阅读实际文件并撰写：

```
whatItDoes
```
—— 1-2句话，使用通俗易懂的语言，避免行话
```
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

。然后运行：

bash

node scripts/architecture-sync.mjs

反复迭代，直到工具报告零未映射文件，或剩余文件确实不属于系统的一部分。

Step 5 — Mount it

步骤5 — 挂载页面

Create the route for the detected framework — see

references/frameworks.md

. Import

keyframes.css

once. Pass

ArchitectureData

in from your graph module plus

UNCLAIMED

from the generated file.

Add

robots: noindex

if the route is public: this is a tool handed out by link, not a search result.

根据检测到的框架创建路由——参考

references/frameworks.md

。仅导入一次

keyframes.css

。从你的图谱模块传入

ArchitectureData

，并从生成的文件传入

UNCLAIMED

。

如果路由是公开的，请添加

robots: noindex

：这是一个通过链接分享的工具，而非搜索结果。

Step 6 — Verify, then be honest

步骤6 — 验证并如实告知

Typecheck and lint.

node scripts/architecture-sync.mjs --check

— must pass.

Run the app and look at it. Screenshot it. Check: no overlapping buildings, no edge cutting through a facade, every flow plays start to finish, the rail and the map agree on what is lit.
Both themes if the repo has two.

Then tell the user plainly:

The geometry and measurements are correct — they are derived. The prose is a first draft. I read the code, but "what this subsystem does" is where a single pass is weakest. Edit
graph.ts
; nothing else needs to change.

Do not leave mediocre writing behind a confident-looking map without saying so.

进行类型检查和代码审查。

运行

node scripts/architecture-sync.mjs --check

—— 必须通过。

启动应用并查看地图。截图检查：无重叠建筑，无线路穿过建筑立面，每个流都能完整播放，导航栏与地图的高亮内容一致。
如果仓库支持双主题，请检查两种主题下的显示效果。

然后如实告知用户：

几何尺寸和测算数据是准确的——它们由工具推导得出。描述文字为初稿。我已阅读代码，但“子系统的用途”是单次扫描最薄弱的部分。请编辑
graph.ts
；其他内容无需修改。

不要在看似专业的地图背后留下平庸的描述文字而不加以说明。

Updating an existing map

更新现有地图

architecture.config.json

exists, this is an update. Never clobber authored content.

Run the sync. New numbers land in the generated file; nothing else moves.
Read
```
UNCLAIMED
```
. Each entry is either a subsystem the map has not been told about, or an existing module whose pattern is too narrow.
For genuinely new subsystems: append a node with derived geometry and drafted prose, and extend
```
coverage.json
```
. Leave every existing node's prose, footprint and edges exactly as they are.
Report what you added and what you left alone.

如果

architecture.config.json

已存在，则本次为更新操作。切勿覆盖人工编写的内容。

运行同步脚本。新数据会写入生成的文件；其他内容保持不变。
查看
```
UNCLAIMED
```
。每个条目要么是地图未收录的新子系统，要么是现有模块的匹配模式过窄。
对于真正的新子系统：追加一个带有推导几何尺寸和初稿描述的节点，并扩展
```
coverage.json
```
。保留所有现有节点的描述、布局和连线不变。
告知用户你添加了哪些内容，以及保留了哪些原有内容。

Scale

规模适配

Past ~25 buildings the map stops being readable. The proposer folds the smallest siblings into a parent node that owns the wider glob — the partition stays total, only the drawing simplifies. If a repo genuinely needs more, map one package at a time rather than shrinking everything.

当建筑数量超过25个时，地图将变得难以阅读。提议工具会将最小的子节点合并到父节点中，父节点对应更宽泛的匹配模式——分区范围保持不变，仅显示方式简化。如果仓库确实需要展示更多内容，请逐个包进行映射，而非缩小所有元素。

What not to do

禁止操作

Do not draw an edge you cannot trace to a call in the code.
Do not set prose in the mono face. Monospace is for codes and paths.
Do not import a host repo's
```
Button
```
or
```
Dropdown
```
— the map ships its own.
Do not hand-write file counts. That is what the scanner is for.
Do not invent flows that sound good. A flow nobody can follow in the source is a lie the page tells confidently.

不要绘制无法追踪到代码中调用位置的连线。
不要使用等宽字体书写描述文字。等宽字体仅用于代码和路径。
不要导入宿主仓库的
```
Button
```
或
```
Dropdown
```
组件——地图自带这些组件。
不要手动编写文件数量。这是扫描工具的职责。
不要虚构听起来合理的流。如果无法在源码中追踪到某个流，那么地图就是在传递虚假信息。