{"id":206,"date":"2026-10-16T13:03:49","date_gmt":"2026-10-16T13:03:49","guid":{"rendered":"https:\/\/devdojo.co.in\/?p=206"},"modified":"2026-10-16T13:03:50","modified_gmt":"2026-10-16T13:03:50","slug":"agents-md-guide","status":"publish","type":"post","link":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/","title":{"rendered":"AGENTS.md Guide: How to Write Instructions for AI Coding Agents"},"content":{"rendered":"\n<div class=\"dd-post\">\n<style>\n.single article:has(.dd-hero) .entry-media{display:none}\n.dd-post{--dd-navy:#0b1020;--dd-blue:#3178c6;--dd-violet:#7c5cff;--dd-ink:#1d2333;--dd-muted:#5b6478;line-height:1.75;color:var(--dd-ink)}\n.dd-post h2{margin:2.2em 0 .6em;font-size:1.6em;line-height:1.3;scroll-margin-top:90px}\n.dd-post h3{margin:1.6em 0 .5em;font-size:1.25em;scroll-margin-top:90px}\n.dd-post a{color:var(--dd-blue)}\n.dd-post .dd-hero{margin:0 0 28px;border-radius:16px;overflow:hidden;box-shadow:0 10px 30px rgba(11,16,32,.25)}\n.dd-post .dd-hero svg{display:block;width:100%;height:auto}\n.dd-post .dd-hero .node rect{transition:stroke .25s,fill .25s}\n.dd-post .dd-hero .node:hover rect{stroke:#7c5cff;fill:#232a5c}\n.dd-post .dd-hero .node:hover text{fill:#ffffff}\n.dd-post pre{background:#0f1430;color:#e6e9f5;padding:18px 20px;border-radius:12px;overflow-x:auto;line-height:1.6;margin:1.2em 0;border:1px solid #232a52;font-size:14.5px !important}\n.dd-post pre code{font-family:\"JetBrains Mono\",Consolas,Menlo,monospace;background:none;color:inherit;padding:0;font-size:1em !important;white-space:pre}\n.dd-post :not(pre)>code{background:#eef1fb;color:#3a2fa0;padding:2px 6px;border-radius:5px;font-size:.92em}\n.dd-post .dd-label{display:inline-block;font-size:12px;font-weight:700;letter-spacing:.04em;text-transform:uppercase;color:#7c5cff;margin-bottom:-6px}\n.dd-post .dd-summary{background:linear-gradient(135deg,#f3f0ff,#eaf3ff);border:1px solid #d9d2ff;border-left:5px solid var(--dd-violet);border-radius:12px;padding:18px 22px;margin:0 0 24px}\n.dd-post .dd-summary h2{margin:0 0 8px;font-size:1.2em}\n.dd-post .dd-summary ul{margin:0;padding-left:20px}\n.dd-post .dd-toc{background:#f7f8fc;border:1px solid #e3e6f0;border-radius:12px;padding:16px 22px;margin:0 0 28px}\n.dd-post .dd-toc strong{display:block;margin-bottom:6px}\n.dd-post .dd-toc ol{margin:0;padding-left:20px;columns:2;column-gap:28px}\n.dd-post .dd-toc li{break-inside:avoid;margin:3px 0}\n.dd-post .dd-tip,.dd-post .dd-note{border-radius:10px;padding:14px 18px;margin:1.2em 0}\n.dd-post .dd-tip{background:#ecfdf3;border-left:5px solid #16a34a}\n.dd-post .dd-note{background:#fff8e6;border-left:5px solid #f59e0b}\n.dd-post .dd-cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:14px;margin:1.2em 0}\n.dd-post .dd-card{background:#fff;border:1px solid #e3e6f0;border-radius:12px;padding:16px;box-shadow:0 2px 8px rgba(20,30,60,.05)}\n.dd-post .dd-card h4{margin:0 0 6px;font-size:1.02em;color:#3178c6}\n.dd-post .dd-card p{margin:0;font-size:.95em;color:var(--dd-muted)}\n.dd-post table{width:100%;border-collapse:collapse;margin:1.2em 0;font-size:.95em}\n.dd-post th,.dd-post td{border:1px solid #e3e6f0;padding:10px 12px;text-align:left;vertical-align:top}\n.dd-post th{background:#151b3b;color:#fff}\n.dd-post tr:nth-child(even) td{background:#f7f8fc}\n.dd-post .dd-table-wrap{overflow-x:auto}\n.dd-post figure{margin:1.6em 0;text-align:center}\n.dd-post figure svg{width:100%;height:auto;border-radius:12px}\n.dd-post figcaption{font-size:.9em;color:var(--dd-muted);margin-top:8px}\n.dd-post .dd-tabs{margin:1.4em 0;border:1px solid #e3e6f0;border-radius:12px;overflow:hidden}\n.dd-post .dd-tabs input{position:absolute;opacity:0;pointer-events:none}\n.dd-post .dd-tabs .dd-tab-labels{display:flex;flex-wrap:wrap;background:#151b3b}\n.dd-post .dd-tabs label{cursor:pointer;padding:12px 18px;color:#aab3d6;font-weight:600;font-size:.95em;border-bottom:3px solid transparent}\n.dd-post .dd-tabs label:hover{color:#fff}\n.dd-post .dd-tabs .dd-panel{display:none;padding:4px 18px 10px}\n.dd-post #dd-t1:checked~.dd-tab-labels label[for=dd-t1],.dd-post #dd-t2:checked~.dd-tab-labels label[for=dd-t2],.dd-post #dd-t3:checked~.dd-tab-labels label[for=dd-t3]{color:#fff;border-bottom-color:#7c5cff;background:#232a5c}\n.dd-post #dd-t1:checked~.dd-p1,.dd-post #dd-t2:checked~.dd-p2,.dd-post #dd-t3:checked~.dd-p3{display:block}\n.dd-post details{border:1px solid #e3e6f0;border-radius:10px;padding:12px 16px;margin:10px 0;background:#fff}\n.dd-post details summary{cursor:pointer;font-weight:600}\n.dd-post details[open] summary{color:#3178c6;margin-bottom:6px}\n.dd-post .dd-cta{background:linear-gradient(135deg,#0b1020,#151b3b);color:#e6e9f5;border-radius:16px;padding:26px 28px;margin:2em 0 1em;text-align:center}\n.dd-post .dd-cta h3{color:#fff;margin:0 0 8px}\n.dd-post .dd-cta p{margin:0 0 6px}\n.dd-post .dd-cta a{color:#9db8ff}\n@media(max-width:640px){.dd-post .dd-toc ol{columns:1}.dd-post pre{padding:14px}}\n<\/style>\n\n<div class=\"dd-hero\">\n<svg viewBox=\"0 0 1200 520\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\" role=\"img\" aria-label=\"AGENTS.md guide banner: one instructions file read by many AI coding agents\">\n<defs>\n<linearGradient id=\"ddbg\" x1=\"0\" y1=\"0\" x2=\"1\" y2=\"1\"><stop offset=\"0\" stop-color=\"#0b1020\"\/><stop offset=\"1\" stop-color=\"#151b3b\"\/><\/linearGradient>\n<linearGradient id=\"ddac\" x1=\"0\" y1=\"0\" x2=\"1\" y2=\"0\"><stop offset=\"0\" stop-color=\"#3178c6\"\/><stop offset=\"1\" stop-color=\"#7c5cff\"\/><\/linearGradient>\n<radialGradient id=\"ddglow\" cx=\"0.5\" cy=\"0.5\" r=\"0.5\"><stop offset=\"0\" stop-color=\"#7c5cff\" stop-opacity=\".45\"\/><stop offset=\"1\" stop-color=\"#7c5cff\" stop-opacity=\"0\"\/><\/radialGradient>\n<\/defs>\n<rect x=\"0\" y=\"-60\" width=\"1200\" height=\"640\" fill=\"url(#ddbg)\"\/>\n<g opacity=\".08\" stroke=\"#ffffff\">\n<path d=\"M0 60H1200M0 140H1200M0 220H1200M0 300H1200M0 380H1200M0 460H1200\"\/>\n<path d=\"M100 -60V580M250 -60V580M400 -60V580M550 -60V580M700 -60V580M850 -60V580M1000 -60V580M1150 -60V580\"\/>\n<\/g>\n<circle cx=\"880\" cy=\"270\" r=\"230\" fill=\"url(#ddglow)\"\/>\n<text x=\"70\" y=\"120\" fill=\"#9db8ff\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"22\" font-weight=\"600\" letter-spacing=\"3\">DEVDOJO \u00b7 AI CODING AGENTS<\/text>\n<text x=\"70\" y=\"200\" fill=\"#ffffff\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"64\" font-weight=\"800\">AGENTS.md<\/text>\n<text x=\"70\" y=\"262\" fill=\"#ffffff\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"40\" font-weight=\"700\">The README for AI<\/text>\n<text x=\"70\" y=\"310\" fill=\"#ffffff\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"40\" font-weight=\"700\">Coding Agents<\/text>\n<rect x=\"70\" y=\"336\" width=\"190\" height=\"6\" rx=\"3\" fill=\"url(#ddac)\"\/>\n<text x=\"70\" y=\"390\" fill=\"#c4cbe8\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"22\">One file. Every agent. Better code on the first try.<\/text>\n<text x=\"70\" y=\"424\" fill=\"#8b94bb\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\">Codex \u00b7 Cursor \u00b7 Copilot \u00b7 Gemini CLI \u00b7 Jules \u00b7 and more<\/text>\n<g id=\"ddlines\" stroke=\"#3a4380\" stroke-width=\"2\" fill=\"none\">\n<path id=\"ddp1\" d=\"M880 270 L740 140\"\/>\n<path id=\"ddp2\" d=\"M880 270 L1040 140\"\/>\n<path id=\"ddp3\" d=\"M880 270 L740 400\"\/>\n<path id=\"ddp4\" d=\"M880 270 L1040 400\"\/>\n<\/g>\n<circle r=\"6\" fill=\"#7c5cff\"><animateMotion dur=\"2.6s\" repeatCount=\"indefinite\"><mpath href=\"#ddp1\"\/><\/animateMotion><\/circle>\n<circle r=\"6\" fill=\"#3178c6\"><animateMotion dur=\"3.1s\" repeatCount=\"indefinite\"><mpath href=\"#ddp2\"\/><\/animateMotion><\/circle>\n<circle r=\"6\" fill=\"#7c5cff\"><animateMotion dur=\"2.9s\" repeatCount=\"indefinite\"><mpath href=\"#ddp3\"\/><\/animateMotion><\/circle>\n<circle r=\"6\" fill=\"#3178c6\"><animateMotion dur=\"3.4s\" repeatCount=\"indefinite\"><mpath href=\"#ddp4\"\/><\/animateMotion><\/circle>\n<g class=\"node\"><rect x=\"800\" y=\"230\" width=\"160\" height=\"80\" rx=\"14\" fill=\"#1b2150\" stroke=\"url(#ddac)\" stroke-width=\"3\"\/><text x=\"880\" y=\"268\" text-anchor=\"middle\" fill=\"#fff\" font-family=\"Consolas,monospace\" font-size=\"20\" font-weight=\"700\">AGENTS.md<\/text><text x=\"880\" y=\"292\" text-anchor=\"middle\" fill=\"#9db8ff\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"14\">repo root<\/text><\/g>\n<g class=\"node\"><rect x=\"670\" y=\"105\" width=\"140\" height=\"56\" rx=\"12\" fill=\"#151b3b\" stroke=\"#3178c6\" stroke-width=\"2\"\/><text x=\"740\" y=\"139\" text-anchor=\"middle\" fill=\"#c4cbe8\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\">Codex<\/text><\/g>\n<g class=\"node\"><rect x=\"970\" y=\"105\" width=\"140\" height=\"56\" rx=\"12\" fill=\"#151b3b\" stroke=\"#3178c6\" stroke-width=\"2\"\/><text x=\"1040\" y=\"139\" text-anchor=\"middle\" fill=\"#c4cbe8\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\">Cursor<\/text><\/g>\n<g class=\"node\"><rect x=\"670\" y=\"372\" width=\"140\" height=\"56\" rx=\"12\" fill=\"#151b3b\" stroke=\"#3178c6\" stroke-width=\"2\"\/><text x=\"740\" y=\"406\" text-anchor=\"middle\" fill=\"#c4cbe8\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\">Copilot<\/text><\/g>\n<g class=\"node\"><rect x=\"970\" y=\"372\" width=\"140\" height=\"56\" rx=\"12\" fill=\"#151b3b\" stroke=\"#3178c6\" stroke-width=\"2\"\/><text x=\"1040\" y=\"406\" text-anchor=\"middle\" fill=\"#c4cbe8\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\">Gemini CLI<\/text><\/g>\n<\/svg>\n<\/div>\n\n<div class=\"dd-summary\">\n<h2>Quick Summary<\/h2>\n<ul>\n<li><strong>AGENTS.md<\/strong> is a plain Markdown file in your repo that tells AI coding agents how to set up, build, test and style your project.<\/li>\n<li>It is an open standard, now looked after by the Agentic AI Foundation (part of the Linux Foundation), and is used by more than 60,000 open-source projects.<\/li>\n<li>Codex, Cursor, GitHub Copilot&#8217;s coding agent, Gemini CLI, Jules, Aider, Zed, Windsurf and many more read it. Claude Code uses <code>CLAUDE.md<\/code>, but can import AGENTS.md in one line.<\/li>\n<li>In big repos you can add one AGENTS.md per folder. The <strong>closest file to the code being edited wins<\/strong>, and your chat message overrides everything.<\/li>\n<li>Keep it short, specific and command-focused: exact commands, hard rules and a &#8220;definition of done&#8221; beat long essays.<\/li>\n<\/ul>\n<\/div>\n\n<nav class=\"dd-toc\" aria-label=\"Table of contents\">\n<strong>In this guide<\/strong>\n<ol>\n<li><a href=\"#what-is-agents-md\">What is AGENTS.md?<\/a><\/li>\n<li><a href=\"#why-it-matters\">Why it matters now<\/a><\/li>\n<li><a href=\"#how-agents-read-it\">How agents find and read it<\/a><\/li>\n<li><a href=\"#first-agents-md\">Write your first AGENTS.md<\/a><\/li>\n<li><a href=\"#examples-by-stack\">Examples for different stacks<\/a><\/li>\n<li><a href=\"#monorepos\">Nested files for monorepos<\/a><\/li>\n<li><a href=\"#tool-setup\">Making every tool read it<\/a><\/li>\n<li><a href=\"#check-script\">Check your file with a script<\/a><\/li>\n<li><a href=\"#errors\">Common mistakes and fixes<\/a><\/li>\n<li><a href=\"#best-practices\">Best practices<\/a><\/li>\n<li><a href=\"#faq\">FAQ<\/a><\/li>\n<li><a href=\"#conclusion\">Conclusion<\/a><\/li>\n<\/ol>\n<\/nav>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<p>If you use an AI coding agent like Codex, Cursor or GitHub Copilot, you have probably seen this happen: the agent writes decent code, but it runs <code>npm<\/code> when your project uses <code>pnpm<\/code>, puts files in the wrong folder, or forgets to run the tests. The fix is not a smarter model. The fix is <strong>AGENTS.md<\/strong> \u2014 a small Markdown file that gives every agent the same clear instructions about your project, every single time.<\/p>\n<p>In this guide you will learn what AGENTS.md is, how agents read it, and how to write a good one with copy-paste examples for Node.js, Python and monorepos. We will also cover how to make tools that use other file names (like Claude Code) share the same file, plus a small script to keep your AGENTS.md healthy.<\/p>\n\n<h2 id=\"what-is-agents-md\">What is AGENTS.md?<\/h2>\n<p>AGENTS.md is a simple, open format for guiding coding agents. Think of it as <strong>a README written for AI agents instead of humans<\/strong>. Your normal <code>README.md<\/code> explains the project to people: what it does, screenshots, how to contribute. AGENTS.md holds the extra, detailed context an agent needs to work safely in your code: exact setup commands, test commands, code style rules, folder layout and things it must never do.<\/p>\n<p>There is no special syntax and no required fields. It is plain Markdown, and you can use any headings you like. The agent simply reads the text and follows it. According to the official site at <a href=\"https:\/\/agents.md\/\" target=\"_blank\" rel=\"noopener\">agents.md<\/a>, popular sections include:<\/p>\n<div class=\"dd-cards\">\n<div class=\"dd-card\"><h4>Project overview<\/h4><p>What the project is, the main tech stack, and where the important code lives.<\/p><\/div>\n<div class=\"dd-card\"><h4>Build and test commands<\/h4><p>The exact commands to install, run, lint and test. This is the most valuable section.<\/p><\/div>\n<div class=\"dd-card\"><h4>Code style<\/h4><p>Language settings, naming, formatting and patterns you prefer or avoid.<\/p><\/div>\n<div class=\"dd-card\"><h4>Testing instructions<\/h4><p>How to run one test, where tests live, and when new tests are expected.<\/p><\/div>\n<div class=\"dd-card\"><h4>Security notes<\/h4><p>Secrets, risky folders, and actions the agent must never take.<\/p><\/div>\n<div class=\"dd-card\"><h4>PR and commit rules<\/h4><p>Title format, commit style and checks to run before finishing.<\/p><\/div>\n<\/div>\n\n<h2 id=\"why-it-matters\">Why AGENTS.md matters now<\/h2>\n<p>A year or two ago, every tool had its own instructions file: <code>.cursorrules<\/code> for Cursor, <code>.github\/copilot-instructions.md<\/code> for Copilot, <code>GEMINI.md<\/code> for Gemini CLI, and so on. Teams that used more than one tool had to copy the same rules into several files and keep them in sync. That got messy fast.<\/p>\n<p>AGENTS.md came out of joint work between OpenAI Codex, Amp, Google&#8217;s Jules, Cursor and Factory, and was released in August 2025. In December 2025, OpenAI, Anthropic and Block launched the <strong>Agentic AI Foundation (AAIF)<\/strong> under the Linux Foundation, with support from Google, Microsoft, AWS, Bloomberg and Cloudflare. AGENTS.md became one of its three founding projects, next to Anthropic&#8217;s Model Context Protocol (MCP) and Block&#8217;s goose. You can read the announcement on <a href=\"https:\/\/openai.com\/index\/agentic-ai-foundation\/\" target=\"_blank\" rel=\"noopener\">OpenAI&#8217;s blog<\/a>.<\/p>\n<p>That neutral home matters. It means AGENTS.md is not tied to one company, and you can write your project instructions once and expect most agents to understand them. If you have already played with MCP in our guide on <a href=\"https:\/\/devdojo.co.in\/build-mcp-server-typescript\/\">building an MCP server in TypeScript<\/a>, AGENTS.md is the other half of the picture: MCP gives agents <em>tools<\/em>, and AGENTS.md gives them <em>context<\/em>.<\/p>\n<div class=\"dd-note\"><strong>Note:<\/strong> Writing a good AGENTS.md is quickly becoming a normal developer skill, like writing a good README or a CI pipeline. Interviewers at AI-first companies already ask how you set up agents on a codebase.<\/div>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<h2 id=\"how-agents-read-it\">How AI agents find and read AGENTS.md<\/h2>\n<p>When you start a task, the agent looks for AGENTS.md files and adds their text to its instructions before it begins planning. The basic rules, from the official FAQ, are simple:<\/p>\n<ul>\n<li>The agent reads the <strong>nearest<\/strong> AGENTS.md in the directory tree.<\/li>\n<li>If there are several files, <strong>the one closest to the file being edited wins<\/strong> when rules conflict.<\/li>\n<li><strong>Your chat prompt overrides everything.<\/strong> If you say &#8220;use npm this time&#8221;, that beats the file.<\/li>\n<li>If you list test commands, the agent will try to run them and fix failures before it says it is done.<\/li>\n<\/ul>\n<figure>\n<svg viewBox=\"0 0 900 400\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\" role=\"img\" aria-label=\"Diagram: a repository with a root AGENTS.md and a nested AGENTS.md in packages\/api; the agent editing a file in packages\/api uses both, with the nested file winning\">\n<rect width=\"900\" height=\"400\" rx=\"16\" fill=\"#0f1430\"\/>\n<g font-family=\"Consolas,Menlo,monospace\" font-size=\"17\" fill=\"#c4cbe8\">\n<text x=\"40\" y=\"60\" fill=\"#ffffff\" font-weight=\"700\">my-app\/<\/text>\n<rect x=\"60\" y=\"78\" width=\"200\" height=\"34\" rx=\"8\" fill=\"#1b2150\" stroke=\"#3178c6\" stroke-width=\"2\"\/>\n<text x=\"76\" y=\"101\" fill=\"#9db8ff\">AGENTS.md  (root)<\/text>\n<text x=\"60\" y=\"150\">packages\/<\/text>\n<text x=\"90\" y=\"190\">web\/<\/text>\n<text x=\"120\" y=\"225\" fill=\"#8b94bb\">src\/App.tsx<\/text>\n<text x=\"90\" y=\"270\">api\/<\/text>\n<rect x=\"110\" y=\"285\" width=\"200\" height=\"34\" rx=\"8\" fill=\"#231c55\" stroke=\"#7c5cff\" stroke-width=\"2\"\/>\n<text x=\"126\" y=\"308\" fill=\"#d8ccff\">AGENTS.md  (api)<\/text>\n<text x=\"120\" y=\"352\" fill=\"#ffffff\">src\/users.py  \u270e<\/text>\n<\/g>\n<path d=\"M330 345 C 430 345, 450 230, 540 230\" stroke=\"#7c5cff\" stroke-width=\"2.5\" fill=\"none\" stroke-dasharray=\"6 5\"\/>\n<rect x=\"540\" y=\"60\" width=\"320\" height=\"290\" rx=\"14\" fill=\"#151b3b\" stroke=\"#3a4380\"\/>\n<text x=\"700\" y=\"96\" text-anchor=\"middle\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"18\" font-weight=\"700\" fill=\"#ffffff\">Agent edits users.py<\/text>\n<g font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"15\">\n<rect x=\"565\" y=\"120\" width=\"270\" height=\"52\" rx=\"10\" fill=\"#1b2150\"\/><text x=\"580\" y=\"142\" fill=\"#9db8ff\">1. Root AGENTS.md<\/text><text x=\"580\" y=\"162\" fill=\"#8b94bb\">general rules, loaded first<\/text>\n<rect x=\"565\" y=\"184\" width=\"270\" height=\"52\" rx=\"10\" fill=\"#231c55\"\/><text x=\"580\" y=\"206\" fill=\"#d8ccff\">2. packages\/api\/AGENTS.md<\/text><text x=\"580\" y=\"226\" fill=\"#8b94bb\">closest file: wins on conflict<\/text>\n<rect x=\"565\" y=\"248\" width=\"270\" height=\"52\" rx=\"10\" fill=\"#14361f\"\/><text x=\"580\" y=\"270\" fill=\"#86efac\">3. Your chat prompt<\/text><text x=\"580\" y=\"290\" fill=\"#8b94bb\">overrides both files<\/text>\n<\/g>\n<text x=\"700\" y=\"332\" text-anchor=\"middle\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"14\" fill=\"#8b94bb\">priority grows from top to bottom<\/text>\n<\/svg>\n<figcaption>How precedence works: general rules come from the root file, the nearest file wins on conflicts, and your prompt beats both.<\/figcaption>\n<\/figure>\n<h3>How Codex reads it (a detailed example)<\/h3>\n<p>OpenAI&#8217;s Codex documents its behaviour in detail, and it is a good mental model for other tools too:<\/p>\n<ol>\n<li><strong>Global file first.<\/strong> Codex checks <code>~\/.codex\/AGENTS.md<\/code> (or <code>AGENTS.override.md<\/code> if it exists) for your personal rules that apply to every project.<\/li>\n<li><strong>Walk the project.<\/strong> It starts at the project root (usually the Git root) and walks down to your current folder. In each folder it uses at most one file: <code>AGENTS.override.md<\/code>, then <code>AGENTS.md<\/code>, then any fallback names you configured.<\/li>\n<li><strong>Join them in order.<\/strong> Files are joined from root to leaf, so deeper files appear later and override earlier ones.<\/li>\n<li><strong>Respect a size limit.<\/strong> The combined text is capped by <code>project_doc_max_bytes<\/code>, which defaults to <strong>32 KiB<\/strong>. Anything beyond that is not loaded.<\/li>\n<\/ol>\n<div class=\"dd-tip\"><strong>Tip:<\/strong> Codex builds this instruction list once per run (once per session in the terminal UI). If you edit AGENTS.md, start a new session to pick up the change.<\/div>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<h2 id=\"first-agents-md\">Write your first AGENTS.md (step by step)<\/h2>\n<p>Create a file called <code>AGENTS.md<\/code> in the root of your repository, next to <code>README.md<\/code> and <code>package.json<\/code>. Start small. Here is a solid starter for a TypeScript + Node.js project:<\/p>\n<pre><code># AGENTS.md\n\n## Project overview\n- Express + TypeScript REST API for an online bookstore.\n- Source code lives in `src\/`, tests in `tests\/`.\n- Database: PostgreSQL via Prisma (`prisma\/schema.prisma`).\n\n## Setup and commands\n- Install dependencies: `pnpm install`\n- Start dev server: `pnpm dev` (runs on http:\/\/localhost:3000)\n- Type check: `pnpm typecheck`\n- Lint and format: `pnpm lint --fix`\n- Run all tests: `pnpm test`\n- Run one test file: `pnpm vitest run tests\/orders.test.ts`\n\n## Code style\n- TypeScript strict mode. Never use `any`; use `unknown` and narrow it.\n- Use `async\/await`, not `.then()` chains.\n- Named exports only. No default exports.\n- Validate request bodies with Zod schemas in `src\/schemas\/`.\n\n## Hard rules\n- Never commit `.env` files or print secrets in logs.\n- Never edit files in `prisma\/migrations\/` by hand.\n- Do not add a new npm dependency without explaining why.\n\n## Definition of done\n- `pnpm typecheck`, `pnpm lint` and `pnpm test` all pass.\n- New or changed code has tests.\n- PR title format: `[api] Short description`<\/code><\/pre>\n<p>Notice what makes this file useful:<\/p>\n<ul>\n<li><strong>Exact commands<\/strong>, not vague advice. &#8220;Run <code>pnpm vitest run tests\/orders.test.ts<\/code>&#8221; is something an agent can actually do.<\/li>\n<li><strong>Hard rules written with &#8220;never&#8221;<\/strong>. Short, clear limits are easier for a model to follow than long explanations.<\/li>\n<li><strong>A definition of done<\/strong>. This tells the agent when to stop, which stops it from declaring victory before tests pass.<\/li>\n<\/ul>\n<p>Commit the file like any other code. It is part of your project, it should be reviewed in pull requests, and it should change when your project changes.<\/p>\n<div class=\"dd-note\"><strong>Remember:<\/strong> AGENTS.md lives in your repo, so treat it as public. Never put API keys, passwords or internal URLs you would not share in it.<\/div>\n\n<h2 id=\"examples-by-stack\">AGENTS.md examples for different stacks<\/h2>\n<p>Pick your stack below. These are short, realistic files you can copy and adjust.<\/p>\n<div class=\"dd-tabs\">\n<input type=\"radio\" name=\"dd-tabs\" id=\"dd-t1\" checked>\n<input type=\"radio\" name=\"dd-tabs\" id=\"dd-t2\">\n<input type=\"radio\" name=\"dd-tabs\" id=\"dd-t3\">\n<div class=\"dd-tab-labels\">\n<label for=\"dd-t1\">Next.js frontend<\/label>\n<label for=\"dd-t2\">Python \/ FastAPI<\/label>\n<label for=\"dd-t3\">Personal global file<\/label>\n<\/div>\n<div class=\"dd-panel dd-p1\">\n<pre><code># AGENTS.md \u2014 Next.js app\n\n## Stack\n- Next.js (App Router), React, TypeScript, Tailwind CSS.\n- Pages and layouts: `app\/`. Shared UI: `components\/ui\/`.\n\n## Commands\n- Install: `npm ci`\n- Dev: `npm run dev`\n- Build (must pass before finishing): `npm run build`\n- Tests: `npm test`   |   E2E: `npx playwright test`\n\n## Conventions\n- Server Components by default. Add `\"use client\"` only when\n  the component needs state, effects or browser APIs.\n- Fetch data in Server Components, not in `useEffect`.\n- Use the `cn()` helper from `lib\/utils.ts` for class names.\n- Images always use `next\/image` with a meaningful `alt`.\n\n## Never\n- Never put secrets in `NEXT_PUBLIC_*` variables.\n- Never disable ESLint rules inline to make a build pass.<\/code><\/pre>\n<\/div>\n<div class=\"dd-panel dd-p2\">\n<pre><code># AGENTS.md \u2014 FastAPI service\n\n## Stack\n- Python 3.13, FastAPI, Pydantic v2, SQLAlchemy 2.0, PostgreSQL.\n- Package manager: uv (do not use pip directly).\n\n## Commands\n- Install: `uv sync`\n- Run API: `uv run fastapi dev app\/main.py`\n- Tests: `uv run pytest -q`\n- One test: `uv run pytest tests\/test_users.py -k create`\n- Lint + format: `uv run ruff check --fix . &amp;&amp; uv run ruff format .`\n- Types: `uv run mypy app`\n\n## Conventions\n- Routers in `app\/routers\/`, one file per resource.\n- Request\/response models in `app\/schemas\/` (Pydantic).\n- Use `async def` endpoints and the async DB session\n  from `app\/db.py`.\n- Raise `HTTPException` with clear `detail` messages.\n\n## Definition of done\n- pytest, ruff and mypy all pass with no new warnings.<\/code><\/pre>\n<\/div>\n<div class=\"dd-panel dd-p3\">\n<pre><code># ~\/.codex\/AGENTS.md \u2014 my personal defaults\n\n## How I like to work\n- Explain your plan in 3-5 bullet points before big changes.\n- Prefer small, focused commits with clear messages.\n- Ask before deleting files or running database migrations.\n\n## Style\n- Write simple, readable code over clever one-liners.\n- Add short comments only where the \"why\" is not obvious.\n\n## Tools\n- I use pnpm for JavaScript and uv for Python.<\/code><\/pre>\n<\/div>\n<\/div>\n<p>The global file is for <em>your<\/em> habits across every project. Project rules belong in the repo, so your teammates (and their agents) get them too.<\/p>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<h2 id=\"monorepos\">Nested AGENTS.md files for monorepos<\/h2>\n<p>In a monorepo, one giant file quickly becomes too long and full of rules that only matter for one package. The solution is <strong>nested files<\/strong>: a short root file for shared rules, plus one AGENTS.md inside each package. The agents.md site notes that OpenAI&#8217;s own main repository uses 88 AGENTS.md files.<\/p>\n<pre><code>my-monorepo\/\n\u251c\u2500\u2500 AGENTS.md              # shared: pnpm, commit rules, CI, security\n\u251c\u2500\u2500 packages\/\n\u2502   \u251c\u2500\u2500 web\/\n\u2502   \u2502   \u2514\u2500\u2500 AGENTS.md      # Next.js rules, UI components, Playwright\n\u2502   \u251c\u2500\u2500 api\/\n\u2502   \u2502   \u2514\u2500\u2500 AGENTS.md      # FastAPI rules, uv, pytest\n\u2502   \u2514\u2500\u2500 shared\/\n\u2502       \u2514\u2500\u2500 AGENTS.md      # types package: no runtime deps, semver\n\u2514\u2500\u2500 infra\/\n    \u2514\u2500\u2500 AGENTS.md          # Terraform: plan only, never apply<\/code><\/pre>\n<p>And here is what a nested package file might look like. It only adds what is different for that folder:<\/p>\n<pre><code># packages\/web\/AGENTS.md\n\nThese rules add to the root AGENTS.md. If they conflict, follow this file.\n\n## Commands (run from packages\/web)\n- Dev: `pnpm --filter web dev`\n- Tests: `pnpm --filter web test`\n- Find the package for a file: `pnpm dlx turbo run where web`\n\n## Rules\n- Import shared types from `@acme\/shared`, never copy them.\n- New components need a Storybook story in `stories\/`.<\/code><\/pre>\n<figure>\n<svg viewBox=\"0 0 900 300\" xmlns=\"http:\/\/www.w3.org\/2000\/svg\" role=\"img\" aria-label=\"Diagram: what to put in AGENTS.md versus what to leave out\">\n<rect width=\"900\" height=\"300\" rx=\"16\" fill=\"#f7f8fc\"\/>\n<rect x=\"30\" y=\"30\" width=\"400\" height=\"240\" rx=\"14\" fill=\"#ecfdf3\" stroke=\"#16a34a\" stroke-width=\"2\"\/>\n<text x=\"230\" y=\"66\" text-anchor=\"middle\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"20\" font-weight=\"700\" fill=\"#166534\">Put it in AGENTS.md<\/text>\n<g font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"16\" fill=\"#1d2333\">\n<text x=\"60\" y=\"106\">\u2714 Exact install \/ test \/ lint commands<\/text>\n<text x=\"60\" y=\"140\">\u2714 Folder map: where things live<\/text>\n<text x=\"60\" y=\"174\">\u2714 Hard rules (&#8220;never edit migrations&#8221;)<\/text>\n<text x=\"60\" y=\"208\">\u2714 Style choices a linter can&#8217;t check<\/text>\n<text x=\"60\" y=\"242\">\u2714 Definition of done<\/text>\n<\/g>\n<rect x=\"470\" y=\"30\" width=\"400\" height=\"240\" rx=\"14\" fill=\"#fef2f2\" stroke=\"#dc2626\" stroke-width=\"2\"\/>\n<text x=\"670\" y=\"66\" text-anchor=\"middle\" font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"20\" font-weight=\"700\" fill=\"#991b1b\">Leave it out<\/text>\n<g font-family=\"Segoe UI,Arial,sans-serif\" font-size=\"16\" fill=\"#1d2333\">\n<text x=\"500\" y=\"106\">\u2718 API keys, passwords, tokens<\/text>\n<text x=\"500\" y=\"140\">\u2718 Marketing text from the README<\/text>\n<text x=\"500\" y=\"174\">\u2718 Rules your formatter already enforces<\/text>\n<text x=\"500\" y=\"208\">\u2718 Long history or design essays<\/text>\n<text x=\"500\" y=\"242\">\u2718 Outdated commands nobody runs<\/text>\n<\/g>\n<\/svg>\n<figcaption>A quick checklist: AGENTS.md should be practical instructions, not documentation for humans.<\/figcaption>\n<\/figure>\n\n<h2 id=\"tool-setup\">Making every tool read the same file<\/h2>\n<p>Most agents read AGENTS.md automatically, including Codex, Cursor, GitHub Copilot&#8217;s coding agent, VS Code, Jules, Devin, Windsurf, Zed, Warp, Junie, Amp, goose, opencode, Factory and RooCode. A few tools need a small nudge.<\/p>\n<h3>Claude Code<\/h3>\n<p>Claude Code reads <code>CLAUDE.md<\/code>. You do not need to maintain two copies. Either create a <code>CLAUDE.md<\/code> that imports AGENTS.md (Claude Code supports <code>@path<\/code> imports), or use a symlink:<\/p>\n<pre><code># Option 1: CLAUDE.md that imports AGENTS.md\necho \"@AGENTS.md\" &gt; CLAUDE.md\n\n# Option 2: symlink (macOS \/ Linux)\nln -s AGENTS.md CLAUDE.md<\/code><\/pre>\n<p>Option 1 is nice because you can add a few Claude-only notes below the import line later.<\/p>\n<h3>Gemini CLI and Aider<\/h3>\n<pre><code>\/\/ .gemini\/settings.json\n{\n  \"context\": {\n    \"fileName\": \"AGENTS.md\"\n  }\n}<\/code><\/pre>\n<pre><code># .aider.conf.yml\nread: AGENTS.md<\/code><\/pre>\n<h3>Codex: custom names and a bigger limit<\/h3>\n<p>If your team already has a file like <code>TEAM_GUIDE.md<\/code>, Codex can use it as a fallback. You can also raise the size limit, though splitting into nested files is usually better:<\/p>\n<pre><code># ~\/.codex\/config.toml\nproject_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"]\nproject_doc_max_bytes = 65536   # default is 32 KiB<\/code><\/pre>\n<h3>Migrating from old file names<\/h3>\n<pre><code># Rename an old file and keep a link for older tools\nmv .cursorrules AGENTS.md\nln -s AGENTS.md .cursorrules<\/code><\/pre>\n<div class=\"dd-tip\"><strong>Windows tip:<\/strong> symlinks need Developer Mode or an admin terminal, and Git must have <code>core.symlinks=true<\/code>. If that is a hassle, use the CLAUDE.md import approach instead.<\/div>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<h2 id=\"check-script\">Check your AGENTS.md with a small script<\/h2>\n<p>AGENTS.md files tend to grow over time until they are too long or quietly hit the 32 KiB limit. Here is a tiny Node.js script (no dependencies, Node 18+) that finds every AGENTS.md in your repo and warns you when one gets too big or is missing the key sections:<\/p>\n<pre><code>\/\/ scripts\/check-agents-md.mjs\nimport { readdir, readFile, stat } from \"node:fs\/promises\";\nimport { join } from \"node:path\";\n\nconst MAX_BYTES = 32 * 1024;   \/\/ Codex default limit\nconst MAX_LINES = 200;         \/\/ keep files easy to read\nconst SKIP = new Set([\"node_modules\", \".git\", \"dist\", \".next\", \".venv\"]);\n\nasync function findFiles(dir, found = []) {\n  for (const entry of await readdir(dir, { withFileTypes: true })) {\n    if (SKIP.has(entry.name)) continue;\n    const full = join(dir, entry.name);\n    if (entry.isDirectory()) await findFiles(full, found);\n    else if (entry.name === \"AGENTS.md\") found.push(full);\n  }\n  return found;\n}\n\nconst files = await findFiles(process.cwd());\nlet totalBytes = 0;\nlet problems = 0;\n\nfor (const file of files) {\n  const text = await readFile(file, \"utf8\");\n  const { size } = await stat(file);\n  const lines = text.split(\"\\n\").length;\n  totalBytes += size;\n\n  const warnings = [];\n  if (lines &gt; MAX_LINES) warnings.push(`${lines} lines (try &lt; ${MAX_LINES})`);\n  if (!\/test\/i.test(text)) warnings.push(\"no test instructions found\");\n  if (\/(api[_-]?key|secret|password)\\s*[:=]\\s*\\S+\/i.test(text))\n    warnings.push(\"looks like it contains a secret!\");\n\n  console.log(`${warnings.length ? \"\u26a0\ufe0f \" : \"\u2705\"} ${file} (${size} bytes)`);\n  warnings.forEach((w) =&gt; console.log(`   - ${w}`));\n  problems += warnings.length;\n}\n\nif (totalBytes &gt; MAX_BYTES) {\n  console.log(`\u26a0\ufe0f  Combined size ${totalBytes} bytes is over ${MAX_BYTES}.`);\n  problems++;\n}\nif (files.length === 0) console.log(\"No AGENTS.md found. Create one in the repo root!\");\nprocess.exit(problems ? 1 : 0);<\/code><\/pre>\n<p>Run it with <code>node scripts\/check-agents-md.mjs<\/code>. Because it exits with code 1 when something is wrong, you can drop it into your CI pipeline. If you followed our <a href=\"https:\/\/devdojo.co.in\/github-actions-ci-cd-nodejs\/\">GitHub Actions CI\/CD guide<\/a>, just add one more step:<\/p>\n<pre><code># .github\/workflows\/ci.yml (extra step)\n      - name: Check AGENTS.md files\n        run: node scripts\/check-agents-md.mjs<\/code><\/pre>\n<p>Note that the combined-size check is a simple safety net. Codex only loads the files on the path from the root to your working folder, so the real loaded size is usually smaller.<\/p>\n\n<h2 id=\"errors\">Common AGENTS.md mistakes and how to fix them<\/h2>\n<div class=\"dd-table-wrap\">\n<table>\n<thead><tr><th>Problem<\/th><th>Likely cause<\/th><th>Fix<\/th><\/tr><\/thead>\n<tbody>\n<tr><td>Agent ignores your rules completely<\/td><td>Wrong file name (<code>AGENT.md<\/code>, <code>agents.md<\/code>) or the tool does not read AGENTS.md<\/td><td>Name it exactly <code>AGENTS.md<\/code>. For Claude Code, Gemini CLI or Aider, add the import\/config shown above.<\/td><\/tr>\n<tr><td>Edits to the file have no effect<\/td><td>The agent loaded instructions at session start<\/td><td>Start a new session or restart the agent after editing.<\/td><\/tr>\n<tr><td>Rules near the end are ignored<\/td><td>File too long; text past the size limit is dropped<\/td><td>Keep it under ~200 lines; move package rules into nested files.<\/td><\/tr>\n<tr><td>Agent uses the wrong package manager<\/td><td>Commands are vague (&#8220;install deps&#8221;)<\/td><td>Write exact commands: <code>pnpm install<\/code>, <code>uv sync<\/code>.<\/td><\/tr>\n<tr><td>Agent says &#8220;done&#8221; but tests fail<\/td><td>No definition of done<\/td><td>Add a &#8220;Definition of done&#8221; section listing the checks that must pass.<\/td><\/tr>\n<tr><td>Different rules in different folders clash<\/td><td>Root and nested files disagree<\/td><td>Closest file wins. Say so at the top of nested files and remove duplicates.<\/td><\/tr>\n<tr><td>Agent runs old commands<\/td><td>AGENTS.md was not updated after a tooling change<\/td><td>Update AGENTS.md in the same PR that changes scripts or tools.<\/td><\/tr>\n<tr><td>Secret leaked in a public repo<\/td><td>Tokens pasted into the file &#8220;for the agent&#8221;<\/td><td>Rotate the secret now. Use env vars and only mention the variable name.<\/td><\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n\n\n\n<div class=\"dd-post\">\n<h2 id=\"best-practices\">AGENTS.md best practices<\/h2>\n<ol>\n<li><strong>Lead with commands.<\/strong> Commands are the highest-value part of the file. An agent that can run your tests can check its own work.<\/li>\n<li><strong>Be specific, not polite.<\/strong> &#8220;Use Zod for validation in <code>src\/schemas\/<\/code>&#8221; works better than &#8220;please try to validate inputs properly&#8221;.<\/li>\n<li><strong>Use &#8220;never&#8221; for hard limits.<\/strong> Short bullet rules like &#8220;Never run <code>terraform apply<\/code>&#8221; are clear and easy to follow.<\/li>\n<li><strong>Keep it short.<\/strong> Aim for under 200 lines per file. Every line uses part of the agent&#8217;s context window, so remove anything that does not change behaviour.<\/li>\n<li><strong>Do not repeat your linter.<\/strong> If Prettier or Ruff already enforces a rule, just tell the agent to run the formatter.<\/li>\n<li><strong>Give a folder map.<\/strong> A few lines like &#8220;API routes: <code>src\/routes\/<\/code>&#8221; save the agent from searching the whole repo.<\/li>\n<li><strong>Split by folder in monorepos.<\/strong> Shared rules at the root, specific rules next to the code.<\/li>\n<li><strong>Review it like code.<\/strong> Changes to AGENTS.md change how every agent behaves for every teammate, so they deserve a proper PR review.<\/li>\n<li><strong>Learn from mistakes.<\/strong> When an agent gets something wrong twice, add one line to AGENTS.md so it does not happen a third time.<\/li>\n<li><strong>Test it.<\/strong> Ask your agent to do a small real task and watch whether it follows the file. Results can vary between runs, so try a few times before deciding a rule works.<\/li>\n<\/ol>\n<p>Building your own agents instead of just using them? Our tutorial on the <a href=\"https:\/\/devdojo.co.in\/openai-agents-sdk-python\/\">OpenAI Agents SDK in Python<\/a> shows how instructions shape agent behaviour from the other side.<\/p>\n\n<h2 id=\"faq\">Frequently asked questions<\/h2>\n<details>\n<summary>Is AGENTS.md the same as README.md?<\/summary>\n<p>No. README.md is for humans: what the project does and how to get started. AGENTS.md is for AI agents: detailed commands, rules and conventions. Keeping them separate keeps your README clean and your agent instructions precise.<\/p>\n<\/details>\n<details>\n<summary>Do I need any special format or front matter?<\/summary>\n<p>No. AGENTS.md is plain Markdown with no required fields. Use normal headings and bullet points. Agents read it as text.<\/p>\n<\/details>\n<details>\n<summary>Which AI coding tools support AGENTS.md?<\/summary>\n<p>Codex, Cursor, GitHub Copilot&#8217;s coding agent, VS Code, Jules, Gemini CLI (with a setting), Aider (with a setting), Devin, Windsurf, Zed, Warp, Junie, Amp, goose, opencode, Factory, RooCode, Kilo Code, Augment Code and more. Claude Code uses CLAUDE.md but can import AGENTS.md with one line.<\/p>\n<\/details>\n<details>\n<summary>What happens if two AGENTS.md files disagree?<\/summary>\n<p>The file closest to the code being edited wins. And whatever you type in the chat overrides both files.<\/p>\n<\/details>\n<details>\n<summary>How long should my AGENTS.md be?<\/summary>\n<p>Short enough that a new teammate could read it in five minutes. Under 200 lines is a good target. Codex stops loading project instructions after 32 KiB by default.<\/p>\n<\/details>\n<details>\n<summary>Should I commit AGENTS.md to Git?<\/summary>\n<p>Yes. It is part of your project setup, just like your linter config. Commit it, review changes in PRs and keep it up to date. Personal preferences go in your global file instead, such as <code>~\/.codex\/AGENTS.md<\/code>.<\/p>\n<\/details>\n\n<h2 id=\"conclusion\">Conclusion<\/h2>\n<p>AGENTS.md is one of the simplest upgrades you can make to how you work with AI. It takes ten minutes to write, it works across most modern coding agents, and it turns &#8220;the agent keeps doing it wrong&#8221; into &#8220;the agent does it our way&#8221;. Start with a root file that lists your exact commands, a few hard rules and a definition of done. Add nested files when your repo grows, connect tools like Claude Code with one import line, and keep the file short and up to date.<\/p>\n<p>Your next step: open your current project, create <code>AGENTS.md<\/code>, and ask your favourite agent to fix one small bug. Watch how much better it follows your project&#8217;s rules.<\/p>\n<div class=\"dd-cta\">\n<h3>New posts every day on DevDojo<\/h3>\n<p>Practical, beginner-friendly guides on AI, frontend, backend and DevOps.<\/p>\n<p><a href=\"https:\/\/devdojo.co.in\/\">Explore more tutorials \u2192<\/a> and drop your questions in the comments below.<\/p>\n<\/div>\n<\/div>\n\n","protected":false},"excerpt":{"rendered":"<p>Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.<\/p>\n","protected":false},"author":1,"featured_media":205,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[38,1],"tags":[102,103,104,105,107,106],"class_list":["post-206","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai","category-general","tag-agents-md","tag-ai-coding-agents","tag-codex","tag-cursor","tag-developer-productivity","tag-github-copilot"],"aioseo_notices":[],"aioseo_head":"\n\t\t<!-- All in One SEO 5.0.2.1 - aioseo.com -->\n\t<meta name=\"description\" content=\"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.\" \/>\n\t<meta name=\"robots\" content=\"max-image-preview:large\" \/>\n\t<meta name=\"author\" content=\"Lokendra\"\/>\n\t<link rel=\"canonical\" href=\"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/\" \/>\n\t<meta name=\"generator\" content=\"All in One SEO (AIOSEO) 5.0.2.1\" \/>\n\t\t<meta property=\"og:locale\" content=\"en_US\" \/>\n\t\t<meta property=\"og:site_name\" content=\"DevDojo - Empowering Developers\" \/>\n\t\t<meta property=\"og:type\" content=\"article\" \/>\n\t\t<meta property=\"og:title\" content=\"AGENTS.md Guide: Write Instructions for AI Coding Agents\" \/>\n\t\t<meta property=\"og:description\" content=\"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.\" \/>\n\t\t<meta property=\"og:url\" content=\"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/\" \/>\n\t\t<meta property=\"article:published_time\" content=\"2026-10-16T13:03:49+00:00\" \/>\n\t\t<meta property=\"article:modified_time\" content=\"2026-10-16T13:03:50+00:00\" \/>\n\t\t<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n\t\t<meta name=\"twitter:title\" content=\"AGENTS.md Guide: Write Instructions for AI Coding Agents\" \/>\n\t\t<meta name=\"twitter:description\" content=\"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.\" \/>\n\t\t<script type=\"application\/ld+json\" class=\"aioseo-schema\">\n\t\t\t{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"BlogPosting\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#blogposting\",\"name\":\"AGENTS.md Guide: Write Instructions for AI Coding Agents\",\"headline\":\"AGENTS.md Guide: How to Write Instructions for AI Coding Agents\",\"author\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/author\\\/lokendra\\\/#author\"},\"publisher\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#organization\"},\"image\":{\"@type\":\"ImageObject\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/agents-md-guide.jpg\",\"width\":1200,\"height\":630,\"caption\":\"AGENTS.md guide banner: one instructions file shared by Codex, Cursor, Copilot and Gemini CLI\"},\"datePublished\":\"2026-10-16T13:03:49+00:00\",\"dateModified\":\"2026-10-16T13:03:50+00:00\",\"inLanguage\":\"en-US\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#webpage\"},\"isPartOf\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#webpage\"},\"articleSection\":\"AI, General, AGENTS.md, AI Coding Agents, Codex, Cursor, Developer Productivity, GitHub Copilot\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#breadcrumblist\",\"itemListElement\":[{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#listItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/devdojo.co.in\\\/\",\"nextItem\":{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/category\\\/general\\\/#listItem\",\"name\":\"General\"}},{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/category\\\/general\\\/#listItem\",\"position\":2,\"name\":\"General\",\"item\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/category\\\/general\\\/\",\"nextItem\":{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#listItem\",\"name\":\"AGENTS.md Guide: How to Write Instructions for AI Coding Agents\"},\"previousItem\":{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#listItem\",\"name\":\"Home\"}},{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#listItem\",\"position\":3,\"name\":\"AGENTS.md Guide: How to Write Instructions for AI Coding Agents\",\"previousItem\":{\"@type\":\"ListItem\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/category\\\/general\\\/#listItem\",\"name\":\"General\"}}]},{\"@type\":\"Organization\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#organization\",\"name\":\"DevDojo\",\"description\":\"Empowering Developers\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/author\\\/lokendra\\\/#author\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/author\\\/lokendra\\\/\",\"name\":\"Lokendra\",\"image\":{\"@type\":\"ImageObject\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#authorImage\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/99f102f0cc9080237ce54b91304fd1b3b6fa29925cbaeba93cd796872e58b45c?s=96&d=mm&r=g\",\"width\":96,\"height\":96,\"caption\":\"Lokendra\"}},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#webpage\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/\",\"name\":\"AGENTS.md Guide: Write Instructions for AI Coding Agents\",\"description\":\"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.\",\"inLanguage\":\"en-US\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#website\"},\"breadcrumb\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#breadcrumblist\"},\"author\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/author\\\/lokendra\\\/#author\"},\"creator\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/author\\\/lokendra\\\/#author\"},\"image\":{\"@type\":\"ImageObject\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/wp-content\\\/uploads\\\/2026\\\/10\\\/agents-md-guide.jpg\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#mainImage\",\"width\":1200,\"height\":630,\"caption\":\"AGENTS.md guide banner: one instructions file shared by Codex, Cursor, Copilot and Gemini CLI\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/index.php\\\/2026\\\/10\\\/16\\\/agents-md-guide\\\/#mainImage\"},\"datePublished\":\"2026-10-16T13:03:49+00:00\",\"dateModified\":\"2026-10-16T13:03:50+00:00\"},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#website\",\"url\":\"https:\\\/\\\/devdojo.co.in\\\/\",\"name\":\"DevDojo\",\"description\":\"Empowering Developers\",\"inLanguage\":\"en-US\",\"publisher\":{\"@id\":\"https:\\\/\\\/devdojo.co.in\\\/#organization\"}}]}\n\t\t<\/script>\n\t\t<!-- All in One SEO -->\n\n","aioseo_head_json":{"title":"AGENTS.md Guide: Write Instructions for AI Coding Agents","description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.","canonical_url":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/","robots":"max-image-preview:large","keywords":"","webmasterTools":{"miscellaneous":""},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"BlogPosting","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#blogposting","name":"AGENTS.md Guide: Write Instructions for AI Coding Agents","headline":"AGENTS.md Guide: How to Write Instructions for AI Coding Agents","author":{"@id":"https:\/\/devdojo.co.in\/index.php\/author\/lokendra\/#author"},"publisher":{"@id":"https:\/\/devdojo.co.in\/#organization"},"image":{"@type":"ImageObject","url":"https:\/\/devdojo.co.in\/wp-content\/uploads\/2026\/10\/agents-md-guide.jpg","width":1200,"height":630,"caption":"AGENTS.md guide banner: one instructions file shared by Codex, Cursor, Copilot and Gemini CLI"},"datePublished":"2026-10-16T13:03:49+00:00","dateModified":"2026-10-16T13:03:50+00:00","inLanguage":"en-US","mainEntityOfPage":{"@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#webpage"},"isPartOf":{"@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#webpage"},"articleSection":"AI, General, AGENTS.md, AI Coding Agents, Codex, Cursor, Developer Productivity, GitHub Copilot"},{"@type":"BreadcrumbList","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#breadcrumblist","itemListElement":[{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/#listItem","position":1,"name":"Home","item":"https:\/\/devdojo.co.in\/","nextItem":{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/index.php\/category\/general\/#listItem","name":"General"}},{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/index.php\/category\/general\/#listItem","position":2,"name":"General","item":"https:\/\/devdojo.co.in\/index.php\/category\/general\/","nextItem":{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#listItem","name":"AGENTS.md Guide: How to Write Instructions for AI Coding Agents"},"previousItem":{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/#listItem","name":"Home"}},{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#listItem","position":3,"name":"AGENTS.md Guide: How to Write Instructions for AI Coding Agents","previousItem":{"@type":"ListItem","@id":"https:\/\/devdojo.co.in\/index.php\/category\/general\/#listItem","name":"General"}}]},{"@type":"Organization","@id":"https:\/\/devdojo.co.in\/#organization","name":"DevDojo","description":"Empowering Developers","url":"https:\/\/devdojo.co.in\/"},{"@type":"Person","@id":"https:\/\/devdojo.co.in\/index.php\/author\/lokendra\/#author","url":"https:\/\/devdojo.co.in\/index.php\/author\/lokendra\/","name":"Lokendra","image":{"@type":"ImageObject","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#authorImage","url":"https:\/\/secure.gravatar.com\/avatar\/99f102f0cc9080237ce54b91304fd1b3b6fa29925cbaeba93cd796872e58b45c?s=96&d=mm&r=g","width":96,"height":96,"caption":"Lokendra"}},{"@type":"WebPage","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#webpage","url":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/","name":"AGENTS.md Guide: Write Instructions for AI Coding Agents","description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.","inLanguage":"en-US","isPartOf":{"@id":"https:\/\/devdojo.co.in\/#website"},"breadcrumb":{"@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#breadcrumblist"},"author":{"@id":"https:\/\/devdojo.co.in\/index.php\/author\/lokendra\/#author"},"creator":{"@id":"https:\/\/devdojo.co.in\/index.php\/author\/lokendra\/#author"},"image":{"@type":"ImageObject","url":"https:\/\/devdojo.co.in\/wp-content\/uploads\/2026\/10\/agents-md-guide.jpg","@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#mainImage","width":1200,"height":630,"caption":"AGENTS.md guide banner: one instructions file shared by Codex, Cursor, Copilot and Gemini CLI"},"primaryImageOfPage":{"@id":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/#mainImage"},"datePublished":"2026-10-16T13:03:49+00:00","dateModified":"2026-10-16T13:03:50+00:00"},{"@type":"WebSite","@id":"https:\/\/devdojo.co.in\/#website","url":"https:\/\/devdojo.co.in\/","name":"DevDojo","description":"Empowering Developers","inLanguage":"en-US","publisher":{"@id":"https:\/\/devdojo.co.in\/#organization"}}]},"og:locale":"en_US","og:site_name":"DevDojo - Empowering Developers","og:type":"article","og:title":"AGENTS.md Guide: Write Instructions for AI Coding Agents","og:description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.","og:url":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/","article:published_time":"2026-10-16T13:03:49+00:00","article:modified_time":"2026-10-16T13:03:50+00:00","twitter:card":"summary_large_image","twitter:title":"AGENTS.md Guide: Write Instructions for AI Coding Agents","twitter:description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices."},"aioseo_meta_data":{"post_id":"206","title":"AGENTS.md Guide: Write Instructions for AI Coding Agents","description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.","keywords":null,"keyphrases":{"focus":{"keyphrase":"AGENTS.md"},"additional":[]},"primary_term":null,"canonical_url":null,"og_title":"AGENTS.md Guide: Write Instructions for AI Coding Agents","og_description":"Learn what AGENTS.md is, how AI coding agents like Codex, Cursor and Copilot read it, and how to write one with real examples, nested files and best practices.","og_object_type":"default","og_image_type":"default","og_image_url":null,"og_image_width":null,"og_image_height":null,"og_image_custom_url":null,"og_image_custom_fields":null,"og_video":"","og_custom_url":null,"og_article_section":null,"og_article_tags":null,"twitter_use_og":false,"twitter_card":"default","twitter_image_type":"default","twitter_image_url":null,"twitter_image_custom_url":null,"twitter_image_custom_fields":null,"twitter_title":null,"twitter_description":null,"schema":{"blockGraphs":[],"customGraphs":[],"default":{"data":{"Article":[],"Course":[],"Dataset":[],"FAQPage":[],"Movie":[],"Person":[],"Product":[],"ProductReview":[],"Car":[],"Recipe":[],"Service":[],"SoftwareApplication":[],"WebPage":[]},"graphName":"BlogPosting","isEnabled":true},"graphs":[]},"schema_type":"default","schema_type_options":null,"pillar_content":false,"robots_default":true,"robots_noindex":false,"robots_noarchive":false,"robots_nosnippet":false,"robots_nofollow":false,"robots_noimageindex":false,"robots_noodp":false,"robots_notranslate":false,"robots_max_snippet":"-1","robots_max_videopreview":"-1","robots_max_imagepreview":"large","priority":0,"frequency":"default","local_seo":null,"breadcrumb_settings":null,"limit_modified_date":false,"ai":{"faqs":[],"keyPoints":[],"schemas":[],"titles":[],"descriptions":[],"socialPosts":{"email":{"subject":"","preview":"","content":""},"linkedin":[],"twitter":[],"facebook":[],"instagram":[]}},"created":"2026-10-16 12:58:06","updated":"2026-10-16 13:03:50","focus_keyword":"AGENTS.md","additional_keywords":null,"truseo_locale":null,"seo_analyzer_scan_date":null},"aioseo_breadcrumb":"<div class=\"aioseo-breadcrumbs\"><span class=\"aioseo-breadcrumb\">\n\t\t\t<a href=\"https:\/\/devdojo.co.in\/\" title=\"Home\">Home<\/a>\n\t\t<\/span><span class=\"aioseo-breadcrumb-separator\">\u00bb<\/span><span class=\"aioseo-breadcrumb\">\n\t\t\t<a href=\"https:\/\/devdojo.co.in\/index.php\/category\/general\/\" title=\"General\">General<\/a>\n\t\t<\/span><span class=\"aioseo-breadcrumb-separator\">\u00bb<\/span><span class=\"aioseo-breadcrumb\">\n\t\t\tAGENTS.md Guide: How to Write Instructions for AI Coding Agents\n\t\t<\/span><\/div>","aioseo_breadcrumb_json":[{"label":"Home","link":"https:\/\/devdojo.co.in\/"},{"label":"General","link":"https:\/\/devdojo.co.in\/index.php\/category\/general\/"},{"label":"AGENTS.md Guide: How to Write Instructions for AI Coding Agents","link":"https:\/\/devdojo.co.in\/index.php\/2026\/10\/16\/agents-md-guide\/"}],"_links":{"self":[{"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/posts\/206","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/comments?post=206"}],"version-history":[{"count":1,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/posts\/206\/revisions"}],"predecessor-version":[{"id":207,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/posts\/206\/revisions\/207"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/media\/205"}],"wp:attachment":[{"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/media?parent=206"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/categories?post=206"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devdojo.co.in\/index.php\/wp-json\/wp\/v2\/tags?post=206"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}