kratos-skills

AI エージェント向け Kratos スキル

このスキルでは、go-kratos マイクロサービスフレームワークに関する包括的な知識を提供します。開発者が本番環境に対応できるサービスを構築できるよう支援する AI エージェント向けに最適化されています。

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

go-kratos を使用する際に、このスキルを呼び出してください。

• サービスの作成：REST API、gRPC サービス、またはマイクロサービスアーキテクチャ
• レイヤードアーキテクチャ：DDD を用いた Service → Biz → Data レイヤーの実装
• 依存性注入：コンパイル時 DI に Wire を使用
• 本番環境向けの強化：サーキットブレーカー、レート制限、ミドルウェア
• デバッグ：エラーの理解、設定の修正、問題の解決
• 学習：kratos のパターンとベストプラクティスの理解

📚 ナレッジ構成

一度にすべてを読むのではなく、必要に応じて特定のガイドを読み込んでください。

クイックスタート

リンク：Kratos 公式ドキュメント 内容：インストール、プロジェクトの作成、基本的なコマンド、Hello World のサンプル

パターンガイド

API とトランスポート

ファイル	読み込むタイミング
references/api-patterns.md	Protobuf API の定義、HTTP/gRPC コードの生成
references/transport-patterns.md	HTTP/gRPC サーバー／クライアントの設定
references/encoding-patterns.md	カスタムシリアライズ、コンテンツネゴシエーション
references/openapi-guide.md	OpenAPI/Swagger ドキュメントの生成

アーキテクチャと設計

ファイル	読み込むタイミング
references/architecture-patterns.md	DDD レイヤー、リポジトリパターン、Wire DI
references/error-patterns.md	エラーの定義、アサーション、proto エラー
references/middleware-patterns.md	カスタムミドルウェア、リクエストのフィルタリング

インフラストラクチャ

ファイル	読み込むタイミング
references/config-patterns.md	設定の読み込み、ホットリロード、設定センター
references/registry-patterns.md	サービスディスカバリー（etcd、consul、nacos、k8s）
references/selector-patterns.md	ロードバランシング（P2C、WRR、ランダム）

レジリエンスと信頼性

ファイル	読み込むタイミング
references/circuit-breaker-patterns.md	フォールトトレランス、SRE サーキットブレーカー
references/ratelimit-patterns.md	トークンバケット、BBR レート制限
references/recovery-patterns.md	パニックリカバリー、スタックトレースのログ記録

オブザーバビリティ

ファイル	読み込むタイミング
references/logging-patterns.md	構造化ログ、Zap/Logrus アダプター
references/metrics-patterns.md	Prometheus メトリクスの収集
references/tracing-patterns.md	OpenTelemetry、Jaeger/Zipkin トレーシング
references/metadata-patterns.md	コンテキストの伝播、トレース ID

セキュリティとバリデーション

ファイル	読み込むタイミング
references/auth-patterns.md	JWT 認証、クレーム、トークン生成
references/validate-patterns.md	Proto フィールドのバリデーション、protoc-gen-validate

データとツール

ファイル	読み込むタイミング
references/ent-patterns.md	Ent ORM の統合、スキーマ設計
references/cli-guide.md	kratos CLI、コード生成コマンド

参考リソース

ファイル	読み込むタイミング
best-practices/overview.md	本番環境へのデプロイ、コードレビューのチェックリスト
troubleshooting/common-issues.md	エラーのデバッグ、protoc／wire の問題
getting-started/claude-code-guide.md	Claude Code との統合、高度な機能

🚀 一般的なワークフロー

新しいサービスの作成

1. プロジェクトを作成する：kratos new <project-name>
2. API を定義する：google.api.http アノテーションを含む .proto を作成します
3. コードを生成する：kratos proto client api/demo/v1/demo.proto
4. サービスを生成する：kratos proto server api/demo/v1/demo.proto -t internal/service
5. 各レイヤーを実装する：Biz ロジックは internal/biz/、データアクセスは internal/data/ に記述します
6. Wire を設定する：provider セットを使って cmd/server/wire.go を更新します
7. 実行する：go generate ./... && kratos run

詳細：references/api-patterns.md

レイヤードアーキテクチャの実装

1. internal/biz/ にインターフェースを定義します（biz レイヤー）
2. internal/data/ にリポジトリーを実装します（data レイヤー）
3. internal/biz/ にユースケースを記述します（biz レイヤー）
4. internal/service/ にハンドラーを実装します（service レイヤー）
5. ProviderSets を作成します：data.ProviderSet、biz.ProviderSet、service.ProviderSet
6. cmd/server/wire.go で各レイヤーを Wire で接続します

詳細：references/architecture-patterns.md

ミドルウェアの追加

http.Middleware(
    recovery.Recovery(),           // 1. Catch panics first
    validate.Validator(),          // 2. Validate requests
    jwt.Server(keyFunc),           // 3. Authentication
    ratelimit.Server(limiter),     // 4. Rate limiting
    logging.Server(logger),        // 5. Logging
)

詳細：references/middleware-patterns.md

サービスディスカバリーの設定

// Server-side
reg := etcd.New(client)
app := kratos.New(kratos.Registrar(reg))

// Client-side
dis := etcd.New(client)
conn, _ := grpc.DialInsecure(
    context.Background(),
    grpc.WithEndpoint("discovery:///service-name"),
    grpc.WithDiscovery(dis),
)

詳細：references/registry-patterns.md

⚡ 主要な原則

✅ 必ず守ること

• レイヤーの分離：Service（API）→ Biz（Business）→ Data（Persistence）
• 依存性逆転：インターフェースは biz に、実装は data に配置します
• Protobuf を優先する：API とエラーは .proto ファイルで定義します
• Wire によるインジェクション：コンパイル時 DI を使い、グローバル状態は使用しません
• コンテキストの伝播：すべてのレイヤーで ctx context.Context を渡します
• インターフェースベースの設計：実装ではなく、インターフェースに対してプログラミングします
• エラーコード：コード、理由、メッセージ、メタデータを含む構造化エラーを使用します

❌ 決してしないこと

• サービスハンドラーにビジネスロジックを記述する（レイヤードアーキテクチャに反します）
• インターフェースの定義を省略し、具象型を直接使用する
• 依存関係にグローバル変数を使用する
• HTTP ハンドラーを手動で定義する（proto から生成されたコードを使用します）
• 設定値をハードコードする
• 検証を省略する、または err != nil の確認を忘れる
• 生成された .pb.go ファイルを変更する

📖 段階的な学習ガイド

🟢 kratos を初めて使いますか？

1. 公式クイックスタート - CLI をインストールし、最初のプロジェクトを作成します
2. references/architecture-patterns.md - Service → Biz → Data の構成を理解します
3. references/api-patterns.md - Protobuf API の定義方法を学びます

🟡 本番サービスを構築していますか？

1. best-practices/overview.md - 本番環境向けチェックリスト
2. references/circuit-breaker-patterns.md + references/ratelimit-patterns.md - 耐障害性を高めます
3. references/registry-patterns.md - サービスディスカバリー
4. troubleshooting/common-issues.md - よくある問題を回避します

🔵 機能を拡張しますか？

1. getting-started/claude-code-guide.md - Claude Code の高度な機能
2. Kratos のサンプル - サンプルプロジェクト

🔗 Kratos エコシステム

プロジェクト	目的
kratos	フレームワークのコア、CLI ツール
kratos-layout	公式プロジェクトテンプレート
contrib	設定、レジストリ、ログ、メトリクス用のプラグイン
aegis	可用性アルゴリズム
gateway	API ゲートウェイ
examples	サンプルコード

📝 バージョン互換性

• 対象バージョン：kratos v2.0.0+
• Go バージョン：Go 1.19 以降を推奨
• Protoc：3.0+

---

クイック呼び出し：/kratos-skills を使用するか、「kratos で [タスク] を行うにはどうすればよいですか？」と尋ねてください。