backend-feature
Scaffolds backend features including new domain entities, new properties on existing entities, and new business operations. Use when creating a new domain entity, extending an existing entity with new properties, or adding new business features/commands.
When & Why to Use This Skill
This Claude skill automates the scaffolding of backend features for .NET applications, specifically designed for projects following Domain-Driven Design (DDD) and CQRS patterns. It streamlines the development process by generating complete vertical slices for new domain entities, extending existing models with new properties, and implementing business operations. By automating the creation of DTOs, mappers, MediatR handlers, and EF Core configurations, it ensures architectural consistency and significantly reduces manual boilerplate code.
Use Cases
- New Domain Entity Scaffolding: Rapidly create a full backend structure for new business objects (e.g., 'Product', 'Order') including domain events, DTOs, controllers, and persistence logic.
- Entity Property Extension: Seamlessly add new fields to existing entities while automatically updating all related components like Mapperly mappers, request/response DTOs, and database configurations.
- Business Logic & CQRS Implementation: Add new business commands or queries to existing entities by generating standardized MediatR handlers and API endpoints.
- Database Schema Evolution: Automate the generation of Entity Framework Core migrations and entity configurations when modifying domain models.
- Architectural Standardization: Ensure that all backend features across a team follow the same structural patterns, naming conventions, and best practices for clean architecture.
| name | backend-feature |
|---|---|
| description | Scaffolds backend features including new domain entities, new properties on existing entities, and new business operations. Use when creating a new domain entity, extending an existing entity with new properties, or adding new business features/commands. |
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash(dotnet:*, ls:*, mkdir:*) |
Backend Feature Scaffolding
This skill handles three scenarios:
- New Entity - Create a complete vertical slice for a new domain entity
- New Property - Add properties to an existing entity
- New Feature - Add business operations (commands/queries) to an existing entity
Scenario 1: New Entity
For a new entity named [EntityName] (e.g., Customer, Order, Product), this skill generates:
Domain/
└── [EntityName]s/
├── [EntityName].cs # Rich domain entity
├── DomainEvents/
│ ├── [EntityName]Created.cs
│ ├── [EntityName]Updated.cs
│ └── [EntityName]Deleted.cs
├── Dtos/
│ ├── [EntityName]Dto.cs
│ ├── [EntityName]ForCreationDto.cs
│ ├── [EntityName]ForUpdateDto.cs
│ └── [EntityName]ParametersDto.cs
├── Features/
│ ├── Add[EntityName].cs
│ ├── Update[EntityName].cs
│ ├── Delete[EntityName].cs
│ ├── Get[EntityName].cs
│ └── Get[EntityName]List.cs
├── Mappings/
│ └── [EntityName]Mapper.cs
└── Models/
├── [EntityName]ForCreation.cs
└── [EntityName]ForUpdate.cs
Databases/
└── EntityConfigurations/
└── [EntityName]Configuration.cs # EF Core entity configuration
Controllers/
└── v1/
└── [EntityName]sController.cs
Scenario 2: New Property on Existing Entity
When adding properties to an existing entity, update these files:
| File | Changes |
|---|---|
[EntityName].cs |
Add property with private setter |
[EntityName]ForCreation.cs |
Add property if set at creation |
[EntityName]ForUpdate.cs |
Add property if updatable |
[EntityName]ForCreationDto.cs |
Add property if set at creation |
[EntityName]ForUpdateDto.cs |
Add property if updatable |
[EntityName]Dto.cs |
Add property for response |
[EntityName]Mapper.cs |
Add custom mapping if value object |
[EntityName]Configuration.cs |
Configure property constraints, value objects |
Scenario 3: New Feature on Existing Entity
When adding a business operation to an existing entity:
| Component | Files to Create/Modify |
|---|---|
| Domain method | [EntityName].cs - Add behavior method |
| Domain event | DomainEvents/[EntityName][Action].cs - New event |
| Feature | Features/[Action][EntityName].cs - New command/query |
| Controller | [EntityName]sController.cs - Add endpoint |
| DTOs (if needed) | Dtos/[Action][EntityName]Dto.cs - Request/response |
Usage Examples
New Entity
Create a backend feature for managing Products with name, price, and category
New Property on Existing Entity
Add an email property to the Customer entity
Add a status property with Draft, Active, and Archived states to the Product entity
New Feature on Existing Entity
Add a Submit feature to the Order entity that changes status and validates requirements
Add a GetOrdersByCustomer query that returns orders for a specific customer
Process: New Entity
Gather Requirements
- Entity name (PascalCase, singular:
Customer,Order,Product) - Properties and their types
- Any special business rules or value objects needed
- Entity name (PascalCase, singular:
Generate Domain Entity
- Create rich domain entity following DDD principles
- Private setters, factory methods, encapsulated behavior
- Value objects for complex concepts
- See:
.claude/rules/backend/working-with-domain-entities.md
Generate Domain Events
- Created, Updated, Deleted events
- Additional business-specific events as needed
- See:
.claude/rules/backend/domain-events.md
Generate DTOs and Models
- Read DTO for responses
- Creation/Update DTOs for requests
- Parameters DTO for list queries
- Internal models for domain method contracts
- See:
.claude/rules/backend/dtos-and-mappings.md
Generate Mapperly Mapper
- Entity to DTO mappings
- DTO to internal model mappings
- IQueryable projection support
- See:
.claude/rules/backend/dtos-and-mappings.md
Generate CQRS Features
- Add, Update, Delete commands
- Get single and Get list queries
- MediatR handlers with proper patterns
- See:
.claude/rules/backend/features-and-cqrs.md
Generate Controller
- Thin controller delegating to MediatR
- Proper API versioning
- OpenAPI documentation
- See:
.claude/rules/backend/controllers.md
Generate Entity Configuration
- Create
IEntityTypeConfiguration<T>class - Configure property constraints and indexes
- Configure value object mappings with
OwnsOne - See:
.claude/rules/backend/entity-configurations.md
- Create
Update Infrastructure
- Add DbSet to AppDbContext
- Ensure
ApplyConfigurationsFromAssemblyis called in OnModelCreating
Process: New Property
Read Existing Entity
- Understand current entity structure and patterns
- Identify if property is a simple type or value object
Add Property to Domain Entity
// Simple property public string PhoneNumber { get; private set; } // Value object property public EmailAddress Email { get; private set; } = default!;Update Factory Method (if set at creation)
public static Customer Create(CustomerForCreation forCreation) { var entity = new Customer { // ... existing properties PhoneNumber = forCreation.PhoneNumber, // Add new property }; // ... }Update Update Method (if updatable)
public Customer Update(CustomerForUpdate forUpdate) { // ... existing updates PhoneNumber = forUpdate.PhoneNumber; // Add new property // ... }Update Internal Models
- Add to
[EntityName]ForCreation.csif set at creation - Add to
[EntityName]ForUpdate.csif updatable
- Add to
Update DTOs
- Add to
[EntityName]Dto.csfor responses - Add to
[EntityName]ForCreationDto.csif set at creation - Add to
[EntityName]ForUpdateDto.csif updatable
- Add to
Update Mapper (for value objects)
// Add custom mapping for value objects private static string? MapEmail(EmailAddress? email) => email?.Value;Update Entity Configuration
// Simple property builder.Property(e => e.PhoneNumber).HasMaxLength(20); // Value object builder.OwnsOne(e => e.Email, email => { email.Property(e => e.Value).HasColumnName("email").HasMaxLength(320); });Create Migration
dotnet ef migrations add Add[PropertyName]To[EntityName]
Process: New Feature
Read Existing Entity
- Understand current entity structure
- Identify what state changes are needed
- Determine guard conditions
Add Domain Method to Entity
public Order Submit() { GuardIfNotDraft("Cannot submit"); Status = OrderStatus.Submitted(); QueueDomainEvent(new OrderSubmitted { OrderId = Id, SubmittedAt = DateTimeOffset.UtcNow }); return this; }Create Domain Event (if needed)
// DomainEvents/OrderSubmitted.cs public sealed record OrderSubmitted : IDomainEvent { public required Guid OrderId { get; init; } public required DateTimeOffset SubmittedAt { get; init; } }Create Feature (Command or Query)
// Features/SubmitOrder.cs public static class SubmitOrder { public sealed record Command(Guid Id) : IRequest<OrderDto>; public sealed class Handler(AppDbContext dbContext) : IRequestHandler<Command, OrderDto> { public async Task<OrderDto> Handle(Command request, CancellationToken ct) { var order = await dbContext.Orders.GetById(request.Id, ct); order.Submit(); await dbContext.SaveChangesAsync(ct); return order.ToOrderDto(); } } }Add Endpoint to Controller
/// <summary> /// Submits an order for processing. /// </summary> [Authorize] [HttpPost("{id:guid}/submit", Name = "SubmitOrder")] [ProducesResponseType(typeof(OrderDto), StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status404NotFound)] [ProducesResponseType(StatusCodes.Status400BadRequest)] public async Task<ActionResult<OrderDto>> SubmitOrder(Guid id) { var command = new SubmitOrder.Command(id); var result = await mediator.Send(command); return Ok(result); }Create Additional DTOs (if needed)
- Request DTO if the action needs input parameters
- Custom response DTO if different from standard entity DTO
Important Guidelines
Domain Entity Design
- Use private setters for all properties
- Create static factory method
Create()for entity creation - Use
Update()method for modifications - Implement guard methods for business rules
- Use value objects for complex domain concepts
- Queue domain events on state changes
Property Naming
- Entity properties: PascalCase (
FirstName,Email) - DTO properties: PascalCase with
{ get; init; } - Route parameters: camelCase in URLs, PascalCase in code
Value Objects to Consider
EmailAddress- validated emailPhoneNumber- formatted phoneMoney- currency with amountAddress- street, city, state, zip- Status enums with SmartEnum pattern
Common Patterns
Status with Behavior:
public class OrderStatus : ValueObject
{
private OrderStatusEnum _status;
public bool IsFinalState() => _status.IsFinalState();
public bool CanBeCancelled() => !IsFinalState();
public static OrderStatus Draft() => new("Draft");
public static OrderStatus Submitted() => new("Submitted");
}
Encapsulated Collections:
private readonly List<LineItem> _lineItems = [];
public IReadOnlyCollection<LineItem> LineItems => _lineItems.AsReadOnly();
public LineItem AddLineItem(Product product, int quantity)
{
var item = LineItem.Create(product, quantity);
_lineItems.Add(item);
return item;
}
Checklists
New Entity Checklist
- Review generated entity for business logic completeness
- Add DbSet to
AppDbContext.cs - Verify entity configuration is in
Databases/EntityConfigurations/and properly applied - Install MediatR if not already present
- Install Mapperly if not already present
- Run
dotnet buildto verify compilation - Add any needed FluentValidation validators
- Consider what additional business methods the entity needs
- Run
dotnet ef migrations add Add[EntityName]to create migration
New Property Checklist
- Property added with private setter in entity
- Factory method updated (if set at creation)
- Update method updated (if updatable)
- Internal models updated (ForCreation/ForUpdate)
- DTOs updated (Dto, ForCreationDto, ForUpdateDto as needed)
- Mapper updated (custom mapping for value objects)
- Entity configuration updated (constraints, value object mapping)
- Run
dotnet buildto verify compilation - Run
dotnet ef migrations add Add[PropertyName]To[EntityName]
New Feature Checklist
- Domain method added to entity with proper guards
- Domain event created (if state change is significant)
- Feature file created with Command/Query and Handler
- Controller endpoint added with proper attributes
- Additional DTOs created if needed
- Run
dotnet buildto verify compilation
Reference Files
The following rules provide detailed patterns:
.claude/rules/backend/working-with-domain-entities.md- Rich domain entities.claude/rules/backend/features-and-cqrs.md- CQRS with MediatR.claude/rules/backend/dtos-and-mappings.md- DTOs and Mapperly.claude/rules/backend/controllers.md- API controllers.claude/rules/backend/domain-events.md- Domain events.claude/rules/backend/entity-configurations.md- EF Core entity configurations