fhir-ig-analysis

FHIR 実装ガイドの測定

FHIR IG を客観的に測定し、何を数えたかを報告します。**読み取り専用です。**ビルド、変更、公開は一切行わず、予測もしません。

前提条件

コンテキストを確認してください。推測したり、作成したりしないでください。

1. ツール。 python3 が実行可能である必要があります。アナライザーは標準ライブラリのみを使用するため、インストールは不要です。python3 がない場合は、その旨を伝えて停止してください。インタープリターを取得しないでください。

2. 対象。 1 つ以上の IG を指定します。それぞれ、ローカルパス、git URL、またはパッケージ .tgz で指定します。run がそれぞれを自動的に解決します（URL の場合はシャロークローン、パッケージの場合はダウンロード）。ツールが読み取る内容以外に、リポジトリ内で確認する必要のあるものはありません。

   • sushi-config.yaml も input/ もないローカルパスは、IG プロジェクトではありません。その旨を報告して停止してください。
   • git URL にはネットワークアクセスが必要です。クローンに失敗した場合は、空の測定結果を報告するのではなく、失敗を報告してください。

3. デフォルトは静的解析です。そこに伴う制約を把握してください。 ビルドを行わない場合、解析は静的です。対象は、sushi-config／パッケージのメタデータ、FSH の件数、ナラティブ、ディレクティブ、依存関係、言語的特徴、重複、衛生状態です。ビルドから得られる指標（qa.json：エラー、警告、リンク切れ、検証結果）は null のままで、カタログでは Build と表示されます。パッケージ .tgz の場合、解析対象はさらに限定され、生成済みリソースのみになります。

数値を報告する際は、どのモードで生成されたものかを明記してください。null はゼロではありません。

手順

生成されるレポートはドイツ語です。このスキルの手順は英語です。これは意図的なもので、どちらか一方の事実から自動的に導かれるものではありません。レポートの文章は引き継がれたもので、翻訳されていません。黙って「修正」したり、数値を翻訳したりしないでください。

まずスクリプトのパスを解決してください。 以下のコマンドでは、ツールを作業ディレクトリ（作業対象のプロジェクト）ではなく、このスキル自身のディレクトリからの相対パスで指定しています。SKILL.md があるディレクトリを SKILL_DIR に設定し（今読んだばかりなので、場所は分かるはずです）、すべての呼び出しで使用してください。

SKILL_DIR=<the directory containing this SKILL.md>   # e.g. .claude/skills/fhir-ig-analysis

プロジェクトのルートから scripts/... をそのまま実行すると、単に失敗するだけではありません。プロジェクトに同じ名前のファイルを含む scripts/ ディレクトリがある場合、気付かないうちにそちらが実行されてしまいます。

1. 測定します。 IG は 1 つでも複数でも、IG のルートからでも任意の場所からでも実行できます。

   python3 "$SKILL_DIR/scripts/ig-stats.py" run <input…> [-o OUTDIR] [--label a,b]
   

   入力が 2 つ以上の場合、IG ごとに 1 つのレポートを出力し、さらに compare-report.md も自動的に生成します。--label では表示ラベル（レポートの見出し、比較表の列）を入力ごとに設定します。出力のファイル名は常に IG ID に基づきます。

   入力の解決方法によって数値の読み取りに影響する点が 2 つあります。Git URL は浅いクローンとして取得されるため、Git 履歴のメトリクス（バスファクター、メンテナンス頻度）は「算出不可」（git.history_complete: false、値は null）として報告されます。これらが必要な場合は、ローカルの完全なクローンを測定してください。また、このツールは成熟度の構成要素をカウントしますが、集計スコアは出しません。0～100 の「準備度」数値は予測になってしまうため、このスキルでは意図的に出力していません。

2. 上級者向けのエントリーポイント。各段階を個別に実行する場合に使用します。

   python3 "$SKILL_DIR/scripts/ig-stats.py" analyze <ig-dir> [-o stats.json]
   python3 "$SKILL_DIR/scripts/ig-stats.py" report  <stats.json>  [-o report.md]
   python3 "$SKILL_DIR/scripts/ig-stats.py" compare <stats.json…> [-o compare.md]
   

3. 必須ページに関する調査結果を慎重に確認してください。 ツールが照合するページ一覧は、references/report-content.json の mandatory_pages にあり、意図的に手動編集できるようになっています。MII KDS モジュールテンプレートで実際に使われているページ名を初期値として設定しています。

   測定対象の IG で別のページ一覧が正当に使われている場合は、そのページを不足として報告するのではなく、一覧を修正してください。また、レポートには使用した一覧を記載してください。ページの網羅性メトリクスの精度は、照合対象の一覧の精度に左右されます。

4. 両方の成果物を報告してください。 JSON は固定スキーマを持つため、継続的な実行結果をきれいに比較でき、リリース間でモジュールがどのように成長したかを示せる、長期保存に適した成果物です。Markdown は人が読むためのものです。

5. 正規化されたメトリクスのみで比較してください。 サイズの異なる IG 間で絶対数を比較しても、ほとんど意味はありません。比較レポートではスコープ全体の合計を示す Σ 列を集計しますが、公平な比較に使えるのは正規化された列です。

6. 同一モジュールの検証は自動で行われます。 比較対象のすべての入力が同じ packageId を持つ場合、それらは 1 つのモジュールの状態（通常はプラットフォームのソースと、その移行後のコピー）です。このときレポートは同一モジュール検証に切り替わり、ID フィールドの一致、公開済み成果物セットの一致（内部 FSH 構成要素は別途報告されます。テンプレートの採用では、正当に追加されるスキャフォールドのルールセットが考慮されます）、正準 URL の一致（両方の入力に fsh-generated がある場合はそこから読み取ります）、および言語レベルごとのナラティブ（デフォルト／翻訳／保持されたプラットフォームページ）を単語カバレッジの指標とともに報告します。Σ 列は削除されます（1 つのモジュールでは意味がないためです）。各判定はすべてカウントされ、予測は行われません。順序が重要です。最初の入力が基準になります。

事前確認の観点（移行ゲート 0）

v0.17.0 以降、各測定結果には、ツリーのみからオフラインで測定される、移行判断を左右する観点を含む preflight セクションが含まれます。

• ライセンスの証拠、段階別 — ライセンスが宣言されているすべての箇所（sushi-config/package.json、LICENSE ファイル、著作権に関する説明文）。不在や矛盾も、独立した検出事項として扱います。
• 正規空間の調査 — url が IG の正規 URL の範囲外にあるリソース、および範囲内での id↔url の不一致。これらを合わせて、移行時に必要となる special_url_prediction とパブリッシャーの special-url リストを示します。example.org の正規 URL は別途明示します。sushi-config と package.json の正規 URL が一致しない場合は、config_contradiction として報告します（実測例：PRO の package.json には modul-dok の正規 URL が記載されています）。
• 依存関係のピン留め状況 — 旧形式／仮想パッケージ、THO／Extensions-Pack が直接ピン留めされているかどうか（不在の場合、IG Publisher がビルド時に最新リリースを注入します）、外部親の正規 URL。パーサーは SUSHI の依存関係の両形式（フラット形式と、id/version のサブキーを持つネスト形式）を読み取ります。dependency_block_unparsed: true は、ブロックは存在するもののエントリが得られなかったことを示します。これはパーサーの検出事項であり、依存関係がないソースを意味するものではありません。
• パッケージのレイアウト — 配布パッケージの場合、.index.json の有無（不在の場合、インデックスベースのオラクルは実行されません）と、ネストされたリソースディレクトリ（フラットな glob では取りこぼします。この調査は再帰的です）。
• 説明文のソース — 説明文を含むツリー（pagecontent、intro-notes、implementation-guides/）を示します。dual_source: true と各ツリーの最終コミット日付により、どちらを正本とするかを既定の順位ではなく、測定に基づいて判断できます。
• QA ベースライン — ツリー内にレンダリング済みの qa.json があれば示します。None の場合は取得してください（移行前のソースをビルドするか、レンダリング済みの QA を取得します）。決してあると仮定しないでください。

これらの観点の基盤には、調査結果の正確性を保つための 3 つのルールがあります。ConceptMap、Measure、ObservationDefinition など、正規の基底型のインスタンスは「例」に含めず、開かれた artifacts.other バケットに数えます。FSH 宣言と生成済みリソースの両方が存在する場合は、その件数を相互検証し、不一致をすべて報告します（generated_crosscheck — ページに関する判断では、生成された resourceType の調査結果を正とします）。SUSHI プロジェクトがルートの下にネストしているリポジトリ（strukturdaten の Resources/ など）は、ページ 1 に警告を表示してルートを再設定します。検出事項を出さずに空の識別情報を返すことはありません。

None は、この測定ツールがツリーから測定できない項目を示します。利用者は別途取得する必要があり、決してあると仮定しません（「null はゼロではない」というルールです）。mii-ig-migration スキルは、移行前のソースに対して、この測定を必須のゲート 0 事前確認として実行します。

検証

python3 "$SKILL_DIR/scripts/ig-stats.py" run <ig-dir> -o /tmp/igstats
python3 -c "import json;d=json.load(open('/tmp/igstats/<name>-stats.json'));print(d['mode'],d['schemaVersion'])"

• 実行が 0 で終了し、入力ごとに *-stats.json と *-report.md が 1 つずつ書き出されること。
• 入力が 2 つ以上の場合、compare-report.md が存在すること。
• JSON の mode が申告内容（static／reduced）と一致し、schemaVersion が含まれていること。
• 引用するすべてのメトリクスは、カウントされた数値か null のいずれかであること — 推定値は使用しません。フィールドが null の場合は、ゼロではなく静的には導出できないと報告してください。
• 必須ページの結果が、測定対象の IG と照らして妥当であること。すべてが欠落している場合は、通常、IG の不具合ではなくページセットの誤りです。
• 同一モジュールの比較では、Befund ブロックに各観点の IDENTISCH／DIVERGIERT が記載されること — 識別情報、公開されるアーティファクトの集合、正規 URL がすべて IDENTISCH である場合に限り、移行は忠実です。移行スキルの完了定義では、まさにこれが求められています。

対象範囲と対象外

測定と比較を対象とします。IG に何が含まれているか、どの程度整備されているか、どのように比較できるか、時間の経過とともにどう変化するかを扱います。

意図的に対象外としているもの：

• 工数の予測。 ツールが報告するのは、実際に数えた内容です。人日やコスト、準備状況のスコアは推定しません。また、数値を移行のスコーピングとして位置づけていた以前のバージョンのこのスキルは、意図的に範囲を絞りました。この機能を再び持ち込まないでください。測定値を予測のように装うことは、このスキルが出し得る最も信頼性の低い情報です。
• MII KDS モジュールテンプレートへの移行 — mii-ig-migration を参照してください。移行済みガイドとそのソースの照合も、同じくそちらの scripts/verify-migration.py の担当です。 成果物の 到達可能性、メニュー構造、コンテンツの配置、レンダリング後のヘッダーメタデータ、ツールチェーンの来歴は、移行のページマップと実行ログを読み取る合否判定基準です。これらの入力は IG の性質ではなく、このスキルの「パス、URL、または .tgz」という契約を損なうためです。以下の同一モジュール内での検証は、その判定が利用する測定であり、代替手段ではありません。成果物が存在することは証明しますが、そこへリンクするものがあることまでは証明しません。
• 翻訳 — fhir-ig-translation を参照してください。
• MII メタ Wiki またはメタデータ契約に照らした規約と命名のチェック。これは別のチェックであり、モジュールテンプレートには専用のスキルが付属しています。
• あらゆるもののビルドまたは公開。 読み取り専用はガードレールであり、既定の設定ではありません。

この名前のスキルがこのカタログとローカルの両方で提供されている場合は、ローカル版が優先されます。

ガードレール

• 読み取り専用。 分析対象の IG を変更したり、ビルドを強制したりしないでください。
• 予測ではなく測定。 上記を参照してください。
• 公平な比較は正規化されたメトリクスのみで行います。
• 推測で補わない。 入力が欠けている場合は推測せず、null を返します。ヒューリスティックなメトリクスはカタログ内でその旨を示し、必ずそのように報告します。

参考資料

• references/metrics-catalog.md — パラメーターのカタログ（グループ A～N）。各メトリクスについて、情報源と用途を記載しています。手動で拡張でき、測定対象の SSOT です。
• references/ig-stats-schema.json — ig-stats.json のスキーマです。
• references/report-content.json — 平易な文章、用語集、ディレクティブのパターン、メトリクスの説明、および mandatory_pages リストです。手動で編集できます。
• references/triggers.md — Gate 3 のプロンプトセットです。
• scripts/ig-stats.py — アナライザー（run / analyze / report / compare）。

出典

medizininformatik-initiative/mii-kds-module-template のコミット b5beedb17a66a4397d597429668c7b6d54202c62 に含まれる skills/ig-analyze を基にしています。このスキルは、さらに forschungsgruppe-digital-health/mii-kds-sample-ig-inoffiziell の ig-analyze スキルを改変したものです（CC-BY-4.0）。この系譜における両方の段階を意図的に記録しています。

このカタログ向けに、2026-07-31 に再構成しました。カタログの契約要件を超える、実質的な変更は3点です。

• 分析ツールをスキルとともに同梱するようになりました。以前はソースリポジトリの scripts/ に置かれ、親ディレクトリへの遡及によって参照されていたため、別の場所にインストールすると、スキルから到達できないファイルを指していました。
• scripts/ig-stats.py は、references/report-content.json を自身のパスを基準に特定するようになりました。以前は、計算したリポジトリのルートとハードコードされた skills/ig-analyze/references/… を組み合わせてパスを構築していましたが、ここでは2つの理由で機能しませんでした。計算すべきリポジトリのルートがなく、スキルの名前も変更されていたためです。
• 必須ページのリストをコードから references/report-content.json に移し、内容を修正しました。引き継がれたリストには11ページが記載されていましたが、そのうち6ページは存在しません。テンプレートのモジュールの基になっているのは（use-cases、data-sets、uml、context、references、 security-privacy）であるため、測定のたびに存在しないページが6ページあると誤って報告されていました。

このスキルの最初の実タスク演習（kerndatensatz-dokument と kerndatensatz-basis を対象としたドライラン）の後、2026-08-01 に改訂しました。出力上の不備を4点修正しました。いずれも「予測ではなく測定」という方針に沿ったものです。集計した Reifegrad／「Freigabe-Indikator」スコアを削除し、各構成要素を集計せずに報告するようにしました（schemaVersion 1.4）。「Empfehlungen」テーブルの移行範囲に関する説明を、中立的な「Befunde & Einordnung」という測定結果の説明に変更し、指標のない「Arbeitsweise」行を削除しました。浅いクローン（ツール自身が作成するクローンもすべて含みます）の git 履歴指標は、架空の「100 % top author」ではなく、history_complete: false と null を報告するようになりました。また、ずれが生じていた references/ig-stats-schema.json を実際の出力に基づいて再生成しました（mandatory_missing は宣言されていましたが、出力されていませんでした）。ドライランの調査結果は、mii-kds-dokument-ig-inoffiziell のサンドボックス内、docs/reports/dry-run-2026-07-31/ にあります。

原著作物のライセンスは CC-BY-4.0 です。両方のソースリポジトリでその旨が明記されています。scripts/ は、このリポジトリのコードライセンスに合わせて Apache-2.0 です。

4つの KDS モジュールを対象としたモジュールの測定・比較、および完了済みの2つの移行に対する同一モジュールの検証ゲートで、実タスクに繰り返し使用したことを受けて、2026-08-05 に stable に昇格しました。references/triggers.md のトリガーセットは、これらの実行で検証されました。