Intro

Agent instruction files are project-level configuration documents that tell AI coding agents how to behave inside a specific repository. They encode the local contract: coding conventions, architectural boundaries, tool preferences, and domain language. This pattern emerged because generic models become much more reliable when they are grounded in how a particular codebase actually works.

Mechanically, the agent loads instruction files when a session starts (and in some tools, while traversing directories). The content is injected into the agent's operating context, so it influences every decision: which files to edit, what patterns to follow, what commands to run, and how to validate changes. This is why a concise, accurate file improves output quality across all tasks, while stale or contradictory rules degrade it.

Instruction File Landscape

What Good Instruction Files Include

• Tech stack and versions: runtime, framework, package manager, and build/test commands the agent should use first
• Coding conventions: naming, error handling, logging, testing expectations, and formatting policy
• Architecture rules: folder ownership, module boundaries, and allowed dependency directions
• Project-specific knowledge: domain terms, business invariants, and integration constraints that are not obvious from code alone
• Prompt-efficiency discipline: short, actionable rules with clear verbs; avoid long narrative text that wastes context tokens

For modular, reusable behavior packs that complement instruction files, see Skills.

Example

Minimal but effective AGENTS.md for a .NET API project:

# Project Instructions

- Stack: .NET 9, ASP.NET Core, PostgreSQL 16, xUnit
- Run `dotnet test` before proposing any change as complete
- Prefer explicit DTO mapping; never return EF entities from API handlers
- Feature code lives under `src/Features/<FeatureName>/`
- Do not introduce new top-level folders without explicit rationale
- Error responses use ProblemDetails (RFC 9457) with `type` URI
- All new endpoints require at least one integration test

This works because it sets: execution defaults (stack, verification command), data boundaries (DTO mapping), structural constraints (feature folders), error format (ProblemDetails), and quality gates (integration tests). Each rule is actionable — the agent can verify compliance mechanically.

Anti-pattern — a 500-line instruction file that describes ideal architecture, coding philosophy, and team values. This consumes prompt budget, dilutes critical rules, and creates contradictions when the codebase does not match the aspirational description. Keep the core under 30 rules; link to deeper docs for reference.

Pitfalls

• Instruction bloat: very long files consume prompt budget and dilute high-priority rules. Keep a short core and link to deeper docs only when needed.
• Contradictory hierarchy: root and subdirectory files that disagree cause unstable behavior (for example, two different testing commands). Define precedence and eliminate overlaps.
• Aspirational, not actual, guidance: rules that describe an ideal architecture instead of the current repository state lead to wrong edits. Write what is true now, then migrate gradually.
• Stale rules: codebase evolves faster than instructions; outdated commands or paths create repeated failures. Treat instruction files as living operational docs and update with major repo changes.

Tradeoffs

Questions

References

• Manage Claude Code memory (CLAUDE.md, project and user scope) (Anthropic)
• Adding repository custom instructions for GitHub Copilot (.github/copilot-instructions.md) (GitHub Docs)
• Cursor Rules documentation (.cursorrules and .cursor/rules) (Cursor)
• Windsurf Cascade memories and workspace rules (.windsurf/rules/*.md) (Windsurf Docs)
• Claude Code best practices (Anthropic)
• OpenCode documentation (AGENTS-style project instructions) (OpenCode)