The 6 Essential .md Files You Need Before Vibe Coding

Before you write a single prompt, an AI coding agent needs six markdown files in your repo root: README.md, PRD.md, ARCHITECTURE.md, DESIGN-SYSTEM.md, AGENTS.md (or CLAUDE.md), and TASKS.md. Together they take about three hours to write and they replace the context an agent otherwise invents — scope, stack boundaries, design tokens, coding rules, and build order. Skip them and the model guesses; every guess becomes code you have to unpick later.

We wrote earlier about where vibe coding earns its keep and where it quietly falls apart. This is the fix for the “falls apart” half. It isn’t a better prompt. It’s context the agent can read on every single turn.

The six files at a glance

Total: roughly 3 hours 10 minutes. For context, unpicking a drifted design system across an already-built storefront is typically a multi-day job.

Naming conventions by tool

Keep one canonical file and symlink or copy it to whatever your tool expects. Maintaining two copies means maintaining one and forgetting the other.

What actually goes in each file

1. README.md — orientation

The first thing any agent reads. Under 150 lines. Product in one sentence, stack in a table with versions, the exact commands to install, run, build, lint and test, every environment variable with where to get it, and a folder map.

If your agent has to run ls -R and open package.json to work out what framework you’re on, you’ve paid for those tokens and that turn for nothing.

2. PRD.md — scope and reasoning

The “why” file, and the one a founder must write rather than generate. Problem statement, user types with their actual constraints, success metrics you could check in 90 days, and the user journeys that matter.

The single most valuable section in the whole pack is “Explicitly NOT in scope.” An agent with a blank spec will happily add a wishlist, a review system and a blog you never asked for, because those things co-occur with “e-commerce site” in its training data. Name them as out of scope and they stop appearing.

Add a decisions log at the bottom, append-only. It stops the agent re-litigating calls you already made.

3. ARCHITECTURE.md — structure and boundaries

Stack choices with a why column, a folder map with a rule for what belongs where, the data model with conventions (money as integer paise, timestamps as timestamptz in UTC, enums not free-text), integrations and their failure modes, and a performance budget.

Include a known trade-offs section. If you deliberately left something simple — no caching layer, no CMS — write down why. Otherwise an agent will helpfully “fix” it.

4. DESIGN-SYSTEM.md — the anti-drift file

This is the one most teams skip and the one that costs the most. Real hex values, real pixel numbers, real font names. “Modern and clean” tells a model nothing. --color-brand: #1A5F3F tells it exactly one thing.

Cover tokens (color, type scale, spacing scale, radius, shadow, motion), then every component with its variants, sizes, and all its states — default, hover, active, focus-visible, disabled, loading. States are where agents cut corners, because a screenshot only ever shows one.

Then one standing rule at the top: never invent a value. If it isn’t in this file, stop and ask.

5. AGENTS.md — operating rules

Standing instructions, read before every session. Rules here must be specific and checkable. “Write clean code” does nothing. “Never import from lib/db inside a component” is enforceable.

What belongs here:

• Non-negotiables — don’t add dependencies without asking, don’t touch migrations/, don’t delete tests to make them pass, don’t refactor unrelated files
• Working rules — one task at a time; plan before touching more than three files; stop after two failed attempts and report instead of retrying variations
• Definition of done — typecheck, lint, test, build, renders at 375px and 1440px, keyboard-navigable with visible focus states, no new console errors
• Project gotchas — the undocumented thing a newcomer trips on. formatPrice() takes paise, not rupees. Write it down the day you discover it.

6. TASKS.md — the build queue

This is what converts “build me a store” into twenty prompts you can actually review. Each task gets an ID, a one-line outcome, checkable acceptance criteria, and its blockers.

Sizing rule: if a task can’t be verified in under five minutes, split it. Sections for Now, Next, Later, Blocked, Done and Bugs. Keep Done — it’s the project’s history and it stops the agent redoing finished work.

How to set this up: the sequence

Step 1 — Write PRD.md first, by hand. Before any tooling. If you can’t write the problem statement and the out-of-scope list without hedging, you aren’t ready to build yet, and no amount of prompting will cover for that.

Step 2 — Write DESIGN-SYSTEM.md from your existing brand assets. Pull the real hex codes out of your logo files and packaging. If the brand doesn’t have a defined type scale yet, define one now — this is cheaper than retrofitting it across 30 components.

Step 3 — Scaffold the project, then write README.md and ARCHITECTURE.md. These describe decisions, so they follow the decisions. Write them the same day you make the calls, while the reasoning is still fresh.

Step 4 — Write AGENTS.md last of the five. It references the other four, so it’s easier once they exist. Point to them explicitly at the top: read README, then PRD, then ARCHITECTURE, then DESIGN-SYSTEM.

Step 5 — Break the build into TASKS.md. Twenty to forty items for a typical storefront. Each one small enough to check in five minutes.

Step 6 — Run one task per prompt. Point the agent at TASKS.md, tell it to take the top unblocked item, finish it, update the status, and stop. Review. Then the next one.

Step 7 — Update the files as you go. These are living documents. Every gotcha discovered goes into AGENTS.md. Every settled argument goes into the PRD.md decisions log. A stale context file is worse than none, because the agent trusts it.

What we see in practice

We build D2C storefronts, and we’ve run projects both ways.

Without these files, the pattern is predictable and it always shows up around week two or three. Spacing values that don’t belong to any scale. Three greys where there should be one. Buttons with no focus state, because nobody prompted for keyboard users. A component that fetches its own data because the agent had no reason to know that wasn’t allowed. None of it looks broken in a screenshot. All of it has to be redone before real traffic hits the site.

With the files in place, the failure mode changes shape entirely. The agent asks instead of assumes, because AGENTS.md tells it to. Review gets fast, because each TASKS.md item is small enough to check properly. And when a build gets handed to a different developer — or a different model six months from now — the context is in the repo, not in someone’s memory of a Slack thread.

The honest caveat: this doesn’t make vibe coding equivalent to a designed build. Strategy still isn’t in the files — why your specific customer abandons the cart, where your product photography needs to lead the eye, how your packaging story carries through to the PDP. What context files do is stop you losing the implementation to drift while you work on the parts that actually need a human.

Frequently asked questions

Building something and not sure whether it’s a prototype or a real storefront? Talk to us about your build →