クイックサマリー：AGENTS.md・SOP文書・Claude Code の Skills・MCP（Model Context Protocol）を組み合わせることで、コーディングエージェントを「思いつきで質問するチャット」ではなく「規則・検証・記録を伴う開発統制系」として運用できます。対応CLIは Claude Code / Codex CLI / Antigravity CLI など複数の主要コーディングエージェントで、いずれもオープンなテキストファイル形式のため特別なライセンス契約は不要です。
導入：「AIなしで手書きできますか」に感じた違和感
「AIを使うのはいいけれど、結局は手でコードを書けないと」――就労支援や採用面接でこう言われて、モヤモヤした経験はないでしょうか。実務では日常的にコーディングエージェントを使いこなしているのに、評価の場だけ「素のエディタで手打ちできるか」を主な物差しにされると、実際に問われている能力とズレを感じます。
この記事では、エンジニアの Ryo Minegishi 氏が Zenn に投稿した記事「『AIなしで手書きできますか？』は何を測っているのか」を軸に、AGENTS.md・MCP・Skills を組み合わせた「認知的外骨格」という開発統制の考え方と、実際に自分のプロジェクトへ取り入れる手順を紹介します。
- AGENTS.md・SOP・Skills・MCP がそれぞれ何を担っているか
- 実際にどう組み合わせて「統制された開発系」を作るか
- Claude Code / Codex CLI での具体的な設定手順
- 導入時の注意点とセキュリティ上の論点
何を伝えている記事なのか：プロンプトではなく「開発統制系」
元記事の筆者は、NousResearch/Hermes-Agent への継続的なコントリビューションや、派生プロジェクトでの Watchdog・プロセス所有権・再起動機構の実装まで行っている開発者です。その筆者が伝えているのは、「チャット欄に『これを作って』と打ち込む」レベルの利用ではなく、次のようなレイヤーを積み重ねた運用だという点です。
- AGENTS.md：恒常的なポリシー・禁止事項・品質基準を置く場所
- SOP（標準作業手順書）：着手条件・セキュリティ・検証・完了条件を定義する文書
- Skills：専門作業を再利用可能な単位にする仕組み
- MCP経由のSequential Thinkingツール：問題分解と段階的な検討を補助
- Context7等：関連ライブラリの文書を取得し、公式ドキュメントや現行ソースコードと照合する
元記事によると、筆者がコーディングエージェントへ毎回読ませているSOP群は執筆時点で「20ファイル・合計801行」あり、入口となる「SOP-Implementation-Start-Gate.md」では、実装前に「PC全体とプロジェクトローカルのAGENTS.mdを読む」「適用基準が不明・矛盾・不足している間は実装を始めない」ことなどを要求していると具体的に説明されています。これは単なるプロンプトのテンプレートではなく、「何を実行してよいか、何を証拠とし、どこで止まり、誰が責任を持つか」を定義した統制系だと筆者は位置づけています。
自分のプロジェクトに導入する手順
AGENTS.md・MCP・Skills はいずれもオープンな仕様/機能で、特別なインストーラは不要です。公式ドキュメントや実例を参考に、以下の順で導入するのが再現性の高い手順です。
1. AGENTS.mdを作る
AGENTS.md は、AIコーディングエージェントに「プロジェクトのルール」を伝えるためのプレーンテキストファイルです。プロジェクトルートに配置し、禁止事項や制約を箇条書きで書きます。
# AGENTS.md の記述例
## Constraints
- src/legacy/ 配下は変更しない
- 外部APIキーをコードに直書きしない公開されている検証（arXiv:2601.20404、2026年3月公開）では、10リポジトリ・124件のプルリクエストを対象に、AGENTS.md の有無でAIコーディングエージェントの挙動（実行時間・トークン消費）がどう変わるかを比較する試みが報告されています。具体的な改善幅は原論文で確認する必要がありますが、AGENTS.md の効果を定量的に検証する研究が出てきていること自体は、この仕組みが「気休め」ではなく実際に挙動へ影響を与えることを示唆しています。
2. Claude Code の Skills を配置する
Claude Code では、繰り返し使う専門手順を .claude/skills/<skill-name>/SKILL.md に配置することで、エージェントが必要に応じて自動参照したり、スラッシュコマンド（/skill-name）で明示的に呼び出せるようになります。
手動配置する場合はプロジェクト直下にディレクトリを作成します。
# 手動配置のディレクトリ例
.claude/
└── skills/
└── code-review/
└── SKILL.mdマーケットプレイス経由でプラグイン形式のスキル集を導入する場合は、次のようにコマンドを実行します。
/plugin marketplace add <組織名/リポジトリ名>
/plugin install <プラグイン名>@<マーケットプレイス名>Antigravity CLI（agy）を使う場合は、ワークスペース単位では <プロジェクトルート>/.agents/skills/、グローバル設定では ~/.gemini/antigravity-cli/skills/ に SKILL.md を配置する構成になっています。
3. MCPサーバーを接続する
MCP（Model Context Protocol）は、AIエージェントを外部のデータベース・API・ツールへ接続するためのプロトコルです。VS Code や Claude Code では、設定ファイルにサーバー定義を追記して有効化します。
// .vscode/mcp.json の例
{
"servers": {
"postgres": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"]
}
}
}元記事では、この MCP 経由で「Sequential Thinking」ツールを接続し問題分解を補助させたり、「Context7」等で関連ライブラリの最新ドキュメントを取得し、重要な仕様は公式ドキュメントや現行ソースコードと照合する、という使い方が説明されています。
ルールあり／なしで何が変わるのか：具体的な差分イメージ
「SOPやAGENTS.mdを整備すると、実際にエージェントの挙動がどう変わるのか」は文章だけでは伝わりにくい部分です。たとえば「外部APIを呼び出す関数にリトライ処理を追加する」という小さなタスクを例に、ルールなしの場合とSOP/AGENTS.mdを効かせた場合の典型的な差分を比較してみます。
ルールなし（素のチャット依頼）でありがちな挙動
You: リトライ処理を追加して
Agent: 追加しました。exponential backoffを実装し、
3回まで自動リトライするようにしています。
（実際には存在しないretry_with_backoff()という
架空のユーティリティ関数をimportしたコードを生成）
You: このretry_with_backoff、どこにあるの？
Agent: 申し訳ありません、そのユーティリティは
このプロジェクトには存在しませんでした。
自前で実装します。
（テストを書かずに実装だけ提示、既存のリトライ設定と
重複する形で新しい定数を追加）このパターンでは、存在しないAPI・関数の捏造（元記事が指摘する「架空のAPIを捏造する」挙動そのもの）に気づくまで往復が発生し、テストや既存設定との整合確認は人間が都度指摘しない限り行われません。
SOP + AGENTS.mdを効かせた場合の典型的な挙動
You: リトライ処理を追加して
Agent: [SOP-Implementation-Start-Gate.md を参照]
着手前チェック:
- AGENTS.md の制約を確認 → 外部API変更はテスト必須
- 既存のリトライ実装がないか grep で検索
→ utils/http_client.py に既存のretry設定を発見
- 変更範囲: src/api/client.py の1関数のみ（可逆）
実装方針を先に提示します:
- 既存の http_client.py の retry 設定を流用（新規実装しない）
- 変更前にテストを1件追加し、現状の挙動（リトライなし）を
レッドで確認してから実装します
この方針でよろしいですか？
You: OK
Agent: [実装 → テスト実行 → 差分提示]
test_client_retry.py: 1 passed
変更ファイル: src/api/client.py（+8 -1行）
検証: 実際にモックサーバーで3回失敗→成功のケースを確認済み
省略した検証: 本番相当のレイテンシ環境でのテストは未実施
（理由: ローカル環境に本番相当の遅延シミュレータがないため）この例が示すように、SOPの着手ゲートが効くと「既存コードを先に調べる」「変更前に方針を確認させる」「テストで検証してから完了と主張する」という手順がエージェント側の自発的な行動として組み込まれます。元記事の言葉を借りれば、これが「AIの出力を読めず、誤りを論理的に説明できない状態」と「エージェントを厳格に統制して成果に責任を持つ状態」の実務上の違いです。なお、この比較は元記事および一般的なSOP運用パターンから構成した典型例であり、特定のログをそのまま転載したものではない点にご留意ください。
実際の開発フローに組み込む方法
この構成を実務にどう組み込むかは、元記事の「共通規格」の記述が参考になります。筆者はSOPで次のような完了条件を課していると述べています。
- 要求から実装、検証証拠までを追跡可能にする
- 小さく可逆な変更を優先し、ロールバック経路を持つ
- 新しい証拠なしに「完了」と主張しない
- 挙動変更にはテストを要求する
- 省略した検証、その理由、残余リスクを記録する
Claude Code のワークフローに当てはめると、CLAUDE.md（またはAGENTS.md）に恒常ルールを書き、実装前に /plan 相当のコマンドやサブエージェントでリスクを洗い出し、実装後は hooks でテスト・lintを自動実行、最後に /review 相当のコマンドや独立したレビュー用エージェントで差分をチェックする、という一連の流れに対応します。元記事でも「AIの出力を読めず、誤りを論理的に説明できず、検証の仕組みも作れない状態」と「エージェントを厳格に統制して成果に責任を持つ状態」は大きく異なると強調されています。
SOPを肥大化させないための工夫：トークン消費とコンテキスト劣化への対策
「20ファイル・801行のSOP」と聞くと、「毎回そんな量のテキストを読ませたらトークン代が跳ね上がるのでは」「コンテキストウィンドウが圧迫されてAIが指示を見落とすのでは」という懸念が浮かびます。実際、これは正当な懸念で、全てのファイルを常に全文読み込ませる運用は非効率かつコンテキスト劣化のリスクを伴います。実務では次のような設計でこれを抑えるのが一般的です。
- オンデマンド参照を基本にする：恒常的に必要なのは「着手ゲート（Start-Gate）」のような入口ファイルだけで、そこから「このタスクの種類なら、このSOPファイルを読め」という参照ゲートを張る構成にします。本記事の元になった運用元（AI for GOOD の CLAUDE.md）でも、「常時ロードするのは数十行の索引だけ、詳細ルールはタスクの種類に応じて都度Readする」というゲート方式を採用しており、801行全てを毎ターン読み込む設計にはなっていません。
- サブエージェント・Skillsへの権限とコンテキストの局所化：レビュー・セキュリティ監査・特定ドメインの実装など、専門性の高い作業は独立したサブエージェント（例: Claude Code の
.claude/agents/）や Skills に切り出し、そのタスクに必要なルールだけをそのエージェントのコンテキストに閉じ込めます。メインの会話コンテキストには「どのサブエージェントを呼ぶか」という薄い判断だけを残すことで、本体側のトークン消費と指示の見落としリスクを同時に抑えられます。 - 索引ファイルで全体を要約する：ルールファイルそのものではなく、「どんな状況でどのファイルを読むべきか」を1枚の表にまとめた索引ファイル（例: CLAUDE.md内のタスク別ルール参照ゲート表）を常時ロード対象にし、詳細な手順書は必要になった瞬間だけ読み込む二段構成にします。
この設計により、SOP・AGENTS.mdの分量を増やしてもエージェントの応答速度やコスト、指示の追従精度を大きく損なわずに運用できます。逆に言えば、801行を毎回丸ごとプロンプトに詰め込む運用は非効率なアンチパターンであり、「統制の厚みを増やす」ことと「常時コンテキストを肥大化させる」ことは分けて設計する必要がある、という点は導入前に押さえておく価値があります。
類似アプローチとの比較
| 仕組み | 対応CLI | ライセンス | 位置づけ | 特徴 |
|---|---|---|---|---|
| AGENTS.md（認知的外骨格の構成要素） | Claude Code / Codex CLI / Antigravity CLI 等 複数対応 | オープンなテキスト規格（特定のライセンスなし） | プロジェクト横断の恒常ルール | 複数ベンダーのエージェントが共通で読み込む前提の規格 |
| CLAUDE.md | Claude Code専用 | Claude Code の仕様に準拠 | Claude Code向けの指示書 | 階層的に配置可能（グローバル/プロジェクト/ディレクトリ単位） |
| .cursorrules（Rules for AI） | Cursor | Cursorの仕様に準拠 | エディタ単位のルール設定 | Composer/Agentモードのリファクタに連動 |
| MCP（Model Context Protocol） | Claude Code / VS Code / 対応クライアント全般 | オープンプロトコル | 外部システムとの接続層 | DB・API・ファイルシステム等へエージェントを接続 |
注意点・制約・セキュリティ
この構成には利点だけでなく、正直に向き合うべき注意点もあります。
- 悪意ある設定ファイルによる情報流出リスク：Claude Code では過去に、悪意あるリポジトリを開くだけで認証情報が外部送信される脆弱性（CVE-2026-21852）や、同意確認前にMCP・フックが悪用される脆弱性（CVE-2025-59536）が報告されています（いずれも修正済み）。また、MCPサーバー経由の通信自体も接続先が侵害されていれば機密流出のリスクが残るため、外部サーバーや共有リポジトリの信頼性は常に検証が必要です。
- Skillsの自動実行：同記事では、
disable-model-invocationを設定していないスキルは、AIが「使うべき」と判断すると勝手に発動する可能性があると指摘されています。想定外のタイミングで重い処理やファイル変更が走るリスクがあるため、権限スコープの設計が重要です。 - AIの出力を無条件に信じない：元記事の筆者自身も「AIは平気で存在しない架空のAPIを捏造する」「テストを都合よく弱めてパスさせようとする」と明言しており、変更範囲の制限・全件レビュー・回帰テストの義務化・型検査/Lint/CIの全パスといった検証プロセスとセットで運用する前提です。
- 企業利用時のガバナンス：Enterprise契約・ローカルモデル・機密データの投入制限・アクセス制御・監査ログなど、扱うデータの機密区分や業界規制に応じた個別の運用設計が必要になります。
まとめ
- AGENTS.md・SOP・Skills・MCPを組み合わせることで、コーディングエージェントを「都度チャットで頼む道具」から「規則・検証・記録を伴う開発統制系」へ引き上げられます。
- 「AIなしで手書きできるか」という評価軸は、構文の暗記量や無支援時の入力速度は測れても、根本原因の特定力・セキュリティ設計・回帰テスト設計・AIの誤りを見抜く力といった実務で価値のある能力を十分には測れません。
- SOPやルールファイルは分量を増やすほど効果が上がるわけではなく、オンデマンド参照やサブエージェントへの局所化でトークン消費とコンテキスト劣化を抑える設計とセットで運用する必要があります。
- 導入にあたってはMCP経由の情報流出やSkillsの自動実行など、セキュリティ面の注意点も踏まえた権限設計が必要です。
より体系的にAGENTS.mdやSOPの設計を学びたい場合は、Claude Code や Codex CLI の公式ドキュメントも参照してみてください。
よくある質問（FAQ）
AGENTS.mdとCLAUDE.mdは何が違いますか？
AGENTS.mdは特定のベンダーに縛られないオープンなテキスト規格で、Claude Code・Codex CLI・Antigravity CLIなど複数のコーディングエージェントが読み込める前提で使われます。一方CLAUDE.mdはClaude Code専用の指示ファイルで、階層的な配置など同ツール固有の機能に対応しています。プロジェクトを複数のエージェントで併用する場合はAGENTS.md、Claude Code専用の細かい制御が必要な場合はCLAUDE.mdを使い分けるのが実務的です。
SOP（標準作業手順書）は必ず自分で書く必要がありますか？
元記事の筆者は20ファイル・合計801行のSOPを自作して運用していますが、最初から全て自作する必要はありません。まずは着手条件・完了条件・禁止事項程度の簡易なAGENTS.mdから始め、プロジェクトの規模や失敗の経験に応じてSOPを追加していく段階的な運用が現実的です。
MCPサーバーを接続するとコードや機密情報が外部に送信されますか？
MCPサーバーの実装次第です。接続先が信頼できないサーバーだったり、サーバー自体が侵害されている場合は情報流出のリスクがあります。CVE-2026-21852のように、MCPサーバーを悪用して機密情報を外部送信させる攻撃が報告された事例もあるため、接続先の信頼性確認とアクセス制御が必要です。
ローカルLLMやオンプレ環境でも同じ構成は使えますか？
AGENTS.md・SOP・Skillsはテキストファイルの規約であり特定のクラウドサービスに依存しないため、ローカルLLMを使うツールでも概念上は適用できます。ただしMCPサーバーやSkillsの自動実行機能を使う場合は、接続先の実装がローカル環境をサポートしているか個別に確認する必要があります。
この仕組みを導入すればコードを一切書けなくても開発できますか？
いいえ。元記事の筆者も『AIを使えば誰でもエンジニア』ではないと明確に述べています。AIは架空のAPIを捏造したり、テストを弱めてパスさせようとすることがあるため、生成物のレビュー・回帰テストの追加・セキュリティ境界の判断といった人間側の検証能力が引き続き前提になります。
採用面接や就労支援で『AIなしで手書きできるか』と聞かれたらどう答えればよいですか？
元記事では、素の入力速度よりも『AIを含む開発系全体をどこまで理解し、制御し、検証し、説明できるか』を測る実技（要求の明文化、不適切な差分の指摘と修正、回帰テストの追加、アーキテクチャの説明など)の方が実務に即した評価だと提案されています。面接の場では、自分がどのような検証プロセスを組んで開発しているかを具体的に説明するのが一つのアプローチです。
Claude Code以外のツールでも同様の構成は作れますか？
作れます。Codex CLIやAntigravity CLIもAGENTS.mdやSkillsに相当する仕組みを持っており、CursorであればRules for AI（.cursorrules）が近い役割を果たします。ツールごとに設定ファイルの配置場所や記法は異なるため、各公式ドキュメントで最新の仕様を確認してください。
コメント