prd.md

A common pain point working with code generation tools like Cursor is that with every new chat, the agent needs to scan the code base to get context. The agent acts as though it's never seen this codebase before, even if it wrote every line of it. It's as if every day that an engineer showed up to work, they had to first sit through new hire orientation, peruse all the readmes, and internalize the organization's software development processes before writing a single line of code.

The best way I've found to mitigate this is to include a product requirements doc (PRD) as a markdown file in the repo. This prd.md file allows the agent to quickly catch up on what we're building.

Just like in human collaboration, good documentation matters. The difference is agents are amnesiacs (for now).

Prajwal Tomar on X goes a few steps further, recommending that you also include:

• App Flow Doc: Descriptions of user stories and flows
• Tech Stack Doc: List of technologies used (and perhaps ones to avoid)
• Frontend Guidelines: Fonts, color scheme, icon set, etc.
• Backend Structure Doc: DB schema, API spec, auth flow, etc.
• Implementation Plan: List of steps the agent should take

I don't agree with the last one – the agent should be able to figure that out on its own. And by listing the implementation steps you overprescribe what the agent does – perhaps the agent has a better plan. In that case, since LLMs are trained to be so agreeable, they will take the stupider path i.e. yours.

And aside from prd.md, I'm not sure the user should be generating these docs. If the user has strong opinions about tech stack, specify those up front when the app is initialized. But you probably just want to ask the agent itself to create and update this documentation as it goes.

If this technique catches on – a prd.md file that governs the agent's behavior – then I foresee a few further implications. From nearer- to longer-term:

1. Product documentation should really live in the codebase. In my experience it's always instead lived in Google Docs, Notion, etc. As agents contribute more to codebases, they'll need direct access to the product specs. What better place than in the codebase itself?
2. Bundling product specs with the codebase will invite coding agents to contribute more to product management. Give agents access to product usage data and user feedback, and they can start autonomously opening PRs on the product spec itself.
3. Taken to its extreme, we'll see the role of humans being (1) product conception, i.e. conceiving of awesome, novel products and initializing them and (2) orchestrating product development agents that ship, observe, deliberate, iterate, and repeat.
4. A question is where that orchestration will happen. Linear today announced that agents are coming – just assign an issue to an agent and then review their work. I suspect Github actually might end up being the winner, because it's the single source of truth for code.
5. The other opportunity that's interesting is how to make product usage data and user feedback accessible and optimized for agents. And developing agents that can intelligently go from those raw inputs to successful product iterations. I could see Amplitude or Atlassian going after this.