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

