The Pain: Why AI Coding Keeps Blowing Up in the Same Spots

Anyone shipping real work with Cursor, Windsurf, or Claude Code has felt this: the agent spits out a wall of code, you paste it in, and the build explodes. Tests go red. Dependencies land in the wrong folder. The agent isn’t dumb. It just doesn’t know your project’s unwritten rules.

AGENTS.md is a Markdown file parked at the repo root, written for the machine. It tells the agent how to build, how to test, which lint rules matter. README.md is for humans: project pitch, contribution guide, brand story. When an agent reads that, it’s like a new hire getting a glossy brochure on day one and being told to ship a feature. The agent knows what the company sells, but it doesn’t know the build command, the test runner, or that ESLint exists. So you end up repeating yourself every session: “use pnpm, not npm,” “tests live under packages/web,” “run lint before you commit.” Say it a hundred times, the repo is still a mess.

The hit is brutal on client work. You land a Next.js + Prisma contract, fire up Cursor to move fast, and the agent runs npm install. Your pnpm workspace config is dead. It doesn’t know where your schema lives, so the migration it generates crashes. The client wants delivery yesterday, and you burn three hours debugging code the AI wrote. That’s a terrible way to earn a paycheck.

Three classic failure modes when the agent doesn’t know your rules: ① Wrong package manager (project uses pnpm, agent defaults to npm install), dependencies land in the wrong tree, workspace config breaks. ② Test entry point missing (tests live in packages/web, agent runs pnpm test at the root and gets “no test files found”). ③ Style drift (project runs ESLint + Prettier, agent outputs wrong indents and quotes, CI fails on push).

The Opportunity: Splitting Human Docs From Machine Docs

The open-source project AGENTS.md (repo at github.com/agentsmd/agents.md, around 24k stars as of 2026-08-25) solves this with one move: drop a Markdown file at the repo root that tells the agent how to build, test, and style code.

It’s not a README replacement. It’s a README companion. README serves human contributors. AGENTS.md serves AI agents. Clean split, no overlap.

Per the source post, AGENTS.md has been adopted by tens of thousands of open-source projects (exact count unverified), covering VS Code, Cursor, Windsurf, Aider, GitHub Copilot, and other major AI coding tools (verified). Community chatter also flags support in OpenAI Codex and Google Jules (⚠️ unverified). Skip this and you’re letting the agent talk to you in dialect.

Path 1: Hand-Write a Minimum Viable AGENTS.md

Cost is near zero. New file, three sections, done.

Quick context: the examples below use pnpm (lighter on disk than npm, native monorepo workspace support), turbo (monorepo task runner), and the --filter flag (targets one sub-package without touching the rest of the repo).

Section 1, “Dev environment tips”: tell the agent which package manager, how to jump into a sub-package, how to scaffold a new module. From the official example:

• pnpm dlx turbo run where <project_name>: jump straight into a sub-package directory, no ls hunting.
• pnpm install --filter <project_name>: install deps for one sub-package only, leave the rest of the monorepo alone.
• pnpm create vite@latest <project_name> -- --template react-ts: scaffold a new React + Vite sub-package with TypeScript checks.

The agent won’t guess these. Write them down and it follows.

Section 2, “Testing instructions”: how to run tests, where the CI plan lives, what must pass before commit. Official example:

• pnpm turbo run test --filter <project_name>: run the full check suite for one sub-package.
• pnpm vitest run -t "<test name>": run a single test by name match.
• “Fix any test or type errors until the whole suite is green.” Don’t stop until it’s green.
• “Add or update tests for the code you change, even if nobody asked.” This line is the unlock. Skip it and the agent will skip tests every time.

Section 3, “PR instructions”: commit title format, mandatory lint + test runs. Official example: Title format: [<project_name>] <Title> plus “Always run pnpm lint and pnpm test before committing.”

Three sections, under 50 lines, and the agent’s first-pass success rate jumps noticeably (per community feedback, exact numbers unverified).

Path 2: Nesting AGENTS.md Inside a Monorepo

On enterprise gigs where the codebase is a monorepo (multiple related projects in one Git repo, with frontend, backend, and shared code each in their own subfolder), one root AGENTS.md isn’t enough. AGENTS.md supports nesting: drop a dedicated file in each subdirectory, and the agent auto-loads the closest one.

How to do it: the root AGENTS.md covers global rules (package manager, CI flow, security notes). Then drop one in packages/web/, packages/api/, packages/shared/. Each one captures the build commands, test entry points, and special deps for that sub-package. Example: the frontend file says “component library is shadcn, styling is Tailwind, icons are lucide-react.” The backend file says “DB migrations use Prisma, API routes live under src/routes, auth is JWT.”

When the agent works inside a subdirectory, it loads the nearest AGENTS.md, which overrides the root. Frontend agent and backend agent get totally different instructions in the same repo, with no cross-talk.

Path 3: Turn It Into a Freelance Differentiator

The AI freelance market is a bloodbath. Everyone has Cursor, delivery quality is all over the map. Drop one line in your proposal: “This project ships with an AGENTS.md standard config. AI-assisted development follows project conventions.” That beats every competitor who just says “I use AI to code.”

The play: after winning the gig, spend 30 minutes reading the client’s repo, then write a custom AGENTS.md. That file is part of the deliverable. When the client maintains the code later with their own AI tools, it still works.

Price the AGENTS.md config service as a standalone line item (adjust to your local market): Basic tier ~$70 (single-file config + README walkthrough), Enterprise tier ~$420 (monorepo nesting + security rules + team training). Deliverables: ① Custom AGENTS.md file. ② 30 days of async Q&A support. ③ 10-minute Loom walkthrough. Best fit: clients already paying for Cursor/Windsurf but not getting results. Bad fit: clients still coding fully by hand with no AI tooling.

Case Study: AGENTS.md’s Compatibility Moat

AGENTS.md ships under MIT (confirmed in source pack), community-maintained (governance details unverified), home page at agents.md.

Compatibility is the moat: VS Code, Cursor, Windsurf, Aider, and GitHub Copilot all read AGENTS.md (verified). Community reports also flag OpenAI Codex, Claude Code, Gemini CLI, and Google Jules (⚠️ unverified). One file, every major agent, no per-tool config sprawl.

Compare the alternatives: Cursor’s .cursorrules only works in Cursor. Switch to Windsurf and it’s dead. Claude Code’s CLAUDE.md only serves Claude. GitHub Copilot’s instruction system is yet another format. AGENTS.md’s “write once, run anywhere” is why adoption is exploding.

Migration cost is zero. Cursor today, Windsurf tomorrow. The same AGENTS.md works, no rewrite.

Call to Action: Add a Machine Manual Tonight

5-minute checklist: ① Open your repo root. ② Create AGENTS.md. ③ Copy the official template (github.com/agentsmd/agents.md). ④ Fill in three commands (build, test, lint). ⑤ Next time you ask the agent to code, watch what happens.

Running a monorepo? Spend an extra 20 minutes tonight dropping a nested config into each sub-package. Tomorrow morning the agent’s output stops needing constant correction.

AGENTS.md is the highest-ROI AI coding config right now. 30 minutes in, hours of debug time saved every month.