規範撰寫心得與經驗分享
為甚麼要撰寫規範
在我入職以前，就已經有某位素未謀面的前端工程師前輩先行為專案建立了一份規範並放置於Notion上。
但是規範的內容並不完整，大多是針對特定組件的說明，以及少部分的撰寫規範，並沒有針對專案的整體架構、流程、規則以及為甚麼要這樣做的說明。
而且隨著專案的演進與變化，規範可能因為專案經歷過不同人經手迭代 抑或是專案規模擴大 以及 專案寫法優化與改良，導致規範可能已經不符合現在的開發需求。
同時也是為了避免新進人員入職時，因為不了解專案的架構與流程，而導致開發效率降低，或是筆者本人在未來維護專案時忘記規範而導致寫起來不容易閱讀或是過於困難。
本人在文件與規範上的貢獻
整體上，我將文件依「誰要看、要看什麼」拆成幾類：如何閱讀與維護文件、程式與模組的慣例與結構說明、TypeScript 與共用程式實務、既有共用介面的用法與注意事項，以及新增／維護共用能力時應遵守的原則。另包含與後端互動、錯誤處理相關的請求層慣例，以及枚舉、常數、對照表等共用基礎設定的約定，讓後續維護者能依同一套敘事找到答案。
以下僅說明性質，不展開前公司實際的目錄、檔名或內部流程，避免涉及不宜公開的架構細節。
- 閱讀與撰寫指引：訂出「接到需求時先看什麼、改完要補什麼」的順序，並定義更新紀錄與格式上的基本規範，降低新進與交接成本。
- 開發慣例與模式說明：撰寫與維護表單／CRUD、元件撰寫方式、雙向綁定、檔案與模組分工等可重複套用的做法，減少風格分歧與重工，說明演進過程以及為甚麼要這樣做。
- TypeScript 與型別實務：把專案中已採用的型別策略、避免濫用寬鬆型別、以及與業務程式銜接時的注意點寫成可對照的說明（與另篇 TypeScript 與型別驅動設計心得 互相呼應）。
- 共用組件與介面文件：為多個共用元件補上用途、API（props／事件／插槽等）、範例與注意事項，並維護總覽索引，方便查閱。 可參考 元件化(componentization)的實作經驗分享
- 請求層與錯誤處理：整理統一請求封裝的用法、狀態與錯誤處理慣例、以及常見設定情境（例如驗證、靜默錯誤、自訂錯誤分支），讓 API 相關程式有一致敘事。
- 共用工具與常數約定：補齊枚舉、常數、對照表等基礎設施的使用方式與範例，避免各處自行定義、難以對齊。
- 持續維運：依功能迭代與重構更新對應段落，並保留更新時間與作者資訊，讓文件與程式碼的「新舊」可被辨識。
以上是我以文件與規範維護者角色，在該專案中實際投入並交付的內容；細節實作與截圖因離職與保密考量，不在此公開。