Claude Codeのメモリ三層構造 — CLAUDE.md / Settings / Skillsの使い分けと組み合わせ

要点

Claude Codeには永続化される情報の置き場所が複数あります。CLAUDE.md / .claude/settings.json / .claude/skills/ の3つはどれも「セッションをまたいで残る」点で似ていますが、役割と使い分けが明確に異なるため、混同するとプロジェクトの構造が崩れます。

3層を一言で言うと:

• CLAUDE.md = 自然言語で書く方針 / 規約 / 文脈(全セッション開始時に必ず読まれる)
• settings.json = 機械可読な設定値(hooks / 権限 / MCP server等)
• Skills = 手順型ノウハウ(必要に応じてClaudeが自分で読みに行く)

本記事はこの3層を整理した上で、「この情報をどこに置くか」の判断基準と、3層を組み合わせた実用設計パターンを扱います。

3層の比較表

ここで重要なのは、読み込まれ方の違いです。

• CLAUDE.mdとsettings.jsonは「常に効く」 — Claude Codeはセッション開始時にこれらを内蔵知識として取り込みます
• Skillsは「呼び出されたときだけ効く」 — Skill ツールや Task 経由で明示的にinvokeして初めて読まれます

この差が、3層の使い分けの本質です。

レイヤごとの詳細

Layer 1: CLAUDE.md(自然言語の方針)

CLAUDE.md はプロジェクトルートと ~/.claude/CLAUDE.md(ホーム)の両方に置けます。プロジェクト側がプロジェクト固有、ホーム側が個人グローバル設定です。両方ある場合は両方とも読み込まれて結合されます。

入れるべきもの

• プロジェクトの目的 / 読者 / トーン(メディアサイトなら「読者像」「文体」)
• コーディング規約(命名 / インデント / 禁則)
• ファイル配置・命名規則
• テスト / ビルドの走らせ方
• コミット / ブランチ / PRの運用ルール
• AIへのドメイン背景情報(「このプロジェクトは〜の目的で、〜の制約がある」)
• Skill / Sub-agentへの参照(「重い手順は ~/.claude/skills/X.md を参照する」)

入れるべきでないもの

• 手順型のノウハウ(→ Skillsへ)
• JSON設定(→ settings.jsonへ)
• 頻繁に変わる動的情報(セッション開始時に毎回読まれるので、変化が大きいとcontextが安定しない)

Layer 2: settings.json(機械可読な設定)

.claude/settings.json にはClaude Codeの挙動を変える構造化設定を入れます。

入れるべきもの

• hooks: PreToolUse / PostToolUse / SessionStart等の自動実行スクリプト(Hooks実例カタログ参照)
• permissions: tool許可 / 拒否ルール
• env: 環境変数(機密でないもの)
• mcpServers: 利用するMCP serverの接続情報
• model: デフォルトモデル指定(opus / sonnet等)

入れるべきでないもの

• 自然言語での説明 / 方針(JSONはコメントが書きにくい → CLAUDE.mdへ)
• 手順書(JSONでは構造化が難しい → Skillsへ)

Layer 3: Skills(手順型ノウハウ)

.claude/skills/<skill-name>.md(または <skill-name>/SKILL.md)に置く、呼び出されたときに初めて読まれる手順書です。

入れるべきもの

• 明確な手順がある作業: 記事執筆、リリースノート生成、コードレビュー
• テンプレート: 出力構造、frontmatter雛形
• 独自フレームワーク: チェックリスト、判断基準、評価軸

構造の定型

---
name: skill-name
description: 1 行で「何ができる skill か」を書く(Claude が呼び出すか判断する材料)
---
 
## 入力(あれば)
 
## 手順
 
ステップ 1: ...
ステップ 2: ...
 
## 出力テンプレート
 
(成果物の構造)
 
## 失敗時

description を具体的に書くことが特に重要です。Claudeはdescriptionだけを見て**「このskillを使うべきか」を判断**します。

「どこに置くか」の判断基準

迷ったときに使えるフローチャート:

1. 「常時読まれる必要があるか?」

   • YES → CLAUDE.mdかsettings.json
   • NO → Skills

2. 「機械可読である必要があるか?(自動実行 / 設定値として参照される)」

   • YES → settings.json
   • NO → CLAUDE.md

3. 「手順型 / テンプレ型のノウハウか?」

   • YES → Skills
   • NO → CLAUDE.md

具体例で当てはめると:

• 「Markdown保存後にprettierを走らせる」→ 機械可読で常時 → settings.json(hooks)
• 「コミットメッセージは日本語で add: update: のいずれかを先頭に」→ 自然言語で常時 → CLAUDE.md
• 「リリースノート記事の構造はこの5見出しに従う」→ 手順型 → Skills

3層を組み合わせた実用設計パターン

Claude Media(本サイト)の運用を例に、3層がどう連携しているかを示します。

例: 記事執筆ワークフロー

[CLAUDE.md] 
  プロジェクトの目的 / 読者 / 禁則(常に効く)
  「記事執筆は article-generator skill を使う」と参照を書く
       ↓
[Skills] article-generator.md
  実際の執筆手順(SSOT 読み込み → article-strategy → article-generator → fact-checker → quality-judge → seo-optimizer)
       ↓
[settings.json] hooks
  PostToolUse Write|Edit に対し、media/content/ 配下の MDX 編集後に
  normalize-ja-spaces.ts --apply を自動実行

3層が役割分担し、互いに補完する形になっています:

• CLAUDE.mdは「何を書くべきか」(方針)を伝える
• Skillsは「どう書くか」(手順)を伝える
• settings.jsonは「どう自動化するか」(機械化)を担う

アンチパターン: 全部CLAUDE.mdに詰め込む

「常時読まれる」便利さに惹かれて、CLAUDE.mdに手順書もテンプレもJSON設定も全部書く運用は失敗します。理由は次の3点:

1. context windowを毎回圧迫: 1,000行のCLAUDE.mdがあると、毎セッション開始時に1,000行分のcontextが消費される
2. 方針と手順の混在で読みづらい: 後から「コミット規約はどこ?」と探すたびに長いCLAUDE.mdを上から下まで見る必要がある
3. 更新の局所性が失われる: 1つのskillだけを直したいのに、CLAUDE.md全体を触らないといけない

CLAUDE.mdは「常時必要な方針 / 規約」に絞り、それ以外はSkillsやsettings.jsonへ振り分けるのが健全な設計です。

アンチパターン: settings.jsonに方針を書こうとする

「設定として一箇所にまとめたい」とsettings.jsonに方針を書くのは無理筋です。JSONはコメントを許さない(厳密には許す方言もあるが、Claude Code側で読むときに無視される可能性が高い)ため、自然言語の説明が書きにくく、後から読み解くのが困難になります。自然言語の方針は必ずCLAUDE.mdかSkillsへ。

アンチパターン: Skillsに方針 / 規約を入れる

「手順型」と「方針」を混ぜると、必要なときだけ呼ばれるSkillの中に、常に守るべき規約が埋もれます。Claudeがskillをinvokeしなかった瞬間、規約がeffectiveでなくなります。規約は常時効くCLAUDE.mdに置くのが原則です。

補足: ホームと プロジェクトの優先順位

~/.claude/ と <project>/.claude/ の両方にファイルがある場合、プロジェクト側が優先されます。同名skillがある場合、プロジェクト側が選ばれます。

ホーム側はテンプレ保管庫として使い、プロジェクト固有の改変はプロジェクト側に置く運用が王道です。プロジェクトを別マシンにcloneしたときに自己完結して動く構造になります。

まとめ

CLAUDE.md / settings.json / Skillsの3層は、それぞれ「方針 / 設定 / 手順」という異なる役割を持ちます。読み込まれるタイミングも違います。混同して全部CLAUDE.mdに詰め込むとcontextを圧迫し、Skillsに方針を入れるとinvocation漏れで規約が効かなくなります。

新しい情報を追加するときは、本記事の3つの判断基準(常時必要か / 機械可読か / 手順型か)を当てはめて、適切なレイヤに振り分けてください。3層がきれいに役割分担した状態が、長期で壊れにくいClaude Codeプロジェクトの前提条件です。

関連:CLAUDE.mdの実装パターンとよくあるつまずきと対処法を合わせて読むと、メモリ運用の落とし穴が早めに見えます。