DEV Community

sowri
sowri

Posted on

.NET Agent instructions

#architecture #dotnet #githubcopilot #productivity

Yes. For a professional .NET team using GitHub Copilot, I would start with a minimal but high-value set of files. The goal is:

  • Consistent code generation
  • Better architectural decisions
  • Faster onboarding
  • Reusable prompts
  • Less prompt engineering by developers

Recommended Structure 

.github/
│
├── copilot-instructions.md
│
├── instructions/
│   ├── architecture.instructions.md
│   ├── entity-framework.instructions.md
│   ├── testing.instructions.md
│   ├── api-design.instructions.md
│   ├── async.instructions.md
│   └── security.instructions.md
│
└── prompts/
    ├── code-review.prompt.md
    ├── performance-review.prompt.md
    ├── bug-investigation.prompt.md
    ├── documentation.prompt.md
    └── refactoring.prompt.md
Enter fullscreen mode Exit fullscreen mode

1. copilot-instructions.md

This should be loaded automatically for everything.

Project Copilot Instructions

You are a Senior .NET Solution Architect.

When generating code:

  • Use .NET 8 or later.
  • Follow Clean Architecture principles.
  • Follow SOLID principles.
  • Prefer dependency injection.
  • Use asynchronous programming for I/O operations.
  • Use nullable reference types.
  • Use constructor injection.
  • Use meaningful names.
  • Avoid code duplication.

API Standards:

  • Use RESTful conventions.
  • Return proper HTTP status codes.
  • Validate requests.
  • Use ProblemDetails for errors.

Data Access:

  • Use Entity Framework Core.
  • Avoid N+1 query problems.
  • Use AsNoTracking for read-only queries.
  • Use pagination for large datasets.

Testing:

  • Generate unit tests using xUnit.
  • Use FluentAssertions.
  • Use Moq for mocking dependencies.

Security:

  • Never hardcode secrets.
  • Follow OWASP best practices.
  • Validate all external inputs.

Documentation:

  • Generate XML documentation for public APIs.
  • Generate meaningful README content when requested.

Always explain architectural trade-offs when proposing solutions.

2. architecture.instructions.md

Architecture Instructions

Use Clean Architecture.

Layers:

  • API
  • Application
  • Domain
  • Infrastructure

Rules:

  • Domain must not depend on Infrastructure.
  • Application must not depend on Infrastructure.
  • Infrastructure implements Application interfaces.
  • API references Application only.

Patterns:

  • CQRS when complexity justifies it.
  • Repository pattern only when needed.
  • Use MediatR for command/query separation when requested.
  • Use Result pattern for business operations.

For new features generate:

  • Entity
  • DTO
  • Service
  • Interface
  • Validation
  • Unit Tests

Prefer maintainability over clever implementations.

3. entity-framework.instructions.md

Entity Framework Core Instructions

Use EF Core best practices.

Queries:

  • Use AsNoTracking for reads.
  • Use projections instead of loading full entities.
  • Avoid Include chains unless necessary.
  • Avoid N+1 queries.

Configuration:

  • Use IEntityTypeConfiguration.
  • Keep configurations separate from DbContext.

Migrations:

  • Use migrations for schema changes.
  • Do not use EnsureCreated.

Performance:

  • Paginate large result sets.
  • Use Select projections.
  • Avoid loading unnecessary columns.

Repositories:

  • Return DTOs when possible.
  • Use cancellation tokens.

Generated code should be production-ready and performant.

4. testing.instructions.md

Testing Instructions

Use:

  • xUnit
  • FluentAssertions
  • Moq

Follow Arrange Act Assert pattern.

Unit Tests:

  • Test happy path.
  • Test validation failures.
  • Test exception scenarios.
  • Test edge cases.

Naming:

MethodName_Scenario_ExpectedResult

Example:

CreateEmployee_ValidRequest_ReturnsEmployee

Do not test implementation details.

Mock external dependencies.

Generate maintainable and readable tests.

5. api-design.instructions.md

API Design Instructions

Follow REST principles.

Routes:

GET /api/employees
GET /api/employees/{id}
POST /api/employees
PUT /api/employees/{id}
DELETE /api/employees/{id}

Responses:

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

Use DTOs.

Never expose EF entities directly.

Support:

  • Pagination
  • Filtering
  • Sorting

Use ProblemDetails for errors.

Generate Swagger annotations when appropriate.

6. async.instructions.md

Async Programming Instructions

Use async/await for all I/O operations.

Rules:

  • Avoid .Result
  • Avoid .Wait()
  • Avoid async void
  • Pass CancellationToken

Prefer:

Task

over:

Task

Use ConfigureAwait(false) only when appropriate for libraries.

Avoid blocking calls.

Ensure generated code is scalable and non-blocking.

7. security.instructions.md

Security Instructions

Follow OWASP recommendations.

Rules:

  • Validate all inputs.
  • Encode outputs where required.
  • Never log secrets.
  • Never hardcode credentials.
  • Use parameterized queries.
  • Validate JWT tokens.
  • Use HTTPS.

Authentication:

  • JWT Bearer authentication.
  • Claims-based authorization.

Security Reviews:

  • Check injection risks.
  • Check authentication flaws.
  • Check authorization issues.
  • Check sensitive data exposure.

8. code-review.prompt.md

Review the provided code as a Senior .NET Architect.

Evaluate:

  1. Clean Code
  2. SOLID Principles
  3. Performance
  4. Security
  5. Maintainability
  6. Readability
  7. Testability

Provide:

  • Findings
  • Risks
  • Suggested Improvements
  • Refactored Example

9. performance-review.prompt.md

Analyze the provided code for performance issues.

Evaluate:

  • Database queries
  • Memory allocations
  • Async usage
  • EF Core performance
  • Caching opportunities
  • Scalability concerns

Provide:

  • Issue
  • Impact
  • Recommendation
  • Improved Code Example

10. bug-investigation.prompt.md

Act as a Senior Production Support Engineer.

Analyze the provided code, logs, stack traces, or error messages.

Provide:

  1. Root Cause
  2. Impact
  3. Reproduction Steps
  4. Fix
  5. Prevention Strategy
  6. Unit Tests to Add

Explain your reasoning.

11. documentation.prompt.md

Generate professional project documentation.

Include:

  • Overview
  • Architecture
  • Prerequisites
  • Setup Instructions
  • Configuration
  • API Endpoints
  • Testing
  • Deployment
  • Troubleshooting

Use markdown formatting.

12. refactoring.prompt.md

Refactor the provided code.

Goals:

  • Improve readability
  • Reduce complexity
  • Apply SOLID principles
  • Improve testability
  • Remove duplication
  • Improve maintainability

Provide:

  1. Problems Identified
  2. Refactored Code
  3. Explanation of Changes
  4. Benefits

This setup is what I'd use for a modern ASP.NET Core + EF Core + SQL Server + xUnit project. Most developers only need copilot-instructions.md daily; the instruction files get added as context when working in a specific area, and the prompt files become reusable templates for reviews, debugging, documentation, and refactoring.

Yes, the templates folder is optional, but for a team adopting Copilot, it's actually one of the highest ROI additions because it standardizes how developers ask Copilot to generate work.

I would absolutely add it.

Updated Structure

```text id="wlhdtj"
.github/
│
├── copilot-instructions.md
│
├── instructions/
│ ├── architecture.instructions.md
│ ├── entity-framework.instructions.md
│ ├── testing.instructions.md
│ ├── api-design.instructions.md
│ ├── async.instructions.md
│ └── security.instructions.md
│
├── prompts/
│ ├── code-review.prompt.md
│ ├── performance-review.prompt.md
│ ├── bug-investigation.prompt.md
│ ├── documentation.prompt.md
│ └── refactoring.prompt.md
│
└── templates/
├── feature-request.md
├── user-story.md
├── architecture-decision-record.md
├── api-endpoint-request.md
├── bug-report.md
├── test-scenario.md
└── spike-investigation.md




---

# 1. feature-request.md

Use when asking Copilot to build a complete feature.

# Feature Request

Feature Name:

Business Goal:

User Type:

Functional Requirements:

1.
2.
3.

Validation Rules:

Security Requirements:

Acceptance Criteria:

Non-Functional Requirements:

Expected Output:

Generate:

* Domain Model
* DTOs
* Interfaces
* Services
* API Endpoints
* Unit Tests
* Swagger Documentation

Example:



```text id="yecbzg"
Feature Name:
Employee Management

Business Goal:
Manage employee records

Requirements:
Create, update, delete, search employees
Enter fullscreen mode Exit fullscreen mode

2. user-story.md

Perfect for agile teams.

User Story

As a:

I want:

So that:

Acceptance Criteria:

  • [ ]
  • [ ]
  • [ ]

Technical Notes:

Dependencies:

Risks:

Generate implementation plan and code.

Example:

```text id="n7gj0j"
As a HR Manager

I want to search employees by department

So that I can manage staffing effectively




---

# 3. architecture-decision-record.md

Very useful for architects and senior developers.

# Architecture Decision Record

Title:

Status:

Context:

Decision:

Alternatives Considered:

Pros:

Cons:

Consequences:

Implementation Notes:

Generate architecture recommendations and implementation approach.

Example:



```text id="smjn1j"
Decision:
Use MediatR vs Service Layer
Enter fullscreen mode Exit fullscreen mode

Ask Copilot to evaluate.

4. api-endpoint-request.md

For API generation.

API Endpoint Request

Resource:

Operation:

Endpoint:

Request DTO:

Response DTO:

Validation Rules:

Authorization Requirements:

Error Scenarios:

Generate:

  • Controller
  • Service
  • DTOs
  • Validation
  • Unit Tests
  • Swagger Documentation

Example:

```text id="btt1rb"
Resource:
Employee

Operation:
Search

Endpoint:
/api/employees/search




---

# 5. bug-report.md

Great for production support.

# Bug Report

Title:

Environment:

Severity:

Expected Behavior:

Actual Behavior:

Steps To Reproduce:

Error Messages:

Logs:

Stack Trace:

Suspected Cause:

Analyze root cause and propose fixes.

Example:



```text id="g55l8q"
Title:
Employee API returns 500

Stack Trace:
...
Enter fullscreen mode Exit fullscreen mode

6. test-scenario.md

Helps QA and developers.

Test Scenario

Feature:

Scenario:

Preconditions:

Steps:

Expected Result:

Edge Cases:

Negative Cases:

Generate:

  • Unit Tests
  • Integration Tests
  • Test Data

Example:

```text id="6m0xov"
Feature:
Employee Creation

Scenario:
Create employee with valid data




---

# 7. spike-investigation.md

For technical research.

# Spike Investigation

Topic:

Problem Statement:

Current State:

Questions To Answer:

1.
2.
3.

Constraints:

Success Criteria:

Provide:

* Findings
* Alternatives
* Recommendation
* Risks
* Implementation Approach

Example:



```text id="v80awh"
Topic:
Redis Caching

Problem:
Slow employee search endpoint
Enter fullscreen mode Exit fullscreen mode

How Teams Actually Use These

Example 1: New Feature

Open:

```text id="x8xxlr"
templates/feature-request.md




Fill it out.

Paste into Copilot Chat.

Result:

* Better code
* Better architecture
* Better tests

---

## Example 2: Production Issue

Open:



```text id="tq4c92"
templates/bug-report.md
Enter fullscreen mode Exit fullscreen mode

Paste logs.

Ask Copilot.

Result:

  • Structured root cause analysis

Example 3: Sprint Story

Open:

```text id="ahjigw"
templates/user-story.md




Paste Jira story.

Ask:



```text id="x8a5qe"
Generate implementation plan.
Enter fullscreen mode Exit fullscreen mode

Result:

  • Tasks
  • DTOs
  • APIs
  • Tests

If I Were Building a Team Standard

I would tell developers:

Daily

```text id="3s4h3f"
copilot-instructions.md




---

### Domain Work



```text id="jyrw7h"
instructions/*
Enter fullscreen mode Exit fullscreen mode

Code Reviews

```text id="yq7hza"
prompts/*




---

### New Features / Stories / Bugs



```text id="f2m61m"
templates/*
Enter fullscreen mode Exit fullscreen mode

This combination gives you a complete Copilot operating system for a .NET development team, rather than just a collection of prompts. It also makes onboarding new developers much easier because they don't have to learn prompt engineering—they just fill in the templates and let Copilot do the heavy lifting.

Top comments (0)