Skip to main content

GitHub Copilot Instructions

  • Status: Accepted
  • Deciders: Abyss Team
  • Date: 2025-05-30

Context​

GitHub Copilot is increasingly being used by developers on the Abyss team to assist with code generation, commit messages, and PR creation. To ensure consistency and adherence to our established conventions (ADR-007 for Conventional Commits and ADR-011 for Branch Naming), we need a standardized approach for providing instructions to GitHub Copilot.

The VS Code GitHub Copilot extension offers several methods for customizing AI assistance, including repository-wide instruction files and user-specific settings. We need to decide on the most appropriate approach for our team to ensure that Copilot follows our established conventions while allowing for individual developer preferences where appropriate.

Decision​

We will implement GitHub Copilot instructions using a hybrid approach that combines repository-wide conventions with project-specific guidance:

  1. Repository-wide instructions (.github/copilot-instructions.md):

    • Maintain a central instruction file in the repository that defines core conventions for branch naming, commit messages, and PR formats
    • Include references to our ADRs and coding standards
    • Focus on team-wide conventions that should be consistent across all developers

  2. Project-specific instructions (.github/instructions/*.instructions.md):

    • Create separate instruction files for different project areas:
      • web.instructions.md: React component structure, styling patterns, and testing approaches
      • mobile.instructions.md: React Native component structure, platform-specific considerations
      • testing.instructions.md: Comprehensive testing guidelines including Playwright and Detox
    • Use front matter with the applyTo property to target specific file patterns
    • Provide specialized guidance tailored to each project's technology stack, patterns, and requirements
    • Include project-specific examples of component structure, testing approaches, and best practices
    • Ensure cross-references between related instruction files

  3. Specialized instruction settings:

    • Utilize GitHub Copilot's specialized instruction settings for specific tasks:
      • github.copilot.chat.commitMessageGeneration.instructions: For commit message generation (particularly important for our ADR-007 conventional commits)
      • github.copilot.chat.pullRequestDescriptionGeneration.instructions: For PR descriptions (following our PR template)
      • github.copilot.chat.reviewSelection.instructions: For code review assistance
    • Document recommended values for these settings that align with our conventions

  4. User-specific customizations:

    • Allow developers to supplement the repository instructions with their own preferences through VS Code settings
    • Document the process for customizing Copilot behavior in the developer onboarding materials

  5. Opt-in approach:

    • Make the use of repository-wide instructions opt-in by documenting the required VS Code settings:
      • github.copilot.chat.codeGeneration.useInstructionFiles: For the main instructions file
      • github.copilot.chat.codeGeneration.instructions: Set to the project-specific files
    • Do not enforce the use of Copilot instructions through automation

Alternatives Considered​

  1. Repository-wide instructions only:

    • Advantages: Ensures complete consistency across all developers; simpler to maintain a single file
    • Disadvantages: Cannot provide targeted guidance for different projects with different technology stacks (React vs React Native)

  2. User-specific instructions only:

    • Advantages: Provides maximum flexibility for individual developers
    • Disadvantages: May lead to inconsistency in code style, commit messages, and PR formats

  3. Add to .gitignore:

    • Advantages: Allows each developer to maintain their own version without affecting others
    • Disadvantages: Loses the benefit of shared conventions and requires each developer to create their own file

  4. Specialized instruction settings only:

    • Advantages: Provides fine-grained control over different types of Copilot assistance (code generation, testing, commit messages, PRs)
    • Disadvantages: More complex to set up and maintain; requires updating multiple settings when conventions change

  5. Multiple instruction files without targeting:

    • Advantages: Could organize instructions by topic or concern
    • Disadvantages: Would apply to all files regardless of project context; no way to provide project-specific guidance

Consequences​

Benefits​

  • Improved consistency in code, commit messages, and PRs generated with Copilot assistance
  • Project-specific guidance that respects the different technology stacks and patterns across our codebase
  • Reduced onboarding time for new developers by automating adherence to our conventions
  • Better alignment with our established ADRs for branch naming and commit messages
  • Flexibility for individual developers to customize their Copilot experience
  • More targeted and relevant assistance from GitHub Copilot based on which part of the codebase is being worked on

Costs​

  • Increased maintenance burden with multiple instruction files to keep updated
  • More complex setup for developers who need to enable multiple VS Code settings
  • Requires coordination between teams to ensure consistent conventions across project-specific instructions
  • Potential for confusion if repository-wide instructions conflict with project-specific or user-specific settings

Developer Configuration​

To enable GitHub Copilot instructions in VS Code, developers need to configure the following settings:

  1. Enable Repository-Wide Instructions:
"github.copilot.chat.codeGeneration.useInstructionFiles": true
  1. Enable Project-Specific Instructions:
"github.copilot.chat.codeGeneration.instructions": [
   { "file": ".github/instructions/web.instructions.md" },
   { "file": ".github/instructions/mobile.instructions.md" },
   { "file": ".github/instructions/testing.instructions.md" }
   ]
  1. Enable Specialized Instruction Settings:
"github.copilot.chat.commitMessageGeneration.instructions": [
  { "file": "/products/abyss-docs-web/docs/adrs/decisions/adr-007-conventional-commits.md" }
],
"github.copilot.chat.pullRequestDescriptionGeneration.instructions": [
  { "file": ".github/PULL_REQUEST_TEMPLATE.md" }
]

Developers can add these settings to their user settings.json or workspace settings.json file.

Future Considerations​

  • Monitor the effectiveness of the instructions and gather feedback from developers
  • Consider expanding instructions to include more detailed code style guidelines
  • Evaluate the need for language or framework-specific instruction files as the codebase grows
  • Develop a process for updating instruction files and settings as our conventions evolve
  • Consider automation to validate that Copilot-generated content follows our conventions
  • Stay updated with GitHub Copilot features and adjust our approach as new capabilities are released
  • Explore integration with our CI/CD pipeline to ensure Copilot-assisted code meets our quality standards
  • Investigate the possibility of creating a VS Code extension that automatically configures Copilot settings for Abyss developers

References​

Table of Contents