Claude Code で CLAUDE.md と Excel だけから、Power BI レポート(PBIP形式) を 9分間で Service に発行できた話 (1) 結果編

Last updated at 2026-10-19Posted at 2026-10-19

はじめに

Excel の売上データを Power BI で可視化し、Service に発行して定期更新まで設定する作業を、Claude Code に任せてみました。

渡したのは次の 3 つだけです。

CLAUDE.md（ルール）
data/prompt.md（依頼）
Excel（元データ）

結果、モデル生成から Power BI Service への発行・更新・スケジュール設定までを 9 分で進められました。

この記事は (1)結果編 です。実行結果と、動かすために何が必要かだけを説明します。CLAUDE.md の概要、実行の流れ、つまずいた点、従来方式との比較、セットアップ手順は (2)解説編 でまとめます。

要点は 3 つです。

3 つのファイルだけで、 Power BI プロジェクト(PBIP) の生成から Service への発行・定期更新の設定まで進められました。
人が手を動かしたのは 2 回だけでした。1 回目は「発行して」と Claude Code に依頼しました。2 回目は Power BI Service で資格情報を設定したあとに、作業の続きを依頼しました。
速さの理由は AI の賢さだけではなく、過去の失敗を CLAUDE.md にルールとして溜めていたので、同じ失敗を繰り返さずに済みました（詳細は解説編で説明します）。

何を 9 分で行ったか

開始時点のフォルダには、CLAUDE.md、data/ec_sales_dummy.xlsx、data/prompt.md の 3 つのみでした。

終了時点の状態は次のとおりです。

dist/売上分析結果.pbip（PBIR + TMDL）が生成されました
Service にセマンティックモデルとレポートが発行されました
データの手動更新が完了し、毎日 10:30 / 14:00 / 20:00 の定期更新が有効になりました

準備（導入に必要なもの）

区分	必要なもの	用途
AI エージェント	Claude Code	PBIP の生成、検証、発行、更新を実行する
実行環境	Windows または Mac、Python、Azure CLI	スクリプトの実行と、API 用トークンの取得（`az login`）
Python ライブラリ	`openpyxl`、`requests`	Excel の列確認、API 呼び出し
Power BI	発行先ワークスペース、発行・共有できるライセンス（Power BI Pro で可）	セマンティックモデルとレポートの発行先
権限	発行先ワークスペースの編集権限（Contributor 以上）	Fabric REST API での発行・更新
テナント設定	Fabric REST API / Power BI REST API の利用許可（管理者設定）	API による発行・更新・スケジュール設定
データ	Service から参照できる場所（SharePoint など）に置いた Excel	Service からのデータ更新
作業フォルダ	`CLAUDE.md`、`data/prompt.md`、Excel	Claude Code に渡す 3 ファイル

補足：

Power BI Desktop は、今回の手順では使用していません。
Windows だけでなく、Mac でも生成できます。
scripts/ は用意する必要はありません。Claude Code が CLAUDE.md のルールをもとに生成します。

準備：作業フォルダに用意する 3 ファイル（①②③）

(root)/
├─ CLAUDE.md          # ①ルール
├─ data/
│   ├─ ec_sales_dummy.xlsx # ②売上データ
│   └─ prompt.md      # ③依頼文（出力名・ワークスペース・URL・更新時刻）

①CLAUDE.md（ルールと実行フロー）

実行フローと、過去の失敗から学んだルール集です。全文は下の折りたたみに載せています。設計の考え方は解説編で説明します。

CLAUDE.md の中身を見たい場合は、横向き三角をクリックしてください

CLAUDE.md

# CLAUDE.md

## 実行フロー（`data\prompt.md` を実行 ＝ 2手で完了）
`data/` と本ファイルだけの状態から、ユーザーへの連絡は次の **2回だけ**にする。途中で質問・確認をしない（URL が `...` で省略されているときだけ例外）。

### 1手目: 生成〜発行 → 「資格情報の設定依頼」
1. `data/prompt.md` を読む（出力名・ワークスペース ID・Excel URL・更新時刻。`scripts/config.py` が同じものを読む）。**prompt.md に「発行してください」とあれば発行は承認済み**。
2. `scripts/` が無ければ、末尾「付録: スクリプト一式」の 5 ファイルをそのまま `scripts/` に Write ツールで作る（`data` の列が付録と違う場合は `build.py` の `SALES_COLS`・`MEASURES`・`p_*` を直す。Excel の列は `openpyxl` で確認する）。
   - **注意: 付録の本文は現在この CLAUDE.md に載っていない**。`scripts/` が無い場合は、本ファイルのルール（スキーマ・型・TMDL/DAX の注意・発行 API の注意）に従って 5 ファイルを新規に書く。書いたら `scripts/` を残し（削除・`dist/` と一緒に消さない）、以後は `scripts/` を正とする。付録を復活させる場合は本文を必ずこのファイル内に置く
3. `az account show` でログイン確認 → `python scripts/build.py` → `python scripts/validate.py` → `python scripts/publish.py --yes`。**コマンドは 1 つずつ別々に実行する**（`&&` でつなぐ・スクリプト修正と発行を同じコマンドに混ぜると、自動モードが「本番デプロイ」として全体を拒否することがある。拒否されたらユーザーに許可を求める）。
4. 発行後は**更新・スケジュールを実行せず**、ユーザーに次を依頼して止まる: 「Service でモデル `<出力名>` の ‘…’→設定→データソースの資格情報→OAuth2・プライバシー ‘組織’→サインイン を設定してください。終わったら教えてください」（Claude Code からは設定不可）。

### 2手目: ユーザーが「設定した」と返信 → 更新・スケジュール → 「出来上がり報告」
1. prompt.md に更新時刻の記載があれば**更新・スケジュール設定も承認済み**。`python scripts/refresh.py --yes`（手動更新が `Completed` になるまで待ち、`refreshSchedule` を設定して取得確認まで行う）。
2. 更新が失敗したら（資格情報の未設定など）、原因を示して再依頼する。スケジュールは更新成功後にだけ設定する。
3. 最後に報告する: 生成物（`dist\<出力名>.pbip`）・発行先（モデル/レポート ID）・更新結果・スケジュール（時刻・タイムゾーン）・ページ構成。**Desktop で未確認の書式（visual の `objects`、`syncGroup` など）は未確認と明記**する。

## プロジェクト概要
- `data/` : 元データ（Excel）
- `dist/` : 生成した Power BI プロジェクト（`＊＊＊＊＊.pbip` ＋ `.Report` / `.SemanticModel`）
- `scripts/` : `config.py`（prompt.md 読込）/ `build.py`（モデル＋レポート生成）/ `validate.py`（静的検証）/ `publish.py`（発行）/ `refresh.py`（更新＋スケジュール）。無ければ付録から作る

## PBIP（PBIR + TMDL）生成時のルール
Power BI Desktop で開いたときのエラー再発を防ぐため、以下を守ること。

### `$schema` URL
- ホストは `https://developer.microsoft.com/json-schemas/fabric/...`。**`json-schemas`（末尾に s）**。`json-schema`（s なし）は不可
  - 過去のエラー: `Expected '$schema' property in '...Report\definition.pbir' to follow patterns: .../report/definitionProperties/2.x.x/schema.json`
- 使用する正しいパス（`.../fabric/item/report/` 配下）:
  - `definition.pbir` : `definitionProperties/2.0.0/schema.json`
  - `definition/report.json` : `definition/report/2.0.0/schema.json`
  - `definition/version.json` : `definition/versionMetadata/1.0.0/schema.json`
  - `definition/pages/pages.json` : `definition/pagesMetadata/1.0.0/schema.json`
  - `page.json` : `definition/page/2.0.0/schema.json`
  - `visual.json` : `definition/visualContainer/2.0.0/schema.json`
  - `.platform` : `.../fabric/gitIntegration/platformProperties/2.0.0/schema.json`
- `$schema` はすべて生成後に grep で一覧し、`json-schemas/fabric/` で始まることを確認する。

### プロパティの型
- `report.json` の `themeCollection.baseTheme.reportVersionAtImport` は**文字列**（例: `"2.0.0"`）で必須。オブジェクト（`{"visual":..,"report":..,"page":..}`）にするとエラーになる
  - 過去のエラー: `report.json の /themeCollection/baseTheme/reportVersionAtImport プロパティが正しい型として指定されませんでした`
- スキーマは推測で書かず、使う前に実物を取得して `required` と型を確認する（WebFetch で `.../schema.json` を取得）。ビジュアルの中身は `.../definition/visualConfiguration/2.0.0/schema-embedded.json`。
- `version.json` の `version` は `^[1-9][0-9]*\.(0|[1-9][0-9]*)\.0$` に合う文字列。`page.json` の `displayOption` は `FitToPage` 等の enum、`additionalProperties: false` のため未定義キーを入れない。

### Power Query (M)
- `Excel.Workbook(File.Contents(path), useHeaders, delayTypes)` は**第2引数が useHeaders**。`null, true` と書くとヘッダー行が列名にならず `テーブルの列 '注文No' が見つかりませんでした` エラーになる。ヘッダー付きシートは `Excel.Workbook(File.Contents(path), true, true)` と書く
- 他の M 関数も引数の位置・意味を Microsoft Learn（`microsoft_docs_search`）で確認してから書く。

### visualType（内部名）
- 存在しない名前を使うと「このカスタム ビジュアルを表示するには、最初にこのレポートに追加します: <名前>」というエラー表示になる（例: `stackedColumnChart` は不可）
- 確認済みの名前: `card` `slicer` `tableEx` `textbox` `lineChart` `lineClusteredColumnComboChart` `donutChart` `scatterChart` `treemap` `clusteredBarChart` `clusteredColumnChart`
- 積み上げ縦棒は **`columnChart`**、積み上げ横棒は **`barChart`**（`stacked` は付かない）。100%積み上げは `hundredPercentStackedColumnChart` / `hundredPercentStackedBarChart`
- 上記以外を使うときは、実在する名前か確認してから使う。

### スタイル（見た目）
- スキーマバージョン（Desktop で開けると確認済み）: `report/3.3.0`、`page/2.1.0`、`pagesMetadata/1.1.0`、`visualContainer/2.13.0`。3.3.0 では `reportVersionAtImport` は `{"visual","report","page"}` のオブジェクト（2.0.0 のときだけ文字列）
- レイアウト（1280x720、**確定版・Service で表示 OK 確認済み**）: ヘッダー（0,0,1280,54・濃紺・タイトル `売上分析ダッシュボード｜<ページ名>`）＋アクセント帯（0,54,1280,13）→ コンテンツパネル（0,60,1280,660）。**左サイドバー（ナビ・スライサー）は置かない**（一度作ったが文字切れしたため全削除）。コンテンツは x=12〜1268 に幅いっぱいで配置。各ビジュアルは白カード＋角丸8＋罫線、`visualHeader` 非表示、タイトルは 11pt 太字
- `syncGroup` は **`visual` オブジェクトの内側**に置く（visualContainer 直下だと発行時に `Property 'syncGroup' has not been defined` で失敗）
- 生成スクリプト: `scripts/run_styled.py`（`gen.py` のモデル部分＋`rep.py` のレポート部分）。見た目を変えるときは `rep.py` を編集して再生成し、`python scripts/validate.py` で静的検証する
- 各ビジュアルの `$schema` は `visualContainer/2.13.0`（スキーマ実体は 404 だが見本は Desktop で開ける）。ビジュアル固有の `objects`（`categoryAxis` `labels` `columnHeaders` 等）はスキーマで検証できないため、**Desktop で未確認**の書式として扱い、報告時に明記する
- テーマ `resourcePackages` の項目 type は `CustomTheme`（見本は `Image` だが、スキーマ上 `CustomTheme` が正）
- Python の `w` などヘルパー関数名と同名のループ変数を使わない（上書きで落ちる）

### 構成
- `.pbip` は `dist/` 直下、`<名前>.Report` と `<名前>.SemanticModel` を同階層に置く。
- `definition.pbir` は `version: "4.0"`、`datasetReference.byPath.path` に `../<名前>.SemanticModel`。
- セマンティックモデルは `definition.pbism`（version 4.0）＋ `definition/`（database / model / expressions / relationships / tables/*.tmdl）。TMDL のインデントは**タブ**。
- データソースのパスは M パラメーター `DataFilePath` で持つ（`.pbip` にデータは含まれない。開いたら「更新」が必要）。

### 生成スクリプトと実行手順
- 実行順は冒頭「実行フロー」。出力名・URL・ワークスペース ID・更新時刻は `config.py` が `data/prompt.md` から読む。URL が `...` で省略されていたら**完全な URL を必ず聞く**
- `scripts/` が無いときは付録から作る。データの列が違えば `build.py` の `SALES_COLS`・`MEASURES`・各 `p_*` を直し、直したら付録も更新する
- **スクリプトの修正は Edit ツールか、ファイル全体の Write で行う**。Python の文字列インデックスで切り貼りする使い捨てスクリプト（`s[:a]+new+s[b:]`）は使わない（`index` の位置を取り違えるとファイルの内容が二重になる）。「直したのに挙動が変わらない」ときは、まずファイルの中身（Grep）を疑う
- Windows で日本語を出力する Python を実行するときは `PYTHONUTF8=1`（Bash なら `export PYTHONUTF8=1`）を付ける（付けないと出力が文字化けする）
- スクリプトで日本語ファイルを書くときは UTF-8（BOM なし）。長い heredoc は途中で切れることがあるため、Write ツールでファイル化して実行する。CLAUDE.md の編集は Bash のスクリプトではなく Edit/Write ツールで行う（自動モードが自己改変として拒否する）

### report.json（Service の発行 API で判明）
- `report.json`（3.3.0）に **`layoutOptimization` は入れない**（`Property 'layoutOptimization' has not been defined` で発行失敗）
- **`visualContainerObjects`（背景・枠線・タイトル・`visualHeader` など）は `visual` オブジェクトの内側**に置く。`visual.json` 直下に置くと全ビジュアルで `Property 'visualContainerObjects' has not been defined` となり発行失敗（`syncGroup` と同じ。ビジュアル固有の `objects` も `visual` の内側）
- 発行時に書き換える `definition.pbir` の `byConnection` は **`connectionString` だけ**にする（`"connectionString": "semanticmodelid=<モデルID>"`）。`pbiServiceModelId`・`pbiModelVirtualServerName`・`pbiModelDatabaseName`・`name`・`connectionType` を入れると `Property '...' has not been defined and the schema does not allow additional properties` で発行失敗
- `report.json` の `resourcePackages` に `SharedResources`（`BaseThemes/CY24SU10.json`）を書いたまま、ファイルを同梱しなくても発行は通った（Desktop では未確認）
- Fabric の作成/更新は非同期（202 + Location）。完了後に `.../result` は取りに行かず、アイテム一覧から ID を引く（`publish.py` 実装済み）

### 生成後の検証
- 全 JSON を `json.load` で構文チェックするだけでは不十分（スキーマ URL やバージョンの誤りは検出できない）。`validate.py` を実行する
- 発行 API はレポートのスキーマ違反を厳密に検出する（`syncGroup`・`visualContainerObjects`・`byConnection` など）。`validate.py` が通っても Service が拒否することがある。拒否メッセージにはファイルパスと理由が出るので、それを根拠に直し、**同種の誤りを `validate.py` のチェックに追加**する（`visualContainerObjects` が `visual` 直下にないことは追加済み）
- `publish.py` が失敗しても、先に作成したセマンティックモデルは Service に残る。再実行すると同名の更新（`updateDefinition`）になり、重複しない（レポートは失敗した分は作られていない）
- Power BI Desktop が使えない環境では「Desktop で開いて未確認」と明示して報告する。
- ユーザーから Desktop のエラー文が来たら、該当ファイルのパス・メッセージを根拠に修正し、同種の誤りを全ファイルで横断チェックする。

### データ（Excel）の扱い
- 列は `openpyxl` で確認する。
- 上記と列が違う場合は、数値列の意味（単価か合計か）を行を見て判断し、報告に前提として書く

### モデル（TMDL / DAX）の注意（発行エラー再発防止）
- **メジャー名を列名と同じにしない**: `販売数` はメジャーと列が衝突し `measure cannot be created because a column with the same name already exists`。メジャーは `販売数合計` にする
- **カレンダーは計算列を後付けしない**: 計算テーブルに計算列を足すと発行時 `Relationship '...' uses an invalid column ID` で失敗する。`VAR _d = CALENDAR(...)  RETURN SELECTCOLUMNS(_d, "日付",[Date], "年",..., "月",..., "年月",..., "曜日番号",..., "曜日",...)` と**テーブル式の中で全列を作り**、TMDL の各列は `sourceColumn: [列名]` にする。`sortByColumn`・`isKey`・`dataCategory: Time` は可
- **カレンダーの DAX は空に強くする**: 更新時はデータ未読込で `MIN/MAX` が空になり `The start date or end date in Calendar function can not be Blank value`。`COALESCE(MIN(..), TODAY())` で代替する
- 前月比は `DATEADD('カレンダー'[日付], -1, MONTH)`

### カード・スライサーの表示崩れ防止（Service で表示 OK 確認済み）
- 上段のカード・スライサーは**高さ 84**、その下のコンテンツは y=172 から（`build.py` の `p_*`）。高さ 56 だと切れる
- カード（`card`）は `objects` に `labels: {labelDisplayUnits: 1D（表示単位なし）, fontSize: 24D}` と `categoryLabels: {show: false}`。表示単位が自動だと「6M」と省略され、`categoryLabels` を消さないとフィールド名（売上高合計など）が下に出て切れる・タイトルと冗長になる
- スライサー（`slicer`）は `objects` に `data.mode: 'Dropdown'` と `header: {show: false}`。フィールド名の行が出るとタイトルと重複しドロップダウンが切れる
- カード・スライサーにはコンテナのタイトルを付ける（フィールド名の行や説明文には頼らない）

## 発行・定期更新（Power BI Service）
### 前提
- 発行は `scripts/publish.py`（Fabric REST API ＋ `az` のトークン）。ワークスペース ID は `data/prompt.md` の記載（`config.py` の `WORKSPACE_ID`）
- 「いまの pbip を発行したい」→ **まず Claude Code から発行できるか確認**（`az account show` と `az account get-access-token --resource https://api.fabric.microsoft.com`）したうえで進める
- 同名があれば `updateDefinition`、なければ create。レポートの `definition.pbir` は発行時だけ `byConnection`（`semanticmodelid=<モデルID>`）に書き換える（ローカルは `byPath` のまま）
- データソースは SharePoint 上の Excel。M は `Excel.Workbook(Web.Contents(DataFilePath), true, true)`、`DataFilePath` は**ユーザー指定のファイル本体の URL**（`?web=1` なし・共有リンク不可）

### 確認ルール
- 外部への送信（発行・再発行・手動更新・スケジュール設定）は、**prompt.md に依頼が書かれていればそれを承認として実行**する（追加の確認質問はしない）。書かれていない操作は実行前に確認する。「発行のみ」とあれば更新・スケジュールはしない
- 資格情報の設定が済むまで更新・スケジュールは実行しない（冒頭「2手目」）

### 発行〜更新〜スケジュールの手順
1. `publish.py --yes`（事前に承認）。モデル・レポートとも新規作成 / updateDefinition。**発行後のモデルはデータが空**
2. ユーザーが Service で資格情報を設定（モデルの「…」→設定→データソースの資格情報→OAuth2・プライバシー「組織」→サインイン）。**Claude Code からは不可**。未設定のまま更新・スケジュールを実行しない
3. 承認後、Power BI REST（トークンは `az account get-access-token --resource https://analysis.windows.net/powerbi/api`）で
   - 手動更新: `POST /v1.0/myorg/groups/{ws}/datasets/{id}/refreshes`（202）→ `GET .../refreshes?$top=1` が `Completed` になるまで待つ
   - スケジュール: `PATCH .../refreshSchedule` に `{"value":{"enabled":true,"days":[全曜日],"times":[<prompt.md の時刻。既定は 08:00/14:00/20:00>],"localTimeZoneId":"Tokyo Standard Time","notifyOption":"MailOnFailure"}}` → `GET` で反映確認
4. 再発行しても更新スケジュールは維持される（`GET .../refreshSchedule` で確認済み）

## 標準の依頼条件（作成）
- データ参照先は M のパラメーター `DataFilePath`
- 日付が数値（シリアル値）なら日付型に変換し、カレンダーテーブルを作ってリレーションを張る
- メジャーの例: 売上高合計・粗利・粗利率・販売数合計・注文件数・平均注文単価・構成比・前月比など
- ページ構成の目安: サマリー / 商品カテゴリー分析 / エリア・都道府県分析 / 時系列分析

②data/ec_sales_dummy.xlsx（元データ）

EC の販売ダミーデータで、1,000 行 × 8 列です。

購入日 / 商品カテゴリ / 商品名 / 販売数 / 売上高 / 原価 / 購入者都道府県 / 購入者地方

※以下のプロンプトで Claude に生成させた csv を、Excel で保存し直したファイルをダミーデータとして使用しました。

生成に使ったプロンプト（data/ec_sales_dummy.xlsx 用）：

あなたは、何かの通販を運営していると仮定して、その売上表を Power BI で見たいとします。

購入日、商品カテゴリ、商品名、販売数、売上高、原価、購入者都道府県、購入者地方
のカンマ区切りcsvダミーデータを1000件作ってください。
どういうデータかはおまかせします。

購入日は 2025/9/1～2026/8/31 とします。
地方は、東北地方・九州地方といった地方を入れてください。

例：冒頭 9 件

購入日	商品カテゴリ	商品名	販売数	売上高	原価	購入者都道府県	購入者地方
2025/9/1	家電	モバイルバッテリー	2	6960	3783	愛知県	中部地方
2025/9/1	日用品	洗濯洗剤大容量	1	1280	808	東京都	関東地方
2025/9/2	スポーツ・アウトドア	ヨガマット	1	2980	1512	滋賀県	近畿地方
2025/9/2	本・文具	ビジネス書ベストセラー	3	4950	3750	福岡県	九州・沖縄地方
2025/9/3	ファッション	オーガニックコットンTシャツ	3	9870	4562	兵庫県	近畿地方
2025/9/4	スポーツ・アウトドア	キャンプ用チェア	2	11960	7119	東京都	関東地方
2025/9/4	日用品	ステンレスタンブラー	1	2480	1101	北海道	北海道地方
2025/9/5	食品	高級緑茶ティーバッグ	1	1580	714	長野県	中部地方
2025/9/6	本・文具	A5ノート10冊セット	1	1800	887	大阪府	近畿地方

③data/prompt.md（依頼文）

出力名、ワークスペース ID、Excel の URL、更新時刻を書きます。

data\ec_sales_dummy.xlsx をPower BIで可視化したいです。
dist フォルダ に「売上分析結果.pbip」として出力してください。
さらに Power BI Service に発行してください

発行先ワークスペース ID: `<ワークスペース ID>`
Excel データ参照先: https://<tenant>.sharepoint.com/sites/<site>/Shared%20Documents/.../ec_sales_dummy.xlsx
定期更新: 日本時間で毎日 10:30、14:00、20:00

Claude Code の実行手順

※開始時点での時刻を確認：2026-10-18 23:16:46

作業フォルダで claude を起動し、「data/prompt.md を実行して」と伝えます。
ある程度進むと、Claude Code から「Service で、資格情報を設定してください」と表示されます。
Power BI Service を開き、モデルの「…」（3 点リーダー）→「設定」→「データソースの資格情報」の「編集」ボタンを押します。
OAuth2 とプライバシー「組織（Organization）」を選び、「サインイン」ボタンを押します。
「Web データソースが更新されました」と表示されます。
Claude Code に「設定したので続けて」と伝えます。
Claude Code が Power BI Service への発行と更新・スケジュール設定を完了するので、Power BI Service上で発行されたレポートを確認します。

※終了時点での時刻を確認：2026-10-18 23:24:25（実行時間：約9分）

生成されたもの

作業フォルダのファイル構成

(root)/
├─ CLAUDE.md          # ①ルール
├─ data/
│   ├─ ec_sales_dummy.xlsx # ②売上データ
│   └─ prompt.md      # ③依頼文（出力名・ワークスペース・URL・更新時刻）
├─ scripts/           # ← ※Claude Code が生成
│   ├─ config.py      # prompt.md を読む
│   ├─ build.py       # モデル + レポート生成
│   ├─ validate.py    # 静的検証
│   ├─ publish.py     # 発行
│   └─ refresh.py     # 更新 + スケジュール
└─ dist/              # ← ※Claude Code が生成（PBIP: Power BI Project）