Claude Code の「処理」と「ドメイン知識」をレイヤー分離する設計術 — スキルが複利で効く構造をつくる

gura 氏の投稿が、Claude Code を使った PM 業務の知見を共有しています。2 ヶ月間の実運用で最も効いた設計判断は、Skill（処理レイヤー）と CLAUDE.md（ドメイン知識レイヤー）の分離だったとのことです。この考え方は、Claude Code の公式アーキテクチャとも一致する設計パターンです。

問題：なぜ全部入りの設定は破綻するのか

Claude Code を使い始めると、多くの人が CLAUDE.md にあらゆる情報を詰め込みます。プロジェクトの規約、処理手順、ドメイン知識、スタイルガイド。しかしこの「全部入り」アプローチには構造的な問題があります。

コンテキスト汚染: CLAUDE.md はセッション開始時に全文がロードされるため、情報量が増えるほどトークンを圧迫します
Lost in the Middle: 長大なコンテキストの中間部分が軽視される現象が発生します
再利用不能: プロジェクト固有の知識と汎用的な処理手順が混在し、別プロジェクトへの横展開ができません

SO Technologies 開発者ブログの分析によると、全部入り CLAUDE.md はセッション開始時にコンテキストの 40〜50% を占有するケースもあったと報告されています。

2 つのレイヤーを分離する

gura 氏が提唱するのは、明確な 2 層構造です。

Skill = 処理レイヤー

「どのフォルダから何を読んで、どう加工して、どこに出すか」を定義する

Skill は入力と出力が明確な、小さな処理単位です。

Skill の例	入力	出力
議事録の文字起こし	音声データ	テキスト議事録
外部向け議事録変換	内部議事録	フィルタリング済み議事録
Slack 共有	文書	Slack メッセージ
レポート生成	各種データ	フォーマット済みレポート

Skill は どのプロジェクトでも処理の骨格は同じ です。ファイルの場所は .claude/skills/<skill-name>/SKILL.md に配置し、YAML フロントマターで名前と説明を記述します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
---
name: meeting-notes-external
description: 内部議事録を外部向けに変換する
---

内部議事録を読み込み、外部共有用に変換します。

1. 議事録ファイルを読み込む
2. フィルタリングルールに基づいて不要な情報を除去する
3. 外部向けフォーマットに整形する
4. 出力ファイルを生成する

CLAUDE.md = ドメイン知識レイヤー

誰がステークホルダーで何の責任を持っているか。業界特有の制約は何か

CLAUDE.md にはプロジェクト固有の判断基準だけを記述します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
## ステークホルダー
- 発注者: A社 開発部（技術的な詳細を共有可）
- 元請け: B社 PM（進捗と課題のみ共有）

## 情報フィルタリング規則
- 内部見積もり金額: 外部共有不可
- 技術的な課題: A社には共有可、B社には抽象化して共有
- 個人名: 役職名に置換して共有

## 業界制約
- 個人情報保護法に基づくデータ取り扱い
- NDA 対象の技術情報は外部議事録から除外

分離がもたらす「複利効果」

この設計の本質は、同じ処理がドメイン知識の差し替えだけでまったく違う出力を返す 点にあります。

gura 氏の言葉を引用します。

一度作ったスキルは、CLAUDE.mdを書き換えるだけで別のプロジェクトにそのまま持っていけます。議事録スキルも、レポート生成スキルも、処理の骨格は同じまま、ドメイン文脈だけ差し替えれば動く。

これは Claude Code の公式ドキュメントが推奨するスキル配置戦略とも一致します。

配置場所	パス	適用範囲
個人（グローバル）	`~/.claude/skills/<name>/`	全プロジェクト共通
プロジェクト固有	`.claude/skills/<name>/`	そのプロジェクトのみ

汎用的な処理スキルは ~/.claude/skills/ に配置し、プロジェクト固有のドメイン知識は各プロジェクトの CLAUDE.md に記述する。この構造により、スキルを作れば作るほど次のプロジェクトの立ち上げが速くなる「複利構造」が生まれます。

Progressive Disclosure との関係

Claude Code のアーキテクチャは、この分離を技術的に支えています。公式ドキュメントが「Progressive Disclosure（段階的情報開示）」と呼ぶ 3 段階モデルです。

description（常時ロード）: スキルの名前と説明文のみ。数十個のスキルがあってもメモリ負荷は最小限
SKILL.md（呼び出し時にロード）: スキルが実行されるときだけ読み込まれる処理手順
参照ファイル（必要時にロード）: SKILL.md 内からリンクされた詳細資料

CLAUDE.md は常時ロードですが、処理手順を Skill に分離することで、CLAUDE.md には「判断基準」だけが残ります。結果として、コンテキスト使用量が大幅に削減されます。

実践: レイヤー分離の設計手順

Step 1: 既存の CLAUDE.md を分類する

現在の CLAUDE.md の各行を以下の 3 カテゴリに分類します。

カテゴリ	置き場所	例
処理手順	Skill	「議事録を作成する手順」「デプロイの手順」
ドメイン知識	CLAUDE.md	「ステークホルダー一覧」「業界制約」
参照資料	Skill 内の参照ファイル	「API 仕様書」「コーディング規約の詳細」

Step 2: Skill を汎用的に設計する

Skill 内でプロジェクト固有の値をハードコードしない設計が重要です。「A 社向けにフィルタリングする」ではなく、「CLAUDE.md のフィルタリング規則に基づいてフィルタリングする」と記述します。

Step 3: CLAUDE.md を 50 行以内に絞る

公式のベストプラクティスでも、CLAUDE.md はプロジェクト全体に共通する最小限の情報に留めることが推奨されています。処理手順を Skill に移すだけで、多くの場合この目標は達成できます。

ソフトウェア設計との類似性

この「処理とドメイン知識の分離」は、ソフトウェア設計における確立されたパターンと本質的に同じです。

Strategy パターン: アルゴリズム（処理）を定義し、実行時に差し替え可能にする
Dependency Injection: 外部からコンテキスト（ドメイン知識）を注入する
設定と実装の分離: 設定ファイル（CLAUDE.md）とコード（Skill）を分ける

AI エージェントの設計にも、従来のソフトウェア設計原則がそのまま適用できるということです。

Tips: ドメイン知識を docs/ で管理する

チームの開発リポジトリで docs/ 配下にドキュメントを集約する運用をしている場合、CLAUDE.md の内容を docs/ に移すことも可能です。ただし、CLAUDE.md と docs/ ではClaude Code の扱いが根本的に異なるため、移行には設計上の工夫が必要です。

CLAUDE.md と docs/ の違い

項目	CLAUDE.md	docs/ 配下の .md
セッション開始時の自動ロード	される	されない
Claude が自発的に参照	する	明示的に指示が必要
トークン消費	常時	読んだときだけ

CLAUDE.md の内容をそのまま docs/ に移すと、Claude Code はその情報を知らない状態でセッションが始まります。つまり、移動しただけでは機能しなくなります。

解決策: CLAUDE.md をインデックスにする

CLAUDE.md を薄くして、docs/ への参照だけを残す方法が最も実用的です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# CLAUDE.md

## 技術スタック
- バックエンド: Python (Django)
- API: GraphQL (Strawberry Django)

## ドキュメント参照
- ステークホルダー一覧: docs/stakeholders.md を参照
- 業界制約・フィルタリング規則: docs/constraints.md を参照
- 用語集: docs/glossary.md を参照
- API 仕様: docs/api-spec.md を参照

Claude は CLAUDE.md 内の参照先を認識し、関連する作業時に docs/ のファイルを読みに行きます。これは Progressive Disclosure の考え方そのものです。

.claude/rules/ で条件付きロードを組み合わせる

特定のディレクトリで作業するときだけ、対応する docs/ のファイルを自動的に意識させることもできます。

1
2
3
4
5
6
# .claude/rules/api-work.md
---
paths:
  - "src/api/**"
---
API 関連の作業時は docs/api-spec.md を必ず参照すること。

推奨ディレクトリ構成

CLAUDE.md                  # 50行以内。インデックス + 最小限の判断基準
docs/
  stakeholders.md          # ステークホルダー詳細
  constraints.md           # 業界制約・規約
  glossary.md              # 用語集
  api-spec.md              # API 仕様
.claude/
  skills/                  # 処理レイヤー（Skill）
  rules/                   # 条件付きロード規則

docs/ 運用のメリット

この構成には、単に CLAUDE.md にすべてを書く場合にはないメリットがあります。

チームでのレビューが容易: docs/ は通常の PR レビューフローに乗る
Git 履歴で変更を追跡できる: ドメイン知識の変更経緯が残る
トークン効率が良い: 必要なドキュメントだけがコンテキストに入る
ツール非依存: docs/ の Markdown は Claude Code 以外のツール（Cursor、Copilot 等）からも参照できる

注意点

CLAUDE.md からの参照が曖昧だと Claude が読みに行かないことがあります。「docs/ を参照」ではなく「docs/constraints.md を参照」のように具体的なファイル名を書くのが重要です
頻繁に参照する判断基準（3 行程度の短いもの）は CLAUDE.md に直接残す方が効率的です。毎回ファイルを読みに行くオーバーヘッドを避けられます
Skill の参照ファイルとして docs/ を使う場合は、SKILL.md 内に相対パスでリンクを記述します

Tips: MkDocs でドキュメントサイトを兼ねる

docs/ を MkDocs でサイトとしても公開している場合、Claude Code との相性はさらに良くなります。

MkDocs 方式の評価

観点	評価	理由
Claude Code との互換性	高い	Markdown がそのまま読める。HTML 変換不要
チーム共有	高い	サイトとして人間も読め、AI も読める
構造化	高い	`mkdocs.yml` の `nav` がドキュメントの地図になる
トークン効率	高い	必要なページだけ読みに行く Progressive Disclosure
ツール非依存	高い	Cursor、Copilot 等でもそのまま使える
Git 運用	高い	PR レビュー、履歴追跡が自然にできる

mkdocs.yml の nav がインデックスになる

MkDocs の nav セクションは、ドキュメント全体の構造を YAML で定義しています。これは CLAUDE.md に書くインデックスの代わりになります。

1
2
3
4
5
6
7
8
# mkdocs.yml
nav:
  - ステークホルダー: stakeholders.md
  - 業界制約: constraints.md
  - 用語集: glossary.md
  - API仕様:
    - 概要: api/overview.md
    - エンドポイント: api/endpoints.md

CLAUDE.md からは mkdocs.yml を参照するだけで、Claude がドキュメントの全体構造を把握できます。

1
2
3
4
5
# CLAUDE.md

## ドキュメント
ドメイン知識は docs/ に MkDocs 形式で管理。
構成は mkdocs.yml の nav セクションを参照。

個別のファイル名を列挙する必要がなく、mkdocs.yml の nav が Single Source of Truth として機能します。ドキュメントの追加・並べ替えも mkdocs.yml だけで完結します。

Single Source of Truth の実現

MkDocs 方式の最大の強みは、同じ Markdown ファイルが 2 つの役割を同時に果たす点です。

MkDocs でビルド すればチームメンバー向けのドキュメントサイト
Claude Code が直接読めば AI のコンテキスト

ドキュメントの二重管理が発生しません。ドキュメントを更新すれば、サイトも Claude Code の参照先も同時に更新されます。

MkDocs 拡張記法との互換性

MkDocs Material の拡張記法（Admonition、タブ、テーブルなど）は、Markdown として読んでも意味が通ります。

1
2
!!! warning "本番環境での注意"
    この操作は不可逆です。必ずバックアップを取得してください。

Claude Code はこれを「警告: 本番環境での注意」として正しく解釈できます。

注意すべき点

サイト用のファイル分割が細かすぎる場合がある

MkDocs のサイトでは 1 ページを短く保つのがベストプラクティスですが、Claude Code にとっては複数ファイルを読みに行くオーバーヘッドになります。判断基準のような頻繁に参照する情報は、サイト上で複数ページに分かれていても、Claude 向けには 1 ファイルにまとめた方がトークン効率は良い場合があります。

MkDocs 固有のフロントマターは無駄なトークン消費

1
2
3
4
5
---
title: 業界制約
description: サイト表示用の説明文
tags: [規約, コンプライアンス]
---

サイト表示用の YAML フロントマターは Claude Code にとって不要ですが、量は少ないため実害はほぼありません。

ドキュメントが大規模になった場合の選択肢

docs/ が数十ファイル程度なら mkdocs.yml の nav 参照で十分です。ドキュメントが数百ファイル規模になった場合は、mkdocs-mcp-plugin でセマンティック検索を追加する選択肢もあります。

MkDocs 方式の推奨構成

mkdocs.yml                 # nav がドキュメントの地図
CLAUDE.md                  # 50行以内。mkdocs.yml 参照 + 最小限の判断基準
docs/
  index.md                 # サイトトップ（概要）
  stakeholders.md          # ステークホルダー詳細
  constraints.md           # 業界制約・規約
  glossary.md              # 用語集
  api/
    overview.md
    endpoints.md
.claude/
  skills/                  # 処理レイヤー
  rules/                   # 条件付きロード（必要に応じて）

まとめ

Skill は処理レイヤー: 入力と出力が明確な小さな処理単位を定義する
CLAUDE.md はドメイン知識レイヤー: ステークホルダー、業界制約、用語など判断基準を記述する
同じ Skill がドメイン知識の差し替えで異なる出力を返す: これが横展開を可能にする鍵
Progressive Disclosure が技術的に支える: スキルは呼び出し時にのみロードされ、コンテキスト効率が高い
複利構造が生まれる: スキルが増えるほど、次のプロジェクト立ち上げが加速する
ソフトウェア設計原則と一致: Strategy パターンや DI と同じ発想で AI エージェントを設計できる
docs/ でのドメイン知識管理も可能: CLAUDE.md をインデックスにし、詳細を docs/ に置くことでチーム運用との両立ができる
MkDocs との相性が良い: mkdocs.yml の nav がインデックスになり、同じ Markdown が人間向けサイトと AI のコンテキストを兼ねる

Claude Code の「処理」と「ドメイン知識」をレイヤー分離する設計術 — スキルが複利で効く構造をつくる#

問題：なぜ全部入りの設定は破綻するのか#

2 つのレイヤーを分離する#

Skill = 処理レイヤー#

CLAUDE.md = ドメイン知識レイヤー#

分離がもたらす「複利効果」#

Progressive Disclosure との関係#

実践: レイヤー分離の設計手順#

Step 1: 既存の CLAUDE.md を分類する#

Step 2: Skill を汎用的に設計する#

Step 3: CLAUDE.md を 50 行以内に絞る#

ソフトウェア設計との類似性#

Tips: ドメイン知識を docs/ で管理する#

CLAUDE.md と docs/ の違い#

解決策: CLAUDE.md をインデックスにする#

.claude/rules/ で条件付きロードを組み合わせる#

推奨ディレクトリ構成#

docs/ 運用のメリット#

注意点#

Tips: MkDocs でドキュメントサイトを兼ねる#

MkDocs 方式の評価#

mkdocs.yml の nav がインデックスになる#

Single Source of Truth の実現#

MkDocs 拡張記法との互換性#

注意すべき点#

MkDocs 方式の推奨構成#

まとめ#

参考#