Large software repositories create challenges that are difficult to manage through traditional code reviews alone. A single pull request may modify API controllers, database access layers, authentication services, background workers, shared libraries, and automated tests.
Each part of the application may follow different coding conventions and architectural rules. A change that looks correct in isolation can still introduce problems when it conflicts with the way another part of the system works.
GitHub Copilot code review can help developers identify potential issues in pull requests, but its usefulness depends on the context it receives. Without project-specific guidance, AI-generated reviews may suggest changes that do not match the repository's architecture, overlook important business rules, or produce feedback that developers cannot easily apply.
GitHub provides customization options that allow teams to guide Copilot using repository instructions, path-specific instructions, and additional architectural context.
For large repositories, the goal should not be to make Copilot review every possible detail. Instead, teams should help it understand the project's structure, identify important review criteria, and focus on issues that matter.
This article explains how GitHub Copilot code review works, how to customize it for large codebases, how to organize review instructions, and how to reduce irrelevant feedback while maintaining useful security and quality checks.
Why Large Repositories Need Customized Code Reviews
A small application may have a relatively simple structure:
MyApplication/
Controllers/
Models/
Services/
Tests/
A large enterprise repository may look very different:
EnterprisePlatform/
src/
Api/
Controllers/
Middleware/
Authentication/
Application/
Services/
Commands/
Queries/
Domain/
Entities/
Interfaces/
Rules/
Infrastructure/
Database/
Repositories/
Messaging/
Shared/
Extensions/
Utilities/
tests/
UnitTests/
IntegrationTests/
PerformanceTests/
deployment/
docker/
kubernetes/
pipelines/
Different directories have different responsibilities.
For example:
- API controllers should handle HTTP requests and responses.
- Application services should coordinate business operations.
- Domain entities should contain domain rules.
- Infrastructure components should manage external systems.
- Integration tests should verify interactions between components.
A generic review instruction such as "follow clean code principles" does not explain these responsibilities.
Without repository context, Copilot may recommend moving code into another layer, changing an established pattern, or introducing unnecessary abstractions.
Common problems with generic AI reviews
Teams working with large repositories may encounter several types of review noise.
| Problem | Example | Why it matters |
|---|
| Architectural misunderstanding | Suggesting database queries inside controllers | Conflicts with application architecture |
| Incorrect coding conventions | Recommending a different naming style | Creates inconsistent code |
| Missing business context | Treating a special validation rule as unnecessary | Can introduce functional defects |
| Irrelevant suggestions | Recommending changes unrelated to the pull request | Increases review effort |
| Duplicate feedback | Reporting the same issue in multiple comments | Makes reviews harder to manage |
| Missing security context | Overlooking authorization requirements | Can introduce security weaknesses |
Custom instructions help provide the missing project context so that reviews are more aligned with the team's actual development practices.
Understanding GitHub Copilot Code Review Customization
GitHub supports several customization mechanisms for Copilot code review.
The most useful options for repository-level reviews include:
- Repository-wide custom instructions.
- Path-specific custom instructions.
- Agent instructions and repository context.
- Organization-level custom instructions.
- Content exclusions and review configuration.
Each mechanism serves a different purpose.
| Customization | Main purpose | Best use |
|---|
| Repository-wide instructions | Define general project expectations | Architecture, coding standards, review priorities |
| Path-specific instructions | Define rules for particular files or directories | API, database, frontend, and test-specific rules |
| Agent instructions | Provide additional project context where supported | Repository architecture and intentional design decisions |
| Organization instructions | Apply shared engineering standards | Security, compliance, and organization-wide conventions |
| Content exclusions | Restrict which repository content Copilot can use | Sensitive or irrelevant files |
For most large repositories, start with repository-wide instructions and introduce path-specific instructions when different areas need different review criteria.
Creating Repository-Wide Instructions
GitHub Copilot supports repository custom instructions through a file named:
.github/copilot-instructions.md
This file provides general guidance about the repository.
It can describe:
- The purpose of the application.
- The primary programming languages and frameworks.
- Architectural conventions.
- Coding standards.
- Security expectations.
- Testing requirements.
- Important implementation constraints.
Create the .github directory if it does not already exist, then add the instruction file.
For example:
EnterprisePlatform/
.github/
copilot-instructions.md
src/
Api/
Application/
Domain/
Infrastructure/
tests/
A useful instruction file should provide specific guidance rather than generic statements.
Example repository-wide instructions
Consider an ASP.NET Core application that follows a layered architecture.
The following example demonstrates how to describe its development conventions:
# Repository Guidelines
## Project Overview
This repository contains an ASP.NET Core application
that follows a layered architecture.
The main application layers are:
- API: Handles HTTP requests and responses.
- Application: Coordinates business operations.
- Domain: Contains business rules and entities.
- Infrastructure: Handles database and external services.
## Architecture
- Keep business logic outside API controllers.
- Use application services for business operations.
- Keep domain rules inside the Domain layer.
- Use repository abstractions where established by the project.
- Avoid introducing unnecessary dependencies between layers.
## C# Guidelines
- Use asynchronous methods for I/O operations.
- Accept CancellationToken in asynchronous service methods
when cancellation is relevant.
- Prefer dependency injection over direct service creation.
- Use nullable reference types consistently.
- Avoid unnecessary allocations in frequently executed paths.
## Database Guidelines
- Use parameterized database queries.
- Avoid loading unnecessary records.
- Review transaction boundaries for multi-step operations.
- Consider indexes when introducing frequently executed queries.
## API Guidelines
- Follow existing response conventions.
- Validate incoming requests.
- Apply authorization where required.
- Avoid exposing internal exception details.
## Testing Guidelines
- Add unit tests for important business rules.
- Add integration tests for database-dependent behavior.
- Cover failure scenarios and boundary conditions.
- Do not remove existing tests to make a change pass.
## Code Review Priorities
Focus on:
- Functional correctness.
- Security vulnerabilities.
- Data integrity.
- Performance regressions.
- Missing error handling.
- Breaking changes to existing API contracts.
Avoid reporting purely stylistic preferences
when the existing implementation follows project conventions.
This instruction file provides Copilot with a general understanding of the repository.
However, avoid turning it into a complete architecture document. The most effective instructions focus on decisions that repeatedly matter during code reviews.
Using Path-Specific Instructions for Different Modules
A large repository rarely follows identical implementation rules in every directory.
For example, database access code may require strict transaction and query-performance checks, while API controllers may require authorization and response-contract validation.
GitHub supports path-specific instructions through files stored under:
.github/instructions/
These files use the .instructions.md extension and include an applyTo field in YAML front matter.
A possible structure is:
.github/
copilot-instructions.md
instructions/
api.instructions.md
database.instructions.md
domain.instructions.md
tests.instructions.md
frontend.instructions.md
Each instruction file can target specific paths.
API-specific review instructions
Create:
.github/instructions/api.instructions.md
Add:
---
applyTo: "src/Api/**/*.cs"
---
# API Review Guidelines
When reviewing API controllers and endpoints:
- Verify that authentication and authorization
requirements are correctly applied.
- Validate request data before processing.
- Avoid placing business logic directly in controllers.
- Preserve existing API response contracts.
- Review HTTP status codes for consistency.
- Avoid exposing database or internal exception details.
- Consider backward compatibility when changing
request and response models.
These instructions apply to matching API source files.
Database-specific review instructions
Create:
.github/instructions/database.instructions.md
Add:
---
applyTo: "src/Infrastructure/Database/**/*.cs"
---
# Database Review Guidelines
When reviewing database-related code:
- Check whether queries are parameterized.
- Review transaction boundaries.
- Avoid unnecessary full-table reads.
- Identify possible N+1 query patterns.
- Verify cancellation support for long-running
asynchronous database operations.
- Review connection and transaction disposal.
- Consider query plans for performance-sensitive
database operations.
- Check whether schema changes are backward compatible.
This gives Copilot more relevant guidance when reviewing database changes.
Test-specific instructions
Create:
.github/instructions/tests.instructions.md
Add:
---
applyTo: "tests/**/*.cs"
---
# Test Review Guidelines
When reviewing test code:
- Verify that tests cover the intended behavior.
- Include boundary conditions.
- Include failure scenarios.
- Avoid tests that depend on execution order.
- Avoid unnecessary shared mutable test state.
- Use descriptive test names.
- Verify that asynchronous operations are awaited.
- Do not rely on arbitrary delays for synchronization.
This approach allows each part of the repository to have its own review expectations without placing every rule inside one large instruction file.
Providing Architectural Context for Copilot
Instructions explain what Copilot should consider, but architectural context explains how the repository is organized and why certain implementation choices exist.
For large applications, this distinction is important.
Consider a repository that uses Dapper instead of Entity Framework Core for database access.
Without context, Copilot may suggest introducing Entity Framework Core because it recognizes that pattern from other .NET projects.
That recommendation may be inappropriate if the application deliberately uses Dapper for its database operations.
You can provide additional context through a root-level AGENTS.md file where supported by the code review environment.
For example:
# Repository Architecture Context
This repository uses ASP.NET Core with a layered architecture.
## Database Access
- Dapper is used for database access.
- SQL queries are maintained in the Infrastructure layer.
- Database operations should use existing connection
and transaction management patterns.
- Do not introduce Entity Framework Core without
an explicit architectural decision.
## Business Logic
- Business rules belong in the Domain or Application layer.
- API controllers should remain thin.
- Shared business behavior should not be duplicated
across multiple services.
## Authentication
- Authentication is handled through the existing
token validation middleware.
- Authorization policies are centrally configured.
- Do not bypass authorization checks for convenience.
## Important Design Decisions
- Existing public API contracts must remain compatible.
- Database changes must consider existing production data.
- Background jobs should support cancellation
and appropriate failure handling.
This example gives Copilot information about existing technical decisions.
Do not assume that every Copilot feature consumes every instruction-file type. GitHub documents different levels of support for repository-wide instructions, path-specific instructions, and agent instruction files.
For Copilot code review, verify the supported file types and configuration for the environment being used.
Customizing Code Review for Different Pull Request Types
Not every pull request needs the same review priorities.
A database migration, security update, API change, and frontend styling change have different risks.
Custom instructions can help establish the criteria that matter for different parts of the repository.
Consider the following examples:
| Pull request type | Important review areas |
|---|
| API changes | Authentication, authorization, validation, compatibility |
| Database changes | Transactions, query performance, data integrity |
| Authentication changes | Token validation, access control, session handling |
| Background jobs | Retries, cancellation, idempotency, failure handling |
| Frontend changes | State management, accessibility, error handling |
| Infrastructure changes | Permissions, secrets, deployment safety |
| Test changes | Coverage, isolation, deterministic execution |
A repository-wide instruction file can define general priorities, while path-specific files can provide additional rules for matching files.
This is particularly useful when a single pull request modifies several modules.
For example, a pull request that changes an API endpoint, a database query, and a test should be reviewed against the relevant criteria for each area.
Enabling Custom Instructions for Copilot Code Review
Creating instruction files is not the only requirement. You should also verify that Copilot code review is configured to use them.
On GitHub.com:
- Open the repository.
- Select Settings.
- Under Code, planning, and automation, select Copilot.
- Open Code review.
- Locate the option for using custom instructions when reviewing pull requests.
- Ensure that the setting is enabled.
GitHub enables custom instructions for Copilot code review by default, but repository administrators can disable or re-enable the feature.
An important implementation detail is that Copilot code review reads the applicable custom instructions from the pull request's head branch.
For example, when a feature branch is reviewed before merging into main, Copilot uses the instruction files present in that feature branch.
This allows teams to test instruction changes in a pull request before merging them into the default branch.
Reducing Irrelevant Feedback in Large Code Reviews
Adding more instructions does not automatically improve review quality.
A very large instruction file containing dozens of generic rules can make it difficult to identify the most important review criteria.
The objective should be to provide precise, relevant guidance.
Focus on actionable findings
Ask Copilot to prioritize issues that can affect the application.
For example, instructions can emphasize:
- Incorrect business logic.
- Security vulnerabilities.
- Data corruption risks.
- Missing authorization.
- Breaking API changes.
- Resource leaks.
- Performance problems with meaningful impact.
- Missing error handling.
Avoid encouraging reviews that report every possible naming or formatting preference.
Code formatting and naming conventions are often better handled by formatters, analyzers, and automated linting tools.
Explain intentional patterns
Large repositories often contain implementation patterns that may look unusual to an external reviewer.
For example:
- A service may intentionally use a specific transaction strategy.
- A database query may be optimized for a known workload.
- A legacy API response may need to remain unchanged for compatibility.
- A background job may use a particular retry mechanism.
Document these decisions when they are important to review accuracy.
This helps prevent Copilot from repeatedly suggesting changes that conflict with established design choices.
Avoid contradictory instructions
Suppose repository-wide instructions say:
Use asynchronous methods for I/O operations.
But a path-specific instruction says:
Avoid asynchronous methods in this module.
Without a clear reason, these instructions create ambiguity.
When different modules genuinely require different approaches, explain why the exception exists and keep the scope specific.
GitHub's instruction guidance recommends avoiding conflicting instruction sets because all relevant instructions may be provided to Copilot.
Use automated tools for deterministic checks
Copilot code review should complement existing development tools rather than replace them.
Use automated tools for checks that have clear, repeatable rules:
| Requirement | Recommended tool |
|---|
| Code formatting | dotnet format |
| Static code analysis | Roslyn analyzers |
| Dependency vulnerabilities | Dependabot |
| Secret detection | GitHub secret scanning |
| Unit testing | Test frameworks |
| Build validation | GitHub Actions |
| Container image scanning | Container security scanners |
| AI-assisted review | GitHub Copilot code review |
This separation allows Copilot to focus on contextual reasoning while automated tools handle deterministic validation.
Managing Content Exclusions for Large Repositories
Some repositories contain files that should not be included in Copilot's review context.
Examples may include:
- Generated source files.
- Large binary assets.
- Vendor directories.
- Sensitive configuration files.
- Build outputs.
- Files that are irrelevant to the review.
GitHub supports Copilot content exclusions at repository, organization, and enterprise levels, depending on the applicable configuration.
Copilot code review respects supported content exclusion settings.
For example, a repository may have generated files under:
src/
Generated/
Api/
Services/
vendor/
build/
If generated or vendor files should not be used as Copilot context, configure appropriate path-based exclusions through the repository's Copilot settings.
However, content exclusion should be applied carefully.
Do not exclude security-sensitive source code merely because it is difficult to review. Excluding a file means Copilot cannot use that content as context, which may reduce its ability to identify related problems.
Also distinguish content exclusion from code-review scope: excluding context does not automatically mean the corresponding code is removed from every other security or CI check.
Building a Review Workflow for Large Repositories
A consistent workflow helps teams use Copilot without making it another source of review noise.
A practical process can look like this:
Developer creates pull request
|
v
GitHub Actions runs automated checks
|
v
Copilot reviews changed code
|
v
Repository instructions provide context
|
v
Path-specific instructions guide module review
|
v
Developer evaluates review comments
|
v
Valid findings are fixed
|
v
Human reviewer performs final review
|
v
Pull request is approved and merged
For large pull requests, consider requesting another review after substantial changes.
For example, a developer may address Copilot's initial feedback and then modify several files across service boundaries. A new review can help identify issues introduced by those additional changes.
However, repeated reviews of unchanged code can create unnecessary noise and consume review resources.
Teams should define when a new review is useful, such as after significant changes to authentication, data access, or shared application components.
Measuring Whether Customization Improves Review Quality
After introducing custom instructions, evaluate whether the reviews are actually improving.
Do not measure success only by the number of comments generated.
More comments do not necessarily mean better reviews.
Instead, track indicators such as:
| Metric | What it tells you |
|---|
| Actionable finding rate | How many review comments lead to meaningful changes |
| False-positive rate | How often comments identify issues that are not actual problems |
| Duplicate finding rate | Whether the same issue is reported repeatedly |
| Missed defect rate | Whether important problems are still found later |
| Review turnaround time | Whether reviews help or delay pull request completion |
| Developer feedback | Whether the suggestions are relevant and understandable |
For example, if Copilot repeatedly suggests changing an established repository pattern, improve the architectural instructions.
If reviews overlook database performance concerns, add specific database review guidance.
Treat customization as an iterative engineering process rather than a one-time configuration task.
Common Mistakes to Avoid
| Mistake | Why it causes problems | Better approach |
|---|
| Using only generic instructions | Copilot lacks important project context | Describe architecture and development conventions |
| Creating one enormous instruction file | Module-specific rules become difficult to maintain | Use path-specific instructions |
| Writing vague review requirements | Feedback may be difficult to apply | Describe concrete risks and expected behavior |
| Providing conflicting instructions | Copilot receives inconsistent guidance | Keep rules consistent and explain exceptions |
| Treating AI comments as mandatory fixes | Some suggestions may be incorrect or irrelevant | Require developer validation |
| Ignoring content exclusions | Copilot may receive unnecessary or inappropriate context | Review exclusions deliberately |
| Replacing automated checks with AI review | Deterministic checks may be missed | Keep analyzers, tests, and security tools |
| Never updating instructions | Guidance becomes outdated as architecture changes | Review instructions during architectural changes |
Best Practices for Large Repository Teams
A sustainable Copilot code review strategy should include the following practices:
- Maintain a concise repository-wide instruction file.
- Use path-specific instructions for modules with different responsibilities.
- Document architectural decisions that affect code review.
- Prioritize security, correctness, performance, and compatibility.
- Avoid instructions that duplicate existing formatting rules.
- Keep custom instructions under version control.
- Review instruction changes through normal pull request processes.
- Enable custom instructions for Copilot code review.
- Configure content exclusions carefully.
- Evaluate false positives and actionable findings.
- Request re-reviews after substantial changes.
- Keep human review and automated testing as essential parts of the process.
For large organizations, standardize shared review expectations while allowing individual repositories to define their own architectural rules.
Conclusion
GitHub Copilot code review becomes more useful when it understands the repository it is reviewing.
Large codebases contain different modules, architectural boundaries, coding conventions, and business rules. Generic instructions cannot adequately describe all these requirements.
Repository-wide instructions provide the foundation, while path-specific instructions help Copilot apply relevant guidance to individual modules. Additional architectural context, organization policies, and content exclusions can further improve how reviews are tailored.
However, customization should remain focused. Adding more instructions does not guarantee better results. The most useful guidance explains how the application works, which risks matter, and which implementation patterns should be preserved.
Treat Copilot as an additional reviewer that supports developers rather than replacing human judgment, automated testing, or static analysis. With clear instructions and regular evaluation, teams can make AI-assisted code reviews more relevant, consistent, and practical across large repositories.
Join the conversation! Your thoughts help the community grow.