liveBook · Manning

Instruction file

As explained in Context Engineering

A project-specific document or configuration that gives operational instructions to an AI agent.

An instruction file is an agent-readable document that stores durable directives for a project, repository, organization, or working environment. It turns team conventions into explicit context, reducing the need to repeat rules in each prompt. In coding workflows, these files commonly specify architecture boundaries, build and test commands, review expectations, and safety constraints. section 2.4 section 11.3.2

Instruction files complement other instruction layers. A system prompt establishes general behavior, while agent skills package specialized procedures for on-demand use. Instruction-file content is often appended to the system prompt and sent with each model call, but discovery and context injection vary by agent. This makes file size and tool-specific loading behavior important. section 1.5.1 section 2.4.1

For a shared coding-agent baseline, AGENTS.md can hold repository-wide guidance. Tool-specific conventions include CLAUDE.md for Claude Code, .github/copilot-instructions.md for GitHub Copilot, and .cursor/rules/*.mdc for Cursor. These formats and locations are evolving integration details, not interchangeable guarantees. section 2.4.1 section 11.3.2

Listing 2.4 Sample AGENTS.md instruction artifact for a backend Python service
# Project guidance for AI agents

## Purpose
This repository implements the customer billing service for an
e-commerce platform.

## Architecture rules
- Keep business logic inside the `services/` layer.
- Do not place domain logic inside API controllers.

## Coding conventions
- Use Python 3.12 syntax.
- Prefer explicit type hints on public functions.

## Validation steps
Before submitting changes:
1. Run `pytest tests/unit`.
2. Run `pytest tests/integration` if the database code was modified.
3. Run `ruff check .` and `black --check .`.

## Safety constraints
- Do not modify files under `migrations/archive/`.
- Do not hardcode secrets, tokens, or credentials.

## Pull request expectations
- Summarize the functional change.
- List risks and backward-compatibility concerns.

This backend service example combines architecture rules, Python conventions, validation commands, safety boundaries, and pull-request expectations in one AGENTS.md file. section 2.4.1

Design and maintain instruction files as engineering assets:

  • Write actionable rules with concrete commands, locations, or boundaries. Avoid generic advice that consumes context without directing a decision. section 2.4.2
  • Keep shared rules in version-controlled repository files and tool-specific adaptations in their respective files. Keep personal paths, preferences, and private tokens in untracked local configuration. section 2.4.2
  • Use nested files for localized subproject conventions, and state whether they extend or override root guidance. section 2.4.2
  • Keep files concise, review their changes, and remove stale commands or constraints as the project evolves. Outdated guidance can cause agents to follow obsolete patterns or run failing commands. section 2.4.2

How Context Engineering covers it

How deep it goes
Explains file conventions, scoping, actionable directives, and maintenance, with an illustrative repository file.
Examples
Illustrates an AGENTS.md file for a Python billing service with architecture, testing, safety, and review rules.
What you can do after
Apply it via AGENTS.md and tool-specific files to organize, scope, and maintain repository guidance for coding agents.
How it connects
Connects instruction files to system prompts, agent skills, context windows, and version control.

Also explained in

Compare how 2 books explain instruction file →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Context Engineering. The section links point to the parts of the book it draws on.