Give your AI the full picture with a context repository

Most of the bad output people get from AI isn't a model problem. It's a context problem.

The AI doesn't know your product vision. It doesn't know your customer segments. It doesn't know why you chose one architecture over another, or what your brand voice sounds like, or what terms your team uses internally. So it fills in the gaps with assumptions.

The fix is straightforward: build a context repository. A git repo full of Markdown files where you store the critical business documents your AI needs to operate with real understanding. Product vision, PRDs, feature specs, customer profiles, glossary, marketing messaging, style guides, all in one place, versioned and reviewable, where both humans and AI agents can find it.

OpenAI recently showed what this looks like at scale. A team of three engineers used structured documentation to ship a million-line product — with zero hand-written code. The technique wasn't a secret. They kept Markdown files in the repo that gave their agents the context to make real decisions.

What goes inside

I recently set up a context repository for a project I'm working on. Here's the structure:

product-planning/
├── strategy/
├── prds/
├── features/
├── customers/
├── marketing/
├── research/
├── competitors/
├── glossary/
└── integrations/

product-planning/
├── strategy/
├── prds/
├── features/
├── customers/
├── marketing/
├── research/
├── competitors/
├── glossary/
└── integrations/

The strategy/ folder holds the product vision and operating plan. These are the documents that answer why — why this product exists, where it's headed, what matters most right now. When an agent needs to make a judgment call about scope or priority, this is what it reads.

Feature specs in features/ break the product down by domain: catalog, pricing, sales, finance. PRDs in prds/ describe specific initiatives. Customer profiles in customers/ define who you're building for. Each document is focused and self-contained.

How to set it up

I recommend Markdown files in a Git repo. There are a few ways to organize it depending on the size of your team:

• Folder in your project — The simplest option is just a folder like docs/ or planning/. This works fine for solo developers or very small teams where branch drift isn't a concern.
• Dedicated branch — For smaller teams, a dedicated branch in your main repo can work well. The reason I recommend a branch over a folder is subtle but important: when engineers create feature branches for code, those branches carry whatever version of the docs existed when they branched. The docs drift out of sync across branches. A dedicated branch like docs/planning stays canonical — agents always read the latest version from one place.
• Separate repository — For larger organizations, I recommend a dedicated repo for product planning. It's easier to manage access — not everyone on your team pushes code, but many people contribute to product documents. A dedicated repo gives you clean ownership and review workflows without mixing concerns.

You could also put everything in Notion and connect it to your AI via an MCP server, but Markdown in a git repo is better for a few reasons. Every MCP call adds latency — your agent has to make API requests to read each document, while local files are instant. AI agents also understand Markdown natively. Why add a conversion layer? Markdown is also token-efficient: no rich-text metadata, no block structures, just content. And a git repo gives you versioning and branching for free. When you update five documents as part of a product pivot, that's one reviewable PR you can roll back if needed.

AGENTS.md as a table of contents

Once you have a context repository, you need to tell your AI where to find it. The best way to do this is with an AGENTS.md file in the root of your project.

A good AGENTS.md links to content in your context repository describing where to find the important information. When an agent picks up a task, it reads AGENTS.md first, then follows the links to the important information as needed. This keeps your root file short and scannable while giving the agent a clear map of everything available.

# Product context
 
- [Product vision](./docs/strategy/vision.md)
- [Current roadmap](./docs/strategy/roadmap.md)
- [Customer profiles](./docs/customers/)
- [Feature specs](./docs/features/)

# Product context
 
- [Product vision](./docs/strategy/vision.md)
- [Current roadmap](./docs/strategy/roadmap.md)
- [Customer profiles](./docs/customers/)
- [Feature specs](./docs/features/)

Think of the AGENTS.md as a table of contents to the important information in your context repository.

Start small

You don't need all of this on day one. Start with one or two important documents and expand from there. I'd recommend a product vision document and a roadmap. The vision doc gives your AI the "why" of what you are working on. The the roadmap gives it an understanding of what you plan to build next.

Add additional documents like PRDs and customer profiles as you go. Every document you add is another piece of context your AI can draw on. After a few weeks you'll wonder how you ever worked without it.