# Agent Instruction Files

Persistent repository files giving a coding agent standing context — conventions, architecture, commands, constraints.

**Rests on:** Agent Loop, Context Packs

*AI Agents · AI Coding Assistants*


## Why learn this

You want to get reliable code from an AI assistant without having to repeat your team’s specific rules every time you start a new chat. Understanding these instruction files lets you tell the AI exactly how your project works once, so it stops guessing and starts producing work that fits your standards. Imagine you have a complex spreadsheet with unique formatting rules; if you only say 'calculate the total,' the AI might use the wrong format. If you give it a note saying 'use dates in DD/MM/YYYY and round to two decimals,' it gets it right the first time.


## The intuition

When you delegate a task to a human colleague, you usually need to provide context: the project conventions, the quirks of the codebase, the commands to run tests, and the constraints like security rules. For example, you might say, 'Please update the quarterly report, but remember we use British spelling in identifiers' or 'Never modify the database migration folder.' With AI coding agents, you have the same need. Agent instruction files are persistent text files in a repository that give the agent this standing context. Instead of re-explaining your project's style and structure in every chat prompt, the agent reads these files once and applies that context every session. The value is highest when the conventions are non-obvious from the code itself—things like 'we use British spelling in identifiers' or 'never modify the database migration folder.' Without them, the agent will fill in gaps with guesses, and its output will drift from your team's expectations. If your project requires running a specific script to check for errors, writing that command in the file ensures the AI always uses it, rather than trying to guess which tool works best.


## An analogy

Think of a new team member joining your project. On day one, the lead hands them a short handbook: not the entire codebase, but a few pages that say 'we use tabs, not spaces,' 'the build command is make build,' 'never touch the legacy folder.' They read it once and refer back only when uncertain. That handbook is what an agent instruction file is for an AI agent. The analogy works well: both cases, the handbook saves time and prevents repeated mistakes. It breaks down in one way: a human can ask clarifying questions and adapt to contradictions, but an agent will follow the file literally, even if it becomes outdated. So the handbook must be actively maintained—if it falls stale, it misleads the agent worse than having no handbook at all.


## Definition

An agent instruction file is a persistent text file in a code repository that provides an AI coding agent with standing context about the codebase's conventions, architecture, commands, and constraints, so it does not need to be re-explained every session.


## How it connects

You have not yet studied the neighbouring topics, but you will see how agent instruction files tie into them. They are the foundation of Claude Skills, which package reusable instructions into small, clickable tools that run specific tasks automatically. They also matter for Agentic Test Authoring, where an agent explores an application and proposes test cases—for that to work, the agent needs to know the project's test commands and style, which come from instruction files.


## The mathematics

This concept is not mathematical in itself, but it rests on a simple kind of counting and priority-setting that you already use in daily life. Imagine you have a list of things to remember. Some are more important than others. An instruction file is like a weighted list: you decide which items to put first, how many items to include, and what not to include at all. There is no arithmetic here beyond maybe counting how many rules you have written. However, you will often hear the term 'context window' when discussing agents. That is a limited amount of text the agent can hold at once—like a sheet of paper. You cannot write an infinite handbook. So you must prioritise: the most crucial conventions go first, and you might have to decide between including 'use tabs' versus including a long architectural explanation. That is a trade-off you make by counting words and deciding what's most valuable.

Let T be the maximum word count, and let each rule i have cost c_i and importance v_i. You choose a subset S of rules such that the total sum of c_i for i in S is ≤ T, and the total importance is maximised. In plain words: pick the most important rules that fit.


## A worked example

```
Suppose an agent instruction file has a 500-word limit (to fit in context). You have three candidate rules: Rule A costs 50 words, Rule B costs 200 words, Rule C costs 300 words. You want to include as many as possible without exceeding 500 words.

Step 1: Start with no rules: 0 words used, 0 rules included.   # Initial state.
Step 2: Add Rule A (50 words): total = 50, included = 1.   # First choice.
Step 3: Add Rule B (200 words): total = 50 + 200 = 250, included = 2.   # Still under 500.
Step 4: Try to add Rule C (300 words): total = 250 + 300 = 550, which exceeds 500.   # Cannot include all three.
Step 5: So you must drop one. You decide Rule C is least important, so you drop it: total = 250, included = 2.   # Final selection.

Result: You include Rules A and B (total 250 words), leaving 250 words spare for anything else. The decision is about priorities, not arithmetic.
```


## From scratch, in Python

```python
# A simple representation of an instruction file as a Python dictionary
# A dictionary holds key-value pairs, like a real file but in memory.

instructions = {
    "naming": "use_snake_case",
    "commands": ["make build", "make test"],  # a list of commands
    "constraints": "never_modify_database_migrations"
}

# To read a value, we look it up by its key.
print(instructions["naming"])  # prints: use_snake_case

# A list is an ordered collection. We can loop over it.
for command in instructions["commands"]:
    print("Run:", command)
# Output:
# Run: make build
# Run: make test

# A function bundles reusable steps.
def show_commands(doc):
    print("Commands:")
    for c in doc["commands"]:
        print(" -", c)

show_commands(instructions)
# Output:
# Commands:
#  - make build
#  - make test
```


## The same thing, with a framework

```python
In practice, you might use a library like `agent_docs` or the agent's own configuration system, but the underlying idea is the same: you write a text file and the agent reads it. For example, in Claude Code you might have a `CLAUDE.md` file, and the agent automatically loads it at session start. The framework does the file reading for you; you just maintain the file.
```


## What the code does

The Python code demonstrates the core ideas of an instruction file. I create a dictionary named `instructions` with three keys: `naming` (a string), `commands` (a list of strings), and `constraints` (a string). The dictionary is like a real file: it holds named pieces of information. I then print the value of `naming` to show how to access it. Next, I use a `for` loop to go through each item in the `commands` list, printing each one. This is how an agent might read every command and decide what to run. Finally, I define a `function` called `show_commands` that takes a dictionary as input and prints its commands. Functions let me reuse the same logic without rewriting it. In a real agent, this function would be replaced by the agent's own reading mechanism, but the data structure is the same.


## Common misconceptions

**The agent will read my mind** — If I write something in the instruction file, the agent will always know it and never guess otherwise.

The agent reads the file at startup but may not re-read it during a long session, and it may prioritise other system prompts or user messages. Also, the file has a limited context window, so not every detail fits. In fact: The instruction file is one input among many. The agent's behaviour is influenced by the file, the chat prompt, and the model's own priors. For critical constraints, repeat them in the specific task prompt as well.

**Write it once and forget it** — After writing a thorough instruction file, I don't need to update it.

Codebases change: commands change, conventions evolve, new constraints appear. An outdated file actively misleads the agent. In fact: Treat the instruction file as living documentation. Review it whenever the repository structure or tooling changes, and update it to stay accurate.

**More instructions always help** — The more rules I cram into the file, the better the agent will behave.

The agent has a limited context window. Too many rules crowd out the actual task description, and conflicting rules confuse it. In fact: Prioritise: include only the most consequential and non-obvious rules. Keep the file concise enough that the agent can actually absorb it.

**Instruction files are only for coding agents** — This only applies when writing code with an AI assistant.

The same pattern appears in any agentic system, from customer-support chatbots to data-analysis pipelines, where persistent context is needed. In fact: Any agent that operates against a long-lived environment—a repo, a business system—benefits from standing instructions. The file is a general-purpose control surface.


## In short

Agent instruction files are persistent text files that give AI coding agents standing context about a codebase. They save you from re-explaining conventions, commands, and constraints every session. Their value is highest when the context is non-obvious from the code. They must be concise and kept up to date, otherwise they mislead. They are the foundation for agentic coding, skills, and spec-driven workflows.


## Where this is used

Agent instruction files are everywhere in modern AI-assisted development. In large language models like those powering ChatGPT, they are not used directly, but the underlying idea of persistently stored context informs how the model is prompted with system prompts. In small models running on devices (like phone assistants), instruction files may be embedded as configuration to tailor the model's responses to the device's capabilities. In retrieval-augmented generation (RAG), instruction files are analogous to the retrieved context documents—they provide the relevant context for a task. The real power shows in agentic systems: tools like Claude Code or GitHub Copilot agent mode read `AGENTS.md` or `CLAUDE.md` at the start of a session. These files specify commands like 'run tests with `pytest`', architecture rules like 'keep business logic in `src/`', and constraints like 'do not modify generated files'. A developer writes these files once, and every future session with the agent benefits. When done badly—for example, when the file is out of date—the agent consistently runs the wrong commands or violates constraints, leading to wasted time and broken builds. In everyday applied ML work, engineer teams maintain such files to ensure agents follow experiment conventions, such as logging to a specific tracking service and not overwriting model artifacts. The application is everywhere: from individual developers to large enterprises, instruction files are the primary interface for steering AI coding agents.


---

Read this on the web: https://basavapurushottam.com/learn-ai/agent-instruction-files
