🧭 How to Make a Map — 做出一張好心智圖

任何人 + 任何 AI agent，照這個配方就能做出品質一致的心智圖。這是「地圖的地圖」——關於怎麼做地圖的心智圖。 不照配方直接叫 AI「畫一張 mermaid 心智圖」，得到的通常是一坨看不懂的怪圖 — 我們踩過這個坑。

為什麼會失敗

AI 一次同時做「理解」和「畫圖」就會壞掉。圖是已經整理好的理解的呈現方式， 不是理解本身。所以配方的核心只有一句話：先產出結構化文字報告，再畫圖。

另外兩個常見的失敗：

• 畫了一張沒有人需要的地圖。 地圖本身也是一個產品，所以動工前先填意圖卡（product-intent-map 第 3 節）：給誰、改變什麼、怎麼知道成了、不做會怎樣、邊界在哪。
• 地圖只畫了「它怎麼運作」，沒回答「它為什麼存在、是不是最佳解」。 讀者看完知道零件，卻不知道什麼時候該用它、什麼時候不該。所以探索之後、畫圖之前，五問必答（同文件第 8 節）。

兩者是同一個 DNA 的兩個尺度——意圖卡管「這張地圖該不該存在」（需求進門），五問管「地圖畫的東西站不站得住」（提案出門）。

五步驟配方 Step 0–4（直接複製給你的 agent）

Step 0 — 先填地圖的意圖卡（動工前，五格答不完就不要畫）

欄位	對地圖來說的問題
誰的問題	這張地圖給誰看？叫得出名字或角色嗎？
改變什麼	讀完後，他們能做什麼原本做不到的事？
成功訊號	怎麼知道地圖成功了？（例：新人不用問人就能上手）
不做會怎樣	不畫的代價是什麼？（答不出來＝不值得畫）
邊界	這張地圖刻意不涵蓋什麼？（3–5 條）

Step 1 — 先理解，禁止畫圖

Explore this repo/topic and return a structured TEXT report (no diagrams yet):
what it is in one paragraph, the 5-8 core concepts a newcomer must know,
how things flow end to end, the main entry points, and the rules/invariants
it enforces. Give evidence (file paths / sources). Max 150 lines, no dumps.

Step 2 — 五問必答（探索完的預設關卡，答不出來就回 Step 1）

Before any diagrams: answer the Five-Ask (五問) about the subject, one short
paragraph each, based ONLY on the Step-1 report. Mark guesses as assumptions.
1. 解決什麼問題？   What concrete pain does this exist to solve?
2. 考慮過什麼替代方案？ What alternatives exist / why were they rejected?
3. 怎麼解決？       The actual mechanism, not the marketing.
4. 有什麼限制/風險？  Known limits, non-goals, failure modes.
5. 是最佳方案嗎？    Best current tradeoff — and what it deliberately does NOT optimize for.

為什麼必答：五問的答案就是地圖的「意圖層」——讀者靠它判斷該不該用這個東西， 而不只是它怎麼動。五問詳解見 product-intent-map 第 8 節。 （注意別跟 Step 0 的意圖卡搞混：意圖卡問的是你的地圖，五問問的是被畫的主題。）

Step 3 — 規劃圖，一張圖只回答一個問題

From that report, propose 5-7 mermaid diagrams. Each diagram answers ONE
question (e.g. "how does data flow in?", "what is the trust boundary?").
Max ~15 nodes each. List them for my approval before drawing.

Step 4 — 才開始寫文件

Now write the full mental-model doc: prose sections with one diagram each,
a summary table of core concepts, a Five-Ask answers table, and a
best-practices section. Output as README.md with ```mermaid fences.

文件骨架（每張地圖長這樣）

README.md
├── 一段話講清楚這是什麼（放最上面，blockquote）
├── 五問速答（表格：五問各 ≤2 句 — 地圖的意圖層）
├── 大局觀（1 張全景圖）
├── 核心概念（每個概念 1 節：短文字 + 1 張圖）
├── 運作方式（流程/時序）
├── 最佳實踐 / 地雷區（表格）
└── 這張地圖不涵蓋什麼（邊界：3–5 條「不」——展示不出來的，就是還沒決定的）

收藏規則（讓地圖長大也找得到）

1. Repo 名稱以 -map 結尾——地圖用名字就認得出來。
2. 一張地圖一個 repo，README 就是地圖本體（GitHub / GitLab 都原生渲染 mermaid）。
3. 維護一個 maps-index（地圖的地圖的地圖）：一列一張地圖——名稱、一句話說明、連結。 沒登記 = 不存在。開會分享連結永遠只從 index 出發。
4. 含真實資料、內部策略、真實姓名的內容 → 留在私有空間，在 index 只登記名稱、不加連結 （投影時就不可能誤點）。
5. 每張地圖只有一個正本。公開版是刻意去敏後的另一個版本，不是鏡像——不要手動維護兩份一樣的副本。