Practice Exams:

Microsoft AB-100: GitHub Copilot Repository Instructions

AI & Machine Learning

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.

On this page
  1. Start with repository-wide guidance
  2. Use path-specific instructions for local rules
  3. Use AGENTS.md for agent-facing context
  4. Document the commands that actually work
  5. Explain intentional architecture
  6. Avoid instruction conflicts
  7. Treat instructions as code
  8. Do not put secrets in instructions
  9. Measure whether instructions improve work

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. For example, a good instruction file names the one supported test command, identifies generated files that must not be hand-edited, and explains ownership of security-critical modules. That context lets Copilot and human contributors make useful changes without repeatedly rediscovering the same constraints.

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.

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.

Organization-level instructions can reduce repetition when several repositories share security, documentation or review principles. Keep that guidance broad and stable, and let repositories add project-specific implementation rules without creating contradictory directions. Instruction precedence and support depend on the Copilot client and feature, so teams should validate the effective combination rather than assume every interface resolves conflicts the same way.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

Understand instruction scope in code review

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.

Regression-test repository instruction changes

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.

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.

Give repository context a named owner. 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.

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.

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.

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.

Repository instructions describe development conventions, but they cannot authorize an agent to access business data or enforce production approval. Teams deploying enterprise agents still need governance for identity, tool permissions, release control, and measurable business outcomes. The wider Microsoft AB-100 architecture scope addresses those operational decisions; repository instructions are one implementation aid, not a substitute for tested controls.

Related Posts

• Mastering the Azure AI Engineer (AI-102) Exam

• Microsoft AI-300: Machine Learning CI/CD Needs More Than a Build Pipeline

• Microsoft AI-103: Managed Identities for AI Apps

• Microsoft AI-900: Skills That Still Matter in the Current AI Path

• Microsoft AI-103: Choosing Safety Controls for Azure AI

• Microsoft AI-103: Controlling the Cost of Azure AI Apps

• Microsoft AI-103: MLOps and GenAIOps Together

• Microsoft AI-103: Reranking Azure RAG Evidence

• Microsoft AI-103: Vector Search Design in Azure

• Microsoft AB-100: Copilot Agents and Business Workflows