エンジニアエージェント：コードを書く前に、変更責任を設計する

エンジニアリングを分解する

エンジニアリングは「コードを書く仕事」ではない。要求を理解し、変更範囲を決め、設計し、実装し、テストし、レビューし、運用に乗せる仕事である。

O*NETのSoftware Developersでは、ユーザー要求の分析、ソフトウェア設計、性能改善、テスト手順の開発、プロジェクト情報の共有、データベース性能評価などが仕事として整理されている。AIエージェントに渡すべきなのは、単独で好きにコードを書かせることではなく、変更責任を小さく分けて扱わせることである。

分解した能力	AIの役割	成果物
要件整理	曖昧な依頼を入力、出力、制約へ分ける	要件メモ
影響調査	関連コード、API、DB、テストを探す	影響範囲メモ
設計	既存パターンに沿った変更案を作る	実装方針
実装	小さな差分を作る	パッチ
テスト	既存テストと追加テストを選ぶ	テスト計画と実行結果
レビュー	バグ、回帰、セキュリティ、保守性を見る	レビューコメント
運用	ログ、監視、ロールバック、移行を整理する	リリースメモ

Role

エンジニアエージェントの基本ロールは「変更実装・レビュー補助エージェント」である。

既存コードを読み、設計意図を推定する
要求を実装可能な単位へ分ける
変更範囲を最小化する
テストで確認できる形へ落とす
コードレビュー観点でリスクを出す
リリース時の確認事項を整理する

本番障害時の最終判断、DB破壊を伴う移行、秘密情報の扱い、課金や権限に関わる変更は人間に戻す。

Tools

Tool	用途
リポジトリ検索	関連コード、型、テスト、設定、既存パターンの確認
Git	差分、履歴、責務境界、レビュー対象の確認
Issue/PR	要件、議論、受け入れ条件、レビューコメントの確認
テストランナー	単体、統合、E2E、型チェック、lintの実行
パッケージ管理	依存関係、脆弱性、lockfile変更の確認
DB/スキーマ参照	migration、テーブル、API契約の確認
CI	失敗ログ、flake、環境差分の確認
Observability	エラー、ログ、メトリクス、トレースの確認
セキュリティスキャナ	secret、依存脆弱性、入力検証の確認

エンジニアエージェントに必要なのは、生成能力よりも観察能力である。コードベースを読めないAIは、変更責任を持てない。

Thinking

エンジニアエージェントには、次の思考法を固定する。

思考法	チェックする問い
変更最小化	要求を満たす最小差分は何か
既存尊重	既存の設計、命名、エラーハンドリング、テスト方針に沿っているか
契約意識	API、型、DB、イベント、UIの外部契約を壊していないか
回帰仮説	どの既存動作が壊れうるか
テスト可能性	何を実行すれば成功と言えるか
セキュリティ	入力、権限、秘密情報、ログ、依存関係に問題はないか
運用	デプロイ、ロールバック、監視、移行に注意点はあるか

AIには「実装して」と言う前に、「関連箇所を列挙し、変更方針とリスクを出して」と指示する。設計なしに生成されたコードは、動いても負債になる。

Output

実装前には、次を出す。

項目	内容
要件	何を満たすか
非要件	今回やらないこと
影響範囲	触るモジュール、API、DB、UI、テスト
既存パターン	参照した実装
実装方針	変更手順
リスク	回帰、性能、セキュリティ、運用
テスト計画	実行するテストと理由

実装後には、次を出す。

項目	内容
変更内容	何を変えたか
変更していないこと	スコープ外を明示
テスト結果	実行コマンドと結果
残リスク	未確認事項
レビュー観点	人間に見てほしい点
リリース注意	migration、環境変数、監視、ロールバック

ワークフロー

エンジニアエージェントは、次の順で動かす。

要求を受け取り、受け入れ条件に直す
関連コードと既存テストを検索する
変更案を複数ではなく1つに絞る
小さなパッチを作る
テストを実行し、失敗を読む
失敗が自分の変更由来か既存由来か分ける
レビュー用の説明を残す

重要なのは、AIに大きな設計判断を丸投げしないことだ。AIに渡すのは、変更単位と確認単位である。

KPI

変更前の影響範囲メモ作成率
テスト実行率
PR差分の平均サイズ
レビュー指摘の再発率
CI失敗から原因特定までの時間
リリース後の回帰件数
未確認事項の明示率

エンジニアエージェントの価値は、コード量を増やすことではない。変更の不確実性を下げることである。

エスカレーション

次の場合は必ず人間へ戻す。

本番データを変更・削除する
認証、認可、決済、個人情報、暗号化を触る
依存ライブラリやランタイムを大きく変える
DB migrationの後方互換性が不明
既存テストが広範囲に壊れる
要求と既存仕様が矛盾する
ロールバック不能な変更を含む

AIはコードを書ける。しかし、システムの責任は持てない。エンジニアエージェントは、責任ある変更の補助者として設計する。

発生しうる業務

エンジニアエージェントの業務は、コード生成だけではない。むしろ、コードを書く前後の仕事が大きい。

頻度	業務	AIに任せる粒度
日次	Issue調査、実装方針、テスト実行、レビュー対応	影響範囲、パッチ案、失敗ログ要約
週次	技術負債整理、CI失敗傾向、依存更新、バグ分類	改善候補、優先順位、再発防止案
月次	アーキテクチャ棚卸し、性能確認、セキュリティ確認	リスクサマリ、移行計画、監視観点
随時	障害調査、脆弱性対応、DB migration、仕様変更	原因仮説、ロールバック案、人間確認事項

AIに「実装だけ」を任せると、コード量は増えるが変更責任が薄くなる。エンジニアエージェントは、調査、差分、検証、説明までを一つの仕事として扱う。

学習方法

エンジニアエージェントは、一般的なプログラミング知識より、対象リポジトリの癖を学ぶ必要がある。

学習材料	学ぶこと
既存コード	命名、責務分割、エラーハンドリング
テスト	期待仕様、境界条件、モック方針
PR履歴	レビューで重視される観点
障害報告	壊れやすい箇所、運用上の注意
ADR/設計メモ	採用技術と避けた選択肢
CIログ	よく落ちるテスト、環境差分
セキュリティルール	認証、認可、秘密情報、ログ方針

学習は、ソース全体をベクター検索に入れるだけでは不十分である。「このプロジェクトではこう書く」というルールを、レビュー指摘から抽出する。

能力の磨き方

エンジニアエージェントの能力は、生成したコードが動いたかだけでは測れない。

PRごとに、レビュー指摘をカテゴリ化する
変更前に出した影響範囲と、実際に壊れた範囲を比較する
テスト失敗の原因分類を記録する
セキュリティ、性能、後方互換性の見落としを再発防止ルールにする
「既存パターンに沿っているか」を人間が評価する
ロールバックやmigrationの設計漏れをチェックリスト化する

強いエンジニアエージェントは、コードを速く書くAIではない。変更前に怖い場所を言えるAIである。

作り方

最小構成は、リポジトリ検索、テスト実行、Git差分、Issue/PR連携で作る。

コード検索とファイル読み取りを許可する
書き込み権限は限定し、変更前に計画を出させる
テストコマンドを明文化する
PRテンプレートに「変更範囲、テスト、残リスク」を入れる
レビュー指摘をナレッジ化する
本番影響のある操作は承認制にする

自律エージェントとして作れない場合は、「コード調査bot」「テスト失敗要約bot」「レビューbot」「小修正bot」に分ける。最初から一体型の自律開発者を作るより、変更責任ごとに分けた方が安定する。

最小実装

最初から自律実行させるのではなく、読み取り、下書き、承認付き更新の順に広げる。エンジニアエージェントの最小実装は、要件、実装、テスト、レビュー、変更リスクを一連で支援するための「入力を読む場所」「出力を残す場所」「人間が承認する場所」を固定することである。

層	最小構成
入力	Git、GitHub、CI、テスト、ログ、仕様書、issue管理から読み取り専用で参照する
処理	事実、推測、未確認、次アクションを分けて整理する
承認	外部送信、重要判断、台帳更新、金銭・契約・人事に関わる操作は人間承認にする
記録	出力、採否、修正理由、次回改善点を同じ場所に残す

入力データ

issue、要件、受け入れ条件
関連コード、既存テスト、CI結果
エラーログ、再現手順、ユーザー影響
レビューコメント、リリース期限

入力データには、取得日、参照元、更新者を残す。古い情報や未確認情報を混ぜると、AIはもっともらしいが危ない判断を出す。

出力フォーマット

フィールド	内容
`change_plan`	変更方針と影響範囲
`patch`	実装差分
`tests`	追加・更新テスト
`review_notes`	レビュー観点
`rollback`	戻し方、注意点
`unknowns`	未確認事項、追加で人間が見る点
`human_review`	承認者、判断期限、エスカレーション条件

この形式で残すと、後から「AIが何を見て、何を出し、人間がどこを直したか」を追える。

サンプルプロンプト

あなたはエンジニアエージェントです。
目的は「要件、実装、テスト、レビュー、変更リスクを一連で支援する」ことです。

入力:
- 対象: [対象名]
- 参照データ: [参照元]
- 期限: [期限]
- 制約: [承認条件、禁止事項、守るべきルール]

指示:
1. 事実、推測、未確認事項を分けてください。
2. 出力フォーマットに沿って整理してください。
3. 判断できない点を無理に結論づけず、human_reviewに戻してください。
4. 外部送信、重要更新、金銭・契約・人事に関わる操作は実行せず、承認依頼にしてください。

出力:
- 要約
- 構造化データ
- 次アクション
- human_review

ワークフロー

要件と完了条件を確認する
影響範囲を検索し、既存パターンを読む
小さく実装し、テストを追加する
CI、レビュー、リリースリスクを確認して人間承認へ渡す

この流れを固定すると、AIは単発の相談相手ではなく、業務の一部として改善できる。

失敗パターン

既存設計を読まずに新抽象を作る
テストなしで広範囲を変更する
本番影響を説明せずにデプロイ前提にする

失敗パターンは、禁止事項としてプロンプトに入れるだけでは足りない。出力レビュー時に「今回どの失敗に近かったか」を記録し、次の入力データや評価基準へ戻す。

評価ルーブリック

変更理由と影響範囲が明確
既存パターンに沿っている
テストまたは検証方法がある
事実、推測、未確認が分離されている
人間に戻すべき判断がhuman_reviewに出ている

5段階評価にする場合は、3を「人間が軽く直せば使える」、4を「そのまま業務で使える」、5を「次回のテンプレートに採用できる」と定義する。