ClaudeでPower Fxの式をレビューする — 委任警告を見落とさない読み取り専用subagent

Power Appsのキャンバスアプリは、式(Power Fx)を取り出せればClaude Codeで点検できます。ただし2点だけ先に押さえてください。pac canvas unpack は非推奨で、取り出した .pa.yaml は読み取り専用です。つまりClaudeに任せられるのは「読んで指摘する」までで、直すのは人がPower Apps Studioで行います。

この記事では、式の取り出し方、点検の観点、観点を詰めた読み取り専用のsubagentの置き方を順に説明します。solution全体を編集する手順はClaude CodeでPower Platformのソリューションを編集する手順にあります。ここで扱うのは、キャンバスアプリの式の中身を読むレビューです。

先に確認する点 — pac canvas unpackは使わない

pac canvas unpack と pac canvas pack は、Power Platform CLIのリファレンスで非推奨と書かれています。ソース管理にはPower Platform Git Integrationを使うよう案内されています。

さらに、unpackが出力する *.fx.yaml は実験的な形式で、Power Appsのソースコード形式の説明ではすでに廃止扱いです。*.fx.yaml を新しい形式へ直接変換することもできません。

現行の *.pa.yaml は \src フォルダーにあり、アプリ全体の App.pa.yaml と画面ごとのファイルに分かれます。コンポーネントは \Component フォルダーに1つずつ入ります。.msapp 内のJSONはソースとして使えません。保存と読み込みを繰り返すと内容が安定しないためです。点検の対象は \src 配下の *.pa.yaml だけにします。

読み取り専用であることを前提に分担を決める

*.pa.yaml は、Power Apps Studioでの変更をレビューするための読み取り専用ファイルです。アプリの読み込みには使われず、ファイルを書き換えても無視されるか、失われる可能性があります。外部での編集やマージは、Git Integrationの範囲でのみサポートされます。

この制約から、役割はこう分かれます。

Claudeに *.pa.yaml を編集させて .msapp に戻す流れは、この記事では扱いません。戻す手段だった pack が非推奨だからです。

手順 — 取り出してレビューにかける

pac canvas list
pac canvas download --name "Expense App" \
  -d ./expense-app-src --overwrite
ls ./expense-app-src/src

--name にはアプリの正確な名前、一部の名前、アプリIDのいずれかを渡せます。--overwrite を付けないと、同名ファイルがあるときに上書きされません。

展開した直後にコミットしておくと、Studioで直した後の再取得との差分が、そのまま修正の記録になります。

点検の観点 — 委任警告から始める

Power Fxの式をレビューするとき、いちばん効くのが委任(delegation)の観点です。委任とは、フィルターなどの処理をデータソース側で実行させることです。式の一部でも委任できないと、式全体が委任されません。その場合、Power Appsはデータソースから最初の500件を取得して、手元で処理を続けます。上限はアプリ設定の「データ行の制限」で最大10,000件まで変えられます。

怖いのは、エラーにならず結果が欠けることです。データが10,000件あっても、501件目以降は検索にかかりません。件数の少ないテスト環境では気づけず、本番で初めて表面化します。

観点を3つに絞ってsubagentに渡します。

観点1: 委任できない関数が混ざっていないか

委任できる関数には、Filter、Search、First、LookUp、Sort、SortByColumns などがあります。集計の Sum、Average、Min、Max、CountRows、Count も、データソースが対応していれば委任できます。

委任できない代表は次のとおりです。FirstN、Last、LastN、Choices、Concat、Collect、ClearCollect、GroupBy、Ungroup が挙げられています。Filter の条件の中では、If、*、/、Mod、Text、Value、Left や Mid などの文字列操作、& による連結が、委任の対象外として並んでいます。

たとえばフィルターの条件で Mid と Len を使うと、SQL Serverが委任できるデータソースでも委任されません。このときStudioは黄色い三角と青い波線で警告します。500件以下なら正しく動くので、気づかないまま残りやすい形です。

観点2: LookUpの段数と書き方

式の中で使える参照の段数は、2段までです。基本のテーブルを引いた後に、参照先を展開する2回目のクエリが走る仕組みです。オフラインでは1段までです。

比較の書き方にも制約があります。エンティティのプロパティは、等号の左辺に置きます。公式の例では、'Business unit ID'.Name = LookUp(...).Name は動き、左右を入れ替えた形は動きません。Filter の中で LookUp を使っている式は、この向きを確かめる価値があります。

もう1つ、ForAll やギャラリーの各行から LookUp を呼ぶ形は、行数ぶんだけ問い合わせが増える疑いがあります。これは件数が増えたときの負荷を見積もるための観点で、実際にどう動くかはStudioの警告やモニターで確かめてください。subagentには「疑いとして挙げ、断定しない」と指示します。

観点3: ハードコードされた値

式に直接書かれた値は、環境を移したときに壊れます。環境ごとに変わるURL、ID、上限値、メールアドレスの文字列が典型です。これはPower Fxの仕様ではなくレビュー側の観点なので、subagentには「該当箇所と、変数や設定の置き場所の候補を示す」ところまで求めます。

警告が出ない落とし穴

点検用subagentを置く

ここまでの観点を、読み取り専用のsubagentにまとめます。プロジェクト用のsubagentは .claude/agents/ に置きます。必須のフロントマターは name と description の2つです。tools を読み取り系に絞れば、書き込みの手段そのものを持たせずに済みます。

---
name: powerfx-reviewer
description: Power Appsキャンバスアプリの*.pa.yamlを読み、Power Fxの委任・LookUp・ハードコードを点検する。式の変更を伴うレビューで使う
tools: Read, Grep, Glob
model: inherit
---
 
あなたはPower Appsキャンバスアプリの式のレビュアーです。
ファイルは読むだけで、書き換えません。
 
対象は src/ 配下の *.pa.yaml だけです。JSONは見ません。
 
点検の観点:
1. 委任できない関数(FirstN, Last, LastN, Concat, GroupBy,
   Collect など)が、データソースを引く式の中にないか
2. Filter の条件に If, Mid, Len, 数値演算, & の連結がないか
3. LookUpが2段を超えていないか。比較で参照先の列が左辺にあるか
4. ForAll やギャラリーの各行から LookUp を呼んでいないか(疑いとして挙げる)
5. With, UpdateContext, Set 経由で件数が切り詰められていないか
6. URL, ID, 上限値, メールアドレスの直書き
 
データソースの種類と件数は依頼文に書かれています。書かれていなければ、
委任できるかどうかを判定せず、「データソース不明」と報告します。
 
出力は「ファイル名・行付近・観点番号・指摘・確からしさ(確定/疑い)」の表にします。

tools を省略すると、subagentは利用できるツールをすべて引き継ぎます。レビュー用に読み取り系へ絞るなら、Read, Grep, Glob のように明示します。

追加したファイルは、.claude/agents/ を起動時から監視していれば、数秒で検出されて次の委任から使われます。そのフォルダー自体を新しく作った場合は、セッションを再起動してください。

呼び出しは、名前を文中に書くか、@ で明示します。@-mentionなら、そのsubagentが必ず実行されます。

@"powerfx-reviewer (agent)" ./expense-app-src/src を点検して。
データソースはSharePointリスト(約3万件)とDataverseの Accounts テーブル。

データソースと件数を依頼文に入れる理由

委任できるかどうかは、関数だけでなく、データソースの種類で決まります。公式の説明では、In 演算子はDataverseが対応していてExcelは対応していない、という例が挙がっています。ソースファイルには式しか載らないので、依頼文でデータソースを渡さない限り、subagentは判定の材料を持ちません。上のプロンプトが「データソース不明」と報告させているのは、この理由です。

件数も同じです。500件以下のテーブルなら、委任されなくても結果は正しくなります。依頼文に件数の目安を添えると、指摘の優先度が付けやすくなります。

返ってきた指摘を確かめる

返ってくる指摘は、次のような表の形になります。以下は形式の例で、実際の出力ではありません。

「確定」は、subagentがソースの字面から言い切れるものです。「疑い」は、Studioで確かめる前提で受け取ります。確かめ方は2通りです。Studioで該当する式の警告表示を見る方法と、データ行の制限を1にして動かす方法です。公式の説明では、制限を1にすると委任できない処理は1件しか返さなくなり、問題に気づきやすくなります。

subagentの指摘を直接アプリへ反映することはできません。指摘ごとにStudioで式を直し、保存してから、pac canvas download で取り直した *.pa.yaml の差分をもう一度subagentに渡します。この往復が、読み取り専用のレビューの回し方です。

運用の補足

式が長いアプリを扱うとき

画面数が多いアプリは、1回の依頼にまとめず、画面ごとに分けて依頼します。画面ごとの依頼なら、指摘の出どころも追いやすくなります。

方針をCLAUDE.mdに残す

観点のうち、チームで合意した値のルールは、subagentの定義ではなく CLAUDE.md に書いておくと再利用できます。URLや環境IDは設定の置き場所を決めて書いておけば、指摘に「置き場所の候補」が具体的に付きます。観点ごとにsubagentを分ける考え方は、design docを観点別のサブエージェントでレビューする記事でも使っています。

DAXなど隣接する式の点検

Power BIのDAXはPower Fxとは別物です。DAXの修正はPower BI MCPサーバーをClaudeにつなぐ手順で扱っています。

よくある質問

取り出した式をClaudeに直させて、アプリに戻せますか

*.pa.yaml はアプリの読み込みに使われないので、編集しても反映されません。Git Integrationを使う環境では、外部での編集とマージがサポートされています。それ以外の環境では、Studioで直す前提にしてください。

古い .msapp で src フォルダーが無いときは

src フォルダーが無い古い .msapp は、Studioで取り込み直して保存し、もう一度 .msapp をダウンロードします。その後でソースを取り出せます。