GitHub Copilot Instructions Guide

- Define your project's coding standards and conventions
- Specify preferred frameworks, libraries, and patterns
- Set language and response format preferences
- Guide Copilot toward your team's architectural decisions
- Reduce repetitive corrections across chat sessions
- Ensure consistent suggestions across all team members

1. Developer opens Copilot Chat or triggers a suggestion
2. Copilot checks for instruction files in the repository
3. Matching instructions are appended to the request context
4. Copilot generates responses informed by your instructions
5. Path-specific instructions are combined with repo-wide ones

┌─────────────────────────────────────────────────────────┐
│  Type              │ File / Location                    │
├─────────────────────────────────────────────────────────┤
│  Repository-wide   │ .github/copilot-instructions.md    │
│  Path-specific     │ .github/instructions/*.instructions.md │
│  Agent             │ AGENTS.md / CLAUDE.md / GEMINI.md  │
└─────────────────────────────────────────────────────────┘

Repository-wide instructions:
  → Project-level coding standards
  → Tech stack preferences
  → General conventions (naming, formatting, patterns)

Path-specific instructions:
  → Language or framework-specific rules
  → Different conventions for frontend vs backend
  → File-type-specific patterns (tests, components, APIs)

Agent instructions:
  → Multi-step task workflows for AI coding agents
  → Repository-specific agent behaviors
  → CI/CD and automation guidance

# What Copilot sees for a .tsx file:

1. Repository-wide instructions (always included)
   → "Use TypeScript strict mode, prefer functional patterns..."

2. Path-specific instructions (when glob matches)
   → "Use React Server Components by default, co-locate styles..."

3. The developer's actual chat message or code context

your-project/
├── .github/
│   └── copilot-instructions.md   ← Repository-wide instructions
├── src/
├── package.json
└── README.md

# Project Instructions for Copilot

## Language and Framework
- This is a TypeScript project using React 19 and Next.js 15
- Always use TypeScript with strict mode enabled
- Use the App Router (not Pages Router)

## Code Style
- Use functional components with arrow function syntax
- Prefer named exports over default exports
- Use `interface` for object shapes, `type` for unions and intersections
- Use template literals instead of string concatenation

## Naming Conventions
- Components: PascalCase (e.g., UserProfile)
- Files: kebab-case (e.g., user-profile.tsx)
- Variables and functions: camelCase
- Constants: UPPER_SNAKE_CASE
- CSS classes: kebab-case

## Testing
- Write tests using Vitest and React Testing Library
- Co-locate test files next to source (*.test.ts)
- Prefer userEvent over fireEvent for interactions

Good candidates for repository-wide instructions:
  ✓ Programming language version and strict mode settings
  ✓ Framework and library preferences
  ✓ Naming conventions (files, variables, components)
  ✓ Error handling patterns
  ✓ Import ordering rules
  ✓ Code formatting preferences
  ✓ Documentation and comment standards

Not ideal for repository-wide instructions:
  ✗ Rules that only apply to certain file types
  ✗ Detailed API endpoint documentation
  ✗ Environment-specific configuration
  ✗ File-path-specific patterns (use path-specific instead)

your-project/
├── .github/
│   ├── copilot-instructions.md              ← Repo-wide
│   └── instructions/
│       ├── react-components.instructions.md  ← TSX files
│       ├── api-routes.instructions.md        ← API files
│       ├── tests.instructions.md             ← Test files
│       └── styles.instructions.md            ← CSS files
├── src/
└── package.json

---
applyTo: "**/*.tsx"
---

---
applyTo: "**/*.tsx"
---

# React Component Instructions

- Use functional components with arrow function syntax
- Define props with a TypeScript `interface` named `{ComponentName}Props`
- Destructure props in the function parameters
- Use React Server Components by default unless client interactivity is needed
- Add "use client" directive only when the component uses hooks or event handlers
- Co-locate CSS Modules in the same directory as the component
- Include a `data-testid` attribute on the root element for testing
- Use `React.Suspense` boundaries for async data loading

---
applyTo: "src/app/api/**/*.ts"
---

# API Route Instructions

- Use Next.js App Router route handlers (export GET, POST, etc.)
- Validate all request bodies with Zod schemas
- Return consistent JSON response shapes: { data } or { error }
- Always include appropriate HTTP status codes
- Add rate limiting headers to public endpoints
- Log errors to the structured logger, never to console
- Use the `withAuth` wrapper for protected endpoints

---
applyTo: "**/*.test.{ts,tsx}"
---

# Test File Instructions

- Use Vitest as the test runner with React Testing Library
- Structure tests with describe/it blocks
- Follow the Arrange-Act-Assert pattern
- Use `screen.getByRole` over `getByTestId` when possible
- Mock external API calls using MSW (Mock Service Worker)
- Test accessibility with `toBeAccessible()` matcher
- Include at least one happy path, one edge case, and one error case

Common glob patterns for applyTo:

  "**/*.tsx"                → All TSX files in the project
  "**/*.test.ts"            → All TypeScript test files
  "src/app/api/**/*.ts"     → API route files only
  "**/*.css"                → All CSS files
  "src/components/**/*"     → All files in components directory
  "**/*.{ts,tsx}"           → All TypeScript and TSX files
  "docs/**/*.md"            → All Markdown files in docs
  "**/migrations/**/*.sql"  → All SQL migration files

Chat Instructions (copilot-instructions.md):
  → Guide interactive Copilot Chat responses
  → Included with every chat message
  → Focus on code style and conventions

Agent Instructions (AGENTS.md):
  → Guide autonomous Copilot coding agents
  → Used when agents operate independently
  → Focus on workflows, commands, and multi-step tasks

your-project/
├── AGENTS.md            ← Root-level agent instructions
├── CLAUDE.md            ← Claude-specific instructions (optional)
├── GEMINI.md            ← Gemini-specific instructions (optional)
├── src/
│   ├── AGENTS.md        ← Subdirectory instructions (scoped)
│   ├── frontend/
│   │   └── AGENTS.md    ← Frontend-specific agent rules
│   └── backend/
│       └── AGENTS.md    ← Backend-specific agent rules
└── package.json

# Agent Instructions

## Project Overview
This is a Next.js 15 full-stack application with a PostgreSQL database.

## Build and Test Commands
- Install dependencies: `npm install`
- Run dev server: `npm run dev`
- Run all tests: `npm test`
- Run specific test file: `npx vitest run path/to/file.test.ts`
- Type check: `npx tsc --noEmit`
- Lint: `npm run lint`

## Code Standards
- Always run `npm run lint` and `npm test` before submitting changes
- Never commit changes that break the TypeScript build
- Follow existing patterns in the codebase for new features
- Add tests for all new functionality

## Database Changes
- Create migrations with `npx drizzle-kit generate`
- Never modify existing migrations — create new ones instead
- Test migrations against a local database before submitting

CLAUDE.md   → Instructions specific to Claude (Anthropic)
GEMINI.md   → Instructions specific to Gemini (Google)
AGENTS.md   → General instructions for all agents

# Create the .github directory (if it doesn't exist)
mkdir -p .github/instructions

# Create the repository-wide instructions file
touch .github/copilot-instructions.md

# Create path-specific instruction files
touch .github/instructions/react.instructions.md
touch .github/instructions/api.instructions.md
touch .github/instructions/tests.instructions.md

# Copilot Instructions

## Tech Stack
- TypeScript 5.x with strict mode
- React 19 with Next.js 15 (App Router)
- Tailwind CSS for styling
- Vitest + React Testing Library for tests
- PostgreSQL with Drizzle ORM

## General Rules
- Always write TypeScript, never plain JavaScript
- Use `const` by default, `let` only when reassignment is needed
- Prefer early returns over deeply nested conditionals
- Handle errors explicitly — never silently catch and ignore
- Write self-documenting code; add comments only for "why", not "what"

---
applyTo: "src/components/**/*.tsx"
---

# Component Instructions

- Use Server Components by default
- Add "use client" only when hooks or event handlers are needed
- Define props interface above the component function
- Use Tailwind utility classes for styling
- Include aria attributes for interactive elements
- Export components as named exports

{
  "github.copilot.chat.codeGeneration.useInstructionFiles": true
}

# Bad — too vague
- Write good code
- Follow best practices
- Use proper error handling

# Good — specific and actionable
- Use try/catch blocks for all async operations
- Return typed error objects using the AppError class from src/lib/errors
- Log errors with the structured logger: logger.error({ err, context })
- Never expose internal error details in API responses

# Less effective — only negations
- Don't use var
- Don't use class components
- Don't use default exports

# More effective — positive direction
- Use `const` for variables that are not reassigned, `let` otherwise
- Use functional components with arrow function syntax
- Use named exports: export const ComponentName = () => ...

# API Response Format

Always return API responses in this shape:

Success: { data: T, meta?: { page, total } }
Error:   { error: { code: string, message: string } }

Example success response:
{ "data": { "id": 1, "name": "Alice" }, "meta": { "page": 1, "total": 50 } }

Example error response:
{ "error": { "code": "NOT_FOUND", "message": "User not found" } }

# Too verbose
When you write a function, you should always make sure that the
function has a clear and descriptive name that explains what the
function does. The name should be in camelCase format and should
start with a verb that describes the action being performed.

# Concise and clear
- Name functions with a verb prefix in camelCase: getUserById, validateEmail, parseConfig

# Project Instructions

## Code Style
- ...

## Naming Conventions
- ...

## Error Handling
- ...

## Testing
- ...

## Architecture
- ...

# Copilot Instructions — Next.js Project

## Framework
- Next.js 15 with App Router
- React 19 with Server Components by default
- TypeScript in strict mode

## Components
- Functional components only (arrow functions)
- Props interfaces named {ComponentName}Props
- Use Server Components by default
- Add "use client" only for interactivity (hooks, event handlers)
- Co-locate styles, tests, and types with components

## Data Fetching
- Use Server Components with async/await for data fetching
- Use React Server Actions for mutations
- Cache with `unstable_cache` or `fetch` cache options
- Handle loading states with Suspense boundaries

## Routing
- File-based routing under src/app/
- Use route groups (parentheses) for layout organization
- Dynamic routes with [param] directories
- Parallel routes with @slot directories

# Copilot Instructions — Django Project

## Language
- Python 3.12+ with type hints on all function signatures
- Use pathlib for file paths, not os.path
- Use f-strings for string formatting

## Django Conventions
- Class-based views for standard CRUD operations
- Function-based views for custom/complex endpoints
- Use Django REST Framework serializers for API validation
- Prefer querysets over raw SQL
- Use select_related/prefetch_related to avoid N+1 queries

## Testing
- Use pytest with pytest-django
- Factory Boy for test data generation
- Test at the view level (integration) and model level (unit)

## Code Quality
- Follow PEP 8 and isort for import ordering
- Use dataclasses or Pydantic for non-ORM data structures
- Keep views thin — business logic goes in services/

# Copilot Instructions — Rust Project

## Language
- Rust 2024 edition
- Use Result and Option types — never unwrap in production code
- Prefer &str over String for function parameters
- Use #[derive] for common traits (Debug, Clone, PartialEq)

## Error Handling
- Use thiserror for library error types
- Use anyhow for application error types
- Propagate errors with the ? operator
- Add context to errors with .context() from anyhow

## Structure
- Keep modules focused and small
- Use pub(crate) to limit visibility
- Place integration tests in tests/ directory
- Benchmark performance-critical code with criterion

---
applyTo: "**/*.css"
---

# CSS Instructions

- Use CSS custom properties (variables) for all colors and spacing
- Follow mobile-first responsive design
- Use logical properties (margin-inline, padding-block) over physical ones
- Use CSS Grid for page layouts, Flexbox for component layouts
- Prefer rem units for font sizes, px for borders and shadows
- Use @layer for cascade management
- Include prefers-reduced-motion media queries for animations

---
applyTo: "**/*.md"
---

# Documentation Instructions

- Use ATX-style headings (# not underlines)
- Include a table of contents for documents over 3 sections
- Use fenced code blocks with language identifiers
- Add alt text to all images
- Keep line length under 100 characters for readability
- Use relative links for internal documentation references

┌──────────────────────────────────────────────────────────────┐
│  Platform          │ Repo-wide │ Path-specific │ Agent      │
├──────────────────────────────────────────────────────────────┤
│  VS Code           │    ✓      │      ✓        │    ✓       │
│  JetBrains IDEs    │    ✓      │      ✓        │    ✓       │
│  GitHub.com        │    ✓      │      —        │    ✓       │
│  Visual Studio     │    ✓      │      ✓        │    ✓       │
│  Xcode             │    ✓      │      —        │    —       │
│  Eclipse           │    ✓      │      —        │    —       │
└──────────────────────────────────────────────────────────────┘

{
  "github.copilot.chat.codeGeneration.useInstructionFiles": true
}

1. Open Settings → Languages & Frameworks → GitHub Copilot
2. Check "Use instruction files" is enabled
3. Restart the IDE if you've just added instruction files

# Start with 5-10 key rules
- Focus on your most common corrections to Copilot
- Add rules that address patterns Copilot gets wrong
- Remove rules that Copilot already follows naturally

# Iterate based on experience
- Notice Copilot ignoring a convention? Add an instruction
- Find an instruction that's never relevant? Remove it
- Getting inconsistent results? Make the instruction more specific

Layer 1: Repository-wide (.github/copilot-instructions.md)
  → Language, framework, and universal conventions

Layer 2: Path-specific (.github/instructions/*.instructions.md)
  → File-type and directory-specific rules

Layer 3: Agent instructions (AGENTS.md)
  → Autonomous workflow commands and procedures

Why commit instruction files:
  ✓ Ensures all team members get the same Copilot behavior
  ✓ Instructions evolve alongside the codebase
  ✓ Changes are tracked and reviewable in pull requests
  ✓ New team members inherit conventions automatically

# Problem — contradiction between files:
# copilot-instructions.md says:
  "Use default exports for all components"
# react.instructions.md says:
  "Use named exports for all components"

# Solution — be consistent or scope clearly:
# copilot-instructions.md:
  "Use named exports by default"
# react.instructions.md:
  "Use named exports. Export page components as default
   only in page.tsx files (required by Next.js)"

Maintenance tips:
  ✓ Review instructions when upgrading frameworks
  ✓ Remove outdated rules (e.g., patterns from older versions)
  ✓ Add a "Last reviewed" date at the top of each file
  ✓ Keep path-specific files focused (one concern per file)
  ✓ Document the "why" for non-obvious rules

- Copilot instructions guide AI suggestions
- ESLint / Prettier enforce formatting rules
- TypeScript compiler catches type errors
- CI/CD pipelines verify builds and tests

Copilot instructions should align with — not replace —
your linters, formatters, and type checkers.

Problem: Copilot ignores your custom instructions

Solutions:
1. Verify file is at the correct path:
   .github/copilot-instructions.md (not copilot_instructions.md)
2. Check VS Code setting is enabled:
   "github.copilot.chat.codeGeneration.useInstructionFiles": true
3. Check "Used references" in Chat to see if the file is loaded
4. Restart VS Code / your IDE after creating the file
5. Ensure the file is committed (or at least saved locally)

Problem: Path-specific instructions don't apply to expected files

Solutions:
1. Verify the file has .instructions.md extension
2. Check the applyTo glob pattern:
   - "**/*.tsx" matches all .tsx files recursively
   - "*.tsx" only matches .tsx files in the repo root
3. Ensure YAML frontmatter has correct delimiters (---)
4. Test the glob pattern against your actual file paths
5. Verify the file is inside .github/instructions/ directory

Problem: Copilot produces inconsistent results due to conflicting instructions

Solutions:
1. Review all active instruction files for contradictions
2. Use repository-wide instructions for universal rules only
3. Use path-specific instructions for file-type-specific rules
4. If a path-specific rule overrides a global one, note it
   explicitly: "Override: use default exports in page.tsx files"
5. Keep instruction files short and focused on one concern

Problem: Long instructions reduce Copilot's effective context window

Solutions:
1. Prioritize your top 10-15 most impactful rules
2. Remove rules that Copilot already follows by default
3. Consolidate overlapping or redundant instructions
4. Move file-specific rules to path-specific files so they
   only load when relevant
5. Use concise phrasing — bullet points over paragraphs

Problem: Copilot coding agent doesn't follow AGENTS.md

Solutions:
1. Ensure AGENTS.md is at the repository root
2. Check that the file uses standard Markdown formatting
3. Include concrete commands (npm test, npm run lint)
4. Verify the Copilot coding agent feature is enabled
   in your repository settings
5. Subdirectory AGENTS.md files only apply when the agent
   is working in that directory