@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/dotnet/CLAUDE.md

@@ -4,316 +4,83 @@
 
 ## Stack
 
-- .NET 8+ (latest LTS)
+- .NET 9 / .NET 8 (LTS)
 - ASP.NET Core Web API
 - Entity Framework Core
-- C# 12+ features
-- xUnit for testing
+- C# 13+
+- xUnit + NSubstitute + FluentAssertions
 
-## Architecture
-
-### Clean Architecture (Recommended)
+## Architecture - Clean Architecture
 
 ```
 src/
-├── Domain/                        # Core business logic (no dependencies)
-│   ├── Entities/
-│   │   └── User.cs
-│   ├── ValueObjects/
-│   │   └── Email.cs
-│   ├── Enums/
-│   ├── Exceptions/
-│   │   └── DomainException.cs
-│   └── Interfaces/
-│       └── IUserRepository.cs
-│
-├── Application/                   # Use cases, CQRS, DTOs
-│   ├── Common/
-│   │   ├── Behaviors/
-│   │   │   ├── ValidationBehavior.cs
-│   │   │   └── LoggingBehavior.cs
-│   │   ├── Interfaces/
-│   │   │   └── IApplicationDbContext.cs
-│   │   └── Mappings/
-│   │       └── MappingProfile.cs
-│   ├── Users/
-│   │   ├── Commands/
-│   │   │   ├── CreateUser/
-│   │   │   │   ├── CreateUserCommand.cs
-│   │   │   │   ├── CreateUserCommandHandler.cs
-│   │   │   │   └── CreateUserCommandValidator.cs
-│   │   │   └── UpdateUser/
-│   │   └── Queries/
-│   │       ├── GetUser/
-│   │       │   ├── GetUserQuery.cs
-│   │       │   ├── GetUserQueryHandler.cs
-│   │       │   └── UserDto.cs
-│   │       └── GetUsers/
-│   └── DependencyInjection.cs
-│
-├── Infrastructure/                # External concerns
-│   ├── Data/
-│   │   ├── ApplicationDbContext.cs
-│   │   ├── Configurations/
-│   │   │   └── UserConfiguration.cs
-│   │   └── Migrations/
-│   ├── Repositories/
-│   │   └── UserRepository.cs
-│   ├── Services/
-│   │   └── DateTimeService.cs
-│   └── DependencyInjection.cs
-│
-└── WebApi/                        # Presentation layer
-    ├── Controllers/
-    │   └── UsersController.cs
-    ├── Filters/
-    │   └── ApiExceptionFilterAttribute.cs
-    ├── Middleware/
-    │   └── ExceptionHandlingMiddleware.cs
-    ├── Program.cs
-    └── appsettings.json
+├── Domain/           # Entities, ValueObjects, Interfaces
+│                     # ZERO external dependencies
+├── Application/      # Commands, Queries, DTOs, Validators
+│                     # MediatR, FluentValidation
+├── Infrastructure/   # DbContext, Repositories, External services
+│                     # EF Core, external APIs
+└── WebApi/           # Controllers/Endpoints, Middleware
+                      # Presentation layer
 ```
 
-### Project References
+**Dependencies**:
+- `WebApi → Application → Domain`
+- `Infrastructure → Application → Domain`
 
-```
-WebApi → Application → Domain
-WebApi → Infrastructure → Application → Domain
-```
+## Core Principles
 
-**Key rule**: Domain has ZERO external dependencies.
+### CQRS with MediatR
 
-## Code Style
+- **Commands** (write): Modify state, return minimal data (ID or void)
+- **Queries** (read): Return data, never modify state
+- Commands and queries implement `IRequest<T>`
 
-### Naming Conventions
+### C# 12 Style
 
-| Element | Convention | Example |
-|---------|------------|---------|
-| Classes | PascalCase | `UserService` |
-| Interfaces | IPascalCase | `IUserRepository` |
-| Methods | PascalCase | `GetUserById` |
-| Properties | PascalCase | `FirstName` |
-| Private fields | _camelCase | `_userRepository` |
-| Parameters | camelCase | `userId` |
-| Constants | PascalCase | `MaxRetryCount` |
-| Async methods | Suffix Async | `GetUserAsync` |
+- File-scoped namespaces
+- Primary constructors for DI
+- Records for DTOs
+- Nullable reference types enabled
+- Required members with `required` keyword
 
-### File-Scoped Namespaces
+### Naming
 
-```csharp
-// Good - C# 10+
-namespace MyApp.Domain.Entities;
+| Element | Convention |
+|---------|------------|
+| Classes/Methods | PascalCase |
+| Interfaces | IPascalCase |
+| Private fields | _camelCase |
+| Async methods | Suffix `Async` |
+| Constants | PascalCase |
 
-public class User { }
+### API Patterns
 
-// Avoid
-namespace MyApp.Domain.Entities
-{
-    public class User { }
-}
-```
+- **Minimal APIs**: Preferred for new projects (93% less memory in .NET 9)
+- **Controllers**: Only for complex model binding scenarios
+- Use `ISender` from MediatR for dispatching commands/queries
+- Return `TypedResults.Ok()`, `TypedResults.NotFound()`, etc.
+- Built-in OpenAPI: `AddOpenApi()` + `MapOpenApi()`
 
-### Primary Constructors (C# 12)
+### Validation
 
-```csharp
-// Good - for simple DI
-public class UserService(IUserRepository userRepository, ILogger<UserService> logger)
-{
-    public async Task<User?> GetByIdAsync(Guid id)
-    {
-        logger.LogInformation("Getting user {UserId}", id);
-        return await userRepository.GetByIdAsync(id);
-    }
-}
-
-// Use traditional constructors when you need field assignment or validation
-```
-
-### Records for DTOs
-
-```csharp
-// Immutable DTOs
-public record UserDto(Guid Id, string Email, string Name);
-
-public record CreateUserRequest(string Email, string Password, string Name);
-
-// With validation attributes
-public record CreateUserCommand(
-    [Required][EmailAddress] string Email,
-    [Required][MinLength(8)] string Password,
-    [Required] string Name
-) : IRequest<Guid>;
-```
-
-### Nullable Reference Types
-
-```csharp
-// Enable in .csproj
-<Nullable>enable</Nullable>
-
-// Be explicit about nullability
-public async Task<User?> GetByIdAsync(Guid id);  // Can return null
-public async Task<User> GetByIdOrThrowAsync(Guid id);  // Never null
-```
+- FluentValidation for complex rules
+- Data annotations for simple DTOs
+- Validation in MediatR pipeline behavior
 
 ## Commands
 
 ```bash
-# Development
-dotnet run --project src/WebApi
-
-# Build
-dotnet build
-dotnet publish -c Release
-
-# Tests
-dotnet test
-dotnet test --filter "Category=Unit"
-dotnet test --collect:"XPlat Code Coverage"
-
-# EF Core migrations
-dotnet ef migrations add InitialCreate -p src/Infrastructure -s src/WebApi
+dotnet run --project src/WebApi           # Dev
+dotnet build                               # Build
+dotnet test                                # Test
+dotnet ef migrations add Name -p src/Infrastructure -s src/WebApi
 dotnet ef database update -p src/Infrastructure -s src/WebApi
-
-# Format
-dotnet format
 ```
 
-## Common Patterns
-
-### Minimal API Endpoints
-
-```csharp
-// Program.cs or endpoint extension
-app.MapGet("/users/{id:guid}", async (Guid id, ISender sender) =>
-{
-    var user = await sender.Send(new GetUserQuery(id));
-    return user is not null ? Results.Ok(user) : Results.NotFound();
-})
-.WithName("GetUser")
-.WithOpenApi()
-.RequireAuthorization();
-
-app.MapPost("/users", async (CreateUserCommand command, ISender sender) =>
-{
-    var id = await sender.Send(command);
-    return Results.CreatedAtRoute("GetUser", new { id }, id);
-})
-.WithName("CreateUser")
-.WithOpenApi();
-```
-
-### Controller-Based API
-
-```csharp
-[ApiController]
-[Route("api/[controller]")]
-public class UsersController(ISender sender) : ControllerBase
-{
-    [HttpGet("{id:guid}")]
-    [ProducesResponseType<UserDto>(StatusCodes.Status200OK)]
-    [ProducesResponseType(StatusCodes.Status404NotFound)]
-    public async Task<IActionResult> Get(Guid id)
-    {
-        var user = await sender.Send(new GetUserQuery(id));
-        return user is not null ? Ok(user) : NotFound();
-    }
-
-    [HttpPost]
-    [ProducesResponseType<Guid>(StatusCodes.Status201Created)]
-    [ProducesResponseType(StatusCodes.Status400BadRequest)]
-    public async Task<IActionResult> Create(CreateUserCommand command)
-    {
-        var id = await sender.Send(command);
-        return CreatedAtAction(nameof(Get), new { id }, id);
-    }
-}
-```
-
-### Global Exception Handling
-
-```csharp
-public class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
-{
-    public async Task InvokeAsync(HttpContext context)
-    {
-        try
-        {
-            await next(context);
-        }
-        catch (ValidationException ex)
-        {
-            context.Response.StatusCode = StatusCodes.Status400BadRequest;
-            await context.Response.WriteAsJsonAsync(new ProblemDetails
-            {
-                Status = 400,
-                Title = "Validation Error",
-                Detail = string.Join(", ", ex.Errors.Select(e => e.ErrorMessage))
-            });
-        }
-        catch (NotFoundException ex)
-        {
-            context.Response.StatusCode = StatusCodes.Status404NotFound;
-            await context.Response.WriteAsJsonAsync(new ProblemDetails
-            {
-                Status = 404,
-                Title = "Not Found",
-                Detail = ex.Message
-            });
-        }
-        catch (Exception ex)
-        {
-            logger.LogError(ex, "Unhandled exception");
-            context.Response.StatusCode = StatusCodes.Status500InternalServerError;
-            await context.Response.WriteAsJsonAsync(new ProblemDetails
-            {
-                Status = 500,
-                Title = "Server Error"
-            });
-        }
-    }
-}
-```
-
-### Dependency Injection Setup
-
-```csharp
-// Application/DependencyInjection.cs
-public static class DependencyInjection
-{
-    public static IServiceCollection AddApplication(this IServiceCollection services)
-    {
-        services.AddMediatR(cfg => {
-            cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
-            cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
-            cfg.AddBehavior(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
-        });
-
-        services.AddValidatorsFromAssembly(Assembly.GetExecutingAssembly());
-        services.AddAutoMapper(Assembly.GetExecutingAssembly());
-
-        return services;
-    }
-}
-
-// Infrastructure/DependencyInjection.cs
-public static class DependencyInjection
-{
-    public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
-    {
-        services.AddDbContext<ApplicationDbContext>(options =>
-            options.UseSqlServer(configuration.GetConnectionString("DefaultConnection")));
-
-        services.AddScoped<IApplicationDbContext>(sp =>
-            sp.GetRequiredService<ApplicationDbContext>());
-
-        services.AddScoped<IUserRepository, UserRepository>();
-
-        return services;
-    }
-}
+## Code Style
 
-// Program.cs
-builder.Services.AddApplication();
-builder.Services.AddInfrastructure(builder.Configuration);
-```
+- `readonly` for immutable fields
+- Expression-bodied members when simple
+- Pattern matching over type checks
+- `async`/`await` all the way down

package/configs/fastapi/.claude/rules/background-tasks.md

@@ -0,0 +1,254 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# FastAPI Background Tasks
+
+## Simple Background Tasks
+
+```python
+from fastapi import BackgroundTasks
+
+def write_log(message: str):
+    with open("log.txt", "a") as f:
+        f.write(f"{datetime.now()}: {message}\n")
+
+@router.post("/items")
+async def create_item(
+    item: ItemCreate,
+    background_tasks: BackgroundTasks,
+) -> ItemResponse:
+    # Process item
+    created_item = await item_service.create(item)
+
+    # Queue background task
+    background_tasks.add_task(write_log, f"Item created: {created_item.id}")
+
+    # Return immediately
+    return created_item
+```
+
+## Async Background Tasks
+
+```python
+async def send_notification(user_id: int, message: str):
+    async with httpx.AsyncClient() as client:
+        await client.post(
+            "https://notification-service/send",
+            json={"user_id": user_id, "message": message},
+        )
+
+@router.post("/orders")
+async def create_order(
+    order: OrderCreate,
+    background_tasks: BackgroundTasks,
+    db: DbSession,
+) -> OrderResponse:
+    created_order = await order_service.create(db, order)
+
+    # Async task
+    background_tasks.add_task(
+        send_notification,
+        order.user_id,
+        f"Order {created_order.id} confirmed",
+    )
+
+    return created_order
+```
+
+## Multiple Background Tasks
+
+```python
+@router.post("/signup")
+async def signup(
+    user: UserCreate,
+    background_tasks: BackgroundTasks,
+) -> UserResponse:
+    created_user = await user_service.create(user)
+
+    # Queue multiple tasks
+    background_tasks.add_task(send_welcome_email, created_user.email)
+    background_tasks.add_task(notify_admin, created_user.id)
+    background_tasks.add_task(update_analytics, "new_signup")
+
+    return created_user
+```
+
+## Background Tasks in Dependencies
+
+```python
+async def log_request(
+    request: Request,
+    background_tasks: BackgroundTasks,
+):
+    background_tasks.add_task(
+        log_to_database,
+        path=request.url.path,
+        method=request.method,
+        timestamp=datetime.now(),
+    )
+
+@router.get("/data", dependencies=[Depends(log_request)])
+async def get_data() -> dict:
+    return {"data": "value"}
+```
+
+## Long-Running Tasks with Celery
+
+```python
+# tasks.py
+from celery import Celery
+
+celery_app = Celery(
+    "tasks",
+    broker="redis://localhost:6379/0",
+    backend="redis://localhost:6379/0",
+)
+
+@celery_app.task
+def process_large_file(file_path: str) -> dict:
+    # Long-running process
+    result = heavy_computation(file_path)
+    return {"status": "completed", "result": result}
+
+# router.py
+from tasks import process_large_file
+
+@router.post("/process")
+async def process_file(file: UploadFile) -> dict:
+    # Save file
+    file_path = f"/tmp/{file.filename}"
+    async with aiofiles.open(file_path, "wb") as f:
+        await f.write(await file.read())
+
+    # Queue Celery task
+    task = process_large_file.delay(file_path)
+
+    return {"task_id": task.id, "status": "processing"}
+
+@router.get("/process/{task_id}")
+async def get_task_status(task_id: str) -> dict:
+    task = process_large_file.AsyncResult(task_id)
+
+    if task.ready():
+        return {"status": "completed", "result": task.result}
+
+    return {"status": task.status}
+```
+
+## ARQ (Async Redis Queue)
+
+```python
+# tasks.py
+from arq import create_pool
+from arq.connections import RedisSettings
+
+async def send_email_task(ctx, email: str, subject: str, body: str):
+    await email_service.send(email, subject, body)
+
+class WorkerSettings:
+    functions = [send_email_task]
+    redis_settings = RedisSettings()
+
+# router.py
+from arq import create_pool
+
+@router.post("/send-email")
+async def send_email(email: EmailSchema) -> dict:
+    redis = await create_pool(RedisSettings())
+
+    job = await redis.enqueue_job(
+        "send_email_task",
+        email.to,
+        email.subject,
+        email.body,
+    )
+
+    return {"job_id": job.job_id, "status": "queued"}
+```
+
+## Periodic Tasks
+
+```python
+# Using APScheduler
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+async def cleanup_expired_sessions():
+    async with async_session() as db:
+        await db.execute(
+            delete(Session).where(Session.expires_at < datetime.utcnow())
+        )
+        await db.commit()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Start scheduler
+    scheduler.add_job(
+        cleanup_expired_sessions,
+        "interval",
+        hours=1,
+    )
+    scheduler.start()
+    yield
+    # Shutdown
+    scheduler.shutdown()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+## Task Status Tracking
+
+```python
+from enum import Enum
+import uuid
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+# In-memory store (use Redis in production)
+tasks_store: dict[str, dict] = {}
+
+async def process_with_tracking(task_id: str, data: dict):
+    tasks_store[task_id]["status"] = TaskStatus.RUNNING
+
+    try:
+        result = await heavy_process(data)
+        tasks_store[task_id].update({
+            "status": TaskStatus.COMPLETED,
+            "result": result,
+        })
+    except Exception as e:
+        tasks_store[task_id].update({
+            "status": TaskStatus.FAILED,
+            "error": str(e),
+        })
+
+@router.post("/process")
+async def start_processing(
+    data: ProcessData,
+    background_tasks: BackgroundTasks,
+) -> dict:
+    task_id = str(uuid.uuid4())
+
+    tasks_store[task_id] = {
+        "status": TaskStatus.PENDING,
+        "created_at": datetime.utcnow(),
+    }
+
+    background_tasks.add_task(process_with_tracking, task_id, data.dict())
+
+    return {"task_id": task_id}
+
+@router.get("/process/{task_id}")
+async def get_status(task_id: str) -> dict:
+    if task_id not in tasks_store:
+        raise HTTPException(404, "Task not found")
+
+    return tasks_store[task_id]
+```