Clean Architecture in .NET, Accelerated by Claude Code

The Enduring Power of Clean Architecture

Clean Architecture, a paradigm championed by Robert C. Martin, remains a cornerstone of robust software design. Its core tenet is the separation of concerns, creating layers that are independent of external frameworks and infrastructure. In a .NET context, this typically translates to:

• Entities: Core business objects, independent of any framework.
• Use Cases (Interactors): Application-specific business rules, orchestrating entities.
• Interface Adapters: Convert data between formats convenient for use cases and entities, and formats convenient for external agencies (e.g., Presenters, Gateways, Controllers).
• Frameworks & Drivers: The outermost layer, containing frameworks, databases, UIs, and external services.

The Dependency Rule is paramount: dependencies can only point inwards. This means your entities know nothing about your use cases, your use cases know nothing about your interface adapters, and so on.

Why Clean Architecture Still Matters

In today’s rapidly evolving tech landscape, the ability to:

• Testability: Isolate business logic for unit testing.
• Maintainability: Easier to understand, modify, and extend.
• Flexibility: Swap out external dependencies (e.g., database, UI framework) with minimal impact.
• Scalability: Well-defined boundaries facilitate parallel development and independent scaling of components.

These benefits are amplified when development speed is critical. This is where Claude Code enters the picture.

Claude Code: Your AI Co-Pilot for Clean Architecture in .NET

Claude Code is not just a code generator; it’s an intelligent assistant that can understand context, infer intent, and accelerate the repetitive, yet crucial, aspects of implementing architectural patterns. For experienced .NET developers, it means less time wrestling with boilerplate and more time focused on the unique business logic.

Accelerating Layer Creation and Dependency Injection

Setting up the foundational layers of a Clean Architecture project often involves creating numerous interfaces, DTOs (Data Transfer Objects), and implementing the Dependency Injection (DI) setup. Claude Code can significantly expedite this.

Scenario: You’re designing a domain for Order management. You need an IOrderRepository interface in the Application layer and its concrete implementation, SqlOrderRepository, in the Infrastructure layer.

Prompting Claude Code (Example):

“Generate C# code for a Clean Architecture .NET project. Project Structure:

• Domain: Entities, Interfaces (e.g., IEntity)
• Application: Use Cases, DTOs, Interfaces (e.g., IRepository)
• Infrastructure: Concrete implementations of interfaces (e.g., repositories), DbContext
• Presentation: Controllers, Views (ASP.NET Core)

Specific Task: Create an IOrderRepository interface in the Application layer and a SqlOrderRepository class in the Infrastructure layer that implements it. The SqlOrderRepository should have a constructor that accepts an AppDbContext (assume this DbContext exists in Infrastructure). Also, provide a basic Order entity in the Domain layer.”

Claude Code Output (Conceptual - actual output will be more complete):

Domain/Entities/Order.cs

namespace MyCleanArchitecture.Domain.Entities;

public class Order
{
    public Guid Id { get; set; }
    public DateTime OrderDate { get; set; }
    public List<OrderItem> Items { get; set; } = new List<OrderItem>();
    public decimal TotalAmount { get; set; }
}

public class OrderItem
{
    public Guid Id { get; set; }
    public string ProductName { get; set; }
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}

Application/Interfaces/IOrderRepository.cs

using MyCleanArchitecture.Domain.Entities;

namespace MyCleanArchitecture.Application.Interfaces;

public interface IOrderRepository
{
    Task<Order?> GetByIdAsync(Guid id);
    Task AddAsync(Order order);
    Task UpdateAsync(Order order);
    Task DeleteAsync(Guid id);
    Task<IEnumerable<Order>> GetAllAsync();
}

Infrastructure/Persistence/SqlOrderRepository.cs

using MyCleanArchitecture.Application.Interfaces;
using MyCleanArchitecture.Domain.Entities;
using MyCleanArchitecture.Infrastructure.Persistence.Context; // Assuming AppDbContext is here

namespace MyCleanArchitecture.Infrastructure.Persistence;

public class SqlOrderRepository : IOrderRepository
{
    private readonly AppDbContext _context;

    public SqlOrderRepository(AppDbContext context)
    {
        _context = context ?? throw new ArgumentNullException(nameof(context));
    }

    public Task<Order?> GetByIdAsync(Guid id)
    {
        // Simplified for example
        return _context.Orders.FindAsync(id).AsTask();
    }

    public async Task AddAsync(Order order)
    {
        await _context.Orders.AddAsync(order);
        await _context.SaveChangesAsync();
    }

    public async Task UpdateAsync(Order order)
    {
        _context.Orders.Update(order);
        await _context.SaveChangesAsync();
    }

    public async Task DeleteAsync(Guid id)
    {
        var order = await _context.Orders.FindAsync(id);
        if (order != null)
        {
            _context.Orders.Remove(order);
            await _context.SaveChangesAsync();
        }
    }

    public Task<IEnumerable<Order>> GetAllAsync()
    {
        // Simplified for example
        return Task.FromResult<IEnumerable<Order>>(_context.Orders.ToList());
    }
}

Dependency Injection Configuration (e.g., in Infrastructure/DependencyInjection.cs):

using Microsoft.Extensions.DependencyInjection;
using MyCleanArchitecture.Application.Interfaces;
using MyCleanArchitecture.Infrastructure.Persistence;
using MyCleanArchitecture.Infrastructure.Persistence.Context;

public static class DependencyInjection
{
    public static IServiceCollection AddInfrastructureServices(this IServiceCollection services)
    {
        // Assuming DbContext registration is handled elsewhere or here
        // services.AddDbContext<AppDbContext>(options => ...);

        services.AddScoped<IOrderRepository, SqlOrderRepository>();
        // ... other infrastructure registrations
        return services;
    }
}

Key Takeaway: Claude Code can quickly generate the interfaces, concrete classes, and basic DI registrations, saving hours of manual typing and reducing the chance of syntax errors.

Generating Use Cases and Command/Query Handlers

The Application layer is where your business logic resides, often implemented as Use Cases. In a CQRS (Command Query Responsibility Segregation) pattern, which pairs exceptionally well with Clean Architecture, these use cases are often represented as Commands (for state changes) and Queries (for data retrieval).

Scenario: You need a CreateOrderCommand and its handler, CreateOrderCommandHandler.

Prompting Claude Code (Example):

“Generate C# code for a CQRS-style Use Case in a .NET Clean Architecture project. Task: Create a CreateOrderCommand class with properties for OrderDate, Items (a list of CreateOrderItemDto), and TotalAmount. Also, create a CreateOrderCommandHandler that implements IRequestHandler<CreateOrderCommand, Guid> (assume MediatR is used). The handler should depend on IOrderRepository and orchestrate the creation of an Order entity. Return the newly created Order’s ID.”

Claude Code Output (Conceptual):

Application/UseCases/Orders/Commands/CreateOrderCommand.cs

using MediatR;
using MyCleanArchitecture.Application.DTOs; // Assuming DTOs are in this namespace

namespace MyCleanArchitecture.Application.UseCases.Orders.Commands;

public class CreateOrderCommand : IRequest<Guid>
{
    public DateTime OrderDate { get; set; }
    public List<CreateOrderItemDto> Items { get; set; } = new List<CreateOrderItemDto>();
    public decimal TotalAmount { get; set; }
}

// Define DTOs if they don't exist
public class CreateOrderItemDto
{
    public string ProductName { get; set; }
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}

Application/UseCases/Orders/Commands/CreateOrderCommandHandler.cs

using MediatR;
using MyCleanArchitecture.Application.Interfaces;
using MyCleanArchitecture.Domain.Entities;
using MyCleanArchitecture.Application.Exceptions; // Custom exception for business rule violations

namespace MyCleanArchitecture.Application.UseCases.Orders.Commands;

public class CreateOrderCommandHandler : IRequestHandler<CreateOrderCommand, Guid>
{
    private readonly IOrderRepository _orderRepository;

    public CreateOrderCommandHandler(IOrderRepository orderRepository)
    {
        _orderRepository = orderRepository ?? throw new ArgumentNullException(nameof(orderRepository));
    }

    public async Task<Guid> Handle(CreateOrderCommand request, CancellationToken cancellationToken)
    {
        // Business Logic/Validation
        if (request.Items == null || !request.Items.Any())
        {
            throw new BusinessLogicException("Order must contain at least one item.");
        }
        if (request.TotalAmount <= 0)
        {
            throw new BusinessLogicException("Order total amount must be positive.");
        }

        var order = new Order
        {
            Id = Guid.NewGuid(),
            OrderDate = request.OrderDate,
            TotalAmount = request.TotalAmount,
            Items = request.Items.Select(dto => new OrderItem
            {
                Id = Guid.NewGuid(),
                ProductName = dto.ProductName,
                Quantity = dto.Quantity,
                UnitPrice = dto.UnitPrice
            }).ToList()
        };

        await _orderRepository.AddAsync(order);

        return order.Id;
    }
}

MediatR Registration (e.g., in Application/DependencyInjection.cs):

using Microsoft.Extensions.DependencyInjection;
using MediatR;
using System.Reflection;

public static class DependencyInjection
{
    public static IServiceCollection AddApplicationServices(this IServiceCollection services)
    {
        services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly()));
        // ... other application registrations
        return services;
    }
}

Presentation Layer Integration (e.g., in Presentation/Controllers/OrdersController.cs):

using MediatR;
using Microsoft.AspNetCore.Mvc;
using MyCleanArchitecture.Application.UseCases.Orders.Commands;
using MyCleanArchitecture.Application.UseCases.Orders.Queries; // Assume GetOrderByIdQuery exists

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IMediator _mediator;

    public OrdersController(IMediator mediator)
    {
        _mediator = mediator ?? throw new ArgumentNullException(nameof(mediator));
    }

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderCommand command)
    {
        var orderId = await _mediator.Send(command);
        return CreatedAtAction(nameof(GetOrderById), new { id = orderId }, orderId);
    }

    [HttpGet("{id}")]
    public async Task<IActionResult> GetOrderById(Guid id)
    {
        var query = new GetOrderByIdQuery { OrderId = id }; // Assume GetOrderByIdQuery is defined
        var order = await _mediator.Send(query);
        if (order == null)
        {
            return NotFound();
        }
        return Ok(order);
    }
}

Benefit: Claude Code generates the DTOs, commands, handlers, and even the basic controller actions, significantly reducing the mundane task of translating requirements into code. This allows developers to focus on the nuances of the business logic within the handler and the presentation concerns in the controller.

Architectural Considerations and Pitfalls

While Claude Code accelerates development, it doesn’t replace architectural thinking. Here are common pitfalls and how to avoid them:

1. Over-reliance on Generated Code: The “Black Box” Problem

Pitfall: Developers might accept generated code without fully understanding its implications, leading to subtle bugs or difficulty in customization later.

Avoidance:

• Treat Generated Code as a Starting Point: Always review and refactor generated code. Claude Code provides a robust foundation, but your specific domain logic and edge cases might require modifications.
• Understand the Dependencies: Be clear about which interfaces and dependencies the generated code relies on. If Claude Code generates a repository, ensure the corresponding interface exists in the Application layer.
• Invest in Unit Testing: Rigorous unit tests are your safety net. They will catch issues introduced by generated or modified code.

2. Inconsistent Naming and Layering

Pitfall: As multiple developers use AI tools, inconsistent naming conventions or incorrect placement of code within layers can creep in, undermining Clean Architecture’s clarity.

Avoidance:

• Establish Clear Guidelines: Define and document naming conventions and architectural boundaries for your team before extensive AI use.
• Leverage Claude Code for Consistency: Use specific prompts to ensure code adheres to your defined standards. For example, “Generate a Product entity in the Domain layer following PascalCase naming conventions for properties and using Guid for primary keys.”
• Code Reviews: AI-assisted development still necessitates thorough code reviews to catch architectural drift.

3. “God” Repositories/Services

Pitfall: The ease of generating CRUD operations might lead to monolithic repositories or services that handle too many unrelated concerns.

Avoidance:

• Single Responsibility Principle (SRP) at the Interface Level: Design your interfaces (e.g., IOrderRepository, IProductRepository) with specific responsibilities in mind. If a repository starts doing too much, consider splitting it into more focused interfaces.
• Prompting for Granularity: When requesting code from Claude, be explicit about the scope. Instead of “Generate repository for Order,” try “Generate a repository interface and implementation for managing Order entities, focusing on retrieval and persistence operations.”
• Architectural Review: Regularly review the layer boundaries and the responsibilities of interfaces and classes.

4. Ignoring the “Why” Behind the Layers

Pitfall: Implementing Clean Architecture just because it’s a buzzword, without understanding the benefits of each layer and the Dependency Rule.

Avoidance:

• Educate Your Team: Ensure everyone understands the principles of Clean Architecture and the rationale behind the layering.
• Focus on Benefits: When generating code, prompt Claude to explain why certain patterns are used. For instance, “Generate a CreateOrderCommandHandler. Explain why it depends on IOrderRepository and not directly on AppDbContext.”
• Iterative Refinement: Use Claude Code to refactor existing code to better adhere to Clean Architecture principles, making the benefits tangible.

5. Mismanaging Dependencies with Claude Code

Pitfall: AI might inadvertently introduce dependencies that violate the Dependency Rule, especially when generating code across layers.

Avoidance:

• Strict Layer Separation in Prompts: Be extremely precise in your prompts about which layer the generated code belongs to and what dependencies it should have.
  • Bad Prompt: “Generate an Order entity and a method to save it to the database.”
  • Good Prompt: “Generate an Order entity in the Domain layer. Then, generate an IOrderRepository interface in the Application layer with an AddAsync method. Finally, generate a SqlOrderRepository in the Infrastructure layer implementing IOrderRepository and depending on AppDbContext.”
• Dependency Graph Visualization: Use tools or manual inspection to visualize dependencies and ensure they flow inwards.

Conclusion

Clean Architecture is a powerful blueprint for building maintainable and scalable .NET applications. Claude Code acts as a potent accelerator, enabling development teams to implement these principles more rapidly and efficiently. By understanding the architectural nuances, leveraging Claude Code strategically, and diligently avoiding common pitfalls, you can build robust systems faster than ever before. The key is to view Claude Code not as a replacement for architectural expertise, but as an extension of it, allowing you to focus on the strategic challenges and the unique business value your application delivers.