AI Agents Integration

AI Development Philosophy

• Structured Guidelines: Every architectural decision is codified in rules that AI agents can understand and follow
• Intelligent Code Generation: AI agents generate code that matches existing patterns and conventions
• Consistent Quality: Rules ensure AI-generated code meets the same standards as human-written code
• Accelerated Development: Complex features can be implemented rapidly while maintaining architectural integrity

Agent Configuration System

CLAUDE.md - Claude Code Integration

# Start development servers
pnpm dev              # Blog app (default)
pnpm devcodemail      # CodeMail app
pnpm devlanding       # Landing pages
pnpm devurl           # URL shortener
pnpm devship          # ShipSaaS app

# Build applications
pnpm build            # Build selected apps
pnpm build-all        # Build all apps
pnpm build-packages   # Build shared packages

# Testing & Quality
pnpm test             # Run tests
pnpm lint             # Run linting
pnpm format:fix       # Fix formatting

# Database operations
pnpm db:generate      # Generate migrations
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Drizzle Studio

AGENTS.md - Multi-Agent Guidelines

• Read guardrails in CLAUDE.md and .cursor/rules/
• Follow stricter guidance when conflicts arise
• Maintain architectural consistency
• Use established patterns and conventions

• apps/*: Customer-facing Next.js applications
• packages/*: Shared logic and utilities
• Proper workspace organization
• Clear separation of concerns

Cursor Rules - Specialized Guidelines

AI-Generated Code Quality

Architectural Consistency

// AI generates services following established patterns
export class UserService {
  async createUser(data: CreateUserInput): Promise<User> {
    // Validation
    const validatedData = createUserSchema.parse(data)

    // Authorization check
    await this.authService.requirePermission('user:create')

    // Business logic
    return this.userRepository.create(validatedData)
  }
}

// AI follows established type patterns
interface CreateUserInput {
  email: string
  name: string
  role: UserRole
}

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
  role: z.nativeEnum(UserRole)
})

// AI generates tests matching patterns
describe('UserService', () => {
  it('should create user with proper authorization', async () => {
    // Follows established testing patterns
    const mockUser = createMockUser()
    mockAuthService.requirePermission.mockResolvedValue(true)

    const result = await userService.createUser(mockUser)
    expect(result).toMatchObject(mockUser)
  })
})

Code Generation Standards

• Security First: All operations include proper authorization checks
• Error Handling: Comprehensive error handling with custom error classes
• Performance: Optimized database queries and caching strategies
• Maintainability: Clear, self-documenting code with proper abstractions
• Testing: Full test coverage following established patterns

Working with AI Agents

Best Practices

1. Define Requirements: Clearly specify what you want to build
2. Reference Patterns: Point to similar existing features
3. Let AI Generate: Allow agents to create code following established rules
4. Review & Iterate: Make adjustments while maintaining architectural consistency

"Create a subscription management service following the existing service patterns,
with RBAC authorization, Zod validation, and comprehensive tests"

"Add a new email notification type for subscription renewals,
following the existing email templates structure"

"Implement a new dashboard widget for user analytics,
following the existing widget patterns in the dashboard"

Rule-Based Development

Documentation Generation

• Follows established MDX patterns
• Uses proper component syntax (Callout, Steps, Tabs)
• Documents actual boilerplate functionality
• Maintains consistency across sections
• Provides practical, actionable guidance

Benefits of AI Integration

Development Acceleration

• Rapid Prototyping: New features can be implemented in minutes
• Consistent Quality: AI follows established patterns automatically
• Reduced Boilerplate: Repetitive code is generated following templates
• Comprehensive Testing: Tests are generated alongside features

Architectural Integrity

• Pattern Consistency: All code follows the same architectural patterns
• Security Compliance: Authorization and validation are built-in
• Type Safety: TypeScript patterns are maintained automatically
• Best Practices: Industry standards are enforced through rules

Knowledge Preservation

• Codified Decisions: Architectural decisions are preserved in rules
• Transferable Knowledge: New team members can leverage AI guidance
• Evolution Friendly: Rules can be updated as patterns evolve
• Documentation Sync: Code and documentation stay aligned