The .md file playbook

Your AI can access specs. But access isn't the problem.

Yes, you can wire up MCP servers to Linear, Notion, or Jira. Your AI can read your tickets. The access problem is solved. But access was never the real problem.

The real problems: tickets are written for humans in sprint planning — "Add GitHub OAuth, see Figma for designs" — not for an AI that needs to know which auth library, which route structure, and which session strategy to use. When the ticket is done, it gets archived. Six months later, nobody can find why auth works the way it does. And when the spec changes mid-project, the edit history in Linear disappears.

Specs in your repo fix all of this. They're version-controlled, reviewable in PRs, and live next to the code they describe. The AI reads them with zero hops — no MCP setup, no searching for the right ticket, no hoping the ticket has enough detail. Read the full argument.

Spec in Linear vs spec in the repo

Same feature. Same AI. The difference is where the spec lives and how detailed it is.

The Linear ticket had enough context for a human in the sprint meeting. The repo spec had enough context for an AI to build it correctly on the first try.

5-minute quickstart

Two files. Five minutes. An immediate improvement to every AI interaction in your project.

Step 1: Create CLAUDE.md in your repo root

This is the file Claude Code reads first. It tells the AI your project's rules — what framework you use, how files are organized, and what to never do. Think of it as onboarding instructions for an AI teammate.

# Project conventions

## Stack
- Next.js 16 (App Router), Supabase, Tailwind CSS v4

## Rules
- Server Components by default. Only 'use client' for interactivity.
- Server Actions for mutations, not Route Handlers.

## File structure
- Pages: src/app/[route]/page.tsx
- Components: src/components/[feature]/[component].tsx

## Don'ts
- Never use localStorage for auth tokens
- Never add 'use client' to a layout

Step 2: Create your first spec

Pick the next feature you're about to build. Before you start prompting, write a short markdown file describing what you want. Put it in a specs/ folder. Then point the AI at it instead of typing a long prompt.

# Auth: GitHub OAuth Login

## Context
We need GitHub OAuth so users can connect their repos.

## Requirements
- Sign in with GitHub button on /login
- Callback handler at /auth/callback
- Session stored in httpOnly cookies (not localStorage)
- Redirect to dashboard after auth

## Non-goals
- Email/password auth (not needed for v1)
- Multiple OAuth providers

## Open questions
- Do we need to request repo:write scope?

Now instead of a 5-paragraph prompt, you say: claude "Build what's in specs/auth-prd.md". The AI reads the spec, reads your CLAUDE.md conventions, and generates code that matches both.

The complete file toolkit

You don't need all of these on day one. CLAUDE.md and specs are the essentials. Add the others as your project grows.

CLAUDE.md in depth

A file in your repo root that Claude Code reads before generating any code. Every major AI coding tool supports a version of this — the file name differs but the concept is the same.

How to build it over time

Start with the basics from the quickstart. Then, every time the AI generates code that violates a convention, add a rule. Over weeks, your CLAUDE.md becomes a comprehensive guide that prevents the AI from repeating mistakes.

The "Don'ts" section is the most valuable part. AI tools are eager to help and will reach for common patterns even when they're wrong for your project. Explicit "never do X" rules are more effective than "prefer Y" suggestions.

# Project conventions

## Stack
- Next.js 16 (App Router)
- Supabase (auth + database)
- Tailwind CSS v4
- TypeScript (strict mode)

## Rules
- Server Components by default. Only 'use client' for interactivity.
- Server Actions for mutations, not Route Handlers.
- All request APIs are async: await cookies(), await headers()
- Use @neondatabase/serverless for Postgres, not @vercel/postgres

## File structure
- Pages: src/app/[route]/page.tsx
- Components: src/components/[feature]/[component].tsx
- Utilities: src/lib/[name].ts
- Specs: specs/[feature].md

## Don'ts
- Never use localStorage for auth tokens
- Never add 'use client' to a layout
- Never use default exports for components (named exports only)
- Never install a package without checking if we already have an equivalent

## Testing
- Integration tests hit real database, not mocks
- Test files live next to the code they test: foo.test.ts

## Before building a feature
- Read the relevant spec in specs/ first
- Check for existing components in src/components/ui/ before creating new ones

Instruction files across tools

Every major AI tool has its own instruction file. You don't need to maintain five copies — start with CLAUDE.md, then create minimal equivalents for other tools that say "Read CLAUDE.md for full conventions."

Specs — the most important file you're not writing

What a good spec contains

• Context — Why does this feature exist? What problem does it solve?
• Requirements — What must it do? Be specific enough that an AI could build it from this alone.
• Non-goals — What is explicitly out of scope? This prevents AI tools from over-engineering.
• Open questions— What's unresolved? This signals where judgment is needed.
• Constraints — Are there technical or business constraints?

When to write one: Before any feature that would take more than ~2 hours to build. If you're about to spend 30 minutes explaining the feature to an AI in a chat window, that time is better spent writing a spec file.

MEMORY.md — your AI gets smarter over time

What gets saved

• User memories: "Senior engineer, deep Go experience, new to React" → The AI tailors explanations accordingly
• Feedback memories: "Integration tests must hit real DB, not mocks" → The AI never generates mock-based tests again
• Project memories: "Merge freeze after March 5" → The AI flags non-critical PRs near that date
• Reference memories: "Pipeline bugs tracked in Linear project INGEST" → The AI knows where to look

- [User role](user_role.md) — Senior eng, deep Go experience, new to React
- [Testing preference](feedback_testing.md) — Integration tests must hit real DB, not mocks
- [Merge freeze](project_merge_freeze.md) — No non-critical merges after 2026-03-05
- [Linear tracking](reference_linear.md) — Pipeline bugs tracked in Linear project "INGEST"

---
name: Real database in tests
description: Never mock the database in integration tests
type: feedback
---

Integration tests must hit a real database, not mocks.

**Why:** Prior incident where mock/prod divergence masked a broken migration.
**How to apply:** Any test file that touches data persistence
should use the test database, not jest.mock().

ADRs — why you chose X over Y

# ADR-003: Use Supabase Auth over NextAuth

## Status
Accepted

## Context
We need authentication with GitHub OAuth.
NextAuth and Supabase Auth both support this.

## Decision
Supabase Auth. We already use Supabase for the database,
and having auth + data in one service reduces complexity.

## Consequences
- Vendor lock-in to Supabase for auth
- Simpler session management (Supabase handles refresh)
- One fewer dependency

README.md — the front door

Runbooks — when things break at 2am

# Rollback a production deploy

## When to use
Production deploy caused errors. Need to revert.

## Steps
1. Go to Vercel dashboard → Deployments
2. Find the last known good deployment
3. Click ••• → Promote to Production
4. Verify the rollback in production
5. Post in #engineering Slack channel

## Escalation
If rollback doesn't fix it, page the on-call engineer.

Retros — so you never fight the same bug twice

# Retro: Draft content data loss on publish

## What happened
Users reported that publishing a draft would sometimes
overwrite the document with an empty string.

## Timeline
- Mar 28: First report from user. Could not reproduce.
- Mar 29: Found race condition between Yjs auto-save
  and the publish endpoint. Both writing to content column.
- Mar 30: Fix deployed. Added snapshot guard.

## What we tried
1. Debouncing the auto-save → didn't help, race window
   was between auto-save and the publish API call
2. Locking the row during publish → deadlocked with
   the PartyKit sync writing yjs_state
3. Snapshot comparison before write → THIS WORKED.
   Save a snapshot before publish, compare after,
   reject if content changed during the window.

## Root cause
The publish endpoint read content, transformed it, and
wrote it back. But between the read and write, Yjs
auto-save could overwrite content with a stale buffer.

## Prevention
- Added snapshot guard to all content write paths
- Added integration test that simulates concurrent writes
- Added CLAUDE.md rule: never write to content column
  without checking the snapshot guard

CHANGELOG.md — a history that helps

Writing tips

How to write docs that AI tools actually use.

• Write for the scanner. Headers, bullet points, code blocks. Nobody reads walls of text — and neither does AI. Clear structure = better AI output.
• Be specific, not vague. "Use Supabase Auth with GitHub OAuth" is useful. "Use appropriate authentication" is not. AI tools need concrete details to generate correct code.
• Name files after the feature, not the ticket. auth-prd.md is findable and meaningful forever. AUTH-234.md means nothing after the sprint ends.
• Keep files short.A 200-line spec is a spec nobody reads — including AI. If it's over ~100 lines, split it up.
• Update or delete. A wrong doc is worse than no doc. If a spec no longer reflects reality, update it in the same PR that changed the code.
• Use frontmatter for status. A status: draft | active | deprecated field tells both readers and AI whether to trust the document.
• Link between docs. Reference your ADRs from your specs. Reference your specs from CLAUDE.md. The web of connections makes every doc more powerful.

Naming & folder structure

Here's where everything goes.

├── CLAUDE.md              # AI conventions & guardrails (start here!)
├── README.md              # Project overview
├── CHANGELOG.md           # Release history
├── .claude/
│   └── memory/            # AI memory (auto-managed, don't edit manually)
│       ├── MEMORY.md      # Memory index
│       ├── user_role.md
│       └── feedback_*.md
├── specs/                 # Feature specs & PRDs
│   ├── auth-prd.md
│   ├── notifications.md
│   └── search-v2.md
├── docs/
│   ├── adr/               # Architecture decisions
│   │   ├── 001-nextjs.md
│   │   ├── 002-supabase.md
│   │   └── 003-redis.md
│   └── runbooks/          # Operational procedures
│       ├── deploy-rollback.md
│       └── incident-response.md
├── retro/                 # Post-incident retros & lessons learned
│   ├── 2026-03-30-data-loss.md
│   └── 2026-02-15-auth-outage.md
└── src/                   # Application code

AI tools that read your repo

This isn't specific to one tool. Every major AI coding tool benefits from structured docs in the repo.

• Claude Code — Reads CLAUDE.md automatically on every interaction. References specs, ADRs, and any file you point it at. Maintains MEMORY.md across sessions. The most repo-aware AI tool.
• Cursor — Indexes all project files including markdown. Uses them for autocomplete context and chat responses. Supports .cursorrules for project-specific instructions.
• GitHub Copilot — Uses repo context for inline suggestions. Benefits from well-structured README and specs.
• Windsurf — Reads project markdown files for context. Supports .windsurfrules for instruction files.
• Codex — Uses repo files as context for code generation. Reads AGENTS.md for project-level instructions. Specs give it the clearest signal of intent.

Getting started checklist