principle-foundational-thinking | 先定資料形狀與工作基礎
本頁以 pstack-claude 0.9.126 為基準。原文設定 user-invocable: false，通常由 poteto-mode 按需讀取。你可以用自然語言要求「套用 principle-foundational-thinking」，讓代理先釐清結構，再處理邏輯。
定位與適用情境
這項原則要求先決定資料形狀與主要存取模式。結構應保留後續選擇空間，實作則維持直接簡單。不要為了消除三行相似程式就建立抽象。
本例要替商品匯入工具增加平行處理。輸入是現有匯入器、以商品編號辨識的測試資料，以及「重複編號必須回報、不同批次互不污染」的需求。真正的起點不是開更多工作者，而是決定誰擁有每批資料與錯誤結果。
準備
- 提供匯入器入口、資料型別、呼叫端與現有測試。先確認可修改範圍。
- 列出讀取方式。包含依編號查找、保留原始列順序，以及輸出錯誤報告。
- 準備重複編號、空批次與兩批同時執行的案例。示例只用本機測試資料。
操作步驟
- 畫出資料形狀。 列出商品列、批次結果與錯誤的必要欄位。依編號查找可評估映射表（Map），列順序則仍需明確保留。每個選擇都對應一種實際存取需求。
- 找出共享狀態。 追查目前的錯誤陣列與計數器由誰寫入。對每項狀態問「另一個工作者同時修改會怎樣」。會影響別批結果，就改為每批各自擁有，再於邊界彙整。
- 排序必要基礎。 先辨認已無用途的程式，再提出清理範圍。接著安排各階段都受益的共用型別、測試工具與持續整合（CI）檢查。不是每次都重建整套基礎設施。
- 切成可驗證增量。 先驗證單批資料契約，再驗證隔離後的平行批次。每個增量應交付完整的抽象，不讓呼叫端各自新增特殊協調邏輯。
可直接使用的提示詞
套用 principle-foundational-thinking。請先閱讀商品匯入器、呼叫端與測試，列出資料形狀、主要存取模式，以及每批資料的擁有者。
目標是支援兩批同時匯入，重複商品編號要回報，兩批錯誤不得互相污染。
先交付結構提案與實作順序，不修改檔案。說明哪些既有基礎可沿用、哪些死碼只是待核准清理，以及每個增量如何驗證。不要為消除相似行數建立通用框架。預期結果與驗收
預期拿到資料模型、讀寫對照與增量計畫。可用下列項目檢查提案。
- 每種主要查找與輸出需求都有對應結構，沒有只憑名稱挑選容器。
- 每個可變欄位都有明確擁有者，兩批執行不共用錯誤陣列。
- 後續實作的測試能檢查重複資料、空批次與並行隔離，而不只比較程式行數。
- 基礎工作能指出哪些後續階段受益，沒有與需求無關的大型重建。
限制與權限
常見誤用是把「基礎先行」理解成先做完整框架，或把「結構去重」變成抽取每段相似程式。原文偏好明確、簡單的實作。
本例的資料結構選擇是教學示例，不是上游指定的匯入器架構。清除死碼仍須依專案刪檔規則取得同意。原則不授權修改範圍外的共用狀態，也不保證只改型別就能解決所有並行問題。