Spec-First API：用 codegen 約束 LLM 與人類的 drift

raiven.kao@gmail.com (Raiven Kao) — Tue, 11 Aug 2026 00:00:00 +0000

前言

事情是這樣開始的。

我請 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 裡形同空轉，它是「程式碼的產物」，而我們沒有任何機制拿它回頭驗證程式碼。

Code_generation on omegaatt

Spec-First API：用 codegen 約束 LLM 與人類的 drift

前言

問題不是「有三份檔案」