※ この記事の日本語には、少し不自然な部分があるかもしれません。AIの言語サポートを利用しながら作成しています。
目次
- はじめに
- 権限マトリックス：いつエージェントに任せ、いつ人間がレビューするか
- リスクレベル別の実例
- AIエージェントに絶対に任せてはいけない6つのこと
- AGENTS.md：AIとの契約書
- Two-Agent Loop：一人が書き、もう一人がレビューする
- Final Report：エージェントに責任を負わせる
- まとめ
- 最後に
はじめに
あなたはAIエージェントにコードを書かせていますか？
素晴らしい！
しかし私は、エージェントが指示通りに正しく動いたせいで、1時間を無駄にしたことがあります。
実話です：私はエージェントに「リポジトリを掃除して、使っていないファイルを削除して」と指示しました。するとエージェントは「使っていない」を広義に解釈し、デプロイスクリプトがまだ参照している設定ディレクトリまで削除してしまいました。その設定ファイルは .gitignore に指定されていたため、Gitの管理下にはありませんでした。
結果：削除されたファイルを復元するのに1時間かかりました。
教訓：どのタスクをAIに任せるべきかを見極めること。これがAIエージェントと働く上で最も重要なスキルです。
以下、私の実践経験を詳しく共有します。
権限マトリックス：いつエージェントに任せ、いつ人間がレビューするか
| タスクの種類 | エージェントの自律度 | 人間のレビュー | 理由 / リスク |
|---|---|---|---|
| 小さな関数のリファクタリング | 高 | 不要または軽微 | 簡単にrevert可能。リスク低。 |
| ユニットテスト追加 | 高 | 通常不要 | CIが即座に検知する。 |
| フロントエンドバグ修正 (UI) | 中～高 | 目視確認必要 | ロジックバグは見えるが、UIの微妙な崩れは人間の目が必要。 |
| API動作変更 | 中 | 必要 | クライアントに影響。契約のレビュー必須。 |
| 依存関係追加 | 中 | 必要 | セキュリティホールやライセンス問題の可能性。 |
| データベースマイグレーション | 低 | 必須 | 誤ったマイグレーションはデータ損失やスキーマ破損を引き起こす。 |
| 認証・セキュリティロジック | 低 | 必須 | バグはユニットテストでは発見されず、インシデント報告で発覚する（数ヶ月後になることも）。 |
| Infrastructure / Cloud (IAM, k8s, terraform) | 非常に低 | 必須 | 権限ミスは静かにシステムを破壊する。トレースが非常に困難。 |
| 本番環境へのデプロイ | なし（手動のみ） | 必須＋手動確認 | エージェントは進行中のインシデントやメンテナンススケジュールを知らない。 |
シンプルなルール：元に戻せない操作には、必ず人間のチェックポイントを置くこと。
リスクレベル別の実例
| レベル | タスク例 | エージェントが誤った場合の影響 | 元に戻せるか？ |
|---|---|---|---|
| 高自律 | 変数名のリファクタリング | ビルドエラー、CIが即座に検知、5分で修正可能 | ✅ 簡単 |
| 中 | APIレスポンス形式の変更 | API呼び出し元がエラーになるが、本番デプロイ前なら問題ない | ⚠️ コミットrevert可能 |
| 低 | データベースカラムの削除 | データ損失。バックアップからの復旧に数時間～数日 | ❌ 非常に困難 |
| 自律なし | 深夜3時の本番デプロイ | 誰も気づかない、顧客に影響、オンコール担当者不在 | ❌ 非常に困難 |
AIエージェントに絶対に任せてはいけない6つのこと
1. 破壊的なファイル操作
-
rm -rf,git clean -fd,git reset --hard - エージェントは「clean up」という言葉を見ると、リファクタリングの最中に
git clean -fdを実行しかねません。未コミットの作業が全て消えます。
2. データベースの書き込み・削除
-
WHERE句のないDELETE、DROP TABLE、TRUNCATE、本番データに触れるマイグレーション -
WHERE句のタイポ一つでテーブル全体が消えます。エージェントは確認しません。
3. インフラストラクチャ（クラウド）
-
terraform apply,kubectl delete,aws iam * - 権限変更は特に危険です。何かが壊れるまで静かに進行します。
4. 本番環境へのデプロイ
- コードがエージェントによって書かれても、デプロイの決定はあなたが行うべきです。
- エージェントは「進行中のインシデントがあるか」「メンテナンス予定があるか」を知りません。
5. 認証・セキュリティロジック
- 認証フロー、認可ルール、トークン処理、セッション管理
- この種のバグはユニットテストでは見つかりません。インシデントレポートで発覚し、時には数ヶ月後になります。
6. Secrets、.envファイル、APIキー
- エージェントにこれらのファイルの読み取りや書き込みを許可してはいけません。
AGENTS.md：AIとの契約書
AGENTS.md ファイルをリポジトリのルートに配置します。このファイルはエージェントに対して「プロジェクトの目的」「実行方法」「触れてはいけないもの」を伝えます。
私が使っているテンプレート
# AGENTS.md
## Project
[プロジェクトの簡単な説明と技術スタック]
## Setup
```bash
npm install # または pip install -r requirements.txt
npm run dev
npm test
npm run lint
Coding rules
- 最小限の変更にとどめる。関係のないコードをリファクタリングしない。
- 動作を変更した場合は、テストを追加または更新する。
- タスクのスコープ外のファイルに触れない。
- 1コミット = 1つの関心事。
Safety rules
blocked_commands.md に記載されたコマンドを実行する前に必ず確認を求める。
安全かどうかわからない場合は → 停止して確認する。
Definition of done
- テストが通る
- 差分が一文で説明できる
- 最終レポートがある（下記参照）
Final report format
各タスク終了後、エージェントは以下を提供すること：
- 変更の概要
- 変更したファイル
- 実行したテストと結果
- リスクまたは前提条件
- 完了しなかった事項
### blocked_commands.md（実行前に承認が必要）
```markdown
# blocked_commands.md
## 破壊的なファイル操作
- rm -rf
- git clean -fd
- git reset --hard
## Git操作
- git push --force
- git push --force-with-lease
## データベース操作
- DROP TABLE
- TRUNCATE TABLE
- WHERE句のないDELETE
- 本番スキーマを変更するマイグレーション
## Cloud / Infrastructure
- terraform apply
- kubectl delete
- aws iam *
- gcloud iam *
## Secrets
- .envファイルを読み書きするコマンド
- APIキーや認証情報に触れるコマンド
Two-Agent Loop：一人が書き、もう一人がレビューする
中程度以上の複雑さを持つタスクでは、1つのエージェントではなく2つを使います。
エージェント1 – Implementer（コードを書く）
プロンプト:
あなたはシニアエンジニアです。タスク: [タスクの説明]
Context: [AGENTS.mdへのリンク]
ルール:
- 最小限の変更にとどめる。
- 関係のないコードをリファクタリングしない。
- 動作を変更した場合はテストを追加する。
- 最後に最終レポートを提供する（概要、変更ファイル、テスト、リスク、未完了事項）。
エージェント2 – Reviewer（レビューする）
プロンプト:
あなたはコードレビュアーです。実装への愛着はありません。
このdiffをレビューしてください: [diffを貼り付け]
チェック項目:
- バグとエッジケース
- 不足しているテスト
- セキュリティ問題
- 意図しない動作変更
- 定義されたスコープ外のもの
出力:
- Critical issues（必須修正）
- Minor issues（任意）
- 人間にフラグを立てるべきもの
コードを書き換えないでください。フラグを立てるだけで、修正はしません。
なぜ効果的なのか？
レビューアエージェントにはコードへの「自我」がありません。実装者が見逃したバグやエッジケースを見つけ出します。これはまさに自動化されたコードレビューです。
Final Report：エージェントに責任を負わせる
各エージェントタスクの後に、最終レポートを必須とします：
- 変更の概要
- 変更したファイル
- 実行したテストと結果
- リスク / 前提条件
- 完了しなかった事項
エージェントが明確に要約できない場合 → タスクがきれいでない証拠です。
また、これらのレポートは蓄積されて自動的なドキュメントになります。1週間後にバグが発生したとき、何が変更され、なぜ変更されたかを正確にトレースできます。
まとめ
AIエージェントは確かにあなたの生産性を向上させます。しかし、最も多くを活用できている人は、以下の「地味な作業」をきちんと行っている人です：
-
AGENTS.mdを書く - 権限レベルを設計する
-
blocked_commands.mdを構築する - Two-Agent Loopを設定する
エージェントは明確な指示があるときに最もよく機能します。その部分はあなたの責任です。
最後に
ここまでお読みいただき、誠にありがとうございます。
もし**「システム開発を依頼したい」「技術的な相談をしたい」「AIを活用した課題解決のアイデアがある」** といったお悩みがございましたら、ぜひ私たちTOMOSIA VIETNAMにご相談ください。
私たちの主なサービス
- 💻 ソフトウェア受託開発（Web・アプリ・システム）
- 🤖 AIソリューション（チャットボット、画像処理、LLM応用）
- 📱 モバイルアプリ開発（iOS / Android）
- 🔌 Fintech / IoT開発
- 🔧 ブリッジSE（BrSE）支援（日本語でのコミュニケーションをスムーズに）
私たちの強み
- ISO/IEC 27001（情報セキュリティ）認証取得済み – 安心して任せていただけます
- 日本語対応チーム – 日本の文化・ビジネス習慣を理解したメンバーが直接対応
- 「Win-Win, Happy Together」の文化 – 長期的なパートナーシップを大切にします
🔗 公式サイト: tomosia.com
まずはお気軽に、一言ご連絡ください。私たちと一緒に、「ベトナムの知恵」で世界に挑戦しませんか？