CLEAR instructions for GitHub Copilot

Imagine GitHub Copilot as a talented intern who’s still learning the ins and outs of your company handbook, but eager to help!

It knows how to code.
But it does not know how you code.

So sometimes it helps.
Sometimes it guesses.
Sometimes it gives you code that looks right, but feels wrong the moment you read it.

Copilot is not bad. It is just under-briefed.

If you don’t teach Copilot your rules, it borrows someone else’s.

Over the weekend, I was getting Copilot to help me write some code, and one of the suggestions looked like this:

if (string.Equals(modeType, "Private", StringComparison.OrdinalIgnoreCase))
{
    // No participants in the game. creator-only. resolvedUserIds stays empty.
}
// Business rule: Automatically include creator for shared games
else if (string.Equals(modeType, "Shared", StringComparison.OrdinalIgnoreCase))
{
    if (selectedUserIds != null) resolvedUserIds.AddRange(selectedUserIds);

    if (!resolvedUserIds.Contains(primaryUserId, StringComparer.OrdinalIgnoreCase))
        resolvedUserIds.Add(primaryUserId);
}

Nothing about that code is obviously broken. All the tests pass.

But it also has that very familiar Copilot feeling. It is plausible, generic, and a little detached from the actual shape and conventions of the codebase it is supposed to fit into.

That is where custom instructions come in(This was before setting up the custom instructions).

GitHub supports repository-wide custom instructions through .github/copilot-instructions.md, and VS Code can generate a starter version. VS Code also supports path-specific *.instructions.md files for narrower parts of a codebase.

This post isn’t about writing perfect instructions but about creating ones that actually help.

What custom instructions are

Think of custom instructions as a short note to Copilot that says:

Here is how this project works. Please follow this when helping me.

Rather than repeating the same context over and over, you can save it in a file once and let Copilot reuse it. This makes AI responses more aligned with your project needs and coding style, making your workflow smoother.

That means you can tell Copilot things like:

• where logic should go
• what patterns your repo uses
• what patterns to avoid
• what kind of tests matter
• when it should ask before making bigger changes

You are not teaching Copilot how to code.

You are teaching it how to fit in.

Why should you care

If you’re new to Copilot, you might think:

“Copilot gave me code, so it must be good.”

But good-looking code isn’t always the right fit.

Every project has its own:

• structure
• naming conventions
• architecture
• testing strategies
• boundaries

The most helpful instruction files typically include these key elements: project overview, tech stack, coding guidelines, structure, and useful resources.

Therefore, the biggest benefit is less cleanup.

Less undoing.
Less rework.
Less “why did it do that?”

Copilot is quick. Cleanup takes a while.

The easiest way to start

Do not start from a blank file if you do not have to.

VS Code now offers two simple methods to get started:

• Create an instructions file via the Chat Customizations UI or by using the Chat: New Instructions File command.
• Generate workspace-wide instructions with /init.

That distinction is important. Creating a file provides a space to write rules. Running /init offers a draft to improve.

Treat generated instructions as a starting point, not a finished answer. VS Code supports /create-instruction for capturing individual conventions.

That provides a very simple beginner workflow:

1. Create a workspace instruction file
2. Run Chat: New Instructions File command if you want a starter draft
3. Read the generated file
4. Remove the vague parts
5. Add the rules your repo actually needs
6. Test it on real tasks
7. Improve it over time

That’s much easier than staring at an empty Markdown file and trying to come up with the perfect rules from scratch.

Quick test

When setting up the custom instructions, I would prompt the Copilot Chat with the following:

What are the custom instructions for this project?

If it can summarise your file back to you, that’s a good indication the file is active.

You can also check the References list in the response to confirm the instruction file was used.

My go-to approach is to use C.L.E.A.R.

If you only remember one thing from this post, remember this:

C - Create a first draft

Start with a workspace instruction file, then use /init if you want a draft to refine.

L - List your real repo rules

Add the patterns, boundaries, and expectations that matter in your project.

E - Eliminate vague advice

Remove rules that sound nice but do not change Copilot’s output.

A - Align your rules

Check that your rules do not clash or repeat each other. Make sure Rule #1 is not fighting Rule #5.

R - Refine with real tasks

Test on actual work and keep improving the file over time.

That is the whole process.

Not more instructions.
Clearer instructions.

• The aim is not to create smarter AI, but to reduce the need for cleanup.

What to include in your first instruction file

Keep it straightforward.

A good beginner-friendly instruction file usually needs just five essentials:

1. A brief project overview

What is this project about?

2. Key rules

What patterns should Copilot follow?

3. Boundaries

What should Copilot avoid?

4. Testing expectations

What types of tests are important here?

5. Changing behaviour

When should Copilot ask first instead of guessing?

The most helpful starting files typically include the same kind of content: a brief overview, tech stack, coding guidelines, project structure, and useful resources.

You don’t need a lengthy rulebook.

You need practical rules.

What to exclude

This is where many instruction files go wrong.

They become filled with appealing-sounding advice like:

• write clean code
• follow best practices
• keep it maintainable
• make it scalable

These sound clever.

But they aren’t very practical.

Because Copilot can’t do much with them.

• If Copilot can’t act on it, it shouldn’t be in the file.

Here’s the difference.

The clearest instructions are brief, self-contained, and focus on information the AI cannot reliably infer on its own.

Vague rules sound clever. Specific rules save time.

Keep it sharp.

If your instruction file reads like a novel, you are spending context window on rules instead of code.

Prompt: turn vague rules into usable rules

If I am working in a new repo with a different language (like Java, GO, etc.) or a new framework, then I would prompt the Copilot with the following.

Turn these vague engineering preferences into actionable custom instructions for GitHub Copilot.

For each one:
- explain why it is too vague
- rewrite it as a specific rule Copilot can follow

Preferences:
[paste vague rules here]

A simple example

Let’s consider a typical example.

Suppose you have a project that assists teams in transforming rough requirements into organised delivery tasks.

The workflow generally includes:

• shaping the requirement
• identifying missing details
• asking clarification questions
• creating epic, feature, and story breakdowns
• refining stories until they are ready

This example is useful because it demonstrates that custom instructions are not solely about code style.

They can also influence how Copilot assists you in thinking through work.

Here’s what that might look like:

# Copilot Instructions

## Project overview
- This project helps turn rough requirements into clear, structured delivery items.
- The workflow usually moves from requirement shaping to clarification, then to story generation and refinement.

## How to help
- Prefer step-by-step outputs over long unstructured answers.
- Keep explanations simple and easy for beginners to follow.
- When breaking down requirements, clearly identify gaps, assumptions, and missing decisions.
- When generating work items, prefer the structure: Epic -> Feature -> Story.
- When refining stories, focus on clarity, scope, dependencies, and testability.

## Avoid
- Do not invent missing business rules confidently.
- Do not jump straight into implementation details if the requirement is still unclear.
- Do not produce oversized stories that combine multiple deliverables.
- Do not assume a requirement is ready for development if important decisions are still missing.

## Change behavior
- If the requirement is unclear, help shape and clarify it before suggesting implementation.
- Reuse the existing workflow style instead of inventing a new one.
- If multiple interpretations are possible, call them out briefly instead of guessing.

That makes sense because it guides Copilot on:

• what the project is
• how to structure help
• what to avoid
• how to behave when things are unclear

This is the purpose of custom instructions.

Not to sound impressive. To reduce drift.

A tiny code-style example

Most beginners also look for a straightforward coding example.

Here is a small one:

## Frontend style
- Prefer functional components over class components.
- Use Tailwind utility classes instead of inline CSS.
- Keep components focused and small.
- Reuse existing UI patterns before creating new ones.

Now compare that with this:

Make the frontend clean and modern.

One helps.
One just vibes.

How to spot conflicting rules

Once your file grows, it’s easier to accidentally add rules that conflict with each other.

That is a real problem.

One thing I often do here is ask GitHub Copilot Chat to read my instruction file and identify conflicting, overlapping, or vague rules. It usually provides a good starting point rather than making me play instruction detective manually.

Prompt: find conflicting rules

Can you review these custom instructions and help me clean them up?

I want you to find:
- conflicting rules
- repeated rules
- vague rules
- rules that won't really change Copilot output

Then recommend a simpler, more concise version that maintains the intent but eliminates unnecessary details.

Here are the instructions:
[paste instructions here]

Bad combination:

Keep outputs short.
Provide detailed explanations for every step.

Another one:

Create small focused stories.
Keep related work together in one story.

Both may seem reasonable. Together, however, they can pull in opposite directions.

Mixed signals in, mixed results out.

A simple way to spot conflicts is to ask:

• Do any two rules suggest opposite actions?
• Am I repeating the same idea in different words?
• Is one rule broad while another is more specific?
• Could two people interpret this differently and make different choices?

If so, simplify it.

That is the A in C.L.E.A.R. Align your rules.

How to tidy up your instructions

You don’t need to perfect the file on the first go.

It’s better to start small and improve over time.

A good cleanup process looks like this:

• remove generic advice
• eliminate duplicate rules
• get rid of outdated rules
• rewrite confusing lines
• merge similar rules
• keep only the rules that affect output

That last point is the most important.

If a rule does not change output, it is merely decoration.

I’ve also come across tips shared by Boris Cherny (creator of Claude Code) about how their team optimises instructions for Claude Code. Different tool, same idea. The core concept is simple: when the AI makes a mistake, do not just correct it once and move on. Turn that correction into a rule. That approach works really well with GitHub Copilot too.

Instruction files rot too.

What helped six months ago might just be background noise today.

Prompt: trim an oversized instruction file

Help me reduce this custom instruction file without losing the important guidance.

I want you to:
- remove repetition
- shorten long rules
- keep only rules that change Copilot output
- preserve the key project boundaries and expectations

Then give me:
1. a cleaned-up version
2. a short explanation of what you removed and why

Here is the file:
[paste instructions here]

A small level-up for later

Start with one repo-wide file:

.github/copilot-instructions.md

That is the standard repository-wide file.

Later, if your repo has very different areas like frontend, backend, tests, or docs, you can split rules into targeted *.instructions.md files once one shared file is no longer sufficient.

A simple shape could look like this:

.github/
  copilot-instructions.md
  instructions/
    frontend.instructions.md
    backend.instructions.md
    tests.instructions.md

Beginner’s rule of thumb:

Start with one file. Split later only if necessary.

Final takeaway

Custom instructions aren’t about making Copilot smarter.

They’re about making Copilot yours.

They help it fit your repo better.
They reduce incorrect guesses.
And most importantly, they lead to less cleanup.

The goal isn’t perfection.
It’s fewer wrong turns.

So start simple.

Create a small file.
Write only what matters.
Test it on real tasks.
Clean it up when it becomes messy.

You don’t need a perfect file.

You need a useful one.