Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

【ITニュース解説】Plan Mode Saves Your Plan Where Only One Agent Can Find It. Commit PLAN.md Instead

2026年11月04日に「Dev.to」が公開したITニュース「Plan Mode Saves Your Plan Where Only One Agent Can Find It. Commit PLAN.md Instead」について初心者にもわかりやすく解説しています。

作成日: 更新日:

ITニュース概要

AIエージェントが作成する開発計画は一時保存が一般的だ。しかし、コードレビューや他AI、チームでの引継ぎには不便。計画は成果物と捉え、Gitリポジトリに`PLAN.md`としてコミットしよう。計画とコードのずれを防ぎ、共有・確認が容易になり、開発を円滑に進められる。

ITニュース解説

AIコーディングエージェントは、私たちがコードを書く作業を強力に支援してくれるツールである。開発者が「こんな機能を作りたい」と指示を出すと、エージェントはまずそのタスクをどう進めるかの「計画」を立てる。例えば、Claude CodeやGitHub Copilot CLIといった主要なエージェントには、このような計画を立てるための「計画モード」が備わっている。これらのエージェントは、コードを実際に変更する前に、その計画を私たち開発者に提示し、承認を求めることが一般的だ。

しかし、現在多くのエージェントが作成した計画の保存方法には、いくつか課題がある。通常、これらの計画はエージェントが作業している「セッション内」に留まったり、ユーザーのホームディレクトリ内の特定のキャッシュフォルダに一時的に保存されたりする。例えば、Claude Codeは計画ファイルを ~/.claude/plans/ といった場所に置くが、このフォルダはキャッシュとして扱われるため、一定期間が経過すると自動的にクリーンアップされる可能性があり、「ユーザーが意識することのない情報」と位置づけられている。GitHub Copilot CLIも同様に、セッションフォルダ内に計画ファイルを保存する。

このような保存方法は、単なる一時的なキャッシュとしては理にかなっているかもしれない。しかし、計画はエージェントがコードに手を加える前に私たち開発者が最も詳細にレビューすべき重要な成果物である。この重要な計画が一時的なキャッシュとして扱われると、いくつかの問題が生じる。

まず、計画がレビューしにくいという点がある。私たちがプルリクエスト(PR)でコードの変更内容をレビューする際、そのコードがどのような計画に基づいて作成されたのか、元の計画と現在のコードとの間に乖離がないかを確認したいと考えるのは自然なことだ。しかし、計画がエージェントのセッション内に閉じ込められていたり、特定のPCの一時フォルダに隠されていたりすると、コードと計画を並べてレビューすることが非常に困難になる。結果として、計画の承認は一度きりの儀式となり、その後はその内容を二度と確認できない、といった状況に陥りがちだ。

次に、計画の変更履歴を追跡できないという問題がある。タスクを進める中で、エージェントの学習や私たちの指示によって計画が変更されることはよくある。しかし、計画が一時的な場所に保存されていると、その変更がいつ、なぜ行われたのかを後から確認することができない。これは、開発プロセスにおける重要な意思決定の記録が失われることを意味する。

そして最も大きな問題の一つは、エージェント間の作業の引き継ぎ(ハンドオフ)が難しいことだ。例えば、特定のエージェントに利用制限がかかった場合や、より得意な別ベンダーのエージェントにタスクの一部を任せたい場合、最初のエージェントが作成した計画を次のエージェントにスムーズに渡す必要がある。しかし、計画が最初のセッションや一時フォルダに閉じ込められていると、次のエージェントは計画を最初から作り直すか、私たちが手動で情報をコピー&ペーストしなければならない。これは作業の効率を著しく低下させる。

これらの課題を解決するために提案されるのは、エージェントが作成した計画を「Gitのリポジトリにコミットされたファイル」として管理する習慣を身につけることだ。具体的には、PLAN.md のような名前で、マークダウン形式の計画ファイルをタスクブランチに作成し、コードの変更と合わせてバージョン管理システムで管理するのである。

この「計画をコミットする」という習慣には、多くのメリットがある。

一つは、レビュープロセスの改善である。PLAN.md がプルリクエストに含まれていれば、レビュアーはコードと一緒に計画を読み、コードが計画に沿って実装されているか、あるいは計画から逸脱している部分がないかを簡単に確認できる。これにより、単にコードのバグを探すだけでなく、より上位の設計意図に沿ったレビューが可能になる。

二つ目は、計画の変更履歴の明確化だ。Gitの履歴機能を使えば、git log -p -- PLAN.md のようにコマンドを実行することで、計画がいつ、どのように変更されたかを追跡できる。これにより、タスク進行中の意思決定の経緯が明確に記録され、後から振り返る際にも役立つ。

三つ目は、エージェント間のシームレスな連携だ。計画がリポジトリ内の PLAN.md に保存されていれば、どのベンダーのエージェントであっても、作業に取りかかる際にまずこのファイルを読み込み、「PLAN.md を読んで、まだチェックされていないステップから作業を継続してほしい」と指示するだけで、前任のエージェントの作業を引き継げる。これは、エージェントの利用制限に直面した際や、特定のタスクに適したエージェントに切り替えたい場合に、非常に強力な助けとなる。

具体的な運用方法としては、エージェントが計画を承認した後、すぐにその計画を PLAN.md というファイルに書き出し、最初のコード変更を行う前にそのファイルをGitにコミットすることが推奨される。PLAN.md の中には、「目標 (Goal)」、「ステップ (Steps)」、「決定事項 (Decisions)」、「完了条件 (Done when)」といったセクションを設けるのが良い。特に「決定事項 (Decisions)」セクションは、エージェントとの会話の中で行われた重要な判断が失われがちな部分であり、レビューする側にとっても重要な情報となる。

さらに、AGENTS.md というファイルを作成し、エージェントに対する共通のルールを記述することも有効である。例えば、「PLAN.md が存在する場合、コードを変更する前にそれを読むこと」「PLAN.md のステップを完了したら、その変更と同じコミットでチェックを入れること」「アプローチの変更は『決定事項 (Decisions)』セクションに追記すること」といったルールを記述すれば、どのエージェントも一貫した行動を取るようになる。

この PLAN.md の習慣は、特定のIDEやツールに依存するものではなく、一般的なGitの機能と開発者の習慣によって実現できる。もちろん、一行の修正のような単純なタスクや、一つのエージェントで短時間で終わるようなタスクであれば、あえて計画ファイルをコミットする必要はない。しかし、数日にわたるタスク、複数のエージェントやレビュアーが関わるタスクでは、その価値を最大限に発揮するだろう。

ただし、PLAN.md も他のドキュメントと同様に古くなる可能性があるため、注意が必要だ。AGENTS.md で設定したルールに従い、ステップの完了と同時にコミットするなどして、常に最新の状態を保つ努力が重要となる。もしレビュー中に、コードがPLAN.md に記載されていないステップを実行していることに気づいたら、それは質問すべき点だ。

この「計画をコミットする」という考え方は、エージェントが単に記憶している情報ではなく、私たちが管理するドキュメントから情報を取得し、行動するという点で、Retrieval Augmented Generation(RAG)という技術の最も小さな規模での応用と考えることもできる。私たちは、エージェントとのより効果的な協調作業を通じて、開発プロセスをより透明で、堅牢なものにしていくことができるのだ。

関連コンテンツ

関連IT用語