bpa-rules

ベストプラクティスアナライザーのルール

Tabular Editor と Power BI のセマンティックモデル向けに、BPA（ベストプラクティスアナライザー）のルールを作成・改善するための専門的なガイダンスです。

このスキルを使用するタイミング

次のようなタスクでは自動的に有効になります。

• セマンティックモデルの検証用に新しい BPA ルールを作成する
• モデル、チーム、組織に適した BPA ルールを提案または選択する
• BPA ルールの式を改善またはデバッグする
• ルール違反を自動修正する FixExpression を作成する
• TMDL ファイル内の BPA アノテーションを理解する
• ベストプラクティスに照らしてセマンティックモデルを分析する
• その場限りのチェックを再利用可能な BPA ルールに変換する
• 組み込み、URL、モデル、ユーザー、マシンの各ソースにあるすべての BPA ルールを監査または調査する

主なワークフロー：対話型 Q&A による要件の確認（ダブルダイヤモンド）

重要：BPA ルールをすぐに生成しないでください。 これは要件を収集するための作業です。AskUserQuestion ツールを使い、複数回にわたってユーザーと対話を繰り返してください。ユーザーのビジネス、チーム、モデル、優先事項について十分な背景情報が集まるまで質問を続けます。その後で初めて、ルールの生成に進みます。

ワークフローは、ダブルダイヤモンドのパターンに従います。

1. 発散 -- ユーザーの背景、組織、目標を幅広く把握する
2. 収束 -- 優先事項と制約を絞り込む
3. 発散 -- モデルの構造を調査し、ルールの候補領域を特定する
4. 収束 -- 最終的なカスタマイズ済みルールセットを選定し、生成する

ダイヤモンド 1：要件の収集（フェーズ 1～2）

フェーズ 1：ユーザーと組織を理解する

各ラウンドで 2～4 個の質問を AskUserQuestion に渡します。各ラウンドの後に回答を確認し、追加の質問をします。組織の背景が明確になるまで、フェーズ 2 に進まないでください。 十分に把握できたと判断するまで、ラウンドを続けます。

ラウンド 1 -- 目標と対象ユーザー：

主な目標と、ルールを使用する人について質問します。AskUserQuestion の呼び出し例：

• 質問 1：「これらの BPA ルールの主な目標は何ですか？」 -- 選択肢：「チーム向けに BPA を設定する」、「特定のモデルを改善する」、「ガバナンス／コンプライアンスのルールを作成する」、（その他）
• 質問 2：「これらのルールは誰が使用しますか？」 -- 選択肢：「個人開発者」、「小規模チーム（2～5 人）」、「大規模組織／複数のチーム」、（その他）
• 質問 3：「どのツールを使用していますか？」 -- 選択肢：「Tabular Editor 3」、「Tabular Editor 2」、「CI/CD の TE CLI」、「Fabric ノートブック」

ラウンド 2 -- 標準と既存のルール：

ラウンド 1 の回答に基づいて、規約と既存ルールについて質問します。例：

• 質問 1：「既存の命名規則はありますか？」 -- 選択肢：「はい、文書化済みです」、「はい、非公式／場当たり的なものがあります」、「まだ規約はありません」、（その他）
• 質問 2：「すでに使用している BPA ルールはありますか？」 -- 選択肢：「はい、Tabular Editor にあります」、「はい、URL／リポジトリから取得しています」、「既存のルールはありません」、（その他）
• 質問 3：「最も重要なカテゴリはどれですか？」 -- multiSelect: true -- 選択肢：「パフォーマンス」、「メタデータ／ドキュメント」、「DAX の品質」、「命名規則」

ラウンド 3 以降 -- 必要に応じた追加質問：

ユーザーが既存のルールを使用している場合は、ファイルパスまたは URL を尋ねて読み込みます。命名規則がある場合は、具体的な内容を尋ねます。CI/CD に言及している場合は、パイプラインの設定について質問します。組織の全体像が明確になるまで、AskUserQuestion の呼び出しを続けてください。

フェーズ 2：モデルを調査する

フェーズ 1 の後、AskUserQuestion を使ってモデルへのアクセス方法を確認します。

• 質問：「セマンティックモデルはどのように利用できますか？」— 選択肢：「Fabric / Power BI Service に公開済み」、「ローカルの PBIP（.tmdl ファイル）」、「ローカルの .pbix ファイル」、「model.bim ファイルを持っている」

その後、回答に基づいてモデルを調査します。

回答	アクション
Fabric に公開済み	AskUserQuestion を使ってワークスペース名とモデル名を確認します。その後、fabric-cli スキルを読み込み、references/model-investigation.md で具体的なコマンドを確認してから、fab CLI を使ってリモートで調査します。
ローカルの PBIP	AskUserQuestion を使って .SemanticModel/definition/ フォルダーのパスを確認します。その後、Read/Grep ツールで TMDL ファイルを直接読み込みます。
ローカルの .pbix のみ	Power BI Desktop で File > Save as > Power BI Project (*.pbip) を選択して PBIP として保存するよう案内します。その後、保存されたフォルダーのパスを尋ねます。詳しい手順については references/model-investigation.md を参照してください。
model.bim ファイル	AskUserQuestion を使ってファイルのパスを確認します。その後、jq で解析するか、ファイルを直接読み込みます。
モデルがまだない	モデルの調査は省略し、組織のコンテキストのみに基づいて汎用ルールを生成します。

モデルから抽出する内容（ファイルの読み込み、パターンの検索、オブジェクト数の集計）：

• テーブル数、メジャー数、列数
• ストレージモード（Import、DirectQuery、Direct Lake、混在）
• メタデータの完全性（説明、表示フォルダー、書式文字列）
• 使用中の DAX パターン（CALCULATE、FILTER/ALL、計算グループ、UDF）
• リレーションシップのパターン（双方向、多対多、非アクティブ）
• 定義済みの RLS ロール
• 現在使用中の命名規則
• model.tmdl にすでに埋め込まれている BPA アノテーション

モデルの調査後、調査結果をユーザーに要約し、AskUserQuestion を使って分析が正確か確認するとともに、見落としがないか尋ねます。

ダイヤモンド 2：ルールの生成（フェーズ 3～4）

フェーズ 3：優先順位付けと提案

収集した情報に基づき、ルールカテゴリの優先順位付き提案を提示します。ルールを生成する前に、AskUserQuestion を使ってユーザーに確認や調整をしてもらいます。

ユーザーのコンテキストとの関連性が高い順にカテゴリを提示します。 たとえば、説明のないメジャーが多く、ユーザーがガバナンスを重視している場合は、次のようになります。

1. メタデータ（優先度：高 — 説明がないオブジェクトが多数）
2. ガバナンス（優先度：高 — ユーザーの目標）
3. パフォーマンス（優先度：中 — 未使用の非表示列を一部検出）
4. DAX 式（優先度：中 — FILTER/ALL パターンを一部検出）
5. 命名規則（優先度：低 — モデルではすでに一貫した命名規則を使用）

AskUserQuestion を使って次の点を尋ねます。

• 含めるカテゴリ（複数選択）
• 各カテゴリに設定する重要度（またはスキルに任せるか）
• FixExpression を含めるか（手動での修正を好むチームもあります）

ユーザーが優先順位を確認するまで、ルールを生成しないでください。

フェーズ 4：ルールの生成

フェーズ 1～3 の後に限り、ユーザーに合わせた BPA ルールを生成します。各ルールについて、次のとおりにします。

• そのルールがユーザー固有のモデルとコンテキストに関連する理由を説明します
• 安全で実用的な場合は FixExpression を含めます（ユーザーが希望した場合）
• ユーザーが示した優先順位に基づいて重要度を設定します
• ルール ID と名前に組織の命名規則を使用します

ルールの生成後、AskUserQuestion を使って次の点を尋ねます。

• 調整、削除、追加するルールがあるか
• 出力の保存先（ユーザーレベル、マシンレベル、モデルへの埋め込み、または URL）
• scripts/validate_rules.py で検証するか

ユーザーが満足するまで、ルールセットを繰り返し調整します。改善点を確認するため、引き続き AskUserQuestion を呼び出します。

Q&A を省略する場合

次の場合に限り、Q&A の一連のワークフローを省略します。

• ユーザーが具体的で明確に定義されたルールを求めている場合（例：「説明のないメジャーをチェックするルールを書いてください」）
• ユーザーが既存の式の改善やデバッグを求めている場合
• ユーザーが既存のルールの監査を求めている場合
• ユーザーが依頼時に必要なコンテキストをすべて提示している場合

このような場合でも、依頼が曖昧であれば、AskUserQuestion を使って確認してください。

重要事項

• ルール式は提案する前に必ず検証してください
• 対象のスコープ（Measure、Column、Table など）に対して式をテストしてください
• FixExpression によってデータが失われたり、モデルが壊れたりしないことを確認してください
• 新しい TOM プロパティを使う場合は、CompatibilityLevel を考慮してください

Tabular Editor との互換性

BPA ルールファイルを Tabular Editor で正しく読み込むには、特定の形式要件に従う必要があります。これらの要件に従わないファイルは、ルールコレクションが空になったり、読み込みに失敗したりする場合があります。

改行コード（CRLF 必須）

Windows 上の Tabular Editor では、Windows の改行コード（CRLF、\r\n）が必要です。Unix の改行コード（LF のみ）のファイルは、読み込みに失敗するか、ルールコレクションが空になる場合があります。

ファイルを CRLF に変換するには：

# macOS/Linux
sed -i 's/$/\r/' rules.json

# Or use the validation script
python scripts/validate_rules.py --fix rules.json

ファイルパス

Tabular Editor でルールファイルを追加する場合：

• 絶対パスを使用してください（例：C:\BPARules\my-rules.json）
• ..\..\.. のような相対パスは避けてください。TE で解決できない場合があります
• URL は確実に動作します（例：https://raw.githubusercontent.com/...）

JSON 形式の要件

余分なプロパティは指定しないでください： TE の JSON パーサーは厳格です。使用できるフィールドは次のとおりです。

• ID、Name、Category、Description、Severity、Scope、Expression
• FixExpression、CompatibilityLevel、Source、Remarks

次のパターンは避けてください：

// BAD: _comment fields not allowed
{ "_comment": "Section header", "ID": "RULE1", ... }

// BAD: Runtime fields (TE adds these, don't include them)
{ "ID": "RULE1", "ObjectCount": 0, "ErrorMessage": null, ... }

// GOOD: FixExpression can be null or omitted
{ "ID": "RULE1", "FixExpression": null, ... }
{ "ID": "RULE1", "Name": "...", "Severity": 2, "Scope": "Measure", "Expression": "..." }

注： FixExpression: null は有効です。ErrorMessage と ObjectCount は TE が追加する実行時フィールドです。ルール定義には含めないでください。

正規表現の式構文

式で RegEx.IsMatch() を使用する場合：

@ プレフィックスは使用しないでください： C# の逐語的文字列プレフィックスは使用しないでください

// BAD: @ prefix not supported
RegEx.IsMatch(Expression, @"FILTER\s*\(\s*ALL")

// GOOD: Standard escaping
RegEx.IsMatch(Expression, "FILTER\\s*\\(\\s*ALL")

RegexOptions パラメーターは使用しないでください： TE は options パラメーターをサポートしていません

// BAD: RegexOptions not supported
RegEx.IsMatch(Name, "^DATE$", RegexOptions.IgnoreCase)

// GOOD: Use inline flag or pattern only
RegEx.IsMatch(Name, "(?i)^DATE$")
RegEx.IsMatch(Name, "^(DATE|date|Date)$")

正しいスコープ名

TOM enum にある正確なスコープ名を使用してください。よくある間違い：

誤り	正しい
Role	ModelRole
Member	ModelRoleMember
Expression	NamedExpression
DataSource	ProviderDataSource または StructuredDataSource

注： Column は、後方互換性のための DataColumn, CalculatedColumn, CalculatedTableColumn のエイリアスとして有効です。

検証スクリプト

検証スクリプトを使用して、TE との互換性に関する問題をチェックし、修正してください。

# Check for issues
python scripts/validate_rules.py rules.json

# Auto-fix issues (CRLF, remove nulls, remove _comment)
python scripts/validate_rules.py --fix rules.json

スクリプトでは次の項目をチェックします。

• 改行コード（CRLF）
• _comment フィールドがないこと
• オプションフィールドに null 値がないこと
• 有効なスコープ名
• 式構文の警告

BPA ルールについて

• BPA ルールは、Power BI と Fabric のセマンティックモデルに対する QA/QC 用の自動テストを定義します
• BPA ルールは、Tabular Editor 2、3、CLI、または Fabric ノートブックで使用します
• ルール式は、Tabular Editor では C#、Fabric Notebooks では Python で定義します
• BPA ルールは、無視や修正などのアクションを実行でき、IDE に統合されているため、Tabular Editor で定義して使用するのが適しています

ファイルの場所

BPA ルールは複数の場所に存在することがあり、次の優先順位で評価されます。

場所	パス／ソース	説明
組み込みのベストプラクティス	TE3 内部	Tabular Editor 3 にバンドルされているデフォルトのルール
URL	有効な URL（例：https://raw.githubusercontent.com/TabularEditor/BestPracticeRules/master/BPARules-standard.json）	Web から読み込まれるリモートのルールコレクション
現在のモデル内のルール	下記を参照	モデルのメタデータに埋め込まれたルール
ローカルユーザー向けのルール	%LocalAppData%\TabularEditor3\BPARules.json	Windows 上のユーザー固有のルール
ローカルマシン上のルール	%ProgramData%\TabularEditor3\BPARules.json	すべてのユーザーに適用されるマシン全体のルール

組み込みルールの ID（TE3 の 27 個のルール）、モデルに埋め込まれたルールの形式、クロスプラットフォームでのファイルアクセス、すべてのファイルの場所の詳細については、references/te-compatibility.md を参照してください。

クイックリファレンス

ルール JSON の構造、有効なスコープ値、重大度レベル、互換性レベル、カテゴリのプレフィックスについては、references/quick-reference.md を参照してください。

式の構文（Dynamic LINQ、TOM プロパティ、文字列／ブール値／コレクションのチェック、Tokenize()、DependsOn、ReferencedBy）については、references/expression-syntax.md を参照してください。

TMDL のアノテーション

BPA ルールは、アノテーションを使用して TMDL ファイルに埋め込むことができます。

annotation BestPracticeAnalyzer = [{ "ID": "...", ... }]
annotation BestPracticeAnalyzer_IgnoreRules = {"RuleIDs":["RULE1","RULE2"]}
annotation BestPracticeAnalyzer_ExternalRuleFiles = ["https://..."]

アノテーションのパターンについて詳しくは、references/tmdl-annotations.md を参照してください。

ワークフロー

推奨：対話形式でのルール生成

最良の結果を得るには、上記の主要なワークフロー：対話形式の Q&A による調査に従ってください。AskUserQuestion を繰り返し使用してコンテキストを収集し、モデルを調査してから、対象を絞ったルールを生成します。

単一ルールの作成（直接作成）

ユーザーが、詳細な調査を必要としない特定のルールを求めている場合：

1. 適用するベストプラクティスを特定します
2. 適切な Scope を決定します
3. 違反を検出する Expression を記述します
4. 必要に応じて、自動修正用の FixExpression を記述します
5. サンプルモデルに対してテストします
6. ルールコレクションに追加します

既存ルールの改善

1. 現在のルールの目的を理解します
2. 誤検知や見逃しているケースを特定します
3. Expression のロジックを改善します
4. FixExpression が副作用を引き起こさないことを確認します
5. 十分にテストします

その他のリソース

リファレンスファイル

構文とパターンの詳細については、以下を参照してください。

• references/model-investigation.md - Fabric CLI またはローカルの .bim／.tmdl ファイルを使用したモデルの調査、PBIP として保存するようユーザーを案内する方法、モデル分析チェックリスト
• references/te-compatibility.md - Tabular Editor との互換性（CRLF、ファイルパス、JSON 形式、正規表現、スコープ名、検証、組み込みルール、ファイルの場所、クロスプラットフォームでのアクセス）
• references/quick-reference.md - ルール JSON の構造、有効なスコープ、重大度レベル、互換性レベル、カテゴリのプレフィックス、式の構文の概要
• schema/bparules-schema.json - BPA ルールファイルを検証するための JSON Schema（Draft-07） (一時的な場所)
• references/rule-schema.md - BPA ルールの各フィールドを人が読みやすい形式で説明したもの
• references/expression-syntax.md - Dynamic LINQ の式構文、TOM プロパティ、Tokenize()、DependsOn、ReferencedBy
• references/tmdl-annotations.md - TMDL 形式の BPA アノテーション

サンプルファイル

examples/ にある動作するサンプル：

• examples/comprehensive-rules.json - すべてのカテゴリを網羅した、実運用向けルール 30 個以上
• examples/model-with-bpa-annotations.tmdl - すべてのアノテーションパターンを示す TMDL ファイル

スクリプト

ユーティリティスクリプト：

• /scripts/bpa_rules_audit.py - すべてのソース（組み込み、URL、モデル、ユーザー、マシン）にわたる包括的な BPA ルール監査。Windows、WSL、Parallels を使用した macOS に対応。ASCII レポートと JSON エクスポートを出力します。
• scripts/validate_rules.py - BPA ルールの JSON ファイルがスキーマに準拠しているかを検証します

監査スクリプトの使用方法：

# Basic audit
python scripts/bpa_rules_audit.py /path/to/model

# Export to JSON
python scripts/bpa_rules_audit.py /path/to/model --json output.json

# Quiet mode (summary only)
python scripts/bpa_rules_audit.py /path/to/model --quiet

関連コマンド

• /suggest-rule - 説明から BPA ルールを生成します

関連エージェント

• bpa-expression-helper - BPA 式のデバッグと改善

ドキュメントの取得

最新の BPA および TOM のリファレンスドキュメントを取得するには、https://learn.microsoft.com を検索し、関連するページを取得してください。ユーザーのリクエストに基づいて検索し、十分なコンテキストを得てから進められるよう、必要に応じて複数回検索してください。

外部リファレンス

• Tabular Editor BPA の概要
• Tabular Editor BPA ビュー
• BPA サンプルルールの式
• TabularEditor BPA ソースコード
• BPA ルールリポジトリ
• TabularEditor ドキュメントリポジトリ
• Power BI セマンティックモデルのチェックリスト

ルールの例

説明のないメジャー

{
  "ID": "META_MEASURE_NO_DESCRIPTION",
  "Name": "Measure has no description",
  "Category": "Metadata",
  "Description": "All measures should have descriptions for documentation.",
  "Severity": 2,
  "Scope": "Measure",
  "Expression": "string.IsNullOrWhitespace(Description)"
}

非表示の未使用列

{
  "ID": "PERF_UNUSED_HIDDEN_COLUMN",
  "Name": "Remove hidden columns not used",
  "Category": "Performance",
  "Description": "Hidden columns with no references waste memory.",
  "Severity": 3,
  "Scope": "Column",
  "Expression": "IsHidden and ReferencedBy.Count = 0 and not UsedInRelationships.Any()",
  "FixExpression": "Delete()"
}