Agent Instruction Files

Core Philosophy

1. Write only what agents cannot discover -- ETH Zurich research shows auto-generated context files reduce task success by ~3% and increase costs by 20%+. Include non-inferable details: custom build commands, counterintuitive patterns, tooling choices underrepresented in training data.
2. One canonical file, tool-specific bridges -- Maintain a single AGENTS.md as the source of truth. Use symlinks, imports, or @AGENTS.md references to feed the same content to Claude Code, Cursor, and Copilot.
3. Scope rules to where they matter -- Root-level instructions for project-wide standards. Subdirectory files for team-specific or language-specific conventions. Path-scoped rules (Cursor, Copilot, Claude Code) reduce token noise.
4. Treat instructions as code -- Version-control instruction files. Review changes in PRs. Remove stale rules. Stale structure references actively mislead agents.
5. Concise beats comprehensive -- Keep root AGENTS.md under 200 lines. Context windows are shared with conversation, code, and tool outputs. Every line of instruction competes with actual work.

Quick-Start: Common Problems

"Which instruction file should I create?"