AI Rules & Guidelines

Overview

TurboStack includes a comprehensive .ai/rules/ directory containing development guidelines that help AI coding assistants (like GitHub Copilot, Cursor, Windsurf, Claude) understand your project’s patterns and conventions.

Why AI Rules? These guidelines ensure that AI assistants generate code that matches your project’s architecture, coding style, and best practices automatically.

📁 Available Rules Files

Core Guidelines

backend.md

Complete backend development guide for Elysia.js, routes, services, and authentication

frontend.md

Frontend patterns for Next.js 16, React Server Components, and Zustand

docs.md

Mintlify documentation writing standards and MDX components

database.md

Prisma ORM patterns, schema design, and migrations

Specialized Guidelines

media.md

Media upload service with provider pattern (UploadThing, Cloudinary)

security.md

Security best practices, authentication, and authorization

api-response-format.md

Standardized API response structure

email-templates.md

React Email template development guide

swagger.md

OpenAPI/Swagger documentation standards

clean-code.md

Clean code principles and best practices

🤖 How AI Assistants Use These Rules

When you ask an AI assistant to help with your code, it automatically reads the relevant .ai/rules/ files to:

Understand your architecture - Routes, services, database patterns
Follow your conventions - Naming, file structure, import paths
Match your coding style - TypeScript patterns, error handling
Use the right tools - Correct libraries and frameworks
Generate consistent code - Same patterns across the codebase

Example: Adding a New API Endpoint

Without AI Rules:

// AI might generate inconsistent code
app.get("/api/products", (req, res) => {
  const products = await db.products.findAll();
  res.json(products); // ❌ No standard response format
});

With AI Rules (backend.md):

// AI generates code following your patterns
export const productRoutes = new Elysia({ prefix: "/products" }).get(
  "/",
  async () => {
    const products = await productService.getAll();
    return { success: true, data: products }; // ✅ Standard format
  },
  {
    detail: {
      tags: ["Products"],
      summary: "List all products",
      // ✅ Auto-includes Swagger docs
    },
  },
);

📖 Using AI Rules in Your IDE

GitHub Copilot / VS Code

Enable Workspace Instructions

Copilot automatically reads .ai/rules/ when you reference specific files or patterns.

Reference Rules in Comments

// Following backend.md patterns for route creation
export const userRoutes = new Elysia({ prefix: "/users" })

Ask Specific Questions

“Create a new route following backend.md guidelines”
“Add Swagger docs as described in backend.md”
“Follow the media.md provider pattern”

Cursor IDE

Configure Rules Directory

Cursor automatically detects .ai/rules/ and .cursor/rules/ directories.

Reference in Chat

Use @rules or mention specific files: - “@backend.md create a new products endpoint” - “@frontend.md add a server component”

Apply to Current File

Cursor applies relevant rules based on your current file location automatically.

Windsurf

Auto-Detection

Windsurf reads .windsurfrules which references .ai/rules/.

Contextual Suggestions

Suggestions automatically follow your project’s patterns from the rules.

🎯 Quick Reference by Task

Creating Backend API Endpoints

Primary File: .ai/rules/backend.mdWhat You’ll Learn:

Elysia.js route patterns
Service layer architecture
Swagger/OpenAPI documentation
Authentication with Better-auth
Rate limiting
Error handling

Example Request:

“Create a new products API endpoint with CRUD operations following backend.md”

Building Frontend Components

Primary File: .ai/rules/frontend.mdWhat You’ll Learn:

Next.js 16 App Router patterns
Server vs Client Components
Zustand state management
shadcn/ui component usage
Form handling with React Hook Form

Example Request:

“Create a dashboard page following frontend.md patterns with server components”

Working with Database

Primary File: .ai/rules/database.mdWhat You’ll Learn:

Prisma schema patterns
Creating migrations
Query optimization
Relation handling

Example Request:

“Add a products table to the schema following database.md conventions”

Writing Documentation

Primary File: .ai/rules/docs.mdWhat You’ll Learn:

Mintlify MDX format
Component usage (Cards, Tabs, Steps)
Frontmatter structure
Code examples

Example Request:

“Create documentation for the products API following docs.md guidelines”

Implementing File Uploads

Primary File: .ai/rules/media.mdWhat You’ll Learn:

Provider pattern implementation
UploadThing integration
Cloudinary integration
Media transformations

Example Request:

“Implement image upload using the provider pattern from media.md”

Security Implementation

Primary File: .ai/rules/security.mdWhat You’ll Learn:

Authentication patterns
Authorization middleware
Input validation
Data sanitization

Example Request:

“Add role-based access control following security.md”

💡 Best Practices for Working with AI Rules

✅ DO

Be Specific

Reference exact rule files in your requests: - “Following backend.md, create…” - “Using patterns from frontend.md…”

Check Generated Code

Always review AI-generated code to ensure it matches the rules and your needs.

Update Rules

When you change patterns, update the corresponding .ai/rules/ file so future generations stay consistent.

Provide Context

Include the current file path or feature you’re working on for better context.

❌ DON’T

Don’t blindly accept AI suggestions without understanding them - Don’t skip reading the rules files yourself - they’re valuable documentation - Don’t forget to update rules when you change project patterns - Don’t ignore validation - AI can make mistakes

🔄 Keeping Rules Updated

The AI rules are living documents that should evolve with your project:

After Major Changes

When you refactor architecture or change patterns, update the relevant .ai/rules/ file.

Document New Patterns

If you create a new pattern (like a new service structure), add it to the rules.

Review Periodically

Every few months, review rules files to ensure they match your current codebase.

Team Alignment

Make sure all team members know about and follow the rules files.

📚 Complete Rules Index

File	Purpose	When to Use
`backend.md`	Backend API development	Creating routes, services, authentication
`frontend.md`	Frontend UI development	Building pages, components, forms
`docs.md`	Documentation writing	Adding MDX documentation
`database.md`	Database patterns	Schema changes, migrations, queries
`media.md`	Media/upload service	File uploads, image handling
`security.md`	Security practices	Auth, validation, permissions
`api-response-format.md`	API response structure	Standardizing API responses
`email-templates.md`	Email templates	Creating React Email templates
`swagger.md`	OpenAPI docs	API documentation
`clean-code.md`	Code quality	General coding standards
`structure.md`	Project structure	Understanding monorepo layout
`technologies.md`	Tech stack	Technology choices and versions
`path-aliases.md`	Import paths	Using `@/` path aliases

🎓 Example Workflows

Workflow 1: Adding a New Feature

Read relevant rule file (e.g., backend.md)
Ask AI: "Following backend.md, create a products API with CRUD operations"
AI generates routes, services, and Swagger docs
Review and test generated code
Commit changes

Workflow 2: Fixing a Bug

Identify the layer (route, service, database)
Reference appropriate rule file
Ask AI: "Fix this validation error following backend.md patterns"
AI suggests fix matching project conventions
Apply and test

Workflow 3: Refactoring

Update the relevant .ai/rules/ file with new pattern
Ask AI: "Refactor this code to match updated backend.md"
AI refactors using new conventions
Update other files consistently

🔗 IDE-Specific Configurations

Cursor
GitHub Copilot
Windsurf
Claude/Agent

Cursor reads from .cursor/rules/*.mdc which links to .ai/rules/. Usage: - @backend.md in chat - Auto-applies rules to current file

Copilot uses .github/copilot-instructions.md which references .ai/rules/. Usage: - Comment references: // Following backend.md - Chat: “Use backend.md patterns”

Windsurf reads .windsurfrules with symlinks to .ai/rules/. Usage: - Automatic context from file location - Mention rule names in requests

Agents read directly from .ai/rules/ and .agent/rules/. Usage: - Include #file:.ai/rules/backend.md in prompts - Reference specific sections

🚀 Getting Started

Browse the Rules

Explore the .ai/rules/ directory to see what’s available.

Read Relevant Files

Read the rules files relevant to your current task.

Reference in AI Requests

Mention specific rule files when asking AI for help.

Verify Generated Code

Always review and test AI-generated code before committing.

Project Structure - Overall monorepo organization
Backend Guidelines - Elysia.js framework overview
Frontend Guidelines - Next.js App Router overview
Database Schema - Prisma schema reference

Pro Tip: The more specific you are when referencing rules files, the better the AI-generated code will match your project’s patterns!

Getting Started

Backend

Database

Frontend

Deployment

Bugs & Errors

Clean Code

​Overview

​📁 Available Rules Files

​Core Guidelines

backend.md

frontend.md

docs.md

database.md

​Specialized Guidelines

media.md

security.md

api-response-format.md

email-templates.md

swagger.md

clean-code.md

​🤖 How AI Assistants Use These Rules

​Example: Adding a New API Endpoint

​📖 Using AI Rules in Your IDE

​GitHub Copilot / VS Code

​Cursor IDE

​Windsurf

​🎯 Quick Reference by Task

​💡 Best Practices for Working with AI Rules

​✅ DO

Be Specific

Check Generated Code

Update Rules

Provide Context

​❌ DON’T

​🔄 Keeping Rules Updated

​📚 Complete Rules Index

​🎓 Example Workflows

​Workflow 1: Adding a New Feature

​Workflow 2: Fixing a Bug

​Workflow 3: Refactoring

​🔗 IDE-Specific Configurations

​🚀 Getting Started

​📖 Related Documentation

Overview

📁 Available Rules Files

Core Guidelines

Specialized Guidelines

🤖 How AI Assistants Use These Rules

Example: Adding a New API Endpoint

📖 Using AI Rules in Your IDE

GitHub Copilot / VS Code

Cursor IDE

Windsurf

🎯 Quick Reference by Task

💡 Best Practices for Working with AI Rules

✅ DO

❌ DON’T

🔄 Keeping Rules Updated

📚 Complete Rules Index

🎓 Example Workflows

Workflow 1: Adding a New Feature

Workflow 2: Fixing a Bug

Workflow 3: Refactoring

🔗 IDE-Specific Configurations

🚀 Getting Started

📖 Related Documentation