zero-skills

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

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

🎯 このスキルを使用するタイミング

go-zero を扱うときは、このスキルを呼び出してください。

• サービスの作成：REST API、gRPC サービス、マイクロサービスアーキテクチャ
• データベース統合：SQL、MongoDB、Redis、コネクションプーリング
• データ構造：LRU Cache、Ring Buffer、TimingWheel、並行マップ
• 本番環境への対応：サーキットブレーカー、レート制限、エラー処理
• デバッグ：エラーの理解、設定の修正、問題の解決
• 学習：go-zero のパターンとベストプラクティスの理解

📚 知識の構成

このスキルでは、go-zero の知識を用途別のモジュールに整理しています。一度にすべてを読むのではなく、必要に応じて特定のガイドを読み込んでください。

クイックスタートガイド

リンク：go-zero 公式ドキュメント 内容：インストール、最初の API サービス、基本コマンド、hello-world の例（公式ドキュメントを参照）

パターンガイド（詳細リファレンス）

1. REST API パターン

ファイル：references/rest-api-patterns.md 読み込むタイミング：HTTP エンドポイントの作成、CRUD 操作の実装、ミドルウェアの追加 内容：

• Handler → Logic → Context の 3 層アーキテクチャ
• 適切な型を使ったリクエスト／レスポンスの処理
• ミドルウェア（認証、ログ記録、メトリクス、CORS）
• httpx.Error() と httpx.OkJson() を使ったエラー処理
• ✅ 正しいパターンと❌ 誤ったパターンを含む CRUD の完全な例

2. RPC サービスパターン

ファイル：references/rpc-patterns.md 読み込むタイミング：gRPC サービスの構築、サービス間通信 内容：

• Protocol Buffers の定義とコード生成
• etcd／consul／kubernetes を使ったサービスディスカバリー
• ロードバランシング戦略
• クライアントの設定とインターセプター
• RPC コンテキストでのエラー処理

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

ファイル：references/database-patterns.md 読み込むタイミング：データ永続化、キャッシュ、複雑なクエリの実装 内容：

• sqlx を使った SQL 操作（CRUD、トランザクション、一括挿入）
• MongoDB 統合パターン
• Redis キャッシュ戦略とキャッシュアサイドパターン
• goctl model を使ったモデル生成
• コネクションプーリングとパフォーマンスチューニング

4. 回復性パターン

ファイル：references/resilience-patterns.md 読み込むタイミング：本番環境への対応、障害への対処、システム負荷の管理 内容：

• サーキットブレーカーの設定（Breaker）
• レート制限と API スロットリング
• 高負荷時の負荷遮断
• タイムアウトとリトライ戦略
• グレースフルシャットダウンと縮退運転

5. コレクションパターン

ファイル：references/collection-patterns.md 読み込むタイミング：高性能データ構造、ローカルキャッシュ、タイムアウト管理を使用するとき 内容：

• ローカルの頻出データをキャッシュする LRU Cache（O(1) 操作）
• 固定サイズの循環バッファ向け Ring Buffer
• 効率的なタイマー管理を行う TimingWheel（O(1) の追加／削除／実行）
• 並行処理で安全なマップ操作を行う SafeMap
• メモリ管理のベストプラクティスと注意点

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

ファイル：references/goctl-commands.md 読み込むタイミング：goctl によるコード生成、新しいサービスのセットアップ、生成後の手順 内容：

• goctl のインストールと検出
• 正確なフラグを含む API／RPC／Model 生成コマンド
• 生成後のパイプライン（mod tidy、インポートの修正、ビルドの検証）
• 設定テンプレート（API、RPC、本番環境）
• デプロイメントテンプレート（Dockerfile、Kubernetes、Docker Compose）
• ミドルウェアとエラーハンドラーのテンプレート
• API 仕様のパターン（CRUD、JWT、混合認証）

7. Swagger / OpenAPI ドキュメント

ファイル：references/swagger-patterns.md 読み込むタイミング：.api ファイルから Swagger/OpenAPI ドキュメントを生成するとき、API ドキュメントのアノテーションを追加するとき 内容：

• 組み込みの goctl api swagger コマンドリファレンス（goctl ≥ 1.8.4。プラグインは不要）
• info ブロックのメタデータ：title、description、host、basePath、schemes、useDefinitions、wrapCodeMsg
• Swagger UI のグループ分けに使用する @server タグ
• エンドポイントの概要／説明に使用する @doc
• フィールドタグ：example、options（列挙型）、range、default、optional
• セキュリティ定義（securityDefinitionsFromJson + authType）
• ビジネスエラーコード（bizCodeEnumDescription）
• ベストプラクティスを含む、複数ファイルから成る .api 構成の完全な例

8. 分散トランザクションのパターン

ファイル：references/distributed-transactions.md 読み込むタイミング：サービス間のデータ整合性、DTM 連携、SAGA/TCC パターンを扱うとき 内容：

• Workflow、Saga、TCC、XA、2 フェーズメッセージ、outbox のパターン選択ガイド
• 検証済みの DTM HTTP Saga のスケルトン
• バリア、冪等性、補償、セキュリティ、障害テストのチェックリスト

9. 可観測性のパターン

ファイル：references/observability.md 読み込むタイミング：本番環境の監視、トレース、アラートを設定するとき 内容：

• Prometheus メトリクスの設定
• カスタムメトリクスの実装
• OpenTelemetry/Jaeger による分散トレーシング
• logx による構造化ロギング
• Grafana ダッシュボードとアラートルール
• ログ集約のための ELK 連携

10. メッセージキューのパターン

ファイル：references/message-queue.md 読み込むタイミング：非同期処理、遅延タスク、イベントストリーミングを扱うとき 内容：

• 遅延タスク向けの go-queue dq（Beanstalkd）
• 高スループットのメッセージング向けの go-queue kq（Kafka）
• 現在のプロデューサー API とコンシューマー API
• ライフサイクル、再試行、冪等性、シャットダウンに関するガイダンス

11. 高度なコンポーネント

ファイル：references/advanced-components.md 読み込むタイミング：パフォーマンスの最適化、並行処理、キャッシュを扱うとき 内容：

• キャッシュ浸透を防ぐブルームフィルター
• 遅延タスクのスケジューリングに使用する TimingWheel
• 並列処理向けの MapReduce
• バッチタスクのバッファリングに使用する Executors
• 重複を防止する SharedCalls（SingleFlight）

補足リソース

ベストプラクティス

ファイル：best-practices/overview.md 読み込むタイミング：本番環境へのデプロイ、コードレビュー、最適化のとき 内容：設定管理、ロギング、監視、セキュリティ、パフォーマンス

トラブルシューティング

ファイル：troubleshooting/common-issues.md 読み込むタイミング：エラー、設定の問題、実行時の問題をデバッグするとき 内容：よくあるエラーメッセージ、解決策、設定上の注意点、デバッグのヒント

Claude Code 連携

ファイル：getting-started/claude-code-guide.md 読み込むタイミング：スキルを使わずに Claude Code を使用できるよう設定するとき 内容：インストール、呼び出し方法、高度な機能（サブエージェント、動的コンテキスト）

設計原則

ファイル：design/principles.md 読み込むタイミング：フレームワークの理念やアーキテクチャ上の判断を理解するとき 内容：3 層アーキテクチャの根拠、設計上の判断、パフォーマンスに関する考慮事項、アンチパターン

ケーススタディ：go-zero-looklook

ファイル：examples/case-studies/looklook-overview.md 読み込むタイミング：本番規模の例や実際のアーキテクチャから学ぶとき 内容：ソースに基づくリポジトリマップ、学習ワークフロー、再利用可能なパターン、検証チェックリスト

ツール連携ガイド

ファイル: 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. メッセージと RPC を含むサービスを .proto ファイルで定義します
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

Swagger ドキュメントの生成

手順:

1. エントリー .api ファイルに Swagger メタデータ（title、host、basePath、schemes）を含む info ブロックを追加します
2. Swagger UI でグループ分けするため、@server ブロックに tags を追加します
3. 各エンドポイントに @doc の概要を追加します
4. リクエスト／レスポンスのフィールドに example／options／range タグを追加します
5. goctl api swagger --api entry.api --dir docs/swagger --filename api を実行します

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

高性能データ構造の使用

手順:

1. ユースケースに応じて適切なデータ構造を選択します:
   • ローカルのホットデータのキャッシュには LRU Cache
   • 固定サイズのログ／メッセージバッファーには Ring Buffer
   • タイムアウト／遅延タスクの管理には TimingWheel
   • 並行アクセスに安全なキーと値の保存には SafeMap
2. github.com/zeromicro/go-zero/core/collection からインポートします
3. メモリ制約に基づいて容量／パラメーターを設定します
4. リソースのクリーンアップのため、退避コールバックを処理します（LRU Cache）
5. メモリ使用量を監視し、必要に応じて再構築します（SafeMap）

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

⚡ 主な原則

go-zero のコードを生成またはレビューする際は、常に次の原則に従ってください。

✅ 必ず従うこと

• 3 層の分離: Handler（ルーティング）→ Logic（ビジネス）→ Model（データ）を明確に分けます
• 構造化エラー: HTTP エラーには fmt.Errorf ではなく httpx.Error(w, err) を使用します
• 設定: conf.MustLoad(&c, *configFile) で読み込み、ServiceContext 経由で注入します
• コンテキストの伝播: トレースとキャンセルのため、すべてのレイヤーに ctx context.Context を渡します
• 型安全性: リクエスト／レスポンスの型を .api ファイルで定義し、goctl で生成します
• goctl による生成: 常に goctl でボイラープレートを生成し、ハンドラー／ルートを手書きしないでください

❌ 絶対にしないこと

• ハンドラーにビジネスロジックを直接記述する（三層アーキテクチャに違反します）
• 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. データ構造を最適化する：references/collection-patterns.md パフォーマンス向上のための LRU Cache、Ring Buffer、TimingWheel

4. よくある落とし穴を確認する：troubleshooting/common-issues.md 典型的なミスを避け、問題のデバッグ方法を把握します

5. オブザーバビリティを設定する：references/observability.md Prometheus メトリクス、分散トレーシング、構造化ロギング

🔴 高度なシナリオに取り組みますか？

1. 分散トランザクション：references/distributed-transactions.md DTM との統合、SAGA/TCC パターン、データの一貫性

2. メッセージキュー：references/message-queue.md 非同期処理、遅延タスク、Kafka との統合に go-queue を使用します

3. パフォーマンスの最適化：references/advanced-components.md Bloom filter、MapReduce、TimingWheel、SharedCalls

4. 設計を理解する：design/principles.md フレームワークの理念、アーキテクチャ上の判断、アンチパターン

5. サンプルから学ぶ：examples/case-studies/looklook-overview.md 本番規模のアーキテクチャ、実際のパターン

🔵 機能を拡張しますか？

1. Claude Code と併用する：getting-started/claude-code-guide.md サブエージェント、動的コンテキスト、引数の受け渡しなどの高度な機能を学びます デモプロジェクトを実行して、環境を検証します

2. 知識を検証する：examples/verify-tutorial.sh サンプルが正しく動作するか確認するスクリプト

🔗 go-zero AI エコシステムとの連携

このスキルは、AI を活用した go-zero 開発のための二層エコシステムの一部です。

ツール	用途	最適な対象
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 v1.10.3（Go 1.24 以降が必要です）
• master との互換性: go-zero の master ブランチに対してテストする場合は、Go 1.25 以降を使用してください
• 更新: フレームワークの進化に合わせて、パターンを定期的に更新しています
• 破壊的変更: バージョン間の API 変更については、公式ドキュメントを確認してください

---

クイック呼び出し: /zero-skills を使用するか、「go-zero で [タスク] を行うにはどうすればよいですか？」と尋ねてください お困りですか？ 詳しい例と説明については、該当するパターンガイドを参照してください。