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

copilot-instructions.md supplies repository guidance to supported Copilot features. Start by checking that your chosen feature loads the file; loading it does not guarantee that generated output follows every rule.

What is .github/copilot-instructions.md?

Use .github/copilot-instructions.md to supply project-specific guidance in supported Copilot environments.

For repository-wide guidance, put the file at .github/copilot-instructions.md in the repository root. Support and settings depend on the Copilot feature you use; verify loading in that environment. The file uses plain Markdown — no YAML frontmatter, no special syntax. Write concise natural-language instructions; check the limits and loading behavior of your chosen feature.

Candidate rules for supported interactions include:

• 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. Each teammate should verify the file in their chosen environment.

Verify setup before copying a template

For VS Code, select your intended agent harness. Run Chat: Open Customizations and check that the instruction file appears. Start a fresh chat in the repository, request one small change, then inspect References and the result. If the file is missing, inspect Developer: Open Agent Debug Logs and check its location and the selected harness. See the VS Code verification guide.

For example, use a disposable branch and one existing naming convention. Success means both loading evidence and a matching output, plus the project’s relevant checks passing. An agent saying “I read it” alone is not sufficient. This is a suggested check, not a hands-on Copilot test performed for this article.

How Copilot Uses the File

Sources checked October 13, 2026: GitHub support matrix, code review settings, and the VS Code guide above. Do not use typing completions as a test of chat instructions. Instruction loading is not policy enforcement; review generated changes and test them.

For rules limited to particular paths, supported features can use .github/instructions/**/*.instructions.md with matching scope. Keep the repository-wide file focused on shared conventions. Agent tool execution depends on the selected environment and permissions; an instruction is not proof that a command ran.

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

Choose formats that your actual clients support. A filename alone does not establish discovery or precedence across tools.

The GitHub support matrix distinguishes each feature. Do not generalize agent-file support to every IDE or GitHub.com Chat.

Resolve conflicts in the environment you use

GitHub’s web customization documentation lists personal, repository and organization precedence; within repository guidance it lists path-specific, repository-wide, then agent instructions. That is not a universal ordering for all clients.

The VS Code conflict guidance advises resolving contradictions at their source because discovery and merging vary by harness. Keep shared rules consistent and verify them in the selected environment. Neither creating all three files nor adding an “override” sentence guarantees conflict-free behavior.

10 Illustrative 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

Keep instructions concise; check feature-specific limits

The cited documentation does not establish a universal 2,000-token cutoff with silent truncation for every Copilot feature. This article does not claim such a limit. Keep instructions focused and consult the documentation for the feature you use before relying on any size limit. Review loading evidence and output rather than assuming that a shorter file guarantees compliance.

Ordering Instructions by Impact

An example editorial ordering to adapt to your project:

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

Separate instruction loading from execution

Path-specific loading needs a supported mechanism. Running tests or reading an external ticket also needs the relevant tools and permissions. Do not infer either from an instruction sentence: inspect the actual tool activity and results. Typing suggestions are not a test of these instruction files.

Combining with AGENTS.md for Cross-Tool Teams

Use this illustrative two-file layout only when your selected clients support it. Verify discovery in each client and avoid conflicting copies:

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
Project rules: [AGENTS.md](../AGENTS.md). Additional guidance for supported chat/agent use:

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

The relative link identifies the intended shared file; it does not prove that every client loads it or synchronize the contents. Verify referenced-file loading in the selected environment and review both files when shared rules change.

Frequently Asked Questions

What is copilot-instructions.md? A repository guidance file at .github/copilot-instructions.md for supported Copilot features. Verify loading and review output; VS Code typing suggestions do not use these custom instructions.

Where does the copilot-instructions.md file go? For repository-wide guidance, use .github/copilot-instructions.md at the repository root. Other instruction formats and user-level locations depend on the client.

Does copilot-instructions.md work with Copilot CLI? Yes. The current GitHub support matrix lists repository-wide custom instructions for Copilot CLI. Check the documentation for your actual client.

What is the difference between copilot-instructions.md and AGENTS.md? They are different instruction formats with feature-dependent support. Choose supported formats for your clients and verify discovery; do not assume universal precedence or automatic cross-tool loading.

How long should copilot-instructions.md be? Keep it concise and check feature-specific limits. The sources cited here do not establish a universal 2,000-token silent-truncation rule.

Does GitHub Copilot read AGENTS.md? Some features support it, including Copilot Chat in VS Code, cloud agent and CLI. Support, discovery and conflict handling vary by environment; check the matrix and avoid contradictory rules.

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

Disclosure: The 1Password link below is an affiliate link. We may receive a commission from qualifying purchases.

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.