When new devs join a project, someone walks them through the conventions - where things live, what the house rules are, which commands to run. AI agents get none of that. Every session starts context-blind, and an agent that finds no instructions doesnt ask - it guesses. Recent surveys say that most engineers now use 2-4 AI tools at once. If you have more than a couple of devs, you effectively have a multi-agent repo whether you planned it or not. So the question isnt whether to write onboarding docs for agents - its which ones, because they read different files.
Tier 1 — mandatory.
Two files:
AGENTS.md — the cross-tool standard, Linux Foundation-hosted since Dec 2025, read natively by Codex, Copilot's coding agent, Cursor, Windsurf and roughly two dozen other tools. Content: stack, commands, hard rules, pointers to deeper docs. Keep it under ~200 lines.
CLAUDE.md — exists solely because Claude Code (the most-used agent in recent surveys) is the one major tool that doesn't read AGENTS.md. Anthropic's own recommended bridge: first line '@AGENTS.md' (Claude Code expands the import at session start), with Claude-specific notes below. So the mandatory setup is two files, and one is a pointer.
