review-integration

review-integration

Elastic インテグレーションを懐疑的かつ徹底的に品質レビューします。役割は対応可能な問題のみを見つけることです。コードを褒めたり、準拠していると確認したりしてはいけません。ある領域に問題がない場合は、その旨を1行で述べて次に進みます。

単独利用とホスト経由での利用

単独の /review-integration レビューでは、以下のワークフローと参考ガイダンスに従ってください。review-profiles.json は読み込んだり解釈したりしないでください。これは任意のホスト連携用メタデータであり、レビューの指示ではありません。単独レビューにこのファイルは必要なく、ファイルが存在していてもエージェントがホストモードになることはありません。

integration-review-bot などの互換性のあるホストは、ガイダンスを事前に読み込むためにマニフェストを参照する場合があります。ホストはプロファイルと折りたたみ方を選択し、レビューの対象範囲と出力要件を提示します。レビューを行うエージェントがマニフェストを読む必要はありません。

スキルの権威

ドメインスキルとその参照ファイルで定義されているルールとパターンが、唯一の正しい情報源です。elastic/integrations にある既存のインテグレーションには、現在の標準より前の古いパターンが含まれている場合があります。必ず、他のインテグレーションで見つかったパターンではなく、スキルに照らしてレビュー対象のインテグレーションを評価してください。

使用する場合

• インテグレーションパッケージの品質をレビューする場合（パッケージ全体、特定のストリーム、特定のドメインなど、あらゆる範囲）
• 任意のエージェント環境（Cursor、Claude Code、Codex など）でユーザーから直接呼び出された場合
• 委任レビューのために maintain-integration の review-workflow から参照された場合

使用しない場合

• インテグレーションを構築する場合（create-integration、cel-programs、ingest-pipelines などを使用してください）
• 修正や改善を行う場合（maintain-integration を使用してください）
• ベンダーを調査する場合（research-integration を使用してください）

このスキルは読み取り専用です。指摘事項を出力します。ファイルは編集しません。

---

新規インテグレーションと既存インテグレーションのレビュー

バージョンやパターンの選択を評価する前に、 共有パッケージの評価基準を読んでください。 以下で選択するドメインの参照資料にある、新規／既存に関する詳細な調整を適用してください。ルールは重複するエントリーポイントの表ではなく、参照資料にまとめられています。

---

ステップ 1：対象範囲を特定する

レビュー対象を特定します。

• ローカルパッケージ：ユーザーがパッケージディレクトリのパスを指定します。ルートの manifest.yml を読み、すべてのデータストリームと入力タイプを一覧表示します。
• 変更ファイル：ユーザーが変更ファイルの一覧（PR やブランチ比較など）を提示します。各ファイルをドメインに分類します。
• ユーザーによる説明：ユーザーがレビュー内容を説明します。関連するパッケージとファイルを特定します。

ユーザーが最初の要件、調査概要、またはタスクの説明を提示した場合は、「要件との一致」チェックで確認すべき内容として記録します。

重大度を適切に調整するため、対象が新規パッケージか既存パッケージかを判断します（上記の「新規インテグレーションと既存インテグレーションのレビュー」を参照）。

ステップ 2：ファイルをドメイン別に分類する

対象範囲内のすべてのファイルを、次のドメインに分類します。

ファイルパターン	ドメイン
elasticsearch/ingest_pipeline/*.yml	パイプライン
fields/*.yml	フィールド
agent/stream/*.yml.hbs	入力
manifest.yml（ルートまたはデータストリーム）	マニフェスト
_dev/build/build.yml	ビルド
changelog.yml	変更履歴
routing_rules.yml	パイプライン
_dev/test/pipeline/*	テスト
_dev/test/system/*	テスト
kibana/**/*.json	ダッシュボード
_dev/build/docs/README.md	ドキュメント
elasticsearch/transform/**	トランスフォーム
*-expected.json、sample_event*.json	生成物（レビュー対象外。CI 管理）

生成された期待値／サンプルの生出力は、相互参照や別のツール経由であっても、決して読み込まないでください。変更ファイルがすべて対象外の場合は、NOT_REVIEWED と報告して終了してください。生成物を調べたり、承認を出したりしてはいけません。

ステップ 3：ドメインスキルとレビュー用チェックリストを読み込む

検出されたドメインに必要なものだけを読み込みます。レビューごとにすべてのスキルを読み込まないでください。

ドメイン	読み込むスキル	読み込むレビュー用チェックリスト	レビューの評価基準
パイプライン	ingest-pipelines SKILL.md	checklists/pipeline-review-checklist.md	references/domains/pipeline/rubric.md + references/domains/pipeline/conflict-resolutions.md
フィールド	ecs-field-mappings SKILL.md	checklists/field-review-checklist.md	references/domains/fields/rubric.md
入力（CEL）	cel-programs SKILL.md	checklists/cel-review-checklist.md	references/domains/input/rubric.md + references/domains/input/conflict-resolutions.md
入力（HTTPJSON）	input-configurations SKILL.md -> references/httpjson-guide.md	checklists/httpjson-review-checklist.md	references/domains/input/rubric.md（CEL 専用の項目は適用されません）
入力（entity-analytics）	このスキルの references/entity-analytics-provider-matrix.md	checklists/entity-analytics-review-checklist.md	references/domains/input/rubric.md（CEL 専用の項目は適用されません）
入力（その他のタイプ）	input-configurations SKILL.md -> 対応するタイプのガイド	input-configurations/references/common-input-patterns.md	references/domains/input/rubric.md（CEL 専用の項目は適用されません）
マニフェスト + 変更履歴	package-spec SKILL.md	package-spec/references/manifest-rules.md	references/domains/structure/rubric.md
テスト	integration-testing SKILL.md -> 関連するテストのリファレンス	--	references/domains/tests/rubric.md
ダッシュボード	dashboard-review SKILL.md + dashboard-guidelines SKILL.md	dashboard-review/references/review-procedure.md	references/domains/dashboard/rubric.md
ビルド	ecs-field-mappings SKILL.md	（ECS バージョンの固定ルール）	references/domains/fields/rubric.md + references/domains/structure/rubric.md
変換	このスキルの references/transform-guide.md	（レビュー用チェックリストを含む）	references/domains/transform/rubric.md
ドキュメント	（以下のインラインチェックリスト）	--	references/domains/structure/rubric.md

ステップ 3b：常に読み込むスキル

どのドメインが含まれているかにかかわらず、すべてのレビューでこれらを読み込みます。

スキル	理由
elastic-package-cli SKILL.md	検証コマンド（format、lint、check、test）とトラブルシューティング
create-integration -> references/package-layout.md	パッケージのトポロジー、必須ファイル、ディレクトリ構造、命名上の制約
anonymize-logs SKILL.md	データの匿名化チェックにおけるプレースホルダーの規約（RFC 5737 の IP アドレス、example.com ドメイン、合成 UUID）

ステップ 4：レビュー固有のリファレンスを読み込む

これらのリファレンスは、このスキルの references/ ディレクトリにあり、レビュー専用の手順を説明しています。

条件	読み込むリファレンス
常に	references/domains/severity-core.md -- 共通の重要度と新規／既存パッケージの評価基準
常に	references/domains/conflicts-core.md -- 共通のレビュー例外
常に	references/review-calibration.md -- ソースの証拠、任意のダイジェスト、報告上の制限
常に	references/review-output-template.md -- 出力形式のテンプレートとレンダリング規則
常に	references/repo-conventions.md -- elastic／integrations リポジトリの慣例と自動化（作成日あり。検証日ヘッダーを確認してください）
対象が2つ以上のドメインにわたる	references/consistency-rules.md -- ドメイン間の整合性（pipeline-fields-manifest-tests の連携）
CEL 入力ファイルが対象	references/version-check-procedure.md + references/beats-mito-version-matrix.md + references/config-options-by-version.md + references/extensions-per-version.md
CEL 入力ファイルが対象	references/cel-validator-procedure.md -- celfmt の正規性、型変換の監査、エラー形式の検証
API ドキュメントを参照できる CEL または HTTPJSON	references/api-conformance-methodology.md -- 実装とベンダーのドキュメントを相互参照
entity-analytics 入力が対象	references/entity-analytics-provider-matrix.md + checklists/entity-analytics-review-checklist.md -- プロバイダーとの同期／マーカー／削除の意味とパッケージのチェックリスト
入力テンプレートが対象	references/input-review-orchestration.md -- 入力タイプ別のレビュー深度の振り分け
Federated Identity／Cloud Connectors が対象	input-configurations/references/federated-identity-aws.md -- 入力の分類、iac_template_url、auth.aws／use_cloud_connectors、入力のゲーティング
PR タイトル／説明を評価する（初回レビュー）	references/commit-message-conventions.md -- PR タイトルの評価基準となる、スクワッシュマージのコミットメッセージ規則
クラウドセキュリティ／CDR 統合	ecs-field-mappings/references/cdr-field-requirements.md + ingest-pipelines/references/cdr-pipeline-requirements.md + references/cdr-transform-requirements.md
Entity／entity-inventory データストリーム	entity-mappings/references/entity-field-catalog.md + entity-mappings/references/entity-pipeline-patterns.md

CDR の検出： ルートの manifest.yml のカテゴリを確認してください。cloudsecurity_cdr が含まれている場合、その統合は CDR であり、CDR リファレンスを3つすべて読み込む必要があります。カテゴリに cloudsecurity_cdr が明示的に含まれていない限り、EDR／XDR 統合（crowdstrike、sentinel_one、trend_micro）には CDR ルールを適用しないでください。

Entity データストリームの検出： 対象の各データストリームに、entity-mappings/references/entity-datastream-classification.md のレビュー時ルール（最初に該当したものを採用）を適用してください。

1. 確定： いずれかのパイプラインで event.kind: asset が設定されている。
2. 確定： いずれかの manifest.yml で、データストリームまたはポリシーテンプレートの入力に input: entity-analytics が記述されている。
3. 強い兆候： いずれかの fields/*.yml で、*entity.attributes.*、*entity.lifecycle.*、*entity.relationships.*、entity.type、または entity.id に一致するフィールドが宣言されている。
4. ヒューリスティック： ストリーム名が Entity 用語のいずれか（users、members、devices、hosts、assets、accounts、identities、apps、groups、service_accounts、roles、resources）であり、かつ event.action も event.outcome も設定されておらず、手書きの入力フィクスチャにも収集時刻とは異なるレコード単位のイベントタイムスタンプがない。許可されたソースまたは提供されたダイジェストから判断できない場合、このヒューリスティックは未確定のままにしてください。解決のために生成済みの出力を調べてはいけません。
5. 除外条件（3と4に優先）： ルートの manifest.yml のカテゴリに cloudsecurity_cdr が含まれ、かつストリームで result.evaluation または vulnerability.* が設定されている。これは CDR の状態であり、Entity アセットではありません。CDR リファレンスのみを読み込んでください。 いずれかのストリームがチェック1～4に該当した場合（除外条件によって無効化されない限り）、そのストリームについて Entity リファレンスを両方読み込んでください。 フェデレーション ID の検出： 次のいずれかに該当する場合は、input-configurations/references/federated-identity-aws.md を読み込みます。
6. ルートの manifest.yml に、identity_federation という名前の var_groups オプションがある。
7. provider_permissions エントリーのいずれかに provider: aws がある。
8. agent/stream/*.yml.hbs のいずれかに use_cloud_connectors または supports_identity_federation が含まれている。
9. ルートの manifest.yml の conditions.kibana.version が ^9.6.0（またはそれ以上）で、さらに入力が aws-cloudwatch、aws/metrics、cel、または AWS 認証情報変数を含む httpjson のいずれかである。この場合はフェデレーションの対象となる可能性があるものとして扱い、リストの残りの項目も確認します。

次に、マニフェストのチェックリスト、CEL および HTTPJSON のレビューチェックリスト、該当する input-configurations ガイドにあるフェデレーション項目を適用します（CloudWatch ストリームテンプレート — トップレベルの use_cloud_connectors を使用し、auth.aws: は使用しません。S3 — deployment_modes: ["default"] を固定します）。専用ガイドのないフェデレーション対象タイプ（例：aws/metrics）にも、federated-identity-aws.md を適用します。フラットなアクセスキーだけを設定する auth.aws 単独をフェデレーションとして扱ってはいけません。また、external_id や hide_in_var_group_options がないことを指摘してはいけません。これらはどちらも提供済みパッケージから削除されています。

---

Step 5: 自動検証を実行する

ディスク上のパッケージにアクセスできる場合は、次を実行します。

cd packages/<package_name>

elastic-package format --fail-fast
elastic-package lint
elastic-package check

生成出力の検証とスナップショットの最新性確認は、CI の elastic-package に任せます。レビュー作業として出力を再生成したり、スナップショットを比較したりしないでください。代わりに、手書きのテストシナリオと、それを生成するソースを確認します。利用可能な CI の結果は参考情報であり、シナリオがすべて網羅されている証拠でも、生成出力を調べる指示でもありません。想定出力やサンプル出力との不一致、古いスナップショットではなく、関連するソースや設定の不具合を報告します。

Step 6: 確認して指摘事項をまとめる

対象範囲内の通常のソースファイルとテストファイルについて：

1. 問題と修正方法を確認できるだけの周辺ソースを読み、必要に応じてファイル全体を読みます
2. 差分をレビューする場合は、変更内容を把握するために差分の該当箇所を読みます
3. ドメインスキルとレビューチェックリストから、該当する項目を適用します
4. 見つかった問題ごとに、次を記録します。
   • severity：critical、high、medium、low のいずれか
   • domain：以下のドメインタグのいずれか
   • title：短い説明（10 語以内）
   • path：リポジトリルートからの相対ファイルパス
   • line：ファイル内の行番号（不明な場合は 1）
   • description：問題点と、それが重要な理由
   • recommendation：修正方法。修正後の YAML/CEL/JSON を示すコードブロックを含めます

テストの基準にある生成出力の除外ルールに従います。厳密なシナリオの確認に必要で、コンパクトなテストダイジェストがすでに提供されている場合に限り、それを読んでもかまいません。ダイジェストの作成や検証のために、生の生成出力を読んではいけません。要約がないことは、検証に合格した証拠にはならず、除外対象の成果物を再度確認する理由にもなりません。

ファイル間のチェック

各ファイルの確認後、ドメイン間の整合性を確認します（まだ読み込んでいない場合は references/consistency-rules.md を読み込みます）。

• パイプラインプロセッサーで設定されたフィールドは、動的マッピングで機能する標準 ECS キーワード／日付型でない限り、fields/ecs.yml で宣言されている必要があります
• build.yml の ECS バージョンは、パイプラインで設定される ecs.version と一致している必要があります
• マニフェスト変数はストリームテンプレートで参照されている必要があります。入力タイプに対して、データストリームのマニフェスト streams[].vars、ルートマニフェスト policy_templates[].vars、またはルートマニフェスト policy_templates[].inputs[].vars のいずれかに記載されていれば、テンプレート変数は宣言済みとみなします（{{#each tags as |tag|}} などの Handlebars ブロックパラメーターは変数ではありません）
• データストリームのマニフェストでルートマニフェストのフィールド（format_version、conditions）を重複して定義してはいけません
• 手書きのテスト設定と入力フィクスチャでは、関連するパイプラインの分岐と失敗シナリオを検証する必要があります。網羅性や最新性の確認に、生成された期待出力やサンプル出力を使用してはいけません。

ファイル間の参照に必要な場合は、変更されていないファイルもワークスペースから読みます。

出力形式

現在の作業ディレクトリにある tmp/integration-review.md にレビューを記述してください。tmp/ ディレクトリが存在しない場合は作成してください。また、ファイルを開かなくてもユーザーが指摘内容を直接確認できるよう、レビュー全文を回答にも記載してください。

正確な出力形式とレンダリング規則については、references/review-output-template.md を読んでください。このテンプレートでは、ドメインごとのセクション、指摘ごとの形式（タイトル、重大度、場所、問題、コードブロックを含む推奨事項）、提案、サマリーテーブル、判定が定義されています。ファイルと回答の両方で同じ形式を使用してください。

判定ルール

• 重大または高の指摘がある場合 → NEEDS_CHANGES
• 中または低の指摘のみの場合 → APPROVED_WITH_SUGGESTIONS
• レビュー対象として許可されたソースを確認した結果、指摘がない場合 → APPROVED
• 変更されたものが除外対象の生成物のみの場合 → NOT_REVIEWED

ドメインタグ

各指摘には、次のドメインタグを1つだけ付けてください。

タグ	対象
domain:manifest	ルートまたはデータストリームのマニフェストフィールド、format_version、conditions、categories、owner、ポリシーテンプレート
domain:changelog	Changelog のスキーマ、エントリー、バージョン要件、リンク、観測可能な互換性または動作の変更。構造の評価基準と共通の競合解決ルールを適用
domain:build	_dev/build/build.yml の不足または古さ、ドキュメントテンプレートの問題
domain:pipeline	Ingest パイプラインの正確性、JSE00001、on_failure、タグ、パイプライン内の ECS 分類
domain:input	エージェントストリームテンプレートの問題。CEL、HTTPJSON、AWS S3、TCP など、すべての入力タイプが対象
domain:fields	フィールド定義、型、重複、geo のネスト、ECS マッピング戦略
domain:tests	手書きのパイプライン入力フィクスチャー、システムテスト設定、test-common-config.yml、シナリオの網羅状況。生成された expected/sample 出力は対象外
domain:dashboard	パッケージルートにある Kibana ダッシュボード JSON（kibana/）、TSVB、データセットフィルター、by-reference パネル
domain:transform	パッケージルートにある transform 設定（elasticsearch/transform/）、同期、フィールド定義、CDR
domain:docs	README の内容、プレースホルダーテキスト、タイトルと説明の品質
domain:anonymization	コミット済みファイル内の実データ、合成ではない IP アドレス／ホスト名／認証情報
domain:consistency	ドメイン間の問題：パイプラインとフィールドの不一致、build.yml とパイプラインの ECS 不一致、未使用のマニフェスト変数

重大度レベル

重大度の共通定義と、Step 3 の該当するドメイン別の評価基準／競合解決に関するリファレンスを使用してください。同じリファレンスに加えて、互換性インデックスを読み込まないでください。

重要なルール

• 指摘に肯定的な所見を含めないでください。
• すべての指摘にファイルパスと行番号を記載してください。
• すべての推奨事項に、修正後のコードを示すコードブロックを含めてください。
• 重複は統合してください。同じ問題が複数のファイルで見つかった場合は、まとめてください。
• ドメインをレビューして問題がなかった場合は、次の1行を記載してください：「✅ レビュー済み — 対応が必要な問題は見つかりませんでした。」
• 対象外のドメインは記載しないでください。

レビューの規律

• すべての指摘は、レビュー対象のコードにある具体的かつ現在発生しているバグを、根拠とともに示す必要があります。仮定上の内容や「API が変更された場合」または「将来のシナリオでは」といった説明に依存する指摘には根拠がないため、削除してください。
• validation.yml の除外項目は指摘しないでください（パッケージ作成者が管理するものであり、レビュー対象ではありません）。
• ベンダー側で処理済みのフィールドに対するプロセッサーの追加を提案しないでください（例：ベンダー側で既にマスキングされているパスワードに対する redact の提案）。
• コード内で実際に露出している根拠がない、仮定上のセキュリティリスクを指摘しないでください。

参照ファイル

ファイル	読み込み条件	内容
references/reviewer-subagent-guidance.md	レビュアーサブエージェント自身が読み込みます（オーケストレーターはパスのみを渡し、内容は埋め込みません）	対象範囲、スキルの読み込み順序、読み取り専用の運用ルール、課題ごとの形式チェックリスト、判定ルール、オーケストレーターからディスパッチされたレビュアー向けの報告仕様
references/review-output-template.md	常時	出力形式のテンプレート、レンダリングルール、重大度の対応付け
references/domains/severity-core.md	常時	共有される重大度とパッケージ経過期間の調整基準
references/domains/conflicts-core.md	常時	共有されるレビュー例外
references/review-calibration.md	常時	根拠となる情報、任意のコンテキスト、報告上の制限
references/consistency-rules.md	2 つ以上のドメイン	ドメイン間の整合性ルール（パイプライン・フィールド・マニフェスト・テスト）
references/version-check-procedure.md	CEL が対象範囲内	体系的なバージョン検証の 5 段階手順
references/beats-mito-version-matrix.md	CEL が対象範囲内	beats と mito の全バージョン対応表（160 件以上）
references/config-options-by-version.md	CEL が対象範囲内	beats のバージョンごとの CEL 設定オプションの導入状況
references/extensions-per-version.md	CEL が対象範囲内	beats のバージョンごとに登録された mito 拡張機能
references/cel-validator-procedure.md	CEL が対象範囲内	celfmt の権威性、型変換の監査、エラー形式の検証
references/api-conformance-methodology.md	CEL/HTTPJSON および API ドキュメントが対象範囲内	実装とベンダーの API ドキュメントの相互参照
references/input-review-orchestration.md	いずれかの入力テンプレート	入力タイプに応じたレビューの深度の割り当て
input-configurations/references/federated-identity-aws.md	フェデレーション ID の検出時（ステップ 4 を参照）	AWS Cloud Connectors の手順：iac_template_url、use_cloud_connectors、入力のゲーティング
references/transform-guide.md	Transform が対象範囲内	Transform のタイプ、設定、フィールド、同期、レビューチェックリスト
references/cdr-transform-requirements.md	CDR transforms	最新の CDR transform 要件、宛先の命名、キー、保持
references/repo-conventions.md	常時	elastic/integrations リポジトリの規約：group フィールド、Elastic Managed の名称変更と agentless の release、owner.type、changelog/backport の自動化、バージョン制約の適切な運用（日付付きの参照資料）
references/entity-analytics-provider-matrix.md	entity-analytics が対象範囲内	プロバイダー機能マトリックス（azure-ad、okta、activedirectory、jamf）、従来方式と最小状態方式の同期・マーカー・削除のセマンティクス
checklists/pipeline-review-checklist.md	Pipeline が対象範囲内	重大度ラベル付きパイプラインレビューチェックリスト
checklists/field-review-checklist.md	Fields が対象範囲内	重大度ラベル付きフィールドマッピングレビューチェックリスト
checklists/cel-review-checklist.md	CEL が対象範囲内	重大度ラベル付き CEL レビューチェックリスト
checklists/httpjson-review-checklist.md	HTTPJSON が対象範囲内	重大度ラベル付き HTTPJSON レビューチェックリスト
entity-mappings/references/entity-field-catalog.md	エンティティデータストリームが対象範囲内（エンティティ検出ルールを参照）	ECS の対応状況マトリックス、Must Have / Should Have フィールドの表、区別ガイド、フィールド定義の例、エンティティフィールドレビューチェックリスト
entity-mappings/references/entity-pipeline-patterns.md	エンティティデータストリームが対象範囲内（エンティティ検出ルールを参照）	分類プロセッサー、entity.id のミラーリング、ブール値の強制変換、関係オブジェクトのパターン、アンチパターン、エンティティパイプラインレビューチェックリスト
checklists/entity-analytics-review-checklist.md	entity-analytics が対象範囲内	重大度ラベル付き entity-analytics パッケージレビューチェックリスト

共有ドメインリファレンス

ステップ 3 の表は、このスキルのドメイン振り分けマップです。ドメイン別の評価基準と競合に関する参照情報は、ホスト型レビュアーと共有される正式な情報源です。レビューと、必要なドメイン横断チェックに関連する参照情報のみを読み込んでください。references/severity-rubric.md と references/conflict-resolutions.md は互換性インデックスであり、ルールの複製ではありません。

review-profiles.json は引き続き任意のホストメタデータです。スタンドアロンレビュアーは、ホストのプロファイルや折りたたみ設定ではなく、この Markdown ワークフローに従ってください。