我構建了一個參考性 Go 專案（並教會 AI 代理克隆它）
作者建立了一個參考性Go專案結構，旨在解答常見問題並使專案對AI代理友好。該專案是一個基於PostgreSQL的最小化Go HTTP/RPC服務（模擬書店），包含詳細的文件目錄，其中特別為AI代理編寫了BOOTSTRAP.md引導檔案，以幫助其機械地複製結構。文章還介紹了專案的目錄佈局、設計原則以及透過Claude Code技能與BOOTSTRAP.md結合實現專案腳手架自動化的方法。
許多Go開發者常問專案結構問題，比如配置檔案放哪，為什麼沒有pkg/目錄，internal/books/和internal/database/books/的區別等。作者曾用長篇文字回答，後來連結真實專案，但實際專案總有特殊決策。於是建立了示例專案example-project-structure，一個最小的Go HTTP/RPC服務，使用PostgreSQL，模擬書店領域（書籍、作者、流派）以展示連線和型別轉換，避免過多功能。
第二個原因更有趣：作者常使用AI編碼代理，但每次新專案都希望結構符合個人偏好，而AI輸出不確定。因此，作者以代理為第二讀者編寫文件。docs/目錄包含layout.md（對映每個目錄並說明作用）、design-decisions.md（解釋“Service not Repository”等決策原因）和adding-an-entity.md（代理可機械執行的逐步指南）。更進一步，倉庫包含BOOTSTRAP.md，專為AI代理編寫，假設代理已克隆倉庫並複製內容到新專案目錄，然後逐步引導重新命名、刪除檔案、根據使用者需求（如僅OpenAPI或ConnectRPC，無資料庫）進行調整。作者結合了Claude Code技能（尚未開源），詢問使用者專案名稱、模組路徑、API風格、資料庫選擇等，然後執行BOOTSTRAP.md來搭建新專案。
專案結構很小但能展示模式：api/目錄（protobuf和OpenAPI架構）、apigen/目錄（生成的API存根）、cmd/bookstore/（二進位制入口點）、internal/目錄下按功能分包（books/、database/、server/），沒有pkg/、models/、handlers/目錄。每個缺失都是有意選擇，並在文件中說明。作者計劃將細節拆分為多篇文章：結構本身（目錄樹、每個包職責、分層規則、刻意缺失）、設計決策（為何Service勝於Repository、按功能分包勝於按層分包、在runner.go中使用手動依賴注入）、BOOTSTRAP.md方法（為人類和AI代理編寫文件的方法論，以及Claude Code技能的工作原理和讓倉庫更代理友好的經驗）。目前倉庫已公開，文件詳盡，後續將深入探討設計決策和BOOTSTRAP.md方法。