--- slug: instruction-file type: pattern summary: "A durable, project-scoped document that gives an agent persistent knowledge of your conventions, architecture, and constraints across every session." created: 2026-04-04 updated: 2026-05-22 related: aggregate: relation: supports note: "Documenting aggregate boundaries in the instruction file helps agents respect them." architecture-decision-record: relation: enabled-by note: "ADRs feed directly into the instruction files that govern agent behavior." best-current-practice: relation: related note: "Instruction files encode best current practices for agents and need updating as those practices evolve." bounded-agency: relation: informs note: "An instruction file is where the agency envelope lives in version-controlled form so the agent reads it at startup." coding-convention: relation: enabled-by note: "A coding convention is a primary input to the instruction file an agent loads." context-engineering: relation: uses note: "Instruction files are the primary mechanism for project-level context engineering." enabling-team: relation: used-by note: "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." eval: relation: used-by note: "Eval results reveal whether instruction files are pulling their weight; eval is the test for instruction-file changes." feedforward: relation: used-by note: "Instruction files are the primary vehicle for persistent feedforward — the durable layer where \"what to consider\" lives." garbage-collection: relation: used-by note: "Instruction files are one of the cleanup targets — codified standards drift fast when no one revisits them." harness-agentic: relation: depends-on note: "The harness loads instruction files automatically." harnessability: relation: related note: "Instruction files codify conventions that might otherwise be invisible to agents — they make implicit knowledge legible." inverse-conway-maneuver: relation: used-by note: "For agent teams, instruction files are the mechanism that implements the organizational boundary." memory: relation: contrasts-with note: "Instruction files are written by humans; memory is accumulated from experience." naming: relation: enabled-by note: "A naming guide is a form of instruction file that shapes how agents write code." platform-as-a-product: relation: complements note: "A platform team can maintain organization-wide agent configuration templates, giving every team a strong starting point for directing agents." progressive-disclosure: relation: uses note: "Keep the top-level instruction file short and push task-specific detail into deeper documents loaded only when relevant." skill: relation: contrasts-with note: "Instruction files are project-wide; skills are task-specific." ubiquitous-language: relation: informed-by note: "A domain glossary is a form of instruction file that shapes agent behavior through vocabulary." verification-loop: relation: enables note: "Instruction files typically include the commands needed for verification." --- # Instruction File > **Pattern** > > A named solution to a recurring problem. *Also known as: Knowledge Priming, Encoding Team Standards* ## Understand This First - [Harness (Agentic)](harness-agentic.md) -- 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](agent.md) across all sessions. It's the primary mechanism for [context engineering](context-engineering.md) 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](model.md) 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](harness-agentic.md) 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](verification-loop.md). **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. ## 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](https://code.claude.com/docs/en/memory). - Cursor introduced the `.cursorrules` file as a repo-level rules document for its AI editor, later superseding it with [Project Rules](https://docs.cursor.com/context/rules) — `.mdc` files under `.cursor/rules/` that offer scoped, versioned instructions. - GitHub Copilot adopted the same idea through [`.github/copilot-instructions.md`](https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-repository-custom-instructions-for-github-copilot) 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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-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](https://martinfowler.com/articles/reduce-friction-ai/knowledge-priming.html)* and *[Encoding Team Standards](https://martinfowler.com/articles/reduce-friction-ai/encoding-team-standards.html)* (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. --- - [Next: Memory](memory.md) - [Previous: Hook](hook.md)