Custom Instructions: Teaching Copilot Your Codebase

Why Custom Instructions Matter

Out of the box, Copilot knows how to write code — but it does not know your codebase. It does not know that your team uses Zod for validation instead of Joi. It does not know that all database queries must go through the repository layer. It does not know that you prefer async/await over Promise chains, or that components should never import directly from other components' internal files.

Custom instructions solve this. They are markdown files you commit to your repository that Copilot reads before every Chat interaction. When Copilot has your instructions, its suggestions align with your conventions instead of with general best practices that might conflict with your codebase.

The Repository-Wide Instructions File

Create a file at .github/copilot-instructions.md in the root of your repository. This file applies to every Copilot Chat request in that repo — across Ask, Edit, Agent mode, and Code Review.

Copilot does not surface this file in the chat panel, but it appears in the References section of any response that used it, so you can verify it was loaded. The instructions are added as context to every request automatically — you do not need to reference the file yourself.

A useful instructions file covers:

• Stack and versions — "This project uses Node.js 20, TypeScript 5.4, Express 4, and PostgreSQL 16."
• Coding conventions — "Use async/await throughout. Never use .then() chains. All functions must have TypeScript return types."
• Architecture patterns — "Controllers handle HTTP; services contain business logic; repositories handle all database queries. Do not put database queries in controllers."
• What to avoid — "Do not use console.log for logging — use the logger module at src/utils/logger. Do not install new dependencies without checking with the team first."
• Testing — "Tests use Jest and Supertest. Each service function needs unit tests. Integration tests live in test/integration/."

Path-Scoped Instructions Files

For instructions that apply only to certain parts of the codebase, create files in .github/instructions/ with the naming pattern NAME.instructions.md. Each file has a YAML frontmatter block with an applyTo glob that specifies which files it applies to:

---
applyTo: 'src/api/**'
---
# API Layer Instructions

All endpoints must validate request bodies using the Zod schema
defined in schemas/. Return 400 with a structured error object
for validation failures. Use the apiError() helper for all error responses.

Path-scoped files load only when Copilot is working on files matching the glob. An instructions file for src/api/** will not load when you are working in src/components/. This prevents irrelevant instructions from adding noise.

Personal Instructions

You can also set personal instructions that apply across all your repos. In VS Code, open Settings and search for Copilot: Instructions. Personal instructions are useful for preferences that apply everywhere — your preferred coding style, how you want explanations formatted, your level of experience with certain technologies.

Copilot also reads AGENTS.md files — a convention shared with other AI coding tools. If your project already has an AGENTS.md, Copilot will use it as instructions automatically.

What to Put in Instructions (and What Not To)

Keep the main file under 1,000 lines. Focused instructions load faster and produce more consistent behaviour than exhaustive ones. Use path-scoped files to keep each instruction set targeted to its domain.

Try This

Create .github/copilot-instructions.md in your project right now, even if it is just five lines. Start with your tech stack, one architecture rule, and one "do not do this" convention. Then open Copilot Chat, ask a question about your codebase, and check the References panel to confirm your instructions file was loaded. Iterate from there — add instructions as you notice Copilot making suggestions that don't fit your project.