kafka-schema-review

Kafka スキーマ進化レビュー

スキーマ変更の互換性と進化に関するベストプラクティスをレビューします。互換性を損なうスキーマ変更が1つあるだけで、トピックのすべてのコンシューマーが停止する可能性があります。

対象環境：$ARGUMENTS

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Schema Review Progress:
- [ ] Step 1: Fetch registered schemas
- [ ] Step 2: Scan codebase for schema files
- [ ] Step 3: Detect breaking changes
- [ ] Step 4: Check schema quality
- [ ] Step 5: Check schema drift
- [ ] Step 6: Generate report

1. 登録済みスキーマを取得する：Lenses MCP 経由で稼働中のクラスターから取得します
2. コードベースをスキャンする：スキーマ定義ファイルを探します（ファイル形式については references/compatibility-rules.md を参照）
3. 互換性を損なう変更を検出する：references/compatibility-rules.md の互換性ルールに照らして確認します
4. スキーマの品質を確認する：ベストプラクティスに照らして確認します
5. スキーマの乖離を確認する：リポジトリとクラスターを比較します
6. 調査結果を報告する：移行方法の案内を含めます

ステップ 1：登録済みスキーマを取得する

Lenses MCP ツールを使い、クラスター内のスキーマの現在の状態を取得します。

• list_topic_metadata - トピックに登録されているすべてのスキーマ（キーと値）を取得します
• get_topic_metadata - 特定のトピックの現在のスキーマを取得します
• get_dataset - データセットのフィールド単位の詳細、ポリシー、ガバナンスメタデータを取得します
• schema_format フィルター付きの list_datasets - 指定した形式（AVRO、JSON、PROTOBUF）を使用するすべてのトピックを検索します

期待される出力：トピックを、登録済みスキーマ（キーと値）、形式、バージョン情報に対応付けた一覧。

検証：スキーマが登録されていない場合は、ガバナンス上の不備として記録し、コードベースのみを対象とする分析を続行します。

ステップ 2：コードベースの調査

コードベースからスキーマ定義ファイルを検索します。ファイル形式と検索パターンの一覧は、references/compatibility-rules.md を参照してください。

PR をレビューする場合は、git diff を使って最近変更されたスキーマファイルを特定します。

ステップ 3：互換性チェック

スキーマ変更ごとに、references/compatibility-rules.md の互換性ルールに照らして評価します。トピックに設定されている互換性レベルに応じて、後方互換性、前方互換性、完全互換性を確認します。

ステップ 4：スキーマの品質チェック

references/compatibility-rules.md の品質チェックを実施します。

• ドキュメント用アノテーションのないフィールド
• 任意フィールドにデフォルト値が設定されていない
• 命名規則に一貫性がない
• 使用されていない、または汎用的すぎるフィールド名

ステップ 5：スキーマの乖離を検出する

リポジトリ内のスキーマファイルと、クラスターに登録されているスキーマを比較します。

• execute_sql を使って本番データをサンプリングし、想定されるスキーマと一致することを検証します
• リポジトリ内のスキーマと登録済みスキーマが異なる場合は、その旨を報告します
• リポジトリ内に対応するファイルがないのに、スキーマが登録されているトピックがあれば報告します

成功基準

定量的

• スキーマ関連の問い合わせの90％で起動する（表現を変えた10～20件の問い合わせでテスト）
• 12回未満のツール呼び出し（MCP＋コードベース検索）でレビューを完了する
• 互換性を損なう変更の検出における誤検出が0件

定性的

• 互換性を損なう変更について、明確な移行方法を提示する
• スキーマの乖離を報告する際、リポジトリとクラスターの両方のバージョンを示す
• 品質に関する指摘は、外部ドキュメントを参照しなくても対応できる内容にする

例

例 1：マージ前のスキーマレビュー

ユーザーの依頼：「この PR のスキーマ変更をレビューしてください」

実施内容：

1. git diff を実行し、変更された .avsc、.proto、.json のスキーマファイルを探します
2. Lenses MCP 経由でクラスターに現在登録されているスキーマを取得します
3. 各変更を互換性ルールに照らして評価します

結果：互換性を損なう変更があれば、移行方法の案内とともに一覧で報告します

例 2：スキーマ全体の監査

ユーザーの依頼：「ステージング環境のすべてのスキーマを監査してください」

実施内容：

1. list_topic_metadata 経由ですべての登録済みスキーマを取得します
2. コードベースからスキーマファイルを検索します
3. リポジトリとクラスターの乖離を確認します
4. すべてのスキーマに品質チェックを実施します

結果：互換性、品質、乖離を網羅した包括的なレポートを作成します

例 3：コンシューマーの障害を調査する

ユーザーの発言：「コンシューマーが orders.payment.completed からのメッセージをデシリアライズできず、失敗しています」

アクション：

1. get_topic_metadata を使って、そのトピックに登録されているスキーマを取得します
2. execute_sql でライブデータをサンプリングし、実際のメッセージ形式を確認します
3. リポジトリ内のスキーマファイルと比較します 結果：スキーマの不一致を診断し、修正手順を提示します

トラブルシューティング

クラスターにスキーマが登録されていない

原因：Schema Registry が設定されていないか、トピックでスキーマなしの形式（プレーンな JSON、CSV）が使用されています。 解決策：これは有効な調査結果です。エラーとしてではなく、ガバナンス上の課題として報告してください。スキーマ登録の追加を推奨します。

スキーマのドリフトが検出されたが、意図的な変更である

原因：クラスターのスキーマがリポジトリとは別に更新されました（例：Schema Registry の UI を使用）。 解決策：ドリフトを報告し、信頼できる情報源としてクラスターに合わせてリポジトリを同期するよう推奨します。

execute_sql でデータをサンプリングできない

原因：トピックが空である、権限が制限されている、またはトピックでサポートされていない形式が使用されています。 解決策：レポートに制限事項を記載してください。スキーマ情報の代替手段として get_topic_metadata を使用します。

出力形式

## Schema Review Report

### Environment: {name}

### Breaking Changes (must fix before merge)
- [schema-file] Description of the breaking change
  Affected topics: {list}
  Migration: {guidance}

### Compatibility Warnings
- [schema-file] Description of the issue
  Recommendation: How to fix it

### Schema Quality
- [schema-file:field] Description of the quality issue
  Recommendation: How to improve it

### Schema Drift
- [topic-name] Schema in repo differs from registered schema
  Repo version: {summary} | Cluster version: {summary}

### Summary
- X breaking changes found
- Y compatibility warnings found
- Z quality issues found
- Schema files scanned: N
- Topics with drift: M