【Claude Code】Medicare Part D × Text-to-SQL Part0：全体像とハーネス設計

1. 連載の主題

この連載のテーマは agentic coding です。エージェントが自分で計画し、実行し、結果を検証して次の手を決める。そのループが回る状態を人が先に作り、その中で走らせる進め方を指します。

雰囲気で指示を出し、返ってきたコードを読まずに採用する vibe coding とは、人の仕事が違います。人が渡すのはコードではなく、環境・判断基準・停止条件です。 そのために人が組む道具一式を、この連載では「ハーネス」と呼びます。

医療データのアプリは、ハーネスの組み方を具体的に見せるための題材です。誰でも取れる公開データなら、ガバナンスの議論より先に「何を渡し、どこで止め、どう検証するか」を固められ、その型はそのまま社内データに持ち込めます。

アプリの機能を説明するのはこの Part0 だけです。Part1 以降はハーネスの話に絞ります。

2. 題材のアプリ

2-1. 画面

2-2. 機能

• 日本語で聞くと、Claude が SQL を書いて BigQuery で実行し、結果と解釈を返す
• 表・棒グラフ・折れ線・州別地図・CSV を、言い直すだけで切り替えられる
• 生成された SQL はいつでも展開・コピーでき、何を集計したかを人が確かめられる

2-3. 構成

Claude には「SQL の実行」と「グラフ仕様の決定」を別々のツールとして渡しています。SQL をアプリ側で検査してから実行するためです。

3. 題材のデータ

米国の公的保険 Medicare の薬剤給付（Part D）を、処方医 × 薬剤ごとに年次集計して医師名付きで公開したデータです。3年分で約 8,000万行あり、CSV で誰でも取得できます。日本の NDB オープンデータにはない粒度で、請求ベース・集計済み・少数セルの抑制ありという、実務の RWD に近い構造を持っています。

制度とデータ構造の詳細は、データ説明ページ「Medicare Part D」に分けてあります。

4. ハーネスの全体像

道具	役割	このリポジトリでの実体
プロジェクト文書	作業の順序・制約・用語の正本	CLAUDE.md、docs/design.md・data_dictionary.md・DECISIONS.md・HARNESS.md
権限と停止条件	どのコマンドを通し、どれを人が確認し、どれを拒否するか	.claude/settings.json（allow / ask / deny）
MCP	外部システムをエージェントの道具として接続する	.mcp.json：BigQuery を読み取り専用で接続
skill	繰り返す手順を、呼び出せる形で持たせる	.claude/skills/ の7本
hook	検査を、人が覚えていなくても走らせる	.claude/hooks/ の3本
評価	正解のある問いで成果物を測る	精度評価30問、ガードの単体テスト50ケース

.claude/
├── settings.json        権限（allow / ask / deny）と hook の登録
├── skills/
│   ├── cms-csv-to-bigquery/   CSV の取得から BigQuery 投入まで
│   ├── verify-data/           投入結果の検証（MCP だけで動く）
│   ├── display-check/         数値の表示崩れの点検
│   ├── guard-glossary-update/ 失敗した質問から辞書・ガードを直す
│   ├── eval/                  精度評価と記録（人だけが起動）
│   ├── deploy/                Cloud Run への公開（人だけが起動）
│   └── sync-public/           公開リポジトリへの同期（人だけが起動）
└── hooks/
    ├── billing_gate.py        --plan を見ていない投入を止める
    └── post_edit_checks.py    編集後にテスト・ruff・tsc
.mcp.json                    BigQuery MCP の接続

skill には、Claude が状況を見て自分で呼べるものと、人だけが起動できるものがあります。課金が発生する評価・公開・外部への同期は後者にしました。どの道具に何を任せ、どこで人が止めるかを決めることが、ハーネス設計の中身です。

5. ハーネスが肩代わりする工程

ハーネスがなくても、CLAUDE.md に「課金が出るコマンドは実行前に見せること」と書いておけば、エージェントはおおむね従います。ただしそれは文章の約束で、守られたかどうかは人が毎回目で確かめるしかありません。確認・検証・手順の記憶が、全部人の手に残ります。

文書だけのとき、人がやること	肩代わりする道具
課金が出るコマンドを、実行前に目で確認する	権限の ask。投入は hook が「直前に --plan を見たか」まで確かめる
.env や鍵を読ませないよう気を配る	権限の deny
投入後の行数・型を BigQuery コンソールで見て貼る	読み取り専用の BigQuery MCP と /verify-data
「テスト回して」「tsc 通して」と毎回指示する	編集後に自動で走る hook
投入・評価・公開の手順を、過去の記録から思い出す	skill 7本

ハーネスを組むと、文章の約束は設定による強制に、人の記憶は呼び出せる手順に置き換わります。人に残るのは、ask で止まったところの判断と、評価結果の読み取りです。各 Part では、道具ごとに「ないとき人が何をするか／あると何が消えるか」を並べてお見せします。

6. 連載の構成

Part	タイトル	ハーネスの主題	題材
0	全体像とハーネス設計（本記事）	全体像	アプリとデータの紹介
1	環境設定と MCP	権限（allow / ask / deny）、BigQuery MCP	データ取得と BigQuery 投入
2	プロジェクト文書と skill	CLAUDE.md の書き方、skill にする手順の選び方	SQL 生成とツール分離
3	プロンプト設計と hook	指示の境界条件、hook による強制	UI 実装と表示崩れ
4	評価と運用	評価セット、改善ループ、記録	30問評価・モデル比較・Cloud Run（任意）

各 Part では毎回、走らせる前に人が用意したもの／指示に入れた境界条件／人が決めたことと実行が見つけたことの3点を、実際の画面と一緒に書きます。

7. 配布方針

アプリは常時公開せず、コード一式を GitHub で公開します（MIT）。読者は clone して、自分の Anthropic API キーと自分の Google Cloud プロジェクトで動かします。.claude/ と .mcp.json もリポジトリに含めてあるので、Claude Code で開けば同じハーネスで作業できます。有効にする手順は README にあります。

8. まとめ

この連載の主題は agentic coding で、医療データのアプリは題材です。第1作では、文書・権限・MCP・skill・hook・評価の6つを組み、人が繰り返す確認と手順をハーネスに肩代わりさせました。任せられる範囲は、事前にどれだけ検証可能にしておいたかで決まります。

次のステップ

Part1 では、作業環境を整えます。.claude/settings.json で「確認なしで通すもの／人が確認するもの／拒否するもの」を分け、BigQuery を読み取り専用の MCP でつなぎます。題材は、CMS の CSV を取得して BigQuery に載せる工程です。投入の結果を、人ではなくエージェント自身が MCP で確かめるところまでをお見せします。