Microsoft AB-100: GitHub Copilot Repository Instructions
Repository instructions are one of the highest-leverage ways to make GitHub Copilot behave like it understands a codebase instead of treating every task as a fresh repository. GitHub currently supports repository-wide instructions in .github/copilot-instructions.md, path-specific instruction files under .github/instructions/, and agent instructions such as AGENTS.md. Those layers can apply across chat, coding agents, and code review depending on the feature and client.
The goal is not to write a second README. Good instructions capture durable constraints that repeatedly change the quality of generated work: how to build, test, validate, navigate, structure changes, and avoid known project-specific mistakes. They are part of the repository’s operating context.
This makes repository instructions a practical extension of Microsoft Business AI for engineering teams using GitHub Copilot at scale.
Start with repository-wide guidance
The repository-wide file should contain rules that apply to most work in the repository. Useful content includes the project’s purpose, important technologies, test commands, formatting expectations, architectural boundaries, generated-code rules, and conventions that cannot be inferred easily from one file.
Copilot context is strongest when standing knowledge prevents repeated exploration rather than repeating information already obvious from the directory tree.
Keep this file concise. If a rule applies only to one subsystem, move it to a narrower instruction layer.
Use path-specific instructions for local rules
Path-specific instruction files can apply different guidance to matching files or directories. This is valuable in monorepos or mixed-technology repositories where frontend, backend, infrastructure, database, and test code have different expectations.
A migration directory can require rollback notes. Infrastructure code can require policy validation. Generated code can be marked as non-editable. Those rules should not occupy every request in unrelated paths.
The applyTo pattern makes the scope explicit and easier to review.
Use AGENTS.md for agent-facing context
GitHub supports AGENTS.md for AI agents, and the nearest relevant file in the directory tree can provide local instructions. This gives teams a way to describe how an agent should work in a repository or subsystem without overloading the repository-wide file.
Use it for durable operational guidance: where to start, how to validate, what should not be edited, and which commands represent the supported workflow.
Do not turn the file into a task backlog. Current-request details still belong in the prompt or issue.
Document the commands that actually work
Build and test commands are some of the most valuable repository context because they prevent predictable failed attempts.
Include the package manager, working directory, required setup, test runner, lint command, type checking, generated-code steps, and any prerequisite local service that matters.
Copilot code review also benefits because instructions can point the reviewer toward the checks maintainers expect before approval.
Explain intentional architecture
AI tools often try to “clean up” patterns that look unusual but are deliberate. Repository instructions should identify stable interfaces, dependency rules, compatibility constraints, or legacy boundaries that must remain intact.
A short explanation of why a rule exists helps Copilot choose a compliant implementation instead of working around the rule.
This is particularly important when the repository contains generated clients, migration layers, compatibility shims, or security-sensitive abstractions.
Avoid instruction conflicts
Several instruction layers can apply to one request. Repository-wide, path-specific, organization, and agent instructions can conflict if ownership is unclear.
Keep broad principles in the broadest layer and place exceptions as close as possible to the code they govern.
When output becomes inconsistent, inspect the combined instruction set before assuming the model is randomly ignoring guidance.
Treat instructions as code
Instruction changes affect future AI behavior, so review them through pull requests. Record why a change is being made and test representative tasks where the instruction should help.
Stale paths, renamed commands, and obsolete architecture rules should be removed. A wrong instruction can waste more time than having no instruction at all.
ALM patterns apply here in a lightweight form: version the behavior-changing configuration, validate it, and preserve a clear history.
Do not put secrets in instructions
Instruction files live in the repository and may be exposed to every user or automation that can read it.
Document where secrets come from and which environment variables are required, but never embed tokens, passwords, private keys, or confidential production values.
Security guidance should explain the boundary without placing the protected material inside the context.
Measure whether instructions improve work
Useful instructions should reduce failed builds, unnecessary repository exploration, repeated review comments, and corrections for known conventions.
Copilot metrics can show adoption, while repository outcomes such as failed CI, rework, review time, and developer feedback show whether the context is actually improving engineering.
For GitHub Copilot teams, repository instructions should become a small maintained layer of project infrastructure: concise, scoped, reviewable, and tied to real work.
Repository instructions should also define the repository’s supported validation path. If contributors sometimes run a fast unit-test suite and sometimes require a full integration environment, explain when each level applies. AI tools become much more useful when they know which command gives a quick confidence check and which command represents release-quality validation.
Instructions can also capture file ownership boundaries. If configuration files are generated from another source, or if a package exposes a stable public API that should not change casually, state that clearly. The model can then propose changes within the intended boundary rather than editing whichever nearby file looks easiest.
Large repositories benefit from context hierarchy. Organization instructions can define company-wide security or coding expectations, repository instructions can define project norms, path-specific files can define subsystem rules, and task prompts can define the immediate goal. Each layer should add information rather than restate the same policy.
Keep instruction files compatible with human workflows too. The best repository guidance usually helps new engineers understand the project as well as it helps Copilot. Build commands, architecture boundaries, generated-file rules, and test expectations are useful documentation regardless of whether AI is involved.
For code review, remember that custom instructions come from the pull request’s head branch. This allows a team to test instruction changes with the code they affect, but it also means reviewers should notice when a branch changes the instructions that guide Copilot’s own review. High-risk repositories may want human attention on instruction-file changes themselves.
Path-specific instructions should avoid becoming a fragmented policy maze. If several files repeat the same rule, move the rule upward. If one file grows large, ask whether the subsystem needs a short architecture document and a smaller instruction pointer rather than embedding every detail in always-on context.
Use examples when they clarify a convention that is otherwise easy to misunderstand. One small example of a preferred error-handling pattern can be more useful than several abstract sentences. Avoid large code samples that quickly become stale and consume context every time Copilot works in the repository.
Instruction testing can be lightweight. Pick a few representative tasks—adding an endpoint, modifying a database migration, changing a UI component, fixing a test—and compare whether Copilot follows the intended build, style, and architecture rules. If the new guidance does not improve those tasks, simplify it.
Finally, assign ownership to repository context. Someone should review the instruction files when build tooling changes, frameworks are upgraded, or the repository is reorganized. AI context should not become abandoned documentation. A short accurate file is far more valuable than a detailed file that confidently directs Copilot toward commands and paths that no longer exist.
Organization-level instructions can reduce duplication across repositories when the same security, documentation, or review principles apply everywhere. Keep organization guidance broad and stable, then let repositories override only what is genuinely project-specific. That hierarchy makes maintenance easier and reduces the chance that one repository silently diverges from company policy.
Instruction changes should also be tested against agent workflows, not only chat. A rule that improves conversational answers can make a coding agent overly conservative or cause code review to comment on every file. Check the Copilot surfaces the repository actually uses before treating the change as an improvement.
For mature repositories, keep a short ownership note near the instructions. Identify who reviews changes, how often the files are checked, and where maintainers should report a conflict or stale rule. This turns AI context into a maintained project asset instead of a one-time setup task.
Keep organization and repository instructions auditable through ordinary code history. If an instruction change produces worse suggestions or review noise, maintainers should be able to identify the exact diff and restore the previous behavior quickly.
For repositories that use several Copilot surfaces, document which instruction types each surface actually supports. GitHub support varies by client and feature, so a team should not assume that one path-specific file automatically influences every IDE, cloud agent, and review experience.