Every AI coding tool wants a Markdown file with your project’s rules. But they all want a different Markdown file.

If you’re using multiple AI tools (and most developers are), this gets confusing fast. Here’s the definitive guide to which files you need and what goes in each one.

The Files at a Glance

File	Tool	Location	Scope
`AGENTS.md`	Universal (all tools)	Project root	Shared rules for all AI agents
`CLAUDE.md`	Claude Code	Project root	Claude-specific instructions
`.cursor/rules/*.md`	Cursor	`.cursor/rules/` directory	Cursor-specific rules
`.github/copilot-instructions.md`	GitHub Copilot	`.github/` directory	Copilot-specific instructions
`.windsurf/rules`	Windsurf	`.windsurf/` directory	Windsurf-specific rules
`JULES.md`	Google Jules	Project root	Jules-specific instructions

AGENTS.md: The Universal Standard

Best for: Teams using multiple AI tools, open-source projects

AGENTS.md is the closest thing we have to a universal standard. It’s now used by over 60,000 repositories and is stewarded by the Linux Foundation’s Agentic AI Foundation (alongside MCP and goose).

Put your shared instructions here --- things every AI tool should know:

Project structure and architecture
Build and test commands
Code style conventions
Common patterns and anti-patterns
Dependencies and setup steps

Every major AI coding tool will read AGENTS.md, making it the single source of truth for your project’s AI instructions.

CLAUDE.md: Claude Code’s Memory

Best for: Claude Code users, teams standardizing on Anthropic

CLAUDE.md is read automatically at the start of every Claude Code session. It supports some Claude-specific features like memory persistence and session context.

Use CLAUDE.md for:

Claude-specific behavioral tweaks
Features that only Claude Code supports
Override or extend AGENTS.md for Claude

The recommended pattern: shared rules in AGENTS.md, Claude-specific additions in CLAUDE.md.

.cursorrules / .cursor/rules/: Cursor’s Approach

Best for: Cursor users, teams using Cursor as their primary IDE

Cursor originally used a single .cursorrules file, then evolved to a .cursor/rules/ directory for more granular control. Each file in the directory is a separate rule that Cursor applies.

Use Cursor rules for:

Cursor-specific agent behavior
Rules for Cursor’s Composer and Agent modes
File-type-specific instructions (e.g., different rules for .tsx vs .py)

copilot-instructions.md: GitHub’s Convention

Best for: GitHub Copilot users, GitHub-centric workflows

GitHub Copilot reads .github/copilot-instructions.md for project-level instructions. It follows GitHub’s convention of putting configuration in the .github/ directory.

The Recommended Setup

For most projects, you need at most two files:

If you use one AI tool:

Just use that tool’s native file (CLAUDE.md for Claude Code, .cursor/rules/ for Cursor, etc.).

If you use multiple AI tools:

AGENTS.md --- all shared rules (architecture, build commands, conventions)
Tool-specific file --- only for features unique to that tool

Example structure:

your-project/
  AGENTS.md              # Shared: build commands, architecture, conventions
  CLAUDE.md              # Claude-specific: memory preferences, tool usage
  .cursor/rules/style.md # Cursor-specific: composer behavior
  .github/copilot-instructions.md  # Copilot-specific

What to Include in Your Rules

Based on analysis of thousands of repositories, the most effective instruction files include:

Always include:

How to build and run the project
How to run tests
Key architectural decisions
Coding style preferences

Often helpful:

What NOT to do (negative instructions work surprisingly well)
File structure explanations
Common debugging steps
Dependency management commands

Skip:

Obvious language features
Things the AI already knows
Overly detailed rules (start minimal, add as needed)

Building Your AI Rules with Web Context

Writing good AI instruction files often requires referencing external documentation, style guides, or architectural patterns. This is where having web content in Markdown format helps.

For example, if your project follows a specific API pattern from a documentation page, you can:

Use Save to convert that documentation page to Markdown
Reference or excerpt the relevant sections in your AGENTS.md
Your AI coding assistant now has the full context

The same applies for framework documentation, style guides, best practices articles, and Stack Overflow solutions. Clean Markdown is the format that both you and your AI tools can work with most effectively.

The Takeaway

The AI coding rules ecosystem is still evolving, but the pattern is clear: it’s all Markdown. Whether you use one tool or five, your project’s AI instructions live in Markdown files that are version-controlled, human-readable, and machine-parseable.

Start with AGENTS.md for universal rules, add tool-specific files as needed, and keep everything minimal until you see a repeated problem worth solving.

Save converts any webpage to clean Markdown --- perfect for building the reference material and documentation context your AI coding assistants need. Try Save free.