# AGENTS.md (File Convention) AGENTS.md is a file convention for providing instructions and guidelines to AI coding agents. The file is typically placed at the root of a repository and contains context, rules, and preferences that AI assistants should follow when working with the codebase. ## Purpose The AGENTS.md file serves as a persistent memory and instruction set for AI agents, ensuring consistent behavior across sessions. It solves the problem of having to repeatedly explain project conventions, coding styles, and preferences to AI assistants. ## Common Contents ### Project Context - Overview of the project - Architecture decisions - Technology stack - Important constraints ### Coding Guidelines - Code style preferences - Naming conventions - File organization rules - Testing requirements ### Workflow Instructions - How to handle commits - PR conventions - Branch naming - Review processes ### Safety Rules - Files or directories to avoid modifying - Destructive operations that require confirmation - External actions that need approval ## Usage Pattern As suggested by David Heinemeier Hansson in [[37signals AI Recommendations (2026-01)]]: > "Agents take revisions and direction very well. Then ask it to commit those style guidelines to the AGENTS.md file." This creates a feedback loop where AI agents learn and codify project preferences over time. ## Adoption The convention has been adopted by various AI coding tools: - [[OpenAI Codex]] - Cursor - GitHub Copilot Workspace - [[Claude Code]], late: only since v2.1.277 (2026-09-18), and only as a fallback. It reads `AGENTS.md` when no `CLAUDE.md` exists, and you can edit it under "Project instructions" in `/config` (not on Bedrock, Vertex or Foundry) - Other AI-powered development environments ## The Claude Code holdout Anthropic held out for a long time. `CLAUDE.md` came first, and Anthropic's line was that model families aren't interchangeable: the system prompt around the instructions changes how well they're followed. The pressure built anyway. [[Shopify]]'s CEO threatened to ban Claude Code internally until it supported `AGENTS.md` and the `.agents/skills` folder. When support finally shipped, the changelog entry hit 737 points on [[Hacker News]]. Notable points from the thread: - Many saw the delay as deliberate lock-in. Some had already switched to Codex or Qwen, and one person canceled their subscription over it - Others called it a mild inconvenience: `ln -s AGENTS.md CLAUDE.md` solved it all along - Some reported that Claude Code wraps instructions in a note saying they may not be relevant, while Codex follows `AGENTS.md` more literally - swyx argued that standardizing too early has a cost, since model-specific tuning still matters My take: the symlink crowd is right on mechanics, and the lock-in crowd is right on signal. A one-line fallback that took this long tells you how Anthropic weighs ecosystem control against user convenience. In my own vault, `CLAUDE.md` just points to `AGENTS.md`, which keeps every agent on the same instructions. ## Example Structure ```markdown # AGENTS.md ## Project Overview Brief description of the project... ## Rules - Always run tests before committing - Use conventional commits - Never modify files in /config without asking ## Code Style - Use TypeScript strict mode - Prefer functional patterns - Maximum line length: 100 characters ## Workflow - Create feature branches from main - Squash commits on merge ``` ## References - Claude Code changelog (v2.1.277): https://code.claude.com/docs/en/changelog - Hacker News discussion: https://news.ycombinator.com/item?id=49760187 ## Related - [[AI Agents]] - [[Claude Code]] - [[Claude Code Memory]] - [[OpenAI Codex]] - [[37signals AI Recommendations (2026-01)]]