Skip to main content

AIエージェント向けの効果的なガードレール

本ドキュメントは、AIエージェントを利用した開発において、プロンプトへの依存を減らし、品質とルールを「仕組み」で強制するためのベストプラクティスをまとめた。

1. プロンプトではなく仕組み（ガードレール）で解決する​

AIへの「テストを書いて」「この規約を守って」というお願い（プロンプト）は、いずれ必ず無視されるタイミングが来る。人間への指示ではなく、機械的・決定論的な仕組みで品質を強制する必要がある。

  • リンター・フォーマッターの導入：
    • 本プロジェクトでは Biome を採用している。
    • 重要： リンターのエラーメッセージには、AIが自己修正できるように「どう直すべきか」が明確になるルール設定を心がける。
  • Gitフック (Pre-commit / Pre-push) の設定：
    • コミット前やプッシュ前に必ずリンター、フォーマッター、型チェック（tsc）が走るようにしている。具体的な設定は メンテナンスについて を参照すること。これにより、AIがルール違反のコードをコミットできない仕組みを作る。
  • 構造・アーキテクチャのテスト：
    • ドキュメントで「XはYに依存する」と説明するのではなく、依存関係やデータ構造をテストコードとして記述し、CIで検証させる。例として dependency-cruiser の導入や型チェックによる境界防御が挙げられる。未利用・不要なコードの発見には Knip を利用する。

2. エージェント可読性（Agent Readability）の最適化​

AIエージェントはリポジトリ内のテキストしか読めない。コンテキスト（文脈）をエージェントに正しく伝える工夫が必要である。

  • 暗黙知のコード化 (ADRの活用)：
  • 枯れた技術（Boring Technology）の選定：
    • APIが安定しており、LLMの事前学習データに多く含まれている技術を選定する。最新技術よりも、AIが確実に正解を出力できる技術を優先する。
  • 指示書（CLAUDE.md / .cursorrules）の軽量化：
    • システムプロンプトとして読み込まれる全体指示書は50行以下などの最小限に抑え、詳細なルールやツールの使い方への「ポインタ（ファイルパス）」のみを記述する。

3. 中央集権的な制約とローカルの実装の自由​

「何をすべきか（境界）」は厳格に守らせ、「どう実装するか（内部）」はAIの自律性に委ねる。

  • インターフェース・境界の厳密化：
    • 外部入力やモジュール間の境界では、Zod などを用いてデータの型や形状をパース・検証することを必須とし、テストやリンターで強制する。
  • 実装手法の自由：
    • データパースにZodを使うかなどの内部実装詳細はエージェントに任せ、結果だけを自動テストで担保する。

4. 特化したAIツールの活用とレビュー​

すでに導入されているツールを組み合わせることで、開発環境をさらに強固にする。

  • AI向けCLIツール・開発支援ツールの活用：
    • AIの能力拡張には Agent Skills やフロントエンドの構築支援プラグインを利用できる。
    • Difit を活用し、ローカルのGit差分をAIエージェント向けのプロンプトに変換してコードレビューにかけることで、レビュー漏れを防ぐ。
  • AIによるPRレビューと人間のレビュー：
    • CI上でPRエージェントを動かし、人間のレビュアーが見る前に軽微なバグを指摘・修正させるアプローチが有効である。人間が行うレビューの意図の伝え方については Pull Request 時のレビューについて を参照すること。

5. AIに実行させるべきではない破壊的コマンドの制限​

AIエージェントに強い権限を与えて運用する場合、取り返しのつかないインフラやデータベースの破壊操作を制限する強固なガードレールが必要である。

  • 破壊的コマンドのブロック設定：
    • AIエージェントには、以下のような取り返しのつかないコマンドや、予期せぬ副作用を生むコマンドの実行権限を与えないようにする。
      • インフラ・リソース削除: terraform destroy, terraform apply, aws * delete-*, kubectl delete
      • データベース破壊: DROP TABLE, TRUNCATE, データベースの初期化・削除コマンド
      • Git履歴/未保存データの破壊: git push -f（強制プッシュ）, git reset --hard
      • パッケージ・イメージの誤公開: npm publish, docker push
      • 強権的なファイル操作: rm -rf, chmod -R 777, chown
      • 外部スクリプトの任意実行: curl, wget（予期せぬ外部スクリプトの拾い食いを防ぐため）
    • Claude Codeなどのツールでは、プロジェクトの設定ファイル（.claude.json など）の権限設定で明示的にこれらの実行を拒否（deny）することが重要である
    • 設定例 (Claude Codeの場合)： 
      {
        "permissions": {
          "deny": [
            "Bash(terraform destroy *)",
            "Bash(terraform apply *)",
            "Bash(rm -rf *)",
            "Bash(git push -f *)",
            "Bash(npm publish *)"
          ]
        }
      }
  • インフラ側の多重防御：
    • TerraformのStateファイルをローカルへ配置せず、リモート（S3など）で管理する。
    • AWS RDS等の deletion_protection（削除保護）を有効化し、自動バックアップのリストアテストを定期実施する。
    • 大規模な破壊コマンドが実行された場合でも、インフラ側で防御し確実に復旧できる状態を保つことが不可欠である。

6. 今後追加推奨される発展的なガードレール​

開発がスケールしエージェントの処理量が増えた際に、さらに堅牢にするための追加の仕組みである。

  • コンポーネント分割を強制する仕組みの導入（長大ファイルの出力防止）：
    • AIはコンテキスト長が許す限り1つのファイルにコードを書き連ねる傾向がある。これを防ぐため、Biomeの noExcessiveCognitiveComplexity などの複雑度を制限するルールを有効にし、関数の肥大化を防ぐ手法が推奨される。さらに物理的な行数制限が必要な場合は、Gitフック（Husky等）にシンプルな行数チェックスクリプト（シェルスクリプトやNode.js）を組み込み、強制的にファイル分割を促す仕組みが有効である。
  • モックデータの自動生成・管理ルール：
    • AIにE2Eテストや結合テストを任せる場合、MSW (Mock Service Worker) などを整備する。外部環境に依存せず決定論的に動くテスト環境を作ることが重要である。
  • シークレットスキャンとセキュリティテストの自動化：
    • AIが誤ってAPIキーやパスワードをハードコードしてしまうリスクを防ぐ必要がある。git-secrets などのシークレットスキャンツールをGitフックに組み込み、セキュリティリスクを漏れなく弾く。
Last updated on