DevTk.AI
中文
AGENTS.mdAI CodingClaude CodeCursorDeveloper Tools

AGENTS.md: The Open Standard for Guiding AI Coding Agents (2026 Guide)

Learn how to write an AGENTS.md file that works with Claude Code, GitHub Copilot, Cursor, Devin, and more. Includes templates, best practices, and a free online generator.

DevTk.AI 2026-02-22

AI coding agents are becoming standard tools for developers in 2026. Claude Code, GitHub Copilot, Cursor, Devin, Windsurf, Gemini CLI — the list keeps growing. But there’s a problem: every AI agent that enters your codebase starts with zero context about how your project works.

AGENTS.md solves this. It’s a simple Markdown file that tells AI agents everything they need to know about your project: how to build it, how to test it, what conventions to follow, and what to avoid.

This guide covers everything you need to know about AGENTS.md — what it is, why you need it, how to write one, and best practices from projects that are already using it.

What Is AGENTS.md?

AGENTS.md is an open standard for guiding AI coding agents. Think of it as a README for AI — a dedicated, predictable file where you provide context and instructions that help AI systems work effectively on your project.

Key facts:

  • Format: Standard Markdown (no special syntax required)
  • Placement: Project root directory
  • Adoption: Over 60,000 open-source projects since 2025
  • Backed by: The Agentic AI Foundation (AAIF) under the Linux Foundation, alongside MCP (Anthropic) and Goose (Block)
  • Compatible with: Claude Code, GitHub Copilot, Cursor, Windsurf, Devin, Gemini CLI, Aider, VS Code AI, and more

Why Do You Need AGENTS.md?

Without an AGENTS.md, AI coding agents have to guess:

  • Which package manager? npm? yarn? pnpm? bun?
  • How to run tests? npm test? pytest? go test ./...?
  • What coding style? Tabs or spaces? camelCase or snake_case?
  • What patterns to use? Functional components or class components? Services or controllers?

These guesses waste time and produce code that doesn’t match your project. An AGENTS.md eliminates the guesswork.

Real Impact

Teams that adopt AGENTS.md report:

  • Fewer AI-generated code revisions (the agent gets it right the first time)
  • Consistent code style across all AI tools
  • Faster onboarding for new team members using AI assistants
  • Less time spent in code review fixing AI-generated style issues

How to Write an AGENTS.md

An AGENTS.md file is flexible — there are no strictly required sections. However, the most effective files include these sections:

1. Project Overview

Tell the agent what the project is and what tech stack it uses.

## Project Overview

**MyApp** — A real-time collaboration platform built with Next.js 15, TypeScript, Prisma, and PostgreSQL.

2. Development Environment

This is the most critical section. Build commands, dev commands, and test commands are what AI agents use most frequently.

## Development Environment

- Package manager: `pnpm`
- Start dev server: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

3. Codebase Structure

Help the agent navigate your project.

## Codebase Structure

src/
  app/          — Next.js App Router pages
  components/   — React components (PascalCase)
  lib/          — Shared utilities and helpers
  server/       — Server-side logic and API
  db/           — Prisma schema and migrations

4. Code Style & Conventions

Define the rules that matter to your team.

## Code Style & Conventions

- Use Server Components by default, add "use client" only when needed
- Prefer named exports over default exports
- Use TypeScript strict mode — no `any` types
- Use Tailwind CSS utility classes instead of custom CSS
- Keep components under 200 lines — split if larger

### Naming Conventions

- Components: PascalCase (e.g. UserProfile.tsx)
- Hooks: camelCase with `use` prefix (e.g. useAuth.ts)
- Utilities: camelCase (e.g. formatDate.ts)
- Constants: UPPER_SNAKE_CASE

5. Testing Instructions

Tell the agent how to write and run tests.

## Testing

- Run tests: `pnpm test`
- Write unit tests with Vitest
- Use React Testing Library for component tests
- Test user interactions, not implementation details
- Check CI status before marking a task as done

6. PR & Commit Guidelines

Shape how the agent contributes to your project.

## PR & Commit Guidelines

- Use Conventional Commits: feat:, fix:, docs:, refactor:, test:
- Keep commit messages under 72 characters
- Add a description and test plan to every PR
- Reference issue numbers in commits (e.g. "fix: resolve login bug #123")

7. Security Considerations

Prevent the agent from introducing vulnerabilities.

## Security Considerations

- Never commit secrets, API keys, or .env files
- Sanitize all user inputs — never trust client-side data
- Use parameterized queries for all database access
- Always validate auth tokens in middleware, not in route handlers

Best Practices

Keep It Actionable

Write instructions the agent can directly follow. Instead of “We value clean code”, write “Keep functions under 30 lines. Extract helpers for repeated logic.”

Update It Regularly

AGENTS.md is a living document. Update it when you:

  • Add a new dependency or framework
  • Change your testing strategy
  • Adopt new coding patterns
  • Encounter recurring AI-generated issues

Use Monorepo-Aware Placement

For monorepos, place AGENTS.md files at multiple levels:

my-monorepo/
  AGENTS.md            ← Global conventions
  packages/
    frontend/
      AGENTS.md        ← Frontend-specific rules
    backend/
      AGENTS.md        ← Backend-specific rules

AI agents read the nearest AGENTS.md in the directory tree. The closest file takes precedence, allowing you to override global rules with package-specific ones.

Don’t Duplicate Your README

AGENTS.md and README.md serve different audiences:

  • README.md → For humans (project description, setup guide, screenshots)
  • AGENTS.md → For AI agents (build commands, coding rules, security constraints)

Keep them separate and focused.

AGENTS.md vs Other Configuration Files

FileToolScope
AGENTS.mdAll AI agentsUniversal standard
CLAUDE.mdClaude Code onlyAnthropic-specific
.cursorrulesCursor onlyCursor-specific
.windsurfrulesWindsurf onlyCodeium-specific
copilot-instructions.mdGitHub CopilotGitHub-specific

If you only want to maintain one file, choose AGENTS.md — it works everywhere. If your team uses specific tools, you can also add tool-specific files for features unique to that tool.

Generate Your AGENTS.md

Don’t want to write it from scratch? Use our free AGENTS.md Generator to build one visually:

  • 6 quick presets for popular stacks (React, Next.js, Python, Node, Go, Rust)
  • Form-based editor with all recommended sections
  • Live Markdown preview
  • One-click copy or download

It’s the fastest way to create a production-ready AGENTS.md for your project.

Conclusion

AGENTS.md is one of those rare standards that’s both simple and immediately useful. A 20-line file can save hours of AI-generated code review. A well-maintained AGENTS.md turns AI coding agents from “helpful but messy” assistants into genuinely productive team members.

Start with the basics — project overview, build commands, and a few coding conventions. You can always add more sections as you learn what your AI agents need most.

Get started: Generate your AGENTS.md now →