Bonus: Copilot Instructions

What is .github/copilot-instructions.md?

The `.github/copilot-instructions.md` file is a special configuration file that allows you to provide custom instructions to GitHub Copilot when it works in your repository. Instead of Copilot relying solely on context from your code, you can explicitly guide it on how to approach tasks, what standards to follow, and what tools to use.

Think of it as a project-wide prompt or rulebook that Copilot reads when working on your codebase. Every developer using Copilot in your repository benefits from these instructions.

Why Use Copilot Instructions?

Consistency and control. Without explicit instructions, Copilot might:

• Generate code that doesn't match your team's style guide
• Suggest design patterns your team doesn't use
• Forget about important security or compliance requirements
• Miss project-specific best practices
• Suggest outdated dependencies or APIs

With `.github/copilot-instructions.md`, you ensure Copilot understands your project's context, values, and constraints from the start.

Setting Up Copilot Instructions

Step 1: Create the File

In your repository root, create a `.github` directory (if it doesn't exist) and add a `copilot-instructions.md` file:

.github/
└── copilot-instructions.md

Step 2: Write Your Instructions

The file uses a simple markdown format with instruction blocks. Here's a basic template:

# Copilot Instructions for ByteStrike Project

## Architecture and Design

- Use async/await patterns for all asynchronous operations
- Follow MVC architecture for web components
- Utilize dependency injection for testability
- Implement single responsibility principle in all classes

## Code Style

- Follow PEP 257 for Python docstrings
- Use TypeScript for all JavaScript projects (no plain JS)
- Use meaningful variable names (no single letters except loop counters)
- Maximum line length: 100 characters

## Security Requirements

- Never hardcode secrets or credentials
- Validate all user input
- Use prepared statements for database queries
- Implement proper error handling without exposing sensitive details

## Dependencies and Frameworks

- Use React 18+ for UI components
- Use fastapi for Python web services
- Use Jest for JavaScript testing
- Keep dependencies up to date

Step 3: Commit and Push

Commit the file to your repository. Copilot will automatically pick it up for future interactions:

git add .github/copilot-instructions.md
git commit -m "Add Copilot instructions for project governance"
git push

What to Include in Your Instructions

1. Architecture and Design Principles

Explain the architectural patterns your project uses:

## Architecture

- Services should be stateless and horizontally scalable
- Use event-driven architecture for asynchronous processing
- Implement the repository pattern for data access
- All APIs should follow REST conventions

2. Code Style and Conventions

Specify naming conventions, formatting, and style standards:

## Code Style

- Use snake_case for Python variables and functions
- Use camelCase for JavaScript variables and methods
- Class names: PascalCase
- Constants: UPPER_SNAKE_CASE
- Private methods/properties: _leadingUnderscore

3. Security and Compliance

Define non-negotiable security requirements:

## Security Guardrails

- Always use HTTPS for external API calls
- Implement rate limiting on all public endpoints
- Use bcrypt for password hashing (minimum cost factor: 12)
- Validate input length and type before processing
- Log security events without exposing sensitive data

4. Testing Requirements

Set expectations for test coverage and testing approach:

## Testing Standards

- Minimum 80% code coverage required
- All public methods must have unit tests
- Use mocking for external service calls
- Integration tests required for API endpoints
- Test both happy path and error scenarios

5. Technology Stack

List preferred tools, versions, and when to use alternatives:

## Technology Choices

- Python 3.11+ for backend services
- PostgreSQL for relational data
- Redis for caching and sessions
- Docker for containerization
- Kubernetes for orchestration

6. Project-Specific Rules

Include rules unique to your project:

## ByteStrike-Specific Rules

- All secret extraction must use regex patterns with {* *} markers
- Mission reports must be ISO 8601 timestamped
- Agent codenames must be validated against approved list
- Audit logs must capture all access attempts
- Classified data must never be logged to standard output

7. External Tool Integration

Reference external resources and tools Copilot should know about:

## Tools and Integration

- Use Azure Best Practices when implementing cloud features
- Reference @microsoft/TypeScript-eslint for linting
- Use GitHub Actions for CI/CD pipelines
- Integrate with Snyk for dependency scanning

Example: ByteStrike's Full Instructions

Here's a complete example for the ByteStrike decoder project:

# Copilot Instructions: ByteStrike Blueprint Decoder

## Project Context

ByteStrike is a mission-critical system for decoding encrypted blueprints. 
Security, accuracy, and auditability are paramount.

## Architecture

- Stateless service design (horizontal scalability)
- Async/await for all I/O operations
- Repository pattern for data access
- Dependency injection for testability
- Event-driven logging for audit trails

## Code Quality Standards

- All functions must have docstrings (PEP 257 for Python, JSDoc for JavaScript)
- Maximum cyclomatic complexity: 5
- No magic numbers (use named constants)
- Extract functions > 50 lines into separate units
- Use type hints (Python) or TypeScript

## Security Requirements (NON-NEGOTIABLE)

- Secrets never logged to standard output
- All inputs validated and sanitized
- Use regex with proper escaping for pattern matching
- Implement rate limiting (max 100 requests per minute)
- Audit log all blueprint access and extraction
- Use bcrypt for credential storage
- Validate file size before processing (max 10MB)
- Implement timeout handling (30 second max)

## Testing Standards

- Minimum 90% code coverage
- All edge cases tested (malformed input, large files, etc.)
- Security tests for injection attacks
- Performance tests for benchmark compliance
- Integration tests with real blueprint data

## Approved Technologies

- Python 3.11+ for backend
- PostgreSQL for audit logs
- Redis for caching
- Docker for containerization
- GitHub Actions for CI/CD

## ByteStrike-Specific Rules

- Blueprint markers are always {* and *}
- Secrets extracted are trimmed of whitespace
- All times are UTC ISO 8601 format
- Agent codenames must be alphanumeric + underscore only
- Declassification authority required for log export

Using Instructions with Copilot Chat and Agent Mode

Once you've set up `.github/copilot-instructions.md`, Copilot automatically applies these rules when:

• In Chat: Ask questions and Copilot answers based on your project's standards
• In Inline Completions: Copilot generates code that follows your style and conventions
• In Agent Mode: Copilot uses instructions to plan and execute multi-file changes
• In Code Review: Copilot evaluates code against your project's standards

You don't need to pass the instructions in every prompt. They're part of the repository context now.

Best Practices for Copilot Instructions

Be Specific

Vague instructions are ignored. Instead of "write good code," say "implement unit tests for all public methods with Jest, using AAA pattern (Arrange, Act, Assert)."

Keep It Focused

Include essential rules, not every coding tidbit. Focus on what makes your project unique and critical. Too many instructions dilute their effectiveness.

Prioritize Security and Compliance

Lead with non-negotiable requirements (security, compliance, audit trail). Mark them as "NON-NEGOTIABLE" so Copilot treats them as hard constraints.

Update Regularly

As your project evolves, update the instructions. When you adopt a new framework or change standards, document it here. Make it a team habit to suggest updates during code review.

Make It Discoverable

Reference the file in your README:

## Using GitHub Copilot

We've configured Copilot with project-specific instructions in `.github/copilot-instructions.md`. 
When using Copilot Chat or Agent Mode, these instructions will guide code generation to match our standards.

Test Your Instructions

After creating instructions, test them:

• Open Copilot Chat and ask: "What are the security requirements for this project?"
• Generate code inline and verify it matches your style
• Assign an Agent task and check that it follows the architecture rules

Common Pitfalls to Avoid

Too Rigid

Don't make instructions so strict that they prevent Copilot from being helpful. Allow flexibility where it makes sense.

Too Long

Keep instructions concise. Copilot processes context more effectively with focused, clear guidance.

Not Version Controlled

Always commit changes to instructions to version control. Track what guidelines evolve over time.

Forgetting About Team Buy-In

Socialization matters. Share the instructions with your team and get agreement before enforcement.

Summary

`.github/copilot-instructions.md` is a powerful tool for ensuring Copilot works within your project's constraints, standards, and best practices. By investing time in clear, specific instructions, you:

• Ensure code consistency across the team
• Embed security and compliance requirements
• Reduce code review friction
• Help new developers understand project norms
• Give Copilot the context it needs to be most helpful

For ByteStrike and The League, that means Copilot becomes not just a productivity tool, but a guardian of mission-critical standards.

Resources

• GitHub Copilot Custom Instructions Documentation
• GitHub Copilot Official Documentation
• Awesome Copilot Repository