cursor-rust-rules/README.md

🦀 Cursor Rust Rules

Production-tested Rust coding standards and best practices for Cursor IDE

A comprehensive collection of Rust development rules designed for use with Cursor IDE, providing opinionated guidelines for building production-ready Rust applications with modern patterns and industry best practices.

✨ Features

• 🏗️ Modern Architecture Patterns - Domain-driven design, subsystem organization, and clean architecture
• 🌐 Web Development Standards - Axum web framework, OpenAPI integration, authentication patterns
• 🗄️ Database Best Practices - SQLx patterns, migrations, connection pooling, and repository patterns
• ⚡ Async & Concurrency - Tokio patterns, async/await best practices, and concurrent data structures
• 🛠️ Utility Libraries - JWT authentication, CLI development, HTTP clients, and more
• 📦 Workspace Organization - Multi-crate workspace structure with clear subsystem boundaries
• 🔍 Code Quality - Comprehensive linting, error handling, testing, and documentation standards

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/your-username/cursor-rust-rules.git
cd cursor-rust-rules

2. Set Up Cursor Rules

Copy the rules to your Cursor configuration:

# Create cursor rules directory if it doesn't exist
mkdir -p ~/.cursor/rules/rust

# Copy all rules
cp -r .cursor/rules/rust/* ~/.cursor/rules/rust/

3. Use in Your Rust Project

In your Rust project, create or update .cursorrules:

# .cursorrules
rules:
  - "@rust/main"          # Core Rust standards
  - "@rust/axum"          # Web development with Axum
  - "@rust/database"      # Database patterns with SQLx
  - "@rust/concurrency"   # Async and concurrency patterns
  - "@rust/utilities"     # Utility libraries and CLI tools
  - "@rust/workspace"     # Multi-crate workspace organization

Or for specific features only:

# .cursorrules - Minimal web API setup
rules:
  - "@rust/core/code-quality"
  - "@rust/features/axum"
  - "@rust/features/database"

📁 Project Structure

cursor-rust-rules/
├── .cursor/rules/rust/          # Cursor rule definitions
│   ├── main.mdc                 # Main rule loader and feature detection
│   ├── core/                    # Core standards
│   │   └── code-quality.mdc     # Code quality and best practices
│   ├── features/                # Feature-specific rules
│   │   ├── axum.mdc            # Web framework standards
│   │   ├── database.mdc        # Database patterns
│   │   ├── concurrency.mdc     # Async/concurrency patterns
│   │   ├── utilities.mdc       # Utility libraries
│   │   ├── http-client.mdc     # HTTP client patterns
│   │   └── tools-and-config.mdc # Development tools
│   └── complex/                 # Advanced patterns
│       └── workspace.mdc        # Multi-crate workspace organization
└── README.md                    # This file

🎯 Rule Categories

Core Standards

• Code Quality (@rust/core/code-quality) - Error handling, logging, testing, and code organization

Feature-Specific Rules

• Web Framework (@rust/features/axum) - Axum 0.8+, OpenAPI, middleware, authentication
• Database (@rust/features/database) - SQLx patterns, migrations, connection pooling
• Concurrency (@rust/features/concurrency) - Tokio, async patterns, concurrent data structures
• Utilities (@rust/features/utilities) - JWT, CLI tools, builder patterns, validation
• HTTP Client (@rust/features/http-client) - Reqwest patterns, retry logic, authentication
• Tools & Config (@rust/features/tools-and-config) - Development tooling and configuration

Advanced Patterns

• Workspace (@rust/complex/workspace) - Subsystem-based multi-crate organization

🛠️ Usage Examples

Web API Development

For building a web API with Axum:

// Cargo.toml gets configured with these dependencies
[dependencies]
axum = { version = "0.8", features = ["macros", "multipart", "ws"] }
utoipa = { version = "5.0", features = ["axum_extras", "chrono", "uuid"] }
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
tokio = { version = "1.45", features = ["macros", "rt-multi-thread"] }

Your project follows patterns like:

// AppState with hot-reloadable config
#[derive(Clone)]
pub struct AppState {
    pub config: Arc<ArcSwap<AppConfig>>,
    pub db: PgPool,
    pub http_client: reqwest::Client,
}

// Route handlers with OpenAPI documentation
#[utoipa::path(
    post,
    path = "/api/v1/users",
    request_body = CreateUserRequest,
    responses(
        (status = 201, description = "User created", body = User),
        (status = 400, description = "Validation error", body = ApiError)
    ),
    tag = "users"
)]
pub async fn create_user(
    State(state): State<AppState>,
    Json(request): Json<CreateUserRequest>,
) -> Result<(StatusCode, Json<User>), ApiError> {
    // Implementation follows validation and error handling patterns
}

Database Integration

For database operations with SQLx:

// Repository patterns with proper error handling
#[async_trait]
pub trait UserRepository: Send + Sync {
    async fn find_by_id(&self, id: UserId) -> Result<Option<User>, DatabaseError>;
    async fn create(&self, user: CreateUserRequest) -> Result<User, DatabaseError>;
    async fn update(&self, id: UserId, user: UpdateUserRequest) -> Result<User, DatabaseError>;
}

// Migration and connection management
pub async fn setup_database(config: &DatabaseConfig) -> Result<PgPool, DatabaseError> {
    let pool = PgPoolOptions::new()
        .max_connections(config.max_connections)
        .connect(&config.url)
        .await?;

    sqlx::migrate!("./migrations").run(&pool).await?;
    Ok(pool)
}

Multi-Crate Workspace

For complex applications, organize as subsystems:

my-ecommerce-platform/
├── shared/                      # Cross-cutting infrastructure
│   ├── shared-types/           # Domain primitives
│   ├── shared-db/              # Database infrastructure
│   └── shared-events/          # Event definitions
├── subsystems/                 # Business subsystems
│   ├── user-management/        # User & auth subsystem
│   ├── product-catalog/        # Product management
│   ├── order-management/       # Order processing
│   └── payment/                # Payment processing
└── services/                   # Infrastructure services
    ├── api-gateway/            # Unified API
    └── admin-cli/              # Admin tools

🎮 Interactive Features

The rules provide intelligent feature detection and suggestions:

Automatic Dependency Detection

When you use certain patterns, Cursor will suggest appropriate dependencies:

// Using async patterns triggers Tokio suggestions
async fn my_function() -> Result<(), Error> {
    // Cursor suggests: Add tokio = "1.45" with appropriate features
}

// Using database patterns triggers SQLx suggestions
sqlx::query!("SELECT * FROM users")
    // Cursor suggests: Add sqlx with postgres features

Smart Code Generation

Rules include templates for common patterns:

• API Endpoints - Complete handler with validation and OpenAPI docs
• Database Repositories - Repository trait and implementation
• Error Types - Structured error handling with proper HTTP status codes
• Configuration - Environment-based config with hot reload support

📊 Rule Hierarchy

Rules are loaded based on project complexity:

1. Simple Projects - Core quality standards only
2. Web APIs - Core + Axum + Database rules
3. Complex Systems - All rules including workspace organization

🔧 Customization

Override Specific Rules

Create a local .cursorrules file to customize:

rules:
  - "@rust/main"

overrides:
  # Use different web framework
  web_framework: "warp"

  # Custom database configuration
  database:
    orm: "diesel"
    features: ["mysql"]

Add Project-Specific Rules

Extend with your own patterns:

// .cursor/rules/rust/project/custom.mdc
// Your project-specific patterns and standards

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-rule)
3. Add your rule with documentation and examples
4. Test with real projects
5. Submit a pull request

Rule Writing Guidelines

• Comprehensive Examples - Show complete, working code
• Production Patterns - Based on real-world usage
• Clear Documentation - Explain why, not just what
• Test Coverage - Include testing patterns
• Version Compatibility - Specify crate versions

📚 References

• Axum Documentation
• SQLx Documentation
• Tokio Documentation
• Rust API Guidelines

📄 License

MIT License - see LICENSE file for details.

🚨 Disclaimer

These rules represent opinionated best practices based on production experience. Adapt them to your specific project needs and constraints.

---

Happy Coding with Rust! 🦀