How I Made AI Stop Hallucinating on Our Codebase
AIコーディングツールは、実際のプロダクションプロジェクトでは失敗します。新しいコードにはうまく機能しますが、履歴のある古いコードになると崩壊してしまいます。
私たちのフィンテックプロジェクトには3年間の履歴があります。2つのReactフロントエンド、管理パネル、そしてFastAPIバックエンドで構成されています。データベースは多くのテーブルと複雑な結合（join）を持つ、非常に複雑なものです。
開発スピードを上げるためにAIを使おうとしましたが、失敗しました。
AIに「contacts（連絡先）テーブルを作成して」と頼んだところ、名前とメールアドレス用の新しいカラムを作成してしまいました。すでにusersテーブルにそれらが存在していることに気づかなかったのです。外部キーを使用する代わりに、データを重複させてしまいました。
AIが愚かだったわけではありません。コンテキスト（文脈）がなかったのです。不完全な情報に基づいて判断を下してしまったのです。
私は「どうすればより良いコードが得られるか」と問うのをやめました。代わりに「AIが適切な判断を下すためには、どのようなコンテキストが必要か」を問い始めました。
私たちは構造化されたワークフローを構築しました。AIの性能は、提供するコンテキストの質に依存します。私たちはそのコンテキストを明示的にしました。
私たちのセットアップは以下の通りです：
- ADRディレクトリ: Architecture Decision Records（アーキテクチャ決定記録）用のフォルダを作成しました。これらのファイルは、なぜ特定の選択を行ったのかを説明するものです。あるファイルでは、新しいテーブルを作成する前に既存のテーブルを確認するようAIに指示しています。また、ユーザーデータの重複を禁止しています。
- context.md: このファイルでは、プロジェクト独自の用語を説明しています。独自の言葉が互いにどのように関連しているかをAIに伝えます。
- plot.md: プロジェクトのハイレベルなマップと、各要素がどのように接続されているかを提供します。
- 必須テスト: すべての新しいAPIルートにはテストケースが必要です。
これですべてが変わりました。かつて、AIが共有ユーティリティ関数を変更したことがありました。その変更により、システムの他の8箇所が壊れてしまいました。しかし、テストスイートが即座にそれを検知しました。AIは失敗を認識し、古い要件と新しい要件の両方に対応するバージョンを作成することで、自らのミスを修正しました。
テストがなければ、そのバグはプロダクション環境に到達していたでしょう。
AIを新しい開発者のように扱ってください。新しい採用者がコードベースを知らないことを責めたりはしませんよね。ドキュメントを提供し、オンボーディングを行います。私たちはAIに対しても同じことをしました。
私たちの構造:
- docs/context.md: プロジェクトの用語と関連性。
- docs/plot.md: コードベースのハイレベルマップ。
- docs/adr/: テーブル作成やAPI構造などの具体的なルール。
チームのための3つのルール:
- ADRは具体的に。曖昧なアドバイスではなく、明確な指示を使用してください。
- ドキュメントに権威を持たせる。これらのルールが最優先であることをAIに伝えてください。
- ミスをルールに変える。AIが失敗するたびに、新しいADRを記述してください。
このシステムはAIを完璧にするものではありません。AIを予測可能にするものです。私たちは、AIが一貫して動作し、チームがより速く動けるようなコードベースを目指しています。