Agent instruction files are repository documents that tell an AI coding agent how to work inside a software project. Also called AI agent instructions, repository instructions, or files such as AGENTS.md, they supply persistent rules about commands, code style, architecture, tests, and boundaries. They exist because a general-purpose model cannot infer every local convention from source code alone. A checked-in file gives the agent project context before it plans or edits, so the same guidance can apply across tasks and team members.
What an agent instruction file actually is
An agent instruction file is a human-written configuration document whose sentences become working constraints for an AI agent. It usually lives beside the code, uses readable text, and describes facts or procedures that the agent should apply while inspecting, changing, and checking the project.
The file is closer to an operating manual than to a program. It does not normally execute a test, install a package, or alter a source file by itself. Instead, the agent reads the document into its working context. The model then uses those words while deciding which files to inspect, which command to run, what kind of edit fits, and how to judge the result.
A useful instruction answers questions that the repository cannot answer reliably on its own. Which package manager is authoritative? Does a database schema need a generated migration? Which folder contains hand-written code, and which folder contains generated output? Is a full test suite slow enough that a focused command should run first? These are local facts, not universal facts about programming.
The filename is only a convention. The important mechanism is that the agent discovers the file, reads its text, determines its scope, and treats applicable statements as instructions.
Common filenames differ among tools, and some tools also read general project documents. A file may use Markdown because headings, lists, and code spans make instructions easy for both people and language models to parse. The document belongs in version control when its guidance belongs to the project. That lets a code review show instruction changes beside the code changes they affect.
How instruction discovery works
Instruction discovery is the process by which an agent searches known locations, loads recognized files, and selects the text that applies to its current task. The exact filenames and search order depend on the agent, but the underlying pipeline is consistent.
Imagine a repository with a root instruction file and another inside apps/storefront. A request to repair checkout code begins at the repository. The agent reads the root guidance, then finds the nearer file while inspecting the storefront directory. The root might define the package manager and ban edits to generated files. The nested file might name the storefront test command and its component pattern. Both can apply.
The agent checks the repository root, parent locations, task directory, or other locations defined by its own instruction system.
It places applicable content in the model context, often alongside the user request and information gathered from the repository.
It determines which instructions cover the file being read or edited. A rule in a nested directory may apply only within that subtree.
The agent consults the guidance while planning, editing, running commands, and deciding whether the work is complete.
A careful agent states which verification ran and identifies any instruction it could not follow because of missing access, tools, or information.
Discovery is not unlimited memory. Every loaded instruction consumes some of the context available to the model, along with the conversation, source code, command output, and test failures. A short, specific file is easier to keep active than a handbook full of history and repeated advice.
How scope and precedence work
Scope determines where an instruction applies, while precedence determines which instruction wins when two statements conflict. Agents commonly combine broad repository guidance with more specific directory guidance, while higher-authority system or user requests can sit above repository text.
Consider this directory tree:
shop/
AGENTS.md
apps/
api/
AGENTS.md
src/orders.ts
web/
src/cart.ts
The root file can describe rules shared by apps/api and apps/web. The nested file can add API rules for src/orders.ts. It should not silently govern src/cart.ts, because that file sits outside the nested directory. This tree structure lets maintainers place facts near the code that owns them.
| Instruction | Likely scope | Reason |
|---|---|---|
| Use the repository's locked package manager. | Whole repository | Dependency installation is shared. |
| Run the order contract test after changing handlers. | API directory | The command concerns one service. |
Do not edit files in generated/. | The tree containing that folder | A generator owns those files. |
| Keep browser components free of server secrets. | Web application | The boundary belongs to client code. |
Precedence matters most during conflict. Suppose the root says, “Use double quotes in JavaScript,” while the API file says, “The formatter owns quote style; do not hand-format.” The more specific statement may control API files if the tool defines nested instructions that way. A direct user request can also override a project preference, but it should not be assumed to cancel an unrelated safety boundary.
Choose the sentence that is easiest to follow, combine incompatible rules, or ignore the conflict without telling anyone.
Identify authority, compare directory scope, apply the more specific valid rule, and surface a genuine ambiguity before making a risky change.
No universal precedence table covers every agent. A repository author must check the documentation for the tool in use. The transferable idea is simple: instructions are layered inputs, and the agent needs a deterministic way to decide which layer applies.
Agent instruction files versus prompts
A prompt asks for the current task, while an agent instruction file records reusable project guidance. The two enter the same decision process, but they differ in lifespan, ownership, location, and the kind of information they should contain.
“Add an error state to the payment form” is a task prompt. “Payment form components use the shared error summary and must pass the accessibility check” is repository guidance. Copying the second sentence into every future prompt wastes time and invites drift. Putting the first sentence in a permanent file would make the agent think the same task is always active.
| Question | Task prompt | Instruction file |
|---|---|---|
| How long does it apply? | Usually one task or conversation | Across tasks until edited |
| Who changes it? | The person requesting work | Repository maintainers through normal review |
| What belongs there? | Desired outcome and current constraints | Stable commands, boundaries, conventions, and definitions of done |
| Where is it stored? | Conversation or task system | Usually in or near the repository |
An instruction file is also different from a linter configuration. A linter applies explicit programmed checks and can reject code mechanically. Natural-language guidance can cover choices that are hard to encode, such as “reuse the existing billing service instead of opening a second network path.” It is broader, but less deterministic.
The distinction affects maintenance. A changed test command belongs in one authoritative place. If the command appears in five prompts, two READMEs, and several agent files, some copies will eventually be wrong. Good repository design reduces duplicated truth.
How useful instructions turn intent into observable checks
Useful instructions connect a concrete trigger to an action and an observable result. They tell the agent when a rule applies, what to do, and how to verify compliance, using commands and repository paths that actually exist.
Compare “write good tests” with “When changing price calculation in src/pricing, add or update a case in tests/pricing, then run npm test pricing.” The second sentence defines a trigger, a location, and a check. An agent can plan around it and report the result.
This is a reasoning model, not a measured law. If specificity S, actionability A, or verifiability V is effectively zero, usefulness U falls with it.
Specificity does not mean describing every keystroke. It means naming the distinctions that change the result. “Use existing patterns” is vague because a repository may contain old and new patterns. “New HTTP handlers use the service and repository split shown in src/orders” gives the agent a named reference to inspect.
Positive directions often work better than a wall of bans. “Write generated clients to src/generated by running npm run generate:client” supplies a safe route. “Never touch generated code” blocks one error but does not explain how to make the requested API change.
Trigger: a database model changes. Action: create a migration with the repository script rather than editing an old migration. Check: apply the migration to an empty local database and run the model tests. Boundary: never put production credentials in the command or file.
The scenario turns architectural intent into steps that leave evidence. The new migration can be reviewed. The empty-database run can pass or fail. The model tests can be named in the agent's final report. This is much easier to audit than a claim that the change “looks correct.”
How instruction files shape an agent's work loop
Instruction files shape the full work loop by narrowing search, influencing the plan, constraining edits, selecting checks, and defining the final report. Their effect is strongest when guidance appears at the decision where it is needed.
During inspection, a rule such as “the active implementation is under packages/v2” prevents the agent from copying obsolete code. During planning, “schema changes require a migration” adds a required deliverable. During editing, “public functions need type annotations” changes the patch. During verification, an exact focused test command provides the first check.
A single instruction can affect several stages. “Do not edit snapshots by hand; update them through the test runner” tells the agent what not to change, what command path to use, and what generated diff to review. The instruction works because it identifies both ownership and procedure.
Instructions do not guarantee obedience. Language models produce probabilistic outputs, tools may expose only part of a repository, and long contexts can weaken attention to a buried sentence. Mechanical enforcement should remain mechanical. Type checkers, formatters, tests, permission controls, and protected branches still do work that prose cannot reliably replace. The practice of checking AI-written code with focused and system-level tests remains necessary even when the instruction file is excellent.
That proof can be a test result, a formatter check, a schema validation, or a small diff in the correct directory. Human review still judges requirements that tools cannot settle, including names, product behavior, and architectural fit.
How agent instruction files show up in software teams
Software teams use agent instruction files as shared operational memory for routine coding work. The files capture repository-specific facts that experienced maintainers know but that a new contributor or AI agent would otherwise have to rediscover.
In a small application, one root file may be enough. It can name setup commands, the main test command, formatting policy, sensitive paths, and the completion standard. In a monorepo, local files can describe the web client, mobile app, data pipeline, or infrastructure directory without flooding every task with irrelevant text.
The files are especially useful where history has left misleading clues. A project may contain two authentication libraries because a migration is unfinished. Source code alone shows both patterns, so frequency is not proof of preference. A sentence naming the approved pattern can stop new code from extending the older one. This is one reason working safely with AI in older codebases depends on explicit boundaries and targeted checks.
A developer asks an agent to add a shipping method. The repository file says rates must come through ShippingService, currency values use integer minor units, and shipping tests run with a named command. The agent inspects the existing service, adds the method without creating a second rate client, runs the focused tests, and reports the command. Reviewers can compare each action with a written project rule.
Instruction files also affect money and time. A command that launches every integration environment may be inappropriate after a one-line documentation edit. A project can name a fast local check for common changes and reserve the full suite for broader changes or continuous integration. The wider discipline of controlling compute, model, and verification costs starts with matching the check to the risk instead of running commands blindly.
Ownership matters. The team that owns a directory should review instructions for that directory. A rule without an owner tends to survive after the architecture changes. Treating instruction edits as code changes gives maintainers a chance to ask: Is the command valid? Does the path exist? Can a test enforce this? Does a nested file now contradict the root?
Five mistakes people make with agent instructions
Most instruction failures come from vague language, excessive scope, stale facts, hidden conflicts, or reliance on prose where enforcement is available. Each mistake makes the agent spend more effort guessing and gives reviewers less evidence that the result follows project policy.
1. Writing values instead of actions
“Prefer quality” and “keep code clean” express values, but they do not distinguish an acceptable patch from an unacceptable one. Replace them with observable directions. Name the formatter, maximum allowed responsibility of a module if the project defines one, or tests required for a public behavior change.
2. Filling the root file with local detail
A root document that explains every package forces unrelated tasks to carry irrelevant text. Put shared rules at the root and narrow rules near their code. A mobile build command does not help an agent correcting a server query, and it may distract the plan.
3. Copying facts that already have an authority
Duplicated version numbers, command lists, and architecture notes drift. If package.json defines a test script, the instruction can tell the agent which script to use and under what condition. It need not reproduce the script's full command. Link by local path or name the source of truth.
4. Allowing silent contradictions
Conflicts make outcomes depend on which sentence the agent notices. Search all instruction files when changing a shared convention. If the root requires one formatter and a child file requires another, state the intended exception and its scope, or remove the obsolete rule.
5. Treating prose as a security control
“Do not read secrets” is useful guidance, but it does not revoke file access. Sensitive values should be excluded from the agent's environment or protected by permissions. Dangerous operations should require appropriate approval. A sentence can guide behavior; an access control changes what behavior is possible.
Never place credentials in an instruction file. A checked-in document may be copied, indexed, logged, reviewed, or sent to a model as context. Store secrets in an approved secret system and refer only to the variable name or setup procedure.
A maintenance pass can catch all five errors. Read the file as if you are new to the repository. Try every named command in the correct directory. Confirm every path. Search for conflicting statements. Then move enforceable rules into tests or configuration, leaving the document to explain triggers, choices, and local procedures.
Can one instruction file control every coding agent?
One instruction file cannot reliably control every coding agent because tools recognize different filenames, locations, syntaxes, context limits, and precedence rules. Teams can share a small body of project facts, but they must verify how each agent discovers and applies it.
A tool that never loads AGENTS.md cannot follow it merely because the file exists. Another tool may load the root file but ignore nested versions. A third may support path-specific rule files. Even when two tools read the same Markdown, their available commands, permission systems, and planning behavior can differ.
Repository layout, authoritative commands, generated-file boundaries, naming conventions, and definitions of done can often be shared.
Recognized filenames, precedence, approval behavior, supported path filters, and special syntax must match the selected agent.
Portability is best treated as a design goal, not an assumption. Keep shared facts concise and neutral. Add thin tool-specific files only where necessary, and avoid maintaining large copies. A simple test task can reveal which document a tool reads and which rule wins.
What belongs in an instruction file, and what stays out?
An instruction file should contain stable, local, actionable guidance that changes how the agent works. Temporary task details, secret values, long tutorials, copied documentation, and rules already enforced automatically should usually stay elsewhere.
- Include: the authoritative setup, build, test, formatting, and generation commands.
- Include: directory ownership, generated paths, architectural boundaries, and examples of the current approved pattern.
- Include: conditions that change verification, such as extra checks after schema, API, or dependency changes.
- Exclude: passwords, tokens, private keys, production data, and sensitive personal information.
- Exclude: a one-time feature request that belongs in the current prompt or issue.
- Exclude: generic programming advice that does not distinguish this repository from another.
A practical test is to remove a sentence and ask what decision becomes less accurate. If nothing changes, the sentence may be noise. If the answer is “the agent might edit generated code” or “the agent would miss the contract tests,” the sentence carries useful local information.
Length is a budget. More text can reduce performance if important rules become harder to find or no longer fit beside the source material needed for the task. Prefer the smallest document that removes the most consequential uncertainty.
How can a team test its agent instructions?
A team can test agent instructions by checking their references mechanically and giving an agent small tasks with observable expected behavior. The goal is to verify discovery, scope, command accuracy, and compliance rather than trusting that readable prose will always work.
Start with static checks. Confirm that mentioned paths exist, commands are defined, and local links resolve. A simple repository script can scan instruction files for stale directory names. Then use a harmless task: ask the agent to change a sample module governed by a nested rule and inspect its plan before permitting edits.
- Choose one instruction with a visible result, such as running a focused formatter.
- Create or select a low-risk change that triggers that instruction.
- Observe whether the agent finds the right file and states the expected action.
- Check the diff and command output rather than accepting the agent's summary alone.
- Revise wording if the same ambiguity causes repeated failure, then repeat the task.
Tests should include a negative case. If the rule applies only under apps/api, change a file under apps/web and confirm that the API-only command is not treated as mandatory. Scope is correct only when a rule applies where intended and stays out elsewhere.
The takeaway: Treat instruction text like an interface between maintainers and agents. Give it precise inputs, visible outcomes, narrow scope, and regular checks against the repository it describes.
Agent instruction files turn computer science decisions into shared procedure
Agent instruction files connect computer science concepts such as hierarchy, scope, interfaces, testing, and access control to daily software work. Writing one well requires modeling the repository as a system, then expressing decisions in forms that people and agents can check.
The file itself may be plain text, but the ideas behind it are substantial. Directory trees create scope. Precedence rules resolve competing inputs. Context limits create a resource budget. Tests convert a natural-language expectation into evidence. Permissions separate a request from the power to carry it out. These are the same kinds of mechanisms found across the broader computer science topics behind software systems.
Open an instruction file in a project you use and inspect one sentence. Identify its trigger, required action, scope, and proof. If any part is missing, rewrite the sentence so another person could tell, from the repository and command output, whether an agent followed it. That small exercise turns vague advice into an engineering specification.