database-schema

database-schema 技能概覽

database-schema 的用途

database-schema 技能能幫助 AI 在撰寫查詢、遷移或模型程式碼之前，先讀懂資料庫契約。若你從事 Database Engineering，當你想減少欄位名稱寫錯、遺漏欄位、型別不匹配，以及對資料表結構的默默假設時，這就是該用的技能。

誰適合使用

如果你的工作仰賴既有資料表、產生型別，或遷移歷史，就應該使用 database-schema skill。它特別適合正在修改應用程式程式碼的工程師、產生 SQL 的 agents，或任何需要在不猜測 schema 的前提下安全調整資料存取的人。

為什麼它在實務上重要

它的核心價值不是抽象的「schema 意識」，而是提早避免本可省下的破壞。這個技能會推動模型先檢查 schema 的權威來源，確認欄位名稱與型別，並在寫資料庫邏輯之前，先讓生成的程式碼對齊那份契約。

如何使用 database-schema 技能

安裝並啟用它

要進行 database-schema install，先把這個技能加入你的 Claude skills 設定，然後把 agent 指向任何會碰到持久化層的工作。在 repo 裡，這個技能被定義為 non-user-invocable，所以它設計上是透過工作流程情境觸發，而不是當成獨立命令直接呼叫。

提供正確的輸入

一個好的 database-schema usage 提示，應該包含技術棧、相關檔案，以及明確的資料庫任務。例如：「把 user profile API 改成在我們的 Drizzle schema 裡寫入 display_name 和 timezone；先檢查 schema 並確認型別。」這比「修資料庫程式碼」更好，因為它給了技能明確目標，也提供可驗證的位置。

先讀對的檔案

先從 SKILL.md 開始，再檢查你技術棧對應的 schema 來源：schema.ts、schema.prisma、migration SQL，或 model 檔案。如果 repository 裡有生成型別，也一併檢視，因為這個技能的設計是把 schema 與型別生成一起當成安全檢查，而不是只看 schema 而已。

採用 schema-first 工作流程

最有效的流程是：先找出資料表或模型，確認精確的欄位與限制，把你的任務對應到那些欄位，然後再寫符合契約的程式碼或 SQL。如果 schema 還不存在，這個技能的建議是先建立它，再往下做，而不是在應用層臨時腦補資料表形狀。

database-schema 技能 FAQ

database-schema 只適用於某一種 ORM 嗎？

不是。database-schema 技能跨不同技術棧都能用，因為它強調的是同一個習慣：先讀 schema，再寫程式碼。repository 裡明確提到的包含 Drizzle、Prisma、Supabase、SQLAlchemy，以及 TypeORM 風格的 model 位置。

這比一般提示詞更好嗎？

在任務仰賴正確資料庫結構時，答案是肯定的。一般提示詞可能產生看起來合理的 SQL，但這個技能多加了一層工作流程限制：先確認 schema 與型別，再根據已驗證的契約產生程式碼。

對新手友善嗎？

大致上是，只要使用者能找到專案的 schema 檔案。新手會因為這個技能減少猜測而受益，但他們仍需要知道 schema 放在哪裡，以及專案用的是 migration、ORM model，還是生成型別。

什麼情況下不該用它？

當任務和持久化無關，或 schema 刻意保持彈性、尚未建立權威來源時，不要依賴 database-schema。對純前端工作、只改文件的變更，或沒有真正資料庫契約的臨時原型，它也比較沒幫助。

如何改進 database-schema 技能

給它更精準的 schema 目標

最大的升級，是直接點出特定實體與操作：「在 users 新增 last_login_at 並更新讀取路徑」遠比「改登入功能」更有力。目標越清楚，database-schema skill 越能在寫作前驗證正確的資料表、關聯與型別。

加上限制與邊界情境

如果任務涉及唯一性規則、可為空欄位、外鍵、soft delete，或需要保留既有資料，請一開始就說明。這些細節會改變查詢或 migration 的安全形狀，也能降低「有 schema 意識但還是做錯」的機率。

要求驗證，不只是產碼

一個強的 database-schema guide 請求，應該要求模型確認它使用了哪些 schema 假設，並點出任何含糊之處。這一步能抓出 repository 裡有多個 schema 檔案、生成型別過舊，或模型必須在相似欄位之間做選擇的情況。

從第一版繼續迭代

第一版輸出後，根據缺少什麼再收斂：需要 migration 路徑、型別更新，或是對既有資料列的相容性說明。最好的 database-schema 結果，來自一個短迴圈：「驗證 schema、寫程式碼、對照契約、再修正」，而不是一次生成就結束。