🤖 Comportamento do Agente IA

Propósito deste ficheiro

Este ficheiro define como um agente IA (assistente de código, Cursor, Copilot, Claude, etc.) deve comportar-se quando trabalha neste projeto.
Lê este ficheiro primeiro antes de qualquer tarefa.

Contexto do projeto

Estás a trabalhar num projeto chamado InventoryAI — uma app móvel de gestão de inventário pessoal com sugestões contextuais.

Lê os seguintes ficheiros para entender o projeto completo:

00_PROJECT_OVERVIEW.md — visão geral e princípios
01_MVP_DEFINITION.md — o que está incluído no MVP
02_ARCHITECTURE.md — stack técnica e modelo de dados
03_AI_VISION_LAYER.md — integração com Google Vision
04_CATEGORIES_AND_TAGS.md — sistema de organização
05_RECOMMENDATION_ENGINE.md — lógica de sugestões
06_FUTURE_FEATURES.md — roadmap futuro

Regras de comportamento

✅ SEMPRE fazer

Verificar o ficheiro MVP antes de implementar qualquer funcionalidade — só implementar o que está em 01_MVP_DEFINITION.md
Respeitar a stack definida em 02_ARCHITECTURE.md — Firebase, React Native, Google Vision
Usar o modelo de dados exatamente como definido (campos, tipos, nomes)
Manter o código simples — se há duas formas, escolher a mais simples
Comentar decisões de arquitetura no código quando relevante
Avisar quando uma funcionalidade pedida está fora do MVP
Perguntar antes de alterar o modelo de dados ou a arquitetura
Criar ficheiros de serviço em src/services/ para lógica de negócio
Usar constantes de src/constants/ para valores fixos (categorias, contextos, etc.)

❌ NUNCA fazer

Adicionar funcionalidades que não estão no MVP sem confirmação explícita
Mudar a stack tecnológica (ex: sugerir Flutter, Supabase, AWS)
Implementar OpenAI no MVP — fica para a Fase 2
Guardar a API key do Google Vision em código client-side em produção
Criar lógica de base de dados fora dos ficheiros services/
Usar console.log em produção para dados sensíveis do utilizador
Alterar os nomes dos campos do modelo de dados sem avisar

Linguagem e comunicação

Comunicar em português (de Portugal, não do Brasil)
Explicações técnicas devem ser claras e objetivas
Quando há uma decisão de arquitetura, explicar o porquê
Usar exemplos de código sempre que possível
Avisos sobre o MVP devem ser visíveis (usar emoji ⚠️ ou bloco de nota)

Ordem de construção obrigatória

Seguir esta ordem ao implementar. Não avançar para o próximo passo sem o anterior estar funcional:

PASSO 1: 📸 Upload de fotos
  └── Câmara + seleção de galeria
  └── Upload para Firebase Storage
  └── URL guardado no estado

PASSO 2: 📦 Guardar itens
  └── Formulário básico (nome, categoria)
  └── Gravar no Firestore
  └── Autenticação Firebase

PASSO 3: 🏷️ Categorização
  └── Integração Google Vision API
  └── Mapeamento labels → categorias
  └── UI de confirmação/edição

PASSO 4: 🔍 Pesquisa e visualização
  └── Lista de itens (grid)
  └── Filtro por categoria
  └── Pesquisa por nome

PASSO 5: 🎯 Sugestões simples
  └── Seleção de contexto
  └── Lógica de filtragem por tags
  └── Apresentação da lista sugerida

Como responder a pedidos fora do MVP

Quando o utilizador pede uma funcionalidade que está fora do MVP:

⚠️ MVP: Esta funcionalidade não está incluída no MVP atual.

Está documentada como [Fase X] em 06_FUTURE_FEATURES.md.

Opções:
1. Adiar para a Fase X (recomendado — manter foco no MVP)
2. Priorizar agora (implica atrasar outras funcionalidades do MVP)

O que preferes?

Padrões de código obrigatórios

Nomenclatura

// Componentes React: PascalCase
ItemCard.jsx
AddItemScreen.jsx

// Serviços e utilitários: camelCase
visionApi.js
suggestions.js

// Constantes: camelCase (ficheiros), UPPER_SNAKE_CASE (valores)
categoryMapping.js → export const LABEL_TO_CATEGORY = { ... }
contexts.js → export const CONTEXTS = [ ... ]

Estrutura de um serviço

// services/exemplo.js

// 1. Imports
import { db } from './firebase';

// 2. Funções puras (sem side effects)
export function processarDados(input) { ... }

// 3. Funções de base de dados
export async function guardarItem(userId, item) { ... }
export async function obterItens(userId) { ... }

Tratamento de erros

// Sempre usar try/catch em chamadas assíncronas
try {
  const resultado = await guardarItem(userId, novoItem);
  // sucesso
} catch (erro) {
  console.error('Erro ao guardar item:', erro.message);
  // mostrar mensagem ao utilizador (não o erro técnico)
  Alert.alert('Erro', 'Não foi possível guardar o item. Tenta novamente.');
}

Perguntas frequentes

P: O utilizador pediu uma funcionalidade — implemento já?
R: Verificar 01_MVP_DEFINITION.md. Se estiver no MVP, implementar. Se não, avisar e perguntar.

P: Posso usar uma biblioteca nova?
R: Só se resolver um problema que não tem solução simples sem ela. Avisar antes de instalar.

P: O modelo de dados precisa de um campo novo — adiciono?
R: Avisar o utilizador, explicar o impacto, aguardar confirmação.

P: A API do Google Vision não está a funcionar nos testes — o que fazer?
R: Criar um mock local (services/visionApiMock.js) que retorna dados fixos para desenvolvimento.

Ficheiros de referência rápida

Quero saber...	Ficheiro
O que está no MVP?	`01_MVP_DEFINITION.md`
Que tecnologias usar?	`02_ARCHITECTURE.md`
Como a IA de imagem funciona?	`03_AI_VISION_LAYER.md`
Que categorias existem?	`04_CATEGORIES_AND_TAGS.md`
Como funcionam as sugestões?	`05_RECOMMENDATION_ENGINE.md`
O que vem a seguir?	`06_FUTURE_FEATURES.md`

5.9 KiB Raw Blame History