What Is a Project Instruction File? CLAUDE.md, AGENTS.md and Rules Explained

A project instruction file is a plain text file, kept in your repository, that a coding agent reads at the start of every session. It tells the agent things it cannot work out cheaply on its own: how to run the tests, which conventions to follow, which folders to avoid. Because the model starts each session knowing nothing about your project, this file acts as its standing memory.

Why a model needs one

A language model does not remember earlier sessions. Each time you start, the conversation is empty. Without help, the agent must rediscover that you use pnpm instead of npm, that tests live in spec/, or that you never use default exports. It might discover this by reading files, or it might guess wrong. A short instruction file fixes that for every session and every teammate.

The common files

Each tool has its own convention. The content is similar; the name and location differ.

Tool	File or location
Claude Code	CLAUDE.md in the project root (and other places, see below)
GitHub Copilot	.github/copilot-instructions.md
Cursor	Rule files in .cursor/rules
Several tools	AGENTS.md, a tool-neutral convention that more and more agents read

Check your tool's documentation for the exact lookup rules, because they evolve. For example, Claude Code can also read user-level and nested-folder instruction files, and some tools can attach rules only to certain file patterns.

What the file contains

Write it as short notes to a new teammate. Useful sections are:

• Commands. Build, test, lint, run one test.
• Architecture in brief. Where the main pieces live and how they connect.
• Conventions. Naming, error handling, style rules a linter does not enforce.
• Boundaries. Folders or files not to edit, such as generated code.
• Process. Branch naming, commit message format, what to run before finishing.

A small example

# Billing service

Node 20, TypeScript, PostgreSQL. Package manager: pnpm.

## Commands
- pnpm install
- pnpm check        # lint + typecheck + tests, run before finishing
- pnpm test src/invoices/invoice.test.ts   # single file

## Conventions
- Money is stored as integer cents. Never use floats for money.
- Use the Result type in src/lib/result.ts instead of throwing in domain code.
- Named exports only.

## Do not edit
- src/generated/ (produced by pnpm codegen)
- migrations that are already merged

That is about 150 words, and it prevents several classes of mistake: float money, wrong package manager, edits to generated files.

How the agent uses it

At the start of a session, the tool loads the file's text and places it in the conversation, usually near the top, before your first message. From then on it takes up part of the context window on every step. That has a cost: a 5,000-word file leaves less room for code and reduces how closely the model follows each line. Short, specific files work better than long ones.

The file is guidance, not enforcement. The model usually follows it, but nothing stops it from slipping. For rules that must never be broken, such as "never run a deploy command", use the tool's permission settings or hooks, which are enforced by the program. Later posts cover both.

Instruction file versus prompt

• Put things that stay true for the whole project in the file.
• Put task-specific details in the prompt.
• If you repeat the same sentence in three prompts, move it to the file.

Commit it

Check the file into version control so the whole team shares it and changes are reviewed like code. Personal preferences, such as a favourite response style, belong in your user-level settings rather than in the shared file.

Common mistakes

• Pasting the whole README or a style guide into it.
• Writing vague rules like "write clean code".
• Never updating it, so it describes last year's project.
• Storing secrets or internal URLs in it.