CLAUDE.md / AGENTS.md 設計パターン完全ガイド — チーム運用の実践フレームワーク（2026年版）

AIコーディングの「相転移」と指示ファイルのインフラ化

homulaは、エンタープライズ企業向けにAIエージェントの戦略策定・PoC・実装・運用・内製化までを一気通貫で支援するAIインテグレーターです。本記事では、開発チームのAIコーディングエージェント運用を左右する「指示ファイル」の設計パターンを体系的に解説します。

2024年後半から2026年初頭にかけて、ソフトウェア開発は「コード補完」から「エージェント主導」への相転移（Phase Shift）を経験しました。先進的なエンジニアリング組織ではコードの約80%がエージェントによって生成・修正される段階に達しており、GitHub Copilotの累計ユーザーは2,000万人を突破、Gartnerは2028年までにエンタープライズ開発者の75%がAIコードアシスタントを使用すると予測しています。

この変化を支える技術的基盤が、CLAUDE.md、AGENTS.md、SKILL.mdといった**指示ファイル（Instruction Files）**です。個人のプロンプトエンジニアリングとは異なり、これらはリポジトリにコミットされ、バージョン管理される「指示としてのインフラ（Instruction as Infrastructure）」として機能します。

しかし、日本のエンジニアリング組織の大半は、指示ファイルを「個人のプロンプトTips」として扱っているのが現状です。ZennやQiitaには「俺のCLAUDE.mdを晒す」系の記事が並びますが、チーム標準としての設計・配布・レビュー・セキュリティを体系化した情報は存在しません。

本記事は、テックリード・EM・VPoE・CISOが「自社の指示ファイル運用をどう設計すべきか」を判断するための包括的フレームワークを提供します。

5つの指示ファイルシステムの仕様比較

2026年3月現在、主要なAIコーディングエージェントはそれぞれ独自の指示ファイルシステムを持っています。チームでの導入判断に必要な軸で整理します。

CLAUDE.md の設計思想

Claude Codeの指示ファイルは「エージェントが推測できないプロジェクト固有の情報」を記述する場所として設計されています。公式のベストプラクティスでは、記述すべき情報と除外すべき情報が明確に区別されています。

記述すべき項目: プロジェクト固有のビルド・テスト用Bashコマンド、デフォルトと異なる独自のコードスタイル、アーキテクチャ上の決定事項（ADR）、リポジトリ固有のエチケット（ブランチ命名規則等）。

除外すべき項目: エージェントがコードから推測可能な標準規約、頻繁に変更される一時的な情報、長大なチュートリアル、自明な「クリーンコードを書け」といった指示。

エンタープライズ利用で重要なのはmanaged policyの仕組みです。Linux/WSLでは /etc/claude-code/CLAUDE.md にIT/DevOps管理の組織標準を配置でき、MDM・Ansible等で全開発者マシンに配布可能です。さらに、server-managed settingsにより、Claude.ai管理コンソールからMDMなしでもポリシーを配信できます。

AGENTS.md のエコシステム

OpenAIが提唱しLinux Foundation Agentic AI Foundation（AAIF）に寄贈されたAGENTS.mdは、ツール非依存の「エージェントのためのREADME」として標準化が進んでいます。GitHub Copilot coding agent、Cursor、VS Code、Aider等の主要ツールがAGENTS.mdの読み取りをサポートしており、事実上のクロスツール標準になりつつあります。

最大の特徴は**階層的な発見プロセス（Discovery Chain）**です。グローバルスコープ（~/.codex/AGENTS.md）からプロジェクトルート、サブディレクトリへと指示が結合され、下位の指示が上位を実質的にオーバーライドします。合計サイズはデフォルト32KiBに制限されており、この制約がモジュラー設計を促進しています。

3プレーンモデル — 指示ファイル設計の構造的フレームワーク

個人の指示ファイルとチームの指示ファイルを分けるのは「量」ではなく「構造」です。2026年の先進チームが収斂している設計思想を「3プレーンモデル」として整理します。

図1: 3プレーンモデル。指示・強制・手続きの分離がエンタープライズ指示ファイル設計の基本構造。

Plane 1: 指示プレーン — 「何を知るべきか」

CLAUDE.mdやAGENTS.mdに記述する、エージェントへの「知識注入」層です。ここに書くのは、エージェントがコードベースから自動推測できない情報に限定します。

日本のPlaid社（エンジニア約5名、TypeScript + Goのモノレポ）は、この分離を明確に実践し、PR生成数を月150件から約600件に拡大した事例を公開しています。彼らの定式化は簡潔です。docs/rules = エージェントが知るべきこと、permissions/hooks = エージェントが絶対にやってはいけないこと。

Plane 2: 強制プレーン — 「何を阻止すべきか」

指示プレーンが「お願い」なら、強制プレーンは「物理的な壁」です。Claude Codeのhooks機能はこの思想を体現しています。

典型的な実装例:

• PostToolUse hookでPrettierを自動実行 → エージェントにフォーマットを「覚えてもらう」必要がなくなる
• PreToolUse hookで .env や .git/ への書き込みをブロック → 人間可読の拒否理由をエージェントに返し、代替行動を促す
• ConfigChange hookで設定変更を構造化ログに記録 → 監査証跡の自動生成

Anthropicはhooksを「決定論的制御」として位置づけており、エージェントの確率的な判断に依存しない統制を実現する仕組みです。

Plane 3: 手続きプレーン — 「どう実行するか」

SKILL.mdやsubagentsによる、タスク単位のパッケージ化層です。指示プレーンを肥大化させずに専門知識を提供でき、未使用時のトークン消費がゼロである点がエンタープライズ運用での大きな利点です。

Anthropicが推進するAgent Skills標準は、Claude Code・Claude.ai・Claude APIの全プラットフォームで動作し、26以上のツールが対応するオープンフォーマットです。一度整備したSkillは他部門・他ツールに横展開でき、組織のポータブルな知的資産として蓄積されます。

チーム運用の実践パターン — 日本企業の事例に学ぶ

ルーターパターン — 「巨大な1ファイル」からの脱却

OpenAIのハーネスエンジニアリングチームは、巨大なモノリシック指示ファイルが「予測可能な方法で失敗した」と報告し、約100行のエントリポイントが構造化された docs/ ディレクトリを参照する設計に移行しました。Datadog社もモノレポ環境で同様のルーターパターンを採用しています。

# AGENTS.md（ルーター：約100行）

## ビルド・テスト
npm run build && npm run test

## アーキテクチャ
→ docs/architecture/overview.md を参照

## API設計規約
→ docs/standards/api-design.md を参照

## ドメイン用語集
→ docs/glossary.md を参照（必ず確認してからコード生成）

このパターンのメリットは3つあります。常時ロードされるトークンが最小限に抑えられること、各ドキュメントの所有権が明確になること（CODEOWNERSで管理可能）、そしてCIで各ドキュメントの整合性を検証できることです。

300行ルール — コンテキスト飽和への対策

日本のエンジニアコミュニティで提唱されている実践的な知見として、CLAUDE.mdやAGENTS.mdのサイズを300行以内に収める原則があります。指示が長大化するとエージェントの注意力が分散し、逆に指示に従わない確率が高まるためです。

Anthropic公式も200行以下を推奨し、超過時は .claude/rules/ やimport（@ファイル名）での分割を案内しています。Codex CLI側は32KiBのハードキャップが設計上の制約として機能しています。

ドメイン用語集 — エージェントの「誤解」を防ぐ

日本の開発コミュニティから報告されている効果的なパターンが、ドメイン用語集の指示ファイルへの組み込みです。「メンバー（有料プラン契約者）」と「ゲスト（未ログイン）」のように、コード上の変数名とビジネス上の概念の対応表を含めることで、エージェントのロジックミスを劇的に減らせます。

日本企業の実践事例

Knowledge Work社はClaude Codeを活用して月400件以上のPRを生成するワークフローを公開しています。注目すべきは、確率的なプロンプトに頼らず、リンターとPreToolUse hookによる決定論的な制御を重視している点です。

READYFOR社は社内でClaude Code設定の共有セッションを開催し、コーディング規約やコミットルールを「プラグイン」として全メンバーに配布する運用を実践しています。

Appbrew社はセッション終了時や圧縮前に自動でCLAUDE.mdの更新を提案するhookを構築しました。「人がコマンドを実行し忘れる」「新メンバーは存在すら知らない」という運用課題をhookで解消するアプローチです。

マルチツール環境の相互運用戦略

「1ファイルで全ツール対応」は不可能

2026年3月現在、Claude Code・Codex CLI・Cursor・GitHub Copilot・Antigravityのすべてで完全に共通化された1ファイルを作成することは技術的に不可能です。Cursorの .mdc フロントマター、Antigravityのスキル定義YAML、Copilotの applyTo グロブ指定など、各ツール固有の制御機構がMarkdownの外側に存在するためです。

しかし、基本的な開発規約やドメイン知識の同期は可能です。4つの選択肢を整理します。

実務上の推奨はルーターパターンです。各ツールのエントリファイル（CLAUDE.md、AGENTS.md等）はそれぞれ短いルーターとして機能させ、共通のドキュメントツリーを参照させます。これにより、ドメイン知識の一元管理とツール固有制御の両立が実現できます。

セキュリティ — 指示ファイルは攻撃面である

指示ファイルポイズニング

指示ファイルが単なるドキュメントではなく「実行可能ポリシー」であるという認識が、2026年のセキュリティ研究で確立されました。

Check Point社は2026年2月、リポジトリに含まれる設定ファイル（hooks、MCPサーバー、環境変数）を通じたRCE（リモートコード実行）とAPIトークン窃取の攻撃手法を報告しています。NVIDIA社も2026年1月、.cursorrules や CLAUDE.md / AGENTS.md ファイルを間接プロンプトインジェクションのベクトルとして名指しで警告しました。

Prompt Security社の研究は、VS CodeがAGENTS.mdの内容を全リクエストに自動インジェクトする仕組みを利用し、悪意あるAGENTS.mdがデータ窃取をエージェントに指示できることを実証しています。

スキルのサプライチェーンリスク

Snyk社の「ToxicSkills」レポートは、エージェントスキルのエコシステムにおけるマルウェア、プロンプトインジェクション、認証情報窃取のパターンを大規模スキャンで報告しています。SKILL.mdは実行可能なスクリプトやhookを含むことができるため、指示ファイル単体よりも攻撃面が広がります。

エンタープライズでの実践的対策

1. 指示ファイルをCODEOWNERS対象に追加し、変更にセキュリティチームのレビューを必須化する
2. managed settingsで disableBypassPermissionsMode を有効化し、開発者が権限モードを迂回できないようにする
3. hookで .env や秘匿ファイルへのアクセスをdenyリスト化する（Anthropic公式でも典型例として例示）
4. 外部スキルのホワイトリスト制を導入し、検証済みのスキルのみ許可する
5. ConfigChange hookで設定変更の監査ログを自動記録する

エンタープライズガバナンス設計 — コンプライアンスとの接続

指示ファイルとAIガバナンスフレームワーク

指示ファイル・managed settings・スキルは、AIシステムの振る舞いに影響を与える設定アーティファクトです。既存のAIガバナンスフレームワークとの対応関係を整理します。

NIST AI RMF 1.0は、GOVERN/MAP/MEASURE/MANAGEの4機能でAIリスク管理を体系化しており、特にGOVERN（組織プロセス・ポリシー・説明責任）は指示ファイルの管理プロセスに直接適用可能です。

ISO/IEC 42001はAIマネジメントシステムのポリシー・目標・プロセスの継続的改善を要求しており、「指示 + 強制 + 監視」をシステムコンポーネントとして管理する思想と整合します。

具体的には、以下の対応付けが可能です。

3段階の組織展開モデル

図2: 指示ファイルの組織展開ロードマップ。パイロットから全社ガバナンスまで段階的に拡張する。

Instruction Ops — 新たなエンジニアリングディシプリン

指示ファイルの管理は、GitOps/InfraOpsと同じ「Ops」の特性を備えつつあります。OpenAIは「ハーネスエンジニアリング」として、エンジニアの役割をコード記述から「環境設計・意図明確化・フィードバックループ構築」へ再定義しています。Martin Fowlerも「Context Engineering for Coding Agents」で、コンテキスト/ハーネスエンジニアリングを体系的な実践として位置づけました。

指示ファイル管理に見られる「Ops」の特徴を整理すると、以下の共通点が浮かび上がります。変更管理（Gitによるバージョン管理とレビュー）、自動化（hookによる更新提案、CI検証）、配布（managed settingsによるポリシー配信）、品質シグナル（Vercel社はAGENTS.mdの8KBドキュメントインデックスで評価パスレート100%を達成）。

コミュニティ主導の初期ツールとして、RulixやRule-porterが登場しています。Rulixは複数ツールのルールセットを同期し、トークン/長さバジェットを管理するツール、Rule-porterはCursorルールをCLAUDE.md / AGENTS.md / Copilot instructionsに変換するツールです。いずれも初期段階ですが、「Instruction Ops」のニーズが現実に成長していることを示しています。

まとめ — 指示ファイルは「第一級の成果物」である

本記事で提示したフレームワークを3つのポイントに集約します。

3プレーンで設計する: 指示（何を知るべきか）・強制（何を阻止すべきか）・手続き（どう実行するか）を分離する。CLAUDE.mdに「何でも書く」運用は、チーム規模で確実に破綻します。

セキュリティを前提に構築する: 指示ファイルはエージェントの制御面であり、攻撃面でもあります。CODEOWNERS、managed settings、hookによる強制を「初日から」組み込んでください。

段階的に展開する: パイロット（1チーム）→ 標準化（複数チーム）→ 全社ガバナンスの3段階で進めることで、学習コストとリスクを制御できます。

Copilot/Claude Code/Cursor/Codex CLIが混在するマルチツール環境の統制設計、AGENTS.md/CLAUDE.md/SKILL.mdの組織標準テンプレート構築、MCP接続基盤のセキュリティ設計まで、homulaのFDEチームが上流から下流まで一気通貫で支援します。

AIコーディングエージェント導入支援の詳細を見る

無料相談を予約する（30分）