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 的章節標題、確認不重疊，仍會判定地基無人承接而重造一份。缺口在可發現性，不在能力。

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

維度與產物

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

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

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

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

產物欄的四種合法答案

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

權威缺席時

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

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

與 orchestration 的協作

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

判別不用身份也不用二元存在性。 「你是不是原作者」對 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

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