# Foundation Design

> 地基工作的單一入口與路由層。逐維度決定「本專案的地基產物是什麼」，權威只提供預設產物，形態不符時改寫產物而非跳過維度。維度含 UI／測試／資料庫／DevOps／可觀測性，各指名既有權威並標明權威缺席時的處置。新舊專案一體適用：接手他人專案先盤點萃取再命名固化。觸發詞：地基、地基波、元件庫、design token、fixture、seed、migration、scaffold、鷹架、腳手架、接手老專案。Do NOT use for 環境安裝（用 project-init）。

- Skill: `tarrragon/foundation-design` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add tarrragon/foundation-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tarrragon/foundation-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: tarrragon (https://skillmd.com/u/tarrragon)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tarrragon/foundation-design

---


# Foundation Design

規格說系統**做什麼**；地基工作決定實作用什麼**具名材料**來蓋。本 skill 是那些工作的**單一入口與路由層**。

**具名材料**指值有單一定義位置、程式碼只引用名字的那些東西：色票、間距、字級、文案 key、fixture、migration、CI gate 門檻。判別問「這個值改掉時，要改幾個地方」，超過一個就還不是具名材料。

**與 `project-init` 的分界**：`project-init` 處理環境安裝（工具鏈、相依套件、可執行環境）；本 skill 處理環境就緒之後、實作開始之前的材料設計。兩者在 scaffold 一詞上重疊，判別問「產出的是可執行環境，還是被引用的具名值」。

## 判準的通用形式：問作用，不問存在

本 skill 的每一條判準都問「**它對本專案有沒有作用**」，不問「它存不存在」。存在性檢查對有效性零鑑別力——文件存在不代表它回答得了問題，執法載體存在不代表它掃得到本專案的檔案。實跑證實這個區別會翻轉答案，因此它是讀本文件的通用前提，不是個別條文的例外。

**判準的查證對象一律是版控內容（tracked），不是工作目錄。** 未進版控的本地檔（被 gitignore 的設定檔、個人筆記）在別人的 clone 裡不存在，用它判定會讓同一個 repo 在不同機器上得出不同結論。

## 本 skill 不做什麼

**不重新定義任何維度的判準。** 五個維度全部已有既有權威。本 skill 的職責是指名它們、界定每個維度在本專案該產出什麼、標明權威缺席時的處置、以及交接契約。

會需要這個入口，是因為那些權威散在四類載體：

| 載體 | 本框架的實例 | 它承擔什麼 |
|------|------------|-----------|
| 方法論 | 元件庫雙向約束方法論 | 定判準 |
| orchestration skill | `version-bootstrap`（「建 Spec 骨架」與「地基波」兩步） | 在規劃流程的某一步編排 |
| 執法工具 | CI 的裸值檢查、專案的 PreToolUse guard | 掃描既成違規 |
| 範本 skill | `doc` 的 design-system spec 範本 | 提供產出物契約 |

各自完整，但沒有任何一處回答「地基這件事整體從哪開始」。主動查重的人讀過 orchestration skill 的章節標題、確認不重疊，仍會判定地基無人承接而重造一份。缺口在可發現性，不在能力。

> **本文件指名權威用名字，不用檔案路徑。** skill 以名字載入（走 Skill 工具），方法論與規則以標題檢索（`grep -rl "<標題>" .claude/`）。路徑是「它現在放在哪」，會隨框架改版而移動；名字是「它是什麼」，不會。前一版寫死路徑的後果實測過兩次：框架改版把 hook 移了位置使註冊全數失效，以及可攜性閘門把 25 處路徑判為「指名他專案的檔案」而擋下推送。

## 維度與產物

**判定的對象是產物，不是維度。** 每個維度都要回答一次「本專案的產物是什麼」，權威提供的只是**預設產物**。形態不符時改寫產物，不跳過維度。

| 維度 | 權威來源（判準在此，本 skill 不複述） | 權威提供的預設產物 | 適用條件 |
|------|--------------------------------|------------------|---------|
| **UI** | 元件庫雙向約束方法論的〈地基波 build 順序〉，四塊依序：i18n → design-system → UX 審查 → 元件庫。UX 審查那塊的執行方法見 `ux-design-evaluation` skill；元件庫那塊實作前的契約程序（元件契約欄位表、容器元件）見 `component-contract-design` skill | 四塊各自的實作票；元件庫 `blockedBy` 前三塊與契約齊全 | 不限（權威非 SaaS 特定） |
| **測試** | `tdd` skill 的分層測試策略，以及其 Phase 2 測試設計檢驗 Q9–Q14（資料是否碰巧通過、error path 覆蓋、資料工廠版本、防哪種改壞、斷言是否 flaky、資料代表性） | fixture 策略、分層地基 | 不限（權威非 SaaS 特定） |
| **資料庫** | `saas-tech-selection` skill 的 state-storage 維度（migration 版本化紀律、多租戶資料模型、**防護底線的自動備份與還原驗證**） | migration baseline、**備份與還原驗證**。seed 見〈權威缺席時〉形態 3 | SaaS/伺服器端專案照預設；非 SaaS 專案見下方處置 |
| **DevOps** | `saas-tech-selection` skill 的 reliability 維度（CI gate 構成與起始門檻） | CI gate、部署與還原配方 | SaaS/伺服器端專案照預設；非 SaaS 專案見下方處置 |
| **可觀測性** | 專案的可觀測性規則（統一 log 入口、catch 區塊要求；屬自動載入層，多半已在 context 中），以及 `saas-tech-selection` skill 的 observability 維度（錯誤分類） | log 接線點、錯誤分類骨架 | log 接線點不限；`saas-tech-selection` 的錯誤分類部分限 SaaS/伺服器端，非 SaaS 專案見下方處置 |

**本表列的是五個常見維度，不宣稱窮盡地基的全部外延。** 專案若有本表未涵蓋的地基工作（如協定契約、資料匯入匯出格式），照同一形式增列一行。

**資料庫／DevOps／可觀測性三維度的非 SaaS 專案處置**：這三列的權威來源以 SaaS/伺服器端專案為預設形態，對非 SaaS 專案形態不符時走〈權威缺席時〉「權威存在但形態不符」，先取權威中與形態無關的部分；**不新增第二套權威**。完整處置流程與範例見 `references/dimension-product-notes.md`〈非 SaaS 專案的形態轉換〉。

**預設產物欄是入口不是清單，填完後仍應翻一次權威原文**——最高價值的缺口常在原文而不在此欄。範例見 `references/dimension-product-notes.md`〈填完產物欄仍應翻原文〉。

### 產物欄的四種合法答案

| 答案形態 | 何時使用 | 必須附帶 |
|---------|---------|---------|
| **照預設** | 權威的預設產物對本專案形態成立 | 無 |
| **改寫產物** | 維度成立但預設產物對本形態不適用或有害 | 改寫後的產物 + 一句為什麼預設不適用 |
| **已存在於 X** | 該產物本專案已有 | 位置（檔案路徑或符號名） |
| **無** | 該維度在本專案不產出任何東西 | 理由 + 重評條件 |

**複合產物、多子樹分列、改寫產物的範例與個案界線、無 UI 框架元件庫的產物**：見 `references/dimension-product-notes.md`。

### 權威缺席時

**先定「相對於誰」**：權威是否存在，看的是**執行本流程的 session 的 `.claude/`**，不是被盤點的 repo。判準隨你帶進去，被盤點的 repo 不需要安裝框架。反過來，**產物的載體（ticket 系統、執法載體、決策文件）看的是被盤點的 repo**，它們要落在那裡。這兩者分開判，否則同一個 repo 會得出完全相反的產物欄。

| 形態 | 處置 |
|------|------|
| **權威是框架資產但執行本流程的 session 未安裝** | 產物欄填「待定：權威缺席」，**不得填「無」**。「沒有依據」與「不產出」是兩件事。建一張補該權威的票，該維度的地基票 `blockedBy` 它；或指定替代權威並記錄於被盤點 repo 的決策文件。**這一格不看被盤點的 repo**，它沒有框架是常態，不構成權威缺席 |
| **權威存在但形態不符** | 走「改寫產物」。只取權威中與形態無關的部分，記錄不適用的範圍。來源是 SaaS skill 不構成整條跳過的理由 |
| **框架內確實無承接者** | **拆兩問，分開填**。產物層：該產物本專案有沒有，照四種答案填。判準層：框架有無判斷它合格與否的依據，沒有則另標「無判準」並建框架缺口票。**兩者獨立**，「產物有、判準無」是常見狀態。現已知的判準缺口：**資料庫 seed**（本框架搜尋「種子資料／seed data／seeding」0 命中，因此無從判斷既有 seeder 的量級與冪等策略是否合格） |
| **工作流自身引用的 skill 缺席**（如無 `version-sequencing` 承接產物） | 本 skill 的產物改為文件形式留在決策記錄，待該 skill 安裝後再排版本 |

**為什麼「待定」不能填「無」**：「無」的語意是判定後不產出，記下就結案；「待定」的語意是該判而未能判，必須留下未結的痕跡。兩者混用會讓缺口在盤點表上長得跟已完成一樣。

## 與 orchestration 的協作

判定順序由上而下，先命中者適用。

| 情境 | 判別（查版控內容，問作用不問存在） | 本 skill 的角色 |
|------|--------------------------------|---------------|
| **文件回答不了地基問題的既有實作** | 已有相當程度的實作，且既有文件**無法回答維度表任一格的產物**。行為記錄（changelog）、流程規範（coding rules）、建置指令都不算能回答 | 既有 orchestration 皆不適用，它們假設已有規格或已在規劃波中。走〈接手模式〉 |
| **規劃波進行中** | 該版提案的 `spec_refs` 或 `usecase_refs` 非空（`version-bootstrap` 的 pipeline 確實跑過），且該版尚未建票 | 為 DevOps 與可觀測性各建盤點票後交回 `version-bootstrap`，本流程結束 |
| **規劃波之後** | 該版票已建（不論是否已開工） | **仍由本 skill 驅動**，逐維度補判未被既有票涵蓋的產物。不重排既有票。這是真實 repo 最常見的狀態，不是收手 |
| **其餘** | 以上皆不命中 | 依維度表逐維度定產物，產物交給 `version-sequencing` 排版本 |

**判別不用身份也不用二元存在性。** 「你是不是原作者」對 AI session 無從判定，且自己寫的專案同樣會缺可用文件；「有沒有文件」則會被行為記錄與流程規範誤觸——一份 500 行的 changelog 逐版記了改了什麼，卻回答不了「這個維度的產物是什麼」。**「該版 `todolist.yaml` 填了 `proposals` 欄位」不等於規劃波進行中**，提案登記與 pipeline 執行是兩件事，誤判的代價是整個盤點被跳過。

**交回下游不等於下游覆蓋全部維度。** 實查 `version-bootstrap` 的步驟，`DevOps` 與 `可觀測性` 兩個維度在其全文 0 命中。交回前先為這兩個維度各建一張盤點票（產物欄可填「待定」），口頭明示不構成交接。

## 接手模式

接手的專案常缺可用文件，適用〈與 orchestration 的協作〉表「文件回答不了地基問題的既有實作」列。核心程序「盤點 → 命名 → 固化 → 補文件」、既有 artifact 可信度的四種例外情形、命名前置條件的規模閘門，完整內容見 `references/handoff-mode.md`。

## 工作流

```
1 判定情境（四列，由上而下先命中者適用）
   → 規劃波進行中：為 DevOps 與可觀測性各建盤點票後交回 version-bootstrap，本流程結束
2 逐維度填產物欄（照預設 / 改寫產物 / 已存在於 X / 無），一格可複合
   多子樹各持獨立工具鏈時按子樹分列
   權威缺席時依〈權威缺席時〉四形態處置，不得填「無」
3 依產物欄的形態各自執行：
   「照預設」→ 讀權威來源，依該處判準執行
   「改寫產物」→ 原權威對改寫後的對象通常無判準，走〈權威缺席時〉形態 2：
                 只取權威中與形態無關的部分，並記錄不適用的範圍
   「已存在於 X」→ 確認該處確實承擔該產物，不建票
   接手的專案先跑「盤點→命名→固化」三步
   需結構化評分的多方案取捨委派 .claude/skills/design-decision-framework/SKILL.md
4 產物落為地基票，功能票 blockedBy 它們
   全部維度皆為「已存在」或「無」時不建票，產出即盤點表本身，本流程完成
5 機械檢查接入執法載體（CI 或 hook）
```

**步驟 4 與 `version-sequencing` 的分界**：本 skill 產出票的**內容**（哪幾張、各自的依賴）；`version-sequencing` 在「版本序列落為提案」那一步決定它們**屬於哪一版**，在「首版開票」那一步把它們開出來。同一批票，不是兩批。規劃波前先跑本 skill 時，票可先建、待版本序列定案後再掛版本。

**步驟 5 的機械檢查目前只有 UI 維度有現成形態**（裸值 grep）。其餘維度的檢查需自行設計，這是本 skill 已知的不完整處。未設計機械檢查的維度，其地基票驗收條件改為指名複核者的人工複核，不留空。

**首次接入執法載體必然大量失敗**：設 baseline 凍結既有違規、只擋新增，再逐批收斂。一次要求全綠會導致檢查被停用。

**驗收訊息須指名判準所在的層。** 「grep 不到裸色碼」讀的是原始碼層；若排除清單或 gitignore 使某些檔案不在掃描範圍，訊息應寫「掃描範圍內未命中」而非「專案中不存在」。層次錯置的訊息會把讀者的正確觀察推翻：讀者在檔案系統看到那個值，訊息說不存在，最可能的推論是自己看錯了。

## 移植前置條件

本 skill 是**框架綁定**的：它以框架資產的路徑為主題，路由到的權威不隨它一起移動（同 `version-bootstrap`、`ticket`、`doc`，皆不宣告 `portable`）。開始前確認：

- [ ] **執行本流程的 session** 有維度表指名的全部權威？（三個 skill、一份方法論、一份可觀測性規則）缺者走〈權威缺席時〉形態 1
- [ ] **被盤點的 repo** 有具 `blockedBy` 語意的 ticket 系統？步驟 4 與〈權威缺席時〉的建票動作依賴它
- [ ] **被盤點的 repo** 有執法載體，且**其掃描範圍涵蓋本專案實際存在的檔案**？只問「有沒有」會通過一個只認 `.dart` 的 hook 裝在零 `.dart` 檔的專案上，該載體結構上永不觸發
- [ ] **被盤點的 repo** 有決策文件（任何形式的持久記錄，且進版控）？〈權威缺席時〉的形態 1、形態 4、`references/handoff-mode.md`〈萃取的前提是既有 artifact 可信〉表第四列、以及下方的降級記錄都落在它上面
- [ ] **被盤點的 repo** 有他人在途的工作？（近期 commit 來自他人）有則地基票的改動範圍需先與其協調

**缺項時進入降級模式，並記錄降級。** 記下缺哪一項、因此哪幾步在本專案不成立。**缺的若是執法載體，不另建補齊票**——它就是 DevOps 維度的產物，會在步驟 4 一併落地，另建會使同一件事有兩張票。**連決策文件都沒有時，第一個動作是建立它**（一份進版控的決策記錄即可，位置依專案慣例），否則本流程的缺席處置全部無處落地。無降級記錄的使用不構成完成本流程。

## Examples

五則實測案例（查重粒度不足的兩次反向錯誤、萃取揭露規格漂移、萃取不等於照抄、權威形態不符時的正確取用、產物有而判準無）：見 `references/examples.md`。

## 已知的證據基礎限制

已實跑驗證的形態：Flutter 桌面應用、Go CLI 單檔工具、多語言 SDK monorepo、前後端分離的 PHP 服務（真 PostgreSQL）、瀏覽器擴充套件（非 Flutter 的 GUI，四塊全部成立）、多人協作的既有 Flutter 專案（本機使用者零 commit）。

**未經實跑驗證**：單體遺留系統（十萬行以上、無模組邊界）、非 Web 非 Flutter 的桌面框架、需要合規稽核的受管制系統。

`references/dimension-product-notes.md`〈改寫產物是主路徑〉的改寫案例取自 Go CLI 工具，屬**個案記錄而非推導範本**。該節的推導問句才是可套用的部分。

## Common Issues

| 症狀 | 原因 | 處置 |
|------|------|------|
| 你判定「地基的 token／元件庫規範沒有現成的」，準備自己設計一套 | 查重只讀了 orchestration skill 的章節標題 | 先搜專案的方法論目錄；本 skill 的維度表是查重的起點，不是查重的全部 |
| 維度表某列指名的權威，你在本 session 找不到 | 該權威未安裝於執行本流程的 session，或形態不符本專案 | 走〈權威缺席時〉四形態。產物欄填「待定」，不填「無」 |
| 照權威的預設產物做，做出來的東西讓產品變差 | 權威是從別的形態歸納的 | 走「改寫產物」。維度仍成立，改的是產出什麼 |
| 專案有 README 與變更記錄，但你仍答不出某個維度的產物是什麼 | 文件記的是做過什麼與怎麼做，不是該做什麼 | 該情境走〈接手模式〉。判準看文件能否回答維度表，不看文件在不在 |
| 執法載體裝了，違規卻從來沒被擋下來 | 掃描範圍與本專案的實際檔案不相交 | 查該檢查的路徑與副檔名條件；範圍為空的載體等同沒有 |
| token 表建了，功能票還是各寫各的值 | 地基票與功能票無 blockedBy 依賴 | 功能票一律 blockedBy 地基票；執法載體加裸值檢查（指名它掃描哪一層） |
| 出現次數最多的顏色被命名為「主色」 | 出現次數是觀察不是語意 | 逐色確認實際承擔的角色；次數只是線索 |
| 既有命名的語意與你確認出的角色衝突，而命名者不是你 | 別人的現行決定可能對應一份沒進 repo 的設計稿 | 保留原值原名，疑義落決策文件待確認，不在地基波內改（見 `references/handoff-mode.md`〈萃取的前提是既有 artifact 可信〉表第四列） |
| 命名前要補的特徵測試，比命名本身還大 | 數萬行零覆蓋的專案 | 只在已有覆蓋的模組內命名，其餘設 baseline 只擋新增，未命名範圍記入決策文件 |
| 盤點表每個維度都填了，實作中仍撞到沒人想過的地基問題 | 產物欄填「無」但實際是「待定」；或該地基工作不在五個維度內 | 回查填「無」的理由是判定不產出還是找不到依據；本表不宣稱窮盡，依需要增列維度 |

---

版本紀錄在同目錄的 `CHANGELOG.md`。