mcpField
L
looker-architect

looker-architect

github.com/looker-open-sourceデータ・データベース4387 回インストール2 週間前に更新
リポジトリ

looker-architect について

looker-architect は、LookML プロジェクトの構築、リファクタリング、検証、監査に使う開発スキルです。新規・既存プロジェクト向けに、モジュール構成、モデリング基準、テスト、実行時チェックを定めています。

主な機能

  1. 01新規・既存プロジェクトの作業フロー
  2. 02raw ビューと refined ビューの分離
  3. 03モジュール型 Explore と自動テスト
  4. 04LookML 検証と SQL 実行時監査
  5. 05ダッシュボードと指標のモデリング基準

活用シーン

  1. 01新しい LookML プロジェクトのひな型作成
  2. 02既存プロジェクトのビューやダッシュボードのリファクタリング
  3. 03LookML の検証とクエリエラーの調査

MCP 対応

Looker MCP を使ったプロジェクトファイルの確認、ヘルス検証、ダッシュボードやクエリの実行、データベース列の確認を説明しています。プロジェクトの監査と検証には looker-cli も選択肢として挙げられています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/looker-open-source/looker-skills --skill looker-architect

インストール後、Claude Code で/looker-architectを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

looker_scaffold.py
README.md
examples/ecommerce_block/
ecommerce.model.lkml
manifest.lkml
examples/ecommerce_block/dashboards/
ecommerce_overview.dashboard.lookml
examples/ecommerce_block/explores/
orders.explore.lkml
examples/ecommerce_block/tests/
orders.test.lkml
examples/ecommerce_block/views/raw/
orders.view.lkml
users.view.lkml
examples/ecommerce_block/views/refined/
orders_rfn.view.lkml
users_rfn.view.lkml
references/
aggregate_awareness.md
consumption_guide.md
dashboard_standards.md
pop_engine.md
sql_runtime_debugging.md
templates.md
testing_suite.md
visual_drilling.md
templates/
lookml_linter.yml
lookml_validation.yml

詳細

Looker Architect

このマスター開発者スキルは、エンタープライズ品質の LookML プロジェクトの構築、リファクタリング、検証、監査のライフサイクルを管理します。Google 内部で公式 Looker Blocks の開発に使用されているアーキテクチャ標準、設計原則、ベストプラクティスに基づいて構築されており、開発者がブロック品質の分析アプリケーションを構築できるようにします。関心事の厳格な分離、パフォーマンス優先の設計、自動テスト、包括的なドキュメントを徹底します。

このスキルのもとで開発されるすべての LookML プロジェクトは、特定の方言やスキーマに依存せず、あらゆるデータベース接続と互換性がなければなりません。LookML、Google Cloud のベストプラクティス、エンタープライズデータガバナンスのガイドラインにおける最高水準を厳守します。

1. 標準プロジェクト構成

すべての LookML プロジェクトは、保守性を確保し、堅牢なバージョン管理を可能にし、コンパイルの肥大化を防ぐため、このクリーンでモジュール化されたディレクトリ構成に必ず従わなければなりません。

├── views/
│   ├── raw/                 # Raw views mapping 1:1 to physical database tables
│   │   ├── [view_name].view.lkml
│   └── refined/             # Refined views (extends/refines raw views with business logic)
│       └── [view_name]_rfn.view.lkml
├── explores/                # Modular Explore files (one explore per file: *.explore.lkml)
│   └── [explore_name].explore.lkml
├── tests/                   # LookML test suites (one suite per explore: *.test.lkml)
│   └── [explore_name].test.lkml
├── dashboards/              # LookML dashboard files (*.dashboard.lookml)
│   └── [dashboard_name].dashboard.lookml
├── [project_name].model.lkml # Clean model file (connection constant, caching, and includes only)
├── manifest.lkml            # Defines constants (connection, dataset, and visualization configs)
├── README.md                # End-user documentation (installation, PDT config, KPIs)
├── LICENSE                  # Apache 2.0 or standard open-source license
└── CONTRIBUTING.md          # Guidelines for contributing to the project

2. 動作モード（グリーンフィールドとブラウンフィールド）

Looker Architect スキルは、コードベースの状態に応じて、2 つの異なるモードで動作します。どちらのモードでも、エージェントは必須 PRD 監査チェックリストと完全網羅ルールを必ず遵守しなければなりません。

重要

必須 PRD 監査チェックリストと完全網羅ルール：コードを 1 行でも書く前に、エージェントは提供されたすべての外部ドキュメント URL（Google Docs の PRD、データベーススキーマの仕様、データベース方言のマニュアルなど）を必ず読み、分析しなければなりません。エージェントは、必要なダッシュボード、タブ、タイル、指標、ビューをすべて列挙した具体的な完全性チェックリストを作成し、記述しなければなりません。

さらに、プロジェクト用に作成するすべてのビュー、メジャー、ダッシュボードタイルの 100% に、高度なモデリング標準（カスタムビジュアルドリル、値の書式設定、期間比較）を実装しなければなりません。これらの標準を一部にのみ適用すること（例：プライマリビューだけに適用し、セカンダリビューを未書式設定のボイラープレートのままにすること）や、近道を取り入れることは固く禁止されています。

モード A：グリーンフィールド（新規プロジェクトをゼロから構築）

まったく新しいプロジェクトを開始する場合は、このモードを使用します。以下の 8 ステップの開発ワークフローに従ってください。

  1. 非対話型の ./looker_scaffold.py スクリプトを使用してディレクトリ構成を初期化します（プロジェクト名が Looker インスタンス内の対象プロジェクト名と一致するようにします）。
  2. スキーマの詳細を取り込み、raw テーブルを views/raw/ にマッピングし、ビジネスロジックを views/refined/ に重ねます。
  3. モジュール化された Explore を設定し、主キーの一意性を確認するユニットテストを作成して、ネイティブのタブ付きダッシュボードを構築します。
  4. すべての Key KPI スコアカードに 2 メジャーの PoP 比較パターンが実装されていること、およびすべての主要メジャーにマニフェスト定数を使用した高度なビジュアルドリルリンクがあることを確認します。
モード B：ブラウンフィールド（既存プロジェクトの監査、リファクタリング、アップグレード）

既存の LookML プロジェクトをレビューまたは改善する場合は、このモードを使用します。エージェントは、以下の監査およびリファクタリングのパイプラインを必ず実行する必要があります。

  1. 既存の構造を分析する：looker-cli または Looker MCP（get_project_files、get_project_file）を使用して、アクティブな LookML ファイルを調査します。
  2. 逸脱を検出する：以下の標準違反を特定します。
    • モデルファイルにデータベースのカラムや SQL 計算式が直接記述されている（explore はモジュール化し、explores/ 内に配置する必要があります）。
    • raw/refined フォルダーが分離されていない（例：raw カラムとメジャーが単一のビュー ファイルに混在している）。
    • 機能的な順序になっていない（例：ディメンションより上にメジャーが定義されている）。
    • ネイティブ Looker の type パラメーターではなく、メジャーで SQL 集計関数を使用している。
    • ダッシュボードで、ネイティブの tabs ではなく、古い HTML ナビゲーションメニューを使用している。
    • 主キーを検証するユニットテストがない。
    • 主要なカウントおよび指標メジャーに高度なビジュアル ドリルリンクがない。
    • 主要 KPI の single_value ダッシュボードタイルに期間比較（PoP）のパターンがない。
  3. 必要な箇所のみをリファクタリングする：専用のサブエージェントを起動し、ファイルをその場でリファクタリングします。
    • 混在しているビューを views/raw/（直接対応する 1:1 のカラム）と views/refined/（${field_name} 経由でメタデータを継承する、メジャーを含む拡張ビュー）に分割します。
    • 順序のルール（キー ➔ ディメンション ➔ メジャー ➔ フィルター ➔ セット）に従ってフィールドを並べ替えます。
    • SQL 集計関数をネイティブの Looker タイプに置き換え、安全な除算のために NULLIF を追加します。
    • マニフェスト定数と空のドリルフィールドを使用して、すべての主要メジャーに高度なビジュアル ドリルリンク（例：トレンドチャート、ドーナツチャート、グリッド形式の詳細テーブル）を追加します。
    • HTML ダッシュボードナビゲーションメニューをネイティブの Looker タブ付きレイアウト（tabs: および tab_name:）に変換し、タブごとにグリッド座標を row: 0, col: 0 にリセットします。
    • single_value ダッシュボードタイルを、pop_*_current と pop_*_change の両方のメジャーをクエリし、フィルターを explore の pop_date_filter にマッピングする、2 メジャーの PoP 比較パターンに変換します。
  4. 検証：サーバー側の検証（looker-cli project validate または MCP の health_analyze）を実行し、リファクタリングしたプロジェクトが完全にコンパイルされ、構文エラーがゼロであることを確認します。
  5. 実行時 SQL 実行の監査とスキーマの調整：サーバー側のコンパイルで確認できるのは LookML の構文のみで、データベースとの互換性は確認できません。エージェントは、実行時に発生するクエリのクラッシュを監査して修復するため、自己修復 SQL ループを開始する必要があります。専用マニュアル references/sql_runtime_debugging.md に記載された、完全なデバッグ手順、ループのプロトコル、方言固有の修正方法を参照してください。
    • クエリを抽出して実行する：LookML ダッシュボードの各タイルについて、Looker MCP の run_dashboard または query ツールを使用して、基盤となる SQL クエリを生成し、対象データベースに対して実行します。
    • 実行時のクラッシュを捕捉する：gRPC の Name query_text not found や SQL の構文／型変換エラーなど、実行時に発生したデータベースエラーを捕捉します。
    • 調整して修復する：MCP の get_connection_table_columns を使用してデータベースのスキーマと照合し、LookML ビューを必要な箇所のみ編集して正しいカラムにマッピングし、SQL のキャストを対象の方言に合わせて調整します。その後、クエリが HTTP 200（データの取得成功）を返すまで再検証します。

3. コア開発ワークフロー

エンタープライズ LookML プロジェクトの構築は、厳格な 8 ステップのライフサイクルに従います。

  1. コンテキストの取り込み：ユーザーのデータウェアハウスから、ソースデータベースのスキーマ、テーブルのリレーションシップ、取り込みレベル（スナップショット、リアルタイム、トランザクションログ）を分析します。
  2. ヒアリング：ユーザーのビジネス目標、主要な KPI、フィルタリング要件、主な対象者（経営層向けスコアカードか、アドホック分析を行うアナリストか）について、的を絞った質問をします。
  3. インスタンスの確認（Looker MCP と CLI）：
    • Looker インスタンスに接続し、セッションを開発者モードに切り替えます。 
      looker-cli session login --oauth --host <your-looker-domain.com>
looker-cli session update dev
    • 既存のビュー、エクスプロア、接続を調べ、新しいプロジェクトを稼働中のインスタンスアーキテクチャに合わせます。
  4. スキャフォールディングとボイラープレートの生成：
    • ローカルの Python ユーティリティ looker_scaffold.py を使用して、標準的なディレクトリ構造、パラメーター化された manifest.lkml、クリーンな .model.lkml、プライマリキーを含む raw ビュー、および機能的な順序付けヘッダーがあらかじめ設定された refined ビューを自動生成します。
  5. 実装とダッシュボードの変換：
    • LookML コードを refined ビューとエクスプロアに記述します。
    • 高度な機能の実装は、専門のリファレンスに委任します。
      • 期間比較エンジン：pop_engine.md（方言に依存しない単一エクスプロアのパターン）を参照してください。
      • ビジュアルドリル：visual_drilling.md（ドリルパスとビジュアライゼーションリンク）を参照してください。
      • 集計認識：aggregate_awareness.md（キャッシュとデータベースのロールアップ）を参照してください。
    • ユーザーが Looker ブラウザーでビジュアルダッシュボード（UDD）を設計した場合は、エクスポートして、dashboards/ ディレクトリ内のバージョン管理された LookML ダッシュボードに変換します。 
      looker-cli api dashboard dashboard_lookml <dashboard_id> > dashboards/<dashboard_name>.dashboard.lookml
  6. テストとサーバー検証：
    • プライマリキーとビジネス計算を検証する自動エクスプロアテストを tests/ に作成します。testing_suite.md を参照してください。
    • 必ず Looker サーバーコンパイラーで LookML を検証し、コミット前にエラーがないことを確認します。 
      looker-cli project validate <project_name>
  7. ドキュメント：インストール手順、PDT の再構築頻度、KPI の定義を記載した公開用 README.md ファイルを生成します。
  8. デプロイ：GitHub にコードをプッシュし（gh 認証情報ヘルパーで完全に認証）、main にマージして、本番環境へのデプロイを実行します。 
    looker-cli project deploy <project_name>

4. LookML モデリング規約（重要なルール）

ルール 1：接続とデータセット定数の一元管理

モデルファイルやビューファイルに接続名やデータセット名をハードコードしないでください。常に manifest.lkml で override_optional エクスポート設定を使用してパラメーター化し、ブロックのインストール時やデプロイ時にユーザーが上書きできるようにします。

manifest.lkml：

project_name: "my_lookml_project"

constant: CONNECTION_NAME {
  value: "my_connection"
  export: override_optional
}

constant: DATASET_NAME {
  value: "my_dataset"
  export: override_optional
}

views/raw/users.view.lkml：

view: users {
  # References the dataset constant
  sql_table_name: @{DATASET_NAME}.users ;;
  # ...
}

my_model.model.lkml：

# References the connection constant
connection: "@{CONNECTION_NAME}"
ルール 2：高度なドリルダウンと可視化定数ライブラリ（主要指標では必須）

大量の重複した JSON ブロックでビューのファイルが煩雑になるのを避けながら、プレミアムで高度にインタラクティブなユーザー体験を提供するには、manifest.lkml に一元管理された可視化ドリル定数を定義します。

  • 指標のドリルダウンは必須：洗練されたビューに含まれるすべての主要なメジャーとカウント指標（総売上、トランザクション数、エラー率など）には、マニフェスト定数を使用したカスタムの視覚的なドリルダウンリンクを少なくとも 2～3 個実装する必要があります（折れ線グラフ、分布を示すドーナツグラフ、スタイル設定された詳細グリッドテーブルなど）。
  • drill_fields の注意点：エージェントは、Looker フロントエンドで UI のハイパーリンクを有効にするため、メジャーに空の配列 drill_fields: [] を定義する必要があります。このパラメーターがないと、カスタムリンクは表示されません。
  • 動的な視覚的ドリルダウン：実装例と URL パラメーターの全容については、専用マニュアル references/visual_drilling.md を参照してください。

manifest.lkml：

constant: DRILL_COLUMN_VIZ {
  value: "{% assign vis_config = '{
    \"type\": \"looker_column\",
    \"x_axis_gridlines\": false,
    \"y_axis_gridlines\": true,
    \"show_view_names\": false,
    \"show_y_axis_labels\": true,
    \"show_y_axis_ticks\": true,
    \"show_x_axis_label\": true,
    \"show_x_axis_ticks\": true,
    \"stacking\": \"\",
    \"show_value_labels\": true
  }' %}"
}

views/refined/users_rfn.view.lkml：

view: +users {
  dimension: country {
    type: string
    sql: ${TABLE}.country ;;
    
    # References the visualization constant, passing dynamic filter values
    link: {
      label: "📊 Country Connection States (Bar)"
      url: "@{DRILL_COLUMN_VIZ}{{ link }}&fields=users.state,users.total_connections&f[users.country]={{ value | url_encode }}&sorts=users.total_connections+desc&limit=10&toggle=vis"
    }
  }
}
ルール 3：関心事の厳密な分離（Raw ビューと Refined ビュー）
  • Raw ビュー（views/raw/）：物理データベーステーブルに 1 対 1 で対応させます。列に直接マッピングする Raw ディメンションのみを含めます。メジャー、ラベル、複雑なビジネスロジックは定義してはいけません。主キーは、ファイル内で最初に定義するディメンションにする必要があります。
  • Refined ビュー（views/refined/）：リファインメント構文（view: +view_name）を使用してビジネスロジックを重ねます。メジャー、ラベル、説明、グループラベル、期間比較エンジン、カスタム計算を記述するのはこの場所です。
  • 理由：データベーススキーマが変更されても、Raw ビューのみを再生成すればよく、Refined ビューに残るビジネス計算を壊したり書き直したりせずに済みます。
ルール 4：ビューのフィールド順序（並び順ルール）

可読性を最大限に高めるため、Refined ビューファイル内のフィールドは、次の機能別の順序で上から下に並べる必要があります。

  1. キー：主キー（primary_key: yes）と外部キー。
  2. ディメンション：標準属性（名前、ステータス、カテゴリなど）。
  3. メジャー：集計指標（合計、平均、カウントなど）。
  4. フィルターとパラメーター：動的パラメーターを取得するユーザー入力フィールド。
  5. セット：ドリルダウンに使用する再利用可能なフィールドリスト。

内部の並び順：各カテゴリ内では、フィールドを**アルファベット順（A～Z）**に並べるか、グループラベル（group_label）ごとに論理的にまとめます。

ルール 5：置換演算子の継承（${field_name}）

メジャーまたは複合ディメンションを定義するときは、Raw SQL 列 ${TABLE}.field_name ではなく、LookML の置換演算子 ${field_name} を必ず使用します。

  • 正しい例： 
    dimension: sale_price {
  type: number
  sql: ${TABLE}.sale_price ;;
  description: "Unit price of the item sold."
  value_format_name: usd
}

measure: total_revenue {
  type: sum
  sql: ${sale_price} ;; # メタデータ（説明、書式、型）を継承
}
  • 誤った例： 
    measure: total_revenue {
  type: sum
  sql: ${TABLE}.sale_price ;; # LookML レイヤーを回避し、メタデータが失われる
}
  • 理由：LookML フィールド ${sale_price} を参照すると、メジャーはその書式、説明、メタデータをすべて継承します。データベースで列名が変わった場合も、ベースディメンションを一度更新するだけで済みます。
ルール 6：Looker ネイティブの集計（ファンアウトの防止）

集計関数を sql: パラメーターに直接記述するのではなく（例：type: number と sql: SUM(col) を使用する）、常に集計には Looker ネイティブの type パラメーター（例：type: sum、type: average、type: count）を使用してください。

  • 正しい例： 
    measure: average_benchmark {
  type: average
  sql: ${benchmark_dynamic} ;; # Looker はこれが平均であることをネイティブに認識します
}
  • 誤った例： 
    measure: average_benchmark {
  type: number
  sql: AVERAGE(${TABLE}.benchmark_dynamic) ;; # 集計エンジンを迂回します
}
  • 理由：SQL に集計を記述すると、1 対多のリレーションシップを持つテーブルを結合する際に、Looker のコンパイラーが 対称集計 を実行できなくなり、計算が不正確になったり、データのファンアウトが発生したりします。
ルール 7：命名規則とメジャーのサフィックス
  • すべての LookML オブジェクト（ビュー、エクスプロア、ディメンション、メジャー、セット）は snake_case（小文字とアンダースコア）で記述してください。
  • メジャーのサフィックス：明確さを保つため、集計には特定のサフィックスを使用してください。
    • Count および Distinct Count メジャーには _count または _total を使用します（例：user_count、active_users_total）。
    • Sum メジャーには _total または _amount を使用します（例：revenue_total、discount_amount）。
ルール 8：安全な数値計算、比率計算、必須の値の書式設定
  • 安全な除算：ゼロ除算エラーを防ぐため、除算計算は必ず保護してください。方言に適した安全な数値計算を使用します（例：BigQuery では SAFE_DIVIDE(num, den)、Snowflake／Redshift では num / NULLIF(den, 0)）。
  • 集計比率：比率は、最終的に集計された指標にのみ適用してください。比率を直接集計しないでください。
    • 正しい例： 
      measure: conversion_rate {
  type: number
  sql: 1.0 * ${orders_count} / NULLIF(${sessions_count}, 0) ;; # 先に集計し、その後で除算します
  value_format_name: percent_1
}
    • 誤った例： 
      measure: conversion_rate {
  type: average
  sql: ${TABLE}.conversion_rate ;; # 比率を集計するのは数学的に不正です
}
  • 必須の値の書式設定：書式設定されていない生の数値（例：ダッシュボードのビジュアライゼーションに 0.072826486327 と表示すること）は、非常にプロフェッショナルさに欠け、UI を煩雑にします。絞り込まれたビューにあるすべてのカウント、合計、平均、比率、サイズのメジャーには、読みやすく整った書式設定パラメーターを必ず定義してください。
    • パーセンテージと比率：value_format_name: percent_1（例：7.3%）または percent_2（例：7.28%）を使用します。
    • 標準的な平均値と小数：value_format_name: decimal_2（例：12.34）または decimal_1（例：12.3）を使用します。
    • 大きな整数：カンマ区切りを適用するには、value_format_name: decimal_0 または integer を使用します（例：1,234）。
    • 通貨：value_format_name: usd（例：$1,234.56）または usd_0（例：$1,234）を使用します。
    • カスタム単位（レイテンシ、サイズ、帯域幅）：引用符で囲んだカスタム書式文字列を付けて単位を整えて表示するには、value_format を使用します。
      • レイテンシ（秒）：value_format: "#,##0.00 \"s\""（0.0728 を 0.07 s と表示します）。
      • レイテンシ（ミリ秒）：value_format: "#,##0.0 \"ms\""（72.82 を 72.8 ms と表示します）。
      • データサイズ（GB）：value_format: "#,##0.00 \"GB\""（12.345 を 12.35 GB と表示します）。
      • 行数：value_format: "[>=1000000]#,##0.0,,\"M\";[>=1000]#,##0.0,\"K\";#,##0"（1500000 を 1.5M、2500 を 2.5K と表示します）。
Rule 9: 結合のプルーニングとExploreのガバナンス
  • Exploreで結合を一元管理する: SQLを使って物理テーブルを結合するSQL派生テーブルは作成しないでください。各テーブルを個別のビューで定義し、LookMLの結合パラメーターを使用してExploreで結合します。
    • 理由: これにより、結合のプルーニング（選択されたフィールドに必要なテーブルのみをLookerがクエリし、データベースのパフォーマンスが向上します）が可能になり、メンテナンスが簡素化され、対称集計によってファンアウトが防止されます。
  • ファイルごとにExploreを1つ定義する: 各Exploreはexplores/配下の個別のファイルで定義します（例：explores/orders.explore.lkml）。
  • モデルファイルをシンプルに保つ: .model.lkmlファイルに含められるのは、接続定数、キャッシュポリシー（データグループ）、Exploreとダッシュボードのインクルードのみです。モデルファイル自体にExploreを定義することはできません。
Rule 10: ネイティブのタブ付きダッシュボードとPoP KPI比較（HTMLナビゲーションの禁止）
  • 標準: 複雑で複数のトピックを扱うダッシュボードスイートでは、Lookerネイティブのタブ付きダッシュボード（tabsメタデータパラメーター）を使用して、すべての要素を1つの.dashboard.lookmlファイルにまとめます。
  • 禁止事項: ナビゲーションメニューとして機能するカスタムHTMLテキストタイルの作成は、厳格に禁止されています。必ずLookerネイティブのtabsパラメーターを使用してください。
  • 独立したグリッド座標: Lookerのタブ付きダッシュボードでは、各タブが**row: 0, col: 0から始まる独立した24列のグリッド座標系**で動作します。レイアウトを設計する際は、新しいタブの要素のrowとcolの値を0にリセットしてください。
  • PoP KPIタイルの必須要件: すべての主要KPIタイル（タイプ：single_valueのスコアカード）は、期間比較（PoP）のパターンを必ず実装する必要があります。正確に2つのフィールド（現行期間の指標と変化率の指標）をクエリし、比較設定（show_comparison: trueおよびcomparison_type: change）を有効にして、フィルターをExploreのPoP日付フィルター（pop_date_filter）にマッピングする必要があります。LookMLの例については、references/dashboard_standards.mdを参照してください。
Rule 11: ハードコード／ダミー計算の禁止（厳守）

LookMLのコンパイルで検証されるのは構文のみであり、計算が数学的または論理的に妥当かどうかは確認されません。機能しない「偽物」のプロジェクトの作成を防ぐため、エージェントはこのルールを必ず遵守してください。

  • 厳格な禁止事項: メジャー内にハードコードされた数値定数、ダミーのパーセンテージ、または固定のモック値（例：sql: 0.05 ;;、sql: 0.15 ;;、sql: 1 ;;）を記述することは、特に期間比較の変化率指標において、厳格に禁止されています。
  • 動的な計算: すべてのメジャーとディメンションは、実際のデータベース集計、または基となるフィールドに基づく数学的に妥当な動的計算を表す必要があります。
  • 正しい期間比較のロジック: 期間比較の変化メジャーではすべて、データベースレベルでの実際の時間枠比較SQLロジックを実装する必要があります。次のいずれかを行ってください。
    1. references/pop_engine.mdで定義されている単一ExploreのPoPエンジンを活用する（Lookerフィルターを使用して現行期間と前期間を動的に比較します）。
    2. 現行期間の集計値と前期間の集計値を動的に比較する、有効なデータベースレベルのSQL CASE WHEN式を記述する。
    • コンパイラーの検証を回避するために、モック値や固定のダミー数値を記述してはなりません。

5. Looker CLIとMCPツールの手引き

LookMLプロジェクトのライフサイクルを管理するには、AIエージェントはLooker CLI（looker-cli）またはLooker MCPサーバーを必ず活用してください。アクティブなLookerインスタンスとプログラムでやり取りする場合は、Looker MCPサーバーの使用が推奨されます。以下に、主要なアクションと対応するCLIコマンドおよびMCPツールの対応関係を示します。

1. セッションとワークスペースの管理

編集を行う前に、開発セッションがアクティブであり、Developer Mode を対象にしていることを確認してください。

  • Looker CLI: 
    looker-cli session update dev
  • Looker MCP: dev_mode ツールを呼び出します。 
    { "state": true }
2. データベースのイントロスペクションとメタデータの取得

列のマッピングや結合の計画を行う前に、データベースからテーブルの詳細とスキーマを直接取得してください。

  • Looker MCP:
    • 接続内のテーブル一覧を取得：get_connection_tables
    • テーブルの列一覧を取得：get_connection_table_columns（例：{"connection_name": "my_conn", "table_name": "users"}）
3. プロジェクトのライフサイクルとファイル管理

アクティブな Looker プロジェクトで LookML ファイルを作成・編集します。

  • Looker CLI: 
    looker-cli project create <project_id>
looker-cli project checkout <project_id> <branch_name>
  • Looker MCP:
    • プロジェクト内のファイル一覧を取得：get_project_files（例：{"project_id": "my_project"}）
    • 特定のファイルを読み取る：get_project_file（例：{"project_id": "my_project", "file_id": "views/raw/users.view.lkml"}）
    • 新しいファイルを作成：create_project_file（例：{"project_id": "my_project", "file_id": "views/refined/users_rfn.view.lkml"}）
    • ファイルの内容を更新：update_project_file（例：{"project_id": "my_project", "file_id": "views/refined/users_rfn.view.lkml", "content": "..."}）
4. LookML の品質とサーバーでの検証

デプロイ前に、LookML が Looker サーバーで完全にコンパイルできることを検証してください。

  • Looker CLI: 
    looker-cli project validate <project_id>
  • Looker MCP: ヘルスチェックと検証のツールを呼び出します。
    • プロジェクトの健全性を分析：health_analyze（例：{"project_id": "my_project"}）
    • パルスチェック：health_pulse
5. ビジュアルダッシュボードから LookML への変換

Looker UI でユーザーが設計したビジュアルダッシュボードをコードにインポートします。

  • Looker CLI: 
    looker-cli api dashboard dashboard_lookml <dashboard_id>
  • Looker MCP:
    • ダッシュボード一覧を取得：get_dashboards
    • ダッシュボードの詳細を取得：run_dashboard
6. 本番環境へのデプロイ

検証済みの変更をすべて本番環境にデプロイします。

  • Looker CLI: 
    looker-cli project deploy <project_id>

6. AI エージェントの実行とサブエージェントへの委任に関するガイドライン

実行速度を最適化し、トークンの肥大化を防ぎ、エージェント環境でターン数やコンテキストの上限に達しないよう、次の実行戦略に従ってください。

1. 非対話型の足場作成

プロジェクトを初期化する際、メインエージェントは Unix の入力パイプを使い（例：echo -e "..." | python3 looker_scaffold.py）、ターミナルで looker_scaffold.py スクリプトを非対話型で必ず実行してください。プロジェクトのパラメーター（名前、接続、方言、テーブル）は、ユーザーの自然言語によるプロンプトから直接抽出してください。ユーザーに入力を求めるために、ターミナルを停止しないでください。

  • 命名の一致：ローカルのディレクトリー構造と LookML のモデル名／プロジェクト名が Looker インスタンスと完全に一致し、ローカルとリモートの名前の不一致を防げるよう、エージェントは Looker インスタンスの対象プロジェクト名をそのまま（例：operational-intelligence-cloud-sql）足場作成スクリプトに渡す必要があります。
2. サブエージェントによるダッシュボードの並列分割

大規模で複数タブにわたるダッシュボードの作成には時間がかかり、多くのトークンを消費します。メインエージェントは、ダッシュボードの作成プロセスを必ず分割してください。

  1. レイアウトとタブの定義：メインエージェントがダッシュボード全体の構成を設計し、タブを決定します（例：タブ 1：概要、タブ 2：詳細）。
  2. 専門サブエージェントの起動：定義した各タブについて、専門の汎用サブエージェントを起動します。
  3. サブエージェントへの指示：各サブエージェントに、割り当てられたタブに属する LookML 要素のみを書くよう指示します。正しい tab_name パラメーターを使用し、独立したグリッド座標を row: 0, col: 0 から開始する必要があることを強調します。
  4. 統合とコンパイル：すべてのサブエージェントからそれぞれの LookML 要素配列が返されたら、メインエージェントがそれらを elements 配列にまとめ、グローバルな tabs メタデータ配列を定義して、最終的な .dashboard.lookml ファイルを一度の手順で整然と作成します。
3. 自律的な局所リファクタリング

サーバー側の検証チェック（looker-cli project validate）でコンパイル、結合、または構文エラーが返された場合、メインエージェントはデバッグの反復作業を専門のサブエージェントに委任することが望ましいです。サブエージェントは該当ファイルを局所的に編集し、ローカルで検証ツールを再実行して、ビルドが完全に成功した場合にのみ結果を報告します。これにより、メインの会話に集中し、効率を高く保てます。

4. 実行時 SQL デバッグループ（MCP による支援）

ダッシュボードのクエリで、データベース上の実行時エラー（列が見つからない、型変換の不一致、無効な方言関数など）が返された場合：

  1. サブエージェントへの委任：メインエージェントは、SQL のデバッグループを専門のサブエージェントに必ず委任します。
  2. 自己修復プロトコルの遵守：サブエージェントは Looker MCP ツールを使用し、references/sql_runtime_debugging.md に定義された自己修復 SQL デバッグループ、テレメトリのチェックリスト、およびデータベース方言の修正方法を開いて厳密に遵守する必要があります。
  3. 検証と完了：メインエージェントに報告する前に、すべてのクエリが稼働中のデータベースで正常に実行されること（HTTP 200 とデータが返されること）、および LookML が構文エラーなくコンパイルされることを確認します。
5. 局所変更の原則（全面的な書き直しは禁止）

開発者のコメントを保護し、カスタムディメンションを維持して、API トークンの効率を高めるため、エージェントは次の局所編集プロトコルを必ず遵守します。

  • 全面的な書き直しの禁止：既存の LookML ファイルまたはダッシュボードファイルをリファクタリング、自己修復、またはデバッグする際、エージェントはファイル全体を一から書き直したり、再生成したり、再構築したりしてはなりません。また、ファイルを一から書き換えるグローバルな Python スクリプトを生成してはなりません。
  • 対象ブロックの置換：エージェントは、検索と置換、行を指定した編集、対象を絞ったツール呼び出しなどにより、局所的かつ外科的にブロックを置換し、問題のある行または不整合な行のみを変更する必要があります。
  • 保持：関係のないディメンション、メジャー、Explore の結合、および開発者が記述したコメントは、必ず一切変更せずに残します。

コメント

Markdown 対応