Claude Code ハーネス構築 — 設定・ルール・スキルの全体像

約10分

Level 3（カスタムコマンド）と Level 4（CLAUDE.md 階層）を理解している方。チームや複数プロジェクトで Claude Code を運用したい方。

Claude Code の基本操作（Level 3〜4 相当）
CLAUDE.md の基本的な役割

Claude Code をチームや複数のプロジェクトで使い始めると、「プロジェクトによって Claude の振る舞いがバラバラになる」「新しいメンバーが加わるたびにルールを口頭で共有しなければならない」という課題が生じます。ハーネス（harness）はこの課題を解決する設定システムです。このセクションでは、ハーネスの概念から実際の構築手順まで、11 のトピックに分けて体系的に学びます。

ハーネスとは何か

ハーネス（harness）とは、Claude Code の動作を制御する設定システム全体を指します。具体的には、CLAUDE.md・shared/ ディレクトリ・.claude/ アダプター層の三層構造で構成されます。

自動車のワイヤーハーネスが複数の電線を束ねて整然と管理するように、Claude Code のハーネスは「ルール」「スキル」「コマンド」「権限設定」を一か所に束ねて管理する仕組みです。ハーネスを導入することで、Claude Code は「何でも答えようとする汎用 AI」ではなく「このプロジェクトの規約を知るプロジェクトメンバー」として機能します。

なぜハーネスが必要か

ハーネスなしで Claude Code を複数のコンテキストで使う場合、次の問題が発生します。

一貫性の欠如: 同じタスクでも、セッションごとに異なるアプローチやコーディングスタイルで回答する
ルールの揮発: ひとつのセッションで「〇〇のルール」を伝えても、次のセッションでは忘れる
オンボーディングコスト: 新メンバーが Claude Code を使い始めるたびに、プロジェクト固有のルールを口頭で伝える必要がある
権限の管理困難: どのコマンドを許可し、何を禁止するかを一元管理できない

ハーネスはこれらの問題を構造的に解決します。ルールをファイルとして宣言し、チームで共有し、バージョン管理することで、Claude Code の振る舞いをコードと同じように管理できます。

三層構造の全体像

ハーネスは以下の三層で構成されます。

プロジェクトルート/
├── CLAUDE.md                 # 層 1: エントリーポイント
├── shared/                   # 層 2: 共有アセット（source of truth）
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── commands/
└── .claude/                  # 層 3: アダプター層（シムリンク）
    ├── settings.json
    ├── skills/  → shared/skills/
    ├── agents/  → shared/agents/
    └── commands/ → shared/commands/

層 1（CLAUDE.md） は Claude Code が最初に読む「起動契約」です。非交渉ルール・コマンド一覧・共有アセットマップへの参照を持ちます。長い仕様は直接書かず、shared/ のファイルへ参照します。

層 2（shared/） は実際のルール・スキル・コマンドが格納される source of truth です。チームで共同編集し、Git で管理します。

層 3（.claude/） は Claude Code ツールが読む設定層です。shared/ へのシムリンクを通じて、ツール固有の形式で共有アセットを公開します。権限設定（settings.json）もここに置きます。

構成要素の詳細

構成要素	役割	例
`CLAUDE.md`	エントリーポイント。非交渉ルールと shared/ への参照を宣言する	Non-Negotiable Rules、Shared Asset Map
`shared/rules/`	安全・品質ルールのファイル群。CLAUDE.md から参照される	`build-and-deploy.md`、`content-i18n.md`
`shared/skills/*/SKILL.md`	Claude が特定のタスクを実行するときにロードするスキル定義	`docs-content/SKILL.md`、`blog-content/SKILL.md`
`shared/agents/`	サブエージェントの役割・制約・ツール許可を定義するスペック	`docs-content.md`、`blog-content.md`
`shared/commands/`	ユーザーがスラッシュで呼び出すカスタムコマンド定義	`blog.md`、`docs.md`
`.claude/settings.json`	ツールの権限・フック・MCP プラグイン設定	`permissions`、`hooks`
`.claude/` アダプター層	shared/ へのシムリンクと Claude Code 固有の設定を束ねる層	`.claude/skills/` → `shared/skills/`

このセクションのロードマップ

このセクションでは、ハーネスの各構成要素を順番に深掘りします。

トピック	内容
CLAUDE.md 階層設計	グローバル・プロジェクト・サブディレクトリの三層設計とベストプラクティス
Settings JSON 設計	権限・フック・MCP の設定方法
Rules ファイル設計	安全・品質ルールの宣言方法と命名規則
カスタムコマンド深掘り	再利用可能なコマンドの設計パターン
Skills 設計パターン	タスク特化のスキル定義と使い分け
Agents スペック設計	サブエージェントの役割・制約・ツール制限の定義方法。Commands / Skills / Agents の三角形と description の書き方を学ぶ
Hooks 実装	PreToolUse・PostToolUse・Stop などのライフサイクルフックで自動化・バリデーション・通知を実装する
MCP Plugins 統合	ローカル・リモート MCP サーバーの設定方法と認証情報の安全な管理
Memory システム設計	user・feedback・project・reference の 4 種別と MEMORY.md インデックスの設計指針
ハーネスのテストと検証	設定が意図通りに機能するかを確認する方法
Marketplace 公開	作成したハーネスを共有・配布する方法

前提知識

このセクションは、以下の知識を前提とします。

Level 3: カスタムコマンド（.claude/commands/）を作成・使用した経験
Level 4: CLAUDE.md の階層構造（グローバル・プロジェクト・サブディレクトリ）の理解

Level 3・4 を未学習の場合は、先に Claude Code レベルアップを参照してください。

実践演習: このプロジェクトのハーネスを確認する

このプロジェクト（ai_learning_playground）自体がハーネスの実装例です。実際のディレクトリ構造を確認して、三層構造を自分の目で確認してください。

Step 1: ディレクトリ構造を確認する

ターミナルでプロジェクトルートに移動し、共有アセットのディレクトリを確認します。

ls shared/

出力例:

agents    commands  rules     settings  skills    tools     workflow

ls shared/rules/

出力例:

build-and-deploy.md  content-i18n.md  folder-safety.md  no-ui-regression.md  security.md  spec-first.md

✅ 確認: shared/rules/ に複数の .md ファイルが表示されれば、ルール層が正しく配置されています。

Step 2: エントリーポイントを確認する

cat CLAUDE.md

## Non-Negotiable Rules、## Commands、## Shared Asset Map の三つのセクションが含まれていることを確認します。

✅ 確認: ## Shared Asset Map のセクションに shared/rules/*.md や shared/skills/*/SKILL.md への参照が記述されていれば、エントリーポイントが正しく機能しています。

Step 3: アダプター層を確認する

ls -la .claude/

出力例:

agents -> ../shared/agents
commands -> ../shared/commands
settings.json
skills -> (各スキルファイルへのリンク)
workflow -> ../shared/workflow

✅ 確認: agents、commands、workflow がシムリンク（->）として表示されれば、アダプター層が正しく設定されています。

💡 何が起きているか: .claude/ ディレクトリはシムリンクを通じて shared/ を参照します。これにより、Claude Code ツールは .claude/ の構造を読む一方、実際の設定は shared/ で一元管理されます。shared/ を編集すれば .claude/ にも即座に反映されます。

まとめ

ハーネスは CLAUDE.md・shared/・.claude/ の三層で構成される Claude Code の設定システム
CLAUDE.md は Claude が最初に読むエントリーポイントで、長い仕様は shared/ に委譲する
shared/ は rules・skills・agents・commands を格納する source of truth で、Git で管理する
.claude/ は shared/ へのシムリンクと権限設定を持つアダプター層
このプロジェクト自体がハーネスの動作する実装例として参照できる

次のステップ

まず CLAUDE.md 階層設計から始めて、エントリーポイントの設計パターンを学んでください。

よくある質問

Q: ハーネスは個人利用でも必要ですか？

A: 単一プロジェクト・単独利用の場合、CLAUDE.md だけで十分なケースが多くあります。ハーネスの三層構造は、複数プロジェクト間でルールを共有したい場合、またはチームで Claude Code を運用する場合に特に効果を発揮します。

Q: shared/ ディレクトリは必ずこの名前にする必要がありますか？

A: ディレクトリ名は任意です。ただし、CLAUDE.md の Shared Asset Map でパスを明示する必要があります。このプロジェクトでは shared/ を使っていますが、config/、policies/ など、チームのコンテキストに合わせた名前を選択できます。

Q: .claude/ のシムリンクはどうやって作成しますか？

A: ln -s ../shared/agents .claude/agents のようにシェルコマンドで作成します。詳細は Hooks 実装と Settings JSON 設計で扱います。

Q: CLAUDE.md に書いたルールは必ず守られますか？

A: CLAUDE.md のルールは Claude Code がコンテキストとして読み込むものです。モデルが必ずルールに従う保証はありません。重要な制約（本番デプロイの禁止など）は .claude/settings.json の permissions フィールドでシステムレベルで制御することを推奨します。

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

Anthropic, Claude Code documentation
Anthropic, Claude API documentation

CLAUDE.md 階層設計 — プロジェクト・ユーザー・グローバルの三層構造

Level 10 実践: 次のプロダクトのエージェント群を Claude に設計させる