Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Instruction File

Pattern

A reusable solution you can apply to your work.

Understand This First

Context

At the agentic level, an instruction file is a durable, project-scoped document that provides guidance to an agent across all sessions. It’s the primary mechanism for context engineering at the project level: a way to give the agent persistent knowledge about your project’s conventions, architecture, constraints, and preferences.

Instruction files solve a fundamental problem of model statelessness. A model doesn’t remember previous conversations. Every session starts from zero. Without instruction files, you must re-explain your project’s conventions at the start of every interaction, or accept that the agent will use its defaults, which may not match your project.

Problem

How do you give an agent durable knowledge about your project so that it works consistently across sessions without being re-instructed every time?

Project conventions (coding style, architectural patterns, naming rules, testing practices, deployment procedures) are knowledge that every team member, human or agent, needs. For humans, this knowledge accumulates through experience and documentation. For agents, it must be explicitly provided in every session. Without a standard mechanism for providing it, this knowledge is either repeated manually or omitted.

Forces

  • Model statelessness means the agent starts fresh every session.
  • Convention drift occurs when conventions exist only in human heads and are communicated inconsistently.
  • Context window cost: restating conventions manually consumes window space that could go to the task at hand.
  • Maintenance: conventions change over time, and outdated instructions actively mislead the agent.

Solution

Create instruction files at the project root and, optionally, in subdirectories for subsystem-specific guidance. The harness loads these files automatically at the start of every session, injecting their content into the agent’s context.

A typical project instruction file includes:

Project purpose and architecture. A brief description of what the project does, who it’s for, and how it’s structured. This is the agent’s orientation, the equivalent of an onboarding document.

Coding conventions. Language, style, naming rules, indentation, import ordering, and any project-specific patterns. Be specific: “Use 2-space indentation in all markdown files” is actionable; “follow standard conventions” is not.

Build and test commands. How to build, test, lint, and deploy the project. The agent needs to know which commands to run during its verification loop.

Constraints and warnings. Things the agent should not do: “Don’t modify generated files,” “Don’t use library X,” “Don’t commit to main directly.”

Key directories. Where source code, tests, documentation, configuration, and generated output live.

Keep instruction files concise. They’re loaded into every session, consuming context window space. Focus on the information that affects day-to-day work rather than writing exhaustive documentation.

Tip

Layer your instruction files: a top-level file for project-wide conventions, and subdirectory files for subsystem details. The harness typically loads the relevant files based on the working directory, so each agent session gets the context appropriate to its scope.

How It Plays Out

A developer creates a CLAUDE.md file at the project root with coding conventions, build commands, and architectural notes. The next time they start a session, the agent immediately follows the project’s naming conventions, uses the correct test framework, and avoids patterns the instruction file warns against. The developer no longer needs to start every session with “By the way, we use TypeScript strict mode and two-space indentation.”

A team discovers that their agent keeps suggesting a deprecated library. They add “Don’t use library X; it was replaced by library Y in Q3 2025” to their instruction file. The problem disappears across all team members’ sessions because the instruction file is shared through version control.

Example Prompt

“Create a CLAUDE.md file for this project. Include our coding conventions (TypeScript strict mode, two-space indentation, no default exports), the build and test commands, and a note that we use Prisma for database access.”

Consequences

Instruction files create consistency across sessions and team members. They reduce the overhead of starting new conversations and improve agent output quality by providing context automatically. They also serve as documentation that benefits human team members, not just agents.

The cost is maintenance. Instruction files must be kept current. An instruction file that describes last year’s architecture actively misleads the agent. Treat them as living documents, updated alongside the code they describe. And keep them focused: an instruction file that tries to capture everything becomes too large to be useful, consuming context window space without proportional benefit.

  • Depends on: Harness (Agentic) — the harness loads instruction files automatically.
  • Uses: Context Engineering — instruction files are the primary mechanism for project-level context engineering.
  • Contrasts with: Memory — instruction files are written by humans; memory is accumulated from experience.
  • Contrasts with: Skill — instruction files are project-wide; skills are task-specific.
  • Enables: Verification Loop — instruction files typically include the commands needed for verification.
  • Informed by: Ubiquitous Language — a domain glossary is a form of instruction file that shapes agent behavior through vocabulary.