Pular para o conteúdo principal

Gerenciando Contexto Entre Ferramentas de Codificação IA e Sessões do Cursor

Cursor Context Management

Um dos maiores desafios ao trabalhar com assistentes de codificação IA é manter o contexto entre sessões e ferramentas. O Cursor fornece vários mecanismos para preservar e compartilhar o contexto do projeto, garantindo que seu assistente de IA sempre tenha as informações de que precisa. Este guia cobre as melhores práticas para gerenciamento de contexto.

O Problema de Contexto​

Ao trabalhar com ferramentas de IA, você frequentemente enfrenta esses desafios:

  • Amnésia de sessão: Cada novo chat começa do zero sem memória do trabalho anterior
  • Mudança de ferramenta: Mover entre Cursor, Claude, ChatGPT ou outras ferramentas perde o contexto
  • Compartilhamento de equipe: Os membros da equipe precisam de acesso ao mesmo contexto do projeto
  • Deriva de contexto: Ao longo de sessões longas, a IA perde o rastreamento dos objetivos originais

Solução 1: AGENTS.md - A Constituição do Projeto​

Crie um arquivo AGENTS.md na raiz do seu repositório. Esta é a única fonte de verdade para todas as ferramentas de IA.

Estrutura do AGENTS.md​

# Projeto: MyApp

## Visão Geral
Breve descrição do que este projeto faz e sua stack de tecnologia.

## Stack de Tecnologia
- Frontend: React 18 + TypeScript + Tailwind CSS
- Backend: Node.js + Express + PostgreSQL
- Testes: Jest + React Testing Library
- Build: Vite

## Estrutura do Projeto

src/ components/ # Componentes UI reutilizáveis pages/ # Páginas no nível de rota hooks/ # Hooks React personalizados utils/ # Funções auxiliares types/ # Tipos TypeScript api/ # Funções cliente de API


## Comandos de Build & Teste
```bash
npm run dev       # Iniciar servidor de desenvolvimento
npm run build     # Build de produção
npm run test      # Executar testes
npm run lint      # Executar ESLint

Padrões de Codificação​

  • Usar componentes funcionais com hooks
  • Seguir a organização de arquivos existente
  • Escrever testes para todos os novos recursos
  • Usar o modo strict do TypeScript

Decisões Principais​

  • Usando React Query para gerenciamento de estado do servidor
  • Tokens JWT armazenados em cookies httpOnly
  • Estrutura monorepo com pacote de tipos compartilhados

### Referenciando AGENTS.md no Cursor

No início de cada novo chat:

Leia o AGENTS.md e me ajude a implementar [recurso]. Siga todos os padrões de codificação e use os padrões existentes.


## Solução 2: Regras Específicas do Cursor

Crie `.cursor/rules/` para diretrizes específicas do Cursor:

```markdown
---
description: 'Comportamento específico do Cursor para o projeto'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# Diretrizes do Cursor

## Antes de Fazer Alterações
1. Ler AGENTS.md para contexto do projeto
2. Verificar implementações similares existentes
3. Seguir os padrões estabelecidos

## Preferências de Geração de Código
- Gerar TypeScript com tipos explícitos
- Incluir comentários JSDoc para APIs públicas
- Usar o padrão de tratamento de erros existente

## Requisitos de Teste
- Sempre sugerir testes para novos recursos
- Usar React Testing Library para componentes
- Simular chamadas de API com MSW

Solução 3: Memória de Sessão com MCP​

Use servidores MCP (Model Context Protocol) para memória persistente:

Configurando Memória MCP​

Adicione às suas configurações MCP do Cursor:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@cursor-memory/server"]
    }
  }
}

Usando Memória​

Armazene fatos importantes:

Lembre-se de que estamos usando PostgreSQL com uma tabela users que tem:
- id (UUID, chave primária)
- email (único, indexado)
- created_at (timestamp)
- preferences (JSONB)

Recupere em sessões futuras:

O que você se lembra sobre nosso esquema de banco de dados?

Solução 4: O Padrão CONTRACT.md​

Para projetos complexos, use um arquivo de contrato que define invariantes:

# Contrato do Projeto

## Invariantes (Nunca Violar)
1. Todas as respostas da API devem incluir um booleano `success`
2. IDs de usuário são sempre UUIDs, nunca inteiros
3. Senhas nunca são registradas ou retornadas nas respostas

## Regras de Arquitetura
1. A lógica de domínio reside em `src/domain/`
2. As rotas de API apenas delegam para serviços
3. O acesso ao banco de dados é feito apenas através do padrão repository

## Objetivos da Sprint Atual
- Implementar autenticação de usuário
- Adicionar fluxo de redefinição de senha
- Configurar notificações por email

Atualize este arquivo após cada mudança significativa.

Solução 5: Resumos de Sessão​

No final de cada sessão, crie um resumo:

# Resumo da Sessão: 2026-06-22

## Concluído
- [x] Configurar middleware de autenticação JWT
- [x] Criar endpoints de login e registro
- [x] Adicionar hash de senha com bcrypt

## Em Andamento
- [ ] Fluxo de verificação de email (iniciado, precisa de testes)

## Próximos Passos
1. Implementar redefinição de senha com expiração de token
2. Adicionar rate limiting aos endpoints de autenticação
3. Escrever testes de integração

## Arquivos Principais Modificados
- src/middleware/auth.ts (novo)
- src/routes/auth.ts (novo)
- src/services/auth.ts (novo)
- src/models/user.ts (modificado)

## Decisões Tomadas
- Usando expiração JWT de 15 minutos com tokens de atualização
- Armazenando tokens de atualização no Redis

Salve isso como docs/session-summaries/YYYY-MM-DD.md.

Solução 6: Contexto Entre Ferramentas com Markdown​

Ao alternar entre ferramentas, use um formato de contexto padronizado:

# Transferência de Contexto

## Tarefa Atual
Implementando página de perfil de usuário

## Arquivos Relevantes
- src/pages/Profile.tsx
- src/components/UserForm.tsx
- src/api/users.ts

## Estado Atual
- Esqueleto da página de perfil criado
- Componente UserForm precisa de validação
- Endpoint de API /api/users/me retorna dados corretos

## Bloqueios
- Precisa decidir sobre a abordagem de upload de imagens

## Próxima Ação
Adicionar validação de formulário e manipulador de envio

Copie isso em qualquer ferramenta de IA para continuar de forma contínua.

Resumo das Melhores Práticas​

O que Fazer​

  • Criar AGENTS.md no início do projeto
  • Atualizar AGENTS.md quando a arquitetura mudar
  • Usar regras do Cursor para diretrizes específicas da ferramenta
  • Resumir cada sessão antes de fechar
  • Armazenar fatos persistentes com memória MCP
  • Usar controle de versão para todos os arquivos de contexto

O que Não Fazer​

  • Não confiar apenas na memória de sessão da IA
  • Não manter contexto em notas externas (Obsidian/Notion) sem sincronização
  • Não deixar os arquivos de contexto ficarem desatualizados
  • Não duplicar informações entre vários arquivos

Lista de Verificação de Início Rápido​

Para um novo projeto:

  1. Criar AGENTS.md com visão geral do projeto
  2. Configurar .cursor/rules/ para comportamento do Cursor
  3. Configurar servidor de memória MCP
  4. Criar CONTRACT.md para invariantes de arquitetura
  5. Configurar diretório docs/session-summaries/
  6. Adicionar todos os arquivos de contexto ao controle de versão

Recursos Relacionados​