Repository Instructions for Coding Agents: What to Write
By Numan ·
Write short repository instructions that help coding agents follow build, test, and safety conventions.
Repository Instructions for Coding Agents: What to Write
A coding agent works better when it can find the repository's actual commands and constraints. GitHub's custom-instructions documentation (https://docs.github.com/en/copilot/concepts/prompting-and-context/custom-instructions) describes repository-wide, path-specific, and agent instruction files, and warns that instructions do not guarantee compliance.
Put facts close to the code
Document the app's purpose, where the relevant modules live, how to run tests, and which commands build the project. State concrete constraints such as “use the staging environment for integration checks” or “never use the production database in tests.” Avoid a long motivational essay that hides the instructions a developer needs.
Make instructions checkable
“Follow best practices” is hard to act on. “Run npm test for changes under app/ and include the result in the PR” is concrete. Point to the authoritative configuration instead of copying values that will go stale.
Scope carefully
Use repository-wide instructions for rules that apply everywhere. Put language- or directory-specific advice near that code when the client supports it. If two files give conflicting directions, resolve the conflict rather than asking the agent to guess precedence across tools.
Verify use, not just presence
Try a small task and inspect whether the agent found the instructions, used the right test command, and respected the boundaries. Review the output as you would any contributor's work. The instructions are context; they are not a permission system or a substitute for CI.
Primary source: GitHub custom instructions (https://docs.github.com/en/copilot/concepts/prompting-and-context/custom-instructions).
Editorial note: Prepared with AI assistance and checked against the linked primary documentation on 15 November 2026.