我构建了一个参考性 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方法。