Agents Generic Baseline (.NET 10+)

AGENTS.md

AGENTS.md (Generic Template)

Context and instructions for AI coding agents working on this repository. Adapt this template by replacing placeholder names with your actual project values.

---

Project Overview

YourProject is a [brief description of what the application does]. It uses [primary framework] with [supporting libraries and tools].

Tech stack: [Runtime/SDK version], [Language version], [UI framework], [key libraries], [database], [logging], [test framework + assertion library].

---

Repository Structure

YourProject.slnx              # Solution file
Directory.Build.props          # Global MSBuild properties
Directory.Packages.props       # Central Package Management (all NuGet versions)

src/
  YourProject.Core/            # Domain layer — zero external dependencies
    Abstractions/              # Interface contracts
    Algorithms/                # Algorithm interfaces
    Configuration/             # Settings and constants
    Entities/                  # Domain entities and value objects

  YourProject.Application/     # Application layer — orchestration
    Services/                  # Orchestrators, coordinators
    Models/                    # DTOs, request/response models

  YourProject.Infrastructure/  # Infrastructure layer — implementations
    Algorithms/                # Algorithm implementations
    Persistence/               # Data access, caching
    FileSystem/                # File I/O operations
    Media/                     # External library wrappers

  YourProject.Web/             # Presentation layer — composition root
    Components/                # UI components
    wwwroot/                   # Static assets

tests/
  YourProject.Core.Tests/
  YourProject.Application.Tests/
  YourProject.Infrastructure.Tests/

---

Setup Commands

# Restore dependencies
dotnet restore

# Build the solution (warnings are errors)
dotnet build

# Run all tests
dotnet test

# Run the application
dotnet run --project src/YourProject.Web

---

Build and Test

• Solution file: Use .slnx (XML format) or .sln
• Target framework: Use the latest stable .NET version with latest C# LangVersion
• Warnings as errors: Enabled globally via Directory.Build.props (TreatWarningsAsErrors=true)
• Central Package Management: All NuGet versions centralized in Directory.Packages.props
• Test framework: xUnit v3 with NSubstitute (mocking) and AwesomeAssertions (assertions)
• Tests may suppress CA1707 (underscore naming) but must NOT suppress CS1591 — all public types/members require XML docs
• Run dotnet test to execute all unit tests across all test projects

---

Code Style and Conventions

C# Standards

• Follow Microsoft's C# Coding Conventions
• PascalCase: Classes, interfaces, methods, properties, constants
• camelCase with underscore: Private fields (_repository, _logger)
• camelCase: Parameters (entityId, cancellationToken)
• File-scoped namespaces, nullable reference types enabled, implicit usings enabled
• Always include XML documentation on all public types and members (CS1591 must never be suppressed)
• Namespaces and usings should only appear at the top of the file

Performance-First Philosophy

• No AutoMapper or similar mapping libraries — use manual mapping for performance
• No MediatR or similar mediator libraries
• No ORM (no Entity Framework) — use direct database access with manual mapping
• Use Span<T>, ReadOnlySpan<T>, Memory<T>, and stackalloc for buffer operations
• Use Channel<T> for producer-consumer patterns
• Use ConfigureAwait(false) in library/infrastructure code
• Always pass CancellationToken through async call chains

Architecture Principles (SOLID)

1. Single Responsibility — One class, one responsibility
2. Open/Closed — Open for extension, closed for modification
3. Liskov Substitution — Subtypes must be substitutable
4. Interface Segregation — Many specific interfaces over one general
5. Dependency Inversion — Depend on abstractions, not concretions

Interface vs Concrete Types

• Use IEnumerable<T> for parameters when you only need to iterate
• Use ICollection<T> for parameters when you need to add/remove
• Use IReadOnlyCollection<T> for return values (read-only)
• Use IReadOnlyList<T> for indexed read-only access
• Never expose List<T> or mutable collections from public APIs

Modern C# Features

• Records for DTOs and value types
• Init-only properties for immutable entities
• Pattern matching and switch expressions
• Null-coalescing assignment (??=)
• Source-generated LoggerMessage for high-performance logging

What NOT to Do

• Never suppress CS1591 — implement XML documentation instead
• Never suppress errors or warnings — fix the root cause
• Do not use VSCode Tasks
• Treat all warnings as errors (enforced by build configuration)
• Implement every TODO and FIXME encountered in the codebase

---

Testing Conventions

Structure

• Naming: MethodName_Scenario_ExpectedBehavior (underscores allowed via CA1707 suppression)
• Framework: xUnit v3 with [Fact] and [Theory]
• Mocking: NSubstitute (Substitute.For<T>())
• Assertions: AwesomeAssertions (NOT FluentAssertions) — e.g., result.Should().Be(expected)
• Arrange-Act-Assert pattern in every test

Coverage Goals

• Domain Layer (Core): 90%+
• Application Layer: 80%+
• Infrastructure Layer: 70%+ (focus on critical paths)

Example Test

/// <summary>
/// Unit tests for <see cref="SomeService"/> business logic.
/// </summary>
public sealed class SomeServiceTests
{
    /// <summary>Verifies the happy path returns expected results.</summary>
    [Fact]
    public async Task DoWork_ValidInput_ReturnsExpected()
    {
        // Arrange
        var repo = Substitute.For<IRepository>();
        var service = new SomeService(repo);

        // Act
        var result = await service.DoWorkAsync(CancellationToken.None);

        // Assert
        result.Should().NotBeNull();
    }
}

---

Git and Commit Conventions

Branching Strategy (Git Flow, use hyphens not slashes)

• main — Production-ready code
• develop — Integration branch
• feature-your-feature-name — Feature branches
• bugfix-issue-number-description — Bug fixes
• hotfix-critical-issue — Critical production fixes

Commit Messages (Conventional Commits)

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore

Example:

feat(module): Add feature description

- Implementation detail one
- Implementation detail two
- Implementation detail three

Closes #42

---

Architecture Rules

Layer Dependencies

Presentation → Application → Core ← Infrastructure

• Core has zero external NuGet dependencies (only abstractions packages allowed)
• Infrastructure implements all Core interfaces
• Application orchestrates domain logic
• Presentation is the composition root (DI registration)

Key Principles

• Depend on abstractions — Core defines interfaces, Infrastructure implements them
• Clean boundaries — No leaking of infrastructure types into domain
• Manual mapping — No AutoMapper; explicit conversion methods and constructors
• Direct data access — No ORM; use the database driver directly for maximum control
• Thread safety — Use immutable types, Channel<T>, and connection-per-operation patterns

---

Documentation Updates

When making changes, keep documentation in sync:

• Architecture changes: Update architecture documentation
• User-facing changes: Update user manual / README
• Development process changes: Update contributing guide

---

Security Considerations

• Never commit credentials, secrets, or API keys
• Use atomic writes (temp file + rename) for file persistence to prevent corruption
• Validate all external inputs at system boundaries
• Use parameterized queries for all database operations

---

Important Reminders for Agents

1. Always prefer the latest stable NuGet package versions — check for updates before starting work
2. Use AwesomeAssertions (NOT FluentAssertions) for test assertions
3. Every public type and member needs XML documentation comments
4. Build must succeed with 0 warnings and 0 errors before considering work complete
5. Run dotnet test after every change to verify no regressions
6. Do not use AutoMapper, MediatR, or Entity Framework
7. Performance is the top priority — when in doubt, choose the faster approach
8. Implement every TODO and FIXME encountered rather than leaving them
9. Namespaces and usings go at the top of the file only
10. Use file-scoped namespaces everywhere