Markdown for AI Agents

AGENTS.md and context files that control AI coding behavior

AI Agents Read Markdown

Every major AI coding tool — Claude Code, GitHub Copilot, Cursor, Windsurf — reads Markdown files for project context. These files tell the agent what to build, how the project works, and what rules to follow.

The concept is simple: instead of explaining your project in every prompt, you write the instructions once in a Markdown file. The agent reads it automatically.

Context Files by Tool

Tool Context file Location
Claude Code CLAUDE.md Project root
Cross-agent AGENTS.md Project root
GitHub Copilot copilot-instructions.md .github/
Cursor .cursorrules Project root
Windsurf .windsurfrules Project root
All agents README.md Project root

All of these are Markdown files (or Markdown-like). The content structure is similar across tools.

What Goes in AGENTS.md

AGENTS.md is the cross-tool convention. Any AI agent that recognizes it will follow the instructions. A well-structured AGENTS.md covers:

AGENTS.md # Agent Instructions ## Project Overview E-commerce API built with Node.js, Express, PostgreSQL. ## Commands - `npm run dev` — start with hot reload - `npm test` — run Jest tests - `npm run migrate` — run database migrations ## Architecture - `src/routes/` — Express route handlers - `src/services/` — business logic - `src/models/` — Sequelize models - `src/middleware/` — auth, validation, error handling ## Conventions - TypeScript strict mode - Functional style — no classes except models - Error handling: throw AppError, not generic Error - All endpoints need integration tests ## Constraints - Never expose internal IDs in API responses (use UUIDs) - Rate limiting on all public endpoints - No raw SQL — use Sequelize query builder

Directory-Specific Context

Large projects can have AGENTS.md files in subdirectories for module-specific instructions:

  • ./AGENTS.md — global project instructions
  • ./frontend/AGENTS.md — React conventions, component patterns
  • ./backend/AGENTS.md — API conventions, database patterns
  • ./infra/AGENTS.md — Terraform conventions, deploy process

When an agent works in ./frontend/, it reads both the root AGENTS.md and the frontend-specific one.

Why Markdown for Agent Context?

  • Token-efficient — Markdown uses fewer tokens than JSON or XML for structured text
  • Human-editable — developers can read and write it without tools
  • Git-friendly — clean diffs in pull requests
  • Structured enough — headings, lists, and code blocks provide semantic structure
  • Universal — every AI model understands Markdown from training data

For the full reasoning, see Why AI Tools Use Markdown.

Writing Tips

  • Keep it short — every line uses context window space. 200 lines is plenty.
  • Commands over descriptions — “Run npm test -- --watch” beats “We use Jest with watch mode for development testing”
  • State constraints as rules — “Never use any type” is clearer than “We prefer strong typing”
  • Link, don’t duplicate — “See docs/auth.md for auth details” keeps the context file lean
  • Review in PRs — treat AGENTS.md changes like code changes

Multi-Agent Workflows

Modern development often involves multiple AI agents working together — one writing code, one reviewing, one running tests. AGENTS.md gives all of them the same baseline context:

  • The coding agent knows which patterns to follow
  • The review agent knows which constraints to check
  • The testing agent knows which commands to run

Without a shared context file, each agent would need separate instructions in every prompt.

Related Guides

View Agent Context Files with MDViewer

MDViewer renders AGENTS.md, CLAUDE.md, and all Markdown files with full formatting. See your agent instructions as the agents see them.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.