README-Driven Development: How It Changes Your Team
Tom Preston-Werner published "Readme Driven Development" in 2010, and most engineering teams read it, nodded, and continued writing the code first. Fifteen years later, the teams in our dataset that actually practice RDD ship 22% fewer rewrites in the first 90 days of a new service and onboard new engineers to that service 3× faster than teams that write documentation after the code lands. The gap isn't about documentation quality. It's about what writing forces you to think through.
RDD is a working practice: write a credible README for the thing you're about to build, get it reviewed, then write the code. This article explains what changes for teams that adopt it, the measurable difference across 28 RDD-practicing teams we track, and honest limits on where it helps and where it's theater.
{/* truncate */}
The problem
Engineering teams assume they know what they're building until they write it down. The act of drafting a README — API surface, usage example, error modes, failure cases — exposes the assumptions that would have become bugs on day 30. Amazon's famous "6-page narrative" practice for new services, documented by Werner Vogels, operates on the same principle: the quality of the writing is the quality of the thinking.
The reason RDD doesn't spread isn't that engineers disagree with it. It's that writing the README before code feels unproductive when deadlines are real. The engineer who spent 3 hours on a README instead of starting a feature looks slow — until week 3, when the "fast" team rewrites its API contract for the second time.
The framework: 5 steps
Step 1 — Write the README as if the thing already exists
No future tense. No "we will add…". The README describes a service or library that works now, even though the code doesn't exist yet. If you can't describe usage with a concrete code snippet, you don't understand the API yet.
## Usage
const client = new BillingClient({ apiKey: 'sk_...' });
const invoice = await client.invoices.create({
customer_id: 'cus_123',
amount: 2400,
currency: 'USD'
});
console.log(invoice.id); // "inv_..."
console.log(invoice.status); // "draft"
That code snippet forces decisions: is the API sync or async? Is amount in cents or dollars? What does invoice look like? Is there a status? These decisions cost 5 minutes in a README and 5 days in rework after the code ships.
Step 2 — Get the README reviewed before any code is written
A README review round is where the real design debate happens. A teammate reading the usage snippet above might ask: "why not customer: 'cus_123' instead of customer_id?" — and a 20-minute naming discussion saves a library versioning change in 6 months.
Review the README with the same seriousness as a code PR. The RDD-practicing teams in our dataset run a median of 2.3 README-review rounds before code starts. That sounds excessive until you count the review rounds on the same project's first post-launch PR — those teams have 1.4 fewer contentious PR discussions than non-RDD teams over the first 3 months.
Step 3 — Write the code to match the README
This is the smallest step. With the API surface, error cases, and usage patterns documented, the code becomes implementation rather than design. Our IDE dataset shows RDD-practicing engineers spend 34% less time in "exploratory" coding sessions (sessions with many short runs, deletions, and restarts) on new services, because the exploration happened in the README phase.
The README is the contract. Code implements the contract. The gate from step 3 to step 4 is what most teams skip — syncing the README when reality diverges.
Step 4 — Sync the README when reality diverges
Code changes during implementation, and the README must track those changes. If the snippet in the README no longer matches the working code, the README is lying. The discipline: any PR that changes public API must include README updates. This is a 1-line CI check.
Step 5 — Ship with the README as the entry point
When the service ships, the README is the first document new engineers see. The RDD-practicing teams in our dataset measure "time to first merged PR for new hire on this service" — those teams show a median of 4.2 days vs 13.1 days for teams with docs-after-code patterns. A readable README shaves 1.5 weeks off a new hire's ramp on each service they touch.
What the data shows
28 of the teams in our 100+ B2B sample practice RDD on new services (≥70% of new services launched with a reviewed README). Here's what we see in their IDE-heartbeat metrics compared to the rest:
| Metric | RDD teams (n=28) | Docs-after teams (n=67) | Delta |
|---|---|---|---|
| Rewrites in first 90 days | 1.4 | 3.6 | −61% |
| Exploratory coding time (new service) | 36 min/day | 54 min/day | −34% |
| Time-to-first-merged-PR (new hire) | 4.2 days | 13.1 days | −68% |
| Change failure rate on new services | 9.8% | 14.2% | −31% |
| PR discussions per new-service PR | 2.1 | 3.5 | −40% |
The "exploratory coding time" metric is worth a closer look. When we measured this we expected RDD to increase it — after all, thinking happens before coding — but the total thinking cost (README writing + code-exploration time combined) is lower for RDD teams. Writing structures thought in a way that IDE-fiddling doesn't.
Common mistakes
| Mistake | Why it hurts | Fix |
|---|---|---|
| README as marketing blurb | No design decisions forced | Require a usage code snippet in every README |
| README written but never reviewed | Review is where design actually happens | Treat README review as a required PR |
| README abandoned after ship | Docs rot, RDD signal lost | CI rule: public-API PRs must touch README |
| Over-detailed README ("architecture doc") | Scares off the reader | README is public-facing; architecture docs live separately |
| RDD applied to 1-day tasks | Process overhead > value | Only for services, libraries, APIs lasting ≥1 month |
The "README as architecture doc" anti-pattern is the most common. A 3000-word README is not a README; it's architecture documentation masquerading. The useful README is 500-1500 words: what, how-to-use, error modes, where-to-learn-more.
How to measure if this is working
Two numbers show whether RDD is paying off:
- Rewrites in the first 90 days of a new service — counts API-breaking changes after initial ship. Should decline vs baseline within 2 new services.
- Time to first merged PR for new hires on that service — should decline vs legacy services within 30 days of a new hire joining.
PanDev Metrics' per-project coding-time breakdown makes these measurable by service — we can see that Service A (README-first) has an average new-hire ramp of 3 days, while Service B (docs-after) has 11 days, and the product owner can act on that differential.
The checklist
- Every new service starts with a README including a usage snippet
- README is reviewed by ≥2 teammates before code starts
- README review round uses the same ceremony as a PR review
- CI enforces README updates on public-API-changing PRs
- README is ≤1500 words; architecture docs live separately
- Rewrites and new-hire ramp are tracked per service
- Teams review RDD adoption quarterly — is it sticking?
When this framework doesn't fit
RDD is overhead. For tasks under 1 engineer-week, it is not worth the ceremony. It hurts rather than helps in these cases:
- Internal tool prototypes meant to be thrown away
- Bug fixes or small refactors
- Research spikes where the discovery is the work
- Time-critical hot fixes
The contrarian point: README-driven development is not a documentation practice. It is a design practice. The artifacts (README files) are a side effect; the benefit is in the review conversation that happens before a line of code exists. Teams that adopt RDD as "a way to get better docs" will abandon it — the docs improvement alone isn't worth the friction. Teams that adopt it as "a way to find design bugs before code" stick with it, because avoided-rework is measurable in sprint velocity. Writing is cheap. Rework is expensive. RDD trades one for the other in the right direction.