An agent instruction file gives a coding agent concise project-specific direction that cannot be inferred safely from source alone. It can define scope, approval boundaries, naming, architecture, security rules, required checks, documentation duties, and how narrower directory instructions inherit or override broader ones.
The file should contain durable guidance rather than temporary plans or duplicated implementation detail. It must be maintained with the project, kept internally consistent, and written so that a future agent can verify requirements through current source and executable checks.
ELI5
An agent instruction file is a saved guide that tells an AI agent how work in a project should be done. It prevents the user from repeating the same important preferences in every conversation.
For example, a design instruction file can say to avoid decorative gradients, use the project's spacing scale, and compare the rendered page with supplied references before finishing.
What belongs in an agent instruction file?
Include durable scope, safety, approval, architecture, naming, workflow, verification, documentation, and repository-specific constraints.
Should an agent instruction file describe every implementation detail?
No. Details that can be inspected from current source should remain there so the instruction file does not become a stale duplicate.
