参考用Goプロジェクトを作成し、AIエージェントにそれをクローンする方法を教えた
著者は、Goプロジェクトの構造に関するよくある質問に答え、AIエージェントにとっても使いやすいリファレンスプロジェクトを作成しました。これは、PostgreSQLをバックエンドに持つ最小限のGo HTTP/RPCサービス（仮想書店）であり、人間とAIエージェントの両方を対象とした詳細なドキュメント（layout.md、design-decisions.md、adding-an-entity.md）を含んでいます。特に、BOOTSTRAP.mdはAIエージェントが機械的に新しいプロジェクトを足場できるように設計されています。また、Claude CodeスキルとBOOTSTRAP.mdを組み合わせてプロジェクトの雛形を自動生成する手法についても解説しています。
多くのGo開発者は、プロジェクト構造に関する質問をよく受けます。設定ファイルはどこに置くべきか、なぜpkg/ディレクトリがないのか、internal/books/とinternal/database/books/の違いは何かなどです。著者はこれまで長文で回答したり、実際のプロジェクトをリンクしたりしていましたが、実際のプロジェクトには特殊な決定が含まれており、一般化できません。そこで、example-project-structureというリファレンスプロジェクトを作成しました。これはPostgreSQLをバックエンドに持つ最小限のGo HTTP/RPCサービスで、架空の書店（書籍、著者、ジャンル）をドメインとし、結合や型変換を示すのに十分な機能だけを持ち、機能過多にならないようにしています。
これが第一の理由でした。第二の理由はさらに興味深いものです。著者は最近AIコーディングエージェントをよく使っていますが、新しいプロジェクトを始めるたびに、自分の好みの構造にしたいという問題に直面します。しかしAIの出力は非決定的で、エージェントにプロジェクトの足場を2回依頼すると、異なる構造が得られます。そこで、正しい構造を推測させる代わりに、具体的な例を与えてブートストラップさせることを考えました。
そのために、リファレンスリポジトリは第二の読者を想定して書かれています。docs/ディレクトリは人間だけでなくエージェントのためでもあります。layout.mdは各ディレクトリをマッピングし、何がどこにあるかを説明します。design-decisions.mdは「Service not Repository」や「package-by-feature not package-by-layer」などの選択の背後にある理由を説明します。adding-an-entity.mdはエージェントが機械的に従えるステップバイステップのガイドです。
さらに一歩進んで、リポジトリにはBOOTSTRAP.mdファイルが含まれています。これは特にAIエージェント向けに書かれており、エージェントがリポジトリをクローンし、その内容を新しいプロジェクトディレクトリにコピーしたことを前提としています。そこから、すべてのリネーム、削除するファイル、ユーザーが実際に望むもの（OpenAPIのみ？ConnectRPCのみ？データベースなし？）に基づく条件分岐をガイドします。各ステップで何を変更すべきか、その変更が現れるすべての場所をリストアップし、エージェントが自分で構造を再発見する必要がないようにしています。
著者はこれをClaude Codeスキル（まだオープンソース化されていません）と組み合わせて使用しています。このスキルは、ユーザーにプロジェクト名、モジュールパス、APIスタイル、データベース選択などいくつかの質問をし、BOOTSTRAP.mdに従って新しいプロジェクトの足場を構築します。構築する内容に関する詳細と組み合わせると、AIはかなり良い出発点を生成できます。
プロジェクトの構造は意図的に小規模です。パターンを示すのに十分でありながら、機能過多にならないようにしています。
.\n├── api/ # protobuf & OpenAPIスキーマ\n├── apigen/ # 生成されたAPIスタブ\n├── cmd/bookstore/ # バイナリエントリポイント\n└── internal/\n ├── books/ # ドメインパッケージ（機能ごとに1つ）\n ├── database/ # データアクセス、トランスポートから分離\n └── server/ # HTTP/RPC配線\n pkg/、models/、handlers/ディレクトリはありません。それぞれの欠如は意図的な選択であり、リポジトリのドキュメントでその理由を説明しています。
著者は詳細を一度の投稿に詰め込むのではなく、複数のパートに分けて公開する予定です。
- 構造自体：ディレクトリツリー、各パッケージの責務、レイヤリングルール、意図的に欠落しているもの
- 設計判断：なぜServiceがRepositoryより優れているか、なぜ時間とともにpackage-by-featureが勝つか、なぜrunner.goで手動DIを使うか
- BOOTSTRAP.mdアプローチ：人間とAIエージェントの両方に役立つドキュメントの書き方、Claude Codeスキルの仕組み、リポジトリをエージェントフレンドリーにするために学んだこと
現在リポジトリは公開されており、ドキュメントは充実しています。example-project-structureをご覧ください。著者はフォローアップの投稿で設計判断とBOOTSTRAP.mdアプローチについて深掘りする予定です。