工程憲章
概觀
一份可攜帶的工程實踐章程，分解為專注的技能。本技能是索引：它陳述不可違背的原則，並將你引導至適合你任務的特定技能。完整的推理過程位於 references/engineering-constitution.md 中，與此 SKILL.md 捆綁在一起，以便技能無論安裝在哪裡都能隨身攜帶。
核心概念： 軟體工程是隨著時間推移而整合的程式設計。 為長壽命的系統進行最佳化——操作它、安全地變更它、在故障時恢復它——而不僅僅是首次部署。
八項不可違背的原則
- 先理解，後構建。 未經批准的設計，不得編寫程式碼。
- 記錄每個決策及其理由——以及你拒絕的方案。
- 測試是控制手段，而非形式——行為變更應以測試為先。 失敗的測試是資訊，絕不能擅自編輯掉。結構性變更則以現有測試套件未經編輯而通過為前提。
- 嚴格遵循 YAGNI（你不需要它）。
- 自動化可重複的事務。
- 軟體工程是隨著時間推移而整合的程式設計。
- 未經執行的規則只是建議。 將規則綁定到工具，或將其標記為需要審查者判斷。
- 使用者的明確指示優先於本文件。 優先級：使用者 → 憲章 → 工具預設值。
我需要哪個技能？
第一層 — 通用（適用於每個專案）：
| 你的任務 | 技能 |
|---|---|
| 開始一個功能，將想法轉化為規格/計劃 | designing-before-building |
| 做出決策；記錄下來（ADR、索引、待辦想法） | recording-decisions |
| 提交、撰寫訊息、自動化發布 | conventional-commits-and-releases |
| 撰寫/變更測試；權限/角色規則；重構時測試失敗 | tests-as-a-control |
| 撰寫或重構程式碼；組織變更；DRY 決策 | change-hygiene-and-code-craft |
| 構建 UI、元件、樣式、無障礙性 | interface-craft-and-accessibility |
| CI、預推送鉤子、任務執行器、合併閘道 | merge-gates-and-automation |
| 日誌記錄、指標、追蹤、健康檢查、SLO、警報 | observability-and-slos |
| 不受信任的輸入、機密、認證、依賴項、威脅建模 | defense-in-depth-security |
| 熱路徑、分頁、N+1、列表端點、公開介面 | performance-and-scale |
| 規劃部署、回滾或事件/事後檢討 | resilience-and-deploy-safety |
第二層 — 特定堆疊（僅在工具/主題存在時載入）：
| 你的任務 | 技能 |
|---|---|
| PostgreSQL、PostGraphile、RLS、SQL 檔案、應用程式→GraphQL→資料庫路徑 | postgres-postgraphile-rls-and-sql |
| UI 和測試之間共用的 GraphQL 查詢；路由/模式合約測試 | graphql-contract-testing |
| 包含必須保留資料的綱要變更——遷移、回填 | zero-downtime-migrations |
| 部署到 Kubernetes/AKS、雲端機密、漸進式發布、每個 PR 環境 | cloud-delivery-aks |
這些技能如何應用於新專案
- 第一層保持不變。 上述每個技能都適用於任何專案——網頁應用程式、管道、CLI、函式庫。
- 第二層可替換。 當堆疊不同時，第二層技能不會觸發（其描述是特定於堆疊的），你可以替換為等效技能。它們所實現的原則（單一資料路徑、最終強制執行在底層、合約接縫、可逆部署）仍然適用。
- 隨生命週期調整規模。 預啟動或僅限本地端的專案，將零停機遷移、金絲雀發布和正式事件流程應用為立即制定規則，按需啟動。在其第一個決策記錄中陳述專案的模式。
紅旗
如果你正要編寫程式碼、提交、部署或變更測試，但尚未查閱上述相關技能——請先停下來載入它。憲章會覆蓋預設習慣（原則 7）；習慣正是它要修正的目標。