Markdown for AI Agents

Every major coding agent — Claude Code, Cursor, GitHub Copilot, Codex — reads its project context from plain markdown files, not JSON, YAML, or a proprietary format. A few reasons that held up as the ecosystem grew:

• Heading-anchored chunking — agents split long context files at headings, so consistent H2/H3 structure directly improves what the model can retrieve.
• Git-diffable — plain text means context-file changes show up cleanly in code review, same as any other source file.
• No parser lock-in — a markdown file is readable by every tool a team already uses, including humans, with no proprietary schema to maintain.
• Already the docs format — most repos already have README.md and docs in markdown, so context files fit the existing convention instead of adding a new one.

If a project has both CLAUDE.md and AGENTS.md, the common pattern is to keep one canonical file and make the other a one-line pointer — e.g. CLAUDE.md containing just @AGENTS.md — rather than maintaining two copies that quietly drift apart.

A root-level context file works best as a scannable overview, not a full manual. The sections that consistently earn their place:

• Overview — one or two lines on what the project is.
• Build / test / lint commands — the exact commands, not a description of them.
• Code style & conventions — the things a linter can't enforce.
• Testing expectations — where tests live, what must pass before a change is done.
• Explicit do's and don'ts — anything the agent would otherwise get wrong by default.

Keep it near 20–30 lines. Anything longer should usually become its own linked file rather than growing the root document — content duplicated from the README doesn't help the agent, it just adds tokens to re-read every turn.

# Project Instructions

## Overview
A Next.js + TypeScript app, static export, deployed to Vercel.

## Commands
- `npm run dev` — local dev server
- `npm run build` — production build (must pass before merging)
- `npx tsc --noEmit` — type check

## Code style
- No default exports for components — named exports only.
- Tailwind for all styling; no inline style objects.

## Testing
- Playwright specs live in `/tests`. Run `npm run test:e2e` before opening a PR.

## Do not
- Do not add a backend or database — this project is client-side only.

Notice what's absent: no architecture explanation, no history of past decisions, no restated README content. Those belong in linked docs the agent can open on demand, not in the file it re-reads every session.

Once a project outgrows a single 30-line file, the common pattern isn't a longer CLAUDE.md — it's a small set of linked markdown files, each with one job:

• A root instructions file — the short overview, linking out to the rest.
• A living memory/decisions log — what was decided and why, updated as the project evolves, so the agent doesn't re-litigate settled questions.
• A feature or scope spec — what's in scope and what isn't, so new requests get checked against it instead of assumed.

This mirrors how a team keeps documentation — a short onboarding doc plus a handful of focused references — rather than one file that tries to be everything.

A context file is a living document, not a one-time setup step. Update it at natural checkpoints — after a stack decision, after a recurring correction you'd rather not repeat, after scope changes — instead of writing it once and forgetting it.

Because these are ordinary markdown files, ordinary markdown tools help maintain them: