Agent skill

dotnet-architecture

Guides implementation of Clean Architecture in .NET projects. Covers all layers: DTO, Domain (Models, Services, Enums), Infra.Interfaces (Repository, AppServices), Infra (Context, Repository, AppServices), and Application (DI/Startup). Use when creating entities, services, repositories, or restructuring architecture. Works with any project type (Web, Console, Mobile, Windows).

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/dotnet-architecture

SKILL.md

.NET Clean Architecture Guide

You are an expert assistant that helps developers implement Clean Architecture in .NET projects. You guide the user through ALL required layers. This guide is agnostic to the presentation layer — it works for Web API, Console, Mobile (MAUI), Windows (WPF/WinForms), Worker Services, etc.

Input

The user will describe what to create or modify: $ARGUMENTS

Before generating code:

  1. Read the solution structure — Identify all projects/layers
  2. Find an existing entity — Use it as the primary reference to match patterns exactly (naming, namespaces, mapping approach, DI style)
  3. Read the DbContext (if applicable) — Understand database provider, column naming conventions, and existing configurations
  4. Read the Startup/DI setup — Find the centralized DI class (usually Startup.cs)
  5. Identify the mapping strategy — AutoMapper profiles, manual mapping, or Mapster

Architecture Overview

Layer Structure & Dependencies

┌─────────────────────────────────────────────────────────────┐
│  Presentation (Console, API, Mobile, Windows, Worker, etc.) │
│  Depends on: Application                                    │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│  Application — DI/IoC, Startup, cross-cutting concerns      │
│  Depends on: everything needed to wire up the application   │
└──────────────────────────────┬──────────────────────────────┘
                               │
          ┌────────────────────┼────────────────────┐
          ▼                    ▼                    ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│      Domain      │ │      Infra       │ │       DTO        │
│ Models, Services │ │ Context, Repos,  │ │ Data contracts,  │
│ Enums, Rules     │ │ AppServices      │ │ IOptions configs │
│                  │ │                  │ │                  │
│ Depends on:      │ │ Depends on:      │ │ Depends on:      │
│ Infra.Interfaces │ │ Domain,          │ │ nothing          │
│ DTO              │ │ Infra.Interfaces │ │                  │
└──────────────────┘ └──────────────────┘ └──────────────────┘
          │                    │
          ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│  Infra.Interfaces — Repository & AppService contracts       │
│  Depends on: nothing (may depend on DTO only)               │
│  Uses generics to avoid coupling to Domain models           │
└─────────────────────────────────────────────────────────────┘

Layer Responsibilities

Layer Project Responsibility Dependencies
DTO {Project}.DTO Data Transfer Objects, public contracts, IOptions<T> configuration classes None
Infra.Interfaces {Project}.Infra.Interfaces Repository and AppService interfaces using generics (<TModel>) None (may depend on DTO)
Domain {Project}.Domain Models (rich entities), Enums, Services (business rules), Service interfaces Infra.Interfaces, DTO
Infra {Project}.Infra DbContext, Repository implementations, AppService implementations (SNS, Rabbit, GitHub, Email, etc.) Domain, Infra.Interfaces
Application {Project}.Application Centralized DI/IoC via Startup.cs, cross-cutting concerns All layers as needed
Presentation Varies UI/entry point — NOT covered by this skill Application

Key Rules

  • Domain NEVER depends on Infra — only on Infra.Interfaces (abstractions)
  • Infra.Interfaces has NO dependencies on Domain or Infra — uses generics for type parameters
  • DTO has ZERO dependencies — pure data contracts
  • Application is the composition root — it wires everything together in a Startup class
  • Domain Models are NOT immutable — they are rich entities with public setters and behavior methods
  • All services MUST have interfaces — Domain services define interfaces in Domain/Interfaces/
  • Model interfaces are exceptional — only create I{Entity}Model when there's a specific need

Step-by-Step Implementation

Step 1: DTO

Create data transfer objects in the {Project}.DTO project root.

csharp
namespace {Project}.DTO;

public class {Entity}Info
{
    public long Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; }
}

Guidelines:

  • Create separate DTOs if insert/update shapes differ: {Entity}InsertInfo (no Id), {Entity}UpdateInfo (with Id)
  • Use nullable types for optional fields (DateTime?, long?)
  • Configuration classes for IOptions<T> also live here (e.g., DatabaseSettings, OpenAISettings)
  • No dependencies on any other project
  • Match the naming convention of existing DTOs

Step 2: Infra.Interfaces — Repository

Create repository interfaces in {Project}.Infra.Interfaces/Repository/ using generics.

csharp
namespace {Project}.Infra.Interfaces.Repository;

public interface I{Entity}Repository<TModel> where TModel : class
{
    Task<TModel> GetByIdAsync(long id);
    Task<List<TModel>> ListAllAsync();
    Task<TModel> InsertAsync(TModel entity);
    Task<TModel> UpdateAsync(TModel entity);
    Task DeleteAsync(long id);
}

Guidelines:

  • Always use generics (<TModel>) — the interface must NOT reference Domain models directly
  • The generic constraint where TModel : class is sufficient
  • Keep interfaces focused — don't add methods that only one implementation needs
  • Add pagination signatures if the project uses them: Task<(List<TModel> Items, int TotalCount)>

Step 3: Infra.Interfaces — AppService (if applicable)

Create AppService interfaces in {Project}.Infra.Interfaces/AppServices/ for infrastructure services.

csharp
namespace {Project}.Infra.Interfaces.AppServices;

public interface I{External}AppService<TModel> where TModel : class
{
    Task<TModel> GetDataAsync(string identifier);
    Task SendAsync(TModel data);
}

Guidelines:

  • AppServices are for external infrastructure concerns: messaging (SNS, RabbitMQ), external APIs (GitHub, OpenAI), file storage (S3, Azure Blob), email, etc.
  • Use generics to keep the interface decoupled from Domain
  • If generics don't make sense for a specific service (e.g., IEmailAppService), it's acceptable to use primitive types or DTO types instead

Step 4: Domain Model

Create rich domain entities in {Project}.Domain/Models/.

csharp
namespace {Project}.Domain.Models;

public class {Entity}
{
    public long Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;

    // Business behavior methods
    public void UpdateName(string newName)
    {
        if (string.IsNullOrWhiteSpace(newName))
            throw new ArgumentException("Name cannot be empty.", nameof(newName));
        Name = newName;
    }
}

Guidelines:

  • Models are rich entities with public setters — NOT immutable
  • Business behavior methods belong on the model (validation, state transitions)
  • Model interfaces (I{Entity}) are exceptional — only create when there's a specific need (e.g., multiple implementations, testing boundaries)
  • Enums go in {Project}.Domain/Enums/
  • Domain models must NOT depend on infrastructure types (no EF attributes, no Pgvector Vector, etc.) — use primitive types (float[], string, byte[]) and let Infra handle conversion

Step 5: Domain Service Interface

Create service interfaces in {Project}.Domain/Interfaces/.

csharp
namespace {Project}.Domain.Interfaces;

public interface I{Entity}Service
{
    Task<{Entity}Info> GetByIdAsync(long id);
    Task<List<{Entity}Info>> ListAllAsync();
    Task<{Entity}Info> CreateAsync({Entity}Info dto);
    Task<{Entity}Info> UpdateAsync({Entity}Info dto);
    Task DeleteAsync(long id);
}

Guidelines:

  • All services MUST have interfaces
  • Services receive/return DTOs at their public API
  • Internally they work with Domain Models
  • Match the existing service interface patterns in the project

Step 6: Domain Service Implementation

Create service implementations in {Project}.Domain/Services/.

csharp
using {Project}.Domain.Interfaces;
using {Project}.Domain.Models;
using {Project}.DTO;
using {Project}.Infra.Interfaces.Repository;

namespace {Project}.Domain.Services;

public class {Entity}Service : I{Entity}Service
{
    private readonly I{Entity}Repository<{Entity}> _repository;

    public {Entity}Service(I{Entity}Repository<{Entity}> repository)
    {
        _repository = repository;
    }

    public async Task<{Entity}Info> GetByIdAsync(long id)
    {
        var entity = await _repository.GetByIdAsync(id);
        return MapToDto(entity);
    }

    public async Task<{Entity}Info> CreateAsync({Entity}Info dto)
    {
        var entity = MapToModel(dto);
        entity.CreatedAt = DateTime.UtcNow;
        var saved = await _repository.InsertAsync(entity);
        return MapToDto(saved);
    }

    // Manual mapping — or use AutoMapper/Mapster if project uses it
    private static {Entity}Info MapToDto({Entity} entity) => new()
    {
        Id = entity.Id,
        Name = entity.Name,
        CreatedAt = entity.CreatedAt
    };

    private static {Entity} MapToModel({Entity}Info dto) => new()
    {
        Id = dto.Id,
        Name = dto.Name
    };
}

Guidelines:

  • Services contain business rules that are not specific to a single domain entity
  • Entity-specific behavior belongs on the Model itself
  • Services depend on Infra.Interfaces (repository/AppService abstractions), never on Infra directly
  • Match the mapping strategy used by the project (manual, AutoMapper, Mapster)

Step 7: Infra — DbContext Configuration

Add DbSet and configure the entity in OnModelCreating.

csharp
// Add DbSet
public DbSet<{Entity}> {Entity}s { get; set; }

// Inside OnModelCreating:
modelBuilder.Entity<{Entity}>(entity =>
{
    entity.ToTable("{table_name}");
    entity.HasKey(e => e.Id);

    entity.Property(e => e.Id)
        .HasColumnName("id")
        .UseIdentityAlwaysColumn();

    entity.Property(e => e.Name)
        .HasColumnName("name")
        .HasMaxLength(240)
        .IsRequired();

    entity.Property(e => e.CreatedAt)
        .HasColumnName("created_at")
        .HasColumnType("timestamp with time zone")
        .HasDefaultValueSql("now()");
});

Conventions to detect and match:

  • Table naming: snake_case vs PascalCase vs plural vs singular
  • Column naming: snake_case (created_at) vs PascalCase (CreatedAt)
  • Primary key: auto-increment, identity, sequences, or GUID
  • Timestamps: timestamp with time zone (PostgreSQL) vs datetime2 (SQL Server)
  • FK behavior: DeleteBehavior.Cascade vs ClientSetNull vs Restrict
  • Use ValueConverter when Domain model types differ from database types (e.g., float[] → pgvector Vector)

Step 8: Infra — Repository Implementation

csharp
using {Project}.Domain.Models;
using {Project}.Infra.Context;
using {Project}.Infra.Interfaces.Repository;
using Microsoft.EntityFrameworkCore;

namespace {Project}.Infra.Repository;

public class {Entity}Repository : I{Entity}Repository<{Entity}>
{
    private readonly {DbContextType} _context;

    public {Entity}Repository({DbContextType} context)
    {
        _context = context;
    }

    public async Task<{Entity}> GetByIdAsync(long id)
    {
        return await _context.{Entity}s
            .AsNoTracking()
            .FirstOrDefaultAsync(e => e.Id == id)
            ?? throw new KeyNotFoundException($"{Entity} {id} not found.");
    }

    public async Task<List<{Entity}>> ListAllAsync()
    {
        return await _context.{Entity}s
            .AsNoTracking()
            .OrderBy(e => e.Name)
            .ToListAsync();
    }

    public async Task<{Entity}> InsertAsync({Entity} entity)
    {
        _context.{Entity}s.Add(entity);
        await _context.SaveChangesAsync();
        return entity;
    }

    public async Task<{Entity}> UpdateAsync({Entity} entity)
    {
        var existing = await _context.{Entity}s.FindAsync(entity.Id)
            ?? throw new KeyNotFoundException($"{Entity} {entity.Id} not found.");

        _context.Entry(existing).CurrentValues.SetValues(entity);
        await _context.SaveChangesAsync();
        return existing;
    }

    public async Task DeleteAsync(long id)
    {
        var entity = await _context.{Entity}s.FindAsync(id)
            ?? throw new KeyNotFoundException($"{Entity} {id} not found.");

        _context.{Entity}s.Remove(entity);
        await _context.SaveChangesAsync();
    }
}

Step 9: Infra — AppService Implementation (if applicable)

csharp
using {Project}.Domain.Models;
using {Project}.Infra.Interfaces.AppServices;

namespace {Project}.Infra.AppServices;

public class {External}AppService : I{External}AppService<{Model}>
{
    private readonly HttpClient _httpClient;

    public {External}AppService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    // Implementation that calls external service
}

Examples of AppServices:

  • GitHubAppService — calls GitHub API via Octokit
  • OpenAIAppService — calls OpenAI API for completions/embeddings
  • SnsAppService — publishes messages to AWS SNS
  • RabbitAppService — publishes/consumes RabbitMQ messages
  • EmailAppService — sends emails via SMTP/SendGrid
  • StorageAppService — uploads/downloads from S3/Azure Blob

Step 10: Migration (if applicable)

bash
dotnet ef migrations add Add{Entity}Table --project {InfraProject} --startup-project {StartupProject}
dotnet ef database update --project {InfraProject} --startup-project {StartupProject}

Step 11: DI Registration — Application/Startup.cs

All DI registration is centralized in the Startup class.

csharp
using {Project}.Domain.Interfaces;
using {Project}.Domain.Models;
using {Project}.Domain.Services;
using {Project}.Infra.Context;
using {Project}.Infra.Interfaces.Repository;
using {Project}.Infra.Repository;
using {Project}.Infra.AppServices;
using {Project}.Infra.Interfaces.AppServices;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;

namespace {Project}.Application;

public static class Startup
{
    public static IServiceCollection ConfigureServices(
        this IServiceCollection services,
        Action<{Settings}> configureSettings)
    {
        var settings = new {Settings}();
        configureSettings(settings);

        // IOptions configuration
        services.Configure<{SubSettings}>(opt => { /* ... */ });

        // DbContext
        services.AddDbContext<{DbContext}>(options =>
            options.UseNpgsql(settings.Database.ConnectionString));

        // Repositories
        services.AddScoped<I{Entity}Repository<{Entity}>, {Entity}Repository>();

        // AppServices
        services.AddHttpClient<I{External}AppService<{Model}>, {External}AppService>();

        // Domain Services
        services.AddScoped<I{Entity}Service, {Entity}Service>();

        return services;
    }
}

Guidelines:

  • One centralized Startup class — all registrations in one place
  • Match the lifetime used by the project: AddScoped (per-request), AddTransient (per-resolve), AddSingleton (app lifetime)
  • Use AddHttpClient<> for services that need HttpClient (OpenAI, GitHub, etc.)
  • AutoMapper: services.AddAutoMapper(typeof(Startup).Assembly) if used

Checklist

# Layer Action Description
1 DTO Create {Entity}Info.cs (and Insert/Update variants if needed)
2 Infra.Interfaces Create I{Entity}Repository<TModel> in Repository/
3 Infra.Interfaces Create I{External}AppService<TModel> in AppServices/ (if applicable)
4 Domain Create {Entity}.cs model in Models/
5 Domain Create I{Entity}Service.cs interface in Interfaces/
6 Domain Create {Entity}Service.cs implementation in Services/
7 Infra Modify DbContext — add DbSet and OnModelCreating configuration
8 Infra Create {Entity}Repository.cs in Repository/
9 Infra Create {External}AppService.cs in AppServices/ (if applicable)
10 Infra Run dotnet ef migrations add (if applicable)
11 Application Modify Startup.cs — register repositories, AppServices, services

Response Guidelines

  1. Read existing files first — Find an existing complete entity and use it as the reference for all layers
  2. Follow the order — DTO → Infra.Interfaces → Domain → Infra → Application
  3. Match all conventions exactly — naming, namespaces, folder structure, code style
  4. Run migrations after modifying DbContext
  5. Detect and match the database provider conventions (column naming, timestamps, key generation)
  6. Adapt mapping strategy — AutoMapper, manual mapping, or whatever the project uses
  7. Match DI patterns — registration style and service lifetimes
  8. Never touch the presentation layer — this skill is agnostic to UI/entry point
  9. Keep Infra.Interfaces decoupled — always use generics, never reference Domain models
  10. Domain models use primitive types — infrastructure-specific types (Vector, BsonDocument, etc.) are converted in Infra via ValueConverters or mapping

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results