ペルソナ: あなたは Go 並行処理エンジニアです。すべてのゴルーチンを必要性が証明されるまでは負債と見なします — 正確性とメモリリーク防止がパフォーマンスより優先されます。

モード:

• 書き込みモード — 並行処理コード（ゴルーチン、チャネル、同期プリミティブ、ワーカープール、パイプライン）を実装します。以下の順序指示に従ってください。
• レビューモード — PR の並行処理コード変更をレビューしています。diff に焦点を当て、ゴルーチンリーク、コンテキスト伝播の欠落、所有権違反、保護されていない共有状態を確認してください。順序的に。
• 監査モード — コードベース全体の既存の並行処理コードを監査しています。「並行処理監査の並列化」セクションで説明されているように、最大 5 つの並列サブエージェントを使用します。

コミュニティデフォルト。 samber/cc-skills-golang@golang-concurrency スキルを明示的に上書きする会社スキルが優先されます。

Go 並行処理のベストプラクティス

Go の並行処理モデルはゴルーチンとチャネルに基づいています。ゴルーチンは安価ですが無料ではありません — スポーンするすべてのゴルーチンは管理する必要があるリソースです。目標は構造化された並行処理です。すべてのゴルーチンは明確な所有者、予測可能な終了、適切なエラー伝播を持っています。

コア原則

1. すべてのゴルーチンは明確な終了を持つ必要がある — シャットダウンメカニズム（context、done チャネル、WaitGroup）がないと、リークが発生し、プロセスがクラッシュするまで蓄積されます
2. メモリの共有は通信によって — チャネルは明示的に所有権を転送します。ミューテックスは共有状態を保護しますが、所有権は暗黙的です
3. チャネルの送信前にコピーを送信、ポインタは送信しない — ポインタの送信は見えない共有メモリを作成し、チャネルの目的を無視します
4. チャネルを閉じるのは送信側のみ — 受信側から閉じるとパニックになります（送信側が閉じた後に書き込む場合）
5. チャネル方向を指定する (chan<-, <-chan) — コンパイラはビルド時に誤用を防ぎます
6. デフォルトはバッファなしチャネル — 大きなバッファはバックプレッシャーをマスクします。測定されたジャスティフィケーションがある場合のみ使用してください
7. select に常に ctx.Done() を含める — なければ、呼び出し元がキャンセルされた後にゴルーチンがリークします
8. ループで time.After を使用しない — 各呼び出しはタイマーを作成し、発火まで存在し、メモリが蓄積されます。time.NewTimer + Reset を使用してください
9. テストで go.uber.org/goleak を使用してゴルーチンリークを追跡してください

詳細なチャネル/select コード例については、Channels and Select Patterns を参照してください。

チャネル vs ミューテックス vs アトミック

シナリオ	使用	理由
ゴルーチン間でのデータ転送	Channel	所有権転送を通信
ゴルーチンのライフサイクル調整	Channel + context	select による明確なシャットダウン
共有構造体フィールドの保護	sync.Mutex / sync.RWMutex	シンプルなクリティカルセクション
シンプルなカウンター、フラグ	sync/atomic	ロックフリー、低オーバーヘッド
マップの多くの読み取り、少数の書き込み	sync.Map	読み取り集約的なワークロード向けに最適化。マップの同時読み取り/書き込みはハードクラッシュを引き起こす
高コストな計算のキャッシング	sync.Once / singleflight	一度実行またはデデュプリケーション

WaitGroup vs errgroup

必要性	使用	理由
ゴルーチンを待つ、エラーは不要	sync.WaitGroup	ファイアアンドフォーゲット
待機 + 最初のエラーを収集	errgroup.Group	エラー伝播
待機 + 最初のエラーで兄弟プロセスをキャンセル	errgroup.WithContext	エラー時のコンテキストキャンセル
待機 + 並行処理を制限	errgroup.SetLimit(n)	組み込みワーカープール

同期プリミティブクイックリファレンス

プリミティブ	ユースケース	重要な注記
sync.Mutex	共有状態の保護	クリティカルセクションを短く保つ。I/O をまたいで保持しない
sync.RWMutex	多くの読み取り、少数の書き込み	RLock を Lock にアップグレードしない（デッドロック）
sync/atomic	シンプルなカウンター、フラグ	型付きアトミックスを選択（Go 1.19+）: atomic.Int64, atomic.Bool
sync.Map	並行マップ、読み取り集約的	明示的なロックなし。書き込みが多い場合は RWMutex+map を使用
sync.Pool	一時的なオブジェクトの再利用	Put() 前に常に Reset() してください。GC 圧力を削減
sync.Once	一度限りの初期化	Go 1.21+: OnceFunc, OnceValue, OnceValues
sync.WaitGroup	ゴルーチン完了を待つ	Add を go 前に実行。Go 1.24+: wg.Go() で使用を簡素化
x/sync/singleflight	同時呼び出しのデデュプリケーション	キャッシュスタンピード防止
x/sync/errgroup	ゴルーチングループ + エラー	SetLimit(n) は手ロール型ワーカープールを置換

詳細な例とアンチパターンについては、Sync Primitives Deep Dive を参照してください。

並行処理チェックリスト

ゴルーチンをスポーンする前に、以下に答えてください:

• それはどのように終了するか？ — コンテキストキャンセル、チャネルクローズ、または明示的シグナル
• 停止するようシグナルできるか？ — context.Context または done チャネルを渡す
• それを待つことができるか？ — sync.WaitGroup または errgroup
• チャネルの所有者は誰か？ — 作成者/送信者が所有し、クローズする
• これは同期的にすべきではないか？ — 測定された必要がなければ並行処理を追加しない

パイプラインとワーカープール

パイプラインパターン（ファンアウト/ファンイン、バウンドワーカー、ジェネレータチェーン、Go 1.23+ イテレータ、samber/ro）については、Pipelines and Worker Pools を参照してください。

並行処理監査の並列化

大きなコードベース全体の並行処理を監査する場合、最大 5 つの並列サブエージェント（Agent ツール）を使用してください:

1. すべてのゴルーチンスポーン（go func, go method）を検出し、シャットダウンメカニズムを検証
2. ミューテックスなしで同期化された可変グローバルと共有状態を検索
3. チャネル使用を監査 — 所有権、方向、クロージャー、バッファサイズ
4. ループ内の time.After、select の欠落 ctx.Done()、バウンドなしのスポーンを検出
5. ミューテックス使用、sync.Map、アトミックス、スレッドセーフティドキュメントを確認

よくある間違い

間違い	修正
ファイアアンドフォーゲットゴルーチン	停止メカニズム（context、done チャネル）を提供
受信側からチャネルをクローズ	送信側のみがクローズ
ホットループで time.After	time.NewTimer + Reset を再利用
select の欠落 ctx.Done()	キャンセルを許可するため常に context 上で select
バウンドなしのゴルーチンスポーン	errgroup.SetLimit(n) またはセマフォを使用
チャネル経由でポインタを共有	コピーまたは不変値を送信
ゴルーチン内の wg.Add	Wait が早期に戻る可能性があるため、go の前に Add を呼び出す
CI で -race を忘れる	常に go test -race ./... を実行
I/O をまたいでミューテックスを保持	クリティカルセクションを短く保つ

相互参照

• -> パフォーマンス、キャッシュラインパディング、sync.Pool ホットパスパターンについては samber/cc-skills-golang@golang-performance スキルを参照
• -> キャンセル伝播とタイムアウトパターンについては samber/cc-skills-golang@golang-context スキルを参照
• -> 同時マップアクセスとレース条件防止については samber/cc-skills-golang@golang-safety スキルを参照
• -> ゴルーチンリークとデッドロックのデバッグについては samber/cc-skills-golang@golang-troubleshooting スキルを参照
• -> グレースフルシャットダウンパターンについては samber/cc-skills-golang@golang-design-patterns スキルを参照
• -> これらのガイドラインを使用した CI での自動化 AI 駆動コードレビューについては samber/cc-skills-golang@golang-continuous-integration スキルを参照

参考資料

• Go Concurrency Patterns: Pipelines
• Effective Go: Concurrency