TL;DR
- AIエージェント開発は、ツール選定より先に 仕様・権限・テスト・運用 の4層を決めると安定する。
- 外部から参照される入口ページは、個別ノウハウではなく「導入順序」と「判断表」を持つ親ハブにしたほうが強い。
- まず SDDハブ で仕様を固定し、次に AIが迷わないリポジトリ設計、AIコーディング導入のセキュリティ設計、AI生成コードのテスト戦略 へ進む。
なぜ親ハブが必要なのか
AIコーディングツールの導入は、最初だけ見ると簡単です。Claude Code、Codex、Cursor、GitHub Copilot などを入れれば、コードを書く速度はすぐに上がります。
でも、チーム運用に移すと別の問題が出ます。
- 何を作るべきかが曖昧なまま、AIが実装だけ進める
- 権限を広く渡しすぎて、危ないファイルや外部サービスに触れる
- レビューする人間が、AIの意図を復元する作業で詰まる
- テストやCIが追いつかず、速くなったはずなのにリリースが重くなる
- 事故後に、なぜその判断になったのかを追跡できない
これは「どのAIツールが優れているか」だけでは解けません。必要なのは、AIエージェントを開発プロセスに入れる前に、どの層を誰が設計するかを決めることです。
この記事は、その入口になる親ハブです。個別記事へ直接飛ぶ前に、まず全体の地図を置きます。
AIエージェント開発の4層モデル
AIエージェント開発は、次の4層で考えると整理しやすくなります。
| 層 | 決めること | 失敗すると起きること | 先に読む記事 |
|---|---|---|---|
| 仕様層 | 目的、非目的、受入条件、変更理由 | AIが勝手にスコープを広げる | SDDハブ |
| 環境層 | repo構造、入口ファイル、subagents、hooks | セッションごとに判断がぶれる | AIが迷わないリポジトリ設計 |
| 権限層 | MCP allowlist、secret scanning、監査ログ | 触ってはいけない場所に触る | AIコーディング導入のセキュリティ設計 |
| 検証層 | テスト設計、CI品質ゲート、レビュー基準 | 実装量だけ増えて品質が追いつかない | AI生成コードのテスト戦略 |
この4層は順番が大事です。権限やテストを先に作っても、仕様層が曖昧なら何を守るべきかが決まりません。逆に、仕様だけ整えても、環境層と権限層が弱いとAIは推測で動きます。
flowchart TD
A[仕様層目的と受入条件] --> B[環境層repoと文脈の設計]
B --> C[権限層MCPとガードレール]
C --> D[検証層テストと品質ゲート]
D --> E[運用改善ログと学習ループ]
E --> A
1. 仕様層：チャットではなくファイルを正本にする
AIエージェント開発で最初に壊れるのは、だいたい仕様です。
「この機能をいい感じに直して」と頼むと、AIは不足している前提を推測で埋めます。推測が当たれば速い。外れると、速く間違えます。
だから最初に決めるべきなのは、ツールではなく SSoT（Single Source of Truth） です。
- 要件はどこに書くか
- 受入条件は誰が承認するか
- 設計変更の理由をどこに残すか
- 会話ログではなく、どのファイルを正本にするか
この考え方は なぜAIエージェントは仕様書を無視するのか と 会話は流れるがファイルは残る で詳しく扱っています。大事なのは、AIに「覚えていて」と頼むことではありません。AIが毎回読める場所に、判断材料を置くことです。
仕様層のチェックリスト
- 目的と非目的が1文で分かれる
- 受入条件が実行またはレビューで検証できる
- 実装前に設計方針が残る
- 完了後に検証ログが残る
- 仕様と実装の差分を説明できる
2. 環境層：AIが迷わないrepoにする
仕様があっても、repoの構造が読みにくいとAIは迷います。
人間なら「このへんのファイルを見れば分かる」で済むことも、AIにはかなり重い。入口ファイル、局所ルール、作業ログ、テストコマンド、禁止事項が散らばっていると、セッションごとに参照先が変わります。
環境層で決めるべきことは、次の4つです。
| 項目 | 役割 | 例 |
|---|---|---|
| 入口 | 全体方針を渡す | AGENTS.md、CLAUDE.md |
| 局所ルール | 領域ごとの作法を渡す | .agents/rules/、各ディレクトリのREADME |
| 分業 | 読む文脈を分ける | subagents、skills、reviewer |
| 強制 | 守るべき制約を機械化する | hooks、CI、lint、test |
この層は AIが迷わないリポジトリ設計 が中心です。Claude Code や Codex の使い方というより、AIが作業しやすい地図をrepoに埋め込む話です。
3. 権限層：できることを先に狭める
AIエージェントに「注意して」と言うだけでは、セキュリティ設計になりません。できることを先に狭める必要があります。
特に MCP や GitHub 連携を使う場合、AIは外部ツールを通じてファイル、Issue、PR、検索結果、ブラウザ、データベースに触れる可能性があります。ここで権限を雑に渡すと、prompt injection や secret leakage の事故半径が広がります。
権限層では、少なくとも次を決めます。
- どのツールを許可するか
- 書き込み可能な範囲はどこか
- secret scanning はどの段階で止めるか
- hooks や pre-push で何を検査するか
- 人間承認が必要な操作は何か
全体像は AIコーディング導入のセキュリティ設計 にあります。具体的な権限粒度は MCP権限設計の判断軸、流出対策は GitHub MCP Serverでsecret scanningを組み込む が使えます。
4. 検証層：速く作るほど、品質ゲートを先に作る
AI導入で一番起きやすい逆説は、「実装は速くなったのに、レビューと検証で詰まる」ことです。
これは AI生産性のパラドックス で扱っている通り、アウトプット量だけが増えても、価値の流れが太くなるとは限らないからです。
検証層では、次の3つを分けます。
| 検証対象 | 見るもの | 代表記事 |
|---|---|---|
| 意図 | 何を満たすべきか | 受入条件を先に書くTDD実践 |
| 振る舞い | 実装が期待通り動くか | AI生成コードのテスト戦略 |
| リスク | どの変更を強く見るか | リスクベースリリース運用 |
AI生成コードは「誰が書いたか」より「何を保証できるか」で見るほうが安定します。レビューで意図を推測するのではなく、受入条件・テスト・品質ゲートで意図を外に出します。
導入順序：最初の30日で決めること
AIエージェント開発をチームに入れるなら、最初の30日はこの順番で進めるのが現実的です。
| 期間 | 決めること | 成果物 |
|---|---|---|
| 1週目 | 対象業務と禁止業務 | AIに任せる作業リスト、任せない作業リスト |
| 2週目 | 仕様と承認ゲート | requirements、design、tasks、レビュー条件 |
| 3週目 | 権限と監査 | allowlist、secret scanning、hooks、ログ |
| 4週目 | テストと改善ループ | 品質ゲート、失敗分類、改善KPI |
ここで重要なのは、いきなり全自動化を狙わないことです。最初は「AIに任せる範囲を狭くし、成功パターンを観測する」ほうがいい。
自律性は、信頼が積み上がってから広げます。
外部に紹介するときの説明文
このページは、外部からリンクしてもらう入口として使う想定です。紹介文は、次のようにすると伝わりやすくなります。
AIエージェント開発を、ツール選定ではなく「仕様・権限・テスト・運用」の4層で整理した実践ガイド。Claude Code / Codex / MCP / SDD をチーム導入する前に決めるべき順序がまとまっています。
短く紹介するなら、次の一文で十分です。
AIコーディングをチーム運用に載せる前に読む、設計順序のチェックリスト。
関連記事の読み進め方
目的別に読むなら、次の順番がおすすめです。
- 仕様から整えたい: SDDハブ -> 受入条件を先に書くTDD実践
- repoをAI向けに整えたい: AIが迷わないリポジトリ設計 -> CLAUDE.md最適化の本質
- 権限と安全性を固めたい: AIコーディング導入のセキュリティ設計 -> MCP権限設計の判断軸
- 品質ゲートを作りたい: AI生成コードのテスト戦略 -> AI生成PRの品質ゲートを自動化する
- 組織運用まで広げたい: AIエージェント開発のデリバリー統治 -> AI開発KPIと学習ループ
まとめ
AIエージェント開発は、モデルやツールの比較だけでは安定しません。
安定させるには、仕様をファイルに置き、repoを読みやすくし、権限を狭め、テストと品質ゲートで検証する。この順番が必要です。
外部から被リンクを集めるページとしても、個別Tipsよりこの親ハブのほうが長く使えます。AIツールの名前は変わっても、仕様・権限・テスト・運用を分けて設計するという原則は残るからです。
