The Complete Guide to AI Coding Instruction Files: CLAUDE.md, .cursorrules, agents.md, and copilot-instructions.md

Every AI coding agent has its own instruction file format. Claude Code reads CLAUDE.md, Cursor reads .cursorrules, Windsurf reads .windsurfrules, and GitHub Copilot reads copilot-instructions.md. If you are using multiple agents — or switching between them — knowing what each file does and how to structure it is essential.

This guide covers every major AI coding instruction file in 2026: what it does, what goes in it, and when to use it.

Quick Comparison Table

CLAUDE.md is for Claude Code (Anthropic). It lives in your project root and is automatically read when Claude Code starts a session. It supports subdirectory files for scoped context. Best for: project-wide conventions, tech stack declarations, coding rules, and architecture constraints.

.cursorrules is for Cursor IDE. It lives in your project root and provides project-specific instructions that Cursor follows when generating or editing code. Best for: coding style preferences, framework-specific patterns, and file structure conventions.

agents.md is for Cursor's newer agent mode. It provides high-level project context and task-oriented instructions. It sits alongside .cursorrules but is focused on multi-step agentic workflows rather than inline completions.

copilot-instructions.md lives at .github/copilot-instructions.md and is read by GitHub Copilot. It provides repository-level context for Copilot's suggestions across VS Code and GitHub.com.

.windsurfrules is for Windsurf (formerly Codeium). Similar to .cursorrules in structure, it provides project-specific instructions for Windsurf's Cascade AI assistant.

CLAUDE.md — Claude Code's Context File

CLAUDE.md is the most feature-rich of all AI coding instruction files. Claude Code automatically reads it from your project root when you start a session. Key features:

Hierarchical: You can place CLAUDE.md files in subdirectories. Claude Code reads all files in the path hierarchy, so src/frontend/CLAUDE.md adds frontend-specific context on top of the root file.

Persistent: The file is read at session start and provides context across all prompts in that session without you needing to reference it.

A good CLAUDE.md includes: project overview, tech stack with versions, coding conventions, file structure map, testing requirements, and deployment details. Keep it under 500 lines — concise instructions beat verbose documentation.

.cursorrules — Cursor's Instruction File

.cursorrules lives in your project root and is read by Cursor for all AI interactions — inline completions, chat, and CMD+K edits. Unlike CLAUDE.md, it does not support subdirectory files.

Best practices for .cursorrules: be specific about patterns (not just tools), include code examples for preferred patterns, state what NOT to do (anti-patterns), and keep it focused on code style rather than architecture.

agents.md — Cursor's Agent Mode Context

agents.md is newer and complements .cursorrules. While .cursorrules guides inline completions and edits, agents.md provides context for Cursor's agent mode — multi-step tasks where the AI plans and executes across multiple files.

Use agents.md for: project architecture overview, workflow instructions (how to add a new feature, how to write tests), and cross-cutting concerns that span multiple files.

copilot-instructions.md — GitHub Copilot

GitHub Copilot reads its instructions from .github/copilot-instructions.md in your repository. This file provides repository-level context that shapes Copilot's suggestions in VS Code and on GitHub.com.

copilot-instructions.md is best for: language and framework preferences, naming conventions, testing patterns, and library choices. Keep it concise — Copilot works with limited context windows compared to full agent tools.

Can You Use Multiple Instruction Files?

Yes. Most teams use multiple AI coding agents and maintain instruction files for each. The files are independent — CLAUDE.md is only read by Claude Code, .cursorrules only by Cursor, and so on. They do not conflict.

The challenge is keeping them in sync. If you update your coding conventions in CLAUDE.md, you need to update .cursorrules too. This is where tools like Keeborg help — when you generate specs, Keeborg creates instruction files for all major agents simultaneously, ensuring they stay consistent.

Which file does each tool actually read?

Each agent only loads its own file, so the practical question is which file to create for the tools you actually run. The current mapping:

Claude Code (Anthropic) reads CLAUDE.md from the working directory, merging any CLAUDE.md files it finds up the directory tree.

Cursor reads .cursorrules in the project root, and newer versions also read scoped files under .cursor/rules.

GitHub Copilot reads .github/copilot-instructions.md at the repository level.

Windsurf reads .windsurfrules, which follows the same project-root pattern as .cursorrules.

Codex-style agents — OpenAI Codex and other tool-neutral runners — read agents.md (often written AGENTS.md), the closest thing to a portable convention.

What happens when a repo has more than one?

Because each tool reads a different file, they do not collide at runtime — Claude Code never parses .cursorrules, and Copilot never parses CLAUDE.md. Conflicts are a content problem, not a parsing one.

Two rules of precedence are worth knowing. Within a single tool, more specific wins: Claude Code merges CLAUDE.md files down the directory tree, and Cursor lets scoped .cursor/rules override the root .cursorrules. Across tools, nothing arbitrates for you — if CLAUDE.md says one thing and .cursorrules says another, each agent simply follows its own file.

That makes drift the real risk, not conflict. Keep one file canonical and generate the rest from it so the instructions never disagree — which is exactly what Keeborg's CLAUDE.md generator does in a single pass, exporting a matching file for every agent.

FAQ

Which AI instruction file should I create first?

Create the file for the agent you use most. If that is Claude Code, start with CLAUDE.md; if your team lives in Cursor, start with .cursorrules. Then generate the others from it rather than writing each by hand.

Do these instruction files conflict with each other?

Not at parse time — each tool only reads its own file. The conflict is when their contents drift apart, so treat one file as the source of truth and derive the rest from it.

Can one file work for every AI coding tool?

Not yet. agents.md is the closest to a shared standard and is read by several tool-neutral agents, but Claude Code, Cursor, Copilot, and Windsurf each still read their own dedicated file. Maintain one canonical set of rules and export a file per tool.

How to Generate These Files Automatically

Writing instruction files manually takes time, especially for new projects where you need to define everything from scratch. Keeborg generates all of these files as part of its 8-document specification suite. Describe your project in plain English, and Keeborg produces CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md — all tailored to your tech stack and conventions.

The generated files are exported directly to your GitHub repository, ready for each AI agent to read immediately.