From 2773012640197035e6295cb20c7b790cba0aaf14 Mon Sep 17 00:00:00 2001 From: maliming Date: Mon, 9 Mar 2026 17:52:45 +0800 Subject: [PATCH] improve: enhance Claude Code skills descriptions and add key rules sections --- .claude/skills/abp-angular/SKILL.md | 2 +- .claude/skills/abp-app-nolayers/SKILL.md | 2 +- .claude/skills/abp-application-layer/SKILL.md | 10 +++++- .claude/skills/abp-authorization/SKILL.md | 2 +- .claude/skills/abp-blazor/SKILL.md | 2 +- .claude/skills/abp-cli/SKILL.md | 2 +- .claude/skills/abp-core/SKILL.md | 10 +++++- .claude/skills/abp-ddd/SKILL.md | 10 +++++- .claude/skills/abp-dependency-rules/SKILL.md | 2 +- .claude/skills/abp-development-flow/SKILL.md | 31 +------------------ .claude/skills/abp-ef-core/SKILL.md | 11 ++++++- .claude/skills/abp-infrastructure/SKILL.md | 2 +- .claude/skills/abp-microservice/SKILL.md | 2 +- .claude/skills/abp-module/SKILL.md | 2 +- .claude/skills/abp-mongodb/SKILL.md | 2 +- .claude/skills/abp-multi-tenancy/SKILL.md | 2 +- .claude/skills/abp-mvc/SKILL.md | 2 +- .claude/skills/abp-testing/SKILL.md | 2 +- 18 files changed, 51 insertions(+), 47 deletions(-) diff --git a/.claude/skills/abp-angular/SKILL.md b/.claude/skills/abp-angular/SKILL.md index c0734cc701..3723cc3266 100644 --- a/.claude/skills/abp-angular/SKILL.md +++ b/.claude/skills/abp-angular/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-angular -description: ABP Angular UI patterns - project structure, service proxies, list components, localization, authorization, forms, modals, toast notifications. Use when working on Angular UI in ABP projects. +description: ABP Angular UI patterns - generate-proxy, ListService, PermissionGuard, abpLocalization pipe, ConfirmationService, ToasterService, ConfigStateService. Use when building or reviewing Angular UI components, routing, or service integration in ABP Angular projects. --- # ABP Angular UI diff --git a/.claude/skills/abp-app-nolayers/SKILL.md b/.claude/skills/abp-app-nolayers/SKILL.md index 99a8b61d8e..74603e288e 100644 --- a/.claude/skills/abp-app-nolayers/SKILL.md +++ b/.claude/skills/abp-app-nolayers/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-app-nolayers -description: ABP Single-Layer (No-Layers) application template patterns - simplified structure, file organization, simplified entities. Use when working with the single-layer web application template. +description: ABP Single-Layer (No-Layers / nolayers) application template - single project structure, feature-based file organization, no separate Domain/Application.Contracts projects. Use when working with the single-layer web application template or when the project has no layered separation. --- # ABP Single-Layer Application Template diff --git a/.claude/skills/abp-application-layer/SKILL.md b/.claude/skills/abp-application-layer/SKILL.md index d43017d1a0..d5507c2a7e 100644 --- a/.claude/skills/abp-application-layer/SKILL.md +++ b/.claude/skills/abp-application-layer/SKILL.md @@ -1,12 +1,20 @@ --- name: abp-application-layer -description: ABP Application Services, DTOs, validation, error handling, object mapping patterns. Use when creating or reviewing application services, DTOs, or working in the Application or Application.Contracts projects. +description: ABP Application Services, DTOs, CRUD service, object mapping (Mapperly/AutoMapper), validation, error handling. Use when creating or reviewing application services, DTOs, or working in the Application or Application.Contracts projects. --- # ABP Application Layer Patterns > **Docs**: https://abp.io/docs/latest/framework/architecture/domain-driven-design/application-services +## Anti-Patterns to Avoid + +- **Entity name in method**: use `GetAsync` not `GetBookAsync` +- **ID inside UpdateDto**: pass `id` as a separate parameter, not inside the DTO +- **Calling other app services in the same module**: use domain services or repositories directly +- **Using `IFormFile`/`Stream` in app service**: accept `byte[]` from controllers instead +- **Business logic in app service**: put it in domain entities or domain services + ## Application Service Structure ### Interface (Application.Contracts) diff --git a/.claude/skills/abp-authorization/SKILL.md b/.claude/skills/abp-authorization/SKILL.md index c3db176931..a805f5f067 100644 --- a/.claude/skills/abp-authorization/SKILL.md +++ b/.claude/skills/abp-authorization/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-authorization -description: ABP permission system and authorization patterns - defining permissions, using Authorize attribute, programmatic checks, current user access, multi-tenancy permissions. Use when working with permissions, authorization, or security in ABP projects. +description: ABP permission system - PermissionDefinitionProvider, [Authorize] attribute, CheckPolicyAsync, IsGrantedAsync, ICurrentUser, IPermissionManager, multi-tenancy side. Use when working with permissions, authorization, role-based access, or security in ABP projects. --- # ABP Authorization diff --git a/.claude/skills/abp-blazor/SKILL.md b/.claude/skills/abp-blazor/SKILL.md index 8a347beb68..ff0ef325dc 100644 --- a/.claude/skills/abp-blazor/SKILL.md +++ b/.claude/skills/abp-blazor/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-blazor -description: ABP Blazor UI patterns - component base classes, CRUD pages, localization, authorization, navigation/menu, notifications, forms, JavaScript interop. Use when working on Blazor UI in ABP projects. +description: ABP Blazor UI patterns - AbpComponentBase, AbpCrudPageBase, DataGrid, IMenuContributor, Message/Notify, Validations, JavaScript interop. Use when building or reviewing Blazor Server or WebAssembly UI components in ABP projects. --- # ABP Blazor UI diff --git a/.claude/skills/abp-cli/SKILL.md b/.claude/skills/abp-cli/SKILL.md index 365ea78f4d..da08280b39 100644 --- a/.claude/skills/abp-cli/SKILL.md +++ b/.claude/skills/abp-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-cli -description: ABP CLI commands reference - generate-proxy, install-libs, add-package-ref, new-module, install-module, update, clean, suite generate. Use when the user needs to run ABP CLI commands or asks about ABP tooling. +description: ABP CLI commands - generate-proxy, install-libs, add-package-ref, new-module, install-module, abp update, abp clean, abp suite generate. Use when the user asks how to run ABP CLI commands, generate proxies, install libraries, or use ABP Suite. --- # ABP CLI Commands diff --git a/.claude/skills/abp-core/SKILL.md b/.claude/skills/abp-core/SKILL.md index 8f3c639f20..b1f7bca91b 100644 --- a/.claude/skills/abp-core/SKILL.md +++ b/.claude/skills/abp-core/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-core -description: Core ABP Framework conventions - module system, dependency injection, base classes, async patterns, time handling, business exceptions, localization. Use when working on any ABP project or when the user asks about ABP fundamentals. +description: Core ABP Framework conventions - module system, DI registration, base classes (ApplicationService, DomainService), IClock, BusinessException, localization, async patterns. Use when working on any ABP project, asking about ABP fundamentals, or unsure which skill applies. --- # ABP Core Conventions @@ -8,6 +8,14 @@ description: Core ABP Framework conventions - module system, dependency injectio > **Documentation**: https://abp.io/docs/latest > **API Reference**: https://abp.io/docs/api/ +## Key Rules + +- Use `IClock` / `Clock.Now` instead of `DateTime.Now` / `DateTime.UtcNow` +- Use `ITransientDependency` / `ISingletonDependency` instead of `AddScoped/AddTransient/AddSingleton` +- Use `IRepository` instead of injecting `DbContext` directly +- Check base class properties (`Clock`, `CurrentUser`, `GuidGenerator`, `L`) before injecting services +- Use `BusinessException` with namespaced error codes for domain rule violations + ## Module System Every ABP application/module has a module class that configures services: diff --git a/.claude/skills/abp-ddd/SKILL.md b/.claude/skills/abp-ddd/SKILL.md index a3dd5d91f3..885324130d 100644 --- a/.claude/skills/abp-ddd/SKILL.md +++ b/.claude/skills/abp-ddd/SKILL.md @@ -1,12 +1,20 @@ --- name: abp-ddd -description: ABP DDD patterns - Entities, Aggregate Roots, Repositories, Domain Services, Domain Events, Specifications. Use when designing domain layer, creating entities, repositories, or domain services in ABP projects. +description: ABP DDD patterns - Entities, Aggregate Roots, value objects, Repositories, Domain Services, Domain Events, Specifications. Use when designing domain layer, creating entities, repositories, or domain services in ABP projects. --- # ABP DDD Patterns > **Docs**: https://abp.io/docs/latest/framework/architecture/domain-driven-design +## Anti-Patterns to Avoid + +- **Anemic entities**: public setters with no behavior — use private setters + methods that enforce invariants +- **Repository for child entities**: only aggregate roots get repositories — access child entities through their root +- **Generating GUID in entity constructor**: use `IGuidGenerator` from outside and pass `id` parameter +- **Navigation properties to other aggregates**: reference by `Id` only, never add full navigation properties across aggregates +- **Domain service depending on current user**: accept values from the application layer instead + ## Rich Domain Model vs Anemic Domain Model ABP promotes **Rich Domain Model** pattern where entities contain both data AND behavior: diff --git a/.claude/skills/abp-dependency-rules/SKILL.md b/.claude/skills/abp-dependency-rules/SKILL.md index 748aabe0af..025e6b707f 100644 --- a/.claude/skills/abp-dependency-rules/SKILL.md +++ b/.claude/skills/abp-dependency-rules/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-dependency-rules -description: ABP layer dependency rules and project structure guardrails - correct dependency directions, repository pattern enforcement, multi-application scenarios. Use when reviewing project structure, adding new projects, or checking if dependencies are correct. +description: ABP project layer dependency rules - which projects can reference which, domain/application/infrastructure separation, cross-layer violations to avoid. Use when reviewing project structure, adding new project references, or checking if a dependency direction is correct. --- # ABP Dependency Rules diff --git a/.claude/skills/abp-development-flow/SKILL.md b/.claude/skills/abp-development-flow/SKILL.md index ec40b92457..ad6abe3373 100644 --- a/.claude/skills/abp-development-flow/SKILL.md +++ b/.claude/skills/abp-development-flow/SKILL.md @@ -100,17 +100,7 @@ public class BookRepository : EfCoreRepository, IBookRe ``` ### 5. Run Migration -```bash -cd src/MyProject.EntityFrameworkCore - -# Add migration -dotnet ef migrations add Added_Book - -# Apply migration (choose one): -dotnet run --project ../MyProject.DbMigrator # Recommended - also seeds data -# OR -dotnet ef database update # EF Core command only -``` +See `abp-ef-core` skill for migration commands. Recommended: use `DbMigrator` project to apply migrations and seed data. ### 6. Application.Contracts Create DTOs and service interface: @@ -254,25 +244,6 @@ public class BookAppService_Tests : MyProjectApplicationTestBase } ``` -## Quick Reference Commands - -### Build Solution -```bash -dotnet build -``` - -### Run Migrations -```bash -cd src/MyProject.EntityFrameworkCore -dotnet ef migrations add MigrationName -dotnet run --project ../MyProject.DbMigrator # Apply migration + seed data -``` - -### Generate Angular Proxies -```bash -abp generate-proxy -t ng -``` - ## Checklist for New Features - [ ] Entity created with proper constructors diff --git a/.claude/skills/abp-ef-core/SKILL.md b/.claude/skills/abp-ef-core/SKILL.md index e4b5b7a54e..d255042b83 100644 --- a/.claude/skills/abp-ef-core/SKILL.md +++ b/.claude/skills/abp-ef-core/SKILL.md @@ -1,12 +1,21 @@ --- name: abp-ef-core -description: ABP Entity Framework Core patterns - DbContext configuration, entity configuration, repository implementation, migrations, data seeding. Use when working in EntityFrameworkCore projects or with EF Core repositories. +description: ABP Entity Framework Core - DbContext, entity configuration, EfCoreRepository implementation, migrations (dotnet ef migrations add), data seeding. Use when working in EntityFrameworkCore projects, adding migrations, or implementing EF Core repositories. --- # ABP Entity Framework Core > **Docs**: https://abp.io/docs/latest/framework/data/entity-framework-core +## Never Do + +| Don't | Do Instead | +|-------|-----------| +| Skip `b.ConfigureByConvention()` | Always call it first in entity config | +| `AddDefaultRepositories(includeAllEntities: true)` | Use `AddDefaultRepositories()` only for aggregate roots | +| Inject `DbContext` in application/domain services | Use `IRepository` or custom repository interface | +| Use `DbContext` directly outside the EF Core project | Access via `GetDbContextAsync()` inside repository only | + ## DbContext Configuration ```csharp diff --git a/.claude/skills/abp-infrastructure/SKILL.md b/.claude/skills/abp-infrastructure/SKILL.md index a813862b6d..3d48675bfc 100644 --- a/.claude/skills/abp-infrastructure/SKILL.md +++ b/.claude/skills/abp-infrastructure/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-infrastructure -description: ABP infrastructure services - Settings, Features, Distributed Caching, Event Bus (local and distributed), Background Jobs, Localization. Use when working with settings, feature flags, caching, events, or background jobs in ABP. +description: ABP infrastructure services - ISettingProvider, IFeatureChecker, IDistributedCache, ILocalEventBus, IDistributedEventBus, IBackgroundJobManager, localization resource. Use when working with settings, feature flags, caching, event bus, or background jobs in ABP. --- # ABP Infrastructure Services diff --git a/.claude/skills/abp-microservice/SKILL.md b/.claude/skills/abp-microservice/SKILL.md index 69aae90ce2..e122789728 100644 --- a/.claude/skills/abp-microservice/SKILL.md +++ b/.claude/skills/abp-microservice/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-microservice -description: ABP Microservice solution template patterns - solution structure, inter-service communication via Integration Services, distributed events, entity cache, pre-configured infrastructure. Use when working with the microservice solution template. +description: ABP Microservice solution template - service structure, Integration Services ([IntegrationService]), inter-service HTTP proxies, distributed events with Outbox/Inbox, Entity Cache, RabbitMQ/Redis/YARP setup. Use when working with the ABP microservice solution template or inter-service communication patterns. --- # ABP Microservice Solution Template diff --git a/.claude/skills/abp-module/SKILL.md b/.claude/skills/abp-module/SKILL.md index feb1d35801..def061f3cb 100644 --- a/.claude/skills/abp-module/SKILL.md +++ b/.claude/skills/abp-module/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-module -description: ABP Module solution template patterns - reusable module structure, database independence (EF Core + MongoDB), virtual methods for extensibility, module options, entity extension, localization. Use when building reusable ABP modules. +description: ABP reusable Module solution template - EF Core + MongoDB dual support, virtual methods for extensibility, DbTablePrefix, module options pattern, entity extension, separate connection string. Use when building or reviewing reusable ABP modules that will be distributed or consumed by other solutions. --- # ABP Module Solution Template diff --git a/.claude/skills/abp-mongodb/SKILL.md b/.claude/skills/abp-mongodb/SKILL.md index b61c161e89..42ef94517c 100644 --- a/.claude/skills/abp-mongodb/SKILL.md +++ b/.claude/skills/abp-mongodb/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-mongodb -description: ABP MongoDB patterns - MongoDbContext configuration, entity configuration, repository implementation, indexing. Use when working in MongoDB projects or with MongoDB repositories in ABP. +description: ABP MongoDB patterns - AbpMongoDbContext, IMongoCollection, MongoDbRepository, no migrations, embedded documents vs references, manual UpdateAsync required. Use when working in MongoDB projects or implementing MongoDB repositories in ABP. --- # ABP MongoDB diff --git a/.claude/skills/abp-multi-tenancy/SKILL.md b/.claude/skills/abp-multi-tenancy/SKILL.md index 428aefc8ed..1e2cf95e22 100644 --- a/.claude/skills/abp-multi-tenancy/SKILL.md +++ b/.claude/skills/abp-multi-tenancy/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-multi-tenancy -description: ABP Multi-Tenancy patterns - tenant-aware entities, data isolation, switching tenant context, disabling multi-tenant filters, tenant resolution. Use when working with multi-tenant features, tenant-specific data, or tenant isolation. +description: ABP Multi-Tenancy - IMultiTenant interface, CurrentTenant, CurrentTenant.Change(), DataFilter.Disable(), tenant resolution order, database-per-tenant. Use when working with multi-tenant features, tenant-specific data isolation, or switching tenant context. --- # ABP Multi-Tenancy diff --git a/.claude/skills/abp-mvc/SKILL.md b/.claude/skills/abp-mvc/SKILL.md index d1daff0e6c..f7e4cc0bff 100644 --- a/.claude/skills/abp-mvc/SKILL.md +++ b/.claude/skills/abp-mvc/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-mvc -description: ABP MVC and Razor Pages UI patterns - page models, tag helpers, JavaScript API, DataTables integration, modal pages, bundle/minification. Use when working on MVC or Razor Pages UI in ABP projects. +description: ABP MVC and Razor Pages UI - AbpPageModel, abp tag helpers (abp-card, abp-dynamic-form, abp-modal), JavaScript abp.ajax/abp.auth/abp.notify, DataTables integration, bundle/minification. Use when working on MVC or Razor Pages UI in ABP projects. --- # ABP MVC / Razor Pages UI diff --git a/.claude/skills/abp-testing/SKILL.md b/.claude/skills/abp-testing/SKILL.md index eea14355e0..bd41ef4a32 100644 --- a/.claude/skills/abp-testing/SKILL.md +++ b/.claude/skills/abp-testing/SKILL.md @@ -1,6 +1,6 @@ --- name: abp-testing -description: ABP testing patterns - integration tests, application service tests, domain service tests, test data seeding, Shouldly assertions, mocking, multi-tenancy testing. Use when writing or reviewing tests in ABP projects. +description: ABP testing patterns - integration tests over unit tests, GetRequiredService, IDataSeedContributor, Shouldly assertions, AddAlwaysAllowAuthorization, NSubstitute mocking, WithUnitOfWorkAsync. Use when writing or reviewing tests for application services, domain services, or repositories in ABP projects. --- # ABP Testing Patterns