/
Copilot Instructions

Copilot Instructions

This document will introduce a very common and powerful context file, copilot-instructions.md. You’ll learn how it works, why it’s useful, and how to generate one quickly and easily.

What Are Copilot Instructions?

GitHub Copilot’s copilot-instructions.md file lets you guide how the AI generates code inside a repository.
Think of it like a “style and context guide” for Copilot, telling it how your team writes code, what frameworks you use, and how you want responses structured.

Without this file, Copilot guesses based on code patterns alone.
With it, you explicitly tell Copilot things like:

  • The preferred frameworks and libraries

  • How files are organized

  • What naming conventions you use

  • Which syntax or patterns to prefer (e.g., arrow functions vs. function syntax)

  • Rules for tests, comments, and styles

Example: Without vs With Instructions

Prompt:
“Create a function that adds two numbers.”

Without Instructions:

function add(a, b) { return a + b; }

With Instructions (copilot-instructions.md says “Use arrow functions”):

const add = (a, b) => a + b;

Even subtle differences like this help Copilot align with your team’s style consistently across the codebase.

Why Instructions Matter

Copilot uses context, including open files, visible code, and the repository’s copilot-instructions.md.
The file acts as persistent context that’s always considered when generating suggestions.

One way to think of it is like defining a role or persona for Copilot:

  • “You are a React developer using hooks and TypeScript.”

  • “You follow Airbnb’s ESLint conventions.”

  • “You prefer functional programming.”

Instructions files can also be used to tell Copilot about your codebase’s architecture, your team’s conventions, and any style or formatting details that are relevant

  • “Test files are stored in /tests/{filename}.test.js"

  • “Use snake_case for variable names, never camelCase”

  • “All classes should use getters and setters”

By writing clear instructions, you help Copilot make smarter, on-brand decisions automatically.

Generating Instructions Automatically

You can create a copilot-instructions.md file manually, or have Copilot generate one for you.

Bitovi has developed a custom prompt chain that systematically analyzes a codebase step-by-step before generating the final copilot-instructions.md.
This process is AI-driven, but far more structured and complete than asking Copilot to “just generate it.”

Prompt chain: ai-enablement-prompts/understanding-code/instruction-generation/README.md at main · bitovi/ai-enablement-prompts

Overview of the Prompt Chain

Goal: Produce a single copilot-instructions.md file that encapsulates the architecture, domains, and conventions of your codebase.

Each prompt in the chain builds on the last and outputs context files into a results folder:

Step

File

Purpose

Step

File

Purpose

1

1-determine-techstack.md

Identify language, frameworks, and domain focus

2

2-categorize-files.md

Classify every file by role and purpose

3

3-identify-architecture.md

Understand major architectural patterns

4

4-domain-deep-dive.md

Explore how each domain is implemented

5

5-styleguide-generation.md

Extract unique style and code conventions

6

6-build-instructions.md

Combine everything into the final instructions file

Step-by-Step Breakdown

1. Determine Tech Stack

Analyzes:

  • Primary programming languages

  • Frameworks (e.g. React, Next.js, Prisma)

  • Domain concepts (e.g. “task management app”)

  • Data types and architectural boundaries

Outcome: .results/1-techstack.md

2. Categorize Files

Categorizes files by function (e.g., components, hooks, utils)
and writes the results as JSON:

{ "react-components": ["./src/components/Button.tsx"], "hooks": ["./src/hooks/useUser.ts"] }

Outcome: .results/2-file-categorization.json

3. Identify Architecture

Reads the categorization and maps out architectural domains:

  • UI, routing, data layer, auth, etc.

  • Lists required patterns (e.g. all API calls go through apiClient.ts)

Outcome: .results/3-architectural-domains.json

4. Domain Deep Dive

For each domain (e.g., UI, state-management, API), the AI:

  • Analyzes real code examples

  • Describes implementation patterns and conventions

  • Documents what is actually used, not what’s ideal

Outcome: .results/4-domains/{domain}.md

5. Style Guide Generation

Generates one markdown file per category (components, hooks, etc.)
Each file documents project-specific stylistic conventions.

Outcome: .results/5-style-guides/{category}.md

6. Build Instructions

Synthesizes everything into a final copilot-instructions.md, including:

  • Overview of the project

  • File category reference

  • Feature scaffold guide

  • Integration rules

  • Example prompt usage

Outcome: .github/copilot-instructions.md

Next Steps

Now that you understand how Copilot Instructions work, it’s time to generate one yourself.

Continue to: Context Engineering Workshop | ✏️ Steps.1