Como montar um contexto de projeto para a IA não te dar respostas genéricas

Entendendo o poder do contexto

System prompts: o alicerce do contexto

Stack tecnológico

Framework: Next.js 14 com App Router
Linguagem: TypeScript (strict mode)
Styling: Tailwind CSS v3.3
State: Zustand para gerenciamento global
Testing: Vitest + React Testing Library
Node.js: 18+

Padrões e convenções do projeto

// ✅ Componentes: PascalCase (exemplo)
export function UserProfile() {
  return <div>User Profile</div>;
}

// ✅ Hooks customizados: camelCase com prefixo 'use'
export function useAuthForm() {
  const [email, setEmail] = useState('');
  return { email, setEmail };
}

// ✅ Funções utilitárias: camelCase
export function formatCurrency(value: number): string {
  return new Intl.NumberFormat('pt-BR', {
    style: 'currency',
    currency: 'BRL',
  }).format(value);
}

// ✅ Tipos: arquivo .types.ts
// types/user.types.ts
export interface User {
  id: string;
  email: string;
  name: string;
}

// ✅ Testes: co-locados com sufixo .test.ts
// UserProfile.test.ts
import { render, screen } from '@testing-library/react';
import { UserProfile } from './UserProfile';

describe('UserProfile', () => {
  it('should render user profile', () => {
    render(<UserProfile />);
    expect(screen.getByText(/User Profile/i)).toBeInTheDocument();
  });
});

Requisitos não funcionais

• Acessibilidade: WCAG 2.1 AA obrigatório

• Performance: Lighthouse score acima de 90

• Segurança: validação em cliente e servidor

• SEO: meta tags dinâmicas em todas as páginas

Workspace instructions: a visão 360 do projeto

Estrutura e arquitetura

/apps
  /web                    # Aplicação Next.js principal
  /admin                  # Painel administrativo
/packages
  /ui                     # Componentes compartilhados
  /api-client             # Cliente HTTP centralizado
  /utils                  # Funções utilitárias comuns
  /types                  # Tipos TypeScript compartilhados
/docs
  /context                # Documentação de contexto

Modelos de domínio

// User Domain
interface User {
  id: string;
  email: string;
  role: 'customer' | 'admin';
}

// Product Domain
interface Product {
  id: string;
  name: string;
  price: number;
  inventory: number;
}

// Order Domain
interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  status: 'pending' | 'processing' | 'shipped' | 'delivered';
  total: number;
}

interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

// Payment Domain
interface Payment {
  id: string;
  orderId: string;
  provider: 'stripe' | 'paypal';
  status: 'pending' | 'completed' | 'failed';
  amount: number;
}

Exemplo prático: montando um contexto de verdade

Stack

Frontend:
  - Next.js 14 (App Router)
  - React 18
  - TypeScript 5

Backend:
  - Node.js/Express
  - API RESTful

Database:
  - PostgreSQL
  - Prisma ORM

Styling:
  - Tailwind CSS
  - shadcn/ui

State Management:
  - Zustand (client state)
  - React Query (server state)

Authentication:
  - NextAuth.js com JWT

Arquitetura

Monorepo com Turborepo
Separação clara entre /apps/web, /apps/api e /packages
DDD com contextos delimitados (User, Product, Order, Payment)

Padrões de código

// ✅ Exemplo de componente reutilizável
'use client';

import { ComponentPropsWithoutRef } from 'react';
import { cn } from '@/packages/utils';

interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
}

export function Button({
  variant = 'primary',
  size = 'md',
  className,
  ...props
}: ButtonProps) {
  return (
    <button
      className={cn(
        'font-medium rounded transition-colors',
        variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
        variant === 'secondary' && 'bg-gray-200 text-gray-900 hover:bg-gray-300',
        size === 'sm' && 'px-3 py-1 text-sm',
        size === 'md' && 'px-4 py-2 text-base',
        size === 'lg' && 'px-6 py-3 text-lg',
        className
      )}
      {...props}
    />
  );
}

// ✅ Exemplo de hook com lógica de domínio
import { useCallback, useState } from 'react';
import { useQuery, useMutation } from '@tanstack/react-query';
import { apiClient } from '@/packages/api-client';
import type { Order } from '@/packages/types';

export function useOrders() {
  const [error, setError] = useState<string | null>(null);

  const { data: orders, isLoading } = useQuery({
    queryKey: ['orders'],
    queryFn: async () => {
      const response = await apiClient.get('/orders');
      return response.data as Order[];
    },
  });

  const createOrderMutation = useMutation({
    mutationFn: async (orderData: Omit<Order, 'id'>) => {
      return apiClient.post('/orders', orderData);
    },
    onError: (err: any) => {
      setError(err.message);
    },
  });

  return { orders, isLoading, createOrder: createOrderMutation.mutate, error };
}

// ✅ Exemplo de teste
import { renderHook, waitFor } from '@testing-library/react';
import { useOrders } from './useOrders';

describe('useOrders', () => {
  it('should fetch orders', async () => {
    const { result } = renderHook(() => useOrders());

    await waitFor(() => {
      expect(result.current.isLoading).toBe(false);
    });

    expect(result.current.orders).toBeDefined();
  });
});

Requisitos críticos

Performance:
  - Pré-renderização da landing page
  - Images otimizadas com next/image
  - Code splitting automático

Conversão:
  - Checkout em menos de 3 cliques
  - Formulários com validação em tempo real
  - Feedback visual imediato

Segurança:
  - CSRF protection
  - Validação de inputs (zod/yup)
  - Rate limiting em APIs

SEO:
  - Metadata dinâmica
  - Structured data (JSON-LD)
  - Sitemap.xml gerado automaticamente

Onde colocar seu contexto

# Contexto do Projeto

## Stack
- Next.js 14, React 18, TypeScript 5
- Zustand + React Query
- Tailwind CSS + shadcn/ui
- Vitest + RTL

## Convenções
- Componentes: PascalCase
- Hooks: useXXX em camelCase
- Tipos: arquivo .types.ts
- Testes: co-locados com .test.ts

## Padrões
- DDD com contextos delimitados
- Componentes sem lógica de negócio
- Hooks para toda lógica stateful
- Mínimo 80% de cobertura de testes

node_modules/
.next/
dist/
build/
*.log
.env.local
.DS_Store

Testando seu contexto

• Uso de Tailwind CSS com cn() utility

• TypeScript com tipos Props

• Suporte a variantes (primary/secondary)

• Padrões do projeto (PascalCase, estrutura esperada)

• Exemplo de uso correto

Puxe a IA para dentro do seu universo