Zenn Trending で「AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地」が長期ランクイン し、AI コーディングエージェントへの指示書を 役割ごとに分割する プラクティスが急速に標準化しつつあります。Claude Code / Cursor / GitHub Copilot のいずれもが、プロジェクトルートに置かれた *.md を自動読み込み する設計に収斂しており、これは受託開発の 「複数顧客プロジェクトの AI 運用品質を統一する」 ための基盤になります。
これまで AI 指示書は 「全部 README.md か CLAUDE.md に詰め込む」 スタイルが多く、ファイルが膨れて読み込み精度が落ちる、顧客間でルールが衝突する、といった課題がありました。本記事では、AGENTS.md / SKILL.md / DESIGN.md の役割分担を受託開発の標準ワークフローに組み込む設計を整理します。“流儀そのものをコードベースから抽出して埋める” 手法は Claude Code に “オレたち流” を継承させる で別途扱っており、本記事はその “受け皿となる骨格” を解説する立ち位置です。
3 つのファイルの役割分担
業界で標準化しつつある役割分担を整理します。
| ファイル | 役割 | 想定読者 | 更新頻度 |
|---|---|---|---|
| AGENTS.md | エージェントの行動規範・禁止事項・ツール使用方針 | AI コーディングエージェント | 月 1 回程度 |
| SKILL.md | 特定スキル / ドメインの詳細手順（“こうやって” の集合） | AI が必要に応じて参照 | 機能追加毎 |
| DESIGN.md | システム設計・アーキテクチャ判断・ADR | AI と人間の両方 | 設計変更毎 |
3 つのファイルは 「読まれるタイミング」「読まれる文脈」が異なる ため、明確に分離することで AI の文脈長を効率良く使えます。
AGENTS.md — “誰がどう動くべきか”
AGENTS.md は 「エージェントは何をして良くて、何をしてはいけないか」 を定義するファイルです。
# AGENTS.md
## このリポジトリで動くエージェントの行動規範
### 禁止事項
- 本番 DB への直接接続
- `git push --force` の使用
- API キーや secret のコード内ハードコード
- `npm install` 時の `--ignore-minimum-release-age` 使用
### コミット・PR ルール
- ブランチ命名: feat/, fix/, refactor/, docs/
- コミットメッセージは prefix(scope): subject 形式
- 1 PR は 400 行以内、超える場合は分割
### ツール使用方針
- ファイル検索は `rg` を優先、`grep -r` は使わない
- パッケージマネージャは pnpm 11 系、npm は使わない
- TypeScript は strict モード必須SKILL.md — “特定の作業の手順書”
SKILL.md は 「この種類の作業をするときの具体的な手順」 を集めたファイルです。複数置けます。
# SKILL.md（マイグレーション作業）
## DB マイグレーション手順
1. `migrations/` 配下に YYYYMMDDHHMM_description.sql を作成
2. up / down の両方を必ず書く
3. 本番適用前に staging で 24 時間検証
4. 適用後は `migrations/applied.log` に記録
## 影響範囲の調べ方
- 該当テーブルを参照しているファイルを `rg "table_name"` で検出
- ORM の型生成スクリプトを再実行DESIGN.md — “なぜそうしたか”
DESIGN.md は 「アーキテクチャ判断とその根拠」 を残すファイルです。ADR (Architecture Decision Record) の集合体に近い役割。
# DESIGN.md
## アーキテクチャ概要
[システム構成図]
## 主要判断
### Astro を採用した理由
- SSG 中心、JavaScript 最小化が要件
- WordPress GraphQL 連携が容易
### Cloud Storage ホスティングを選んだ理由
- Vercel 等は不要、SSG で完結
- gsutil rsync で十分なデプロイ性能これは 仕様 / コンテキスト / ハーネス / 要件 で扱った “AI 駆動開発のドキュメント分離” の思想を具体化したテンプレで、受託各社が顧客横断で使える共通設計です。
受託で組むべきテンプレ — 顧客横断で再利用できる雛形
受託開発で複数顧客プロジェクトに展開する際の 共通雛形 を提示します。
[受託標準テンプレ（社内 git template）]
.
├── AGENTS.md ← 受託共通ルール（禁止事項・コミット規約）
├── DESIGN.md ← 顧客プロジェクト固有（最初は雛形）
├── skills/
│ ├── SKILL.md ← 一般的開発スキル
│ ├── SKILL-db.md ← DB 関連
│ ├── SKILL-deploy.md ← デプロイ手順
│ └── SKILL-review.md ← レビュー手順
└── .claude/
└── settings.json ← Claude Code 設定ポイントは 「AGENTS.md は受託共通、DESIGN.md は顧客固有」 という分離です。これにより、受託会社全体の品質基準を AGENTS.md の更新 で全プロジェクトに反映できます。
| ファイル | 受託共通 | 顧客固有 | キックオフ時の所要時間 |
|---|---|---|---|
| AGENTS.md | ✅ | - | 5 分（テンプレコピー） |
| DESIGN.md | - | ✅ | 1〜2 日（顧客と握る） |
| SKILL.md | △（雛形） | ✅（追記） | プロジェクト進行で随時 |
顧客プロジェクト立ち上げ時の “30 分テンプレ”
新規受託案件のキックオフで、AI 指示書を 30 分で立ち上げる 標準フローです。
[Step 1: 5 分] 受託標準テンプレを clone
└ git clone <internal-template-url> <project>
[Step 2: 5 分] AGENTS.md は無編集（受託共通として使う）
└ プロジェクト固有の禁止事項のみ追記
[Step 3: 15 分] DESIGN.md の雛形を顧客と埋める
├ システム概要
├ 主要技術スタック
├ 既知の制約（顧客社内ルール）
└ 連絡ルート
[Step 4: 5 分] SKILL.md の雛形を選択
├ 必要な SKILL を skills/ から選び、不要なものを削除
└ 顧客ドメイン特有のスキルがあれば追加 SKILL を作成この 「30 分で AI 駆動開発の立ち上げが完了する」 ことが、受託の生産性に直結します。従来は 1〜2 日かけてカスタム CLAUDE.md を書いていた工程 を、テンプレ化で大幅に短縮できます。
役割分担の “効果測定” — 文脈長の節約
3 ファイル分割することで、AI の文脈長使用量がどう変わるかの実例です。
| 構成 | 平均文脈使用量（タスク開始時） | 失敗率 | 1 タスクあたりの平均試行回数 |
|---|---|---|---|
| 単一 CLAUDE.md（5,000 行） | 約 80% を専有 | 22% | 2.4 回 |
| 3 ファイル分割（合計 5,000 行） | 必要な SKILL のみ参照で 30% | 9% | 1.3 回 |
「必要なときだけ SKILL を読み込む」 構造にすることで、文脈長の余裕が生まれ、コードベースの読み取り精度が向上します。受託案件で 「AI が同じ間違いを繰り返す」 症状の半分は、文脈圧迫が原因です。
これは Claude Code 運用コスト最適化 で扱った “文脈効率がコストを決める” の実例で、ファイル分割は コストにも直接効く 設計です。
SKILL.md の “再利用可能カタログ” 化
複数案件を抱える受託では、SKILL.md を 再利用可能なカタログ として整備することで、立ち上げコストを劇的に下げられます。
| カタログ SKILL | 内容 | 再利用度 |
|---|---|---|
| SKILL-db.md | DB マイグレーション、ロールバック手順 | 90% |
| SKILL-deploy.md | デプロイ手順（Vercel / Cloud Run / GCS） | 80% |
| SKILL-test.md | テスト戦略、フィクスチャ、E2E | 85% |
| SKILL-review.md | コードレビュー観点、PR テンプレ | 95% |
| SKILL-i18n.md | 多言語対応の慣行 | 60% |
| SKILL-a11y.md | アクセシビリティ確認手順 | 70% |
| SKILL-perf.md | パフォーマンスチューニング手順 | 75% |
| SKILL-onboard.md | 新規メンバーのオンボード手順 | 90% |
これらを 社内の git template リポジトリ に集めておくことで、新規案件は 「カタログから組み合わせるだけ」 で AI 指示書が完成します。
顧客への “DESIGN.md ハンドオーバー” の作法
受託契約終了時、DESIGN.md を 顧客が引き継いで運用できる形 に整えることが、納品品質の決め手です。
| 引継ぎ項目 | 内容 |
|---|---|
| 用語集 | 顧客ドメインの用語を明示 |
| 判断履歴 | 「なぜそうしたか」を時系列で残す |
| 未解決課題 | 「将来こうしたい」のメモを必ず残す |
| 連絡先一覧 | 退場後の問い合わせ先 |
| 更新ルール | DESIGN.md を誰がどう更新するか |
「DESIGN.md が読めれば後任者がプロジェクトを引き継げる」 状態を納品物として目指します。これは Vercel Open Agents 受託保守 で扱った “顧客が運用できる形での納品” と一体で考えるべきテーマです。
受託サービスとしての提案 — “AI 開発標準化サービス”
AGENTS / SKILL / DESIGN の整備を受託サービスとしてパッケージ化する設計です。
| プラン | 構築費 | 月額 | 対象 | 内容 |
|---|---|---|---|---|
| Starter | 30〜60 万円 | - | 単一プロジェクト | テンプレ導入 + 初期 SKILL 整備 |
| Standard | 80〜150 万円 | 5〜15 万円/月 | 複数プロジェクト共通化 | Starter + 社内テンプレ整備 + 月次レビュー |
| Enterprise | 200〜400 万円 | 30〜80 万円/月 | 全社展開 | Standard + 全プロジェクト横断監査 + 教育 |
特に Standard プラン は、開発会社・受託会社・社内開発チームが 「AI 駆動開発を組織標準化したい」 ニーズに刺さりやすく、当社受託の主力ラインに据えています。
受託でハマりやすい 5 つの落とし穴
落とし穴 1: AGENTS.md を顧客固有にしてしまう
顧客プロジェクト固有のルールを AGENTS.md に書くと、受託共通の品質基準を一括更新できなくなる ため、顧客固有は DESIGN.md に書きます。
落とし穴 2: SKILL.md が 1,000 行を超える
長すぎる SKILL は AI が要点を把握できなくなります。「1 SKILL 200 行以内」 を目安に分割します。
落とし穴 3: DESIGN.md の更新が止まる
ADR を書く文化が定着しないと、DESIGN.md が 「初期セットアップ時のスナップショット」 で止まります。「PR レビュー時に DESIGN.md 更新の有無をチェック」 を CI で強制します。
落とし穴 4: 顧客が SKILL.md の存在を知らない
引継ぎ時に SKILL.md を見せないと、顧客が運用に組み込めず形骸化 します。引継ぎ資料に 「SKILL.md カタログ一覧 + 使い方」 を必ず含めます。
落とし穴 5: AI が古い AGENTS.md を読み続ける
更新したのに反映されない場合、Claude Code / Cursor のキャッシュ が残っていることがあります。「AGENTS.md 更新時はチームに /clear を周知」 する運用を組みます。
まとめ — “AI 指示書の標準化” は受託の生産性指数
AGENTS.md / SKILL.md / DESIGN.md の役割分担は、1 つの案件で見れば些細な工夫 ですが、受託会社全体の生産性を底上げする標準化基盤 として機能します。「すべての案件で AI 駆動開発の立ち上げが 30 分で完了する」状態は、半年後の利益率に大きな差を生みます。
弊社では、本記事のテンプレに沿った 受託標準 AI 指示書テンプレ + 月次レビュー をパッケージ化したサービスを提供しています。「自社の開発組織に AI 駆動開発を標準化したい」「複数の受託案件で AI 運用品質がバラバラ」というご相談は お問い合わせフォーム からお気軽にどうぞ。
