PLAN.md

PLAN.md is a file that lives in your project and serves as long-term memory for an AI coding assistant. It records the project’s goals, architecture decisions, current status, and what’s next, so the AI can read it at the start of every session and pick up where things left off. In practice, it functions as a project charter that prevents drift when working across multiple conversations or sessions.

The Simple Version

When you’re working with an AI coding assistant like Claude Code, it can only remember so much conversation at a time (that’s the context window). Start a new session and it might forget what you were building, what decisions you already made, or what phase the project is in.

PLAN.md solves that. It’s a file that lives right inside your project folder. It records everything the AI needs to know: what the project is, what’s been built, what’s in progress, what comes next, and what design decisions were made along the way. When a new session starts, the AI reads this file and picks up exactly where things left off.

Think of it like leaving yourself a detailed note before going to sleep, so you know exactly what to do when you wake up.

Why It Matters

Without a plan file, every conversation with an AI assistant starts from scratch. You spend the first 10 minutes re-explaining your project instead of building. With it, the AI has institutional memory. It knows not to suggest React when you’ve already decided on Astro. It knows your color scheme. It knows which features are done and which are next.

PLAN.md also forces you to think like a product manager. Writing down your goals, constraints, and architecture choices clarifies your own thinking. The precision of the plan directly improves the quality of what gets built.

How It’s Used on This Site

This site’s PLAN.md records every phase of the build, from preserving the original Lovable code to deploying on Vercel to building The Vibe-Coder’s Dictionary. It tracks which blog posts are published, which features are in progress, and what’s consciously deferred. Claude Code reads it at the start of every session, which is why this project has stayed coherent across dozens of work sessions.

See It in Action

The PLAN.md file is referenced throughout the blog post on how this site was built, where it’s described as the system that prevents drift and keeps the AI aligned with the project’s goals.