GitHub Copilot is only as good as the context you give it. Without proper guidance, you’ll waste time correcting off-target recommendations or explaining basic project details repeatedly.
A well-crafted copilot_instructions.md file provides consistent, project-specific context for every prompt. You get:
- Better first drafts
- Fewer corrections
- Faster work in Agent mode
Let’s examine how to build an effective instructions file.
Don’t vibe your copilot_instructions.md
I researched on GitHub and in developer communities to see how people write their copilot_instructions.md files. The majority either let an LLM generate it without proper project context, or copy/paste generic instructions from others.
The result is mostly generic AI slop. Don’t do that.
The copilot_instructions.md file becomes part of every Copilot request’s context window. Since it’s included with every prompt, its content directly impacts the quality and relevance of all suggestions. Research shows that irrelevant information can drastically reduce response quality or, worse, send the AI astray entirely. Therefore, avoid generic sentences that just waste tokens and instead prioritize project-specific details Copilot can’t immediately infer from your code alone, e.g. architectural patterns, domain terms, and non-obvious constraints.
But first, let’s set it up.
Setting up your copilot_instructions.md
You have two starting options: writing it yourself by filling out the skeleton below or have Copilot Agent bootstrap it for you and then edit the file. Due to the aforementioned reasons, I recommend using the former option.
Option 1: Write the file yourself (recommended)
In your repository root, create the folder github if it doesn’t exist already.
Then, create an empty file in that directory called copilot_instructions.md and copy/paste the following content into the file
## Summary
<!-- brief summary of the repository -->
## Terminology
<!-- list of domain specific terms with their explanation -->
## Architecture
<!-- short summary of the architecture -->
## Task planning and problem-solving
<!-- the most important problem-solving guidelines -->
<!-- e.g. "plan the task before writing any code" -->
## Coding guidelines
<!-- the most important coding guidelines -->
Option 2: Generate the file with the Copilot Agent
Alternatively, you can let GitHub Copilot Agent generate the file with the latest VSCode release (@pierceboggan thanks for the heads-up):
This will provide you with a usable starting point but some information will most likely be off or even incorrect and some will be missing. Therefore, after creating the file, go over each sentence, improve the existing content iteratively, and add your own.
Next, let’s cover what to include.
What to include in your instruction file
I researched the most frequently used sections in copilot_instructions.md files to identify effective practices. Use these as inspiration, but tailor them to your project and Copilot usage. If you use Copilot to only generate unit tests for a React repository, your instruction file will look very different from someone who only uses it to generate new features for Java services.
Summary
Summarize your repository briefly, e.g.:
This repository contains the source code for a Pokémon card
trading platform's web app, enabling online card trading.
It manages trade processing and card inventory tracking.
Terminology
List domain-specific terms with explanations, e.g.:
- trade - User’s trade request (card, condition, price).
- stock - Inventory of Pokémon cards for tracking and listing.
- queue - List of pending trades, prioritizing user offers.
Architecture
Describe the architecture, focusing on non-obvious details. Reference key files:
The React frontend interacts directly with Supabase
for database operations, user authentication, and
real-time trade updates, while integrating with
the PokeAPI for Pokémon data.
- `supabaseClient.js` - Supabase client & authentication.
- `realTimeTradeSubscriptions.js` - Manages trade updates.
- `pokeApiIntegration.js` - Interacts with PokeAPI.
Task planning and problem-solving
LLMs struggle with common sense and problem-solving. If Copilot isn’t solving tasks well, add clear instructions. I noticed better results when telling the LLM to plan before coding. Some models drown problems in code until they work (Claude 👀). Instructing Copilot to reuse existing code helps.
- Before each task, you must first complete the following steps:
1. Provide a full plan of your changes.
2. Provide a list of behaviors that you'll change.
3. Provide a list of test cases to add.
- Before you add any code, always check if you can just re-use
or re-configure any existing code to achieve the result.
Model-specific instructions
If you find yourself mostly working with the same AI model, you probably notice some recurring flaws or annoyances. Use this section to nudge the LLM in your desired direction. For example, for Claude I noticed that it tends to be over-comprehensive. I, therefore, use:
- Always focus on simplicity and precision and not comprehensiveness.
- When writing tests, focus on the happy path and only the most
important edge cases.
- Before adding a new test, always make sure that a similar test
doesn't exist already.
Language-specific instructions
Add language specific rules or use code generation instructions (at the time of writing only available for VSCode).
Try 10xrules.ai to generate these quickly
Coding Guidelines
Specify coding styles not caught by linters. Include examples where needed
What else?
These are just the most commonly useful examples. Add other relevant instructions specific to your project. Share your ideas in the comments!
Now, let’s discuss how to write clear instructions.
How to write your copilot_instructions.md
Whatever you finally decide to include in your copilot_instructions.md file, I strongly recommend following this writing style. This is a summary of all the information I found in my research and is aimed at making the instructions as clear and actionable as possible:
Use consistent imperative voice.
<!-- Don't ❌ -->
When fixing a bug, it helps to write a failing test first.
<!-- Do ✅-->
When fixing a bug, always write a failing test first.
Don’t be generic. Advice should be specific and actionable.
<!-- Don't ❌ -->
Write maintainable code.
<!-- Do ✅ -->
Always follow the DRY principle and avoid code duplication.
Instead of just telling the AI what not to do, tell it what to do instead.
<!-- Don't ❌ -->
Don’t use hard-coded numbers.
<!-- Do ✅-->
Avoid hard-coded numbers and use shared constants instead.
Don’t add style guides that your linter catches anyway. Less is more.
<!-- Don't ❌ -->
- Follow the ESLint rule `default-case`.
- Always add a `default` case at the end of a `switch` statement.
<!-- Do ✅ -->
<!-- Let your linter catch these issues instead. -->
Don’t link to external resources in the instructions.
<!-- Don't ❌ -->
The API endpoint to retrieve data about a specific Pokémon
is defined [here](https://pokeapi.co/docs/v2#pokemon).
<!-- Do ✅-->
To retrieve data about a specific Pokémon, send a `GET` request
to `https://pokeapi.co/api/v2/pokemon/{id or name}/`.
Include examples where necessary, especially when writing about patterns.
<!-- Don't ❌ -->
Prefix boolean variables with an appropriate verb.
<!-- Do ✅-->
Prefix boolean variables with an appropriate verb, e.g.
`isLoading`, `hasPermissions`, `matchesFilter`.
Bonus: Boost the Agent mode
GitHub Copilot’s Agent mode runs tasks in the background while you focus elsewhere. Ideally, you give it an instruction, and it completes code, tests, and checks automatically. In reality, Copilot often changes code and stops, needing prompts to run linters or tests. Adding upfront instructions can automate this process.
For this, add to the task planning section of your copilot_instructions.md:
If you add new code or change existing code, always verify that
everything still works by running *each* of the following checks:
1. `npm run lint` to run the linter.
2. `npm run test:unit` to run the unit tests.
3. `npm run test:e2e` to run the e2e tests.
Complete the task only after all checks pass.
Copilot adds changes, runs the commands, assesses output, and iterates until errors are fixed:
By default, Copilot requires your approval for each tool usage, but in VSCode, you can add "chat.tools.autoApprove": true to your settings.json to enable auto-approval and go full vibe-coding.
Questions?
A tailored copilot_instructions.md saves you time and improves Copilot’s output. Focus on specific, actionable instructions to guide its suggestions. Use the tips above to craft a file that fits your project.
Try these strategies in your next project! Did I miss any tips you use for copilot_instructions.md?