Agent instructions file
Also known as: AGENTS.md, CLAUDE.md, rules file
A plain text file kept with the code that tells AI tools the project's rules, commands and habits before they start work.
Draft - this entry has not been reviewed yet.
Formal
A file stored in the project under version control that a coding agent automatically loads into its context window each time it starts work, holding standing guidance such as build and test commands, style rules, folder layout and things never to do.
In plain English
Like the folder kept aboard a sailing club's shared boat, which every member reads before taking her out - how to start the engine, where the key hangs, never moor by the rocks.
In practice
At a Danish software house, the lead developer adds a short file to the payroll project - “run the tests before finishing, never edit generated files, use the shared date helper” - and the agent now follows it every time without being told.
Why it matters
It turns team knowledge into lasting guidance for AI tools, but anyone who can change the file can change what the agent does - so it needs the same care as code.
Technical deep dive
Every coding tool initially invented its own file: CLAUDE.md for Claude Code, .cursorrules and later .cursor/rules for Cursor, .github/copilot-instructions.md for GitHub Copilot, GEMINI.md for Gemini CLI. AGENTS.md emerged in 2025 as a vendor-neutral convention, and OpenAI contributed it to the Agentic AI Foundation under the Linux Foundation in December 2025 alongside MCP. The format is deliberately minimal: plain Markdown with no required fields or schema. Its website reports use in over 60,000 open-source projects and states two precedence rules: in a nested hierarchy the closest AGENTS.md to the file being edited takes precedence, and explicit user prompts override everything.
Loading semantics differ by tool and matter in practice. Claude Code, for example, loads a managed policy file set by IT, the user's ~/.claude/CLAUDE.md, and every CLAUDE.md or CLAUDE.local.md from the working directory up to the root at launch, while files in subdirectories are loaded on demand when the agent reads files there. Files can pull in others with @path imports, up to four hops deep, and .claude/rules/ holds topic files that can be scoped to path globs. By default it reads AGENTS.md only when no CLAUDE.md is present, and its documentation recommends keeping each file under about 200 lines, because every line consumes context on every session and long files reduce adherence.
Effective files contain what the agent cannot infer cheaply from the code: exact build, test and lint commands, non-obvious conventions, forbidden actions, pointers to where things live, and the definition of done. Restating general best practice or duplicating a linter configuration wastes tokens. Contradictory rules across nested files are a common source of erratic behaviour, and stale commands are worse than none, since the agent will trust them.
Two limitations define the security model. First, the file is context, not configuration: the model is steered by it but not bound by it, so hard guarantees (never read .env, never push to main) belong in permission settings, hooks, sandbox policy or branch protection, not in prose. Second, anyone who can change the file can steer the agent. Researchers at Pillar Security demonstrated in 2025 a "rules file backdoor" that used invisible Unicode characters to hide malicious instructions in rules files, and a cloned third-party repository brings its own instructions with it. Mitigations are to require code-owner review for these files, scan diffs for hidden characters, and treat untrusted repositories as untrusted input before running an agent in them.
What to learn first
Everything this builds on, foundations first.
- Inference
- →Token
- →Network
- →Next-token prediction
- →IP address
- →Protocol
- →Sampling
- →Client
- →Port
- →Structured output
- →Server
- →API
- →Tool calling
- →Coding agent
- →Agent instructions file
Relationships
- Part of
- Context engineering
- Requires
- Coding agent
- Don't confuse with
- System prompt
Sources & further reading
Official documentation
- AGENTS.md - a simple, open format for guiding coding agents (agents.md)
- Anthropic, Claude Code documentation - Manage Claude's memory (CLAUDE.md) · Anthropic
Reference works
Where this data comes from
This entry was drafted by an AI from the sources above and has not yet been checked by a person. Treat it as a starting point, and check anything important against the sources.
See the review queueSuggest a correction on GitHubThis term as JSON
Check yourself
Loading…