mingfang.tech

Author: Ming Fang

  • The simplest way to code with Copilot Instructions

    I’ve been exploring the easiest way to kickstart a new page or revamp an existing component using the company’s proprietary design system. The most straightforward approach is to use the design system’s instructions as the foundation, incorporating its documentation directly into the codebase for added context.

    Supercharging Your Development with GitHub Copilot Custom Instructions

    GitHub Copilot has become an indispensable tool for many developers, but did you know you can make it even more powerful by providing custom instructions? As of May 2025, custom instructions have evolved to become one of the most effective ways to tailor Copilot to your specific development needs and standards. In this blog post, I’ll guide you through how to leverage this feature to significantly improve your team’s productivity, especially for frontend development workflows.

    Custom instructions allow you to provide context about your project, coding standards, and preferred libraries directly to GitHub Copilot, resulting in more accurate and useful code suggestions.

    What Are GitHub Copilot Custom Instructions?

    Custom instructions are essentially specialised prompts you give to GitHub Copilot to guide its responses and code suggestions. Think of them as a way to “train” Copilot to understand your project’s specific context, coding standards, and technical preferences without having to repeatedly mention these details in every prompt.

    For example, instead of telling Copilot each time that you prefer using double quotes for JavaScript strings, you can set this preference once in your custom instructions. This context is invisibly added to every interaction you have with Copilot, making its responses more relevant and aligned with your standards.

    There are three main levels of custom instructions:

    1. Personal instructions: Apply to all your interactions with Copilot
    2. Repository instructions: Apply to everyone working with a specific repository
    3. Organisation instructions: Apply to all members of your organisation (for Enterprise users)

    Types of GitHub Copilot Custom Instructions

    Repository Custom Instructions

    Repository-level instructions are stored in a .github/copilot-instructions.md file at the root of your repository. These instructions are automatically applied whenever someone uses Copilot with that repository, ensuring consistent responses across your team.

    This approach is particularly valuable for maintaining coding standards across larger teams. When a new developer joins the project, they automatically get the same Copilot guidance as everyone else, without needing to learn and manually apply the project standards.

    Personal Custom Instructions

    Personal instructions allow individual developers to set their own preferences that will apply across all their GitHub Copilot interactions. These take precedence over repository and organisation instructions.

    To set personal instructions, you can:

    1. Click the Copilot icon in the top right of any GitHub page
    2. Select “Personal instructions” from the dropdown menu
    3. Add your custom instructions in the text box
    4. Click “Save”

    These instructions will follow you across different repositories and projects.

    VS Code-Specific Settings

    In Visual Studio Code, there are additional ways to customise GitHub Copilot through settings. You can set specific instructions for different tasks like code generation, test generation, commit message generation, and more:

    {
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "file": ".copilot-code-instructions.md"
    }
  ],
}

    Creating and Using Repository Custom Instructions

    Attention: Please verify that you are using the latest versions. The versions tested so far are VS Code Mac 1.100.2 and Copilot 0.27.1.

    Setting Up the Instructions File

    Let’s walk through how to set up repository instructions for a frontend project using the company’s design system:

    1. Create a .github directory at the root of your repository (if it doesn’t already exist)
    2. Create a file named copilot-instructions.md inside the .github directory
    3. Add your custom instructions in Markdown format

    Sample Instructions for Frontend Development with the Company’s Design System

    Here’s an example of what your .github/copilot-instructions.md file might look like for a frontend project using the company’s design system:

    - This is a React project using TypeScript and Vite.
- Use functional components and React Hooks.
- Follow ES6+ syntax.
- Write unit tests using Vitest and React Testing Library.
- Mock API responses using MSW (Mock Service Worker). Handlers are in `src/mocks/handlers.ts`.
- Follow ESLint and Prettier rules for code consistency. You can run `yarn lint:fix` to format.
- Component names should be in PascalCase.
- UI components are prefixed with the company namespace (e.g., `CompanyButton`, `CompanyInput`).
- Use the `~/*` path alias to refer to files in the `src` directory (e.g., `import MyComponent from '~/components/MyComponent';`).
- Access environment variables using `import.meta.env.VITE_VARIABLE_NAME`.
- Always check for errors and fix them.
- Do not allow implicit 'any' types in TypeScript. Always specify explicit types where required.
- Use the documentation in the company’s design system directory for reference.

    With these instructions in place, GitHub Copilot will understand your project context and provide more relevant code suggestions.

    Writing Effective Custom Instructions

    Best Practices

    1. Keep instructions concise and specific: Focus on the most important guidelines that will influence code structure and style.
    2. Use clear, self-contained statements: Each instruction should be a complete thought that can be understood on its own.
    3. Consider repository complexity: For large repositories with diverse components, avoid overly restrictive instructions that might not apply to all areas.
    4. Avoid conflicting instructions: If you have multiple types of instructions (personal, repository, organisation), try to avoid conflicts between them.
    5. Update instructions as your project evolves: As your project grows and standards change, keep your instructions file up to date.

    What to Include

    Your instructions can cover a wide range of aspects:

    • Coding standards and conventions
    • Preferred libraries and frameworks
    • Project-specific context
    • Common patterns used in your codebase
    • Documentation requirements
    • Testing approaches

    Advanced Usage: Specialised Instruction Files

    Beyond the standard .github/copilot-instructions.md file, VS Code also supports more specialised instruction files:

    Task-Specific Instructions

    You can create separate instruction files for different coding tasks. For example:

    {
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "file": "copilot-code-instructions.md"
    }
  ],
  "github.copilot.chat.reviewSelection.instructions": [
    {
      "file": "copilot-review-instructions.md"
    }
  ],
  "github.copilot.chat.testGeneration.instructions": [
    {
      "file": "copilot-test-instructions.md"
    }
  ],
  "github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
    {
      "file": "copilot-test-instructions.md"
    }
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {
      "file": "copilot-commit-message-instructions.md"
    }
  ]
}

    Real-World Benefits for Your Team

    Implementing custom instructions for GitHub Copilot offers several tangible benefits:

    1. Consistent Code Quality: Ensures all AI-generated code follows your established standards.
    2. Reduced Onboarding Time: New team members immediately benefit from contextual guidance about your project’s patterns and practices.
    3. Improved Collaboration: Creates alignment across teams by standardizing how Copilot assists different developers.
    4. Time Savings: Reduces the need to repeatedly correct or reformat Copilot suggestions to match your standards.
    5. Knowledge Preservation: Captures important project context and standards that can be maintained over time.

    Conclusion

    GitHub Copilot custom instructions represent a powerful way to tailor AI assistance to your specific development needs. By taking the time to set up well-crafted instructions, you can drastically improve the quality and relevance of Copilot’s suggestions, leading to more efficient workflows and more consistent code.

    For frontend teams working with the company’s design system, custom instructions can ensure that all developers—regardless of their familiarity with the system—can generate code that follows established patterns and best practices.

    I encourage you to start with a simple .github/copilot-instructions.md file in your repository and gradually refine it as you learn what instructions are most effective for your team’s needs. The investment in setting up these instructions will pay dividends in development efficiency and code consistency.

    Remember, the most effective instructions are specific, concise, and regularly updated as your project evolves. Happy coding!