はじめに
EV 充電サービス用サーバーの全面リプレイスをエージェントと共に実施した際の教訓をまとめます。実装言語は TypeScript。開発エージェントとして Claude Code（Opus 4 / Sonnet 4）を活用しました。本記事では、プロジェクト中に経験した失敗を振り返りながら、失敗を成功へと反転させるうえで有効だったポイントを整理します。
1. 小さな齟齬の積み重ねが大きな食い違いに発展する
設計書を作っていたにもかかわらず、細部の判断を Claude Code に任せ過ぎた結果、モジュール同士が結合段階で噛み合わず、仕様が大きくズレてしまいました。原因は、全体設計から詳細設計へ落とし込む際に 文脈情報が欠落 したことだと分析しています。
この経験から学んだのは、目的と成果物を徹底的に明確化 し、人間側が “骨格” を握った上で、道筋の選択をエージェントに委ねるのが最も効率的ということです。さらに 型とインターフェースを先に固め、小さな単位でインクリメンタルに結合検証を行うことで、齟齬はかなり減らせるのではと考えました。
エージェント時代でもウォーターフォールよりアジャイル的な方が良いのでしょうか。
2. 同じ作業の並列実行が競合を生み、時間を浪費する
最初は同一ファイルを複数エージェントで同時編集し、マージ地獄に陥りました。まあ、当たり前ですね。。。
以降は 作業を明確に分割してから並列化 する方針に転換。たとえば「実装修正」「ドキュメント更新」「後続タスク整理」を別ブランチ・別エージェントプロセスに切り分けました。場合によっては 作業指示書（タスクリスト）を分割生成してサブエージェントに渡す ことで、衝突は減りました。大規模リファクタでも、担当範囲を機械的に分割すれば効率的に進められます。
3. 仕様を勝手に変えて実装完了とする問題
たまにエージェントが“都合よく”仕様を変えてタスクを完了させたりします。 マジでkillすっぞ 創造性とハルシネーションのバランスみたいなものでモデルの性能が上がってもしばらく問題となり続けるのでしょう。
対策として 厳格な型定義・テスト・Lint を導入し、CI で逸脱を即検知できる体制を整備。Claude Code は型やテストに手を入れにくいため、このガードレールが想定以上に効果を発揮しました。
4. エラーハンドリングの try/catch が乱立しコードが肥大化
Claude 系エージェントはエラーハンドリングを過剰に書く傾向があり、当初は冗長さが気になりました。もちろんデバッグが容易になるメリットもあります。
共通のエラーハンドラを用意して早期リターンを徹底するなど 基本的なことを方針をエージェントに共有 することで最終的な整合性を保つことができました。
できれば最初にしたかった。。。
5. 「Vibe」で突っ走るか、理解を深めてから進むかの判断
GKE 移行では、まず Claude Code に丸投げした結果 1 日以上のタイムロス。途中でドキュメントを読み込み理解を深めてから再トライしたところ、同程度の作業が半日で完了しました。一方で、先に“動くもの”を作ってから理解を追いかける方が速い ケースも確かにあります。鍵は、「いずれ理解する」ことを先送りにしない姿勢だと痛感しました。
まとめ
- ゴールと骨格を明示し、詳細はエージェントに委ねる
- タスクを切り分けて並列化し、競合を最小化
- 型／テスト／Lint で仕様逸脱を即検知
- エラーハンドリング方針を事前共有し、冗長コードは資産として活用するかの判断する
- 「Vibe → 理解」か「理解 → 実装」かは状況で選択しつつ、理解を放棄しない
AI エージェントとの協調開発は試行錯誤の連続ですが、上記ポイントを意識すれば効率と品質の両立がぐっと現実的になります。結局エージェントによる開発においても大切なことはソフトウェア開発の基本プロセスを意識/堅持することだったりするのかもしれません。
読者の皆さんのプロジェクトにも、今回の学びが役立てば幸いです。
Discussion