How to install project instructions for a coding agent

How do I make a coding agent install project instructions for tests and safety

Create the instructions where the agent loads them automatically, then make the rules concrete: which tests to run, what changes are safe, what needs review, and when to stop and ask. For GitHub Copilot, repository-wide instructions live in .github/copilot-instructions.md, and agent instructions can also live in AGENTS.md; GitHub documents both as supported instruction sources for Copilot agents and cloud workflows.

The part people get wrong is writing “be careful” and calling that safety. Agents follow operational instructions better than vague advice. GitHub’s docs recommend spelling out build, format, lint, and test expectations, and OpenAI’s guidance for coding agents says to be explicit about test expectations, acceptance criteria, and when to continue versus ask for help. Put the rules in the repository, not in a chat prompt you have to repeat every time.

Use one file for always-on repository rules, then add narrower files for special paths. GitHub supports repository-wide instructions in .github/copilot-instructions.md, path-specific instructions in .github/instructions/**/*.instructions.md, and agent instructions in AGENTS.md, CLAUDE.md, or GEMINI.md depending on the tool. That split matters when your frontend, backend, and infrastructure code need different test commands or different safety limits.

A practical setup looks like this:

text .github/copilot-instructions.md .github/instructions/api.instructions.md .github/instructions/web.instructions.md AGENTS.md

Put global rules in the repository-wide file, for example, “run unit tests before finishing, never touch secrets, and stop if a database migration is needed.” Put path-specific rules where the code lives, for example, “for files under web/, run the frontend test command and do not change analytics events without approval.” GitHub says nearest AGENTS.md files take precedence in the directory tree, which makes local overrides possible without rewriting the whole project policy.

The test part should name commands, not intentions. Write the exact commands the agent should run, the order to run them in, and what counts as a pass. For example: pnpm test, pnpm lint, pytest, or the repo’s own smoke test command. GitHub’s Copilot docs explicitly use examples like “run pnpm test before committing,” and its cloud-agent guidance says to include how to build, format, lint, and test the codebase.

Safety instructions need concrete boundaries that the agent can verify from the codebase. Say which files are off limits, which actions require human review, and which operations must never happen in an unattended run. Examples that work: do not change authentication flows without an approval step, do not edit .env files, do not widen network access, and do not ship a schema migration unless the migration file and rollback note are updated in the same change. OpenAI’s coding-agent guidance recommends giving clear policy, safety, business, evidence, and side-effect limits when those limits matter.

A good instruction file is short enough to read in one pass and strict enough to be testable. Use plain language, one rule per line when possible, and include commands the agent can copy. A strong example is:

md Run pnpm lint and pnpm test before you finish. Do not change secrets, keys, or production endpoints. If a task needs a migration, stop and ask for review. If tests fail outside the changed area, report the failure and do not broaden the fix unless asked.

That style works because the agent can act on it without guessing. GitHub says whitespace between instructions is ignored, so you can format for clarity. OpenAI’s model guidance also says coding agents respond well to explicit reuse, delegation, and verification instructions, which is another reason to write operational rules instead of motivational ones.

The inconvenient part is that instructions only help if the agent actually loads them. GitHub documents that different Copilot features support different instruction types, so a rule that works in Copilot Chat may not be enough for a cloud agent, CLI, or another third-party tool. If you switch tools, verify which instruction files each tool reads before you rely on them for tests and safety.

Another common failure is making the rules too broad. If you dump your whole engineering handbook into a single file, the agent has to sift through noise and can miss the part that matters for the current task. GitHub’s Copilot CLI guidance warns that instructions can become so large or specific that they distract Copilot from the immediate task, and recommends moving task-specific behavior into skills or custom agents when needed. Keep the always-on file short, then push special workflows into a narrower file.

For safety, put the high-risk checks in the instruction file and the mechanical checks in the repo itself. Use scripts, CI, and pre-commit hooks to enforce what should never be skipped, then tell the agent to run those scripts. For example, a repository can have npm run verify that chains lint, unit tests, and a security scan, and the instruction file can say to run only that command before marking work done. That keeps the agent aligned with the same gate humans use.

If you use GitHub Copilot, start with .github/copilot-instructions.md for the default project rules, add AGENTS.md if you want the same instructions shared across agents, and use .github/instructions/ for per-directory overrides. If you use another coding agent, look for its equivalent project-rules file and give it the same kind of content: exact test commands, file boundaries, review triggers, and stop conditions. The file name changes by tool, but the structure does not.

A clean rollout is simple: add the instruction file, commit it, run the agent on one small task, and check whether it follows the test and safety rules without extra prompting. If it skips a test, edits a protected file, or keeps going after a failure that should stop work, tighten the instructions until the agent behaves correctly. The goal is not to give the agent more text, it is to give it fewer ambiguities.

If you want the rule set to live next to the product docs for humans too, keep the agent file separate and point people to it from your contributor guide. That way the instructions stay versioned with the code, the agent loads them automatically, and reviewers can see exactly what the agent was supposed to do before they inspect the diff. If you also use DevConnect for reciprocal testing, you can keep the same test expectations in the repo and share the same standard with testers without copying policy into chat.

FAQ

Where should I put instructions for one directory only Use a path-specific instructions file under .github/instructions/**/*.instructions.md. GitHub documents that these rules apply only to the matching path, which is the right place for frontend-only, API-only, or infra-only test steps.

Should I put safety rules in the prompt or in the repo Put them in the repo. A prompt is easy to forget, but repository instructions are loaded automatically when the agent works in that codebase. GitHub and OpenAI both recommend explicit, reusable instructions for agent behavior.

What should I include besides test commands Include file boundaries, approval triggers, rollback expectations, and any side effects the agent must avoid. OpenAI’s guidance calls out policy, safety, business, evidence, and side-effect limits as useful context for coding agents.

What if the agent still ignores the instructions Verify that the tool supports the file type you chose, then move the critical rules into the instruction file the tool actually reads. GitHub documents different support across Copilot Chat, CLI, cloud agent, code review, and IDEs, so the wrong file can look correct and still do nothing.