AIエージェントを活用して35万行のコードベースを一人で構築した実践的教訓

コンテキストとしてのエンジニアリング環境

開発者の52日間プロジェクト（600コミット、約96万5千行のコード処理量、35万6千行の本番コード）から明らかになったのは、エージェントの出力品質がモデルだけでなく、エンジニアリング環境に大きく依存することだ。コードベース自体がエージェントのコンテキストシステムとして機能し、別途のRAGやメモリファイルが不要となる。

明確なアーキテクチャ境界が不可欠であることが証明された。コードベースは厳格なDDDレイヤリングに従っている：データ構造のためのドメインレイヤー、ビジネスロジックのためのサービスレイヤー、HTTPフォーマット変換のためのハンドラーレイヤー。22のドメインモジュールは明確な境界を持ち、これがエージェントに変更箇所を指示する。

ディレクトリ構造は、クロススタックの命名整合性を持つドキュメントとして機能する。「Loop」機能の場合：データ構造はbackend/internal/domain/loop/、ロジックはbackend/internal/service/loop/、フロントエンドはweb/src/components/loops/。製品コンセプトからコードパスへの直接マッピングにより、エージェントがコードベース全体を探索する必要がなくなる。

技術的負債の増幅

技術的負債はAIエージェントによって指数関数的に拡散する。開発者が一時的な妥協（サービスレイヤーをバイパスしてDBに直接クエリしたり、ハードコードされたマジックナンバーを使用したり）を行うと、エージェントはこれらのパターンを合法的なアプローチとして体系的に再利用する。人間のエンジニアが悪いコードを地雷と認識するのに対し、エージェントは既存のパターンを有効な前例として扱う。

実用的な教訓：定期的なリファクタリングは、美学のためではなく、エンジニアリングシグナルの純度を維持するために不可欠となる。良いプラクティスが支配的であれば、エージェントは良いプラクティスを増幅する。ショートカットが支配的であれば、エージェントはショートカットを増幅する。これはエージェント協調開発における独特のメンテナンスコストを表している。

品質ゲートとしての強い型付け

Go + TypeScript + Protoを使用することで、コンパイル時エラー検出が可能となり、エージェントのエラーを実行時から開発時に移行できる。署名が一致しないエージェント生成関数はビルド失敗を引き起こす。TypeScriptはAPIフォーマットの不一致を即座に検出する。Proto生成コードは、バックエンドの同期なしにメッセージフォーマットが変更されるとコンパイルできない。これらのエラーは、弱い型付け言語では実行時に潜り込んでしまう。

4層フィードバックシステム

エージェントは効率的な反復のために4層のフィードバックを必要とする：

• コンパイル — ホットリロード、Goは1秒以内に再起動、TypeScriptの型エラーはリアルタイムでフラグ付け。構文エラーと型エラーを排除。
• 単体テスト — ドメイン層とサービス層をカバーする700以上のテスト。エージェントは5分以内に、特にマルチテナント分離のような境界条件で回帰を導入したかどうかを把握できる。
• E2Eテスト — 実際の機能パスのエンドツーエンド検証。単体テストが到達できない統合問題を捕捉。
• CIパイプライン — すべてのPRで完全なテストスイート、リンティング、型チェック、マルチプラットフォームビルドを実行。マージ前の最終安全網。

4層は遅延を増加させながらカバレッジを拡大する：第1層は単一行の変更を確認し、第4層はクロスモジュールリファクタリングを検証する。