# Instruction files

Persistent, always-loaded guidance that tells an agent the commands, structure and boundaries of a repository.

> An instruction file is plain-text guidance that the harness loads into the agent's context at the start of every session. It tells the model how the project works.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files

**Diagram:** Instruction files at each scope are combined and loaded into the context before the first prompt.

- Scopes:
  - User file — your habits, all projects
  - Project file — commands and layout
  - Directory file — rules for one folder
- → at session start
- Context window:
  - Standing guidance — stays for the whole session
  - Model and harness — loop from turn one

**Also called** *custom instructions* (GitHub Copilot, and Codex's docs), *project instructions* or
*memory* (Claude Code) — and often simply by file name: `AGENTS.md`, `CLAUDE.md`,
`.github/copilot-instructions.md`. This site uses **instruction files**, the one term all three
agents' documentation shares.

An instruction file holds what the agent should always know: how to build and test, how the code is laid out, which conventions to follow and what to leave alone. The harness reads it and places it in the context window before your first prompt.

Files exist at different **scopes**: for you across all projects, for one repository, and for one directory inside it. The harness combines them, and a defined precedence resolves conflicts. File names differ per agent; the idea does not. Loaded files stay in the context for the whole session, so they cost space on every turn.

## Why it exists

An agent starts each session knowing nothing about your repository. Asked to run the tests, it guesses: `npm test` in a pnpm project, or a runner that is not installed. It repeats the same guess in every session, and every developer corrects it by hand.

## How it works

**Diagram:** The harness loads the files as plain text, so the model follows them most of the time, not every time.

- Harness looks — known locations for each scope
- → at session start
- Harness joins — specific scopes usually override broader
- → into context
- Model reads text — follows most of the time
- → also
- Extras:
  - Directory file — some agents load it on entry
  - Versioned with code — one source of truth

## Use it when

- The agent needs a fact on nearly every task: commands, layout, conventions.
- A rule is short enough to state in a line or two.
- You want teammates using different agents to start from the same guidance.

## Use something else when

- The guidance is a multi-step procedure needed only sometimes → [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills)
- The behavior must happen every time, without exception → [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks)
- The agent needs live data from another system → [MCP](https://ai-sw-factory.mellicci.dev/fundamentals/mcp)
- The rule is a security limit, not a preference → [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model)

## Key terms

- **Instruction file** — standing guidance loaded into the context automatically.
- **Scope** — user, project or directory level.
- **Precedence** — which file wins when scopes conflict.
- **Boundary** — a limit stated to the model; a request, not enforcement.