(English article)

I’ve been using Copilot in VS Code on and off for about two years now. The experience has changed over time. Multi-Agent AI functionality, introduced in late 2025, allowed Copilot to handle progressively more complex tasks. But for me, Agent mode only started delivering real, time-saving value when combined with instructions files. Learning how to use them became a major asset across projects and tasks.

This is how I found I needed it, and how I use it (and you can too).

Skip to section “Copilot instructions for the rescue” for the instructions without the rant.

First-world developer problems

“Copilot writes code that doesn’t work the way I need”

Copilot often produced code that looked correct but didn’t respect how my project worked. It probably guessed what someone would want, just not what I needed. The code looked clean, but solutions were generic, so more often than not I ended up rewriting them. It was more trouble than it was worth.

Long chat sessions lose relevant context over time

In long sessions, the quality of answers degraded. Early constraints were forgotten and rejected solutions resurfaced. Earlier context was likely summarized or dropped.

Long work sessions meant long chats, and those were the worst time sinks, because of having to explain everything all over again.

And so I avoided giving it complex tasks

Copilot seemed unable to handle even mildly complex tasks, even looping through variations of solutions that had already failed. Instead of shortcuts, I got detours.

To avoid frustration, I started simplifying prompts (and expectations). Yeah, I was adapting to Copilot instead of Copilot adapting to me. I knew I was missing out on something.

That’s when it hit me: Copilot didn’t know my project, and it wasn’t going to magically learn it.

Copilot instructions for the rescue

The solution is simple in concept: give it permanent context.

In VS Code, you can create Copilot instructions files that provide persistent guidance about your project. Think onboarding documentation for a very literal junior developer.

Where configurations files live (and how VS Code detects it)

There are a bunch of types of Copilot instructions files you can use based on the official documentation, and probably a few ways not documented, either because it’s new or because developers find creative ways to add context to chat. In this article, I want to talk about two mechanisms VS Code Copilot Chat uses for persistent instructions.

1. Repository instructions (the main one)

Copilot automatically detects a repository‑level file at:

• .github/copilot-instructions.md

If that file exists, Copilot Chat treats it as baseline context for the entire repository. No configuration is required. This is the primary place to describe architecture, conventions, and project rules.

2. Additional .instructions.md files (scoped context)

Copilot Chat can also read additional instruction files that end with:

• .instructions.md

These files can live anywhere in the repository, for example:

.github/instructions/
  frontend/
    react.instructions.md
    accessibility.instructions.md
  backend/
    api-design.instructions.md
  testing/
    unit-tests.instructions.md

VS Code indexes workspace files and may retrieve these instruction files when they appear relevant to the current chat or the files you are editing. In other words, Copilot does not blindly load every .instructions.md file. It uses heuristic retrieval, similar to how it selects related source files for context.

They are not guaranteed to be loaded every time. They are more likely to be used when their content or location matches the current task. Think of them as modular guidance files Copilot can pull in when appropriate, instead of a single massive instructions document.

In most projects, I recommend starting with one clean repository instructions file before experimenting with additional scoped ones.

Formatting instructions files

The two instruction types use slightly different conventions.

1. .github/copilot-instructions.md

This file is free‑form Markdown. Think of it as a compact technical briefing for the project.

Example:

# Project overview

Type: React + Node application
Architecture: feature folders + service layer

Key rules
- UI never calls APIs directly
- All HTTP calls go through src/server/apiClient.ts
- Dates must use src/utils/date.ts

Important folders
- src/app      → features
- src/server   → backend services
- src/ui       → shared components

Structure is up to you. Headings and bullet lists work well.

2. *.instructions.md

Scoped instruction files support a small YAML front‑matter block that tells Copilot when the instructions should apply.

Typical fields include things like name, description, and applyTo (which files the rules apply to).

Example (react.instructions.md):

---
name: React Standards
description: React UI conventions
applyTo: "src/**/*.tsx"
---

Rules
- Use functional components
- Prefer hooks over class components
- State logic goes in hooks under src/app/hooks

Patterns
- Data fetching uses useQuery from TanStack Query

Another example (tests.instructions.md):

---
name: Testing Standards
description: Unit testing conventions
applyTo: "**/*.test.ts"
---

Rules
- Use Jest
- Mock external services
- Avoid testing implementation details

The YAML header helps Copilot determine when the instructions are relevant, especially based on the files involved in the chat or edit.

What to put in .github/copilot-instructions.md

1. Explain the architecture (concisely)

Not a novel. Not a manifesto. Not your entire README.md. Just:

• What type of app is this?
• What architectural pattern does it use?
• What technology stack is on board? Frameworks? Programming languages?
• Where is the business logic?
• Where are API calls handled?
• What is intentionally not used?

Be extremely direct. Machines don’t need motivational paragraphs.

2. Add folder structure and where to find answers

Don’t write

“The project follows a clean layered architecture.”

First because you know that’s a lie. Second, because it’s meaningless to the machine. Do tell what the project folders have in store instead:

• docs → documentation and reference
• src/app → front-end and features
• src/server → API, infrastructure
• src/ui → components and views

If a folder contains validation rules, say it explicitly. If configuration lives somewhere specific, say it.

You know where things are. Copilot doesn’t, until you write it down for them.

3. Add pitfalls and project gotchas

This part is “fun”. Your project probably has landmines. Teach Copilot to defuse them.

• “Never call API directly from UI.”
• “All dates must go through dateUtils.ts.”
• “Do not mutate state directly.”
• “This project avoids third-party form libraries.”

Again, you already know these things, but Copilot doesn’t. Write them down.

4. Add (short) examples

Examples are stronger than explanations. Instead of:

“Use the repository pattern.”

Add a small repository example for the most important patterns you don’t want it to miss. Add a small use-case example, component example, etc. That helps with output alignment.

Careful though. This can get very long very quickly, and you want to avoid that. Stick to very important examples.

5. Add do’s and don’ts

Short bullet points.

Do:
- Always use existing utilities before creating new ones
- Follow naming conventions already in the folder

Don't:
- Introduce new dependencies without explicit request
- Change architectural layers
- Assume patterns based on Oracle (faulty) documentation

While on the subject of Oracle documentation, here’s a cheeky message I got from Copilot the other day:

Ha! Classic Oracle - documentation says /ccagent/v1/onBehalfOf but it actually works at /ccagentui/v1/onBehalfOf. Good thing you checked the network traffic from the working Agent console!

Anyway, be clear and be strict about dos and don’ts.

Another consideration: you can use definitive words (“always do”, “never try”) and nuanced words (“avoid”) to qualify your instructions. The semantic intent from using the word “never” conveys a stronger negative than the more nuanced word “avoid”.

6. Be very concise

This is important. Large language models produce fluff, but they do not need fluff.

Your instructions file should read like technical notes, not like this blog post. The clearer and shorter, the better. That saves on token count and sanity (my mental sanity).

“Advanced” tips

Avoid long instructions files

Don’t stretch Copilot’s memory too thin. More instructions don’t mean better results.

Problems with instructions files too large:

• Harder for you to maintain
• Harder to debug when Copilot behaves oddly
• Heavier token usage
• Potentially worse performance on smaller models

So keep it as lean as you can.

Add current task details to the instructions file (sometimes)

If I’m working on a large refactor or a multi-step change, I may temporarily add a short Current Task section to the instructions file. That section describes requirements, constraints, expected steps, and any context that could help. I also like to update this section as the task progresses, letting Copilot know what stage of the current task I’m at.

What this does is create a permanent context about a large task that won’t get easily diluted by chat summarization once the chat history overflows token count limit. If I manage to break down my task into smaller steps, it allows me to start separate chats for each of them, keeping each chat focused with smaller history.

This helps a lot for larger tasks, but it also carries the risk of making the instructions file much longer, so use with caution.

Important: adding your current task to the instructions file should always be temporary. I remove that section once the task is done. The instructions file is baseline context, not a task manager.

Common Misconceptions

Let’s clear up a few myths.

“Copilot reads the entire project”

Not in the way people imagine.

Copilot has access to the current file, nearby files, and relevant context it can retrieve. But it does not load and reason over your entire repository as a human would.

It operates within context window limits. If something important isn’t visible or explicitly described in your instructions, it may as well not exist for Copilot.

“Copilot reads the root folder automatically”

Not if it doesn’t need to.

While analyzing code or trying to find solutions for a problem, the Agent mode of Copilot Chat might look for answers in places like your README.md file or similar places like a human would, but don’t count on it.

“Copilot understands project structure by scanning folder structure”

The presence of files and folders does not equal understanding. Copilot does not infer your architecture simply because the structure exists. Structure is not documentation.

Explicit context still wins.

Final Words

Copilot is not a mind reader. It’s a probabilistic engine that performs better when you reduce ambiguity.

An instructions file won’t make it perfect. But it can turn it from “sometimes helpful” into “consistently aligned.” Which is a big difference when you’re working on layered, real-world software.

In-depth look at topics implied here coming later. Probably.