GitHub Copilot Instruction Files Explained
May 2026
GitHub Copilot now has three different instruction surfaces — VS Code, Visual Studio, and Copilot CLI — and they all use Markdown. That's exactly why they're confusing. This post gives you the correct mental model, the right folder structure, and clear rules for when to use each one.
The Three Types of Instruction File
There are three kinds of Markdown instruction file, each with a distinct purpose:
1. Project-level rules
.copilot/instructions.md
Used by VS Code and Visual Studio automatically. Tells Copilot how to behave across the entire repo.
2. Feature specs
specs/<feature>.spec.md
Task-specific generation instructions. Passed explicitly to Copilot Chat or the CLI.
3. Solution blueprint
solution.blueprint.md
High-level architecture document. Referenced when generating new features to give Copilot the full picture.
Why This Is Confusing
All three files are Markdown. All three influence Copilot's output. But they are read by completely different surfaces, and none of them are interchangeable:
- VS Code and Visual Studio only read from
.copilot/instructions.md - Copilot CLI only reads what you pass via
--context - Copilot SDK reads whatever you load into the agent
- None of them automatically read your feature specs or blueprints unless you explicitly include them
The key insight is to separate global behaviour from generation instructions. Once that clicks, the whole system becomes predictable.
The Correct Mental Model
.copilot/instructions.md — The Global Rulebook
This is the file VS Code and Visual Studio read automatically. Think of it as a persistent system prompt for your repository — it tells Copilot how to behave regardless of what you're generating.
What belongs here:
- Coding style and naming conventions
- Architecture rules and folder structure
- Dependency rules ("never use EF Core migrations directly")
- Framework preferences ("always use MediatR for commands")
- Testing conventions
- Forbidden patterns
This file is not for feature specs. Keep it to rules and conventions.
specs/<feature>.spec.md — Task-Specific Instructions
These are one-off generation briefs. Each file describes what you want Copilot to build right now — inputs, outputs, UI structure, API endpoints, state requirements, routing, edge cases.
Examples of what belongs here:
- Generate a Blazor component for the travel gallery
- Create a domain service for trade execution
- Build a SQL repository for UserProfile
- Scaffold an Angular component with a specific form layout
You pass these explicitly:
gh copilot generate --context specs/travel-gallery.spec.md
# or in Copilot Chat:
@workspace /specs/travel-gallery.spec.md solution.blueprint.md — The Architecture Document
This is your single source of truth for the entire system. It defines project layout, domain boundaries, naming conventions, technology stack, dependency flow, and how modules communicate.
VS Code does not read this automatically. You reference it when generating new features to give Copilot the full architectural picture before producing code.
When to Use Which File
| Situation | File | Reason |
|---|---|---|
| You want Copilot to follow your architecture rules everywhere | .copilot/instructions.md | IDE reads it automatically |
| You want Copilot to generate a specific feature | specs/<feature>.spec.md | Task-specific, passed explicitly |
| You want Copilot to understand the whole system | solution.blueprint.md | High-level context for generation |
| You're using Copilot CLI to generate code | --context specs/*.spec.md | CLI requires explicit file references |
| You want consistent behaviour across VS Code and VS.NET | .copilot/instructions.md | Both IDEs pick this up automatically |
How They Work Together
For the best results, combine all three when generating a feature. You give Copilot the rules, the architecture, and the task — and the output becomes dramatically cleaner and more consistent.
gh copilot generate \
--context .copilot/instructions.md \
--context solution.blueprint.md \
--context specs/travel-gallery.spec.md Rules
.copilot/instructions.md
Style, conventions, forbidden patterns
Architecture
solution.blueprint.md
Project layout, domain boundaries
Task
specs/<feature>.spec.md
What to generate right now
Blazor + Visual Studio Setup
For a Blazor application in Visual Studio, the setup is straightforward. Visual Studio automatically picks up .copilot/instructions.md — you don't need to configure anything.
Recommended Folder Structure
/MySolution
/src
/Api
/Application
/Domain
/Infrastructure
/Web
/Components
/Pages
/Shared
/Layout
/tests
/.copilot
instructions.md
/specs
travel-gallery.spec.md
user-management.spec.md
solution.blueprint.md
MySolution.sln Example: .copilot/instructions.md for Blazor
Rules that belong here — what Copilot should always follow in this Blazor repo:
# Copilot Instructions — MySolution
## Architecture
- Clean Architecture: Domain, Application, Infrastructure, Api, Web
- Domain project has zero external dependencies
- Use MediatR for all commands and queries
- Use FluentValidation for request validation
## Blazor
- Use Blazor Server with interactive server-side rendering
- Components live in Web/Components/Pages or Web/Components/Shared
- Use @inject for DI, not constructor injection in components
- Use cascading parameters for layout state, not static services
- Prefer @rendermode InteractiveServer only where needed
## Naming
- Components: PascalCase, suffix with .razor
- Services: PascalCase, suffix with Service
- Commands: PascalCase, suffix with Command
- Queries: PascalCase, suffix with Query
## Forbidden
- Do not use ViewState or code-behind patterns
- Do not generate EF Core models directly — always go through repositories
- Do not use static classes for business logic Example: specs/travel-gallery.spec.md for Blazor
A feature spec — passed explicitly when generating:
# Feature Spec: Travel Gallery Component
## Goal
A Blazor component that displays a paginated grid of travel photographs.
## Component
- Name: TravelGallery.razor
- Location: Web/Components/Pages/Gallery/
- Route: /gallery/travel
## Data
- Fetches photos via IPhotoService (already exists in Application layer)
- Query: GetTravelPhotosQuery returns IReadOnlyList<PhotoDto>
- Each PhotoDto: Id, Title, Location, ImageUrl, TakenAt
## UI
- Responsive grid: 3 columns on desktop, 2 on tablet, 1 on mobile
- Each card: image, title, location badge, date
- Pagination: 12 per page, previous/next buttons
- Loading skeleton while fetching
## Edge Cases
- Show empty state message when no photos exist
- Handle service errors gracefully with a retry button How Visual Studio Uses These Files
Automatic
.copilot/instructions.md — VS picks this up without any configuration.
Explicit in Chat
Drag or reference spec and blueprint files into the Copilot Chat context when generating a feature.
Explicit in CLI
Pass all three via --context flags when using the Copilot CLI from the VS Developer terminal.
Angular + VS Code Setup
Angular projects in VS Code use exactly the same Copilot instruction model. The difference is that Angular projects tend to grow complex quickly — so structuring instruction files well pays off more than it does in smaller codebases.
Recommended Folder Structure
/my-angular-app
/src
/app
/core
/services
/interceptors
/guards
/models
/shared
/components
/pipes
/directives
/features
/travel
/art
/trading
/layouts
/utils
/.copilot
instructions.md
/specs
travel-gallery.spec.md
art-feed.spec.md
trading-dashboard.spec.md
solution.blueprint.md
angular.json
package.json
tsconfig.json Example: .copilot/instructions.md for Angular
Global rules that VS Code applies to every Copilot interaction in this workspace:
# Copilot Instructions — my-angular-app
## Components
- Use standalone components — no NgModules
- Use ChangeDetectionStrategy.OnPush by default
- Use Angular signals instead of RxJS BehaviorSubject for local state
- Keep templates lean: extract logic into the component class or a service
## Styling
- Use SCSS for all component styles
- Use CSS custom properties for theming — no hard-coded colour values
- Follow BEM naming for component-scoped classes
## State & Data
- Use Angular signals for component state
- Use RxJS only where streaming or async coordination is required
- Fetch data via typed HttpClient services in /core/services
- Never call HttpClient directly from a component
## Routing
- Use lazy-loaded routes for all feature modules
- Protect routes via guards in /core/guards
## Testing
- Use Jest for unit tests
- Use Cypress for e2e tests
- Test component behaviour, not implementation details
## Forbidden
- Do not use NgModules
- Do not use zone.js-dependent patterns in new code
- Do not use any as a TypeScript type Example: specs/travel-gallery.spec.md for Angular
A feature spec for an Angular component — pass this explicitly when generating:
# Feature Spec: Travel Gallery Component
## Goal
A standalone Angular component that displays a paginated grid of travel photographs.
## Component
- Selector: app-travel-gallery
- Location: src/app/features/travel/
- Route: /gallery/travel (lazy-loaded)
## Data
- Inject TravelService from /core/services
- Method: getPhotos(page: number): Observable<PhotoPage>
- PhotoPage: { photos: Photo[], total: number, page: number }
- Photo: { id: string, title: string, location: string, imageUrl: string, takenAt: Date }
## UI
- Responsive grid: 3 columns on desktop, 2 on tablet, 1 on mobile
- Each card: image, title overlay, location badge, date
- Pagination: 12 per page, previous/next buttons
- Loading state: skeleton cards while fetching
## State
- Use Angular signals: currentPage, photos, isLoading, hasError
- Trigger fetch on currentPage change via effect()
## Edge Cases
- Empty state message when no photos returned
- Error state with retry button Generating the Component in VS Code
# In Copilot Chat (VS Code):
@workspace Generate the travel gallery component.
Use /specs/travel-gallery.spec.md and /solution.blueprint.md for context.
# Or via Copilot CLI:
gh copilot generate \
--context .copilot/instructions.md \
--context solution.blueprint.md \
--context specs/travel-gallery.spec.md What VS Code Reads Automatically vs. Explicitly
Automatic (no action needed)
.copilot/instructions.md
Explicit (you reference them)
specs/*.spec.md— in Chat or via--contextsolution.blueprint.md— in Chat or via--context
Summary
The three instruction files map to three distinct concerns. Once you separate them clearly, Copilot becomes a significantly more reliable tool — because it always has the right context for the right job.
.copilot/instructions.md— global rules, read automatically by VS Code and Visual Studiospecs/<feature>.spec.md— what to generate right now, always passed explicitlysolution.blueprint.md— the system architecture, referenced alongside specs
The pattern works the same whether you're in a Blazor solution in Visual Studio or an Angular workspace in VS Code. The tooling differs slightly; the mental model does not.