用Claude自動產生內部API文件

簡而言之： 先用確定性的方式從程式碼庫裡抽出路由表，再讓Claude只去描述這些端點——參數、回應、錯誤語意——並在每次合併時透過CI重新產生。把模型錨定在一份真實清單上，正是它不會憑空編出端點的原因。而第一次跑完，通常會翻出一些沒人知道還暴露在外的東西。

每個工程團隊都有同一份文件。它在服務上線時被認真寫過，準確了大約五週，如今它描述著三個已經不存在的端點，同時漏掉了此後新增的十一個。沒人信它，所以沒人更新它，於是它繼續腐壞。新人乾脆去讀原始碼——而這恰恰是那份文件本該避免的事。

這種腐壞是結構性的，不是文化性的。文件活在一個系統裡，變更發生在另一個系統裡，只有當某個人注意到落差時，兩者才被連起來。這正是語言模型擅長的那類機械的、高脈絡、低判斷的工作——前提是你約束住它被允許聲稱什麼。

為什麼內部API文件總是最先腐壞？

內部文件比對外文件腐壞得更快，原因值得點名，因為每一條都會影響你怎麼做自動化。

沒有外部壓力。 一個對外API的文件寫錯了會傷到客戶。一個內部API寫錯了只會絆住同事，而同事會走過來問一句，於是繞行方案變成口耳相傳的部落知識，而不是一次文件修正。

作者會離開。 內部服務往往由一兩個人寫成，整個模型裝在他們腦子裡。等他們換了團隊，文件就不再是「共同理解的摘要」，而成了唯一的紀錄——偏偏就在沒人維護它的那一刻。

文件不在「完成的定義」裡。 合併需要測試和審查，卻很少要求更新文件，所以文件在設計上就永遠慢一步。

沒人知道端點的真實數量。 服務會累積除錯路由、內部管理路徑、某個被人擴充過的健康檢查，以及一個已廢棄卻從未被移除的功能的端點。任何從「人們記得什麼」開始的文件工作，都是從一份不完整的清單開始的。

最後這一點最要緊，它改變了解決方案的形狀：目標不是更快地寫出文字，而是讓端點清單從程式碼本身推導出來，這樣文件就無法悄無聲息地漏掉沒人記得的東西。

Claude究竟能從程式碼庫裡產生什麼？

端點參考、範例與錯誤語意

給定一個路由處理函式和它觸及的型別，模型能穩定產出描述層：這個端點是做什麼的、每個參數是什麼意思、一次真實的請求和回應長什麼樣，以及程式碼實際會回傳哪些錯誤。按篇幅算，這是API參考文件的主體，也是工程師最不願意寫的部分。

它同樣擅長那些手寫文件會跳過的連接組織。哪些端點需要哪種驗證。分頁慣例是什麼。哪些欄位可為空、在什麼條件下可為空。某個操作是否具冪等性。這些都能從程式碼裡讀出來，但手工彙編起來很煩，而它們的缺失，正是讓一份參考文件「技術上完整、實用上沒用」的原因。

兩條誠實的邊界。第一，模型描述的是程式碼做了什麼，不是它應該做什麼——如果實作與預期契約矛盾，你拿到的是對這個bug的文件。第二，它無法知道未被寫下的業務脈絡：某個欄位為什麼存在、哪個呼叫方依賴著那個奇怪的行為，或者某個參數因為一個設定開關在正式環境裡其實被忽略了。這些依然只能來自人。

事實來源應該是程式碼、規格，還是兩者？

多數框架已經能從註解或型別定義產生OpenAPI規格，而那份機器產生的規格，是一個比「模型讀檔案」好得多的地基。它在建構上就是窮盡的，也不可能幻覺出一條不存在的路由。

所以兩者都用，但順序要對。用確定性的方式產生或抽取規格——從框架註解，或透過解析你的路由定義——並把它當作端點及其形狀的權威清單。然後把它連同相關的處理函式程式碼一起交給模型，要它給出描述、範例和文字。模型負責豐富，不負責列舉。

這個順序是整條管線裡最重要的一個設計決定。一個被要求「給這個儲存庫寫文件」的模型，會產出看起來很合理、但並不存在的端點，而正是這份合理性讓它們在審查裡格外難被抓到。一個被要求「描述這十四個端點，如果程式碼不清楚就明說」的模型，是在一個它無法繞開的事實之內工作。

一條務實的管線：產生、審查、發布、重新產生

從「每次合併到主分支時抽出路由表」開始。框架工具、建置期的規格產生器，或者一個解析路由檔的小腳本——只要它是確定性的就行。這個產物就是契約。

把它與上一次的結果做差異比對。多數合併不會改變任何相關的東西，而只為變化的部分重新產生文字，能讓成本和審查負擔保持在合適的比例上。一個新端點、一處簽章變更、一條被移除的路由，會觸發工作；一次不觸及任何介面的重構，不會。

對每一個變化的端點，把規格條目、處理函式原始碼、它引用的型別，以及已存在的舊描述一併交給模型。要求它在人寫的內容仍然準確時予以保留、在不再與程式碼相符時予以標記，而不是直接覆蓋——否則每一段精心寫下的解釋，都會在下一次執行時被換成千篇一律的文字，然後團隊就不再寫它們了。

然後經由審查發布，而不是直接發布。管線應當向文件儲存庫或你的wiki提一個PR，而不是無人看管地提交產生的內容。這以很低的成本把人留在迴圈裡，給你的是一份可以掃一眼的差異而不是一份要通讀的文件，也意味著一次糟糕的產生是一個被拒的PR，而不是一處已發布的錯誤。文件放在哪裡，遠不如「它是被產生出來的而不是被記住的」重要——同樣的原則，我們在用Claude保持Confluence文件同步那篇裡也講過。

AI產生文件 vs 規格優先工具 vs 手寫文件

涵蓋度 — 規格優先工具完勝。它在建構上就記錄了每一條路由，而純模型方案只記錄了你給它看過的，手寫文件只記錄了某個人記得的。
可讀性與有用性 — AI產生勝出。一份原始的OpenAPI渲染只告訴你某個欄位是字串；有用的版本會告訴你該往裡放什麼、放錯了會發生什麼。
端點清單的準確性 — 規格優先勝出，而這是最要緊的一項。絕不要讓模型成為這份清單的來源。
保持最新 — 規格優先和AI產生都勝過手寫，因為兩者都會自動重新產生。手寫文件只在某一個瞬間是準確的。
捕捉意圖與業務脈絡 — 手寫勝出。一個端點為什麼存在、哪個呼叫方依賴它的怪癖，這些都不在程式碼裡。
建置投入 — 短期看手寫勝出；如果你的框架支援，規格優先是中等投入；而一條帶CI整合和審查流的完整AI管線，是其中最大的一筆投入。

真正行得通的組合是三者並用：規格優先負責清單，AI負責描述，人負責意圖——並且讓管線保留人寫的內容，而不是把它們輾平。

它會暴露什麼——以及為什麼那才是真正的價值

這樣一條管線的第一次完整執行，通常比它產出的文件更有意思。

沒人記得的端點。 兩年前某次事故留下的除錯路由、為一次性遷移加的管理路徑、本該在v2上線時下線的v1。每一個都是活著的、可達的暴露面。

缺失或不一致的驗證。 「彙編出哪些端點強制了哪些檢查」這件事，恰恰是那個會暴露出「中介層從未被套用到那個處理函式上」的動作。這很少是惡意的，幾乎總是一次把路由從守衛後面挪出來的重構。

範例和測試夾具裡的金鑰。 產生範例請求的模型，依據的是你給它看過的東西，而測試夾具裡滿是看起來很真的權杖——有時候它們就是真的。發布前請掃描產生結果裡的憑證樣式，並把找到的任何東西都當作一支需要立即輪換的活金鑰。

未被寫下的「僅內網」假設。 那些因為「只有內網能存取到它們」而被認為安全的端點，而這是某人在三次架構變更之前對網路拓撲作出的判斷。

面對一份「被遺忘的、可能未驗證的端點」清單，誠實的回應不是一個wiki頁面，而是去測試它們是否真的可達、暴露了什麼——那正是滲透測試的用途。文件告訴你你有什麼，只有測試才告訴你它是否安全——而「我們剛發現四十個沒人記得的端點」，是預約一次滲透測試的相當充分的理由。

把這件事做對：原始碼保密、API金鑰，以及何時該讓IT介入

把專有原始碼送給第三方模型是一個真實的決定，不是一道手續，它值得一個刻意給出的答案，而不是工程師在當下的個人判斷。

去讀適用於你所用那個具體層級的條款——商業版和API層級在保存與訓練上通常與消費級產品不同，而且條款會變，所以請以當前文件為準，而不是某位同事的記憶。然後決定範圍：很多組織能接受送出應用程式碼，但堅決不接受送出任何來自「存有客戶資料夾具、密碼學材料，或受客戶保密條款約束的程式碼」的儲存庫。把這條邊界寫下來，因為另一種選擇是每個工程師各自私下決定。

機制層面同樣要緊。這條管線需要一支儲存庫權杖和一支模型API金鑰，它們活在CI裡。請使用短生命週期、最小權限、且限定到具體儲存庫的憑證，把它們放進CI服務商的金鑰庫而不是設定檔，並按一個真的有人負責的週期輪換。一條擁有全組織範圍讀取權限的產生管線，本身就是你攻擊面上不容忽視的一塊。我們的AI+支援服務負責在建置這類工具時從一開始就把這些控制放進去，而託管IT支援則在不只一個團隊依賴它之後，接手圍繞它的身分、權限與金鑰生命週期。Brocent自2007年在北京創立以來一直在亞洲提供託管IT服務，總部位於新加坡，並自2016年起設有香港辦公室。

常見問題

把專有原始碼送給AI模型安全嗎？

這取決於層級和程式碼本身，而且它應該是一個被記錄下來的決定，而不是每位工程師各自的判斷。請查清服務商當前條款就你所在的具體方案在保存和訓練上的說法，並對「哪些儲存庫可以走這條路」設一條明確邊界——應用邏輯，和一個包含憑證、客戶資料夾具或受客戶保密義務約束的程式碼的儲存庫，是完全不同的兩個問題。

它會幻覺出不存在的端點嗎？

如果你讓它來列舉，會。這正是為什麼路由清單必須來自確定性的抽取——框架的規格產生，或解析你的路由定義——而模型的職責被限制在描述這份清單上的條目。這樣約束之後，「捏造端點」就不再是一個現實的失效模式。

怎麼讓文件與程式碼保持同步？

在CI裡以「合併時觸發」來重新產生，而不是靠排程或手動。對抽出的規格做差異比對，只重新產生變化的部分，並提一個PR供審查。任何需要某個人記得去跑一下的東西，一個季度之內就會漂移。

它找出來的、沒人記錄過的端點該怎麼辦？

先分診，不要急著寫文件。對每一個，弄清楚它是否仍在被使用、它強制了什麼驗證、它暴露了什麼。把死的移除，把活的加固，然後才寫它。給一個未驗證的、被遺忘的端點寫文件，只是把它更清楚地公布出去。

它會覆蓋我們工程師寫的解釋嗎？

只有當你把它做成那樣時才會，而這正是那個會扼殺採用率的失效模式。把既有的描述作為脈絡傳進去，並指示模型：保留準確的人寫文字、標記不再與程式碼相符的部分、只補上缺失的內容。如果工程師看到自己的解釋被換成千篇一律的文字，他們就不會再寫了。

這能取代OpenAPI規格嗎？

不能——它依賴於規格。規格是那份權威的、機器可讀的契約，同時還驅動著用戶端產生和測試。這條管線是在它之上加一層人類可讀的東西，而那正是原始規格渲染做得不好的部分。

從哪裡開始

挑一個服務，最好是一個大家會抱怨的、中等規模的內部服務。用確定性的方式抽出它的路由表，把這份清單與現有的任何文件做比較——通常正是這一次比較，讓這個專案拿到了預算。然後為通過分診的端點產生描述，把重新產生接進CI並走PR，並且在把範圍擴大到其他儲存庫之前先把憑證權限定好。如果第一次執行翻出了一些沒人說得清的端點，而你更希望知道它們實際暴露了什麼、而不是靠猜，歡迎與我們聯絡。