【ITニュース解説】Why your AI coding agent contradicts itself in session 5 (and the three-file fix)

AIコーディングエージェントは、ソフトウェア開発の現場でコードの生成、デバッグ、ドキュメント作成など、多岐にわたる作業を支援する強力なツールとして期待されている。しかし、このエージェントが会話のセッションをまたぐと、過去の議論や指示を忘れ、以前の決定と矛盾するような行動を取ることがあるという問題が指摘されている。これは、エージェントの性能が低いわけではなく、根本的にセッションごとに独立しており、前のセッションの記憶を保持しないためである。結果として、人間がセッション間の情報の橋渡し役となり、その負担がプロジェクト進行の妨げとなる。

このエージェントの記憶喪失は、主に二つの具体的な問題を引き起こす。一つは「コンテキストの喪失」である。新しいセッションが始まると、エージェントはプロジェクトの背景、目的、制約事項などを全く知らない状態となる。そのため、人間は毎回、これらの情報を頭の中から引き出し、エージェントに再度説明しなければならない。この過程で、重要な制約を見落としたり、誤って伝えたりするリスクがあり、それが原因で生成されるコードが意図と異なるものになることがある。もう一つは「再検討される決定」である。例えば、ある機能の設計について時間をかけて議論し、特定の仕様で合意したとする。しかし、新しいセッションでは、エージェントはその決定の経緯を知らないため、未完成の機能を見て、過去に却下された選択肢を再び提案してくるかもしれない。これにより、人間は過去の議論を繰り返すか、熟慮の末の決定を覆すかの選択を迫られ、開発の効率が低下する。これらの問題は、プロジェクトに関する重要な情報や決定が、人間の記憶や閉じたチャット履歴の中にしか存在しないために発生するのだ。

この問題に対処し、エージェントがセッションを越えてもプロジェクトの情報を「記憶」し続けるための効果的な解決策がある。それは、プロジェクトの基本情報、これまでの決定事項、そして現在の進捗状況をテキストファイルに明示的に記述し、エージェントがこれらのファイルを読み込むことで、常に最新かつ正確なコンテキストを把握できるようにする方法である。このアプローチは、主に三つの「層」で構成される。

第一の層は「マスタープロンプト」だ。これは、プロジェクトが何を目指しているのか、誰のために開発されているのか、どのような制約があるのかといった、プロジェクトの根本的な真実や変わることのない基本方針を記述したものである。この情報はプロジェクトの期間中にほとんど変更されないため、セッション開始時にエージェントに提示する固定的な背景情報として機能し、一貫した理解の基盤を提供する。

第二の層は「スキャフォールドファイル」と総称される、これまでに下された決定やプロジェクトの現在の進捗状況を記録するファイル群である。この層は、エージェントが「記憶」を形成する上で最も重要であり、セッションごとに内容が更新される動的な情報源となる。具体的なファイルとして、以下の三つが挙げられる。

一つ目は「CLAUDE.md」のように、AIエージェントがセッション開始時に自動的に読み込む設定ファイルである。このファイルには、プロジェクト固有の慣習、使用するツール、またはエージェントのデフォルト動作と異なる特有のルールや情報を記述する。例えば、「公開される文章では、特定の実績を保証するような表現は避ける」「料金の識別子は特定のファイルで管理し、コードに直接記述しない」「あるファイルは自動生成されるため、手動で編集してはならない」といった項目だ。このファイルは、エージェントが毎回読み込むため、内容を短く、約40行程度に保つことが推奨される。エージェントが通常行うであろう「良いコードを書く」といった一般的な指示や、頻繁に変わる作業内容はここには含めず、エージェントが通常知り得ない「驚き」となるような固有の情報に限定して記述する。

二つ目は「DECISIONS.md」で、これはプロジェクトにおける重要な決定事項とその背景を記録するためのファイルだ。各決定は、日付、具体的な決定内容、その決定に至った理由、検討された代替案、そしてどのような状況になればその決定を再検討すべきかというフォーマットで記述する。例えば、「支払いと役割のマッピングは設定テーブルで行う」という決定に対し、「価格は将来的に変更される可能性があるが、そのロジックは安定させるべきだから」といった理由を明記する。代替案を記録することで、同じ議論の蒸し返しを防ぎ、再検討条件を定めることで、将来的に状況が変わった際に適切に決定を見直せるようにする。一度記録した決定は削除せず、もしその決定が覆された場合は、新しい決定を追記し、古い決定が新しいものに取って代わられたことを明記して、決定の完全な履歴を残すことが重要である。

三つ目は「PROGRESS.md」で、これはプロジェクトの現在の状態、次に何をするべきか、そして何が作業を妨げているかという三つの問いに答えるファイルだ。具体的には、「ウェブサイトのフェーズは進行中であり、テストがパスし料金ページがレンダリングされれば完了する」といったステータスボード、次に実行すべき具体的なアクション、そして「ライブ支払いリンクはアカウント認証待ちでブロックされている」といったブロックされている事項を記述する。このファイルは、エージェントが何も覚えていない新しいセッションのために書かれるものと考え、各セッションの終了時に必ず更新する習慣を徹底することが推奨される。これにより、エージェントと人間が常に最新の進捗状況と次のアクションを共有できる。

第三の層は「セッションライン」で、これはその日の作業範囲をエージェントに簡潔に指示する一行の命令である。例えば、「今日は標準プランの支払いリンクを料金カードに組み込む。まずPROGRESS.mdを読み込んでから作業を開始せよ」といった具体的な指示を出す。この命令によって、エージェントはその日のタスクと、参照すべきファイルの指示を受け取る。

特に、金銭の処理、顧客データの操作、公開、データの削除など、リスクの高い作業を行う場合には、特別な手順を踏む必要がある。これは、作業を「計画」「承認」「構築」の三段階に分割することだ。まず、エージェントに「何を行うか、どのような順序で、どのファイルに影響するか、そしてどのような問題が発生しうるか」という詳細な計画を作成させる。この時点では、実際のコード生成は行わせない。次に、人間がその計画を慎重にレビューし、承認するか、修正を指示する。最後に、承認された計画に基づいてエージェントに構築作業を実行させ、計画からの逸脱があれば報告させる。人間が口頭で与えた承認は、次のセッションでは存在しないものとして扱われるため、承認内容は必ずPROGRESS.mdに記録することが極めて重要である。

これらのファイルを最大限に活用するためには、セッションの開始と終了時に特定のルーチンを実行することが効果的だ。セッションを開始する際には、マスタープロンプトを提示し、その日の具体的な作業範囲と「まずPROGRESS.mdを読み込むこと」という指示を含むセッションラインをエージェントに伝える。セッションを終了する際には、エージェントにPROGRESS.mdを更新させ、現在のステータス、次に取るべきアクション、そしてブロックされている事項を記録させる。もしセッション中に新しい重要な決定がなされた場合は、その内容をDECISIONS.mdに追記させる。また、エージェントに、何を変更し、何を検証しなかったかを報告させることで、次回のセッションへの引き継ぎをより明確にする。

この「ファイルを介した記憶」の仕組みを導入することで、AIコーディングエージェントはセッションをまたいでもプロジェクトの背景、これまでの決定、そして現在の進捗を正確に把握できるようになる。これにより、同じ議論を繰り返す無駄を省き、誤ったコンテキストでの作業を防ぎ、開発プロセス全体の効率と精度を大幅に向上させることができる。セッションの終わりに数分間のルーチンを設けるだけで、次回のセッションで失われたコンテキストを再構築するために費やす時間を大きく節約できるのだ。もしエージェントが特定の決定を何度も再提案してくる場合は、DECISIONS.mdにその決定の「理由」や「再検討すべき条件」が適切に記述されているかを確認してみると良いだろう。