abp/ai-rules/README.md

ABP AI Rules

This folder contains AI rules (Cursor .mdc format) for ABP based solutions. These rules help AI assistants understand ABP-specific patterns, conventions, and best practices when working with ABP-based applications.

Purpose

This folder serves as a central repository for ABP-specific AI rules. The community can contribute, improve, and maintain these rules collaboratively.

When you create a new ABP solution, these rules are included in your project based on your configuration. This provides AI assistants with ABP-specific context, helping them generate code that follows ABP conventions.

Important: These rules are ABP-specific. They don't cover general .NET or ASP.NET Core patterns—AI assistants already know those. Instead, they focus on ABP's unique architecture, module system, and conventions.

How Rules Work

Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level.

When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.

Mini Glossary (ABP Terms)

• Application service: Use-case orchestration (ABP’s primary “business API” surface). Usually exposed remotely via Auto API Controllers or explicit controllers.
• Auto API Controllers: ABP can auto-generate HTTP endpoints from IApplicationService contracts.
• Client proxy: Generated client-side code (Angular/JS/C#) to call remote application services.
• Integration service (microservices): Application-service-like contract intended for service-to-service communication; typically exposed separately and consumed via generated C# proxies.
• Domain vs Application: Domain holds business rules/invariants; Application coordinates domain + infrastructure and returns DTOs.

File Structure

ai-rules/
├── README.md
├── common/                       # Rules for all ABP projects
│   ├── abp-core.mdc             # Core ABP conventions (alwaysApply: true)
│   ├── ddd-patterns.mdc         # DDD patterns (Entity, AggregateRoot, Repository)
│   ├── application-layer.mdc    # Application services, DTOs, validation
│   ├── authorization.mdc        # Permissions and authorization
│   ├── multi-tenancy.mdc        # Multi-tenant entities and data isolation
│   ├── infrastructure.mdc       # Settings, Features, Caching, Events, Jobs
│   ├── dependency-rules.mdc     # Layer dependencies and guardrails
│   ├── development-flow.mdc     # Development workflow
│   └── cli-commands.mdc         # ABP CLI commands reference
├── ui/                          # UI-specific rules (applied by globs)
│   ├── blazor.mdc              # Blazor UI patterns
│   ├── angular.mdc             # Angular UI patterns
│   └── mvc.mdc                 # MVC/Razor Pages patterns
├── data/                        # Data layer rules (applied by globs)
│   ├── ef-core.mdc             # Entity Framework Core patterns
│   └── mongodb.mdc             # MongoDB patterns
├── testing/                     # Testing rules
│   └── patterns.mdc            # Unit and integration test patterns
└── template-specific/           # Template-specific rules
    ├── app-nolayers.mdc        # Single-layer app template
    ├── module.mdc              # Module template
    └── microservice.mdc        # Microservice template

Rule Format

Each rule is a markdown file with frontmatter metadata:

---
description: "Describes when this rule should apply - used by AI to decide relevance"
globs: "src/**/*.cs"
alwaysApply: false
---

# Rule Title

Your rule content here...

Frontmatter Properties

Property	Description
description	Brief description of what the rule covers. Used by AI to determine relevance.
globs	File patterns that trigger this rule (e.g., **/*.cs, *.Domain/**).
alwaysApply	If true, rule is always included. If false, AI decides based on context.

Rule Types

Type	When Applied
Always Apply	Every chat session (alwaysApply: true)
Apply Intelligently	When AI decides it's relevant based on description
Apply to Specific Files	When file matches globs pattern
Apply Manually	When @-mentioned in chat (e.g., @my-rule)

Rule Categories

Common Rules

Core ABP patterns that apply to all DDD-based templates (app, module, microservice):

• abp-core.mdc - Always applied, covers module system, DI conventions, base classes
• ddd-patterns.mdc - Entity, AggregateRoot, Repository, Domain Services
• application-layer.mdc - Application services, DTOs, validation, error handling
• authorization.mdc - Permission system and authorization
• infrastructure.mdc - Settings, Features, Caching, Events, Background Jobs
• dependency-rules.mdc - Layer dependencies and project structure
• development-flow.mdc - Development workflow for adding features

UI Rules (Applied by Globs)

• blazor.mdc - Applied to **/*.razor, **/Blazor/**/*.cs
• angular.mdc - Applied to **/angular/**/*.ts
• mvc.mdc - Applied to **/*.cshtml, **/Pages/**/*.cs

Data Rules (Applied by Globs)

• ef-core.mdc - Applied to **/*.EntityFrameworkCore/**/*.cs
• mongodb.mdc - Applied to **/*.MongoDB/**/*.cs

Template-Specific Rules

• app-nolayers.mdc - For single-layer web application template
• module.mdc - For reusable module template
• microservice.mdc - For microservice template

Best Practices

Good rules are focused, actionable, and scoped:

• Keep rules under 500 lines - Split large rules into multiple, composable rules
• Provide concrete examples - Reference actual files or include code snippets
• Be specific, not vague - Write rules like clear internal documentation
• Reference files instead of copying - This keeps rules short and prevents staleness
• Start simple - Add rules only when you notice AI making the same mistake repeatedly

What to Avoid

• Copying entire style guides: Use a linter instead. AI already knows common style conventions.
• Documenting every possible command: AI knows common tools like dotnet and npm.
• Adding instructions for edge cases that rarely apply: Keep rules focused on patterns you use frequently.
• Duplicating what's already in your codebase: Point to canonical examples instead of copying code.
• Including non-ABP patterns: Don't add generic .NET/ASP.NET Core guidance—focus on ABP-specific conventions.

Contributing

We welcome community contributions to improve these rules! You can open a PR to add new rules or improve existing ones.

Please review our Contribution Guide and Code of Conduct before contributing.

Contribution Guidelines

• Each rule should focus on a single ABP concept or pattern
• Use clear, actionable language
• Include examples where helpful
• Test your rules by using them in a real ABP project
• Keep ABP-specific focus—don't add general .NET patterns

Related Resources

• Cursor Rules Documentation
• ABP Framework Documentation