Plan Mode Saves Your Plan Where Only One Agent Can Find It. Commit PLAN.md Instead

In the world of AI coding tools, plans are often stored in a default location that is only accessible to the specific agent that created them. This can make it difficult for other agents to review and build upon the work done by the original agent. However, there is a solution that ensures the plan is accessible to all involved parties.

Claude Code, a popular AI coding tool, allows users to enter plan mode by using the Shift+Tab or /plan command. In this mode, Claude Code writes the plan to a file named plan.md in a specified directory. By default, the plan is saved in ~/.claude/plans/, but users can customize this location by setting the plansDirectory setting in the .claude/settings.json file.

The contents of the plan.md file include the plan itself, a status showing the progress of the plan, a goal or objective, a list of steps to complete the plan, any decisions made during the planning process, and a section called Done when, which specifies when the plan is considered complete.

After approving the plan in plan mode, users are encouraged to commit the PLAN.md file to the repository along with the initial code changes. This ensures that the plan is a part of the version-controlled history, allowing reviewers to see how the plan evolved as the agent learned more about the task at hand. By committing the plan file, users enable multiple agents to pick up where the original agent left off, regardless of which AI coding tool they are using.

To promote a standardized approach across different AI coding agents, users can create an AGENTS.md file that contains guidelines for handling plans. For example, AGENTS.md can instruct agents to read PLAN.md before making any code changes, to tick off steps in the plan when completed, and to document any changes made to the plan in the Decisions section.

By adopting this approach, the plan becomes an integral part of the development workflow, ensuring that all agents involved in the project have access to the same information and can collaborate effectively. This not only improves the review process but also enhances the overall quality and maintainability of the codebase.