Project instruction files for agents

This guide is for developers who use coding agents on a real project and want the agent to follow the same conventions every session. It covers the four instruction formats in common use, how to write instructions that an agent can actually act on, and what one team has put in its own files.

Why instruction files exist

Agents start every session with no memory of your project. Instruction files fill that gap. Claude Code has two complementary memory systems, CLAUDE.md files and auto memory. Both are loaded at the start of every conversation, and Claude treats them as context rather than enforced configuration.^[2] That last point matters. An instruction is a strong hint, not a guarantee, so the most important rules should also be checkable.

CLAUDE.md for Claude Code

CLAUDE.md is a markdown file of persistent instructions for a project, your personal workflow, or your whole organization. You write it in plain text, and Claude reads it at the start of every session.^[2]

There are several locations, listed from broadest scope to most specific, so a project instruction appears after a user instruction. A managed policy file sits at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows. User instructions are at ~/.claude/CLAUDE.md, project instructions at ./CLAUDE.md or ./.claude/CLAUDE.md, and local instructions at ./CLAUDE.local.md.^[2]

Claude Code loads CLAUDE.md and CLAUDE.local.md from the current directory and every directory above it, and concatenates all the files it finds rather than letting one override another. Files in subdirectories load on demand, once Claude reads, writes or edits a file in that subdirectory.^[2]

To get a starting point, run /init. Claude analyzes the codebase and creates a file with the build commands, test instructions and project conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it.^[2]

For larger projects, the instructions can be split. Markdown files in .claude/rules/ are discovered recursively. Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. paths is the only frontmatter field Claude Code reads. Personal rules in ~/.claude/rules/ apply to every project on the machine.^[2]

AGENTS.md as a shared format

AGENTS.md is an open format for guiding coding agents. The site calls it a README for agents, a predictable place to put the context and instructions that help an agent work on your project.^[5] Its stewardship sits with the Agentic AI Foundation under the Linux Foundation, and the site lists Codex, Jules, Cursor, Gemini CLI and the GitHub Copilot coding agent among the tools that support it.^[5]

To create one, put an AGENTS.md file at the repository root. There are no required fields. It is ordinary Markdown with any headings you like, and the agent simply parses the text.^[5] The site suggests covering the project overview, build and test commands, code style, testing instructions and security considerations. Commit message rules, deployment steps and security gotchas are common additions.^[5]

Claude Code reads AGENTS.md as project instructions, but only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. Reading AGENTS.md directly requires Claude Code v2.1.277 or later.^[2] The docs note that most users only edit CLAUDE.md and settings.json. If a repository already has an AGENTS.md for other coding agents, Claude Code can read that file in its place.^[3]

Codex reads AGENTS.md before doing any work. At global scope it reads AGENTS.override.md if it exists, otherwise AGENTS.md, from the Codex home directory, which defaults to ~/.codex unless CODEX_HOME is set. It uses only the first non-empty file at that level.^[6]

At project scope, Codex walks from the project root, typically the Git root, down to the current directory. It checks each directory for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames, and includes at most one file per directory. It concatenates the files from the root downward, joined with blank lines, so that files closer to the current directory override earlier guidance. Once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB, it stops adding files.^[6]

For monorepos, the site recommends nested AGENTS.md files inside each package. Agents read the nearest file in the directory tree, so the closest one takes precedence and each subproject can carry its own instructions. When instructions conflict, the closest file to the edited file wins, and explicit chat prompts override everything.^[5]

Cursor rules

Cursor separates instructions into four kinds: Project Rules stored in .cursor/rules, User Rules that apply across the Cursor environment, Team Rules managed from the dashboard, and AGENTS.md.^[7]

Project rules are .mdc files in .cursor/rules, and they are version-controlled. A plain .md file in that folder is ignored by the rules system, because it has no frontmatter for description, globs and alwaysApply.^[7] Each rule's type sets when it applies. Always Apply applies to every chat session. Apply Intelligently applies when the agent decides it is relevant from the description. Apply to Specific Files applies when a file matches a pattern. Apply Manually applies when you @-mention it in chat.^[7]

Cursor also supports AGENTS.md in the project root and in subdirectories. Nested files apply when you work on files in their directory or below, and more specific instructions take precedence.^[7] For simple cases, the page presents AGENTS.md as the lighter option, with no metadata or complex configuration.^[7]

The Cursor guidance on quality is blunt. Keep rules under 500 lines, split large rules into composable pieces, and avoid vague guidance. Don't copy an entire style guide when a linter can enforce it, don't document every possible command, and don't repeat what the codebase already shows.^[7]

GEMINI.md for Gemini CLI

Gemini CLI uses GEMINI.md as its default context file. It provides instructional context for project-specific rules, a persona or a coding style guide.^[8]

Gemini CLI loads context files from several locations and concatenates everything it finds, then sends the result with every prompt. The global file is ~/.gemini/GEMINI.md. Environment and workspace context files come from configured workspace directories and their parents. Just-in-time context files are scanned when a tool accesses a file or directory, up to a trusted root.^[8]

The CLI footer shows how many context files are loaded. /memory show displays the full concatenated content, and /memory reload forces a re-scan.^[8] Large files can be split with the @file.md import syntax, which accepts relative and absolute paths. The context.fileName setting in settings.json can rename the file, or list several names such as ["AGENTS.md", "CONTEXT.md", "GEMINI.md"].^[8]

A minimal GEMINI.md for a TypeScript library looks like this:^[8]

# Project: My TypeScript Library

## General Instructions

- When you generate new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.

## Coding Style

- Use 2 spaces for indentation.
- Prefix interface names with `I` (for example, `IUserService`).
- Always use strict equality (`===` and `!==`).

Writing instructions an agent can follow

The Claude Code guidance is to treat CLAUDE.md as the place for what you would otherwise repeat in every session. Keep it to facts the agent should hold in every session: build commands, conventions, project layout and always-do rules. A multi-step procedure, or a rule that matters for only one part of the codebase, belongs in a skill or a path-scoped rule instead.^[2]

Be concrete enough to check. "Use 2-space indentation" can be verified, and "Format code properly" cannot. "Run npm test before committing" is actionable, and "Test your changes" is not. Keep each CLAUDE.md under 200 lines, because longer files take up more context and adherence drops.^[2]

How TellWorld uses its CLAUDE.md

TellWorld keeps two instruction files: a user-level one with rules for all projects, and a project-level one with the project's conventions. The project file caps concurrently running sub-agents at three, and tells the agent to start new ones only after earlier ones finish.^[1] It asks for the cheaper Haiku model for fixed-process work such as checking material, converting formats and batch rewriting, and it keeps more expensive models for tasks that need deep judgment.^[1]

The project file also records a hand-off rule for the queue. When the app that gathers material has not updated its files for about 30 minutes, Claude may take over a queued task, after first marking it as in progress by Claude in the queue file.^[1]

The user-level file sets two standing rules. One is about code comments: write only what the code cannot show, such as where a number comes from, an external contract, or a pitfall already hit. The other fixes a branch naming pattern and says which command-line tool to use for which Git host, so the agent does not have to ask each time.^[1]

We chose these rules because our work runs through several agents at once and nobody wants to repeat the same conventions in every session. The file is short by design, and rules that need checking are written so that someone can check them.^[1]

How TellWorld uses its CLAUDE.md

TellWorld keeps two instruction files: a user-level one with rules for all projects, and a project-level one with the project's conventions. The project file caps concurrently running sub-agents at three, and tells the agent to start new ones only after earlier ones finish.^[1] It asks for the cheaper Haiku model for fixed-process work such as checking material, converting formats and batch rewriting, and it keeps more expensive models for tasks that need deep judgment.^[1]

The project file also records a hand-off rule for the queue. When the app that gathers material has not updated its files for about 30 minutes, Claude may take over a queued task, after first marking it as in progress by Claude in the queue file.^[1]

The user-level file sets two standing rules. One is about code comments: write only what the code cannot show, such as where a number comes from, an external contract, or a pitfall already hit. The other fixes a branch naming pattern and says which command-line tool to use for which Git host, so the agent does not have to ask each time.^[1]

Limits and common problems

Instructions are context, not enforcement. Claude may not follow a rule perfectly, so anything that must hold, such as a permission or a blocked command, belongs in settings or hooks, not in prose.^[2][4]

Claude Code's system prompt is not published. The settings docs suggest standing instructions go in CLAUDE.md files or the --append-system-prompt flag.^[4]

Conflicts are easy to create when several files exist. Gemini CLI concatenates everything it finds, Claude Code concatenates CLAUDE.md files, and Codex and Cursor use precedence rules of their own. Check which files load before you assume a rule applies.^[2][6][7][8]

Next steps

For Claude Code, the memory page explains how the files load, and the .claude directory page shows where each file goes.^[2][3] For settings and precedence, read the settings page.^[4] For Codex, the AGENTS.md guide covers the lookup order.^[6] For Cursor and Gemini CLI, read their rules and context file pages.^[7][8]