Pular para o conteúdo principal

Dominando Grandes Bases de Código com Cursor, Gemini e Claude: Um Guia Prático

1. Configuração do Projeto: Estabelecendo a Base para Colaboração com IA​

Pense em seu projeto como uma oficina bem organizada onde você e seus colaboradores de IA (Gemini e Claude) construirão algo incrível. O primeiro passo é configurar a oficina adequadamente.

1.1. Definindo as Regras de Engajamento com .cursorrules​

Assim como qualquer oficina precisa de regras, seus colaboradores de IA precisam de diretrizes. Crie um arquivo .cursorrules na raiz do seu projeto. Este arquivo atua como uma constituição, definindo como a IA deve interagir com seu código.

Por quê: Isso garante que todos (você e a IA) estejam na mesma página em relação a prioridades, padrões de codificação e como abordar tarefas.

Exemplo .cursorrules:

{
    "rules": {
        "context_initialization": {
            "description": "Ponto de partida para cada interação",
            "steps": [
                "SEMPRE leia `.notes/project_overview.md` e `.notes/task_list.md`"
            ]
        },
        "operational_protocol": {
            "description": "Como abordar tarefas",
            "before_action": [
                "Criar uma divisão de tarefas MECE"
            ],
            "code_changes": [
                "Ler seções relevantes do código antes de editar",
                "Preservar funcionalidade existente",
                "Manter segurança de tipos"
            ]
        },
        "safety_requirements": [
            "NUNCA quebrar segurança de tipos",
            "SEMPRE manter tratamento adequado de erros",
            "SEMPRE documentar novo código"
        ],
        "priorities": [
            {
                "source": ".notes/",
                "weight": 1.0
            }
        ],
        "modes": {
            "base": {
                "description": "Para tarefas rotineiras"
            },
            "enhanced": {
                "description": "Para problemas complexos"
            }
        },
        "project_directives": {
            "name": "my_project",
            "ai_first": true
        }
    }
}

1.2. Controlando Visibilidade de Arquivos com .cursorignore​

Use .cursorignore para dizer aos seus assistentes de IA o que ignorar, similar a como você usaria um .gitignore para controle de versão.

Por quê: Isso mantém a IA focada nas partes essenciais do seu projeto, reduzindo ruído e melhorando a eficiência.

Exemplo .cursorignore:

/node_modules
/build
/temp
.DS_Store

1.3. Estabelecendo um Hub Central com .notes​

Todo projeto precisa de um hub central para informações. Crie um diretório .notes para armazenar toda a documentação relacionada ao projeto, notas de reunião, diagramas arquiteturais e logs de interação com IA. Pense nele como o "cérebro" ou "base de conhecimento" do seu projeto.

Por quê: Isso garante que você e seus colaboradores de IA tenham um entendimento compartilhado dos objetivos, status e histórico do projeto.

Arquivos Principais em .notes:

  • project_overview.md: Uma descrição de alto nível do seu projeto, seus objetivos e arquitetura.
  • task_list.md: Uma lista detalhada de tarefas, seu status (ex., "A Fazer", "Em Progresso", "Concluído"), prioridades e quaisquer notas relevantes.
  • directory_structure.md: Uma visão geral automaticamente atualizada da estrutura de diretórios do seu projeto. Isso ajuda a IA a entender onde diferentes componentes de código estão localizados.
  • meeting_notes.md: Um registro de suas interações com a IA, incluindo perguntas feitas, respostas recebidas e decisões tomadas.

2. Gerenciando .notes e Contexto Compartilhado​

Imagine que você está trabalhando com uma equipe de pessoas. Para colaborar efetivamente, você precisa garantir que todos tenham um entendimento compartilhado do projeto como scrum/kanban/plano de projeto. É aqui que usar documentos markdown como blocos de notas compartilhados entra em jogo.

2.1. Preenchendo project_overview.md​

Este documento é como o "elevator pitch" do seu projeto. Ele deve fornecer uma visão geral concisa do que é seu projeto, seus objetivos, sua arquitetura de alto nível e (opcionalmente, mas altamente recomendado) algumas jornadas de usuário de exemplo.

Exemplo:

# Visão Geral do Projeto

## Objetivo

Construir uma aplicação web que permite aos usuários criar e gerenciar listas de tarefas.

## Arquitetura

- **Frontend:** Aplicação React usando TypeScript.
- **Backend:** API serverless usando Node.js e um banco de dados na nuvem.
- **Gerenciamento de Estado:** Usando uma solução personalizada de gerenciamento de estado baseada em hooks React.

## Recursos Principais

- Autenticação de usuário
- Criar, editar e excluir listas de tarefas
- Marcar tarefas como concluídas
- Sincronização em tempo real

2.2. Criando task_list.md​

Este arquivo é a "lista de tarefas" do seu projeto. Ele deve rastrear todas as tarefas, seu status, prioridades e quaisquer notas relevantes.

Exemplo:

# Lista de Tarefas

## Alta Prioridade

- [ ] Implementar fluxo de autenticação de usuário. (**Status:** Em Progresso, **Atribuído Para:** Gemini, **Notas:** Atualmente trabalhando no componente de login.)
- [ ] Projetar esquema do banco de dados. (**Status:** A Fazer, **Atribuído Para:** Claude, **Notas:** Precisa considerar escalabilidade.)

## Média Prioridade

- [ ] Criar UI básica para criação de lista de tarefas. (**Status:** A Fazer, **Atribuído Para:** Gemini, **Notas:** Aguardando autenticação ser concluída.)

## Baixa Prioridade

- [ ] Adicionar suporte para categorização de tarefas. (**Status:** A Fazer, **Atribuído Para:** Nenhum, **Notas:** Pode ser implementado depois.)

## Concluído

- [x] Configurar estrutura do projeto.
- [x] Criar componentes React básicos para cabeçalho e rodapé.

2.3. Gerando directory_structure.md​

Este arquivo fornece um mapa do layout do seu projeto. Você pode criá-lo manualmente ou usar um script para gerá-lo automaticamente.

Exemplo (Manual):

# Estrutura de Diretórios

- **components/**: Componentes UI reutilizáveis (ex., Button, Input, List)
- **hooks/**: Hooks React personalizados (ex., useAuth, useData)
- **lib/**: Funções utilitárias e clientes API
- **pages/**: Páginas de aplicação de alto nível (ex., Home, Login, Register)
- **styles/**: Estilos globais e definições de tema

Exemplo de Script (PowerShell):

# Salvar como update_directory.ps1
$projectRoot = "."
$outputFile = "./.notes/directory_structure.md"

# Gerar listagem de diretório
function Get-FormattedDirectory {
    param (
        [string]$path,
        [int]$indent = 0
    )

    $indentString = "    " * $indent
    $content = ""

    foreach ($item in Get-ChildItem -Path $path -Force) {
        if ($item.PSIsContainer) {
            $content += "$indentString- **$($item.Name)/**`n"
            $content += Get-FormattedDirectory -path $item.FullName -indent ($indent + 1)
        } else {
            $content += "$indentString- $($item.Name)`n"
        }
    }
    return $content
}

# Gerar conteúdo para arquivo markdown
$markdownContent = @"
# Estrutura de Diretório Atual

## Componentes Principais

$(Get-FormattedDirectory -path $projectRoot)

"@

# Saída para arquivo
$markdownContent | Out-File -FilePath $outputFile -Encoding UTF8

Write-Host "Estrutura de diretório atualizada em $($outputFile)"

3. Domínio de Prompts e Focando Conversas​

Agora que você configurou uma "oficina" digital com você, Claude e Gemini todos na mesma página através dos documentos criados acima, é hora de começar a trabalhar com o Compositor no modo Normal com Gemini. É aqui que a arte do prompting entra em jogo.

3.1. Por que o Contexto é Crucial?​

  • Foco: Como um holofote, o contexto ajuda a IA a focar nas partes relevantes da sua base de código, ignorando detalhes irrelevantes.
  • Precisão: Um entendimento compartilhado dos objetivos, status e arquitetura do projeto garante que as respostas sejam precisas e alinhadas com suas intenções.
  • Consistência: Você pode ajudar a IA a manter a integridade arquitetural do seu projeto, impedindo-a de fazer mudanças que possam quebrar funcionalidade existente ou introduzir inconsistências.

3.2. Usando @ para Focar a IA​

O símbolo @ é sua ferramenta principal para fornecer contexto ao Gemini e Claude dentro do Cursor. É como apontar para um documento específico ou seção de código durante uma conversa.

Exemplos:

  • @components/Button.tsx: "Ei Gemini, vamos focar neste componente específico."
  • @.notes/task_list.md: "Claude, dê uma olhada na lista atual de tarefas e prioridades."
  • @.notes/project_overview.md: "Gemini, lembra dos objetivos gerais e arquitetura que discutimos?"

3.3. Fundamentando Respostas da IA com Precisão e Consistência​

  • Seja Específico: Faça perguntas diretas e específicas. Evite linguagem vaga ou ambígua.
    • Em vez de: "Como posso melhorar este código?"
    • Tente: "Gemini, como posso tornar a função handleSubmit em @components/LoginForm.tsx mais eficiente?"
  • Use MECE: MECE (Mutuamente Exclusivo, Coletivamente Exaustivo) é uma técnica poderosa de resolução de problemas. Divida tarefas complexas em subtarefas menores e não sobrepostas.
    • Exemplo: "Claude, vamos dividir a implementação do fluxo de autenticação de usuário usando MECE:
      1. Entrada do Usuário: Lidar com entrada de nome de usuário e senha.
      2. Chamada API: Enviar credenciais para a API de autenticação.
      3. Tratamento de Resposta: Processar a resposta da API (sucesso ou erro).
      4. Atualização de Estado: Atualizar o estado da aplicação baseado no resultado da autenticação. O que você acha desta divisão? Alguma sugestão?"
  • Itere e Refine: Não espere resultados perfeitos na primeira tentativa. Engaje em um diálogo iterativo com a IA. Forneça feedback sobre suas sugestões, faça perguntas esclarecedoras e refine seus prompts baseado em suas respostas.
    • Exemplo: "Gemini, sua sugestão para otimizar a função handleSubmit é boa, mas não aborda o potencial para condições de corrida. Como podemos modificá-la para lidar com esse cenário?"
  • Pergunte "Por quê": Encoraje a IA a explicar seu raciocínio. Isso ajuda você a entender seu processo de pensamento e identificar possíveis mal-entendidos.
    • Exemplo: "Claude, por que você recomendou usar esta abordagem particular de gerenciamento de estado em vez daquela descrita em @.notes/project_overview.md?"