standardize-naming-conventions

命名規則の標準化

TMDL ファイルとして保存された Power BI セマンティックモデルの命名規則を監査し、標準化するための対話型ワークフローです。テーブル、列、メジャー、表示フォルダーの名前が、人にとって読みやすく、一貫性があり、ビジネスに即した命名基準に従っていることを確認します。

主なワークフロー

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

TMDL ファイルを探します。文脈からパスが明らかでない場合は、.SemanticModel/definition/ ディレクトリへのパスをユーザーに尋ねます。その後、モデルの構造をスキャンします。

# Count tables and get an overview
ls <path>/tables/*.tmdl

すべてのテーブル TMDL ファイルを読み込み、現在の命名パターンを把握します。次の点を確認します。

• テーブル名（DIM_、FACT_ などの技術的な接頭辞があるか）
• メジャー名（略語、プログラミング規則、一貫性のない構文があるか）
• 列名（CamelCase、snake_case、略語があるか）
• 表示フォルダーの構造（整理され、一貫性があるか）
• 説明（/// コメント）の有無

フェーズ 2：ビジネスコンテキストを理解する

重要：ビジネス用語を理解する前に、名前を変更しないでください。

AskUserQuestion を使って、次の情報を確認します。

1. ビジネス用語：「主要な指標には、組織でどのような用語を使っていますか？ たとえば、Revenue、Turnover、Sales、Gross Sales のどれを使っていますか？」
2. 既存の規則：「すでに文書化された命名規則や標準はありますか？」
3. 期間に関する規則：「過去の期間は通常どのように表しますか？（例：1YP、PY、Prior Year、Last Year）」
4. 単位に関する規則：「メジャー名では、単位を通常どのように表しますか？（例：(%), (Value), (Quantity) のように括弧で囲む）」
5. 下流への影響：「このモデルに接続されていて、名前の変更後にビジュアルの再バインドが必要となる下流のレポートはありますか？」

ユーザーのビジネスコンテキストに合わせて命名規則を調整します。references/naming-rules.md の規則はデフォルトです。ユーザーの組織ですでに規則が定められている場合は、それに合わせて変更してください。

フェーズ 3：監査して報告する

変更を行う前に、監査レポートを作成します。変更案を示す Markdown テーブルを表示します。

| Object Type | Current Name | Proposed Name | Issues Found |
|-------------|-------------|---------------|-------------|
| Table | FACT_Invoices | Invoices | Technical prefix |
| Measure | NetSls | Net Sales | CamelCase, abbreviation |
| Column | shp_dt | Ship Date | snake_case, abbreviation |

指摘事項を問題の種類ごとに分類します。

• プログラミング規則：CamelCase、snake_case、UPPER_CASE
• 略語／頭字語：短縮された名前や意味が不明瞭な名前
• 一貫性のない構文：期間、単位、集計パターンの混在
• 技術的な接頭辞：テーブル名の DIM_、FACT_、STG_
• 説明の不足：/// のドキュメントコメントがないオブジェクト
• 整理されていないフォルダー：表示フォルダーの階層がない、またはフラットである

先に進む前に、変更案を確認し、承認または修正するようユーザーに依頼します。

フェーズ 4：変更を適用する

ユーザーの承認後、TMDL ファイルを編集します。各テーブルファイルで次の操作を行います。

1. テーブル名を変更する（必要な場合）：table 宣言を変更します
2. メジャー名を変更する：宣言内のメジャー名を変更します。重要：モデル内のすべてのテーブルファイルを対象に、[Old Name] -> [New Name] のパターンに従って、名前を変更したメジャーへの内部 DAX 参照もすべて更新します
3. 列名を変更する：宣言内の列名を変更します。重要：すべてのテーブルファイルを対象に、'Table'[Old Column] -> 'Table'[New Column] のパターンに従って、DAX 参照もすべて更新します
4. 表示フォルダーを再編成する：displayFolder: プロパティを追加または再構成します
5. 説明を追加する：説明がないメジャーと列に /// コメントを追加します
6. リレーションシップ参照を更新する：名前を変更したテーブルや列が relationships.tmdl で参照されているか確認します

ファイル間の参照更新は不可欠です。 メジャー名または列名を変更するときは、definition/ ディレクトリ全体で参照を検索します。

# Find all references to a renamed measure
rg "OldMeasureName" <path>/definition/tables/
rg "OldMeasureName" <path>/definition/relationships.tmdl

フェーズ 5：検証する

変更を適用した後、次の点を確認します。

1. すべての TMDL ファイルを引き続き正しく解析できること（構文エラーがないこと）
2. どのファイルにも古い名前への参照が残っていないこと
3. テーブル間で表示フォルダーに一貫性があること
4. すべての表示対象のメジャーと列に説明があること

最後に検索を実行し、見落とした参照がないか確認します。

# Check for any remaining old names
rg -n "old_name_pattern" <path>/definition/

命名規則

ルール一式については、以下を含む references/naming-rules.md を参照してください。

• 人が読みやすい名前の要件
• 略語と頭字語のルール
• 技術的なプレフィックスのルール
• 集計、単位、期間の構文標準
• 表示フォルダーの構成パターン
• メジャー名の構成順序：[Aggregation] [Base Name] [Period] ([Unit])
• 列の命名パターン

検出すべき主なアンチパターン

よくある問題をすばやく確認するためのチェックリストです。

アンチパターン	ルール	修正例
snake_case	スペースを使用する	net_sales -> Net Sales
CamelCase	スペースを使用する	NetSales -> Net Sales
UPPER_CASE	スペースを使用する	TOTAL_COST -> Total Cost
略語	正式名称で表記する	Del. Mrgn -> Delivery Margin
意味が不明瞭な頭字語	正式名称で表記する	TFS -> Total Freight Surcharge
技術的なプレフィックス	削除する	FACT_Orders -> Orders
期間の不統一	統一する	LY/PY/Last Year -> 1YP
単位の不統一	統一する	pct/%/(%) -> (%)
説明の欠落	追加する	表示されるすべてのオブジェクトに /// のドキュメント文字列を付ける
フラットなフォルダー構成	整理する	サブフォルダーを含む番号付きの階層構造にする

下流レポートへの影響

警告： モデルオブジェクトの名前を変更すると、それらのフィールドを参照する下流レポートのビジュアルが壊れます。名前を変更した後は、次の手順を実行してください。

1. 接続されているすべてのレポート（.pbir ファイルまたは Power BI Service のレポート）を特定します
2. 新しいフィールド名を使用するようにビジュアルを再バインドします
3. pbir fields replace または pbir fields replace-table を使って各レポートを修復します。レポートの JSON を直接編集しないでください

名前の変更を適用する前に、必ずユーザーにこの影響について警告してください。下流レポートが存在する場合は、次の対応を検討してください。

• 変更前にモデルのバックアップを作成する
• 名前の変更後に再バインド作業を行う計画を立てる
• Tabular Editor で C# スクリプトを使用し、再バインドとともに一括で名前を変更する

追加リソース

参照ファイル

• references/naming-rules.md — 検出パターン、アンチパターンの表、メジャー名の構成順序を含む、命名規則の完全なルール

ドキュメントの取得

最新のセマンティックモデルと TMDL のリファレンスドキュメントを取得するには、利用可能な場合は microsoft_docs_search + microsoft_docs_fetch（MCP）を使用してください。利用できない場合は、mslearn search + mslearn fetch（CLI）を使用してください。ユーザーのリクエストに基づいて検索し、作業を進める前に十分なコンテキストを得られるよう、必要に応じて複数回検索してください。