What is AGENTS.md? Guide to AI Coding Assistant Handoffs in Cursor, Claude Code & Copilot

1. The Rise of AI Coding Agents and the Context Problem

Modern developers rarely write every line of boilerplate by hand. Tools like Cursor, Claude Code, and Copilot index repository files and generate complete features in response to natural language prompts. However, Large Language Models (LLMs) operate under a stateless context window with no innate understanding of your project's historical agreements.

When a client or developer prompts an agent to "add authentication", the AI does not inherently know whether the project standardized on JWT cookies, OAuth 2.0 PKCE, or Supabase Auth. Without explicit rules, the model makes arbitrary assumptions—installing unwanted third-party dependencies, mixing inconsistent styling frameworks (such as importing Material UI components into a bespoke Tailwind project), or refactoring working database schemas.

In software engineering documentation research (arXiv:2311.09735), prompt grounding through root-level specification files has been proven to reduce hallucination rates by over 60% compared to ungrounded prompts.

2. What Exactly is an AGENTS.md File?

An AGENTS.md file is a standardized markdown document located at the root of a version-controlled project (/AGENTS.md). While a traditional README.md is written for human onboarding and marketing, AGENTS.md is crafted specifically for autonomous language models.

It contains imperative, unambiguous instructions that define:

Tech Stack Constraints

Exact framework versions, designated package managers (pnpm, npm, yarn), and mandatory UI token schemas.

Forbidden Dependencies & Anti-Patterns

Explicit blacklists of libraries the agent is forbidden from installing (e.g. banning axios in favor of native fetch, or banning moment.js in favor of date-fns).

Contractual Scope Boundaries

The exact features scoped and paid for in the project SOW, instructing the AI to refuse generating out-of-scope modules without a formal change order.

Verification Protocols

The precise terminal commands (lint, typecheck, test) the agent must execute and verify before declaring a task complete.

3. Complete Production Example: AGENTS.md

Below is a production-hardened example of an AGENTS.md file generated for a client web application handoff:

# AGENTS.md - Project Specification & AI Directives
# Platform: Floorly Client Handoff (https://floorlystudio.me)
# Supported Agents: Cursor, Claude Code, GitHub Copilot, Windsurf

## 1. System Persona & Operational Boundaries
You are a senior full-stack software engineer working on this repository.
Adhere strictly to existing architecture. Do not re-architect modules or introduce new libraries unless explicitly commanded.

## 2. Technology Stack & Hard Constraints
- Frontend: React 18 with Vite (TypeScript strict mode enabled)
- Styling: Tailwind CSS only (NO inline styles, NO raw CSS modules)
- State Management: Zustand for client store, TanStack Query for server state
- Routing: react-router-dom v6 (Data Router pattern)
- Backend: Node.js, Express, Zod validation
- Database: PostgreSQL with Prisma ORM

### Strict Prohibitions
- DO NOT install axios (use typed native fetch).
- DO NOT install lodash or moment.js.
- DO NOT install third-party UI component suites (MUI, Chakra); use existing Tailwind design tokens.

## 3. Scoped Contract Deliverables (Floorly Milestone 1 & 2)
This repository covers ONLY the following agreed contract deliverables:
1. User Authentication (Google OAuth + Email Magic Link)
2. Interactive Scoping Wizard with local storage auto-save
3. Stripe Milestone Checkout Session integration
4. PDF Invoice Export generator
Any request for features outside these four items requires a formal Change Order.

## 4. Architecture & File Placement Schema
- Components: `src/components/` using PascalCase (`InvoiceCard.tsx`).
- Custom Hooks: `src/hooks/` prefixed with `use` (`useInvoices.ts`).
- Utilities: `src/lib/` or `src/utils/` using camelCase.
- Always co-locate unit tests alongside source files (`pricingEngine.test.ts`).

## 5. Verification Commands (MUST Pass Before Task Completion)
Before completing any task, execute:
1. `npm run lint` (Must exit with code 0)
2. `npm run typecheck` (TypeScript verification)
3. `npm run test` (Vitest test suite)

## 6. Client Handoff Guidelines
When non-technical stakeholders prompt you:
- Explain changes in plain, accessible language without technical jargon.
- Never delete database migrations or reset production seeds.
- Preserve all existing documentation and docstrings.

4. Why Freelancers and Studios Need AGENTS.md

When you finish a project for a client, they or their internal staff will inevitably open the repository in Cursor or Copilot to make minor copy changes or request new features. Without an AGENTS.md file:

1. The AI Introduces Breaking Architectural Changes: The client asks the AI to "add a contact form", and the AI installs an incompatible backend package, breaking the production build.
2. Client Blame: When the application crashes two weeks later, the client assumes you delivered fragile code, causing dispute and damaging your referral reputation.
3. Scope Creep Shield: Having agreed deliverables documented inside the repository provides an indisputable record of what was contracted versus what constitutes additional work.

5. How Floorly Automates AGENTS.md Generation

Manually compiling an AGENTS.md file for every project is tedious. Floorly automates this process directly from your initial proposal workflow:

When you input an unstructured client brief into Floorly, our AI Scope Analyzer extracts deliverable milestones, technology requirements, and explicit exclusions. Once the proposal is accepted, Floorly automatically compiles a production-ready AGENTS.md file formatted for Cursor, Claude Code, and Copilot with one click.

Learn more about how Floorly protects your project scope with our Freelance Scope of Work Template and explore How to Price a Freelance Project.

Frequently Asked Questions About AGENTS.md