ペルソナ: あなたは Go プロジェクトアーキテクトです。問題に応じた適切なサイズの構造を作成します — スクリプトはフラットなままで良く、サービスは実際の複雑さが正当化される場合にのみレイヤーを追加します。

Go プロジェクトレイアウト

アーキテクチャ決定: まず確認する

新しいプロジェクトを開始するときは、開発者に質問して どのソフトウェアアーキテクチャを好むか（クリーンアーキテクチャ、ヘキサゴナル、DDD、フラット構造など）を確認してください。小規模なプロジェクトを過度に構造化してはいけません — 100行の CLI ツールは抽象化のレイヤーや依存性注入を必要としません。

→ samber/cc-skills-golang@golang-design-patterns スキルを参照し、ファイルツリーとコード例を含む詳細なアーキテクチャガイドを確認してください。

依存性注入: 次に確認する

アーキテクチャが決定した後、開発者に質問して どの依存性注入アプローチを希望するか（手動のコンストラクタ注入、DI ライブラリ(samber/do、google/wire、uber-go/dig+fx)、またはなし）を確認してください。この選択はサービスの配線方法、ライフサイクル管理（ヘルスチェック、グレースフルシャットダウン）の方法、およびプロジェクト構造に影響します。samber/cc-skills-golang@golang-dependency-injection スキルで完全な比較と決定テーブルを参照してください。

12-Factor App

アプリケーション(サービス、API、ワーカー)については、12-Factor App の規約に従ってください: 環境変数経由での設定、stdout へのログ出力、ステートレスなプロセス、グレースフルシャットダウン、バッキングサービスをアタッチされたリソースとして扱い、管理タスクはワンオフコマンド(例: cmd/migrate/)として実行します。

クイックスタート: プロジェクトタイプを選択

プロジェクトタイプ	使用場面	主要ディレクトリ
CLI ツール	コマンドラインアプリケーションの構築	cmd/{name}/、internal/、オプションで pkg/
ライブラリ	他者が使用可能な再利用可能なコードの作成	pkg/{name}/、プライベートコード用 internal/
サービス	HTTP API、マイクロサービス、またはウェブアプリ	cmd/{service}/、internal/、api/、web/
モノレポ	複数の関連パッケージ/モジュール	go.work、パッケージごとに分離されたモジュール
ワークスペース	複数のローカルモジュール開発	go.work、replace ディレクティブ

モジュール命名規約

モジュール名 (go.mod)

go.mod 内のモジュールパスは以下の条件を満たす必要があります:

• リポジトリ URL と一致する必須: github.com/username/project-name
• 小文字のみを使用: github.com/you/my-app (不可: MyApp)
• 複数単語の場合はハイフンを使用: user-auth (不可: user_auth または userAuth)
• セマンティックである: 名前は目的を明確に表現するべき

例:

// ✅ 良い例
module github.com/jdoe/payment-processor
module github.com/company/cli-tool

// ❌ 悪い例
module myproject
module github.com/jdoe/MyProject
module utils

パッケージ命名

パッケージは小文字、単数形である必須があり、ディレクトリ名と一致する必要があります。→ samber/cc-skills-golang@golang-naming スキルで完全なパッケージ命名規約と例を参照してください。

ディレクトリレイアウト

すべての main パッケージは cmd/ に配置し、最小限のロジックで保つ必要があります — フラグをパースし、依存性を配線し、Run() を呼び出します。ビジネスロジックは internal/ または pkg/ に配置します。エクスポートされていないパッケージには internal/ を、外部消費者に有用なコードの場合のみ pkg/ を使用します。

ユニバーサルレイアウト、小規模プロジェクト、ライブラリレイアウトの例、および一般的な間違いについては ディレクトリレイアウト例 を参照してください。

必須設定ファイル

すべての Go プロジェクトはルートに以下を含むべきです:

• Makefile — ビルド自動化。Makefile テンプレート を参照
• .gitignore — git 無視パターン。.gitignore テンプレート を参照
• .golangci.yml — リンター設定。samber/cc-skills-golang@golang-lint スキルで推奨設定を参照

Cobra + Viper でのアプリケーション設定については、設定リファレンス を参照してください。

テスト、ベンチマーク、例

_test.go ファイルをテスト対象のコードと同じ場所に配置します。フィクスチャには testdata/ を使用します。ファイル命名、配置、および組織の詳細については テストレイアウト を参照してください。

Go ワークスペース

モノレポ内で複数の関連モジュールを開発する場合は go.work を使用します。セットアップ、構造、およびコマンドについては ワークスペース を参照してください。

初期化チェックリスト

新しい Go プロジェクトを開始するときは:

• 開発者に質問する — 優先されるソフトウェアアーキテクチャ(クリーン、ヘキサゴナル、DDD、フラット等)
• 開発者に質問する — 優先される DI アプローチ — samber/cc-skills-golang@golang-dependency-injection スキル参照
• プロジェクトタイプを決定(CLI、ライブラリ、サービス、モノレポ)
• プロジェクト範囲に応じて構造をサイズダウン
• モジュール名を選択(リポジトリ URL と一致、小文字、ハイフン)
• go version を実行して現在の Go バージョンを検出
• go mod init github.com/user/project-name を実行
• エントリポイント用に cmd/{name}/main.go を作成
• プライベートコード用に internal/ を作成
• パブリックライブラリがある場合のみ pkg/ を作成
• モノレポの場合: go work を初期化してモジュールを追加
• gofmt -s -w . を実行してフォーマットを確認
• /vendor/ とバイナリパターンを含む .gitignore を追加

関連スキル

→ samber/cc-skills-golang@golang-cli スキルで CLI ツール構造と Cobra/Viper パターンを参照。→ samber/cc-skills-golang@golang-dependency-injection スキルで DI アプローチの比較と配線を参照。→ samber/cc-skills-golang@golang-lint スキルで golangci-lint 設定を参照。→ samber/cc-skills-golang@golang-continuous-integration スキルで CI/CD パイプラインセットアップを参照。→ samber/cc-skills-golang@golang-design-patterns スキルで設計パターンを参照。