GitHub Copilot

7 min readGitHub Copilot & AI Engineering · GitHub Copilot

Most Copilot material describes a suggestion box: you type, it completes.

That was accurate several years ago. What Copilot is now is a set of surfaces — completions, chat, agent mode in an editor, a terminal CLI, a review bot, a hosted agent — sharing one thing in common: they all read configuration you put in your repository.

This cluster is about that configuration, because it is the difference between a tool that writes generically reasonable code and one that writes code that fits your codebase.

Start with the Complete Guide

The problem this cluster solves

A model given no guidance writes the average of everything it has seen. That produces code which is correct in general and wrong for you in specific, repeated ways:

The test framework you migrated away from two years ago
A logging approach that bypasses your structured logger
Error handling that does not match the convention every other file uses
A dependency you deliberately do not use
Comments in a style your linter rejects

You can correct these individually, every time, forever. Or you can write them down once, in a place every Copilot surface reads.

That is what custom instructions and repository instructions are, and it is why they get two lessons rather than a paragraph.

Surface	Runs	Covered in
Code completion	Your editor, inline	This cluster
Copilot Chat	Editor or github.com	Chat
Agent mode	Your local workspace	Agent mode
Copilot CLI	Your terminal	The CLI cluster
Copilot code review	Pull requests	The review cluster
Copilot cloud agent	GitHub-hosted environment	The agents cluster

The last three have their own clusters because they are substantial enough to need them. This cluster covers the editor surfaces and — more importantly — the configuration that reaches all six.

The lessons

Lesson 1 is the map of the whole product. Lessons 2 and 3 cover the two IDE families with the most capability, and are deliberately separate because their feature sets differ. Lesson 4 covers chat as an engineering tool rather than a chatbot. Lesson 5 covers agent mode — the point at which Copilot stops suggesting and starts doing. Lessons 6 to 8 are the customisation core, and are the most durable material in the cluster: instructions, prompt files, and the repository-level decision about which mechanism to use for what.

Context, and why editors differ

Copilot’s usefulness in an editor is mostly a function of what the editor hands it.

Completions see the current file and, depending on the integration, related open files. They are fast, local, and have the least context of any surface — which is why they are excellent at finishing a line and unreliable at implementing a function whose correctness depends on code elsewhere.

Chat sees what you attach plus what the editor contributes: the open file, the selection, sometimes a workspace index. This is where explicitly attaching files changes output quality more than any prompt wording.

Agent mode goes further — it can search the workspace, read files it decides are relevant, run commands and read their output. It builds its own context, which is both the reason it handles multi-file work and the reason it can go wrong in more interesting ways.

The practical consequence is that the same question produces different answers in different surfaces, and the difference is usually context rather than capability. A chat answer that seems wrong is often a chat answer given without the file that would have made it right.

Editors also differ from each other, which is why VS Code and JetBrains get separate lessons rather than one page with caveats. Feature parity is not the default, and assuming it produces the confusion described in the callout above.

Verification is the constant

Every article here ends up at the same place, so it is worth stating on the hub.

AI output  →  Compile / validate  →  Tests  →  Static analysis  →  Security scan  →  Human review

That chain is not specific to AI-generated code. It is the chain any change goes through, and the reason it appears in every lesson is that AI makes it cheap to produce changes and does not make it cheap to skip verification.

The specific risks worth naming, because they differ from human-authored code:

Hallucinated APIs. A method that does not exist, on a class that does. Caught by compiling, which is why “does it build” is a real check rather than a formality.

Obsolete patterns. Idioms from an older version of a library. Caught by review, or by a linter that knows your version.

Plausible but wrong dependencies. A package name that sounds right. Caught by dependency review, and worth checking manually when a change adds one.

Hidden assumptions. Code that works given an assumption about your system that nobody stated. Caught by tests, if the tests cover it.

Licensing. Generated code resembling something with an incompatible licence. A real consideration; the practical control is your existing dependency and code-provenance process rather than anything AI-specific.

What good instructions look like

The customisation lessons go into detail. The shape, in brief, because it frames the whole cluster:

Short. A page, not a manual. Every line is charged against context on every request.

Specific to this repository. “Use TypeScript strict mode” is worth writing if it is not obvious from configuration. “Write clean code” is not worth writing at all.

About things that are not inferable. A model can see your directory layout. It cannot see that the legacy/ directory is frozen, that a particular helper must be used for all outbound HTTP, or that one module is deliberately not covered by the shared error handler.

Testable where possible. An instruction that says “always use the shared logger” pairs with a lint rule that enforces it. The instruction improves the first draft; the lint rule is what actually holds.

Maintained. Instructions describing a convention you abandoned are worse than none, because they actively push output in the wrong direction.

The test worth applying: would a new engineer need to be told this, and would they be unable to work it out from the code? If yes, it belongs. If no, it is costing you context on every request for nothing.

Prerequisites

Rolling this out on a team

Customisation is a shared artefact, which makes it a review question rather than a personal setting.

Instructions belong in the repository, and in review. .github/copilot-instructions.md is a file that changes how every contributor’s tooling behaves. It deserves the review a configuration change gets — and a CODEOWNERS entry if the repository has one.

Start from observed corrections. The best first instructions file is written by noting, for a week, what you keep correcting. Those corrections are the conventions that are not inferable from the code.

Expect it to be wrong at first. Instructions that seemed clear produce output that reveals what they actually said. Iterating is normal; treat the file as code rather than as policy.

Measure by what stops recurring. The signal that instructions are working is that a particular correction stops being necessary. If nothing changed, the instruction is either being ignored or was never the problem.

One caution worth carrying into the code review cluster: because these files live in the repository, a pull request can change them. Where that matters most is review customisation, which is read from the branch under review — a security property covered in full on Secure AI code review.

Common mistakes

Writing a 2,000-line instructions file. Always-on context costs tokens on every request and crowds out the code the model needs. Long instruction files are followed less reliably, not more.

Documenting things the code already says. Instructions should carry what is not inferable — conventions, constraints, the reason a thing is done unusually. Restating the directory structure wastes context.

Assuming an instruction is a guarantee. Instructions shape behaviour probabilistically. They do not enforce anything. Enforcement is a linter, a test, or a ruleset.

Using prompt files where instructions belong. Prompt files are invoked deliberately; instructions apply always. Choosing wrong produces behaviour that seems intermittent.

Configuring for one surface and expecting all of them. The support matrices differ.

After this cluster

This cluster covers Copilot where a developer is watching. The next moves to the terminal, where the permission model becomes explicit and the same configuration drives an agent with tools.

Next cluster — GitHub Copilot CLI