verso.md

The case for .md files in your repo

How markdown
superpowers AI.

Scroll to see why specs in the repo change everything.

↓

The problem

AI reads your repo.
It can't read your Notion.

What AI sees

Two repos. Same code. Different results.

repo-without-specs/

src/

app/

lib/

components/

package.json

tsconfig.json

AI knows: what exists

AI doesn't know: why, what's next, or how

repo-with-specs/

src/

app/

lib/

components/

CLAUDE.md

docs/auth-prd.md

docs/adr-007-redis.md

help/sso-setup.md

package.json

AI knows: what, why, how, what's next, and what not to do

The result

$ claude "Build what's in docs/auth-prd.md"

That's the entire prompt.

What changes

The spec is the prompt.

No copy-pasting from Linear into a chat window. No describing the context. The AI reads the file directly.

Before

Build a login page. We use Supabase for auth with GitHub OAuth. The callback URL is /auth/callback. Sessions use cookies, not localStorage. Put it in src/app/login/page.tsx. Use the existing Button component from src/components/ui/button.tsx. Follow the same patterns as...

After

Build what's in docs/auth-prd.md

What each file does for AI

CLAUDE.md
Conventions. Patterns. What never to do.
AI follows your rules instead of guessing.
docs/auth-prd.md
The spec. What to build and why.
AI writes code that matches the plan.
docs/adr-007.md
Why you chose Redis over Kafka.
AI won't suggest Kafka.
help/sso-setup.md
How the feature works for users.
AI keeps help docs accurate when code changes.
AGENTS.md
How AI should work in this repo.
Every agent follows the same playbook.

AI output comparison

Same prompt. Different repo.

No specs

Creating /pages/login.js...

Using localStorage for sessions...

No auth library detected.

Guessing route structure...

2 of 3 files won't compile.

With specs

Reading auth-prd.md ✓

Reading CLAUDE.md ✓

Using Supabase Auth + GitHub OAuth

Route: /app/login/page.tsx

4 files. All compile. All match spec.

The loop

Specs and code evolve together.
AI keeps both in sync.

01Write the spec in .md
02AI reads it, generates code
03Code and spec ship in the same PR
04Spec stays accurate. AI stays grounded.

Pull Request #142

+src/app/login/page.tsx
+src/lib/auth/oauth.ts
~docs/auth-prd.mdupdated
+tests/auth.test.ts

Atomic

Spec, code, tests.
One PR.

The reviewer sees the full picture. The spec updates with the code. Not in a separate tool, days later, if someone remembers.

Longevity

Specs outlive
the sprint.

Tickets get archived. The spec that described whyyou built something disappears into the backlog. In the repo, it's there forever.

Linear

AUTH-234 Closed

AUTH-189 Archived

AUTH-167 Done

Where's the spec?

Repo

auth-prd.md

updated 3d ago

47 commits

git blame works

Who benefits

One .md file. Many readers.

Claude Code

Generates code from specs

Cursor

Autocomplete with full context

Copilot

Suggestions that match your patterns

Your PM

Edits specs, opens PRs directly

New engineers

Onboard from the repo, not Notion

Support

Help docs that reference real code

CI agents

Validate code against specs

Future you

Understands why decisions were made

The best thing you can do
for your AI tools is write
great docs and keep them
in the repo.

verso.md makes this effortless.

Get started free

Free 14-day trial on all plans.