.cursorrules (deprecated)

1# Cursor Rules for Megarepo - AI Setup Repository
2 
3You are an expert AI developer working in the Megarepo, a comprehensive AI setup repository designed for AI-related projects. Follow these rules when assisting with code development, analysis, and project setup.
4 
5## Repository Overview
6 
7This is a minimal AI setup repository template configured for Node.js/Next.js development. The repository serves as a foundation for AI-related projects and contains basic setup files with comprehensive development guidelines.
8 
9**Current State**: Minimal setup with basic configuration files
10- Use these rules to guide development when source code is added
11- Follow Node.js/Next.js patterns and best practices
12- Prioritize AI-specific development patterns and security
13 
14## Core Development Principles
15 
16### 1. AI-First Development
17- Prioritize AI integration patterns and best practices
18- Consider model performance, API efficiency, and token usage
19- Implement proper error handling for AI service failures
20- Design for scalability with AI workloads
21 
22### 2. Security & API Key Management
23- **NEVER** commit API keys, secrets, or credentials to version control
24- Always use environment variables for sensitive data
25- Create `.env.example` files to document required environment variables
26- Implement proper API key rotation and management patterns
27- Use secure storage solutions for production deployments
28 
29### 3. Code Quality Standards
30- Write clean, readable, and well-documented code
31- Use TypeScript for type safety when applicable
32- Implement comprehensive error handling and logging
33- Follow established linting and formatting rules
34- Write meaningful commit messages and documentation
35 
36## Technology Stack Guidelines
37 
38### Node.js/Next.js Development
39- Follow Next.js 13+ App Router patterns when applicable
40- Use modern ES6+ JavaScript/TypeScript features
41- Implement proper async/await patterns for AI API calls
42- Use React Server Components where appropriate
43- Optimize for both development and production environments
44 
45### AI Integration Patterns
46```javascript
47// Preferred AI API integration pattern
48const aiResponse = await fetch('/api/ai-service', {
49  method: 'POST',
50  headers: {
51    'Content-Type': 'application/json',
52    'Authorization': `Bearer ${process.env.AI_API_KEY}`
53  },
54  body: JSON.stringify({ prompt, options })
55});
56 
57if (!aiResponse.ok) {
58  throw new Error(`AI service error: ${aiResponse.status}`);
59}
60```
61 
62### Common AI Dependencies
63When adding AI functionality, prefer these well-established packages:
64- `openai` - Official OpenAI API client
65- `@langchain/core` - LangChain framework
66- `@vercel/ai` - Vercel AI SDK
67- `@huggingface/inference` - Hugging Face API client
68 
69## File Structure and Organization
70 
71### Expected Project Structure
72```
73.
74├── README.md                 # Project documentation
75├── LICENSE                   # MIT license
76├── .gitignore               # Node.js/Next.js patterns
77├── .cursorrules             # This file
78├── .env.example             # Environment variable template
79├── package.json             # Dependencies and scripts
80├── next.config.js           # Next.js configuration
81├── tsconfig.json            # TypeScript configuration
82├── src/
83│   ├── app/                 # Next.js app directory
84│   ├── components/          # React components
85│   ├── lib/                 # Utility functions and AI clients
86│   ├── types/               # TypeScript type definitions
87│   └── utils/               # Helper functions
88├── public/                  # Static assets
89└── docs/                    # Additional documentation
90```
91 
92### Key Directories
93- `src/lib/` - Place AI client configurations and utilities here
94- `src/components/` - Reusable UI components, including AI-powered components
95- `src/app/api/` - API routes for AI services and integrations
96- `src/types/` - TypeScript definitions for AI responses and data models
97 
98## Development Workflow
99 
100### Before Writing Code
1011. Check if `package.json` exists before running npm commands
1022. Review existing environment variable requirements
1033. Understand the AI service integrations being used
1044. Consider rate limiting and usage patterns
105 
106### Code Development
1071. Write TypeScript definitions for AI API responses
1082. Implement proper error handling for AI service failures
1093. Add loading states and user feedback for AI operations
1104. Consider performance implications of AI API calls
1115. Implement caching strategies where appropriate
112 
113### Testing AI Components
114```javascript
115// Example AI component test pattern
116describe('AI Chat Component', () => {
117  it('handles API errors gracefully', async () => {
118    // Mock AI service failure
119    mockAIService.mockRejectedValue(new Error('API Error'));
120    
121    render(<ChatComponent />);
122    
123    // Test error handling and user feedback
124    expect(screen.getByText(/error/i)).toBeInTheDocument();
125  });
126});
127```
128 
129## Environment Setup
130 
131### Required Environment Variables
132Create `.env.local` with these patterns:
133```bash
134# AI Service Keys
135OPENAI_API_KEY=your_openai_key_here
136ANTHROPIC_API_KEY=your_anthropic_key_here
137 
138# Application Settings
139NEXT_PUBLIC_APP_URL=http://localhost:3000
140NODE_ENV=development
141 
142# Database (if needed)
143DATABASE_URL=your_database_url_here
144```
145 
146### Development Commands
147When `package.json` exists, use these commands:
148```bash
149npm install          # Install dependencies
150npm run dev          # Start development server
151npm run build        # Production build
152npm run test         # Run tests
153npm run lint         # Run linter
154npm run type-check   # TypeScript validation
155```
156 
157## AI-Specific Best Practices
158 
159### 1. Prompt Engineering
160- Store prompts in separate files or constants
161- Use template literals for dynamic prompt generation
162- Implement prompt versioning for A/B testing
163- Consider token limits and optimize prompt length
164 
165### 2. Response Handling
166- Always validate AI responses before using them
167- Implement fallback mechanisms for failed requests
168- Log AI interactions for debugging and monitoring
169- Handle streaming responses appropriately
170 
171### 3. Performance Optimization
172- Cache AI responses when appropriate
173- Implement request debouncing for user inputs
174- Use background processing for long-running AI tasks
175- Consider edge functions for AI API proxying
176 
177### 4. User Experience
178- Provide clear loading indicators for AI operations
179- Implement progressive disclosure for complex AI features
180- Give users control over AI behavior and settings
181- Provide feedback mechanisms for AI output quality
182 
183## Code Style and Formatting
184 
185### TypeScript Preferences
186- Use strict type checking
187- Define interfaces for all AI API responses
188- Use union types for AI model selections
189- Implement proper error type definitions
190 
191### React Patterns
192- Use functional components with hooks
193- Implement proper cleanup for AI subscriptions
194- Use React.memo for expensive AI-powered components
195- Handle loading and error states consistently
196 
197### API Development
198- Follow RESTful principles for AI service endpoints
199- Implement proper rate limiting and authentication
200- Use middleware for common AI service operations
201- Document API endpoints with clear examples
202 
203## Error Handling and Monitoring
204 
205### AI Service Errors
206```javascript
207// Comprehensive error handling pattern
208try {
209  const response = await aiClient.complete(prompt);
210  return response;
211} catch (error) {
212  if (error.code === 'rate_limit_exceeded') {
213    // Implement backoff strategy
214    await delay(exponentialBackoff(retryCount));
215    return retry();
216  } else if (error.code === 'insufficient_quota') {
217    // Handle quota issues
218    throw new QuotaExceededError('AI service quota exceeded');
219  } else {
220    // Log and handle unexpected errors
221    logger.error('AI service error', error);
222    throw new AIServiceError('Unexpected AI service error');
223  }
224}
225```
226 
227### Monitoring and Logging
228- Log AI API usage and costs
229- Monitor response times and error rates
230- Track user interactions with AI features
231- Implement health checks for AI services
232 
233## Documentation Requirements
234 
235### Code Documentation
236- Document all AI-related functions and components
237- Include usage examples for AI integrations
238- Explain prompt engineering decisions
239- Document environment setup requirements
240 
241### API Documentation
242- Document all AI service endpoints
243- Include request/response examples
244- Explain rate limiting and authentication
245- Provide troubleshooting guides
246 
247## Security Considerations
248 
249### Data Privacy
250- Avoid sending sensitive user data to AI services
251- Implement data anonymization where possible
252- Follow GDPR and privacy regulations
253- Document data usage and retention policies
254 
255### API Security
256- Validate all inputs before sending to AI services
257- Implement proper CORS settings
258- Use HTTPS for all AI API communications
259- Regularly rotate API keys and secrets
260 
261Remember: This repository is designed as a foundation for AI projects. Always consider the specific AI use case when implementing features, and prioritize user experience, security, and performance in all AI-related development.