Creating and maintaining a prd.md file

I've previously written about the utility of having a prd.md in your project repo. It solves the problem of new chats with code agents starting with zero context.

Here are some other tips on creating and utilizing this file.

Creating a prd.md file

When I'm starting a new project, I typically converse with a reasoning model, such as o3 or Gemini 2.5. I start with the general idea and problem I'm trying to solve. The conversation then mainly consists of discussion of various approaches and homing in on a plan.

Once the plan is set, I ask the reasoning model to generate a prd.md file that I can then use to initialize the project. Specifically, the file should include relevant details for a coding agent to best execute our plan.

You can also generate a prd.md file retroactively, after the project is started. In fact, I just generated one for this website. The following prompt was effective:

can you review this codebase, which is a static website that is a personal blog (subtle.so) built using html, css, and vanilla js, and create a prd.md file that provides a general overview, context, and some design principles for future coding agents who might work on this codebase? it doesn't have to be super verbose, maybe just like 4-5 sections with information useful to LLMs.

I've found that Gemini 2.5 excels at repo-wide context. I used it for this prompt and you can see the results here.

Maintaining a prd.md file

As you work on your project and make changes or add features, you should update the prd.md file to reflect the current state of the project. This ensures that the file remains relevant and useful to future coding agents.

I've found the easiest way to do this is to ask a reasoning model to update the file at the end of a coding session. For this, I typically pose the following to Gemini 2.5:

can you review the codebase functionality and compare it to the current prd.md file, and for any significant details from the codebase that are missing from the prd.md file, update that file accordingly? think about context and details that would matter most to coding agents who might work on this project in the future.

(I've stopped saying "please" and "thank you" to these models because apparently that wastes energy 😬)

I'm trying some new agentic products such as Devin and Spur, which will probably work better when they have access to a context file like prd.md.