copilot-instructions.md: The Complete 2026 Guide to GitHub Copilot Custom Instructions

copilot-instructions.md is GitHub Copilot’s persistent instruction layer — place it at .github/copilot-instructions.md and every Copilot suggestion, chat response, and PR review in that repository automatically follows your rules, without pasting context into every prompt.

What is .github/copilot-instructions.md?

GitHub Copilot’s default behavior is generic: it generates code that matches common patterns across millions of repositories. copilot-instructions.md overrides that default with project-specific rules.

The file lives at exactly one path: .github/copilot-instructions.md. There is no configuration required, no settings to toggle, no plugin to install. Copilot detects the file automatically when it is present in the repository. The file uses plain Markdown — no YAML frontmatter, no special syntax. Copilot reads everything inside it as natural-language instructions.

What kinds of rules belong here? Anything that should be consistent across every AI interaction in the project:

• Language version requirements (Use Python 3.12+ type hints throughout)
• Code style decisions not captured by a linter (Prefer composition over inheritance)
• Testing conventions (Every function must have a corresponding unit test)
• Naming patterns (Use kebab-case for CSS class names, camelCase for JavaScript variables)
• Off-limits patterns (Never use any in TypeScript)
• Security requirements (Sanitize all user input before passing to database queries)

The file is committed to the repository, so it is version-controlled, reviewed in PRs, and shared automatically with every team member who pulls the branch. There is no per-developer setup step.

How Copilot Actually Uses the File (What Works, What Doesn’t)

Understanding where copilot-instructions.md applies — and where it does not — prevents wasted effort writing instructions for surfaces that never read the file.

The critical gap is the CLI. Teams that rely on gh copilot suggest or gh copilot explain in terminal workflows will not see their copilot-instructions.md rules applied. For CLI use cases, maintain separate instructions in shell aliases or a project-level AGENTS.md.

Within IDE completions, Copilot applies the file as background context. The instructions influence suggestions but do not hard-block Copilot from generating code that contradicts them — Copilot does not validate its own output against your rules. Treat the file as a strong bias, not a policy enforcer.

What Copilot does not handle well in copilot-instructions.md:

• Conditional logic (“Use Redux only in files under src/store/”) — Copilot applies instructions globally and cannot scope them by file path
• Tool invocations (“Run npm test before committing”) — this is a CI concern, not an instruction file concern
• Long decision trees — if an instruction requires more than two sentences to express, it may be ignored or partially applied

copilot-instructions.md vs AGENTS.md vs CLAUDE.md

Three files, three scopes. Understanding the distinction prevents duplication and gaps when a team uses multiple AI coding tools.

When to use copilot-instructions.md only: Solo Copilot team. No Cursor, no Claude Code, no other AI tools in the workflow. Keep the file focused and skip the duplication overhead.

When to use both copilot-instructions.md and AGENTS.md: Multi-tool teams where some developers use Copilot and others use Cursor or Claude Code. Put shared project rules in AGENTS.md; put Copilot-specific overrides (or additions) in copilot-instructions.md.

When to use all three: Enterprise codebases where Copilot is the primary completion tool, Claude Code handles agentic tasks (refactoring, test generation, migrations), and CLAUDE.md carries Claude-specific workflow instructions like build commands and tool permissions. All three can coexist without conflict.

AGENTS.md is the strongest cross-tool investment. If you can only maintain one file, make it AGENTS.md — it reaches more tools than either of the other two.

10 Real copilot-instructions.md Templates

1. TypeScript / React Project

# Copilot Instructions

## Language & Runtime
- TypeScript 5.x strict mode. Never use `any` or `unknown` without explicit justification in a comment.
- React 18+ with function components and hooks only. No class components.
- Use `const` by default; `let` only when reassignment is required.

## Imports
- Absolute imports only. Path alias `@/` maps to `src/`.
- Group imports: React, external libraries, internal modules, styles. One blank line between groups.

## Components
- One component per file. File name matches component name in PascalCase.
- Props interface declared inline above the component function.
- Avoid prop drilling beyond two levels — use context or state management.

## Testing
- Every component has a co-located `*.test.tsx` file.
- Use React Testing Library. No Enzyme.
- Test user behavior, not implementation details.

2. Python Django Project

# Copilot Instructions

## Python Version
- Python 3.12+. Use type hints on all function signatures.
- Prefer `pathlib.Path` over `os.path` for filesystem operations.

## Django Patterns
- Class-based views for CRUD. Function-based views for one-off endpoints.
- All models must have a `__str__` method and a `Meta` class with `ordering`.
- Never call `Model.objects.all()` without a filter in production code paths.
- Use `select_related` and `prefetch_related` to prevent N+1 queries.

## API
- Django REST Framework for all API endpoints.
- Serializer validation must be explicit — no relying on default field validation.
- Return meaningful error messages with RFC 7807 Problem Details format.

## Security
- Never interpolate user input into raw SQL queries. Use ORM or parameterized queries.
- All file uploads must be validated for MIME type before saving.

3. Go Microservices

# Copilot Instructions

## Go Version & Style
- Go 1.22+. Follow standard `gofmt` / `goimports` formatting.
- Error handling: always check errors. Never use `_` to discard errors in production code.
- Return errors rather than panicking except for unrecoverable initialization failures.

## Package Structure
- One package per directory. Package name matches directory name.
- Avoid `util`, `common`, `helpers` package names — use domain-specific names.
- Internal packages go under `internal/`. Public packages go under `pkg/`.

## Concurrency
- Document goroutine ownership in comments above the goroutine launch.
- Use channels for coordination; mutexes for shared state protection.
- Always pass context as the first argument to functions that do I/O.

## Testing
- Table-driven tests for all exported functions.
- Integration tests in `*_integration_test.go` files with build tag `//go:build integration`.

4. Security-Focused Team

# Copilot Instructions

## Security Non-Negotiables
- Never hardcode credentials, API keys, tokens, or secrets. Use environment variables or a secrets manager.
- Sanitize and validate all user input at the boundary — not inside business logic.
- Use parameterized queries for all database operations. Raw string interpolation into SQL is a critical violation.
- Set `HttpOnly` and `Secure` flags on all cookies.
- Log security events (authentication, authorization failures, input validation failures) with enough context to reconstruct an attack path, but never log passwords, tokens, or full credit card numbers.

## Dependencies
- Pin dependency versions exactly. No range specifiers in production dependency manifests.
- Flag any new dependency for security review before merging to main.

## Code Review
- When reviewing authentication code, explicitly check for timing attacks in comparison operations.
- OWASP Top 10 is the baseline check list for all web-facing code.

5. Code Review Style Guide

# Copilot Instructions

## When Reviewing Pull Requests
- Lead with the most critical issue first. Do not bury blockers under minor comments.
- Distinguish blockers (must fix before merge) from suggestions (nice to have).
- Explain *why* a change is needed, not just *what* to change.
- Reference project conventions from this file or AGENTS.md rather than personal preference.

## Comment Tone
- Direct and respectful. Avoid "you should" — prefer "this function could" or "consider".
- Use code examples in review comments when the suggestion is non-trivial.

## What to Always Check
- Error handling completeness
- Test coverage for the changed behavior
- Security implications of input handling
- Performance implications of loops over unbounded collections

6. Monorepo with Packages

# Copilot Instructions

## Monorepo Structure
This is a Turborepo monorepo. Packages live under `packages/`, applications under `apps/`.

## Cross-Package Rules
- Never import from `apps/` inside `packages/`. Packages must not depend on applications.
- Shared types go in `packages/types`. Shared utilities go in `packages/utils`.
- When adding a new package dependency, update the root `package.json` workspace first.

## Per-Package Conventions
- Each package has its own `tsconfig.json` extending `tsconfig/base.json`.
- Package `package.json` must include a `build`, `test`, and `lint` script.
- Exported functions from `packages/` must be documented with JSDoc.

## Change Scope
- Changes to `packages/` may affect multiple apps — include cross-app impact in PR descriptions.
- Run `turbo build` and `turbo test` before marking a PR ready for review.

7. Testing-Heavy Project

# Copilot Instructions

## Test Requirements
- Every new function or method requires at least one unit test.
- Every bug fix requires a regression test that would have caught the bug.
- Test file naming: `*.test.ts` for unit tests, `*.spec.ts` for integration tests.

## Test Quality
- Arrange-Act-Assert pattern. One assertion concept per test.
- Tests must be deterministic — no sleep, no random, no external network calls without mocking.
- Test names follow: `describe('[function name]') > it('[expected behavior] when [condition]')`.

## Coverage
- Line coverage target: 80%. Branch coverage target: 70%.
- Coverage reports generated on every CI run. Regressions below target block merge.
- Exclude generated files, migration files, and type declaration files from coverage.

8. Documentation-First Team

# Copilot Instructions

## Documentation Requirements
- Every exported function, class, and interface must have a documentation comment.
- Documentation comments must include: purpose, parameters with types, return value, and at least one usage example for non-trivial functions.
- Avoid comments that restate the code. Comments explain *why*, code explains *what*.

## README Updates
- Any change that affects installation, configuration, or public API must include a README update.
- Code examples in documentation must be tested — use doctest or equivalent.

## Changelog
- All user-visible changes go in CHANGELOG.md under `[Unreleased]` before release.
- Format: `- [Type] Description` where Type is Added / Changed / Deprecated / Removed / Fixed / Security.

9. Legacy Code Maintenance

# Copilot Instructions

## Working with Legacy Code
This codebase has sections written before 2018. Consistency with existing patterns is preferred over introducing modern alternatives unless explicitly refactoring.

## Change Discipline
- Minimal footprint: change only what is necessary to fix the bug or implement the feature.
- Do not refactor code that is not in the direct path of the current change.
- When you must touch legacy code, add tests before making changes (characterization tests).

## Dependencies
- Do not upgrade dependencies as a side effect of a feature change. Dependency upgrades are separate PRs.
- Check the `LEGACY_NOTES.md` file for known quirks before modifying any file in `src/legacy/`.

## Patterns to Preserve
- Callback-based async patterns in `src/legacy/` — do not convert to async/await without approval.
- SQL in `.sql` files under `queries/` — do not inline SQL into application code.

10. API Design Team

# Copilot Instructions

## API Design Standards
- RESTful resource naming: plural nouns, no verbs in URL paths (`/users`, not `/getUsers`).
- HTTP method semantics: GET (idempotent read), POST (create), PUT (full replace), PATCH (partial update), DELETE.
- All responses include a consistent envelope: `{ "data": ..., "meta": ..., "errors": [] }`.

## Versioning
- API version in URL path: `/v1/`, `/v2/`. No header-based versioning.
- Never remove a field from a response without a major version bump.
- Deprecate fields with a `deprecated: true` marker in OpenAPI spec before removal.

## Documentation
- Every endpoint must be described in `openapi.yaml` before implementation begins.
- Error codes must be listed in `docs/error-codes.md`.
- Breaking changes require a migration guide in `docs/migrations/`.

Advanced Patterns

Token Budget: Keep Under 2,000 Tokens

Copilot does not have unlimited context. The instruction file competes with your code, the open files, and the conversation history for context window space. Files that exceed roughly 2,000 tokens (approximately 1,500 words) risk being truncated — and truncation is silent. Copilot will not tell you it stopped reading halfway through.

The priority ordering matters: put the most critical rules first. If the file gets cut, you want language version requirements and security rules to survive, not the section on commit message formatting.

Ordering Instructions by Impact

A reliable ordering for most projects:

1. Language version and toolchain (TypeScript version, Python version, framework version)
2. Hard constraints (security rules, patterns that are never acceptable)
3. Architecture conventions (file structure, naming patterns, import rules)
4. Testing requirements
5. Code style preferences (lower priority — linters usually handle these)
6. Documentation conventions

What Copilot Ignores

Some instruction types consistently underperform:

• File-path scoping: "Only apply these rules to files in src/auth/" — Copilot applies instructions globally. Use subdirectory-level AGENTS.md files for path-scoped rules.
• Workflow instructions: "Run the test suite before generating code" — Copilot cannot execute commands mid-completion.
• Tool references: "Check Jira ticket XYZ-123" — Copilot has no access to external tools during completion.
• Long conditional chains: If-then-else logic with more than two branches tends to be applied inconsistently.

Combining with AGENTS.md for Cross-Tool Teams

For teams where developers use multiple AI tools, a two-file approach works well:

AGENTS.md (shared project rules):

# AGENTS.md
## Commands
npm run build
npm test

## Code Standards
- TypeScript strict mode
- No `any` types
- Vitest for all tests

.github/copilot-instructions.md (Copilot-specific additions):

# Copilot Instructions
Apply all rules from AGENTS.md. Additional Copilot-specific guidance:

## Completion Behavior
- When completing a function stub, always include error handling.
- Prefer explicit return types over inference for public-facing functions.

The explicit reference to AGENTS.md in the Copilot instructions file keeps the two files synchronized conceptually and reduces duplication.

Frequently Asked Questions

What is copilot-instructions.md? copilot-instructions.md is a Markdown file at .github/copilot-instructions.md that GitHub Copilot reads automatically to apply persistent custom instructions. It applies to inline completions, Copilot Chat, and pull request reviews.

Where does the copilot-instructions.md file go? Exactly at .github/copilot-instructions.md — inside the .github directory at the repository root. No other path is recognized.

Does copilot-instructions.md work with Copilot CLI? No. As of 2026, the Copilot CLI (gh copilot suggest, gh copilot explain) does not read copilot-instructions.md. CLI users need to provide context manually or rely on AGENTS.md in tools that support it.

What is the difference between copilot-instructions.md and AGENTS.md? copilot-instructions.md is Copilot-only. AGENTS.md is a cross-tool standard supported by Copilot, Cursor, Claude Code, and OpenAI Codex. Teams using multiple AI tools should maintain AGENTS.md as the primary instruction file and use copilot-instructions.md for Copilot-specific additions.

How long should copilot-instructions.md be? Under 2,000 tokens — roughly 1,500 words. Put the highest-priority rules first to protect them from truncation if the file exceeds the context budget.

Does GitHub Copilot read AGENTS.md? Yes, GitHub Copilot reads AGENTS.md when present. copilot-instructions.md takes precedence for Copilot-specific settings, but both files are used. In a multi-tool team, maintaining both is recommended.

Related Articles

• AGENTS.md and GitHub Copilot Integration — how AGENTS.md interacts with Copilot features
• AGENTS.md Best Practices — design principles from 60,000+ real repositories
• CLAUDE.md Guide — Claude Code-specific instruction file reference

Protect Your Copilot Enterprise Secrets

If your .github/copilot-instructions.md references internal tools or API patterns, keep the actual secrets out of the file. 1Password CLI’s op run injects credentials at runtime — no .env files in the repo, no keys in shell history, and an audit log of every secret your workflows touch.