エージェンティック・エンジニアリング — 実装チェックリスト
目次
1. ルールファイルのセットアップ
- リポジトリルートに
CLAUDE.md/AGENTS.mdを作成する。まず10行から始める。 - 以下の4つをカバーする：
- スタックとバージョン
- 規約（フォルダ構成、命名規則、実際に使用するパターン）
- エージェントが絶対に破ってはならないハードルール（禁止パッケージ、シークレット管理、レイヤリング）
- コード生成の前後に従うべきワークフロー
- エージェントが望ましくない動作をするたびに、新しいルールを追加する。
- エージェントが呼び出せるツールと、各ツールの使用タイミングを列挙する（API、スクリプト、DBスキーマ）。
- アーキテクチャの決定は自分で行い、エージェントにはその実装を担当させる（選択はさせない）。
2. コンテキストのエンジニアリング
- 静的（常に読み込む）と動的（必要時に読み込む）を決定する：
- 静的：ルールファイル、システム指示、グローバルメモリ
- 動的：スキル、ツール結果、取得したドキュメント、直近の会話履歴
- 静的コンテキストは短く、シグナルが高いものに保つ。エージェントが毎回必要としないものはすべて削除する。
- 繰り返し使える知識を、タスクが一致したときだけ読み込まれるスキルに移す。
- リポジトリ全体をプロンプトに貼り付けない。関連するものだけを取得する。
3. 検証の構築
- フィーチャーを生成させる前にテストを書く。テストが仕様書となる。
- 非決定論的な部分についてエバリュエーションを書く：
- エージェントは合理的なパスを取ったか？
- 適切なツールを選んだか？
- アウトプットは品質基準を満たしているか？
- 結果（コンパイルが通る、テストが通る）と軌跡（どのように達成したか）の両方を確認する。
- フィードバックループを設定する：
- ベンチマークスイートに対して実行する
- 根本原因別に失敗をクラスタリングする
- 原因となったプロンプトまたはツールを修正する
- リグレッションスイートを再実行する
- 新しい障害発生のために本番環境を監視する
4. 作業の実行
- タスクごとにモードを選ぶ：
- コンダクター（リアルタイム、IDE内）：複雑なロジック、デバッグ、不慣れなコード
- オーケストレーター（非同期、委任してレビュー）：バグ修正、マイグレーション、テスト生成
- タスクごとにエージェントの配置場所を選ぶ：
- エディタエージェント — フロー内での編集と提案
- ターミナルエージェント — 複数ファイルの作業、実行して対応
- バックグラウンドエージェント — 任せて離れられるパラグラフ単位のタスク
- コード生成は承認済みツールのみを使用し、サンドボックス内で実行する。
- 残り20%は自分で対応する：エッジケース、エラー処理、統合ポイント、ビジネスロジック。「正しく見える」コードこそバグが潜む場所である。
5. レビューとリリース
- 人間がレビューする前に、エージェントを一次レビュワーとして活用する（バグ、スタイル、セキュリティ、パフォーマンス）。
- リリースするすべての行をレビューする：
- 巧妙なコードには懐疑的になる
- インポートされたパッケージが実在することを確認する
- 現実的な障害に対するエラー処理を確認する
- コミット・編集のポイントにフックを追加する（例：ハードコードされたシークレットのコミットをブロックする）。
- オブザーバビリティを有効にする：トレース、エバリュエーション結果、トークン・レイテンシ・コスト、ドリフト。
- これまで避けてきたレガシー作業をエージェントに任せる：リファクタリング、マイグレーション、廃止APIの更新。
6. コストの管理
- 速度だけでなく、総所有コストを計測する。
- 一次通過成功率を高めるためにルールファイルを厳密にし、リトライループを避ける。
- タスク別にモデルをルーティングする：
- アーキテクチャと難しい実装にはフロンティアモデル
- テスト生成、レビュー、CI監視には安価なモデル
- 動的コンテキストとスキルを使用して、必要なトークンだけを支払う。
7. 本番エージェントのリリース
- 何を構築しているかを決定する：
- スクリプト — エージェントがエンドポイント
- 実ユーザー向けプロダクト — エージェントには基盤が必要
- プロダクトの場合は追 加する：永続メモリ、スコープされた権限、CIでのエバリュエーションカバレッジ、フルラントレーシング。
- スキルバンドルを使用して、既存のコーディングエージェントがビルド→評価→デプロイ→観測を処理できるようにする。
- マルチエージェント構成では、共有状態でコーディネート、ツールにはMCP、委任にはA2Aを使用する。
8. チームの標準にする
- ルールファイル、プロンプト、エバリュエーションスイート、スキルをバージョン管理する。PRでレビューし、オーナーを割り当てる。
- 動作するデモではなく、明確なルーブリックを持つ合格したエバリュエーションスイートをリリースのゲートにする。
- 生成コードがどのように失敗するかをレビュワーに訓練する。
- プロトタイプと本番の境界を明示する（どのリポジトリ、ブランチ、環境か）。
- ハーネスを一度構築し、継続的に改善し続ける。
- 仕様、評価、アーキテクチャの判断力を持つ人材を採用・昇進させる。
参考資料
The New SDLC With Vibe Coding（Google）を基に： https://www.kaggle.com/whitepaper-the-new-SDLC-with-vibe-coding