Claude Codeの「.claude」でコンテキストを環境から設計するハーネスエンジニアリング
プロンプトから、環境による制御へ。
AIに定義や文脈（コンテクスト）を理解させるため、毎回プロンプトを書いて指示するのではなく、~/.claude/ のディレクトリで定義し、あらかじめシステムに組み込んでおきます。
これにより、Claude Codeが外部ツール（MCP）や複数種類のエージェントを安全に自律駆動させるための制御基盤（ハーネス）が完成します。本稿では、このコンテクストを環境から設計する「ハーネスエンジニアリング」の具体的な構築手法について解説していきます。
~/.claude/ ディレクトリマップ
以下は私のClaude Code環境設定です。その都度人間が細かく指示を出すのではなく、システム全体に共通のルールを組み込むことで、Claudeはより自律的に動いてくれるようになります。
~/.claude/
├─ 🦀 CLAUDE.md グローバル指示書（全セッション共通・最優先）
├─ 🔑 settings.json パーミッション・hooks 設定
├─ 🪝 .mcp.json MCP サーバー定義（認証情報含む）
│
├─ 📋 rules/
│ ├─ 🗂️ context.md 技術スタック・CLIコマンド一覧
│ ├─ 👦 profile.md 個人情報
│ ├─ 🔐 credentials.md 認証情報
│ └─ 🏢 organization.md 組織情報：Google Workspace Directory APIで自動同期
│
├─ 🤖 agents/ (2個)
│ ├─ ✏️ design-lead.md 企画設計チーム（9体）tools 制限あり
│ └─ 🛠️ tech-lead.md 技術設計チーム（6体）tools 全ツール
│
├─ 🧩 skills/ (10個) ※推奨
│ ├─ ✏️ design-lead/
│ │ ├─ SKILL.md
│ │ └─ 📚 references/
│ │ ├─ 📜 Claude_Operating_Rules_Team.md 共通ルール
│ │ ├─ 👥 T_AI_Agent_Team_v2.md エージェント定義
│ │ ├─ 🎤 hearing.md ヒアリング
│ │ ├─ 🎯 issue-define.md イシュー
│ │ ├─ 🔍 researcher.md リサーチ
│ │ ├─ 🧠 brand-strategy.md ブランド戦略
│ │ ├─ ✍️ copywriter.md コピーライター
│ │ ├─ 🎨 art-director.md アートディレクター
│ │ ├─ 💻 web-designer.md WEBデザイナー
│ │ ├─ 🔥 red-team.md 批判担当
│ │ └─ 📊 director.md 統合ディレクター
│ │
│ ├─ 🛠️ tech-lead/
│ │ ├─ SKILL.md
│ │ └─ 📚 references/
│ │ ├─ 🏗️ ui-architect.md UIアーキテクト（技術選定・設計）
│ │ ├─ 🖥️ frontend-engineer.md フロントエンド実装（Liquid/Next.js）
│ │ ├─ ✨ interaction-engineer.md インタラクション（GSAP/WebGL）
│ │ ├─ 🎨 design-system.md デザインシステム（Figma↔コード）
│ │ ├─ ⚙️ automation-engineer.md EC・自動化（Shopify Flow/GAS）
│ │ └─ 🔍 reviewer.md 品質レビュー（Lighthouse/A11y）
│ │
│ ├─ 🏢 context/ 個人・組織コンテクスト
│ ├─ 💰 board/ board API 連携
│ ├─ 🈺 hubspot/ HubSpot API 連携
│ ├─ 💎 gemini-interactions-api/ Gemini Interactions API 実装支援
│ ├─ 🎨 material-design/ M3 デザイントークン・実装参照
│ ├─ 🎞️ slide-deck-builder/ スライド設計書 SLIDE-DECK.md 生成
│ ├─ 🖼️ slide-md-creator/ デザインシステム SLIDE.md 生成
│ └─ 🧱 slide-pattern-creator/ レイアウトパターン抽出
│
├─ ⌨️ commands/ (24個) ※後方互換。今後はskillsを推奨。
│ ├─ 📔 日報・業務系
│ │ ├─ day.md / week.md / plan.md 日報・週報・週次計画の作成
│ │ ├─ push.md GitHub push＋Googleドライブ同期
│ │ ├─ deploy.md / cloudrun.md Cloud Run デプロイ／サービス一覧
│ │ └─ project-health.md プロジェクト健全性調査
│ │
│ ├─ 🛠️ 制作・実装系
│ │ ├─ figma-to-code.md Figmaからコード要件定義
│ │ ├─ sync-design-tokens.md FigmaトークンからTailwindに同期
│ │ ├─ nanobanana.md NanoBananaで画像生成
│ │ ├─ shopify-estimate.md Shopify構築の見積もり
│ │ ├─ biz-consultant.md ビジネス分析レビュー
│ │ └─ gemini-review.md Geminiレビューとファクトチェック
│ │
│ └─ 🧹 メンテナンス系
│ ├─ clear.md キャッシュ・一時ファイル削除
│ └─ maintenance.md 蓄積データ整理・アーカイブ
│
├─ 🔌 plugins/
│ ├─ 📋 installed_plugins.json 導入済みプラグイン一覧
│ ├─ 🛒 known_marketplaces.json 登録済みマーケットプレイス
│ ├─ 🏪 marketplaces/claude-plugins-official/ 公式マーケットプレイス定義
│ ├─ 💾 cache/claude-plugins-official/ 取得済みメタキャッシュ
│ └─ 📦 data/ インライン同梱プラグインの実体
│ ├─ 🖥️ desktop-commander-inline/ ファイル・プロセス操作
│ └─ 📄 pdf-viewer-inline/ PDF 表示・注釈
│
├─ 📚 references/ (2個)
│ ├─ 📈 biz-analysis-methods.md ビジネス分析フレームワーク集
│ └─ 🧠 thinking-methods.md 思考法・フレームワーク集
│
├─ ⏰ scheduled-tasks/ (2個)
│ ├─ 📅 daily-working-report/ /schedule で登録した日次稼働レポート
│ └─ 📆 weekly-report/ /schedule で登録した週次レポート
│
├─ 💭 projects/-Users-osamu/memory/
│ ├─ 🗂️ MEMORY.md 永続メモリインデックス
│ ├─ 👤 user_osamu.md 永続メモリユーザー情報
│ ├─ 💬 feedback_*.md (4個) 行動指針・フィードバック記憶
│ ├─ 📁 project_*.md (8個) 進行中プロジェクト情報
│ └─ 🔗 reference_*.md (5個) 外部参照先
│
├─ 📜 file-history/ ファイル編集バージョン履歴
├─ 📋 plans/ プランモード文書
├─ 💾 cache/ changelog・issues キャッシュ
├─ 🗄️ backups/ .claude.json 自動バックアップ
├─ 🐛 debug/ · 📡 telemetry/ 診断ログ・利用統計
├─ 🔄 sessions/ · 🌍 session-env/ セッション状態・環境変数
├─ 💻 ide/ VSCode 連携設定
├─ 📸 shell-snapshots/ シェル状態スナップショット
└─ 📋 paste-cache/ · 📥 downloads/ クリップボードキャッシュ・DL ファイルCLAUDE.md
CLAUDE.mdは、すべてのセッション、つまりAIとの一連の対話において、自動的に読み込まれる共通の指示書です。
このファイルに、常に日本語で回答することや、ファイルの新規作成前に確認を求めること、変更を確定して共有リポジトリに送信するコマンドであるgit pushの実行前に必ず確認を入れることなどのルールを記載しておきます。これにより、新しい対話を開始するたびに同じ指示を繰り返す必要がなくなり、AIが指定通りのルールを遵守するようになります。
# Claude Code 設定
## 言語
常に日本語で回答する。コード識別子・技術用語は英語のまま。
## スタンス
- 計画立案（プランモード）・Todo 作成・コードレビュー・実装・コマンド実行まで Claude が担う
## 承認ルール
- ファイルの**新規作成・削除・上書き**は実行前に確認を求める
- 読み取り・検索は確認不要
- git push・PR 作成・外部サービスへの送信は必ず確認する
- **現在の作業スコープを超える操作**（他プロジェクト・システム設定・共有設定ファイルの変更など）は必ず承認を得てから実行する
## 開発スタンス（レビュー・計画時）
- コードは簡潔に。不要な抽象化・コメント・エラーハンドリングを避けるよう指摘する
- 依頼範囲を超えた機能追加・リファクタリングは提案にとどめる
- レビューは「何が問題か」「どう直すか」を具体的に出力する
## キャッシュ・クリーンアップ
- .DS_Store などの不要ファイルを発見したら削除を提案する
## 参照情報
<!-- 組織構成・技術スタック・主要 CLI/API（タスク計画・技術判断時に参照） -->
@/Users/osamu/.claude/rules/context.md
<!-- ユーザーの個人情報・マイコンテキスト -->
@/Users/osamu/.claude/rules/profile.md
<!-- 各サービスの認証情報参照先（API 利用・デプロイ計画時に参照） -->
@/Users/osamu/.claude/rules/credentials.md
適切なファイルサイズと分割の推奨
公式ドキュメントでは、指示書の肥大化を防ぐために、このファイルの長さを200行以内に収めることが推奨されています。記述内容が増えて長くなった場合は、rulesフォルダへ分割して管理する方法が効果的です。
実際の運用例として、組織の体制情報、導入している技術要素の構成である技術スタック、よく使用する画面入力形式の命令であるCLIコマンドなどは、あらかじめrulesフォルダ内に別ファイルとして切り分けておきます。その上で、CLAUDE.mdからアットマーク記号などを用いてそれらのファイルを指定し、読み込ませることで管理が非常に容易になります。
この設定を行うことで、対話を新しく切り替えたとしても、常にこちらの前提状況や組織のルールを把握した状態でAIが動くため、開発の引き継ぎや指示の手間が大幅に軽減され、作業の円滑化が向上すると推測されます。
settings.json
CLAUDE.mdがAIに対する行動指針や要望であるのに対し、settings.jsonはシステム自体が強制的に適用する制御ルールです。これはAIが解釈して従う指示書ではなく、プログラムが直接読み込んで処理を制限する設定ファイルであるため、指定したルールが確実に実行されるという特徴があります。
コマンド実行の承認を効率化する方法
システム操作を行う際に、毎回確認を求められる手間を軽減するために、一括で実行を許可する仕組みが用意されています。
ワイルドカードによる一括指定
特定の文字以降をすべて対象とするワイルドカードという指定方法が利用できます。たとえば、Bash(npm *) のように記述することで、関連するコマンドをまとめて許可リストに登録することが可能です。これにより、安全性が確認されている定型作業の承認手続きを省略し、作業効率を高める効果が期待できます。自動許可リストの生成コマンド
毎回コマンドの実行許可を求められる状況を改善したい場合は、/fewer-permission-prompts というコマンドが有効です。これを使うと、過去の作業履歴から安全と判断された操作をシステムが自動で分析し、設定ファイルに適合する許可リストを生成してくれます。
{
"permissions": {
"allow": [
"Bash(git log *)",
"Bash(git diff *)",
"Bash(npm test *)"
],
"deny": [
"Bash(rm -rf *)"
]
}
}.mcp.json
.mcp.jsonは、Claudeに外部のシステムやツールを操作する権限を与えるための設定ファイルです。ここに接続先の設定を記述することで、日常の業務で使用している様々なクラウドサービスとClaudeを直接連携させることが可能になります。
外部連携の共通規格であるMCPとは
MCPとはModel Context Protocolの略称で、AIが外部のシステムやデータと安全にやり取りを行うために定められた標準的な通信の仕組みを指します。この共通規格に対応した定義を.mcp.jsonに登録することにより、Claudeは人間の代わりに外部の情報を読み取ったり、指示された作業を実行したりできるようになります。
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}自分が使っているMCPサーバー
Slack — チャンネル・スレッドの取得、メッセージ送信
GitHub — PR作成・レビュー・issue操作
Google Calendar — 予定の取得・作成
Gmail — メールの検索・送信
Figma — デザインファイルの読み込み、コード生成
Shopify — ストア操作、GraphQL実行
board — 自社の受注管理システムとの連携（自作Pythonサーバー）
Cloud Run — Googleのサーバーレス環境へのデプロイ
Clasp — Google Apps Scriptのローカル開発
plugins/
plugins/フォルダは、Claude Codeに新しい機能を追加するための拡張プログラムを管理する場所です。専用の公開市場であるマーケットプレイスから導入した拡張機能の設定データや、プログラムの本体がこの場所に格納されます。
plugins/
├─ installed_plugins.json 導入済みプラグイン一覧
├─ known_marketplaces.json 登録済みマーケットプレイス
├─ install-counts-cache.json
├─ blocklist.json
├─ marketplaces/ マーケットプレイス定義
│ └─ claude-plugins-official/
├─ cache/ 取得済みメタキャッシュ
└─ data/ インライン同梱プラグインの実体
├─ desktop-commander-inline/
└─ pdf-viewer-inline/フォルダ内に格納される主なデータ構造
拡張機能を安全かつ円滑に動作させるため、内部は以下のような役割を持ったファイルで整理されていると推測されます。
導入済みリスト（installed_plugins.json）
現在システムに正しく組み込まれている拡張機能の一覧を記録したデータです。配布元の登録情報（known_marketplaces.json / marketplaces/）
信頼できる拡張機能の提供元や、公式の公開市場に関する接続情報が管理されています。拡張機能の本体データ（data/）
ファイルの操作を行う機能や、PDFファイルを閲覧・解析する機能など、取り込まれたプログラムの実体がここに配置されます。
references/
references/フォルダは、複数の異なるAIアシスタントや指示書から、横断的に参照できるドキュメントを保管する場所です。特定の命令に固定されるのではなく、どのアシスタントからでも共通の知識ベースとして呼び出すことができる、社内の共有資料棚のような役割を果たします。
知識を共有化するメリット
個別の指示書に毎回同じ背景知識やルールを書き込むと、管理が煩雑になり、AIが一度に処理できる情報量を無駄に消費してしまいます。共通の資料をこのフォルダにまとめておくことで、必要なときにだけAIがその内容を参照し、効率的かつ一貫性のある思考を行えるようになると推測されます。
配置されている具体的なファイル例
ビジネス分析手法をまとめたファイル（biz-analysis-methods.md）
市場環境を分析する3Cや、マーケティング戦略を練る4P、企業の強みや弱みを整理するSWOT分析、価値の流れを追うバリューチェーン、顧客の購買目的を掘り下げるジョブ理論、市場適合性を評価するPMFなど、経営や事業立案に不可欠なフレームワークを集約しています。顧客への提案書を作成するコマンドを実行した際に、このファイルをAIに読み込ませて分析の精度を高めています。思考法と問題解決の型をまとめたファイル（thinking-methods.md）
課題を論理的に分解するイシューツリーや、重複なく漏れのない分類を行うMECE、仮説を立てて検証する仮説思考、物事を根本的な原理から考えるファーストプリンシプルなどの思考の枠組みを網羅しています。課題の本質を定義する命令や、ブランドの方向性を決める戦略立案の際に、AIにこの思考の型を意識させるための参照資料として機能しています。
scheduled-tasks/
scheduled-tasks/フォルダは、あらかじめ指定した日時に特定の作業を自動で繰り返し実行するための設定を保管する場所です。
画面から定期実行の命令であるscheduleコマンドを入力すると、その処理内容を記録した定義ファイルがこのフォルダ内に自動で作成されます。これにより、毎日あるいは毎週行うような定型業務を人間の手を介さずにシステム側で自動運用することが可能になります。
現在運用している定期タスクの具体例
daily-working-report/
Googleカレンダーの予定、Gmailの送受信履歴、Slackでの連絡内容から情報を自動で集約し、日報を生成します。成果物はプログラムの保管庫であるGitHubリポジトリやクラウド上の共有棚であるGoogleドライブへ自動保存されます。複数のツールを確認して日報を手書きする手間が省け、日々の稼働が正確に記録されます。weekly-report/
1週間分の活動記録をシステムが自動で振り返り、週報として取りまとめる処理を行います。週末や週明けの報告書作成にかかる時間を大幅に削減する効果が得られます。
rules/
rules/フォルダは、特定の状況やファイルを作業対象にする場合のみ、専用のルールを自動的に読み込ませるための保管場所です。ファイルの最上部に設定データを記述するフロントマターという領域を活用することで、必要なときだけ動作する条件付きの指示を設定することができます。
---
paths:
- "src/api/**/*.ts"
---
# API設計ルール
- Zodでバリデーション必須
- レスポンス形式は { data: T } | { error: string }特定の作業時のみルールを適用する仕組み
すべての対話において常に大量のルールを読み込ませると、AIの記憶容量や処理能力が無駄に消費されてしまうことがあります。作業内容に応じてルールを自動的に切り替えることで、処理の正確性を高める効果が得られます。
編集対象に応じた自動読み込み
ファイル内に paths: という記述を行い、対象となるシステムやフォルダの場所を指定します。たとえば、特定のデータ連携プログラムが格納されているフォルダを指定しておくと、その中のファイルを編集する瞬間にだけ、関連する設計ルールや禁止事項がAIに読み込まれます。常時読み込みとしての活用
この対象場所の指定を記述しなかった場合は、共通の指示書であるCLAUDE.mdと同様に、対話を開始した時点で常に読み込まれる共通ルールとして機能します。
指示書の適切な分割と管理
共通の指示書であるCLAUDE.mdの記述量が推奨される200行を超えて長くなってきた場合は、このrules/フォルダに内容を小分けにして移していく方法が推奨されます。
skills/ と commands/ の使い分け
現在の仕様において、これらはどちらもスラッシュに続くコマンド名で呼び出すことができますが、その役割と機能には明確な違いがあります。最大の相違点は、フォルダの構造だけでなく、AIが状況に応じて自動的に判断して呼び出せるかどうかにあります。
commandsフォルダは過去のバージョンとの互換性を保つための古い形式であり、現在は拡張性の高いskillsフォルダへの移行が推奨されていると推測されます。
commands/ は .md 1ファイル＝1コマンドのシンプルな構成
skills/ はディレクトリ単位で、SKILL.md に加えて参照ドキュメントやスクリプトを一緒に束ねられる
実際の運用における使い分けの基準
1ファイルで完結する単純なワークフローであれば、これまでの名残としてcommandsフォルダに配置しても動作します。しかし、複数のファイルを束ねて複雑な処理を行わせたい場合は、新形式であるskillsフォルダに集約するのが適切なアプローチです。
実際の管理例として、日報作成を行うdayコマンドや、GitHubへのプッシュとGoogleドライブへのアップロードを同時に行うpushコマンドのような単純な指示は、1ファイルの構成で手軽に管理できます。一方で、企画設計チームや技術設計チームのように、複数の役割や多くの参照ファイルを伴う複雑な仕組みは、skillsフォルダの中に独立したフォルダを作って関連資料ごと整理する形が適していると推測されます。
自動呼び出しを制御する設定方法
skillsフォルダに配置した指示書は、AIが自動的に必要性を判断して実行する便利な仕組みになっています。しかし、本番環境へのデプロイ作業など、意図しないタイミングで自動実行されると困るタスクも存在します。
その場合は、SKILL.mdの最上部にあるフロントマターと呼ばれる設定データ記述エリアに、disable-model-invocation: true という一行を追加します。この記述を行うことで、AIによる自動実行を禁止し、ユーザーが手動でコマンドを入力したときだけ動作する安全なスキルへと制限することが可能になります。これにより、AIが消費するコンテキスト、すなわち一度に認識できる情報量を節約し、動作の正確性を高める効果が得られると推測されます。
agents/
skills/フォルダに配置したコマンドはユーザーが明示的に呼び出すものであるのに対し、agents/フォルダに設定を配置すると、AIが状況に応じてこの作業は特定のエージェントに任せようと自律的に判断し、業務を委譲できるようになります。
それぞれのエージェントは独立したコンテキストウィンドウ、すなわち個別の記憶や作業スペースで動作するため、メインの対話履歴を煩雑にすることなく、整理された環境で作業を進めることが可能です。
エージェントの定義ファイルの構成例
---
name: design-lead
description: Use ONLY when the user explicitly requests creative
project planning. Do NOT auto-invoke for general questions.
tools: Read, Glob, Grep, WebSearch, WebFetch, Write
skills: simone-context
---
Read ~/.claude/skills/design-lead/SKILL.md and operate accordingly.運用の鍵となる説明文（description）の記述
設定ファイル内のdescriptionと呼ばれる説明文の書き方が、エージェントを上手にコントロールするための重要な要素となります。ここにどのような場面で呼び出すか、あるいはどのような時には起動させないかという条件を丁寧に指定しておくことで、意図しないタイミングで勝手にエージェントが動き出すのを防ぐ効果が期待できます。
エージェントを呼び出す3つの方法
エージェントを稼働させるには、以下の3つのアプローチが用意されています。Claudeが description を読んで自律的に委譲する
自律的な自動委譲
AIが説明文を読み、必要に応じて自動で役割を切り替えます。メンションによる指定
アットマーク記号を入力すると、候補が自動表示される機能から手動で選択できます。セッションの固定
起動時のコマンドに特定の指定を添えて、一連の対話の間、役割を固定します。
組織的な運用の具体例
実際の管理例として、クリエイティブな案件のヒアリングからブランド戦略の立案、文章作成を行うコピーライティングまでを担う企画設計チームと、オンラインストアの実装やサーバー環境の自動化を担う技術設計チームの合計15体をこのフォルダに登録しています。
本記事は所属する法人とは一切関係ない個人利用のブログです。文章や画像等のメディアは生成AIで作成していますが、掲載前に筆者が事前に事実関係を確認し、編集を行っています。筆者：岩崎修 https://note.com/_osamu_iwasaki_
