agent instruction file
In plain wordsA plain-text file kept in a software project that tells AI coding agents how the project works — how to build and test it, which conventions to follow, what to avoid — read at the start of every session.
A Markdown file, placed in a repository, a user's home directory or an organization's managed configuration, whose contents a coding agentcoding agent, n.: An AI agent that writes and fixes software by itself: it reads a codebase, edits files, runs commands and tests, and keeps working until a feature is built or a bug is fixed. or other AI agentAI agent, n.: An AI system that does not just answer but acts: given a goal, it decides on steps, uses tools such as a browser or code editor, checks the results and keeps going until the job is done. loads into its context windowcontext window, n.: How much an AI model can read and keep in view at once: the instructions, the conversation so far and any attached documents. Text that does not fit has to be cut, summarized or left out. at the start of each session as persistent instructions: build and test commands, architecture notes, coding conventions, review rules, forbidden actions. Conventions include AGENTS.md, an open, tool-neutral format; CLAUDE.md for Claude Code, which since September 2026 falls back to AGENTS.md when a project has no CLAUDE.md; GEMINI.md for Gemini CLI; and Cursor's rules files. Files can be nested, the one nearest the code being edited taking precedence in large repositories, and some formats support importing other files. In the AGENTS.md project's phrase they are a 'README for agents', separating machine-oriented guidance from human documentation. Their instructions are advisory — the model may still deviate, and long files dilute attention — so teams keep them short and pair them with deterministic hookshook, n.: A user-supplied script or check that runs automatically at set moments in an AI agent's work — before a command, after a file edit, when it tries to stop — enforcing rules the AI cannot skip. and permissionspermission system, n.: The rules that decide what an AI agent may do on its own, what it must ask a person about first, and what it may never do — like a phone's settings for which apps can use the camera..
Put the test command and the rule about generated files in the agent instruction file so every session knows them.
Origin
Cursor's .cursorrules file (in use by 2024) and Claude Code's CLAUDE.md (February 2025) were early examples. OpenAI's Codex launch (May 2025) promoted AGENTS.md, released in August 2025 as an open format developed with Amp, Google's Jules, Cursor and Factory; it was donated to the Agentic AI FoundationAgentic AI Foundation, prop. n.: A nonprofit group under the Linux Foundation that looks after shared, open technical standards for AI agents, such as the Model Context Protocol, so that no single company controls them. in December 2025, when more than 60,000 open-source projects used it.
Usage note
Because these files are read as trusted instructions, a malicious change to one is a form of prompt injectionprompt injection, n.: Tricking an AI system by slipping in text that it mistakes for instructions — for example, a hidden line in an email telling an AI assistant to forward the user's messages to a stranger.; edits deserve code review. Distinct from agent memoryagent memory, n.: The ways an AI assistant or agent keeps information — your preferences, past conversations, lessons from earlier tasks — and brings it back later, beyond what fits in a single conversation. that an agent writes for itself.
Related
- context engineeringcontext engineering, n.: Managing an AI model's reading material: choosing, trimming and arranging the instructions, documents, tool results and memories it is given on every turn, so that it has what the task needs and little else.
- agent skillagent skill, n.: A packaged how-to guide for an AI agent — written steps, sometimes with small programs and examples attached — that sits unread until a job of that kind comes up, when the agent opens it.
- hookhook, n.: A user-supplied script or check that runs automatically at set moments in an AI agent's work — before a command, after a file edit, when it tries to stop — enforcing rules the AI cannot skip.
- system promptsystem prompt, n.: Background instructions given to a chatbot before the conversation starts, setting its role, rules, tone and tools. Users usually never see it, but it shapes every reply.
- coding agentcoding agent, n.: An AI agent that writes and fixes software by itself: it reads a codebase, edits files, runs commands and tests, and keeps working until a feature is built or a bug is fixed.
- agent memoryagent memory, n.: The ways an AI assistant or agent keeps information — your preferences, past conversations, lessons from earlier tasks — and brings it back later, beyond what fits in a single conversation.
- Agentic AI FoundationAgentic AI Foundation, prop. n.: A nonprofit group under the Linux Foundation that looks after shared, open technical standards for AI agents, such as the Model Context Protocol, so that no single company controls them.
- system promptsystem prompt, n.: Background instructions given to a chatbot before the conversation starts, setting its role, rules, tone and tools. Users usually never see it, but it shapes every reply.
Sources
- AGENTS.md. A simple, open format for guiding coding agents. agents.md
- Linux Foundation (2025). Linux Foundation Announces the Formation of the Agentic AI Foundation. linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
- Anthropic. How Claude remembers your project. Claude Code documentation. code.claude.com/docs/en/memory
Mentioned in
coding agentcoding agent, n.: An AI agent that writes and fixes software by itself: it reads a codebase, edits files, runs commands and tests, and keeps working until a feature is built or a bug is fixed., agent skillagent skill, n.: A packaged how-to guide for an AI agent — written steps, sometimes with small programs and examples attached — that sits unread until a job of that kind comes up, when the agent opens it., agentic codingagentic coding, n.: Writing software by directing AI agents that plan, edit and test code themselves, with the human acting more as a reviewer and manager than as the person typing every line., AI coding assistantAI coding assistant, n.: AI software that helps people write computer programs — suggesting the next lines, explaining code, finding bugs or making changes on request — inside the tools programmers already use., Claude CodeClaude Code, prop. n.: A coding assistant from Anthropic that works as an agent: given a programming task, it explores the project, changes the code and runs programs to check its work, from the web, a desktop app, an editor or a terminal., CodexCodex, prop. n.: A name OpenAI has used twice: first for a 2021 AI model that wrote code and powered the original GitHub Copilot, then from 2025 for its family of coding agents., Agentic AI FoundationAgentic AI Foundation, prop. n.: A nonprofit group under the Linux Foundation that looks after shared, open technical standards for AI agents, such as the Model Context Protocol, so that no single company controls them., CursorCursor, prop. n.: A code editor built around AI, in which programmers can ask a model to write, change or explain code across a whole project, or hand it tasks to finish on its own., hookhook, n.: A user-supplied script or check that runs automatically at set moments in an AI agent's work — before a command, after a file edit, when it tries to stop — enforcing rules the AI cannot skip., spec-driven developmentspec-driven development, n.: Building software with AI coding agents by first writing a detailed description of what it should do, which the AI then follows to plan and write the code.