Instruction File

Pattern: A named solution to a recurring problem.

Also known as: Knowledge Priming, Encoding Team Standards

Understand This First

• Harness (Agentic) – the harness loads instruction files automatically.

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.

Complements: Platform as a Product — A platform team can maintain organization-wide agent configuration templates, giving every team a strong starting point for directing agents.

Complements: Reference Repository — Complements Reference Repository.

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.

Depends on: Harness (Agentic) — The harness loads instruction files automatically.

Enabled by: Architecture Decision Record — ADRs feed directly into the instruction files that govern agent behavior.

Enabled by: Coding Convention — A coding convention is a primary input to the instruction file an agent loads.

Enabled by: Naming — A naming guide is a form of instruction file that shapes how agents write code.

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.

Informs: Bounded Agency — An instruction file is where the agency envelope lives in version-controlled form so the agent reads it at startup.

Related: Best Current Practice — Instruction files encode best current practices for agents and need updating as those practices evolve.

Related: Harnessability — Instruction files codify conventions that might otherwise be invisible to agents — they make implicit knowledge legible.

Related: Reflexion — Reflections that capture a recurring lesson can be promoted into durable guidance in an instruction file.

Supports: Aggregate — Documenting aggregate boundaries in the instruction file helps agents respect them.

Used by: Enabling Team — One of the most concrete deliverables an AI-focused enabling team produces is a well-crafted instruction file that codifies the practices the stream-aligned team should follow when directing agents.

Used by: Eval — Eval results reveal whether instruction files are pulling their weight; eval is the test for instruction-file changes.

Used by: Feedforward — Instruction files are the primary vehicle for persistent feedforward — the durable layer where "what to consider" lives.

Used by: Garbage Collection — Instruction files are one of the cleanup targets — codified standards drift fast when no one revisits them.

Used by: Inverse Conway Maneuver — For agent teams, instruction files are the mechanism that implements the organizational boundary.

Uses: Context Engineering — Instruction files are the primary mechanism for project-level context engineering.

Uses: Progressive Disclosure — Keep the top-level instruction file short and push task-specific detail into deeper documents loaded only when relevant.

Sources

• Anthropic’s Claude Code popularized the CLAUDE.md convention: a markdown file at the project root, with optional subdirectory and ~/.claude/CLAUDE.md global variants, that the harness loads before every session as persistent project memory.

• Cursor introduced the .cursorrules file as a repo-level rules document for its AI editor, later superseding it with Project Rules — .mdc files under .cursor/rules/ that offer scoped, versioned instructions.

• GitHub Copilot adopted the same idea through .github/copilot-instructions.md for repository-wide guidance, with *.instructions.md companions for path-specific rules.

• AGENTS.md emerged as a cross-vendor open format for agent instructions and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It reflects the industry’s move toward a shared convention rather than per-tool formats.

• The underlying idea — a durable, project-scoped document that guides an autonomous process — echoes long-standing conventions like README.md, CONTRIBUTING.md, and .editorconfig, adapted to a new consumer: the agent rather than the human teammate.

• Rahul Garg’s Knowledge Priming and Encoding Team Standards (ThoughtWorks, 2026) name two facets of the same practice described here: seeding the agent with project and domain knowledge, and versioning the team’s conventions so the agent and its human teammates draw from the same source.