Default .NET/C# Project AI Directives

copilot-instructions.md

.NET/C# AI Coding Guidelines

Purpose: Comprehensive, non-project-specific guide for AI-assisted .NET development.

---

🎯 CRITICAL RULES (Always Follow)

1. Test-Driven Development: Interface → Test → Implementation
2. LINE BREAKS AFTER CLOSING BRACES - AI models frequently break this rule!
3. Partial classes for files >250 lines using ClassName._.cs naming
4. Operators at beginning of lines for readability

---

🧠 Core Architecture

Design Principles

• Testable code: Clean input/output, interface-driven design
• Modular logic: Small, composable methods and classes
• Immutable & stateless: Favor functional, declarative flows
• Dependency injection: Use interfaces for all swappable behaviors

TDD Workflow

1. Interface First: Define what (not how), ensure mockable
2. Test Second: Realistic inputs, edge cases, validate behavior
3. Implementation Last: Focused methods, clarity over cleverness

---

✍️ C# Language & Formatting

Modern C# Features (Preferred)

• record and readonly record struct for data
• Collection expressions, field keyword
• Span<T>, Memory<T>, ReadOnlySpan<T>, ReadOnlyMemory<T>
• ReadOnlySpan<char> over strings, StringSegment for allocations
• Primary constructors when appropriate

Code Formatting (Critical)

⚠️ LINE BREAKS AFTER CLOSING BRACES (AI Models Often Break This!)

AI models frequently edit code and accidentally remove line breaks. ALWAYS ensure proper spacing:

public void MyMethod()
{
    // logic here
} // <- CRITICAL: Line break required here!

public void NextMethod() // <- This line must have space above
{
    // more logic
}

public class MyClass
{
    // class content
} // <- CRITICAL: Line break required here!

public class NextClass // <- This line must have space above  
{
    // class content
}

Common AI Mistakes to Avoid:

// ❌ WRONG - No line break after brace
public void Method1() { }
public void Method2() { }

// ✅ CORRECT - Line break after brace
public void Method1() { }

public void Method2() { }

Operator Placement:

return condition
    && FirstCheck()
    || SecondCheck();

Standards

• Names: Expressive, no abbreviations, PascalCase for types/files
• Documentation: XML docs (///) for public APIs
• Async: Never async void except event handlers
• State: Avoid static state unless required

---

📐 Partial Classes (High Priority)

Critical for AI Development: Large files are harder for AI models to understand and edit safely. AI often corrupts large files when making changes.

When to Use Partial Classes

• Files >250 lines - Split immediately when approaching this limit
• Multiple concerns - Different logical responsibilities in same class
• AI regeneration safety - Smaller files = less corruption risk
• Better comprehension - AI can focus on specific functionality

Why This Matters for AI

• Regeneration Safety: AI can recreate small files without breaking existing code
• Focused Changes: AI makes targeted edits instead of large, risky modifications
• Reduced Errors: Smaller context means fewer mistakes
• Easier Reviews: Humans can validate AI changes more easily

Naming Convention

• Primary file: ClassName._.cs
  • Contains: Constructor, finalizer, disposal, XML documentation, core structure
  • Underscore makes it sort first in file explorers
• Feature files: ClassName.FeatureName.cs
  • Examples: Calculator.Operations.cs, Parser.Validation.cs, Service.Cache.cs

Implementation Strategy

• Split by logical concern, not arbitrary line counts
• One major feature per file when possible
• Prefer single-method-per-file over large monolithic classes
• Use in test projects with folders for better organization
• When in doubt: Split it - easier to merge than to untangle corruption

---

🧪 Testing

Requirements

• Coverage: All logic unit tested, deterministic & reproducible
• Tools: Prefer NSubstitute and avoid Moq, use Verify for snapshots
• Organization: Folders + partial classes in test projects
• Approach: Test-first encouraged, realistic inputs + edge cases

Snapshot Testing

• Use Verify for XML, SVG, JSON validation
• Snapshot tests for rendered output encouraged

---

🤖 AI Behavior

✅ Do

• Reuse existing interfaces (don't redefine)
• Write tests alongside code
• Ask for confirmation when uncertain
• Add TODO comments for stubs/placeholders
• Read change-logs before making changes

❌ Don't

• Auto-generate boilerplate/scaffolding
• Modify .editorconfig, .github/, directive files
• Make speculative refactors

---

📁 Project Organization

Structure

• Logical namespaces/folders, meaningful names
• Separate test projects, related functionality together
• Dependency injection for swappable behaviors
• Interfaces for external dependencies

Configuration

• Follow .editorconfig rules, modern project formats
• Up-to-date packages, nullable reference types
• Clean builds (no warnings), appropriate target frameworks

---

This guide optimizes AI-assisted .NET/C# development for quality, consistency, and maintainability. All generated code should reflect experienced developer standards in modern, test-driven, interface-oriented environments.