go-style-guide

Go（Golang）スタイルガイドスキル

このスキルでは、人間、コーディングエージェント、本番環境対応システム向けの実践的な Go エンジニアリング規約を定めます。

Go を使った作業（新規コード、リファクタリング、レビュー、アーキテクチャの決定、パッケージ設計、テスト戦略）では、常にこのスキルを使用してください。

---

要約

• まずテスト容易性を考えて設計し、依存関係を注入してロジックを純粋に保ちます。
• Config を入力し、具体的な構造体を返す方法を優先します。重要な実行時設定は検証し、デフォルト値を設定して、ドキュメントに記載します。
• エラーは契約です。長期的に使う分岐にはセンチネルエラーを使い、それ以外は %w または errors.Join でラップします。
• パッケージは再利用可能に保ちます。隠れたグローバル変数、デフォルトのロギング、予期しない副作用を避けます。
• 依存関係を追加する前に標準ライブラリを優先します。サードパーティ製パッケージは、価値のある抽象化を提供し、保守され、採用実績がある場合にのみ導入します。
• カバレッジは指標であり、証明ではありません。正常系だけでなく、エッジケースや誤用時の経路もテストします。
• 「インターフェースを受け取り、構造体を返す」方針に従います。通常、インターフェースは利用側が定義します。共有コントラクト用のパッケージは例外です。
• main.go は薄く保ちます。ディレクトリ構成を無理に統一するのではなく、既存リポジトリのレイアウト規約に従います。
• ホットパスの改善を主張する前にベンチマークを行い、並行処理のコードは -race を付けて実行します。
• 関数シグネチャ、設定の形状、エラーの振る舞い、ドキュメントコメントなどの契約を維持します。これらはコードそのものと同じくらい重要です。

---

スタイルガイドに関する注意事項

このガイドには、意図的に明確な見解が含まれています。Go のあらゆるスタイルの好みに合わせるより、一貫性と長期的な保守性を重視します。対象リポジトリに明確な独自規約がある場合は、通常、その規約を優先します。

---

互換性

例では最新の Go を想定し、errors.Join や log/slog などの標準ライブラリ機能を使用しています。対象リポジトリでサポートされている Go バージョンの制約に従って、このガイドを適用してください。

---

実行プロトコル

実装作業でこのスキルを使用する際は、次のワークフローに従ってください。

1. まずリポジトリを調査します。 新しい API の提案やファイルの移動を行う前に、既存のパッケージ構成、コンストラクター、テスト、エラーの規約を確認します。

2. コーディングの前に契約を定義します。 パッケージの境界、設定の形状、具体的な戻り値の型、センチネルエラー、依存関係の分離点、コンテキストやシャットダウンに関する要件を事前に決めます。

3. 実用的であれば、早い段階でテストを作成または更新します。 テーブル駆動の単体テストから始め、解析など入力の多いコードにはファズテストを追加し、パフォーマンスが重要な経路にはベンチマークを追加します。

4. 保守可能な最小限の変更を実装します。 リポジトリの既存のレイアウトに従い、main.go は薄く保ち、明確な境界がない新しい抽象化の導入は避けます。

5. 最終確認を実行します。 gofmt（リポジトリで使用している場合は goimports も）でフォーマットし、関連する go test の対象を実行します。並行処理が関係する場合は go test -race を実行し、パフォーマンスの改善を主張する場合はベンチマークを実行します。

6. 人間向けの契約を確認します。 ドキュメント、コメント、設定のデフォルト値、エラーの振る舞いが、リリースするコードと一致していることを確認します。

---

クイックルール表

トピック	ルール	参照先
テスト可能性	カバレッジ率ではなく、確信を得られる設計にします。境界ケースや誤用ケースをテストします	references/TESTING.md
コンストラクター	Config を受け取り、具象構造体を返します。New で検証とデフォルト値の設定を行い、設定ロジックが増えたら Config.Validate() を使います	references/CONFIG.md
エラー	長期的な分岐にはセンチネルを使います。%w または errors.Join でラップし、recover はアプリケーションの境界に置きます	references/ERRORS.md
ロギング	パッケージはデフォルトでログを出力しません。ホットパスでのログ出力は、パフォーマンス上の判断事項です	references/LOGGING.md
依存関係	まず標準ライブラリを使います。意味のある、保守が継続されている価値をもたらす場合に限り、サードパーティーパッケージを追加します	references/LAYOUT.md
インターフェース	「インターフェースを受け取り、構造体を返す」ようにします。通常、インターフェースは利用側で定義します	references/INTERFACES.md
ドキュメント	慣用的な godoc と長く使えるコメントを書きます。エージェントのコンテキストに関するコメントは追加しません	references/DOCUMENTATION.md
レイアウト	パッケージを浅く保ち、何でも入れる場所を避け、リポジトリの規約に従います	references/LAYOUT.md
エントリーポイント	main.go は配線だけを担当します	references/LAYOUT.md
ベンチマーク	ホットパスをベンチマークします。b.ReportAllocs() を使い、benchstat で実行結果を比較します	references/BENCHMARKS.md
テスト	テーブル駆動で標準ライブラリを優先し、誤用に備え、入力が複雑な場合はファジングを積極的に行います	references/TESTING.md
並行処理	すべてのゴルーチンに終了経路を用意します。必要に応じて context.Context、-race、ジッターを使います	references/CONCURRENCY.md
レビュー	Go の変更をレビューする際はチェックリストを使います	references/REVIEW-CHECKLIST.md

---

よくある落とし穴

• 具象型ではなく、デフォルトでインターフェースを返す。
• カバレッジ率を正しさの証明として扱う。
• 再利用可能なパッケージでエラーを返す代わりにログを出力する。
• 標準ライブラリで十分に明確に解決できる場合に、フレームワークやヘルパーライブラリを追加する。
• アプリケーション全体の設定を、ローカルな Config ではなくパッケージ間で受け渡す。
• 重要な実行時設定を、危険なデフォルト値のままにする。
• 明確な規約がすでにあるリポジトリに、独自のディレクトリ構成を押し付ける。
• タスクがどのトピックに関係するか分かる前に、すべての参照ドキュメントを読み込む。
• ベンチマークなしでパフォーマンス向上を主張したり、-race なしで並行処理の安全性を主張したりする変更をリリースする。

---

基本ガイダンス

タスクで詳細が必要なトピックの参照ファイルだけを読み込みます。

• アプリケーションのパッケージは、依存関係の配線、ライフサイクル、エラーポリシー、ロギングポリシー、メトリクスポリシーを担います。
• 再利用可能なパッケージはエラーを返し、ローカルな Config または Opts を定義し、初期化済みの依存関係を受け取り、隠れたロギングやグローバル状態を避けます。
• 依存関係の選定では、まず標準ライブラリを検討します。実際の問題を解決し、積極的に保守され、推移的依存関係のコストに見合う場合に限り、サードパーティーパッケージを使います。
• サービスでは通常、cmd/<appname>/main.go を薄く保ちます。pkg/、internal/ などの独自の構成を押し付けず、確立されたリポジトリのレイアウトに従います。
• ライブラリでは通常、パッケージを浅く保ち、ドメインごとに分けます。
• コンストラクターでは、New(cfg Config) (*T, error)、明示的なデフォルト値、検証、具象型の返却、正規化後の変更不可な設定を優先します。
• インターフェースは小さく、境界に基づくものとし、通常は利用側で定義します。
• テストはテーブル駆動で標準ライブラリを優先し、防御的に作成します。並行処理が重要なコードでは -race を付けて実行します。
• パフォーマンスに関する主張にはベンチマークが必要です。
• ドキュメント、コメント、設定のデフォルト値、エラーの振る舞い、シグネチャは、すべて契約の一部です。

---

リファレンスの読み込み

現在のタスクに必要なリファレンスのみを読み込みます。

• コンストラクター、 Config 構造体、デフォルト値、検証、縮退モード、ロギングの注入については、references/CONFIG.md を読みます。
• インターフェースの境界、ドライバーパターン、モック／フェイク、具体的な戻り値の判断については、references/INTERFACES.md を読みます。
• センチネルエラー、ラップ、型付きエラー、recover の配置、コンストラクターの失敗については、references/ERRORS.md を読みます。
• パッケージのロギング、slog、ログレベル、非同期エラーの表面化、ペイロードの安全性については、references/LOGGING.md を読みます。
• テーブル駆動テスト、ファジング、testdata、統合ゲート、テストヘルパー、アサーションの選択については、references/TESTING.md を読みます。
• ゴルーチン、コンテキストの伝播、グレースフルシャットダウン、mutex／atomic／チャネルの選択、ジッター、レーステストについては、references/CONCURRENCY.md を読みます。
• パッケージのレイアウト、ファイル名、main.go、依存関係の整理、構造体フィールドのレイアウト、エクスポートのルールについては、references/LAYOUT.md を読みます。
• パッケージドキュメント、godoc、例、非推奨化、内部コメント、フィールドのドキュメントについては、references/DOCUMENTATION.md を読みます。
• ベンチマークの形式、アロケーションの報告、並行ベンチマーク、IO ベンチマーク、benchstat については、references/BENCHMARKS.md を読みます。
• Go PR をレビューするとき、または最終確認を行うときは、references/REVIEW-CHECKLIST.md を読みます。