A few months ago, I wrote an article about how you can master the art of prompting for code, to get the best results out of your AI pair-programming companion, however even using all of that guidance can still lead to underwhelming results.

If you’ve ever had your AI pair-programmer produce code that looks nothing like what you had in mind, then you may be skipping a step with the AI that - before the AI revolution - you did all the time without realising it.

Planning!

Enter the Planfile

Now, I’m not here to shame you, I’m here to hand you a solution. Meet planfiles: simple Markdown documents where you and your AI hash out a game plan before diving into coding. Think of a planfile as a living blueprint for whatever feature or project you’re tackling. You stash these files in a planfiles directory (and add that to your .gitignore so you don’t accidentally commit your brain dumps), and use them to guide AI-assisted coding tools like Cursor.

Now, if you’re rolling your eyes and thinking “Great, more documentation work.” the yeah, I get it. I’ve been coding since before most of you were born and writing docs has never been my idea of fun. But planfiles aren’t about pleasing project managers or checking a box. They’re about making sure your AI assistant is on the same page (literally) as you, so it stops inventing things or forgetting context. In other words, a little upfront planning with a planfile can save you from heaps of frustration later.

Planfiles in Action: From Rough Outline to Solid Plan

So how do you actually use a planfile? Let me walk you through my process. It usually goes down in two phases:

Step 1: Get the AI to draft a rough plan.

I start a session by telling the AI that before writing any code, we need to flesh out a plan in a separate Markdown file. This prompt is where I outline what feature we’re focusing on and what considerations to include. For example, recently I was building a side panel feature for a mapping application. I told the AI exactly that, and even pointed out the different types of panels we’ll need (with one, bathing site, being our primary focus). I explicitly said, “document this in our plan document but do not start writing any code yet.” That last part is crucial , it keeps the AI from jumping the gun.

I created a file called side-panel.plan.md in my planfiles folder and then I gave it the following prompt (I slightly altered some of the information to make it more generic so as not to risk identifying the client):

Ok before we work, we're going to flesh out our plan. We're going to be working on the plan in this document @side-panel.plan.md

The side panel will be built out in @/map-sidebar

There are different side panels for each type of feature that a user clicks on. The side panels that exist are:

- Location detail feature
- Infrastructure node feature
- Surface node feature
- Grouped feature

They are all mutually exclusive but some of them have similar data shapes and use similar components.

All sidebars have a header and a place for a symbol to go to the left of that header. If the header does not have a symbol then the space for it should collapse.

Today we are focusing on the location detail feature but we still need to have placeholders for the others.

Please document this in our plan document but do not start writing any code yet.

The AI took that prompt and spit out a structured plan in Markdown.

It wasn't perfect and lacked a lot of detail that I hadn't told it about yet but it was a great starting point, but it got a few things wrong and glossed over some project-specific details. And that’s okay.

This is where Step 2 comes in:

Step 2: Refine the plan with your own knowledge.

I went into the generated planfile (side-panel.plan.md) and edited it. I corrected the AI’s wrong assumptions, filled in actual file paths and component names from my codebase, and added constraints the AI missed (like “use our existing theme variables, don’t invent new ones”). The end result was a fleshed-out plan that was accurate, detailed, and tailored to my project.

To give you an idea, here’s what the final planfile looked like after I merged the AI’s outline with my edits:

Here's a link to the GitHub Gist

Yes, that was a lot. But here’s the beauty of it: once this planfile existed, both me and the AI had a shared understanding of what needs to be done. The planfile became our single source of truth for the feature. I could literally say to the AI in subsequent prompts, “Refer to the planfile for details,” and it would have all the context it needed.

I would then tell it to implement phase 1, then phase 2 and so on. It's still not perfect although most of the time it's because I made an assumption which I did not explicitly include in the plan. It's easy to forget that I have domain knowledge and wide context information that, despite being on this project with me since day 1, Cursor does NOT have.

Additional things to include in/with the plan

The plan itself is just one slice of the bigger picture but there are plenty of other things you can include alongside the plan (and reference within the plan). I have a /docs folder which was originally created for onboarding new human developers to the project but actually works well as a foundational knowledge base for the AI as well, so it's useful to reference that.

In other projects, my docs folder also includes things like C4 models, mermaid charts and dbml files to truly give the onboarding developer (be they human or digital) all the information they could possibly need.

Why Planfiles Make AI Collaboration Better

The example above might seem like overkill, but it highlights why planfiles are a game-changer when working with AI:

• Shared Context, Even When Memory Fades: AI models have a limited attention span (the context window). In long sessions, details from earlier prompts can get forgotten. A planfile lives outside the chat buffer, it’s like an external memory. Whenever the AI starts to go off track or forget a detail, you can point it back to the planfile. No more “Ugh, do I have to explain this again?” moments; the planfile keeps the AI on the rails.
• No More Vague Assumptions: Ever had an AI make up a function or a database field that doesn’t exist? That happens when your instructions leave blanks. By fleshing out a plan, you’re proactively filling in those blanks. The planfile lists the actual components, data shapes, constraints, and even file paths. This means the AI doesn’t have to guess, it knows what’s what. When I corrected the planfile above, I made sure to include real filenames and design rules (like using theme variables). The next time the AI generated code, it adhered to those specifics instead of inventing its own.
• Consistency Across Sessions: Maybe you’ve noticed that if you start a fresh chat or come back the next day, the AI might suggest something completely different from yesterday. Planfiles help to avoid that. Since the planfile is saved in your project (and in your AI-integrated IDE side panel), you can easily refresh the AI’s memory by showing it the planfile at the start of a new session. It’s like saying, “Here’s what we decided yesterday, let’s pick up from here.” This keeps the implementation consistent with the plan, no matter how many breaks or context resets happen in between.
• Better Collaboration (Human-Friendly Too): While planfiles are mainly for you and the AI, they’re still just Markdown files. If you’re working with other devs, you can share these planning docs (outside of your repo, since they’re .gitignored or you can agree to leave them in the repo for posterity) to get feedback or do code reviews against the plan. It’s easier to discuss “Hey, in Phase 3 we planned X, but the code does Y” than to reverse-engineer intent from code alone. In a way, you’re documenting as you go, without the formality of a spec document.
• Historical context: As I mentioned earlier, Cursor doesn't have the domain knowledge or wider context that I have even though we started on the project together, going forward, I expect this to change as now it can refer to previous planfiles and can see what it did to implement each feature.
• Bonus: When you are happy with how it has implemented a feature, tell it to update the planfile with it's findings. That way, you'll have a record of the changes each PR creates. Which will make life easier for you and the AI going forwards.
• Bonus 2: As the final step, you can ask it to assess the code that it has written for this plan for improvements - It almost never considers the big picture or things like DRY or performance when it's writing code the first time but once it's finished, you can give it all of the code it wrote as context and ask it what improvements it can make. Tell it to add the suggestions to the plan, that way you can review them and decide on what is worth doing and what isn't.

In short, a planfile acts as a 'north star' for you and your AI assistant. It mitigates the AI’s short-term memory issues, eliminates a lot of the guesswork, and keeps the development process coherent. It’s like having a project manager whispering in both your ears, keeping everyone aligned, except that project manager is you, and the whisper is a Markdown file.

Conclusion: A Little Planning Goes a Long Way

I won’t pretend that creating a planfile is as thrilling as slinging out code. It takes a bit of discipline to pause and plan when you’re itching to build. But from my experience, that small upfront effort pays off massively. When your AI knows exactly what you want and the constraints it must work within, coding becomes a smoother ride. Instead of correcting the AI’s course every 5 minutes, you both follow the roadmap you laid out.

So next time you fire up Cursor (or whatever AI coding tool you’re working with), try this: start a planfile for your task. Treat it like a conversation with your future self and your AI buddy. Outline the goals, nail down the requirements, and don’t be shy about adding all the nitty-gritty details. Then let the AI loose on the coding. You’ll find it sticks closer to the brief, and when it doesn’t, you have the planfile to refer back to and steer it right.

In a world where AI is not clairvoyant, a well-crafted planfile is the closest thing to giving it a clue. It turns out that a little up-front planning makes everything run a lot smoother. Consider it the next time you’re about to dive in head-first.

Let's face it, in the not-too-distant-future, writing code could be something we rarely - if ever - do anymore but writing code isn't what makes us engineers, engineering itself is not about putting the plan into action, it's about creating the plan and thinking through the problem, so you might as well get used to formalising it in writing now as this is very likely to be the bulk of your job before you even know it!

Happy planning!