メダリオンアーキテクチャとClaudeスキル｜層に置くのはデータだけ

Claude のスキルが増えてきたので、メダリオンアーキテクチャで整理しようとしました。ブロンズ、シルバー、ゴールドの3層でデータを段階的にきれいにしていく、Databricks が提唱したあの設計パターンです。ところが「SKILL.md はどの層なのか」を決めようとして、そこで止まりました。シルバーにもゴールドにも見えて、決め手がありません。

原典に戻ったら、理由がわかりました。Databricks 公式も Microsoft Learn も、ブロンズ、シルバー、ゴールドを一貫して「データ（テーブル）の階層」として定義しています。一方で変換処理は、dbt ではモデルという名前の .sql ファイル、Databricks ではパイプラインのソースコードとして扱われ、Git で管理されます。層に置かれるのはデータだけで、コードは層の外にいます。

つまり「SKILL.md はどの層か」という問いは、dbt で「この .sql ファイルはブロンズテーブルですか」と聞いているのと同じ形をしています。カテゴリが一段ずれているので、どちらの答えを選んでも噛み合いません。SKILL.md は層ではなく、層を動かすロジックです。

そう置き直すと、対応関係がきれいに決まります。スキルが読む生の素材がブロンズ、整えたナレッジがシルバー、出てくる成果物がゴールドです。SKILL.md は dbt のモデル、CLAUDE.md はプロジェクト設定ファイル、rules/ はマクロ、Stop フックはテストに当たります。Anthropic の公式ドキュメントが「CLAUDE.md の一節が事実ではなく手順に育ったらスキルにしろ」と書いているのも、データとロジックを分けるのとまったく同じ線です。

この記事では、原典の定義を確認したうえで問いを立て直し、~/.claude/ の具体的なディレクトリ設計、スキル本体を薄く保つ理由、層を壊す4つの失敗パターン、そしてアナロジーをどこで手放すべきかの境界線までを扱います。3層は義務ではありません。Databricks 自身が「推奨であって必須ではない」と明記しています。借りる価値があるのは3つだけだ、というところまで絞り込みます。

メダリオンアーキテクチャは「データの置き場」を決める設計パターン

先に用語を揃えておきます。メダリオンアーキテクチャは Databricks が提唱したデータ設計パターンで、ブロンズ、シルバー、ゴールドという3つの層にデータを分け、右へ進むほど品質を上げていく形をとります。この章で押さえたいのは、各層が何を引き受けるのかと、公式が「層」という言葉で何を指しているのかの2点です。ここを曖昧にしたまま進むと、あとの話が全部ぼやけてしまいます。

メダリオンアーキテクチャは、Databricks が提唱したデータの整理方法です。公式の用語集では「レイクハウス内のデータを論理的に整理するためのデータ設計パターン」と定義されていて、目的は「データがブロンズ、シルバー、ゴールドの各層を通過するにつれて、構造と品質を段階的に改善すること」だとされています（Databricks 用語集）。名前はオリンピックのメダルから来ています。文中のレイクハウスは、大量の生データをそのまま置いておける保管庫と、集計や分析に強いデータベースを1つにまとめた基盤のことです。

具体的な例で見ると輪郭が掴みやすくなります。ネットショップの注文データを扱う場合、決済システムから届いた生の JSON をそのまま貯めておくのがブロンズです。そこから重複した注文を取り除き、日付の書き方を揃え、顧客の一覧と結合して1行1注文の表にするのがシルバーになります。さらに月別や地域別に集計して、営業チームのダッシュボードがそのまま読み込める形にしたものがゴールドです。右へ進むほど手が加わり、その分だけ使い道が限定されていきます。

ブロンズ層は、あえて汚いまま置く

ブロンズ層はソースから来たデータの着地点です。Databricks の定義では「この層のテーブル構造は、ソースシステムのテーブル構造にそのまま対応する」とされています。列名も型も直しません。

わざと汚いまま置くのには理由があります。Microsoft Learn の研修モジュールにある説明が一番わかりやすいので引用します。

データをここで生のまま保つのは意図的なものです。下流の変換がうまくいかなかったとき、ソースシステムまで戻らずにブロンズから再処理できます。
（Microsoft Learn、筆者訳）

つまりブロンズ層は「やり直しの起点」です。Microsoft Learn の別ページでは、ブロンズ層は「生の、検証されていないデータ」を含み、「データの忠実度を保つ単一の情報源として機能する」と書かれています（Microsoft Learn）。

シルバー層は、使える形に揃える

シルバー層では、ブロンズのデータを照合し、統合し、整合させ、クレンジングします。Databricks の定義では、その結果として主要なビジネスの実体や取引についての「全社共通のビュー」を提供できる状態にする、とされています。

Microsoft Learn がシルバー層で行う操作として挙げているのは、スキーマの強制、欠損値の処理、重複排除、遅れて到着したデータの解決、データ品質チェック、スキーマ進化、型変換、結合の8つです。ここが一番地味で、一番手間がかかる層になります。

ゴールド層は、目的別に作り分ける

ゴールド層は、Databricks の言葉では「すぐに使える案件固有のデータベース」です。レポート用に非正規化して、結合を減らし、読み取りの速さを優先します。非正規化というのは、複数の表に分けて持っていた情報をあえて1つの表にまとめ直すことです。分けて持つほうが更新はしやすいのですが、読むたびに表をつなぎ合わせる手間がかかります。更新が月に1回でも読み込みは毎日何百回、という使われ方なら、あらかじめまとめておいたほうが速くなります。

大事なのは、ゴールドは1つではなくてよいという点です。公式にこう書かれています。

ゴールド層はビジネスドメインをモデル化するため、人事、財務、IT といった異なるビジネスニーズに応えるために複数のゴールド層を作る顧客もいます。
（Microsoft Learn、筆者訳）

ここまでで、ひとつ引っかかってほしいところ

定義を読むときに注意して見てほしいのは、公式が何を「層」と呼んでいるかです。

Databricks の定義文は「ブロンズ、シルバー、ゴールドの各層のテーブル（layer tables）」と書きます。Microsoft Learn は「レイクハウスに保存されたデータの品質を示す一連のデータ層（data layers）」と書きます。層という言葉が修飾しているのは、どちらも一貫してテーブル、つまりデータの置き場です。

処理ではありません。層という言葉はデータの置き場を指していて、そのデータを動かす処理は層の外にあります。この区別が、スキルをどこに置くかを決めるときにそのまま効いてきます。

「スキルはどの層に入るのか」という問いが噛み合わない理由

私がこの記事を書こうと思ったきっかけは、自分でこの問いに詰まったことでした。結論を先に書くと、SKILL.md はどの層でもありません。層に置かれるのはデータだけで、SKILL.md はそのデータを動かすロジックの側にあります。なぜそう言えるのかを、dbt と Databricks の原典で確かめていきます。

~/.claude/skills/ の下にスキルが増えてきて、そろそろ整理の軸がほしくなりました。メダリオンを知っていたので、当然のように「SKILL.md はブロンズ、シルバー、ゴールドのどれだろう」と考え始めたのです。

もっともらしい候補は2つ出てきました。

ひとつはシルバー説です。SKILL.md はドメインの知識を構造化して再利用できる形にした中間資産で、いろいろな業務から呼ばれます。全社共通のビューを提供するシルバー層の性質に近いように見えます。

もうひとつはゴールド説です。SKILL.md は特定の業務向けに最適化された成果物で、ユーザーが直接使う終点でもあります。案件ごとに切り出したデータマート（特定の部署や用途だけのために作られた小さなデータベース）に近いようにも見えます。

どちらもそれらしく聞こえて、決め手がありませんでした。こうなるときはたいてい、答えが見つからないのではなく、問いの立て方のほうがおかしい気がしてきます。そこで原典に戻りました。

dbt の「モデル」とは何か

データ変換ツールの dbt には、staging、intermediate、marts という3階層のモデル構成があります。メダリオンとよく対比される考え方です。

その dbt で「モデル」が何と定義されているかを見ると、はっきりします。

モデルは主に select 文として書かれ、.sql ファイルとして保存されます。
（dbt 公式ドキュメント、筆者訳）

dbt-core の README には、さらに直接的な一文があります。

dbt を使うアナリストは、単に select 文を書くだけでデータを変換できます。dbt がそれらの文をデータウェアハウス内のテーブルやビューに変える処理を引き受けます。
（dbt-core README、筆者訳）

select 文（コード）と、テーブルやビュー（データ）は、別のものとして書かれています。あいだに「実行」というステップが挟まっているからです。

Databricks 側も同じ線を引いている

Databricks のパイプラインの定義も見てみます。

パイプラインとは、ソースコードファイルの集まりと設定です。ソースファイルは、データセット（ストリーミングテーブル、マテリアライズドビュー、ビュー）と、それらを生成するクエリやフローを宣言します。
（Databricks 公式ドキュメント、筆者訳）

ソースコードがデータセットを宣言する、という構文になっています。コードが主語で、データセットが目的語です。

メダリオンの説明でも同じ書き方をしています。

Databricks は Spark Declarative Pipelines のようなツールを提供しており、わずか数行のコードから、ブロンズ、シルバー、ゴールドのテーブルを持つデータパイプラインをすぐに構築できます。
（Databricks 用語集、筆者訳）

コードでブロンズ、シルバー、ゴールドのテーブルを作るのであって、コードがブロンズ、シルバー、ゴールドなのではありません。

コードとデータは、そもそも置き場所が違う

置き場所を見ると、この分離はもっとはっきりします。

dbt はコードを Git でバージョン管理するのが前提です（dbt 公式ドキュメント）。そして dbt が生成する標準の .gitignore は、コンパイル済み SQL や実行結果が入る target/ を除外します。コードは Git に入れ、実行して出てきたものは Git に入れない、という線引きが最初から引かれているわけです。

Databricks も同じで、ノートブックやパイプラインのソースコードは Git folders を通じて Git 管理するのが公式の推奨手順になっています（Databricks 公式ドキュメント）。

一方、ブロンズ、シルバー、ゴールドのテーブルは Git に入れません。ストレージに置かれます。

ダメ押しの事実

dbt 公式の構成ガイド「How we structure our dbt projects」は4ページありますが、この4ページ全体に medallion、bronze、silver、gold という語が一度も出てきません。目視と grep の両方で確認して、ヒットはゼロでした。調べていて一番面白かったのがここです。メダリオンとよく並べて語られる dbt が、実は自分の語彙（staging / intermediate / marts）だけで完結していて、メダリオンの用語を借りていません。

dbt がメダリオンとの対応表を出しているのは、Databricks 上で dbt を動かすときのガイドだけです（dbt 公式ガイド）。そしてそれは「dbt のモデルが生成する物理テーブルがブロンズ相当のテーブルになる」という文脈であって、「モデルがブロンズである」とは書かれていません。

結論を言い切ります

SKILL.md は層ではありません。層を動かすロジックです。

dbt でいえばモデル、Databricks でいえばパイプラインのソースコードに当たります。「SKILL.md はブロンズ、シルバー、ゴールドのどれか」という問いは、dbt で「この .sql ファイルはブロンズテーブルですか」と聞いているのと同じ形をしています。カテゴリが一段ずれているので、どちらの答えを選んでも噛み合いません。

補強材料をひとつ挙げておきます。Anthropic の公式ドキュメントは、スキルを作るべきタイミングをこう説明しています。

同じ指示やチェックリスト、複数手順の作業をチャットに貼り続けているとき、あるいは CLAUDE.md のある節が事実（fact）ではなく手順（procedure）に育ってしまったときに、スキルを作ってください。
（Claude Code ドキュメント、筆者訳）

事実は CLAUDE.md へ、手順はスキルへ。この線引きはデータエンジニアリングとは無関係な文脈で書かれたものですが、データとロジックを分ける線と、まったく同じところに線が引かれています。独立に同じ結論に届いているのは、この分離が偶然ではないことの傍証になります。

~/.claude/ の中で、ブロンズとシルバーとゴールドはどこにあるのか

「スキルは層ではない」で話を終えると、宙に浮いてしまいます。では層はどこにあるのか。

答えは、スキルが読むものと、スキルが出すものの中にあります。スキル自体は層の外にいて、層のあいだでデータを動かす役です。

対応表

一次資料に照らして矛盾しない形にすると、こうなります。

データ基盤の世界	~/.claude/ を含む手元の世界	中身の例
ブロンズテーブル	生の素材	議事録の録音と生の書き起こし、スクレイピング結果、API の生レスポンス、過去に自分が書いたレビューコメントそのまま
シルバーテーブル	整えたナレッジ	用語集、表記を統一した調査メモ、rules/ に置いた共通の判断基準
ゴールドテーブル	成果物	記事、提案書、レポート、スライド、納品用 CSV
dbt のモデル（.sql）	SKILL.md	手順そのもの。読み込むのは起動したときだけ
dbt_project.yml	CLAUDE.md	常時読まれる設定。事実とルールの入口
dbt のマクロ	rules/*.md	複数のスキルが参照する再利用ロジック
dbt のテスト	Stop フック	完了を宣言する前に通す品質ゲート
Git リポジトリ	~/.claude/ を Git 管理する	コードは版管理、実行結果は版管理しない

ディレクトリで見ると、線がどこにあるかがわかる

言葉より、実際の配置を見たほうが早いです。私の手元はこうなっています。

~/.claude/                        ← ロジック側。Git で管理する
├── CLAUDE.md                     ← 常時読まれる設定
├── rules/                        ← 複数スキルが参照する共通の判断基準
│   ├── japanese-no-extra-spaces.md
│   └── okf-markdown-knowledge.md
└── skills/
    └── deep-research-pro/
        ├── SKILL.md              ← 手順。174行
        ├── phases/               ← 必要になってから読む詳細
        ├── references/
        └── scripts/              ← 実行するコード

~/work/20260729-topic/            ← 素材と成果物の側。Git 管理は任意
├── raw/                          ← ブロンズ
│   ├── 20260729-scrape/
│   └── interview-recording.m4a
├── notes/                        ← シルバー
│   ├── glossary.md
│   └── research.md
└── output/                       ← ゴールド
    └── article.md

見てほしいのは、ディレクトリツリーが2つに割れていることです。上がロジック、下が素材と成果物です。この分割が、そのまま「層とロジックは別物」という結論の実装になっています。

実際にスキルが走るとき何が起きるかというと、記事を書くスキルは raw/ の調査結果を読み、notes/ の用語集と rules/ の判断基準に照らして、output/ に記事を出します。ブロンズを読み、シルバーを参照して、ゴールドを書きます。dbt のモデルがやっていることと、構造は同じです。

ブロンズの掟は「触らない」

一番守りにくいのがブロンズです。生のまま置くのは、片付いていないようで気持ち悪いからです。

しかし、ここで手を入れると後で困ります。データ基盤の現場で観測された症状として、こんな指摘があります。

「一貫性のために」列名の変更を取り込み時に適用してしまう。するともう、ブロンズとソースシステムの差分が取れなくなります。
「容量を節約するために」ブロンズで重複排除する。おめでとうございます、ソースシステムが二重に発火したことを教えてくれたはずの重複を、あなたは捨てました。
（Algoscale、筆者訳）

同じことが手元でも起きます。議事録の生の書き起こしを消して要約だけ残すと、要約が間違っていたときに戻る先がなくなります。私は日付付きのディレクトリに入れて、上書きしないことだけを決めています。

シルバーは「2回目に気づく」

シルバー層の必要性は、最初は実感しにくいところです。1つのスキルしか持っていないうちは、判断基準をその SKILL.md に直接書いておけば足りるからです。

必要性に気づくのは2つ目のスキルを作るときです。同じ「日本語に余計なスペースを入れない」という基準を、記事執筆スキルと議事録スキルの両方に書くことになります。そして片方だけ直して、もう片方が古いまま残ります。

だから rules/ に切り出して、両方から参照します。dbt でいうマクロと同じ役割です。判断基準がひとつの場所にあれば、直すのも1回で済みます。

同じことを、はるかに大きな規模で測った例があります。Meta のエンジニアリングチームは、4つのリポジトリ・3言語・4,100を超えるファイルにまたがるデータパイプラインで、50以上の専門エージェントに全ファイルを読ませ、59個の簡潔なコンテキストファイルを事前に作らせました。

結果として、AI エージェントが構造化された案内を参照できるコードモジュールの割合は5%から100%になり、1タスクあたりのツール呼び出しは約40%減ったと報告されています（Engineering at Meta、2026年4月）。エージェントごとに毎回ゼロから調べさせるより、共有できる形で一度作っておくほうが安く済みます。手元のスキルが3本か4本かという規模でも、働いている原理は同じです。

ゴールドは複数あっていい

ゴールドは目的別に作り分けるものです。同じ調査結果から、社内共有用のメモと、クライアント提出用の資料と、ブログ記事を作ることがあります。これは3つのゴールドであって、統一する必要はありません。

Databricks 公式も、人事・財務・IT のように業務ドメインごとに複数のゴールド層を持つ顧客がいると書いています。ここは無理にひとつにまとめないほうが健全です。

スキルを1本ずつ作る具体的な手順は、Claudeでフィードバックスキルを作る記事で7ステップにまとめています。この記事は、そうやって作ったスキルが増えてきたあとの整理の話をしています。

スキル本体は積み上げるのではなく、薄くする

ここで、借りたアナロジーが効かなくなる場所を先に出しておきます。あとで気づくより、先に線を引いておいたほうが使いやすいためです。結論を書くと、SKILL.md 本体は500行以内に収めるのが公式の推奨で、薄いほどうまく動きます。理由は読み込みの仕組みと、スキル全体で約2,000文字というコンテキスト予算の2つです。

データ基盤では、層を積むほど価値が上がります。ブロンズよりシルバー、シルバーよりゴールドのほうが手が加わっていて、業務に近づきます。積み上げるほど価値が上がる構造です。

スキルは逆になります。

読み込みは3段階に分かれている

理由は Claude がスキルを読む仕組みにあります。Anthropic はこれを progressive disclosure（段階的開示）と呼んでいます。

起動時、エージェントはインストールされているすべてのスキルの name と description をシステムプロンプトに事前読み込みします。このメタデータが段階的開示の第1段階です。（中略）このファイルの本体が第2段階の詳細です。（中略）リンクされた追加ファイルが第3段階（およびそれ以降）の詳細で、Claude は必要になったときにだけ辿って発見できます。
（Anthropic Engineering、筆者訳）

公式ドキュメントには、トークン数の目安つきの表があります。

段階	読まれるタイミング	トークンコスト	中身
第1段階: メタデータ	常時（起動時）	スキル1つあたり約100トークン	ファイル冒頭の設定欄（frontmatter）に書いた name と description
第2段階: 手順	スキルが起動したとき	5,000トークン未満	SKILL.md の本文
第3段階以降: 参照資料	必要になったとき	読むまでゼロ	同梱ファイル

出典は Claude 公式ドキュメント です。同じページに「スキルが起動するまで、コンテキストを占めるのは name と description だけ」と書かれています。

この仕組みのおかげで「スキルに同梱できるコンテキストの量は事実上、無制限になる」と Anthropic は説明しています。ただし無制限なのは同梱できる量であって、一度に読ませてよい量ではありません。

長いほど思い出せなくなる

薄くすべき理由は、コンテキストが長くなるほど精度が落ちるためです。Anthropic はこれを context rot（コンテキストの腐敗）と呼んでいます。

コンテキストウィンドウ内のトークン数が増えるにつれて、そのコンテキストから情報を正確に思い出すモデルの能力は低下します。モデルによって劣化の緩やかさに差はありますが、この特性はすべてのモデルに現れます。
（Anthropic Engineering、筆者訳）

原因はモデルの仕組みそのものにあります。いまの大規模言語モデルが使っている Transformer という構造では、すべての単語が他のすべての単語を参照できるようになっています。そのため、単語が n 個あると n×n 通りの関係を同時に見ることになります。単語が2倍になれば関係は4倍です。1つの単語に向けられる注意が、その分だけ薄く広がってしまいます。

同じ記事は、良いコンテキスト設計の原則をこう定義しています。

望む結果が得られる確率を最大化する、可能なかぎり小さな高信号トークンの集合を見つけること。
（Anthropic Engineering、筆者訳）

コンテキストエンジニアリングの考え方そのものについては、Claude Opus 5とコンテキストエンジニアリングの記事で詳しく扱っています。

スキルは無限に増やせない、という実務上の上限

もうひとつ、設計を強制してくる制約があります。コンテキスト予算です。

スキルの name と description は常時システムプロンプトに載ります。ということは、スキルの数だけこの固定費がかかります。20万トークンのモデルでは、既定で全スキル合計およそ2,000文字ほどしか割り当てられないという検証があります。スキルが50個あれば、1つあたり平均40文字です（DevelopersIO）。

予算を超えると、呼び出し頻度の低いスキルから description が丸ごと削除されます。短く切り詰められるのではなく、消えます。名前だけが残るので、Claude はそのスキルをいつ使えばよいか判断できなくなります。

スキルを100個作れば100倍賢くなる、とはならないわけです。増やすほど1つあたりの説明が痩せて、発火しなくなります。だから整理の軸が要ります。この記事を書いている動機も、結局はここにあります。トークンをどこに使うかという観点は、Return on Tokenでの運用の見直しでも扱っています。

手順は本体に、知識は参照ファイルに

では何を本体に書き、何を外に出すのか。公式の推奨は明快です。

• SKILL.md 本体は500行以内に収める
• 参照は SKILL.md から1階層だけにする。ネストさせない
• description は三人称で書き、「いつ使うか」を具体的に書く

（Anthropic 公式のベストプラクティス）

書き分けの基準としては、次の言い方がわかりやすいと思いました。

手順は skill.md に、コンテキストは参照ファイルに置く。
（MindStudio、筆者訳）

同じ記事は、参照ファイル側に置くべきものとして、ブランドガイドライン、ドメインの定義、良い出力と悪い出力の例、エッジケースの処理、データのスキーマ、背景知識を挙げています。これらは「作業しながら知っておくべきこと」であって、「作業の手順」ではないからです。

手元のスキルを数えてみたら、この形になっていました。

スキル	SKILL.md の行数	外に出しているもの
seo-article-pipeline	387行	rules/ 12ファイル、helpers/ 6スクリプト
deep-research-pro	174行	phases/ 5ファイル、references/ 2ファイル、scripts/ 1本
tavily-search	140行	helpers/ 1ファイル

3つとも、SKILL.md 本体は目次と要点に徹していて、詳細は外部ファイルへのリンクになっています。意識して揃えたわけではなく、書いているうちにこうなりました。本体に全部書くと、次に開いたとき自分が読み切れないためです。

ここが、層のアナロジーが効かない場所

段階が3つあるので層に見えますが、別物です。

メダリオンの3層は、データの品質を段階的に上げていく仕組みです。ブロンズよりゴールドのほうが加工されています。progressive disclosure の3段階は、読み込む量を減らす仕組みです。第1段階より第3段階のほうが詳しいだけで、品質が上がっているわけではありません。

同じ「3つ」でも、片方は価値の階段、もう片方は読み込みの節約です。ここを混ぜると、「参照ファイルはゴールド層だ」のような、それらしいけれど何の指針にもならない対応表ができあがります。

層を壊す4つのやり方

設計論を読んでも、自分の環境が壊れているかどうかは判断しにくいものです。症状から入ったほうが早いので、実際に起きる壊れ方を4つ挙げます。生の素材を上書きする、中間の共通化を飛ばす、成果物に生ログを混ぜる、共通の層に案件固有のルールを書く、の4つです。データ基盤で報告されている失敗と、手元で同じ形が再現する例を並べました。

壊し方1: 生の素材を上書きする

症状としては、スキルの出力がおかしいのに、どこで狂ったのかを追えません。調査結果が間違っていたのか、要約する段階でねじれたのか、記事にする段階で誤読したのかが切り分けられない状態です。

原因は、生の素材を残していないことです。スクレイピングした生の HTML を消して要約だけ残したり、議事録の書き起こしを消して決定事項だけ残したりします。整理としては正しく見えますが、間違いが見つかったときに戻る先が消えています。

直し方は単純で、生を別ディレクトリに日付付きで置き、二度と触らないことです。ブロンズ層が「やり直しの起点」であるのと同じ役割を持たせます。ディスクは安いので、迷ったら残してください。

壊し方2: 中間の共通化を飛ばす

症状は、似たようなスキルが増えていくことです。そして同じ判断基準が、3つの SKILL.md に少しずつ違う言い回しで書いてあります。片方を直したときに、もう片方を直し忘れます。

原因は、共通のナレッジ層を作らずに、各スキルへ直接書いたことです。データ基盤でいうブロンズからゴールドへの直行にあたります。

補足しておくと、直行そのものが常に悪いわけではありません。r/databricks の実務者はこう書いています。

メダリオンアーキテクチャは厳格なものではありません。層を1つ飛ばしてもシステムが崩壊することはありません。私の扱っているものの多くはブロンズからゴールドへ直行していますが、何年もうまくいっています。
（Reddit r/databricks、筆者訳）

判断の分かれ目は、その判断基準を使う場所が1つか複数かです。1つのスキルでしか使わないなら SKILL.md に書いて構いません。2つ目が現れた時点で rules/ に切り出します。私は「2回書いたら共通化する」を目安にしています。

壊し方3: 成果物に生ログを混ぜる

症状は、コンテキストが膨らんでいるのに精度が上がらないことです。スキルに大量の資料を読ませているのに、出力が雑になります。

原因は、整えていない素材をそのまま読ませていることです。前の章で見たとおり、トークンが増えるほど思い出す精度は落ちます。生ログを丸ごと渡すのは、精度を自分から下げにいく行為になります。

直し方は、スキルが常時読むのはシルバー層、つまり整えたナレッジだけにすることです。ブロンズを読むのは、間違いが見つかって再処理するときに限ります。

壊し方4: 共通の層に、案件固有のルールを書く

これが一番わかりにくい壊れ方です。データ基盤では semantic sprawl（意味の氾濫）と呼ばれています。

シルバーテーブルに直接ビジネス KPI や重い集約を作り始めると、落とし穴が生まれます。異なるチームが指標をそれぞれ違う形で定義してしまい、どれが正式版なのかが存在しなくなるのです。
（Data Engineering Weekly、筆者訳）

手元で起きるのは、こういう形です。汎用の rules/ に「A社の案件では敬体を使わない」と書いてしまいます。すると B 社の資料を作るときにもそのルールが読まれて、意図しない出力になります。

直し方は、置き場所を分けることです。どのプロジェクトでも成り立つ判断はユーザースコープの ~/.claude/rules/ に、案件固有の判断はプロジェクトの .claude/ に置きます。判断がどこまで通用するかで、置く場所を決めます。

書いてあるだけでは、守られない

ここまでの4つは、全部「わかっていても守れない」類のものです。急いでいるときほど、生を消し、共通化を後回しにし、生ログを丸ごと投げます。

指示を書くだけでは守られないというのは、実際に測られています。2026年6月に公開された TRACE という研究は、実際のユーザーが感じた不満から作った課題で、メモリー機能に覚えさせただけの場合、当てはまるはずのチェックの57.5%が破られたままだったと報告しています。

同じ研究は、コーディングエージェントのベンチマークでも測っています。何もしないと違反率が100%になる課題群に対し、ユーザーの修正指示をルールに書き直して実行時の検査に変換したところ、違反率は37.6%まで下がりました（Zhou et al., arXiv:2606.13174）。覚えさせるだけでは足りず、完了前に機械的に検査する仕組みが要る、というのがこの研究の主張です。そもそもClaudeのメモリーは学習とは別の仕組みなので、覚えさせたつもりでも次の作業で読まれるとは限りません。

Claude Code では Stop フックがこれに当たります。ターンが完了する前に走り、非ゼロで終了すると完了を宣言できません。公式ドキュメントにも、すべての単体テストが通ることを完了前に検証する例が載っています（Claude Code ドキュメント）。

データ基盤でいえば、dbt のテストや Lakeflow の expectations に当たる位置です。層を積むだけでは品質は担保されず、各層の出口に検査を置いて初めて担保されます。

手元の例を挙げると、deep-research-pro スキルには次を判定するシェルスクリプトを仕込んでいます。

• 本文中に引用 URL が3件以上あるか
• 見出しが3個以上あるか
• 本文が1,500文字以上あるか

どれかが欠けると非ゼロで終了するので、薄いレポートのまま完了できません。判定はどれも grep と wc で済む単純なものです。凝ったチェックを作ろうとすると作らないまま終わるので、機械的に測れるものだけを、確実に測る形にしています。

自分のスキルに検証を足すなら、まず「このスキルが成功したと言える状態」を1文で書いてみるのが早いです。1文で書けないなら、まだ要件が固まっていない合図なので、フックより先に設計に戻ります。

3層は法律ではない｜どこまで借りて、どこで手を離すか

ここまで読んで「うちのスキルも3層にしないといけないのか」と感じたなら、それは私の書き方が悪かったところです。3層は義務ではありません。

公式が先に逃げ道を用意している

Databricks 自身が、はっきりこう書いています。

メダリオンアーキテクチャに従うことは推奨されるベストプラクティスですが、必須ではありません。
（Databricks 公式ドキュメント（日本語版））

Microsoft Learn の研修モジュールも同じ立場です。

3層のパターンは出発点であって、厳格なルールではありません。ユースケースによっては、特定の形式で届くデータのためにブロンズの前にランディングゾーンを追加したり、特定チームのニーズのためにゴールドの先にドメイン固有の層を追加したりすることもあります。層の名前と数は柔軟です。
（Microsoft Learn、筆者訳）

Delta Lake の公式ブログはもっと踏み込んでいて、「メダリオンモデルでデータアーキテクチャを構築する必要はないし、ブロンズ、シルバー、ゴールドといったメダリオンの命名法を使う必要もない」と書いています（Delta Lake）。

提唱している側が、ここまで明確に「守らなくていい」と言っている設計パターンも珍しいと思います。

実務者は「昔からある話」と見ている

批判も見ておきます。よく指摘されるのは、目新しさがないという点です。

私たちにも、ステージング（STG）、オペレーショナルデータストア（ODS）、データウェアハウス（DWH）といった3つ（ときにはそれ以上）のデータ層がありました。それぞれに目的があり、メダリオンアーキテクチャによく似ています。（中略）私にとってメダリオンアーキテクチャは、データの世界ですでに見てきた概念の、もう一度の反復にすぎません。
（Xebia、筆者訳）

この指摘は技術的に妥当だと思います。ブロンズはステージング、シルバーは ODS や DWH にほぼ対応します。

ただ、だから無価値かというとそうは思いません。20年前から現場でやっていたことに共通の名前がついたおかげで、「この処理はシルバーでやるべきか」という会話が成立するようになりました。設計の話を短い言葉で交換できるようになったこと自体が、この用語の実質だと考えています。

境界が曖昧だという批判もあります。実際、シルバーとゴールドの線引きは公式でも揺れていて、Microsoft Learn には「集約表現が多くの下流ワークロードを駆動するなら、それらの表現はシルバー層にあるかもしれないが、通常はゴールド層にある」という書き方が残っています。公式が厳密に規定していないので、現場が迷うのは当然です。

Platinum 層と言われたら、まず誰の定義かを聞く

もうひとつ整理しておきたいのが、最近よく見る Platinum 層（プラチナ層）です。

先に事実を書くと、Databricks の公式ドキュメント、公式ブログ、Microsoft Learn、Delta Lake のどこにも Platinum という記載はありません。Google Cloud 側から提案された拡張であって、業界標準ではありません。

しかも、中身が提唱者ごとに食い違っています。

出典	Platinum 層の構成
Google Cloud Japan（原典）	セマンティックレイヤー、ナレッジグラフ、ガバナンス、マルチモーダル、リアルタイムの5要素
G-gen Tech Blog	3要素に縮小（ガバナンスとリアルタイムを除く）
Zenn（suwash）	フィーチャーストアやベクトル埋め込みなど、上記2つとほぼ重ならない独自の定義

これ以外の解釈もあり、透明性・信頼性・即応性という切り口で各層を捉え直すベンダー記事もあります。同じ言葉で違うものを指しているので、「うちも Platinum 層を作ろう」という会話は、それだけでは噛み合いません。誰の定義かを確認するところから始める必要があります。

新しい概念なので定義が固まっていないだけ、とも言えます。ただ、固まっていないものを「業界標準に従います」と言って持ち込むと、あとで別の定義を持った人と話が合わなくなります。この記事の前半で原典を確認したのと同じ手順を、ここでも踏んでおくのが安全です。

提案の中身自体は理解できます。ゴールド層は特定の業務向けに集約された表なので、AI に「この指標は何を意味するのか」を伝える情報が抜け落ちます。だから意味の辞書と関係性を別に持とう、というのが提案の骨子です。手元でいえば用語集と、ナレッジグラフ的な相互リンクがそれに当たります。ただ、それを新しい層と呼ぶかどうかは、まだ固まっていません。

似た構図は「AI エージェント向けのコンテキストレイヤー」という言説にもあります。この分野の記事はほとんどがベンダーのブログで、Tellius は自社の記事の中で「それぞれの答えはセールスピッチでもある」と正直に書いています。各社が自社製品を核に定義しているので、差し引いて読むのが安全です。

どこで手を離すか

私が実際に使ってみて、当てはめないほうがよいと判断した境界を3つ挙げます。

ひとつめは、冪等性です。データ基盤では、同じ入力で同じ変換を回せば同じ結果が出ます。だから安心して再実行できます。手元のワークフローには人間と AI の判断が挟まるので、同じ素材から同じ記事は出てきません。「壊れたら再実行すればいい」という前提は持ち込めません。

ただし、これは生成物についての話です。スキルの途中でファイルを書き出したり、外部に投稿したりする副作用のある手順は、同じ操作を2回走らせても二重にならないように作れます。生成そのものは冪等にできませんが、副作用のある部分は冪等に寄せておく価値があります。

ふたつめは、成果物の寿命です。データ基盤のゴールドは、ダッシュボードから毎日参照される資産です。記事やレポートは、一度出したらほとんど参照されません。ゴールドを磨き込む労力の配分は、同じにはなりません。

みっつめは、前の章で書いた progressive disclosure との混同です。3段階あるので層に見えますが、データの品質を上げる仕組みではなく、読み込む量を減らす仕組みです。

そのうえで、借りる価値があると感じているのは次の3つだけです。

1. 生の素材を残す。加工したものだけを残さない
2. 2回以上使う判断基準は、中間の層に切り出して単一の情報源にする
3. 成果物は目的別に分ける。無理にひとつへ統合しない

これだけなら、スキルが3本しかない段階からでも回せます。層を先に作ってから中身を埋めるのではなく、素材と成果物が溜まってきてから「どこが再利用されているか」を見て切り出します。そちらのほうが、最初から3層を設計しようとするより現実的ではないでしょうか。少なくとも私の手元では、後から切り出したもののほうが長く生き残っています。

これから何が起きそうか

短く展望に触れておきます。

いま起きているのは、データ基盤側とエージェント側が直接つながり始めたことです。dbt、Databricks、Snowflake はいずれも MCP サーバーを公式に提供しています。MCP（Model Context Protocol）は、AI が外部のツールやデータに決まった作法でつなぐための共通規格です。各社はその先に、指標の意味を定義したセマンティックレイヤーの製品を接続しています。エージェントが表を直接読むのではなく、意味の定義を経由して読む形に寄っています。

Gartner も2026年5月のプレスリリースで、セマンティクスの欠如が AI エージェントの不正確さと支出の無駄を招くと指摘しています（Gartner）。つなぐための規格が整っても、意味の定義そのものは別に用意しなければいけない、というところに話が戻ってきます。

この流れが続くと、「AI に何を読ませるか」の設計はデータエンジニアリングの仕事とほぼ重なっていきます。逆に言えば、層の分け方、リネージ（そのデータがどこから来て何を経てきたかの来歴）の残し方、再処理のしやすさといった原則をすでに持っている人にとっては、新しく覚えることは多くありません。持っている語彙が、そのまま使えます。

組織の観点でも同じことが言えます。素材とロジックを分けて管理していれば、モデルが世代交代しても資産が残ります。SKILL.md はただのマークダウンなので、書き方を標準の範囲に収めておけば他のツールに移しても解釈されます。逆に、判断基準をチャット履歴の中にだけ置いている組織は、乗り換えのたびに積み上げが消えます。個人のスキルが組織の資産に変わるかどうかの分かれ目も、結局は置き場所を決めているかどうかだと思います。

私たち Deskrex が開発しているSnorbeは、ナレッジグラフ型のリサーチAIエージェントです。この記事で書いてきた3段階を、そのままサービスの構造として持っています。JPO・EPO・Google Patents・arXiv・PubMed などの専門データベースを横断して集めた調査結果を生のまま保持し、そこから意味と関係をつないだナレッジグラフを組み立て、最後に業務で使えるレポートの形にして出します。ブロンズにあたる部分を任せられるので、手元にはロジックだけを置いておけます。クエリの書き方を覚えなくても日本語のまま投げられますし、調べたことが記憶として残るので、同じテーマを掘るほど精度が上がります。

よくある質問

Q1. 結局、SKILL.md はブロンズ・シルバー・ゴールドのどこに置けばいいですか

どこにも置きません。SKILL.md は層に入るものではなく、層のあいだでデータを動かすロジックだからです。dbt でいうモデル（.sql ファイル）、Databricks でいうパイプラインのソースコードに当たります。置き場所としては ~/.claude/skills/<名前>/SKILL.md に置いて Git で管理します。層に入るのは、そのスキルが読む素材（生データと整えたナレッジ）と、出てくる成果物のほうです。

Q2. メダリオンアーキテクチャは Databricks を使っていないと関係ない話ですか

用語の出どころは Databricks ですが、考え方自体は特定の製品に依存しません。Delta Lake の公式ブログも「メダリオンの命名法を使う必要はない、自分のビジネスに最も合うアーキテクチャを使えばよい」と書いています。実際、ブロンズはステージング、シルバーは ODS やデータウェアハウスに対応するもので、20年前から現場で使われてきた分け方に共通の名前がついたものです。手元のファイル整理に借りるぶんには、Databricks の契約は要りません。

Q3. 生の素材は、どれくらい残しておけばいいですか

判断の基準は容量ではなく「間違いが見つかったとき、ここから再処理できるか」です。要約やメモから元の情報を復元できないなら、元を残してください。逆に、いつでも同じものを取り直せるもの（公開されている静的なドキュメントなど）は、URL だけ控えておけば足ります。ただし、保持期間を決めずに貯め続けるのも別の失敗になります。下流が直近のデータしか使っていないのに生データを何年分も抱え続けると、保管と走査のコストだけが増えていきます。日付ディレクトリに入れて、四半期に一度見直すくらいが現実的です。

Q4. CLAUDE.md と SKILL.md と rules/ は、どう書き分けますか

Anthropic の公式ドキュメントが基準を示していて、「CLAUDE.md のある節が事実ではなく手順に育ったら、スキルにする」と書かれています。つまり、常に成り立つ事実や設定は CLAUDE.md、複数の工程からなる手順は SKILL.md です。rules/ は、2つ以上のスキルが同じ判断基準を参照するときに切り出す場所として使います。私の目安は「2回書いたら共通化する」です。1回目は SKILL.md に直接書いて構いません。

Q5. スキルは何個くらいまで増やせますか

無制限ではありません。スキルの名前と説明文は常時システムプロンプトに載るため、スキルの数だけ固定費がかかります。20万トークンのモデルでは、既定で全スキル合計およそ2,000文字ほどしか割り当てられないという検証があり、予算を超えると呼び出し頻度の低いスキルから説明文が丸ごと削除されます。切り詰められるのではなく消えるので、Claude はそのスキルをいつ使うか判断できなくなります。数十個を超えるあたりから、使わないものを整理するか、手動で呼び出す設定に切り替える必要が出てきます。

Q6. Platinum 層は作ったほうがいいですか

作る前に、誰の定義かを確認してください。Platinum は Databricks の公式ドキュメントには存在せず、Google Cloud 側から提案された拡張です。しかも中身が提唱者ごとに違い、原典は5要素、別の解説は3要素、さらに別の記事はフィーチャーストアやベクトル埋め込みという、ほとんど重ならない定義になっています。提案の趣旨である「AI に意味と関係性を渡す層が要る」という問題意識は妥当なので、用語を使うより先に、用語集と相互リンクを整えるところから始めるほうが確実です。

Q7. 3層まるごと作るのは大げさに感じます。小さく始められますか

小さく始めるほうがうまくいきます。Databricks 自身が「メダリオンに従うのは推奨であって必須ではない」と明記していますし、Microsoft Learn も「層の名前と数は柔軟」と書いています。実務者からも「層を1つ飛ばしてもシステムは崩壊しない」という声が出ています。おすすめの順番は、まず生の素材を消さずに残すところだけを始めることです。次に、同じ判断基準を2回書いたタイミングで共通化します。層を先に用意してから中身を埋めるより、溜まってきたものを見て切り出すほうが、結果的に壊れにくくなります。

この記事で参照した一次情報

本文中の定義・引用・数値は、次の資料を確認して書いています。2026年7月時点の内容です。

• Databricks「What is a Medallion Architecture?」（メダリオンの定義、ブロンズ/シルバー/ゴールドの役割）: https://www.databricks.com/glossary/medallion-architecture
• Microsoft Learn「What is the medallion lakehouse architecture?」（各層の性質、複数ゴールド層、必須ではない旨）: https://learn.microsoft.com/en-us/azure/databricks/lakehouse/medallion
• Databricks ドキュメント日本語版（「推奨されるベストプラクティスですが、必須ではありません」）: https://docs.databricks.com/aws/ja/lakehouse/medallion
• Microsoft Learn Training「Describe medallion architecture」（層の名前と数は柔軟、ブロンズを生のまま保つ理由）: https://learn.microsoft.com/en-us/training/modules/describe-medallion-architecture/2-describe-medallion-architecture
• Delta Lake「Delta Lake Medallion Architecture」（命名法を使う必要はない旨）: https://delta.io/blog/delta-lake-medallion-architecture/
• dbt ドキュメント「About dbt models」（モデルは select 文を書いた .sql ファイル）: https://docs.getdbt.com/docs/build/models
• dbt-core リポジトリ（select 文をテーブルとビューに変えるのは dbt 側）: https://github.com/dbt-labs/dbt-core
• dbt ドキュメント「Version control basics」（コードは Git で版管理）: https://docs.getdbt.com/docs/platform/git/version-control-basics
• dbt ガイド「Optimize dbt models on Databricks」（staging/intermediate/marts とメダリオンの対応）: https://docs.getdbt.com/guides/optimize-dbt-models-on-databricks
• Databricks ドキュメント「What are pipelines?」（パイプラインはソースコードファイルの集まり）: https://docs.databricks.com/aws/en/ldp/concepts/pipelines
• Databricks ドキュメント「Git folders」（ノートブックとファイルの Git 管理）: https://docs.databricks.com/aws/en/repos
• Anthropic Engineering「Equipping agents for the real world with Agent Skills」（progressive disclosure の3段階）: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Anthropic Engineering「Effective context engineering for AI agents」（context rot、高信号トークンの最小集合）: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Claude ドキュメント「Agent Skills overview」（3段階のトークンコスト表）: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• Claude Code ドキュメント「Skills」（事実は CLAUDE.md、手順はスキル）: https://docs.claude.com/en/docs/claude-code/skills
• Anthropic「Skill authoring best practices」（500行ルール、参照は1階層、description の書き方）: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Claude Code ドキュメント「Hooks」（Stop フックによる完了前の検証）: https://code.claude.com/docs/en/hooks
• Zhou et al.「Getting Better at Working With You: Compiling User Corrections into Runtime Enforcement for Coding Agents」（TRACE、違反率57.5%と37.6%の数値、2026年6月11日投稿）: https://arxiv.org/abs/2606.13174
• Engineering at Meta「How Meta Used AI to Map Tribal Knowledge in Large-Scale Data Pipelines」（50以上の専門エージェント、59個のコンテキストファイル、ツール呼び出し約40%減、2026年4月6日）: https://engineering.fb.com/2026/04/06/developer-tools/how-meta-used-ai-to-map-tribal-knowledge-in-large-scale-data-pipelines/
• Gartner「Lack of Semantics Causes Inaccurate AI Agents and Wasted Spending」（2026年5月11日）: https://www.gartner.com/en/newsroom/press-releases/2026-05-11-gartner-says-lack-of-semantics-causes-inaccurate-artificial-intelligence-agents-and-wasted-spending
• Data Engineering Weekly「Revisiting Medallion Architecture」（semantic sprawl、層をまたぐ責務漏れ）: https://www.dataengineeringweekly.com/p/revisiting-medallion-architecture
• Algoscale「Medallion architecture implementation failures」（取り込み時の加工がもたらす症状）: https://algoscale.com/go/blog/medallion-architecture-implementation-failures
• Xebia「Medallion Architecture: is it really a new way of doing things?」（STG/ODS/DWH との対応）: https://xebia.com/blog/data-design-pattern-medallion-architecture-is-it-really-a-new-way-of-doing-things
• Google Cloud Japan「メダリオンアーキテクチャ 2.0」（Platinum 層の原典、5要素）: https://zenn.dev/google_cloud_jp/articles/ff74bf18e44f97
• G-gen Tech Blog「メダリオンアーキテクチャ 2.0 with Google Cloud」: https://blog.g-gen.co.jp/entry/medallion-architecture-2-0-with-google-cloud
• Zenn（suwash）「メダリオンアーキテクチャ2.0」（レイテンシーとコストの限界）: https://zenn.dev/suwash/articles/medallion_architecture_2_20250911
• DevelopersIO「Claude Code のスキルとコンテキスト予算」（description が丸ごと削除される挙動）: https://dev.classmethod.jp/articles/claude-code-skill-context-budget
• MindStudio「Claude Code Skills Architecture」（手順は skill.md、コンテキストは参照ファイル）: https://www.mindstudio.ai/blog/claude-code-skills-architecture-skill-md-reference-files