Awesome Cursor Rules Collection

# iSuTech Coding Rules and Best Practices



## Table of Contents
1. [General Guidelines](#general-guidelines)
2. [Code Style](#code-style)
3. [React Best Practices](#react-best-practices)
4. [TypeScript Guidelines](#typescript-guidelines)
5. [State Management](#state-management)
6. [Testing](#testing)
7. [Performance](#performance)
8. [Security](#security)


<!-- > For a quick reference guide to these standards, see [@/Docs/QUICKREFERENCE.md](@/Docs/QUICKREFERENCE.md) -->


## General Guidelines

### File Organization
- One component per file
- Use meaningful file names that reflect the component's purpose
- Group related files in appropriate directories
- Maximum file size should not exceed 400 lines
- Keep components focused and single-responsibility

### Naming Conventions
- Use PascalCase for component names: `UserProfile.tsx`
- Use camelCase for file names of non-components: `useAuth.tsx`
- Use kebab-case for CSS files: `button-styles.css`
- Use descriptive names that indicate functionality

## Code Style

### Formatting
- Use 2 spaces for indentation
- Use semicolons at the end of statements
- Use single quotes for strings
- Add trailing commas in objects and arrays
- Maximum line length: 100 characters

### Comments
- Write self-documenting code
- Add comments for complex logic only
- Use JSDoc for component props and functions
- Keep comments up-to-date with code changes

## React Best Practices

### Components
- Use functional components with hooks
- Keep components small and focused
- Extract reusable logic into custom hooks
- Use proper prop typing with TypeScript
- Implement error boundaries for error handling

### Props
- Use destructuring for props
- Define prop types using TypeScript interfaces
- Provide default props when applicable
- Avoid passing unnecessary props

### Hooks
- Follow hooks rules and naming conventions
- Custom hooks should start with 'use'
- Keep hooks focused on specific functionality
- Memoize values and callbacks when needed

## TypeScript Guidelines

### Types and Interfaces
- Use interfaces for object shapes
- Use type aliases for unions and complex types
- Export types/interfaces when shared
- Use meaningful type names

### Type Safety
- Avoid using 'any' type
- Use strict type checking
- Properly type async operations
- Use generics when appropriate

## State Management

### Local State
- Use useState for simple component state
- Use useReducer for complex state logic
- Keep state as close as possible to where it's used

### Global State
- Use React Query for server state
- Follow object syntax for query configuration
- Implement proper loading and error states
- Use proper caching strategies

## Testing

### Unit Tests
- Write tests for all components
- Test component behavior and user interactions
- Use meaningful test descriptions
- Follow AAA pattern (Arrange, Act, Assert)

### Integration Tests
- Test component integration points
- Verify data flow between components
- Test error handling and edge cases

## Performance

### Optimization
- Use React.memo for expensive components
- Implement code splitting with lazy loading
- Optimize images and assets
- Monitor and optimize bundle size

### Best Practices
- Avoid unnecessary re-renders
- Use proper key props in lists
- Implement proper loading states
- Use performance monitoring tools

## Security

### Data Handling
- Sanitize user input
- Implement proper authentication
- Use HTTPS for API calls
- Follow security best practices

### Error Handling
- Implement proper error boundaries
- Log errors appropriately
- Don't expose sensitive information
- Handle API errors gracefully

## Commit Guidelines

### Commit Messages
- Use conventional commits format
- Write clear and concise messages
- Reference issue numbers when applicable
- Keep commits focused and atomic

### Version Control
- Create feature branches from main
- Keep branches up to date
- Review code before merging
- Delete branches after merging

## Documentation

### Code Documentation
- Document complex logic
- Update README.md when needed
- Document API endpoints
- Keep documentation up to date

### Component Documentation
- Document component props
- Provide usage examples
- Document side effects
- Include accessibility considerations

## Accessibility

### Guidelines
- Use semantic HTML elements
- Implement proper ARIA attributes
- Ensure keyboard navigation
- Test with screen readers

### Best Practices
- Provide alt text for images
- Use proper heading hierarchy
- Implement focus management
- Test color contrast

## CSS/Tailwind Guidelines

### Styling
- Use Tailwind CSS classes
- Follow mobile-first approach
- Maintain consistent spacing
- Use design system tokens

### Best Practices
- Keep styles modular
- Avoid !important
- Use proper responsive classes
- Follow BEM naming for custom CSS

## Code Review

### Process
- Review all code changes
- Provide constructive feedback
- Check for best practices
- Verify documentation

### Checklist
- Code follows style guide
- Tests are included
- Documentation is updated
- Performance is considered
- Security is addressed

Remember: These rules are living guidelines. They should be regularly reviewed and updated based on team feedback and project needs.

This project is a website based on TYPO3.
In the folder "packages/leseohren" you can find a TYPO3 extension, which is the main part of the project.
It contains the extension "leseohren", which is a database for persons, companies, events and more.
In the folder "packages/migration_extend" you can find a TYPO3 extension, which is a migration from an older TYPO3 version to the current one.
In the folder "packages/vite_base_sitepackage" you can find a Vite base sitepackage, which contains a base setup for a TYPO3 site with Vite, TypoScript, SCSS and Bootstrap.

You are an expert in TYPO3, TypoScript, YAML, Fluid, PHP, SCSS, Bootstrap and JavaScript.
Don't make changes to files outside of the "packages" folder.

Key Principles
- Write concise, technical responses with accurate PHP examples.
- Write semantic HTML to improve accessibility and SEO.
- Follow TYPO3 coding standards and best practices.
- Use object-oriented programming when appropriate, focusing on modularity.
- Prefer iteration and modularization over duplication.
- Use descriptive function, variable, and file names.
- Don't remove unrelated code or functionalities. Pay attention to preserving existing structures.
- Ensure suggested changes are compatible with the project's specified language or framework versions.
- When implementing logic, always consider and handle potential edge cases.
- Include assertions wherever possible to validate assumptions and catch potential errors early.
- Always consider security implications when modifying or suggesting code changes.

Dependencies
- TYPO3 (latest LTS version)
- Bootstrap (latest version, SCSS and JS)
- Composer for dependency management (when building plugins or sitepackages)

PHP/TYPO3
- Use PHP 8.2+ features when appropriate.
- Use „PSR-2 Coding Standard“ for PHP code.
- Use strict typing when possible: declare(strict_types=1);
- Use DocBlocks for all PHP classes, methods and properties.
- Utilize TYPO3 core functions and APIs when available.
- File structure: Follow TYPO3 extension directory structures and naming conventions.
- Implement proper error handling and logging.
- Follow TYPO3's Security guidelines.
- Use TYPO3 debug logging features.
- Use TYPO3's built-in functions for data validation and sanitization.
- Using the QueryBuilder of Doctrine for database interactions.

TYPO3 Best Practices
- Create plugins with the Extbase framework and Fluid templating engine.
- Create a domain model and repository if a plugin requires records that are persisted in the database.
- Implement proper internationalization and localization using TYPO3's XLIFF coding guidelines.
- Implement proper security measures.
- Use TYPO3's built-in TypoScript for storing configuration data.
- Modularize layouts, templates and partials.
- Use TYPO3's authentication and authorization functions.

Bootstrap/SCSS
- Leverage Bootstrap's grid system for responsive layouts; use container, row, and column classes to structure content.
- Utilize Bootstrap components (e.g., buttons, modals, alerts) to enhance user experience without extensive custom CSS.
- Apply Bootstrap's utility classes for quick styling adjustments, such as spacing, typography, and visibility.
- Ensure all components are accessible; use ARIA attributes and semantic HTML where applicable.
- Customize Bootstrap's Sass variables and mixins to create a unique theme without overriding default styles.
- Utilize Bootstrap's responsive utilities to control visibility and layout on different screen sizes.
- Keep custom styles to a minimum; use Bootstrap's classes wherever possible for consistency.
- Use the Bootstrap documentation to understand component behavior and customization options.

HTML/SCSS
- Use SCSS for styling.
- Use class selectors over ID selectors for styling.
- Use BEM (Block Element Modifier) methodology for naming classes.
- Avoid !important; use specificity to manage styles.
- Use semantic elements (e.g., <header>, <main>, <footer>, <article>, <section>).
- Avoid using deprecated elements (e.g., <font>, <center>).

Accessibility
- Use ARIA roles and attributes to enhance accessibility.
- Ensure sufficient color contrast for text.
- Provide keyboard navigation for interactive elements.
- Use focus styles to indicate focus state.
- Use landmarks (e.g., <nav>, <main>, <aside>) for screen readers.

{
  "rules": [
    {
      "id": "js-best-practices",
      "description": "Enforce consistent coding style and best practices.",
      "severity": "warning",
      "options": {
        "camelCase": true,
        "useConstLet": true,
        "requireJSDoc": true,
        "noUnusedVars": true,
        "noImplicitAny": true
      }
    },
    {
      "id": "error-handling",
      "description": "Ensure proper error handling in asynchronous functions.",
      "severity": "error",
      "options": {
        "logErrors": true,
        "catchAsyncErrors": true
      }
    },
    {
      "id": "dom-manipulation",
      "description": "Check for existence of DOM elements before manipulation.",
      "severity": "error",
      "options": {
        "useQuerySelector": true,
        "checkElementExistence": true
      }
    },
    {
      "id": "performance",
      "description": "Encourage performance best practices.",
      "severity": "warning",
      "options": {
        "noSyncXHR": true,
        "useRequestAnimationFrame": true,
        "optimizeLoops": true
      }
    },
    {
      "id": "security",
      "description": "Ensure user input is sanitized.",
      "severity": "error",
      "options": {
        "sanitizeInput": true,
        "validateInput": true
      }
    },
    {
      "id": "code-complexity",
      "description": "Set maximum cyclomatic complexity.",
      "severity": "warning",
      "options": {
        "maxComplexity": 10
      }
    },
    {
      "id": "testing",
      "description": "Require unit tests for functions.",
      "severity": "error",
      "options": {
        "requireUnitTests": true,
        "coverageThreshold": 80
      }
    },
    {
      "id": "chrome-extension",
      "description": "Specific rules for Chrome extension development.",
      "severity": "warning",
      "options": {
        "useManifestV3": true,
        "avoidInlineScripts": true
      }
    }
  ]
} 

# general coding rules

if all members of a type definition are methods, use types instead of interfaces.

always use props objects and never destructure them in function bodies. especially in React components, don't destructure component props in the parameter list.

# html and css rules

for html and css: instead of bare tailwind classes, use existing components from the radix-themes library.

# react rules

for react: use server actions and server-side rendering as much as possible.
for react: use React 19's `use(resource)` api to load data on the server.
for react: use React 19's `useOptimistic(state, updateFn)` api when there is a loading state before the server action is executed.

for react: use signals for reactive data.

You are an expert in JavaScript, TypeScript, and SvelteKit framework for scalable web development.

Key Principles
- Write concise, technical responses with accurate SvelteKit examples.
- Leverage SvelteKit's server-side rendering (SSR) and static site generation (SSG) capabilities.
- Prioritize performance optimization and minimal JavaScript for optimal user experience.
- Use descriptive variable names and follow SvelteKit's naming conventions.
- Organize files using SvelteKit's file-based routing system.

SvelteKit Project Structure
- Use the recommended SvelteKit project structure:
  ```
  - src/
    - lib/
    - routes/
    - app.html
  - static/
  - svelte.config.js
  - vite.config.js
  ```

Component Development
- Create .svelte files for Svelte components.
- Implement proper component composition and reusability.
- Use Svelte's props for data passing.
- Leverage Svelte's reactive declarations and stores for state management.
- Use viem for blockchain integration and wallet-related functionality.

Routing and Pages
- Utilize SvelteKit's file-based routing system in the src/routes/ directory.
- Implement dynamic routes using [slug] syntax.
- Use load functions for server-side data fetching and pre-rendering.
- Implement proper error handling with +error.svelte pages.

Server-Side Rendering (SSR) and Static Site Generation (SSG)
- Leverage SvelteKit's SSR capabilities for dynamic content.
- Implement SSG for static pages using prerender option.
- Use the adapter-auto for automatic deployment configuration.

Styling
- Use Svelte's scoped styling with <style> tags in .svelte files.
- Leverage global styles when necessary, importing them in __layout.svelte.
- Utilize CSS preprocessing with Sass or Less if required.
- Implement responsive design using CSS custom properties and media queries.

Performance Optimization
- Minimize use of client-side JavaScript; leverage SvelteKit's SSR and SSG.
- Implement code splitting using SvelteKit's dynamic imports.
- Use Svelte's transition and animation features for smooth UI interactions.
- Implement proper lazy loading for images and other assets.

Data Fetching
- Use load functions for server-side data fetching.
- Implement proper error handling for data fetching operations.
- Utilize SvelteKit's $app/stores for accessing page data and other stores.

SEO and Meta Tags
- Use Svelte:head component for adding meta information.
- Implement canonical URLs for proper SEO.
- Create reusable SEO components for consistent meta tag management.

State Management
- Use Svelte stores for global state management.
- Leverage context API for sharing data between components.
- Implement proper store subscriptions and unsubscriptions.

Forms and Actions
- Utilize SvelteKit's form actions for server-side form handling.
- Implement proper client-side form validation using Svelte's reactive declarations.
- Use progressive enhancement for JavaScript-optional form submissions.

API Routes
- Create API routes in the src/routes/api/ directory.
- Implement proper request handling and response formatting in API routes.
- Use SvelteKit's hooks for global API middleware.

Authentication
- Implement authentication using SvelteKit's hooks and server-side sessions.
- Use secure HTTP-only cookies for session management.
- Implement proper CSRF protection for forms and API routes.

Styling with Tailwind CSS
- Integrate Tailwind CSS with SvelteKit using svelte-add
- Use Tailwind utility classes extensively in your Svelte components.
- Leverage Tailwind's responsive design utilities (sm:, md:, lg:, etc.).
- Utilize Tailwind's color palette and spacing scale for consistency.
- Implement custom theme extensions in tailwind.config.cjs when necessary.
- Avoid using the @apply directive; prefer direct utility classes in HTML.

Testing
- Use Vitest for unit and integration testing of Svelte components and SvelteKit routes.
- Implement end-to-end testing with Playwright or Cypress.
- Use SvelteKit's testing utilities for mocking load functions and other SvelteKit-specific features.

Accessibility
- Ensure proper semantic HTML structure in Svelte components.
- Implement ARIA attributes where necessary.
- Ensure keyboard navigation support for interactive elements.
- Use Svelte's bind:this for managing focus programmatically.

Key Conventions
1. Follow the official SvelteKit documentation for best practices and conventions.
2. Use TypeScript for enhanced type safety and developer experience.
3. Implement proper error handling and logging.
4. Leverage SvelteKit's built-in features for internationalization (i18n) if needed.
5. Use SvelteKit's asset handling for optimized static asset delivery.

Performance Metrics
- Prioritize Core Web Vitals (LCP, FID, CLS) in development.
- Use Lighthouse and WebPageTest for performance auditing.
- Implement performance budgets and monitoring.

Refer to SvelteKit's official documentation for detailed information on components, routing, and server-side rendering for best practices. Same for viem.

You are an expert in Python, PyQt6, RAG systems, electronics, kendo, karates and other martial arts, and scalable application development. You are also a master of
translating motion sensor data into actionable intelligence. 

YOU MUST FOLLOW THESE RULES:

Be completely thorough and detailed in your code, do not leave any loose ends. 
NEVER create empty functions or classes.
Write modular, maintainable code with clear separation of concerns
Use type hints and documentation consistently
Implement proper error handling and logging
Follow object-oriented design patterns for GUI development
Leverage vectorization and efficient data structures for RAG systems
Use descriptive variable names (e.g., document_embeddings, query_vector)
Structure code hierarchically with clear component boundaries
Prefer classes over functions for complex logic
Always create a new file for each new class
Use asyncio for I/O-bound operations
Use SOLID principles for object-oriented design

PyQt6 Development

Use Qt Designer for complex layouts, direct code for simple ones
Implement MVC/MVVM patterns for GUI applications
Properly handle Qt signals and slots:
pythonCopy# Preferred signal/slot connection
self.button.clicked.connect(self.handle_click)

# Avoid direct connections without handlers
self.button.clicked.connect(lambda: print("clicked"))

Create custom widgets by subclassing appropriate Qt classes
Use layouts (QVBoxLayout, QHBoxLayout, QGridLayout) instead of fixed positioning
Implement proper resource cleanup in destructors
Use Qt's event system rather than polling
Separate UI logic from business logic

RAG System Design

Use efficient vector databases (Weaviate, FAISS, etc.) for embeddings
Implement proper chunking strategies for document processing
Use async operations for embedding generation and vector searches
Cache frequently accessed embeddings and results
Implement proper error handling for API rate limits
Use batching for efficient document processing
Monitor and optimize vector similarity search performance
Handle edge cases in document processing and query generation

Weaviate Integration

Use proper schema design for vector objects
Implement efficient batch operations for data import
Use proper indexing strategies for vector search
Handle connection management and retries properly
Implement proper error handling for Weaviate operations
Use connection pooling for concurrent operations
Monitor and optimize query performance
Implement proper backup and recovery strategies

Error Handling and Validation

Use try-except blocks judiciously:

Handle specific exceptions rather than catch-all
Log errors with appropriate context
Provide meaningful error messages
Implement proper cleanup in finally blocks


Validate inputs early:

Check parameters at function entry
Validate data before processing
Handle edge cases explicitly


Use custom exceptions for domain-specific errors
Implement proper logging and monitoring

Dependencies Management

Use virtual environments for project isolation
Specify exact versions in requirements.txt
Use pip-tools or poetry for dependency management
Document all dependencies and their purposes
Keep dependencies up to date and security-patched

Code Organization

Use clear directory structure:
Copyproject/
  ├── src/
  │   ├── ui/
  │   ├── rag/
  │   ├── db/
  │   └── utils/
  ├── tests/
  ├── resources/
  └── docs/

Separate concerns into modules
Use proper naming conventions:

CamelCase for classes
snake_case for functions and variables
UPPERCASE for constants


Document code with docstrings and type hints

Performance Optimization

Profile code to identify bottlenecks
Use asyncio for I/O-bound operations
Implement caching strategies:

Memory caching for frequent queries
Disk caching for large datasets
Redis for distributed caching


Optimize vector operations:

Use efficient data structures
Implement proper batching
Use parallel processing where appropriate


Monitor system resource usage

Testing

Write comprehensive unit tests
Implement integration tests for critical paths
Use proper mocking for external dependencies
Test edge cases and error conditions
Implement performance tests for critical operations
Use pytest for testing framework
Implement proper test coverage reporting

Best Practices

Follow SOLID principles
Write self-documenting code
Implement proper logging and monitoring
Use version control effectively
Document architectural decisions
Review code regularly
Keep security in mind
Optimize for maintainability

Key Conventions

Use consistent code formatting (black, isort)
Implement proper error handling
Document public APIs
Write readable, maintainable code
Follow Python's style guide (PEP 8)
Use type hints consistently
Implement proper testing
Optimize for performance where needed

Remember to refer to official documentation for PyQt6, Weaviate, and relevant libraries for specific implementation details and best practices.

Use Hono for server routing.
Use Bun for bundling and running the app.
Use TypeScript for type safety.
Export a default Hono app instance.
Put route handlers in separate files for organization.
Use absolute imports for internal files.
Add Scripts for dev and build in package.json.
Use getRandomInt helper for generating random numbers.
Name helper functions clearly based on what they do.

{
  "version": "1.0",
  "language": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"],
      "importOrder": [
        "^react$",
        "^react-dom.*$",
        "^next.*$",
        "^@vercel/.*$",
        "^ai$",
        "^@radix-ui/.*$",
        "^prosemirror-.*$",
        "^@/components/.*$",
        "^@/lib/.*$",
        "^@/hooks/.*$",
        "^[./]"
      ],
      "componentStructure": {
        "order": [
          "imports",
          "types",
          "interfaces",
          "constants",
          "component",
          "exports"
        ]
      }
    }
  },
  "formatting": {
    "indentStyle": "space",
    "indentSize": 2,
    "lineWidth": 80,
    "quoteStyle": {
      "typescript": "single",
      "json": "double"
    },
    "semicolons": "always",
    "trailingComma": "all"
  },
  "components": {
    "directory": "components",
    "naming": {
      "pattern": "kebab-case",
      "exceptions": ["ui"]
    },
    "structure": {
      "ui": "components/ui",
      "icons": "components/icons.tsx",
      "shared": "components"
    }
  },
  "paths": {
    "aliases": {
      "@": ".",
      "@/components": "./components",
      "@/lib": "./lib",
      "@/hooks": "./hooks"
    }
  },
  "ignore": [
    "node_modules",
    ".next",
    "public",
    ".vercel",
    "lib/db/migrations"
  ],
  "rules": {
    "typescript": {
      "noExplicitAny": "off",
      "useFragmentSyntax": "warn",
      "noUnusedImports": "warn",
      "useArrayLiterals": "warn",
      "noNewSymbol": "warn"
    },
    "a11y": {
      "useHtmlLang": "warn",
      "noHeaderScope": "warn",
      "useValidAriaRole": {
        "level": "warn",
        "ignoreNonDom": false,
        "allowInvalidRoles": ["none", "text"]
      }
    },
    "nextjs": {
      "clientComponents": {
        "directive": "'use client'",
        "location": "top",
        "required": true
      },
      "hydration": {
        "preventMismatch": {
          "dateHandling": "useEffect",
          "windowChecks": "useEffect",
          "randomValues": "useEffect",
          "dynamicClassNames": "warn"
        },
        "suppressWarning": {
          "enabled": false,
          "message": "suppressHydrationWarning should only be used when necessary"
        }
      },
      "serverComponents": {
        "defaultServer": true,
        "asyncComponents": "preferred"
      }
    },
    "react": {
      "hooks": {
        "dependencies": "error",
        "exhaustiveDeps": "warn",
        "rulesOfHooks": "error"
      },
      "performance": {
        "useMemo": "recommended",
        "useCallback": "recommended",
        "reactMemo": "selective"
      }
    }
  }
} 

# Desenvolvimento Cross-Platform com TypeScript e React

## Diretrizes Gerais de Simplificação

### 1. Remova Complexidade Desnecessária

- Elimine código redundante
- Remova funcionalidades não utilizadas
- Simplifique lógicas complexas
- Evite over-engineering
- manter logs extremamentes necessários
- Ocultar logs de sucesso (200)
- Ocultar mensagens de compilação
- Ocultar o aviso experimental do Node.js
- Manter apenas mensagens de erro importantes

### 2. Gerencie Dependências com Cuidado

- Mantenha apenas dependências essenciais
- Avalie o custo/benefício de cada pacote
- Prefira soluções nativas quando possível
- Remova dependências não utilizadas

### 3. Mantenha o Projeto Limpo

- Apague arquivos e pastas não utilizados
- Remova código comentado
- Mantenha apenas assets necessários
- Faça limpeza regular do projeto

### 4. Simplifique o package.json

- Remova scripts não utilizados
- Mantenha apenas exportações necessárias
- Organize scripts de forma clara
- Mantenha versões de dependências atualizadas

### 5. Desenvolva Componentes Eficientes

- Mantenha componentes simples e focados
- Evite props desnecessárias
- Use composição ao invés de herança
- Documente funcionalidades importantes

### 6. Monitore Padrões de Problemas

- Identifique loops de correções
- Documente soluções recorrentes
- Corrija problemas na raiz
- Evite soluções temporárias

## Processo de Desenvolvimento Incremental

1. **Evolução Gradual**:

   - Comece com uma única página funcional.
   - Adicione um componente por vez.
   - Teste cada adição antes de avançar.
   - Só adicione dependências quando absolutamente necessário.

2. **Regras de Ouro**:

   - Não adicione dependências desnecessárias.
   - Mantenha a simplicidade sempre.
   - Realize testes frequentes.
   - Faça commits pequenos e regulares.

3. **Quando Precisar Escalar**:
   - Use monorepo apenas se for realmente necessário.
   - Adicione ferramentas conforme a necessidade real.
   - Mantenha a documentação atualizada.
   - Faça mudanças incrementais.

## Configuração Inicial

### Remover Avisos Desnecessários

Para remover avisos de desenvolvimento desnecessários, configure o `next.config.js`:

```typescript
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = nextConfig;
```

### Configurar .gitignore

Mantenha o .gitignore limpo e relevante para seu projeto:

#### ✅ Regras para um .gitignore Eficiente:

1. **Mantenha Apenas o Necessário**

   - Inclua somente padrões para arquivos que existem ou podem existir no projeto
   - Remova entradas de tecnologias que não está usando
   - Evite duplicação de padrões

2. **Organize por Categorias**

   - Agrupe entradas relacionadas (ex: dependências, build, ambiente)
   - Use comentários para identificar cada seção
   - Mantenha uma ordem lógica

3. **Revise Regularmente**

   - Remova padrões de ferramentas que não usa mais
   - Atualize conforme o projeto evolui
   - Questione se cada entrada é realmente necessária

4. **Padrões Essenciais para Next.js**

   ```plaintext
   # Dependências
   node_modules

   # Next.js
   .next/

   # Ambiente
   .env*.local
   .env

   # Debug
   npm-debug.log*
   yarn-debug.log*
   yarn-error.log*

   # TypeScript
   *.tsbuildinfo
   next-env.d.ts

   # Sistema
   .DS_Store

   # Logs
   *.log
   ```

#### ❌ Evite no .gitignore:

- Padrões de ferramentas que não usa
- Duplicação de regras
- Entradas muito genéricas
- Padrões de outras tecnologias/frameworks

### Criar um Projeto Next.js Básico

```bash
npx create-next-app@latest meu-projeto --typescript --tailwind --eslint
cd meu-projeto
npm run dev
```

### Estrutura Inicial Recomendada

```plaintext
meu-projeto/
├── src/
│   ├── components/ # Componentes reutilizáveis
│   ├── pages/      # Páginas do Next.js
│   └── styles/     # Estilos globais
├── package.json
└── tsconfig.json
```

### Página Inicial

Crie uma página simples em `src/pages/index.tsx`:

```tsx
export default function Home() {
  return <h1>Bem-vindo ao meu projeto Next.js!</h1>;
}
```

### Adicionar Componentes Básicos

Exemplo: `src/components/Button.tsx`

```tsx
import React from "react";

interface ButtonProps {
  label: string;
  onClick: () => void;
}

const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return (
    <button onClick={onClick} className="bg-blue-500 text-white p-2 rounded">
      {label}
    </button>
  );
};

export default Button;
```

### Estilização com Tailwind CSS

Adicione estilos globais em `src/styles/globals.css`:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

## Boas Práticas

### ✅ Faça:

- Comece com o mínimo necessário.
- Adicione funcionalidades uma por vez.
- Teste cada nova adição.
- Use TypeScript desde o início.
- Use Tailwind CSS para estilização.

### ❌ Não Faça:

- Não adicione dependências desnecessárias.
- Não crie estruturas complexas sem necessidade.
- Não use monorepo sem necessidade clara.
- Não misture múltiplas tecnologias de UI.
- Não tente implementar tudo de uma vez.

## Processo de Desenvolvimento

1. **Crie um Componente**
2. **Teste o Componente**
3. **Integre na Página**
4. **Teste Novamente**
5. **Faça o Commit**
6. **Repita o Ciclo**

## Estrutura Mínima Recomendada

```plaintext
src/
├── pages/
│   └── index.tsx # Apenas uma página inicial
└── components/
    └── Button.tsx # Um componente por vez
```

## Checklist Antes de Adicionar Algo Novo

- Isso é realmente necessário agora?
- Existe uma solução mais simples?
- Isso vai adicionar complexidade?
- Vale a pena o trade-off?

## Sinais de Alerta

- Muitos arquivos de configuração.
- Dependências não utilizadas.
- Arquivos vazios.
- Imports não utilizados.
- Código comentado em excesso.
- IDEs mostrando erros de dependências mesmo após instalação:
  - Este é um problema comum onde a IDE não reconhece imediatamente novas dependências
  - Solução: Feche e reabra o navegador/IDE
  - Na maioria dos casos, os erros desaparecem após reiniciar a IDE
  - Não é necessário reinstalar as dependências nestes casos

## Conclusão

- A simplicidade é a chave.
- Cada linha de código é uma responsabilidade.
- Menos é mais.
- Comece pequeno e cresça conforme necessário.
- Mantenha o projeto limpo e organizado.

### Estrutura Recomendada do Projeto

```plaintext
projeto/
├── .next/                  # ⚠️ no .gitignore
├── node_modules/          # ⚠️ no .gitignore
├── src/
│   ├── @types/
│   └── next-pwa.d.ts
│   ├── app/
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   │   └── Button.tsx
│   └── utils/
│       └── platform.ts
├── .cursorrules
├── .gitattributes
├── .gitignore
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.js
├── next.config.ts
├── package-lock.json
├── package.json
├── postcss.config.mjs
├── README.md
├── tailwind.config.ts
└── tsconfig.json
```

### Descrição da Estrutura

- **src/@types/**: Definições de tipos TypeScript
- **src/app/**: Componentes e layouts principais (App Router)
- **src/components/**: Componentes reutilizáveis
- **src/utils/**: Funções utilitárias e helpers
- **Diretórios Ignorados**:
  - `.next/`: Build e cache do Next.js (ignorado no git)
  - `node_modules/`: Dependências do projeto (ignorado no git)
- **Arquivos de Configuração**:
  - `next.config.js`: Configuração do Next.js
  - `tailwind.config.ts`: Configuração do Tailwind CSS
  - `tsconfig.json`: Configuração do TypeScript
  - `.gitignore`: Arquivos a serem ignorados pelo Git

# Ambiente de Desenvolvimento

- Sistema Operacional: macOS
- Gerenciador de Pacotes do Sistema: Homebrew (brew)
- Gerenciador de Pacotes Node: Yarn (exclusivamente)

## Gerenciamento de Dependências

### ✅ Usar Apenas Yarn 4 (Berry)

```bash
yarn deps:outdated      # Verificar e atualizar dependências interativamente
yarn up -i             # Alternativa direta para verificar atualizações
yarn up [pacote]       # Atualizar um pacote específico
yarn add [pacote]      # Instalar nova dependência
yarn add -D [pacote]   # Instalar dependência de desenvolvimento
yarn remove [pacote]   # Remover dependência
yarn                   # Instalar todas as dependências
yarn dedupe           # Remove duplicações de pacotes e otimiza dependências
```

### Comandos Específicos do Yarn 4

- `yarn up -i`: Interface interativa para atualização de dependências
- `yarn up "*" --latest`: Atualizar todas as dependências para última versão
- `yarn dlx`: Executar pacotes sem instalá-los (substitui npx)
- `yarn why [pacote]`: Verificar por que um pacote está instalado
- `yarn info [pacote]`: Ver informações detalhadas de um pacote

### Sobre yarn dedupe

O comando `yarn dedupe` é utilizado para:

- Remover versões duplicadas de pacotes
- Otimizar a árvore de dependências
- Reduzir o tamanho do node_modules
- Resolver conflitos de versões similares
- Melhorar a performance da aplicação

✅ **Quando Usar**:

- Após adicionar novas dependências
- Quando o node_modules estiver muito grande
- Se houver warnings de versões duplicadas
- Durante otimização de performance
- Antes de fazer deploy em produção

⚠️ **Cuidados**:

- Teste a aplicação após usar dedupe
- Verifique se não houve breaking changes
- Mantenha um backup do yarn.lock
- Execute em ambiente de desenvolvimento primeiro

💡 **Dica**: Use `yarn dedupe --check` para verificar duplicações sem fazer alterações

### ❌ Não Usar

- Evitar comandos npm (npm install, npm run, etc)
- Não manter package-lock.json
- Não misturar npm e yarn no mesmo projeto

## Scripts do Projeto

```bash
yarn dev                  # Ambiente de desenvolvimento
yarn build               # Build de produção
yarn start               # Iniciar em produção
yarn lint                # Executar linter
```

## Arquivos de Lock

- Manter apenas: yarn.lock
- Remover: package-lock.json

## Configuração do .gitignore para Yarn

```plaintext
# Yarn
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions
.pnp.*
```

## Instalação no macOS

- Instalado via Homebrew: `brew install yarn`
- Atualização: `brew upgrade yarn`
- Verificar versão: `yarn --version`

## Boas Práticas para macOS

1. **Sempre prefira Homebrew para instalações globais**

   - Mais confiável
   - Melhor gerenciamento de dependências
   - Atualizações mais simples
   - Menos problemas de permissão

2. **Comandos Homebrew Úteis**

   ```bash
   brew install [pacote]    # Instalar pacote
   brew upgrade [pacote]    # Atualizar pacote
   brew uninstall [pacote]  # Remover pacote
   brew doctor             # Verificar problemas
   brew update             # Atualizar Homebrew
   ```

3. **Manutenção**
   - Mantenha o Homebrew atualizado
   - Limpe pacotes antigos periodicamente: `brew cleanup`
   - Verifique dependências: `brew deps --tree [pacote]`

## Configuração do ESLint

### Configuração Recomendada

1. **Instalação das Dependências**

```bash
yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y
```

2. **Arquivo de Configuração Base**

```javascript:eslint.config.mjs
export default {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:jsx-a11y/recommended',
    'next/core-web-vitals',
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
    },
    ecmaVersion: 'latest',
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint', 'react', 'jsx-a11y'],
  rules: {
    // Regras personalizadas
    'react/react-in-jsx-scope': 'off',
    'react/prop-types': 'off',
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/no-explicit-any': 'warn',
    'no-console': ['warn', { allow: ['warn', 'error'] }],
  },
  settings: {
    react: {
      version: 'detect',
    },
  },
  ignorePatterns: [
    'node_modules/',
    '.next/',
    'out/',
    'public/',
    '*.config.js',
    '*.config.mjs',
  ],
}
```

3. **Scripts no package.json**

```json
{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix"
  }
}
```

### Boas Práticas de Linting

✅ **Recomendado**:

- Execute o linter antes de cada commit
- Configure o auto-fix no seu editor
- Use o ESLint junto com o Prettier
- Mantenha as regras consistentes em todo o projeto
- Documente exceções às regras quando necessário

❌ **Evite**:

- Desabilitar regras do ESLint sem motivo claro
- Ignorar warnings do linter
- Misturar diferentes padrões de código
- Deixar regras conflitantes ativas

### Integração com VSCode

1. **Instale a extensão ESLint**
2. **Configure o settings.json**:

```json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}
```

### Resolução de Problemas Comuns

1. **Conflitos com Prettier**:

   - Instale `eslint-config-prettier`
   - Adicione `prettier` ao final do array `extends`

2. **Regras Muito Restritivas**:

   - Ajuste as regras gradualmente
   - Comece com warnings antes de errors
   - Documente as razões das alterações

3. **Performance**:
   - Use `.eslintignore` para diretórios grandes
   - Configure o cache do ESLint
   - Limite o escopo da análise quando necessário

## Análise de Bundle com yarn analyze

### Configuração do Analisador de Bundle

1. **Instalação da Dependência**

```bash
yarn add -D @next/bundle-analyzer
```

2. **Configuração no next.config.js**

```javascript:next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

module.exports = withBundleAnalyzer({
  // ... outras configurações do Next.js
})
```

3. **Adicione o Script no package.json**

```json
{
  "scripts": {
    "analyze": "ANALYZE=true yarn build",
    "analyze:win": "set ANALYZE=true && yarn build" // Para Windows
  }
}
```

### Como Usar

1. **Execute o Comando**

```bash
yarn analyze
```

2. **Interpretando os Resultados**:
   - Dois relatórios serão gerados automaticamente no navegador:
     - Client bundles (`.next/analyze/client.html`)
     - Server bundles (`.next/analyze/server.html`)
   - Analise o tamanho dos módulos
   - Identifique dependências pesadas
   - Verifique código não utilizado

### Boas Práticas de Análise

✅ **Recomendado**:

- Execute a análise antes de cada deploy
- Monitore o crescimento do bundle
- Otimize dependências grandes
- Utilize code splitting quando necessário
- Remova imports não utilizados

❌ **Evite**:

- Ignorar bundles muito grandes
- Manter dependências duplicadas
- Importar bibliotecas inteiras quando necessário apenas alguns componentes
- Deixar código morto no bundle

### Otimizações Comuns

1. **Redução de Tamanho**:

   - Use dynamic imports para código não crítico
   - Implemente lazy loading para componentes grandes
   - Remova dependências não utilizadas
   - Utilize versões mais leves de bibliotecas quando possível

2. **Monitoramento**:

   - Compare resultados entre builds
   - Estabeleça limites máximos de tamanho
   - Documente decisões de otimização
   - Mantenha um histórico de análises

3. **Performance**:
   - Priorize otimizações em páginas críticas
   - Balance tamanho vs funcionalidade
   - Considere estratégias de caching
   - Implemente code splitting estratégico

## Autoprefixer e Compatibilidade Cross-Browser

### O que é Autoprefixer?

O Autoprefixer é uma ferramenta essencial que:

- Adiciona automaticamente prefixos de vendor (-webkit-, -moz-, -ms-)
- Garante compatibilidade cross-browser
- Integra-se com Tailwind CSS
- Mantém o código limpo e manutenível

### Por que é Necessário?

1. **Integração com Tailwind CSS**:

   - Trabalha em conjunto com o sistema de estilos
   - Garante que todas as classes funcionem em diferentes navegadores
   - Processa automaticamente as utilidades do Tailwind

2. **Exemplos de Transformação**:

```css
/* Seu CSS original */
.elemento {
  display: flex;
  user-select: none;
  backdrop-filter: blur(10px);
}

/* Após o Autoprefixer */
.elemento {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  -webkit-backdrop-filter: blur(10px);
  backdrop-filter: blur(10px);
}
```

### Configuração no Next.js

1. **Instalação**:

```bash
yarn add -D autoprefixer
```

2. **Configuração (postcss.config.js)**:

```javascript:postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

### Boas Práticas

✅ **Recomendado**:

- Mantenha sempre atualizado
- Use em conjunto com Tailwind CSS
- Verifique a cobertura de browsers no browserslist
- Mantenha as configurações padrão quando possível

❌ **Evite**:

- Remover o autoprefixer do projeto
- Adicionar prefixos manualmente
- Sobrescrever configurações padrão sem necessidade
- Ignorar warnings de compatibilidade

### Verificação de Prefixos

Para verificar quais prefixos estão sendo aplicados:

```bash
yarn dlx autoprefixer --info
```

### Integração com Editores

Para VSCode:

- Instale a extensão "PostCSS Language Support"
- Habilite suporte a CSS moderno
- Veja os prefixos sendo aplicados em tempo real

### Resolução de Problemas

1. **Prefixos Não Aplicados**:

   - Verifique se o autoprefixer está listado no postcss.config.js
   - Confirme se o browserslist está configurado corretamente
   - Limpe o cache do Next.js (.next)

2. **Conflitos**:
   - Mantenha todas as dependências CSS atualizadas
   - Verifique a ordem dos plugins no postcss.config.js
   - Evite múltiplas configurações de PostCSS

## Gerenciamento de Dependências Atualizado

### Resolvendo Problemas de Peer Dependencies

1. **Identificação de Problemas**:

   - Use `yarn deps:outdated` para verificar dependências desatualizadas
   - Verifique avisos de peer dependencies com `yarn explain peer-requirements`
   - Monitore warnings do Yarn sobre dependências incorretas

2. **Soluções Aplicadas**:

   - Remova configurações de workspaces não utilizadas
   - Adicione peer dependencies faltantes no package.json
   - Mantenha resolutions para versões específicas
   - Use `yarn dedupe` para otimizar dependências

3. **Estrutura do package.json Otimizada**:

```json
{
  "peerDependencies": {
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "framer-motion": "^10.18.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "tailwind-variants": "^0.3.0",
    "tailwindcss": "^3.4.0"
  },
  "resolutions": {
    "@nextui-org/react": "2.2.9",
    "@nextui-org/system": "2.0.15",
    "@nextui-org/theme": "2.1.17",
    "next": "14.0.4",
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}
```

4. **Processo de Verificação**:

   ```bash
   # 1. Limpar dependências duplicadas
   yarn deps:clean

   # 2. Verificar saúde das dependências
   yarn deps:check

   # 3. Testar a aplicação
   yarn dev
   ```

5. **Tratamento de Avisos**:
   - Avisos do pacote `pacote` podem ser ignorados (dependência interna do Yarn)
   - Mantenha backup do yarn.lock antes de alterações
   - Documente mudanças significativas
   - Teste a aplicação após cada modificação

### Boas Práticas Atualizadas

✅ **Recomendado**:

- Mantenha peer dependencies alinhadas com as dependências principais
- Use resolutions para fixar versões críticas
- Remova configurações não utilizadas
- Monitore regularmente a saúde das dependências

❌ **Evite**:

- Ignorar avisos de peer dependencies
- Manter configurações de workspace sem necessidade
- Misturar diferentes versões de pacotes core
- Deixar dependências conflitantes

### Scripts de Manutenção

```json
{
  "scripts": {
    "deps:outdated": "yarn up -i",
    "deps:clean": "yarn dedupe",
    "deps:check": "yarn dlx @yarnpkg/doctor",
    "validate": "yarn deps:outdated && yarn check-security && yarn lint"
  }
}
```

## Resolução de Problemas de Tipos TypeScript

### Abordagem para Erros de Tipos Persistentes

1. **Quando Aguardar a Resolução Automática**:

   - Se o erro é relacionado a tipos de módulos externos
   - Se você acabou de instalar ou atualizar dependências
   - Se o erro aparece após mudanças no `tsconfig.json`
   - Se o erro persiste mesmo após reiniciar o editor

2. **Tempo de Espera Recomendado**:

   - Aguarde o TypeScript Server reiniciar (geralmente 30 segundos)
   - Deixe o servidor de desenvolvimento rodando (`yarn dev`)
   - Permita que o compositor de tipos do TypeScript trabalhe
   - Evite fazer alterações durante este período

3. **Sinais de Resolução Automática**:
   - Os erros começam a desaparecer sem intervenção
   - O editor mostra menos erros gradualmente
   - As sugestões de autocompletar começam a funcionar
   - O servidor TypeScript mostra "No errors" no log

### ✅ Quando Aguardar:

- Erros de "Cannot find module" após instalação
- Erros de tipos em módulos externos
- Conflitos de tipos após atualização
- Erros que aparecem e desaparecem

### ❌ Quando Intervir:

- Erros em código fonte próprio
- Problemas de sintaxe
- Erros de configuração
- Dependências realmente faltantes

### Boas Práticas

1. **Durante a Espera**:

   - Mantenha o servidor de desenvolvimento rodando
   - Não force reload do TypeScript Server
   - Evite limpar caches desnecessariamente
   - Continue trabalhando em outras partes do código

2. **Após a Resolução**:
   - Documente o tempo necessário para resolução
   - Verifique se todos os tipos estão corretos
   - Faça um commit das alterações que funcionaram
   - Atualize a documentação se necessário

## Erros Comuns de Tipos no TypeScript

### Problemas Frequentes com @types

1. **Módulos Não Encontrados**:

   ```typescript
   // Erro comum
   Não é possível localizar o módulo '[nome-do-pacote]' ou suas declarações de tipo correspondentes.ts(2307)
   ```

   **Soluções**:

   - Aguarde a resolução automática do TypeScript Server
   - Verifique se o pacote @types correspondente está instalado
   - Crie declarações de tipos locais em `src/@types/[nome-do-pacote].d.ts`

2. **Conflitos de Versões**:

   - Tipos incompatíveis entre dependências
   - Versões diferentes do mesmo pacote @types
   - Tipos desatualizados em relação à implementação

3. **Boas Práticas para Tipos**:
   - Mantenha os pacotes @types alinhados com as versões das dependências
   - Prefira tipos oficiais dos pacotes quando disponíveis
   - Use declarações locais apenas quando necessário
   - Documente decisões sobre tipos personalizados

### Estratégias de Resolução

1. **Abordagem Gradual**:

   ```bash
   # 1. Verifique se há tipos oficiais
   yarn add -D @types/[pacote]

   # 2. Se não houver, crie tipos locais
   src/@types/[pacote].d.ts
   ```

2. **Declarações Locais**:

   ```typescript
   // src/@types/[pacote].d.ts
   declare module "[pacote]" {
     // Tipos necessários
     export interface Config {
       // ...
     }
   }
   ```

3. **Configuração do TypeScript**:
   ```json
   {
     "compilerOptions": {
       "typeRoots": ["./node_modules/@types", "./src/@types"]
     }
   }
   ```

### Prevenção de Problemas

1. **Manutenção Regular**:

   - Atualize os pacotes @types regularmente
   - Monitore conflitos de tipos
   - Mantenha documentação de tipos personalizada

2. **Organização**:

   - Mantenha tipos locais em `src/@types/`
   - Use namespaces para evitar conflitos
   - Documente decisões sobre tipos

3. **Quando Criar Tipos Locais**:
   - Pacote não tem tipos oficiais
   - Tipos oficiais estão desatualizados
   - Necessidade de extensão de tipos existentes
   - Resolução temporária de conflitos

### Sinais de Alerta

✅ **Normal**:

- Erros temporários após instalação de pacotes
- Avisos de tipos durante atualizações
- Conflitos resolvidos automaticamente
- Erros que desaparecem após reiniciar o servidor

❌ **Requer Atenção**:

- Erros persistentes após reiniciar
- Conflitos entre versões de tipos
- Tipos incompatíveis entre dependências
- Erros em código fonte próprio

## Erros Persistentes em Arquivos Específicos

### Erros Comuns em page.tsx

1. **Erros de JSX e Tipos Implícitos**:

   ```typescript
   // Erro comum
   O elemento JSX implicitamente tem o tipo 'any' porque não há uma interface de 'JSX.IntrinsicElements'.
   ```

   **Soluções**:

   - Aguarde o TypeScript Server carregar completamente
   - Reinicie o servidor de desenvolvimento
   - Se persistir, adicione tipos explícitos para elementos JSX

2. **Módulos Não Encontrados em Páginas**:

   ```typescript
   // Erro comum
   Não é possível localizar o módulo 'react' ou suas declarações de tipo correspondentes.
   ```

   **Soluções**:

   - Verifique se o arquivo tem a diretiva 'use client'
   - Aguarde a resolução automática
   - Se persistir após 1-2 minutos, tente:
     1. Limpar cache: `rm -rf .next`
     2. Reinstalar deps: `yarn install`
     3. Reiniciar servidor: `yarn dev`

3. **Parâmetros com Tipo 'any' Implícito**:
   ```typescript
   // Erro comum
   O parâmetro 'prev' implicitamente tem um tipo 'any'.
   ```
   **Soluções**:
   - Aguarde a inferência de tipos
   - Se persistir, adicione tipos explícitos:
     ```typescript
     const toggleSidebar = useCallback(() => {
       setIsSidebarOpen((prev: boolean) => !prev);
     }, []);
     ```

### Ordem de Resolução

1. **Primeira Tentativa**:

   - Aguarde 30-60 segundos após iniciar o servidor
   - Não faça alterações durante este período
   - Observe se os erros começam a desaparecer

2. **Segunda Tentativa** (se os erros persistirem):

   ```bash
   # 1. Pare o servidor
   # 2. Limpe os caches
   rm -rf .next
   rm -rf node_modules/.cache
   # 3. Reinstale as dependências
   yarn install
   # 4. Inicie o servidor
   yarn dev
   ```

3. **Terceira Tentativa** (se ainda persistir):
   - Feche completamente o editor
   - Limpe os caches do TypeScript
   - Reabra o projeto
   - Inicie o servidor

### Sinais de Resolução Normal vs. Problemas Reais

✅ **Normal**:

- Erros desaparecem gradualmente
- Erros somem após reiniciar o servidor
- IDE mostra menos erros com o tempo
- Erros de tipos são resolvidos automaticamente

❌ **Problema Real**:

- Erros persistem após múltiplas tentativas
- Erros aumentam com o tempo
- IDE trava ou fica lento
- Build falha com os mesmos erros

### Boas Práticas para Prevenção

1. **Durante o Desenvolvimento**:

   - Mantenha o servidor rodando
   - Evite editar arquivos durante a inicialização
   - Aguarde a resolução automática
   - Use tipos explícitos em casos críticos

2. **Configuração do Projeto**:

   - Mantenha dependências atualizadas
   - Use versões estáveis dos pacotes
   - Evite misturar diferentes versões do mesmo pacote
   - Mantenha o tsconfig.json consistente

3. **Quando Criar Tipos Locais**:
   - Apenas após tentar a resolução automática
   - Quando os erros são consistentes
   - Para componentes específicos do projeto
   - Para sobrescrever tipos problemáticos

## Erros de Lint em page.tsx

### Erros Comuns e Soluções

1. **Erros de Importação**:

   ```typescript
   // Erro comum
   'React' must be in scope when using JSX
   ```

   **Soluções**:

   - Adicione a diretiva 'use client' no topo do arquivo
   - Aguarde o ESLint reconhecer as configurações do Next.js
   - Se persistir, verifique se `eslint-config-next` está instalado

2. **Erros de Tipos em Componentes**:

   ```typescript
   // Erro comum
   Type '{ children: string; }' is not assignable to type 'IntrinsicAttributes'
   ```

   **Soluções**:

   - Aguarde o TypeScript Server carregar os tipos
   - Se persistir, verifique se os tipos do NextUI estão corretos
   - Adicione tipos explícitos quando necessário

3. **Erros de Hook**:
   ```typescript
   // Erro comum
   React Hook useCallback has missing dependencies
   ```
   **Soluções**:
   - Aguarde o ESLint carregar as regras do React
   - Se persistir, adicione as dependências faltantes
   - Use o comando `yarn lint --fix` para correções automáticas

### Ordem de Verificação

1. **Primeira Etapa**:

   ```bash
   # Verifique os erros de lint
   yarn lint
   ```

2. **Segunda Etapa** (se houver erros):

   ```bash
   # Tente correção automática
   yarn lint --fix
   ```

3. **Terceira Etapa** (se persistir):
   - Verifique as regras do ESLint
   - Atualize as dependências do ESLint
   - Limpe o cache do ESLint

### Boas Práticas

1. **Durante o Desenvolvimento**:

   - Mantenha o ESLint atualizado
   - Use o autofix quando possível
   - Documente exceções às regras
   - Mantenha consistência nas soluções

2. **Configuração**:

   - Use as regras recomendadas do Next.js
   - Evite desabilitar regras globalmente
   - Documente regras personalizadas
   - Mantenha o .eslintrc consistente

3. **Quando Ignorar**:
   - Apenas em casos excepcionais
   - Com comentários explicativos
   - Temporariamente durante desenvolvimento
   - Para regras específicas do arquivo

### Prevenção

1. **Setup Inicial**:

   ```json
   // package.json
   {
     "scripts": {
       "lint": "next lint",
       "lint:fix": "next lint --fix"
     }
   }
   ```

2. **Configuração do Editor**:

   ```json
   // .vscode/settings.json
   {
     "editor.codeActionsOnSave": {
       "source.fixAll.eslint": true
     }
   }
   ```

3. **Hooks do Git**:
   ```bash
   # .husky/pre-commit
   yarn lint
   ```

### Sinais de Alerta

✅ **Normal**:

- Erros resolvidos com --fix
- Warnings de dependências
- Erros temporários após mudanças
- Problemas resolvidos após reload

❌ **Requer Atenção**:

- Erros persistentes após --fix
- Conflitos entre regras
- Erros em múltiplos arquivos
- Problemas de configuração

You are an expert in TypeScript, Node.js, Next.js App Router, React, Drizzle ORM, PostgresSQL, Shadcn UI, Radix UI and Tailwind.

Code Style and Structure

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns.
- Write Clean Architecture code independently of any framework, testable and with low coupling.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor default exports for components.

TypeScript Usage

- Use TypeScript for all code; prefer types over interfaces. Use interfaces only for repository/services definitions.
- Avoid enums; use maps instead.
- Use functional components with TypeScript types.

Syntax and Formatting

- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

UI and Styling

- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS.

Performance Optimization

- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: use WebP format, include size data, implement lazy loading.

Key Conventions

- Use 'nuqs' for URL search parameter state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':
  - Favor server components and Next.js SSR.
  - Use only for Web API access in small components.
  - Avoid for data fetching or state management.

Clean Architecture

- Use /app folder only for Next.js and react (UI) specific code
- Use /src folder for the business logic (application layer, entities layer, infrastructure layer and interface-adapters layer)
- Use /di folder for dependency injection
- Use /tests folder for tests that matches the /src folder structure
- Use /drizzle folder for database related code (models, schema, etc.)

Follow Next.js docs for Data Fetching, Rendering, and Routing.

// Backend Development Standards

// API Design
- RESTful Endpoints:
  * Use proper HTTP methods
  * Implement proper status codes
  * Follow resource naming conventions
  * Support proper filtering
  * Implement pagination
- Response Format:
  {
    "success": boolean,
    "data": {
      "items": T[],
      "metadata": {
        "total": number,
        "page": number,
        "pageSize": number
      }
    },
    "error": {
      "code": string,
      "message": string,
      "details": any
    }
  }

// Service Layer
- Business Logic:
  * Implement domain-driven design
  * Use service layer pattern
  * Handle proper validation
  * Implement proper error handling
  * Follow SOLID principles
- Data Access:
  * Use repository pattern
  * Implement unit of work
  * Handle transactions
  * Implement proper caching
  * Follow query optimization

// Error Handling
class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public code: string,
    public details?: any
  ) {
    super(message)
    this.name = this.constructor.name
    Error.captureStackTrace(this, this.constructor)
  }
}

// Error Types
- Domain Errors:
  * ValidationError: 400
  * AuthenticationError: 401
  * AuthorizationError: 403
  * NotFoundError: 404
  * ConflictError: 409
  * BusinessError: 422
  * ServerError: 500

// Database Patterns
- Query Optimization:
  * Use proper indexes
  * Implement query caching
  * Handle N+1 problems
  * Use proper joins
  * Monitor query performance
- Data Management:
  * Implement migrations
  * Handle data versioning
  * Implement soft deletes
  * Manage constraints
  * Handle relationships

// Middleware
- Request Pipeline:
  * Authentication
  * Authorization
  * Validation
  * Rate limiting
  * Request logging
- Response Pipeline:
  * Compression
  * CORS handling
  * Error formatting
  * Response logging
  * Cache headers

// Background Jobs
- Job Processing:
  * Use proper queuing
  * Handle retries
  * Implement timeouts
  * Monitor job status
  * Handle failures
- Scheduling:
  * Use proper scheduling
  * Handle timezone issues
  * Monitor execution
  * Handle overlapping
  * Implement logging

// API Documentation
- OpenAPI/Swagger:
  * Document all endpoints
  * Include examples
  * Document errors
  * Show authentication
  * Include schemas
- Implementation:
  * Use TypeScript decorators
  * Generate documentation
  * Keep docs updated
  * Include postman collections
  * Document breaking changes 

- Never `import ide`. When making changes using ide.*, don't try to import the library because you'll get and error, it should already exist in the repl in the context of the current namespace.
- escape nested codeblocks e.g.
```
Markdown
\```
code
\```
more markdown
```
- When using jupyter execute shell commands using either:
  - The `!` operator,
  - The `%` operator, or
  - `os.subprocess` from the `os` library

Chat Commands:
- `/commit` - Commit the current working state, using the git cli, use a variable for the commit message