10万行のコードベースでAIエージェントを使用した実践的教訓

大規模AI支援開発のための6つの具体的テクニック

ある開発者が最近、chDB分析エンジンの上にpandas互換のAPIレイヤーを構築するためにAIエージェント（Claude Code + Cursor）を使用した経験を文書化しました。このプロジェクトでは、2つのシステム間で600以上のメソッドを整合させ、約2万ドル相当のトークンを使用しました。以下に、彼らが共有した具体的で実践的な教訓を紹介します。

主要な実装詳細

• CLAUDE.mdルールファイルを維持する： AIにはセッション間の記憶がないため、リポジトリにルールファイルをコミットしました。このファイルには、AIが繰り返し間違えるパターン、禁止したショートカット、確定したアーキテクチャ上の決定などが含まれています。これはチームコラボレーションのインターフェースとしても機能しました。ただし、このファイルが「500行のマニフェスト」になり、AIが無視し始めることを避けるよう注意が必要です。
• 出力だけでなく推論過程を観察する： 初期段階では、AIが何を実装するかよりも、どのように考えているかを読む方が価値があります。AIの論理があなたのものからずれているときは、自分の考えが間違っていたのか、それとも適切に伝えられなかったのかを自問してください。
• 定期的にゼロコンテキストエージェントを批評家として使用する： プロジェクトの記憶を持たない新しいエージェント（Claude Code CLIではなくclaude.ai/code）を使用して、批判的で合理的な外部者の視点から自分の作業を評価し始めました。重要なキーワードは2つ：critical（AIのデフォルトの迎合モードを上書き）とrational（雰囲気ではなく構造化された推論を要求）です。
• ターゲットシステムをテストオラクルとして使用する： 既存のAPIに一致させるのが目標だったため、実際のコード（GitHub/Kaggleノートブック）を見つけ、1行のインポートを入れ替えて、テストケースを作成する代わりに出力を比較しました。
• プロンプトよりもルール： AIがどのようにショートカットを取るかを観察し、明示的な禁止事項を記述しました。例えば：行の順序不一致でテストが失敗したとき、AIのお気に入りの対応はテストを通すために.sort_values()を追加することでした。これを明示的に禁止しました。真に一致できないケースはXFAILとしてマークし、決して黙ってスキップしません。
• マルチエージェントパイプラインでは会話履歴よりもファイルシステム： マルチエージェントワークフローは、ファイルシステムを共有コンテキスト層とするPythonスクリプトで調整します。各エージェントは作業をトラッキングディレクトリに書き込み、次のエージェントが必要なものを読み取ります。有効だった主要パターン：役割分離、構造化された決定（決定論的制御フローのためのJSON形式のAPPROVE/REJECT/ESCALATE）、失敗時の自動gitロールバック。

開発者は、AIは大規模作業（数百の関数の整合、数千のテストの生成、リグレッションの検出）に優れているが、判断（「これはバグか機能か？アーキテクチャは正しいか？」）は人間の責任であると指摘しています。