Vertical Slice Architecture in ASP.NET Core Web API for Claude Code

Vertical Slice Architecture is gaining traction as a practical alternative to layered and Clean Architecture approaches for building .NET Web APIs. In this article, we explore dotnet-vsa-webapi — an opinionated Claude Code skill that helps AI agents scaffold, generate, and review ASP.NET Core Minimal API projects using a feature-first, vertical-slice structure.

Overview of dotnet-vsa-webapi architecture skill

What skills are in Claude Code, and how to connect them

Skills in Claude Code are extensions with instructions and supporting files that give the agent specialized ways of working.

A skill usually consists of a folder containing SKILL.md:

• Metadata is defined at the beginning.
• The working rules are described after that.
• Additional templates, examples, and reference files can be included when needed.

How to connect a skill

There are several main ways:

• For personal use — place the skill in:
  • ~/.claude/skills/<skill-name>/SKILL.md
• At the project level — place the skill in:
  • .claude/skills/<skill-name>/SKILL.md
• Via a plugin — install a ready-made package from the marketplace

How Claude uses skills

Claude can:

• pick up a skill automatically if its description matches the task;
• invoke it manually via a slash command.

Usually:

• name in SKILL.md becomes the slash command;
• description helps Claude understand when to apply that skill.

Against this backdrop, dotnet-vsa-webapi It is interesting because it is not a “small command,” but a full architectural playbook for Claude Code.

You can find the repository here: dotnet-vsa-webapi

Or

What this skill is and how to use it

dotnet-vsa-webapi is a skill for designing, generating, refactoring, and reviewing ASP.NET Core Minimal API projects based on:

• Vertical Slice Architecture
• feature-first structure
• Clean Architecture boundaries within each slice
• FluentValidation
• Result-based flow
• strongly typed options
• Serilog
• production-ready practices

What is it good for

This skill is useful when you need to:

• create a new .NET Web API;
• Add a new slice;
• migrate a project from a layered architecture to vertical slices;
• perform an architectural review;
• configure Aspire;
• Make the solution layout cleaner and more structured.

How it is used

The skill gives the agent a clear workflow:

1. First, inspect the current shape of the repository.
2. Then determine the type of task.
3. After that, make the smallest coherent change.
4. Keep endpoints thin.
5. Move logic into request-specific handlers, not into general god services.

So this is not just a skill that says “generate an endpoint,” but a way to make the agent operate within a specific architectural model.

Why is it a good fit for starting new projects

The main advantage of dotnet-vsa-webapi It immediately establishes strong production-oriented defaults.

What is included in the baseline

For new projects, the skill steers toward:

• .NET Aspire
• AppHost for local orchestration
• ServiceDefaults
• .slnx
• Central Package Management
• a real PostgreSQL database
• FluentValidation
• Serilog
• OpenAPI + Scalar
• OpenTelemetry
• Health probes
• Docker/Kubernetes-ready setup

Why this matters

Very often, new projects start with a bad pattern:

• “Let’s throw something together quickly for now.”;
• “We’ll add infrastructure and production practices later.”

The problem is that “later” usually never comes.

dotnet-vsa-webapi removes this trap because it:

• builds the project around real infrastructure from the start;
• does not postpone observability;
• does not postpone health checks;
• does not postpone using a real database.

Why it forbids UseInMemoryDatabase

The skill explicitly and strongly advises against using UseInMemoryDatabase for new projects, because that provider:

• does not reflect real transactions;
• does not expose constraints;
• does not reproduce migration behavior;
• hides SQL-specific details;
• creates a false sense of readiness.

Instead, it recommends using PostgreSQL via Aspire right away.

What constraints, best practices, and anti-patterns are built into it

At the core of the skill is a simple rule:

Every HTTP request is a separate vertical slice.

And the entire codebase should be organized:

• by features,
• not by technical layers.

Key architectural principles

The skill promotes these practices:

• one request = one slice
• feature-first folders
• thin endpoints
• validation located next to the slice
• direct DbContext usage for EF Core
• local SQL inside the slice when using Dapper
• shared code is earned, not created upfront
• interfaces only at meaningful seams
• Exceptions only for unexpected errors

What an endpoint should look like

The ideal flow, according to the skill, is:

1. Accept the request.
2. Validate it.
3. Call the handler.
4. Return the HTTP result.

No unnecessary magic and no heavy orchestration code inside the endpoint.

Which anti-patterns does it cut off

By default, the skill discourages:

• MediatR
• AutoMapper
• generic repository over EF Core
• fat endpoints
• god-services
• service locator
• speculative interfaces
• exception-driven business flow
• giant shared folders
• reflection-heavy magic

Why do these restrictions exist

The reasoning behind these restrictions is very practical:

• fewer unnecessary abstractions;
• fewer layers for the sake of layers;
• less magic;
• more transparency;
• more local changes;
• better code readability.

Why does it work well for agentic development

For agentic development, dotnet-vsa-webapi It is especially good because it forces the agent to think in terms of use cases, not technical layers.

What it suggests is that instead of a layered structure

Instead of an approach like this:

• Controllers/
• Services/
• Repositories/

The skill points toward something more like:

• Features/Orders/CreateOrder/
• Features/Orders/GetOrder/
• Features/Orders/CancelOrder/

What lives inside a single slice

Usually, the following are kept together:

• request DTO;
• validator;
• handler;
• response;
• endpoint.

Why is this convenient for an AI agent

This structure gives the agent several advantages:

• It is easier to find the right place to make a change;
• It is easier to add a new use case;
• It is easier to make local changes;
• It is easier to avoid touching the entire solution;
• It is easier to maintain consistency across features;
• It is easier to avoid creating shared abstractions “just in case.”

Why does the structure end up cleaner

The skill additionally forces the agent to:

1. First, inspect the current repository shape;
2. then make the smallest coherent change;
3. avoid rewriting half the project unnecessarily.

This is especially important in agentic development because it reduces a typical AI problem: when making one change, the tool also starts “improving” everything around it at the same time.

Vertical Slice Architecture vs Clean Architecture

Both Vertical Slice Architecture and Clean Architecture aim to keep .NET codebases maintainable, but they solve the problem differently.

Folder structure

Clean Architecture splits the solution into layers: Domain, Application, Infrastructure, and Presentation. A single feature touches all four projects. Vertical Slice Architecture groups everything by feature — request, validation, handler, and response live in one folder such as Features/Orders/CreateOrder/.

Dependency direction

In Clean Architecture, dependencies flow inward toward the domain, enforced by project references. In Vertical Slice Architecture, each slice is self-contained; cross-slice coupling is avoided, and shared code is extracted only when duplication is proven.

When to choose which

Clean Architecture is a good fit when your domain model is complex and reused across many entry points (APIs, message handlers, scheduled jobs). Vertical Slice Architecture shines when most logic is request-specific, the team values locality, and you want to avoid premature abstractions.

dotnet-vsa-webapi leans firmly into the vertical-slice camp and adds opinionated production defaults on top.

Frequently Asked Questions

Conclusion

Why it is good

• It provides a strong baseline for new projects;
• It immediately pulls in production-friendly defaults;
• It limits harmful patterns;
• It helps keep architecture under control;
• It creates a predictable feature-first structure;
• it is well suited for agentic development.

What makes it specific

• It is highly opinionated;
• It is not universal for every .NET scenario;
• Its value lies precisely in the fact that it imposes strict rules.

Brief takeaway