我構建了一個參考性 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方法。