AI エージェントを「interface 実装者」として扱う

― schema-first で副作用を制御する設計パターン

Claude Code のような AI コーディングエージェントが実務に入ってきました。
賢くて速い。でも、こんな不安もあります。

• ルールが未定義でも、それっぽく動いてしまう
• 人間は守っている暗黙のルールを、AI だけ逸脱する
• 「やっていいこと」の境界が曖昧なまま進む

これは AI が悪いわけではありません。

「何をしていいか」の仕様が明示されていない

のが原因です。

この記事では、
「AI エージェントを interface 実装者として扱う」
という設計パターンを紹介します。

---

問題：AI エージェントは「自由すぎる」

AI エージェントは基本的に善意で動きます。

• 良さそうな判断をする
• それっぽい出力を作る
• でも「ルールが未定義」でも止まらない

人間のチームメンバーなら「これ、勝手にやっていいんでしたっけ？」と聞いてくれます。
AI はそうとは限りません。

---

発想：AI を「interface 実装者」として扱う

ここで発想を変えます。

プログラミングでは当たり前のルール

• interface / schema が定義されていない
• → 実装してはいけない
• → コンパイル・実行に進めない

これを AI にも適用する

• 操作の schema が定義されていない
• → その操作を実行してはいけない
• → AI エージェントはその操作に進まない

つまり：

schema-first / interface-first で
AI エージェントの「副作用」を制御する

これは新しい理論ではありません。既存の設計思想と同じ構造です。

設計思想	原則
Design by Contract	前提条件が満たされなければ実行しない
OpenAPI / Schema-first	schema が先、実装は後
Terraform / CDK	宣言がなければ apply できない

それを AI エージェントの運用 に持ち込んだだけです。

---

重要な前提：これは物理的な強制ではない

• OS レベルで操作を物理的に止める仕組みではありません
• あくまで AI エージェント自身の行動ルール（ガードレール） です

LLM は instruction following（指示追従）の能力が高く、明確なルールを与えれば高い確率で従います。
「schema が無ければ実行しない」という行動パターンを、この性質で定着させます。

---

具体例：commit 操作の制御

ここからは具体例として、Claude Code の commit 行動を制御するケースを見ていきます。

よくある問題

• コミットメッセージの粒度や形式が崩れる
• ルール未定義のまま、それっぽい commit を作ってしまう

実装

1. Claude Code のルール（~/.claude/rules/commit-guard.md）

# Commit Guard Rule

## 前提（MUST）

commit を行う前に、必ず以下のファイルの存在を確認する：

- `docs/rules/commit.schema.md`
- `docs/rules/commit.md`

## ガード（MUST）

上記のどちらかが存在しない場合、**いかなる理由でも `git commit` を実行してはならない**。

その場合は以下のいずれかを行う：

- schema / ルール文書を先に作成する
- ユーザーに「schema が無いため commit できない」と通知して終了

## 禁止（MUST NOT）

schema 確認なしに `git commit` を直接実行してはならない。

2. Commit Schema（<project>/docs/rules/commit.schema.md）

# Commit Message Schema

## Format

<type>(<scope>): <subject>

<body>

## Type（必須）

- feat: 新機能
- fix: バグ修正
- docs: ドキュメントのみ
- style: フォーマット（コード動作に影響なし）
- refactor: リファクタリング
- test: テスト追加・修正
- chore: ビルド・補助ツール

## Subject（必須）

- 50文字以内
- 末尾にピリオドを付けない
- 命令形で書く（Add, Fix, Update...）

3. 運用ルール（<project>/docs/rules/commit.md）

# Commit 運用ルール

## 粒度

- 1 commit = 1 論理的変更
- 動作する状態でのみ commit

## レビュー観点

- commit 単位で差分が理解できるか
- revert しやすいか

補足：ルールの強度について

Claude Code は複数のルールを読み込むため、ルール間で競合が起きると ガードが他ルールに負ける可能性があります。

例えば、別ルールに「ユーザーの指示を優先」とあれば、「schema無視してcommit」という指示が通ってしまうかもしれません。

より強い制約を設けるには：

• ルール内で「ユーザー指示より優先」と明示する
• CLAUDE.md にも同じ制約を書いて冗長化する
• 後段の CI / hook で検証する（後述）

完全な強制は難しいですが、複数レイヤーで同じルールを宣言することで実効性を高められます。

私の環境では、ルールに 優先度値（priority） の概念を導入しています。

---

応用：他の副作用にも同じパターンが使える

commit は一例です。同じ考え方は他の「副作用」にも適用できます。

副作用	schema の例
ファイル削除	deletion-policy.md（削除可能なパス、確認フロー）
外部 API 呼び出し	api-allowlist.md（許可するエンドポイント一覧）
DB マイグレーション	migration.schema.md（命名規則、ロールバック要件）
デプロイ	deploy-policy.md（環境ごとの承認フロー）

共通するのは：

schema / policy が無ければ、その操作に進まない

というガードレールの構造です。

---

この方法でできること / できないこと

できること

• AI エージェントの副作用を安定させる
• ルール未定義状態での「それっぽい操作」を防ぐ
• 人間の自由を奪わず、AI だけを制御する

できないこと

• 物理的な完全強制
• 悪意ある操作の防止

必要なら、後段で CI や hook を組み合わせてください。

---

まとめ

AI エージェントは、

• 賢い
• 速い
• でも「仕様が無くても動いてしまう」

だからこそ、

AI を「自由な職人」ではなく
「interface を実装する存在」として扱う

という設計が効きます。

これはツール依存のテクニックではなく、
ソフトウェア設計の原則を AI 運用に拡張しただけ。

AI エージェントが増えるほど、こういう「設計で縛る」アプローチは重要になってくると思っています。