pma-go

Go プロジェクト実装ガイド

このスキルは /pma と併用してください。/pma はワークフロー、承認、タスク追跡を管理し、このガイドでは承認後の実装の基本方針を定めます。

このエントリーファイルは簡潔に保ちます。タスクに必要なリファレンスパックだけを読み込んでください。

対象範囲

PMA で管理される Go バックエンド、API サービス、CLI アプリケーションが対象です。

組み込みターゲット、バイナリのないライブラリ専用モジュール、PMA 対象外のプロジェクトは対象外です。

読み込み順序

1. 必ず最初に references/baseline.md を読み込みます。
2. 設定のレイヤリング、検証、sqlc、pgx、GORM、マイグレーションには references/config-and-data.md を読み込みます。
3. ハンドラー、ミドルウェア、ロギング、オブザーバビリティ、シャットダウンには references/http-and-runtime.md を読み込みます。
4. リント、テスト、タスクランナー、セキュリティレビュー、CI、Git ワークフローには references/delivery.md を読み込みます。

クイックルーティング

• 新しいサービスまたは CLI のセットアップ → references/baseline.md
• 設定（koanf のレイヤリング、環境変数のマッピング、検証）→ references/config-and-data.md
• データアクセス（sqlc + pgx、GORM、マイグレーション、リポジトリの境界）→ references/config-and-data.md
• ランタイム（HTTP サーバー、ミドルウェア、slog、トレーシング、シャットダウン）→ references/http-and-runtime.md
• 開発用 URL ルーティング（nsl）→ references/http-and-runtime.md（プロトコル全体については /pma references/dev-environment.md）
• テスト → references/delivery.md
• CI とデリバリー（品質ゲート、リント、Taskfile、セキュリティチェックリスト、PR の準備状況）→ references/delivery.md

リファレンスパック

• references/baseline.md スタックのデフォルト、品質ゲート、レイアウト、規約、エラーモデル、コード品質基準。
• references/config-and-data.md koanf による設定のレイヤリング、検証、sqlc と pgx、GORM の代替手段、マイグレーションのルール。
• references/http-and-runtime.md ルーターの構成、ハンドラーパターン、ミドルウェア、ロギング、オブザーバビリティ、グレースフルシャットダウン。
• references/delivery.md リント設定、テスト、タスクランナーの要件、セキュリティチェック、CI、Git の規約。

受け入れチェックリスト

マージ前：

• goimports -l . の出力が空であること。golangci-lint run と go vet ./... が成功すること
• go test -cover ./... が成功すること。カバレッジ目標は 80% 以上
• go build ./... が成功すること。go mod tidy による差分がないこと
• 変更したコードに対して gosec ./... が成功すること
• 設定を koanf でレイヤリング（デフォルト → ファイル → 環境変数 → フラグ）し、読み込み後に検証していること
• グレースフルシャットダウンが組み込まれていること（signal.NotifyContext + タイムアウト付きの http.Server.Shutdown）
• サービスに UI が含まれる場合、nsl による開発用ルーティングが機能すること（references/http-and-runtime.md を参照）

リポジトリがすでにこれらのデフォルトから逸脱している場合は、その逸脱を明示し、コード、ドキュメント、CI 全体で一貫して適用してください。