Forem: georg.dev

Better Context, Better GitHub Copilot: A Guide to copilot-instructions.md

georg.dev — Tue, 22 Jul 2025 12:36:57 +0000

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 reasons above, 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. This section is most effective when you explain the "why" behind your architectural decisions, not just the "what". Also, make sure to reference important 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.  Supabase was chosen for 
its real-time capabilities and PokeAPI for its generous 
rate limits.
- `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. To improve Copilot’s task accuracy, include step-by-step instructions in this section. 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, if the AI tends to be over-comprehensive, use something like this:

- 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. For instance, here are two Reddit posts that contain some additional categories which can be used as further inspiration: 1, 2.

But first, let’s ensure your instructions follow an effective writing style.

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 tips. They ensure your instructions are clear and actionable for Copilot:

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 all 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.

Wrapping up

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? Share them in the comments!

For more tips like these, follow me on X or BlueSky.

How (not) to find the unsung heroes of JavaScript

georg.dev — Wed, 26 Feb 2025 10:21:04 +0000

You’ve seen this xkcd comic — the one where the entire internet runs on a project some random developer has been thanklessly maintaining since 2003. It’s funny because it’s true. And in [insert current year here], it’s still true.

I’m Georg, a data scientist turned software engineer working mostly in the JavaScript/TypeScript ecosystem. I wanted to fix the problem behind the comic — or at least find those invisible maintainers holding up the ecosystem with duct tape and caffeine. You probably depend on their work every day. I definitely do.

But here’s what happened instead: I found thousands of useless npm packages, a blockchain protocol gone wrong, and a lesson in why noble goals aren't enough. Let’s talk about good intentions, bad incentives, and why your code — and your career — are built on a house of cards.

The search for JavaScript’s invisible maintainers

If you ask, “Who here deserves funding for their open-source work?” everyone raises their hand. That’s the problem. The loudest voices — or the savviest marketers — aren’t always the ones keeping your code from collapsing. After all, most open-source maintainers have better things to do than self-market, like fixing bugs, reviewing PRs, and keeping the lights on.

So I tried something simple: ignore the noise. Instead of listening to who was asking for money, I wanted to see what the ecosystem actually depended on. JavaScript’s dependency graphs are public, after all. How hard could it be?

I downloaded npm’s metadata dump — every package, every dependency, every maintainer — and ran the numbers. The goal: find projects with high dependents but low visibility. Think libraries like ipaddr.js, a utility for manipulating IP addresses with 44 million weekly downloads, or long, a library for working with 64-bit integers with 28 million weekly downloads. These tools are everywhere, but their maintainers often go unnoticed — working quietly behind the scenes to keep the ecosystem running.

The logic was sound. If a package has thousands of dependents but just one maintainer and almost no contributors, that’s probably our famous Nebraskan. If it’s a transitive dependency — something your code uses indirectly, three layers deep — even more so.

At first, it worked. I did not only find well-known packages but also others like anakjalanan, nitroteh, and acertea — each with thousands and thousands of dependents, a single maintainer, and names I’d never heard of. These had to be the unsung heroes.

Then I checked the repositories.

Some led me to completely empty codebases. Others only contained bootstrapped Next.js or Node.js applications without any additional functionality. They weren’t just unmaintained. They were literally useless.

What’s going on here? Why would thousands of projects depend on empty repositories and abandoned forks?

But then I noticed that all those repositories had one thing in common: a file called tea.xyz.

This is why we can't have nice things

Meet the tea Protocol — a blockchain-based attempt to fix open-source funding. Their goal was similar to what I was trying to do, but with a cryptocurrency on top: use the dependency graph to measure a package’s impact and automatically reward maintainers with tokens. Simple.

Too simple.

tea’s “Proof of Contribution” model tied funding to dependency counts. The more projects that depend on you, the more you earn. Sounds fair — until you realize how easy it is to fake a dependency.

Suddenly, those empty repositories made sense. Spammers flooded npm with trivial packages, each containing a tea.xyz file. By artificially inflating their dependency counts, they could trick the protocol into paying them for “impact.”

Even worse, some scammers tried to sneak their own tea.xyz file into widely used open-source packages, like node-bin-gen, via a pull request. The maintainers shut it down, but not before uncovering countless similar PRs targeting other established repositories. The same abuse appeared in other package registries like PyPI and RubyGems, with useless packages clogging up the ecosystem.

To tea’s credit, they reacted quickly. By mid-2024, they added mandatory registration and guardrails against spam. npm uploads returned to normal. But the damage was already done: the NPM registry is still littered with those packages.

Good intentions, bad incentives

Goodhart’s Law states: “When a measure becomes a target, it ceases to be a good measure.” In simpler terms, the moment you tie money to a metric — like GitHub stars, dependency counts, or downloads — you create an incentive to optimize for the metric, not the underlying value.

tea Protocol learned this the hard way. And keep in mind, when this happened, tea wasn’t even a major funding allocator yet. Imagine the chaos if large organizations had poured hundreds of thousands of dollars into the system.

Fix one loophole, and another emerges. This isn’t unique to tea — Gitcoin’s quadratic funding battles Sybil attacks, App Store rankings get manipulated constantly, and even academic citation metrics are gamed. Platforms like GitHub Sponsors and thanks.dev take a different approach, enabling companies to fund projects they depend on — even transitive dependencies. While less prone to manipulation, they’re not immune; developers can still game the system by fragmenting code into shallow dependencies. Any funding model based on automation will eventually be exploited.

But let’s assume, for a moment, that you find the perfect metric after all. Let’s say you invent the ungameable tea Protocol 2.0. Now what?

Where does the money come from?

tea’s tokenomics hinge on the price of its cryptocurrency. But if the token’s only utility is to be paid out to maintainers — not to be spent — there’s no real demand. Its effective value is zero. The only way to keep the price above that is to artificially counterbalance the excess supply with enforced staking and built-in deflation, creating demand through financial speculation.

But sustainable, long-term open-source funding can’t be built on speculation. At the end of the day, someone has to open their wallet and pay. Collectively, we seem to agree that it should be those who profit financially from open-source work. But that system has a major flaw.

Why aren't companies funding?

Let me rephrase the question: Why should they? From a company’s perspective, the current system isn’t perfect, but it mostly works (👀 log4j), and best of all, it’s free. As a rational actor, there are only two reasons you’d fund open source:

The open-source project is core to your commercial product. But in this case, why fund it when you could just hire the maintainer? That way, you gain influence over the project and ensure it aligns with your business strategy.
Your product targets developers, and funding open-source projects is good PR. Sponsoring a trendy library or framework can win hearts in the developer community, which is great for hiring and marketing.

Don’t get me wrong — both are valid reasons. Funding with a personal incentive is still infinitely better than not funding at all. But neither scenario solves the Nebraska problem. Critical but unsexy projects stay underfunded.

So, what now?

The xkcd comic endures because it’s not a joke — it’s a reflection of reality. We’ve tried donations (too small), corporate sponsorships (too selective), and blockchain experiments (too gameable). None scale.

Maybe the answer isn’t technical. Maybe it’s a cultural shift — a recognition that open-source infrastructure is as vital as roads or electricity, and that we cannot neglect it in a time when the functioning of our entire modern world depends on it. Or maybe we’re stuck here, forever stacking yet another block on top of our Jenga tower.

What’s your take? Have you seen a funding model that actually works for invisible projects?

Let me know in the comments.

What is the Shadow DOM

georg.dev — Mon, 30 Sep 2024 06:04:19 +0000

Missing style encapsulation

As a web developer, you've probably dealt with the headaches of missing style encapsulation. A single broad CSS selector can unexpectedly mess up the UI somewhere else on your site.

Adding third-party UI libraries only complicates things. Do their CSS class names clash with yours? Will their buttons break yours? Maybe.

The partial solution

Frameworks like Angular or Vue.js offer some form of component-based style encapsulation. Others, like React, let you choose from various style encapsulation libraries, such as styled-components.^[1]

However, their solutions typically offer only pseudo style encapsulation. Instead of fully isolating styles, they often just add prefixes or suffixes to CSS class names following some patterns that hopefully prevent name clashes.

Doesn't this feel like a workaround? It does to me.

Shadow DOM to the rescue

The shadow DOM attempts to fix the issue of missing encapsulation.^[2] It allows you to attach additional subtrees to the main DOM. With this API, you take an HTML node from your DOM and you simply attach a new subtree to it. We call the root node of this new subtree the shadow root. The neat part: styles don't cross this shadow root.

This means, the styles of your subtree don't leak out into the main DOM. Also, the styles of your main DOM don't affect the encapsulated content of the shadow DOM. Moreover, the same encapsulation also applies to browser events. An onclick event originating from the shadow DOM will not bubble up to the root of the main DOM. Instead, it will end at the shadow root.

How the shadow DOM works

There are two different ways how you can set up the shadow DOM. If you want to understand the concept better, take a look at the imperative API. Otherwise, feel free to jump ahead to the declarative API since that one is usually preferred by most developers nowadays.

Imperative API

Heads up: the imperative API does not work for server-side rendering (SSR). If you need SSR, use the declarative approach instead.

Let's assume, we have a very basic HTML structure:

<body>
  <div><span>OUTSIDE the shadow DOM</span></div>
  <div id="host"></div>
</body>

Let's go over this. Our DOM has a <body> element that contains two HTML nodes:

a <div> containing a <span> with the text OUTSIDE the shadow DOM,
a <div> with the ID host. This will be our host element to which we'll attach the shadow DOM.

Next, we get the reference to this <div> element and attach a shadow DOM to it. Then, for the sake of demonstration, we create another <span> and append it to the shadow DOM:

// get the reference to the div
const hostElement = document.querySelector("#host");

// attach a shadow DOM
const shadowDom = hostElement.attachShadow({ mode: "open" });

// create a new HTML node (just for demonstration)
const exampleElement = document.createElement("span");
exampleElement.textContent = "INSIDE the shadow DOM";

// append the new HTML node to the shadow DOM
shadowDom.appendChild(exampleElement);

Now, the new structure looks like this:

If you inspect how this is rendered in the browser, you will see something like this:

<body>
  <div><span>OUTSIDE the shadow DOM</span></div>
  <div id="host">
    #shadow-root (open)
      <span>INSIDE the shadow DOM</span>    
  </div>
</body>

You can see all these steps together in this short animated diagram:

Your browser does not support the video tag.

Declarative API

Heads up: the declarative shadow DOM has only recently been implemented in the last remaining browsers and is not fully adopted yet.^[3] If you use the declarative API, add the required polyfill to your application.^[4]

With the declarative shadow DOM API, you can do the same that we did in the imperative example above in plain HTML:

<body>
    <span>Outside the shadow DOM</span>
    <div id="host">
      <template shadowrootmode="open">
        <span>Inside the shadow DOM</span>
      </template>
    </div>
</body>

Notice that we used the <template> element here. The reason for this is that the <template> element has its own mechanism for rendering its content. If you want to learn more about it, check out my template API article.

References

What is the Template API

georg.dev — Fri, 02 Aug 2024 13:36:49 +0000

The Problem

Re-using HTML within the same page can be tricky. Picture this: you have a complex piece of markup that needs to appear in several places on your page.

As a web developer, you might think, "No problem, I'll just use a framework and create a component.". But does it really make sense to bring in an entire library just to re-use some HTML? Shouldn't re-using HTML be something that is supported natively?

Entering the <template> element.

How it works

Content inside a <template> element isn't rendered when the page loads. However, it's still part of the DOM and can be accessed via JavaScript. This lets you append this content to other DOM nodes and, thereby, making it reusable.^[1]

Consider the following HTML:

<body>
  <span>I'm visible.</span>
  <template id="my-template">
    <span>I'm initially <b>not</b> visible.</span>
  </template>
</body>

As you will see below, the content from inside the <template> is not visible. However, we can get the contents reference and append it to another node where it will be displayed:

// get the refence to the template
const template = document.getElementById('my-template');
// extract and clone the content from the template
const clonedContent = template.content.cloneNode(true);
// append the extracted content to another node
document.body.appendChild(clonedContent);

Now, the previously hidden content becomes visible. Try it out yourself:

This approach not only lets you render content dynamically, showing one component under specific conditions and another under different conditions.

It also allows you to attach the content to multiple nodes, enabling you to declare HTML once and use it multiple times across your page.

Using dynamic content

There's one more thing to consider: dynamic content.

So far, we've only defined static content in the <template>, but what if we want to display dynamic content?

In React, you use the children property for that. In Angular, you use <ng-content>. With the template API, HTML introduces a native element: <slot>.^[2]

The <slot> element specifies the entry point for child nodes. Consider this HTML:

<template>
  <p>Is this the real life</p>
  <slot></slot>
  <p>Caught in a landslide</p>
</template>

<!-- and later -->
<bohemian-rhapsody>
  <p>Is this just fantasy</p>
</bohemian-rhapsody>

The rendered result will be:

As you can see, the content put into the <bohemian-rhapsody> element got rendered into the <slot> element.

If you're wondering where the <bohemian-rhapsody> element came from, check out my upcoming intro to custom elements.

Curious to dive deeper?

In my next articles on georg.dev I’ll break down the other two web component specifications as well: Shadow DOM and Custom Elements. Each article aims to equip you with the tools necessary to implement these technologies in your own projects. Keep learning!

References

What are Web Components

georg.dev — Fri, 05 Jul 2024 14:05:36 +0000

Why Web Components

In 2014, the developer community was hyped: Google just released their new design system, Material Design. It looked fresh and exciting, promising a cohesive and well-thought-out experience. But what if you wanted to use it in your own web app? After all, Material Design is just the design specification.

You needed a component library.

If you were an Angular developer, you would install Angular Material. For React, you would use MUI, and for Vue, you would use Material Vue. Each individual framework needed its own library.

For Material Design 2, each framework still required its own component library since web components weren't supported by all frameworks yet.

Think of all the effort wasted. Not only for the library creators who wrote and maintained the libraries but also for the library users who had to learn them. You could be an expert in Angular Material and still have to re-learn everything if you wanted to do Material Design in React.

But what if we could just write our UI component libraries once and use them in any web framework? This is exactly what happens with Material Design 3. How? With the power of web components.^[1]

For Material Design 3, only one component library is required, which is framework-agnostic thanks to web components.

The Growing Significance of Web Components

Chances are, you've never used a custom web component yet, let alone created one. They are mostly popular among large companies needing framework-agnostic components, like Google, Microsoft, or Netflix. For example, GitHub has been a famous early adopter of web components.^[2] A more recent example is the Photoshop Web UI which was built by relying heavily on the web component framework Lit. In fact, Adobe built their whole Creative Cloud with the power of web components.^[3]

Screenshot of the Photoshop Web UI: Almost every element you see here is a web component.

According to the Google Chrome Platform status report, 15-20% of page loads and around 16% of URLs world-wide contain web components nowadays.^[4] This number has been steadily growing for years and the newly added web component support in React will likely increase it even further.

Google Chrome Platform Status: The number of URLs containing web components has been steadily rising from <0% in 2018 to around 16% in 2024.

What this means for you as a software developer is that even if you've never had any contact web components yet, you will encounter them sooner or later.

Defining a Standard

Even though we talk about the web component standard, it is actually the result of three different specifications:

HTML Templates: allows re-using HTML in the same document
Shadow DOM: Creates encapsulated DOM structures
Custom Elements: Associates HTML elements with JavaScript classes

Each specification already brings useful functionality on its own.
Combined, they create re-usable and encapsulated UI components as a web standard: web components.

Curious to dive deeper?

Check out my upcoming articles on georg.dev where I’ll break down each of the three specifications: HTML Templates, Shadow DOM, and Custom Elements. Each article aims to equip you with the tools necessary to implement these technologies in your own projects. Keep learning!