Spec-First API：用 codegen 約束 LLM 與人類的 drift
前言 事情是這樣開始的。 我請 agent 幫忙加一個 endpoint，它三分鐘寫完，handler 乾淨、error handling 完整、unit test 也跟著補齊，go test ./... 全綠。此時我想到的是，agent 真的有做完嗎？route 真的有被註冊嗎？ 換成三年前的我，也會漏，那要怎麼樣讓 Agent 不會漏？這個系統從一開始就沒有任何機制能發現有人漏改。以前它靠的是 reviewer 的眼力與同一批人的肌肉記憶撐著；現在把產出速度乘上十倍，這條防線就直接被沖垮了。這不是 agent 的問題，是架構債被提早引爆。 這篇想記錄的，就是後來把這個服務從 code-first 遷移到 spec-first 的過程：用 OpenAPI 當單一真值來源(SSOT)，用 oapi-codegen 產生 typed interface，讓 compiler 與 CI 去做原本靠人記憶的事情。 問題不是「有三份檔案」 遷移前，同一條 API 的定義散落在三個地方： infra route definition ← path / method / authorizer cmd/*/main.go ← mux.HandleFunc 手寫註冊 Go swag comments ← @Router / @Param / @Success 三份檔案本身不是問題，同一個概念散在多個檔案是常態。 真正的問題是，它們彼此不知道對方存在。 改 path，可能只改到 Go route，忘了 infra；改 response shape，可能只改 handler struct，忘了註解；授權設定只活在 infra 層，Go 跟 OpenAPI 都不知道有這回事。而 swaggo 的註解在 repo 裡形同空轉，它是「程式碼的產物」，而我們沒有任何機制拿它回頭驗證程式碼。 ...