How to improve my GitHub Copilot results?

Posted on:July 4, 2025 at 05:00 PM

How to improve my GitHub Copilot results?

This week I was on the DWX conference in Mannheim.

I hosted three sessions:

As the first one was related to GitHub Copilot, a lot of attendees came to me during those days asking about how to improve the results of Copilot in their projects.

Without giving a full overview of what’s possible, this is the minimum I do for my projects:

Create instruction files!

One of the most effective ways to improve GitHub Copilot’s results in your projects is by creating instruction files. These files provide context and guidelines that help Copilot understand your project structure, your coding standards and specific requirements.

What are instruction files?

Instruction files are special files that contain information about your project to help GitHub Copilot generate better, more contextually appropriate code. They act as a “README for AI” that describes your project’s architecture, conventions and preferences.

How to create instruction files

  1. Create a “common instructions” file .github/copilot-instructions.md in your project root
  2. Use clear, descriptive language to explain your project and project structure
  3. Include coding standards and naming conventions
  4. Specify frameworks and libraries you’re using
  5. Add examples of your preferred code patterns

Instruction files folder structure in VS Code

What to put in instruction files

Here are first lines of the copilot-instruction.md of this project:

# GitHub Copilot Instructions for harrybin.github.io

## Project Context

This is an Astro-based static site using the AstroPaper theme with:

- **TypeScript** for type safety
- React components for interactive elements
- Tailwind CSS for styling
- Astro Content Collections for blog management
- FuseJS for search functionality
- Deployment on GitHub Pages

## Purpose

The purpose of the project to create a **blog** that showcases developer-focused content, tutorials, and insights.

## Blog Post Creation Guidelines

When creating new blog posts for this Astro-based developer blog, you **MUST** follow these strict requirements:

### File Location and Format

- **MANDATORY**: All new blog posts must be created as `.md` files in `/src/content/blog/`
- **NO EXCEPTIONS**: Do not create blog posts in any other directory
- **File Extension**: Use `.md` for standard markdown or `.mdx` for markdown with JSX components
- **Naming**: Use kebab-case for filenames (e.g., `my-new-blog-post.md`)

### Content Structure Requirements

- **Reference Document**: Follow ALL guidelines specified in `content-md.instructions.md`
- **Frontmatter**: Every blog post MUST include complete YAML frontmatter with all required fields
- **Author**: Always use "Harald Binkle" as the author
- **Date Format**: Use ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) for `pubDatetime`
- **Tags**: Include relevant tags from the approved tag list
- **Description**: Write SEO-friendly descriptions (150-160 characters)

### Enforcement Rules

1. **File Creation**: When asked to create a blog post, ALWAYS create it in `/src/content/blog/`
2. **Template Usage**: Use the exact template structure from `content-md.instructions.md`
3. **Validation**: Ensure all required frontmatter fields are present and correctly formatted
4. **Content Quality**: Follow the writing style and structure guidelines
5. **SEO Compliance**: Include proper meta descriptions, tags, and heading hierarchy

[...]

Another more generic example:

# Project Instructions for AI Assistant

## Project Overview

This is a [description of your project type] using [main technologies].

## Architecture

- Frontend: [Framework/Library]
- Backend: [Framework/Technology]
- Database: [Database type]
- Styling: [CSS framework/approach]

## Coding Standards

- Use TypeScript with strict mode
- Follow ESLint configuration
- Use functional components in React
- Prefer composition over inheritance
- Use descriptive variable names

## File Structure

- `/src/components/` - React components
- `/src/utils/` - Utility functions
- `/src/types/` - TypeScript type definitions
- `/src/hooks/` - Custom React hooks

## Naming Conventions

- Components: PascalCase
- Files: camelCase
- Constants: UPPER_SNAKE_CASE
- Functions: camelCase

## Preferred Patterns

- Use custom hooks for complex state logic
- Implement error boundaries for React components
- Use async/await instead of .then() for promises

The critical importance of describing your project domain

When creating your main instruction file, it’s absolutely crucial to clearly describe what type of project you’re working on. This is especially important when your technology stack doesn’t immediately indicate the project’s purpose. - Like in my case, where I’m using React, TypeScript, and Node.js, but the project is not a traditional web application, it’s a blog based on markdown files.

Why this matters:

Real-world examples where this is critical:

# Example 1: VS Code Extension

## Project Overview

This is a **Visual Studio Code extension** using TypeScript, React, and Node.js.
We're building developer tools, not a web application.

## Business Domain

This extension helps developers manage their project dependencies and provides
automated refactoring suggestions for large codebases.
# Example 2: Office Add-in

## Project Overview

This is a **Microsoft Office add-in** using TypeScript, React, and Office.js APIs.
We're creating productivity tools that run inside Excel/Word, not a standalone web app.

## Business Domain

This add-in helps financial analysts create automated reports and data visualizations
directly within Excel spreadsheets.
# Example 3: Static Site Generator

## Project Overview

This is a **developer blog** built with Astro, TypeScript, and React components.
We're generating static content, not building an interactive web application.

## Business Domain

This blog focuses on sharing technical knowledge about web development, AI tools,
and developer productivity for the software development community.

Key elements to include:

  1. Technical domain: What type of project (web app, extension, CLI tool, blog, etc.)
  2. Business domain: Who uses it and what problem it solves
  3. Platform context: Where it runs (browser, desktop, mobile, server, etc.)
  4. User interaction patterns: How users interact with your project

This context helps Copilot understand whether you need web API patterns, desktop app patterns, CLI tool patterns, or content creation patterns.

Custom instruction files for specific contexts

Instruction files folder structure in VS Code

Beyond the general .github/copilot-instructions.md file, you can create more targeted instruction files for specific file types or folders using VS Code’s .instructions.md files. These are stored in the .github/instructions folder and use the applyTo frontmatter property to automatically apply to specific files.

Documentation Instructions (.github/instructions/docs.instructions.md):

---
description: Instructions for documentation and markdown files
applyTo: "**/*.md"
---

# Documentation Instructions for AI Assistant

## Documentation Style

- Write in clear, beginner-friendly language
- Use active voice and present tense
- Include practical examples for every concept
- Structure content with clear headings and bullet points

## Markdown Guidelines

- Use proper heading hierarchy (H1 for main title, H2 for sections)
- Include code examples with proper syntax highlighting
- Add links to related documentation sections
- Use tables for comparing features or options

## Content Structure

- Start with a brief overview/introduction
- Provide step-by-step instructions
- Include troubleshooting sections
- End with "Next steps" or "See also" sections

## Technical Writing Best Practices

- Define acronyms and technical terms on first use
- Use consistent terminology throughout
- Include prerequisites and assumptions
- Add warnings or notes for important information

## Examples and Code Snippets

- Provide working, tested code examples
- Include both basic and advanced usage scenarios
- Show expected outputs where relevant
- Use realistic data in examples

Configuration Files Instructions (.github/instructions/config.instructions.md):

---
description: Instructions for configuration files
applyTo: "**/{config,*.config.*,*.json,*.yml,*.yaml,*.toml,*.env*}"
---

# Configuration Files Instructions

## Configuration Standards

- Use clear, descriptive property names
- Include inline comments explaining complex settings
- Group related configurations together
- Provide default values and valid ranges

## Environment-Specific Configs

- Separate development, staging, and production configs
- Use environment variables for sensitive data
- Document required vs optional settings
- Include validation rules where applicable

## File Format Guidelines

- For JSON: Use proper formatting and avoid comments in production
- For YAML: Use consistent indentation (2 spaces)
- For ENV files: Use UPPER_SNAKE_CASE for variable names
- Always include example files with documentation

Test Files Instructions (.github/instructions/tests.instructions.md):

---
description: Instructions for test files
applyTo: "**/{test,tests,spec,__tests__}/**/*.{js,ts,jsx,tsx}"
---

# Test Files Instructions

## Testing Standards

- Follow AAA pattern (Arrange, Act, Assert)
- Use descriptive test names that explain the scenario
- Keep tests focused and isolated
- Prefer testing behavior over implementation details

## Test Organization

- Group related tests using describe blocks
- Use beforeEach/afterEach for setup and cleanup
- Create helper functions for common test patterns
- Separate unit, integration, and e2e tests

## Framework-Specific Guidelines

- For React: Use React Testing Library patterns
- For APIs: Test both success and error scenarios
- For E2E: Focus on critical user journeys
- Always consider edge cases and error conditions

## Best Practices

- Mock external dependencies appropriately
- Use meaningful assertions with clear error messages
- Test error conditions and edge cases
- Keep tests maintainable and readable

Advantages of targeted instruction files

Targeted instruction files with applyTo patterns offer several advantages over a single global instruction file:

More precise context

Automatic Context Application

Team Collaboration

Best practices for targeted instruction files

  1. Use descriptive names: Name files clearly like docs.instructions.md, tests.instructions.md, config.instructions.md
  2. Leverage glob patterns: Use specific patterns like **/*.md for markdown files, **/{test,spec}/**/*.{js,ts} for test files
  3. Include descriptions: Always add a description in the frontmatter to explain what the instructions cover
  4. Keep them focused: Each instruction file should cover only what’s relevant to its target files
  5. Test your patterns: Verify that your applyTo patterns match the intended files
  6. Regular maintenance: Update instruction files as your project standards and file structures evolve

Examples of effective applyTo patterns

# Target all markdown files

applyTo: "\*_/_.md"

# Target test files in common test directories

applyTo: "**/{test,tests,spec,**tests**}/**/\*.{js,ts,jsx,tsx}"

# Target configuration files

applyTo: "\*_/{config,_.config._,_.json,_.yml,_.yaml,_.toml,_.env\*}"

# Target specific framework files

applyTo: "\*_/_.{component,page,layout}.{js,ts,jsx,tsx}"

# Target documentation in specific folders

applyTo: "{docs,documentation}/\*_/_.{md,mdx}"

# Target all files (global instructions)

applyTo: "\*\*"

Next Steps: Custom Chat Modes for Large Projects

While instruction files provide an excellent foundation for improving GitHub Copilot results, there’s another powerful technique specifically designed for larger, more complex projects: custom chat modes.

Custom chat modes allow you to create specialized AI configurations for different types of workflows - like code reviews, testing, API design, or documentation. They provide task-specific “personalities” that combine focused instructions with specific tool restrictions.

I’ll be covering this advanced technique in detail in my follow-up article “GitHub Copilot Custom Chat Modes for Large Projects”. This will show you how to create specialized chat configurations that can dramatically improve your AI interactions for complex development workflows.

Have you tried using instruction files in your projects? I’d love to hear about your experiences with improving GitHub Copilot results!