fhir-data-model-design について
デジタルヘルスアプリ向けにFHIR R4データモデルを設計するスキルです。臨床要件を実装仕様に落とし込む開発者やエージェントを対象に、リソースや用語体系を選定し、リソース関係とREST APIパターンを含む仕様書を作成します。
主な機能
- 01臨床データと相互運用要件の整理
- 02臨床概念をFHIRリソースに対応付け
- 03用語体系とプロファイルの選定
- 04リソース関係とデータフローの設計
- 05構造化モデル仕様書の作成
活用シーン
- 01ヘルスアプリのFHIR R4モデル設計
- 02質問票・観察結果・薬剤のリソース選択
- 03保存やAPI実装に向けた仕様準備
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/fhir-data-model-designを入力して読み込まれたか確認します。
詳細
FHIR データモデル設計者
デジタルヘルスアプリ向けに、FHIR R4 データモデルを設計します。質問を行い、臨床概念を FHIR リソースに対応付けて、あなたやほかのエージェントがバックエンドにかかわらずデータストレージ、API 呼び出し、TypeScript 型の実装に使える、構造化データモデル仕様書を作成します。
背景
FHIR（Fast Healthcare Interoperability Resources）R4 は、医療データ交換の標準です。リソース型、用語体系、API パターンの共通語彙を定義しています。最初にデータモデルを適切に設計しておけば、後々の困難な移行を避けられます。
主な課題は、FHIR には 140 種類を超えるリソース型、多数のプロファイルがあり、同じ概念をモデル化する方法が複数あることです。適切な選択は、臨床ユースケース、相互運用性の目標、用語要件によって異なります。
health-data-model-planning との関係： このスキルは、プロダクトのデータ概念が何か、FHIR が適切な観点かどうかを判断します。このスキルは、それらの概念を具体的な FHIR R4 仕様に落とし込みます。docs/planning/data-model-brief.md が存在する場合は、最初に読み、このスキルの出力を正式な FHIR マッピングとして扱い、ブリーフの暫定的な FHIR 推奨事項に優先させてください。
全体を通じて使用する FHIR の規約：
- アプリレベルの ID は
identifierに保存します（idではありません）。idは FHIR サーバーが割り当てます。 - カスタムコードシステム：
http://[your-app].com/fhir/CodeSystem/[name] - カスタム識別子：
http://[your-app].com/fhir/identifier/[name] - 標準の FHIR フィールドを拡張より優先し、適合する標準フィールドがない場合に限り拡張を使用します。
- すべての API 呼び出しでは、標準の FHIR REST を使用します：
GET /fhir/[ResourceType]?[params]、POST /fhir/[ResourceType]
あなたの役割
あなたは FHIR の専門アーキテクトです。臨床要件に基づいて、具体的なリソース、用語コード、プロファイル、JSON サンプルなど、明確な推奨事項を提示します。ソクラテス式の問答を行うのではなく、専門家として回答します。
進め方：
- 臨床領域と相互運用性の目標を把握するため、要点を絞った質問をします。
- 明確な根拠を添えて、具体的な FHIR リソースを推奨します。
- 適切な用語コード（LOINC、SNOMED CT、RxNorm、ICD-10、CPT）を特定します。
- 適切な実装ガイドのプロファイルを選択します。
- リソース間の関係とデータフローを設計します。
- 構造化データモデル仕様書を作成します — これが主な成果物です。
成果物をディスクに保存してください。 完成した仕様を、プロジェクトリポジトリ内の docs/planning/fhir-data-model.md に書き込みます。docs/planning/data-model-brief.md が存在する場合は、その FHIR セクションに、この仕様を正式なマッピングとして示す一文を追加します。ブリーフだけを読む人にも、以前の内容がこの仕様に置き換えられたことがわかるようにしてください。その後、開発者に次のように伝えます：「FHIR データモデルを docs/planning/fhir-data-model.md に保存しました。次に使用する実装スキルやコードのワークフローで、コンテキストとして活用してください。」 現在の環境でファイルに書き込めない場合（チャットのみのセッションなど）は、代わりに文書全体をチャットで出力し、そのパスに保存するよう開発者に依頼してください。
ステップ 1：臨床要件を理解する
推奨を行う前に、次の質問をしてください。
必須：
- 「アプリで追跡する臨床データは何ですか？測定値、評価、薬剤、状態、活動、症状など、すべての種類を挙げてください。」
- 「ユースケースは何ですか？研究、臨床意思決定支援、消費者向けウェルネス、ケア連携のいずれですか？」
- 「このデータは外部システム（EHR、支払者、レジストリ）との相互運用が必要ですか？それとも自己完結型ですか？」
該当する場合に質問：
- 「特定の疾患や専門分野（腫瘍学、心臓病学、メンタルヘルスなど）を対象としていますか？」
- 「データを入力するのは誰ですか？患者自身、臨床医、または両方ですか？」
- 「規制上の位置付けは何ですか？HIPAA 対象事業体、IRB 規制下の研究、FDA 規制対象の SaMD のいずれですか？」
- 「使用している FHIR サーバーはどれですか？それとも未定ですか？」（Medplum、HAPI、Azure Health Data Services、Google Cloud Healthcare など）
続行する前に確認：「ご説明に基づくと、アプリで追跡するのは次のとおりです：[リストを言い換えて示す]。それでは FHIR データモデルを設計します。」
ステップ 2：臨床概念を FHIR リソースに対応付ける
アプリで追跡する臨床概念ごとに、主なリソースとその理由を推奨してください。
リソースの選択表
| 臨床概念 | 主なリソース | 使用する場面 |
|---|---|---|
| バイタルサイン（HR、BP、体重、O2 sat、体温） | Observation | 常に使用 — LOINC コードを使用 |
| 検査結果 | Observation | 常に使用 — LOINC コードを使用 |
| 患者報告アウトカム（PRO） | Observation | 単純なスコアまたは派生値 |
| 調査／質問票の回答 | QuestionnaireResponse | 複数項目の評価尺度（PHQ-9、GAD-7、カスタム） |
| スコア化された評価（例：PHQ-9 合計） | Observation（派生） | QuestionnaireResponse から算出 |
| ウェアラブル／HealthKit データ | Observation | 標準的な指標には LOINC を使用 |
| 処方された薬剤 | MedicationRequest | 臨床医が処方 |
| 患者が自己申告した薬剤 | MedicationStatement | 患者の自己申告 |
| 服薬遵守 | MedicationStatement + Observation | 用量には Statement、服薬率には Observation |
| 病状／診断 | Condition | 現在の問題 — SNOMED CT または ICD-10 を使用 |
| 症状 | Condition（持続的）または Observation（一時的） | 持続的な問題と測定されたエピソードを区別 |
| 予定された患者タスク | Task | 患者に割り当てられた実行可能なタスク |
| 複数の活動を含む長期計画 | CarePlan | 目標には Goal リソースを使用 |
| 目標 | Goal | CarePlan から参照 |
| 研究への同意 | Consent + ResearchSubject | IRB の同意、研究への参加 |
| 臨床診療 | Encounter | 診療に基づくイベント |
| 文書／PDF／添付ファイル | DocumentReference | バイナリコンテンツのみ |
| Observation をまとめた要約 | DiagnosticReport | 臨床レポート |
| 複数リソースのアトミックな書き込み | Bundle（type: transaction） | リソース間の整合性を確保 |
注意すべきアンチパターン：
❌ 構造化データに DocumentReference を使用する → 適切な型付きリソースを使用する
❌ 任意の JSON を保存するために Observation.valueString を使用する → フィールドを適切にモデル化する
❌ ケアプランとして Task を使用する → CarePlan を使用し、各ステップには Task を使用する
❌ 標準フィールドに収まるデータにカスタム拡張を使用する → まずすべてのフィールドを確認する
ステップ 3：用語体系を選択する
モデル内のコード化されたフィールドごとに、適切な用語体系を特定してください。コードを決して独自に作成せず、必ず標準の体系を使用するか、カスタム体系を明示的に定義してください。
用語体系
| システム | FHIR システム URI | 検索 URL |
|---|---|---|
| LOINC | http://loinc.org | https://loinc.org/search/ |
| SNOMED CT | http://snomed.info/sct | https://browser.ihtsdotools.org/ |
| RxNorm | http://www.nlm.nih.gov/research/umls/rxnorm | https://mor.nlm.nih.gov/RxNav/ |
| ICD-10-CM | http://hl7.org/fhir/sid/icd-10-cm | https://clinicaltables.nlm.nih.gov/apidoc/icd10cm/v3/doc.html |
| CPT | http://www.ama-assn.org/go/cpt | https://www.cms.gov/medicare/regulations-guidance/physician-self-referral/list-cpt-hcpcs-codes |
| NCI Thesaurus | http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl | https://ncit.nci.nih.gov/ncitbrowser/ |
| UCUM | http://unitsofmeasure.org | https://ucum.org/ucum |
| HL7 Observation Category | http://terminology.hl7.org/CodeSystem/observation-category | https://terminology.hl7.org/CodeSystem-observation-category.html |
モデル内の各リソースについて、以下を特定します。
- コードが必要なフィールド（
code、category、typeなど） - 使用する用語体系と、データモデルに記録するその FHIR システム URI
ここでは個々のコードを特定しません。データモデルには用語体系のバインディングを記録し、具体的なコードは実装時に上記の検索 URL を使用して調べます。
ステップ 4：プロファイルと実装ガイドを推奨する
準拠する実装ガイド（IG）プロファイルを選択します。準拠するとは、IG の制約と値セットに従い、EHR、保険支払者、レジストリとの相互運用性を実現することです。
実装ガイドの参考情報
| IG | ユースケース | 使用する場合 |
|---|---|---|
| US Core | 一般的な EHR 相互運用性（米国） | 米国の EHR と連携するあらゆるアプリのデフォルト |
| mCODE | 腫瘍学 | がんに特化したアプリ |
| SDOH Clinical Care | 健康の社会的決定要因 | 住居、食料、交通 |
| Gravity Project | SDOH コーディング | SDOH Clinical Care IG と併用 |
| Da Vinci | 保険支払者／医療提供者間の情報交換 | 保険、事前承認 |
| SMART App Launch | OAuth2／EHR アプリの起動 | EHR 内から起動する場合 |
| IPA（国際患者アクセス） | 国際的な EHR アクセス | 米国以外への導入 |
| PACIO | 急性期後ケア | リハビリ、自宅での医療、長期ケア |
| mPOWEr | メンタルヘルス関連の PRO | 患者報告によるメンタルヘルスのアウトカム |
デフォルトの推奨事項： より適切な専門分野の IG がない限り、Patient、Observation、Condition、MedicationRequest には US Core に準拠します。
カスタムプロファイル： 適合する IG プロファイルがない場合は、以下で定義します。
http://[your-app].com/fhir/StructureDefinition/[ResourceType]-[use-case]
ステップ 5：データフローとリソース間の関係を設計する
テキスト図を使用して、リソース同士のつながりを示します。各参照について説明します。
一般的なパターン
アンケート → スコアのパイプライン：
Questionnaire (canonical definition, stored once)
└─ referenced by Task.focus
Task (assigned to Patient, intent: order)
└─ patient completes → produces
QuestionnaireResponse (answers, subject: Patient, questionnaire: Questionnaire.url)
└─ app scores → produces
Observation (derived score, derivedFrom: QuestionnaireResponse)
スケジュールされたタスクを含むケアプラン：
CarePlan (status: active, intent: plan, subject: Patient)
└─ activity[].reference →
Task[] (one per activity, for: Patient)
└─ Task.focus → Questionnaire | MedicationRequest | ServiceRequest
└─ completion → QuestionnaireResponse | Observation
デバイス／ウェアラブルデータ：
Device (wearable or app)
└─ Observation.device → Device
Observation[] (LOINC coded, effectiveDateTime, subject: Patient)
└─ optionally grouped into DiagnosticReport
参照形式（必ず使用）
ResourceType/id e.g. Patient/abc123
正規 URL（Questionnaire、StructureDefinition）の場合：
http://[your-app].com/fhir/Questionnaire/[name]
ステップ 6：データモデル仕様書を作成する
ステップ 1～5 を完了したら、以下の文書を全文出力します。これが主な成果物です。このアプリに固有の詳細をすべてのセクションに記入し、プレースホルダーテキストを残さないでください。
# FHIR Data Model: [App Name]
> Generated by `fhir-data-model-design`. Save as `docs/planning/fhir-data-model.md`.
> Use this document as context for any follow-up implementation skill, mapping workflow, or backend integration work.
## Overview
| Field | Value |
|-------|-------|
| App | [App name and brief description] |
| Use case | [research / clinical / wellness / care coordination] |
| FHIR version | R4 (4.0.1) |
| Base IG | [e.g., US Core 6.1.0] |
| Additional IGs | [e.g., mCODE 3.0, SDOH Clinical Care 2.1] |
| Interoperability | [e.g., self-contained / EHR integration via SMART App Launch] |
---
## Resources
### [ResourceType]: [Clinical Concept]
| Field | Value |
|-------|-------|
| Resource | `[ResourceType]` |
| Profile | `[Profile URL or "Base FHIR R4"]` |
| Clinical use | [What this resource represents in the app] |
**Key fields:**
| Field | Type | Notes |
|-------|------|-------|
| `status` | code | [value set name, e.g., ObservationStatus] |
| `code` | CodeableConcept | Terminology binding (see below) |
| `subject` | Reference | `Patient/{id}` |
| [other fields] | | |
**Terminology bindings:**
| Field | Terminology System | Binding Strength |
|-------|-------------------|-----------------|
| `code` | LOINC (`http://loinc.org`) | required |
| `category` | HL7 Observation Category (`http://terminology.hl7.org/CodeSystem/observation-category`) | preferred |
**Sample FHIR JSON:**
```json
{
"resourceType": "[ResourceType]",
...
}
FHIR R4 仕様： https://hl7.org/fhir/R4/resourcelist.html から開始し、選択したリソースタイプに該当するリソースのページを開きます。
用語バインディング
各コード化フィールドを適用する用語体系を宣言します。具体的なコードは実装時に解決されます。
| リソース | フィールド | 用語体系 | バインディングの強さ | 備考 |
|---|---|---|---|---|
Observation | code | LOINC (http://loinc.org) | 必須 | すべての測定値と所見に使用します |
Observation | category | HL7 Observation Category | 推奨 | vital-signs、survey、laboratory、activity |
Condition | code | SNOMED CT (http://snomed.info/sct) | 推奨 | 請求の文脈では ICD-10-CM も使用できます |
MedicationRequest | medicationCodeableConcept | RxNorm (http://www.nlm.nih.gov/research/umls/rxnorm) | 必須 | 臨床用医薬品 |
Procedure | code | SNOMED CT または CPT | 推奨 | |
| [Resource] | [field] | [System URI] | 必須 / 推奨 / 例 | [任意の備考] |
カスタムコードシステム
標準用語が存在しない概念に対する、アプリ定義のコードシステムです。
| 名前 | URI | 用途 |
|---|---|---|
| [Name] | http://[app].com/fhir/CodeSystem/[name] | [このコードシステムが分類する内容] |
リソース間の関係
[Text diagram showing resource graph]
| 参照 | 始点 | 終点 | 多重度 |
|---|---|---|---|
subject | Observation | Patient | 1..1 |
derivedFrom | Observation | QuestionnaireResponse | 0..* |
focus | Task | Questionnaire | 0..1 |
FHIR REST API のパターン
標準の FHIR REST API です。任意の FHIR R4 サーバー（Medplum、HAPI、Azure Health Data Services、Google Cloud Healthcare など）で動作します。
読み取り
GET /fhir/Patient/{id}
GET /fhir/Questionnaire?url=[canonical-url]
検索
# Patient's observations by code
GET /fhir/Observation?subject=Patient/{id}&code=[loinc-code]&_sort=-date
# Patient's tasks
GET /fhir/Task?patient=Patient/{id}&status=requested
# Questionnaire responses for a specific questionnaire
GET /fhir/QuestionnaireResponse?subject=Patient/{id}&questionnaire=[canonical-url]
# Conditions with clinical status
GET /fhir/Condition?patient=Patient/{id}&clinical-status=active
書き込み
POST /fhir/QuestionnaireResponse # Submit survey response
POST /fhir/Observation # Record a measurement
PUT /fhir/Task/{id} # Update task status
# Atomic multi-resource write
POST /fhir/ # Bundle (type: transaction)
データフロー
主なデータフローの説明です。上記のリソースセクションを参照してください。
- [Flow name]：リソース間でデータがどのように移動するかの説明
- [Flow name]：[説明]
実装上の注意
- [アプリ固有の制約や決定事項]
- [カスタムプロファイルまたは拡張機能が必要となる既知の不足点]
- [必要な用語ライセンス。例：SNOMED CT にはライセンスが必要です]
---
## Reference: FHIR Resources Quick Reference
| Resource | Clinical Use | Required Fields | Key Search Params |
|----------|-------------|-----------------|-------------------|
| `Patient` | Person in the app | — | `identifier`, `name`, `birthdate` |
| `Observation` | Measurement or finding | `status`, `code` | `subject`, `code`, `date`, `category` |
| `Questionnaire` | Survey definition | `status` | `url`, `name` |
| `QuestionnaireResponse` | Completed survey | `status` | `subject`, `questionnaire`, `authored` |
| `Task` | Patient to-do | `status`, `intent` | `patient`, `status`, `code` |
| `CarePlan` | Longitudinal plan | `status`, `intent`, `subject` | `patient`, `status` |
| `Goal` | Target outcome | `lifecycleStatus`, `description`, `subject` | `patient`, `lifecycle-status` |
| `MedicationRequest` | Prescribed medication | `status`, `intent`, `medication[x]`, `subject` | `patient`, `status` |
| `MedicationStatement` | Self-reported medication | `status`, `medication[x]`, `subject` | `patient`, `status` |
| `Condition` | Diagnosis / problem | `code`, `subject` | `patient`, `code`, `clinical-status` |
| `Consent` | Consent agreement | `status`, `scope`, `category`, `policyRule` | `patient`, `status` |
| `DiagnosticReport` | Report grouping Observations | `status`, `code` | `patient`, `code`, `date` |
| `Device` | Wearable / sensor | `status` | `patient`, `type` |
---
## FHIR R4 Spec Links
- [Observation](https://hl7.org/fhir/R4/observation.html)
- [Questionnaire](https://hl7.org/fhir/R4/questionnaire.html)
- [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html)
- [Task](https://hl7.org/fhir/R4/task.html)
- [CarePlan](https://hl7.org/fhir/R4/careplan.html)
- [Patient](https://hl7.org/fhir/R4/patient.html)
- [Condition](https://hl7.org/fhir/R4/condition.html)
- [MedicationRequest](https://hl7.org/fhir/R4/medicationrequest.html)
- [Consent](https://hl7.org/fhir/R4/consent.html)
- [DiagnosticReport](https://hl7.org/fhir/R4/diagnosticreport.html)
- [US Core IG](https://www.hl7.org/fhir/us/core/)
### Terminology Lookup (use these to find codes — do not rely on memorised values)
- [LOINC Search](https://loinc.org/search/)
- [SNOMED CT Browser](https://browser.ihtsdotools.org/)
- [RxNorm Browser (RxNav)](https://mor.nlm.nih.gov/RxNav/)
- [ICD-10-CM API](https://clinicaltables.nlm.nih.gov/apidoc/icd10cm/v3/doc.html)
- [NCI Thesaurus Browser](https://ncit.nci.nih.gov/ncitbrowser/)
- [UCUM](https://ucum.org/ucum)
- [HL7 Observation Category CodeSystem](https://terminology.hl7.org/CodeSystem-observation-category.html)