AIエージェント向けgo-zeroスキル

このスキルは、開発者がプロダクション対応のサービスを構築するのを支援するAIエージェント向けに最適化された、包括的なgo-zeroマイクロサービスフレームワークの知識を提供します。REST API、RPCサービス、データベース操作、レジリエンスパターン、トラブルシューティングをカバーしています。

🎯 このスキルを使用する場合

go-zeroを使用する場合は、このスキルを起動してください:

• サービスの作成: REST API、gRPCサービス、またはマイクロサービスアーキテクチャ
• データベース統合: SQL、MongoDB、Redis、または接続プーリング
• プロダクション強化: サーキットブレーカー、レート制限、またはエラーハンドリング
• デバッグ: エラーの理解、設定の修正、または問題の解決
• 学習: go-zeroのパターンとベストプラクティスの理解

📚 知識構造

このスキルは、go-zeroの知識を焦点を絞ったモジュールに整理します。一度にすべてを読むのではなく、必要に応じて特定のガイドをロードしてください:

クイックスタートガイド

リンク: go-zero公式ドキュメント 含まれる内容: インストール、最初のAPIサービス、基本コマンド、ハローワールドの例(公式ドキュメントを参照)

パターンガイド(詳細リファレンス)

1. REST APIパターン

ファイル: references/rest-api-patterns.md ロードする場合: HTTPエンドポイントの作成、CRUD操作の実装、ミドルウェアの追加 含まれる内容:

• ハンドラ → ロジック → コンテキストの3層アーキテクチャ
• 適切なタイプでのリクエスト/レスポンスハンドリング
• ミドルウェア(認証、ロギング、メトリクス、CORS)
• httpx.Error() と httpx.OkJson() を使用したエラーハンドリング
• ✅ 正しいパターン vs ❌ 正しくないパターンの完全なCRUDの例

2. RPCサービスパターン

ファイル: references/rpc-patterns.md ロードする場合: gRPCサービスの構築、サービス間通信 含まれる内容:

• プロトコルバッファの定義とコード生成
• etcd/consul/kubernetesを使用したサービスディスカバリー
• ロードバランシング戦略
• クライアント設定とインターセプター
• RPCコンテキストでのエラーハンドリング

3. データベースパターン

ファイル: references/database-patterns.md ロードする場合: データ永続化、キャッシング、または複雑なクエリの実装 含まれる内容:

• sqlxを使用したSQL操作(CRUD、トランザクション、バッチ挿入)
• MongoDB統合パターン
• Redisキャッシング戦略とキャッシュアサイドパターン
• goctl model を使用したモデル生成
• 接続プーリングとパフォーマンスチューニング

4. レジリエンスパターン

ファイル: references/resilience-patterns.md ロードする場合: プロダクション強化、障害への対応、システム負荷の管理 含まれる内容:

• サーキットブレーカー設定(Breaker)
• レート制限とAPI制限
• 負荷がかかった場合の負荷シェッディング
• タイムアウトと再試行戦略
• グレースフルシャットダウンと機能低下

5. goctlコマンドリファレンス

ファイル: references/goctl-commands.md ロードする場合: goctlでのコード生成、新しいサービスのセットアップ、生成後のステップ 含まれる内容:

• goctlのインストールと検出
• API/RPC/モデル生成コマンドと正確なフラグ
• 生成後パイプライン(mod tidy、インポート修正、ビルド検証)
• 設定テンプレート(API、RPC、プロダクション)
• デプロイメントテンプレート(Dockerfile、Kubernetes、Docker Compose)
• ミドルウェアとエラーハンドラテンプレート
• APIスペックパターン(CRUD、JWT、混合認証)

サポートリソース

ベストプラクティス

ファイル: best-practices/overview.md ロードする場合: プロダクションデプロイメント、コードレビュー、最適化 含まれる内容: 設定管理、ロギング、監視、セキュリティ、パフォーマンス

トラブルシューティング

ファイル: troubleshooting/common-issues.md ロードする場合: エラーのデバッグ、設定の問題、実行時の問題 含まれる内容: 一般的なエラーメッセージ、ソリューション、設定の落とし穴、デバッグのヒント

Claude Code統合

ファイル: getting-started/claude-code-guide.md ロードする場合: Claude CodeでのZero-Skillsの使用をセットアップ 含まれる内容: インストール、起動方法、高度な機能(サブエージェント、動的コンテキスト)

ツール統合ガイド

ファイル: getting-started/README.md ロードする場合: Cursor、GitHub Copilot、Windsurf、またはCodexでzero-skillsをセットアップ 含まれる内容: 機能比較表、ツールごとのセットアップ手順(Claude Code、Cursor、Copilot、Windsurf、Codex)

🚀 一般的なワークフロー

これらのワークフローは、典型的なgo-zero開発タスクをガイドします:

新しいREST APIサービスの作成

ステップ:

1. .api ファイルでタイプとルートを使用してAPI仕様を定義
2. コード生成: goctl api go -api user.api -dir .
3. internal/logic/ レイヤーでビジネスロジックを実装
4. httpx でバリデーションとエラーハンドリングを追加
5. 適切なリクエスト/レスポンスハンドリングでエンドポイントをテスト

詳細ガイド: references/rest-api-patterns.md

データベース操作の実装

ステップ:

1. データベーススキーマを設計してテーブルを作成
2. モデル生成: goctl model mysql datasource -url="..." -table="users" -dir="./model"
3. internal/svc/service_context.go のServiceContextにモデルをインジェクト
4. ロジックレイヤーでsqlxメソッド(Insert、FindOne、Update、Delete)を使用
5. ctx の伝搬で適切にトランザクションとエラーを処理

詳細ガイド: references/database-patterns.md

ミドルウェアの追加

ステップ:

1. internal/middleware/ ディレクトリでミドルウェア関数を作成
2. .api ファイルでミドルウェアを定義するか、プログラムで登録
3. 認証/認可ロジックを実装
4. r.Context() を通して検証済みデータを渡す
5. 適切なHTTPステータスコードでエラーを処理

詳細ガイド: references/rest-api-patterns.md

RPCサービスの構築

ステップ:

1. .proto ファイルにメッセージとRPCを使用してサービスを定義
2. コード生成: goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.
3. internal/logic/ でサービスロジックを実装
4. サービスディスカバリー(etcd/consul/kubernetes)を設定
5. RPCクライアントでテストしてエラーを処理

詳細ガイド: references/rpc-patterns.md

⚡ 主要原則

go-zeroコードを生成またはレビューする場合、常にこれらの原則を適用してください:

✅ 常に従う

• 3層の分離: ハンドラ(ルーティング) → ロジック(ビジネス) → モデル(データ)を明確に区別
• 構造化エラー: fmt.Errorf の代わりに HTTPエラーには httpx.Error(w, err) を使用
• 設定: conf.MustLoad(&c, *configFile) でロードし、ServiceContextを通してインジェクト
• コンテキスト伝搬: トレーシングとキャンセルのため、すべてのレイヤーを通して ctx context.Context を渡す
• タイプセーフティ: .api ファイルでリクエスト/レスポンスタイプを定義し、goctlで生成
• goctl生成: ボイラープレートを生成するのに常に goctl を使用し、ハンドラ/ルートを手書きしない

❌ しないこと

• ハンドラに直接ビジネスロジックを配置(3層アーキテクチャに違反)
• httpx ヘルパーの代わりに w.Write() または fmt.Fprintf() で生のエラーを返す
• ポート、ホスト、データベース認証情報を設定値にハードコード
• ユーザー入力の検証をスキップするか、err != nil のチェックを忘れる
• 生成されたコードを修正(代わりに logic レイヤーを通してカスタマイズ)
• ServiceContextインジェクション(密結合とテストの問題につながる)をバイパス

📖 段階的学習パス

必要に応じて、このパスに従ってください:

🟢 go-zeroが初めてですか?

1. ここから開始: go-zero公式クイックスタート go-zeroをインストール、最初のAPIを作成、基本的な概念を理解

2. データベースを追加: references/database-patterns.md MySQL/PostgreSQLに接続、モデルを生成、CRUDを実装

🟡 プロダクションサービスを構築していますか?

1. ベストプラクティスをレビュー: best-practices/overview.md 設定、ロギング、監視、セキュリティチェックリスト

2. レジリエンスを追加: references/resilience-patterns.md サーキットブレーカー、レート制限、グレースフルな機能低下

3. 一般的な落とし穴を確認: troubleshooting/common-issues.md 典型的な間違いを回避し、問題をデバッグする方法を知る

🔵 機能を拡張していますか?

1. Claude Codeで使用: getting-started/claude-code-guide.md サブエージェント、動的コンテキスト、引数渡しなどの高度な機能を学習 環境を検証するためにデモプロジェクトを実行

2. 知識を検証: examples/verify-tutorial.sh 例が正しく機能しているかチェックするスクリプト

🔗 go-zero AIエコシステムとの統合

このスキルは、AIを支援するgo-zero開発のための2層エコシステムの一部です:

ツール	目的	最適なのは
ai-context	簡潔なワークフロー手順(約5KB)	GitHub Copilot、Cursor、Windsurf
zero-skills(このリポジトリ)	包括的な知識ベース + goctlリファレンス(約45KB)	すべてのAIツール、深い学習、リファレンス

AIはコード生成のためターミナルで goctl を直接実行します — 別のMCPサーバーは必要ありません。完全なコマンドリファレンスについては references/goctl-commands.md を参照してください。

Claude Codeでの使用:

• go-zeroプロジェクトを操作する場合、このスキルは自動的にロードされます
• go-zeroのガイダンスについて /zero-skills を使用してアマノジュアルに起動します
• AIはコード生成のためターミナルでgoctlコマンドを直接実行します
• 必要に応じて特定のパターンファイルを参照してください(Claudeはオンデマンドでロードします)

詳細な使用方法については getting-started/claude-code-guide.md を参照してください。

🌐 その他のリソース

• 公式ドキュメント: go-zero.dev - 最新のAPIリファレンスとガイド
• GitHub: zeromicro/go-zero - ソースコードとサンプル
• コミュニティ: メインリポジトリでのディスカッション、イシュー、コントリビューション

📝 バージョン互換性

• 目標バージョン: go-zero 1.5+
• Goバージョン: Go 1.19以降が推奨
• 更新: フレームワークの進化を反映するため、パターンは定期的に更新
• 破壊的変更: バージョン間のAPI変更については公式ドキュメントを確認

---

クイック起動: /zero-skills を使用するか、「go-zeroで[タスク]を実行するにはどうしたらいいですか?」と聞いてください ヘルプが必要ですか? 詳細な例と説明については、特定のパターンガイドを参照してください。