Visão e Stack

Duas seções que respondem às perguntas mais básicas: o que é este projeto (Visão) e onde e com o que ele roda (Stack). As duas servem para você, para um sócio que acabou de chegar e para um dev que vai assumir o código.

Como o painel do projeto se organiza

Antes das seções, vale saber como navegar dentro de um projeto:

• O menu lateral começa pelo Insights (o painel que abre junto com o projeto) e separa as outras seções em três grupos, pelo que você vai fazer:
• Projeto, para entender o projeto: Visão, Arquitetura, Stack e Mapa do código.
• Trabalho, para acompanhar o trabalho: Funcionalidades, Memória, Workflows, Atividade e Proteção.
• Qualidade, para conferir antes de lançar: Design, Qualidade, Testes, Erros, Segurança e Lançamento.
• Configurações fica no fim do menu, separada dos grupos.
• Cada seção tem abas no topo. As abas com coleções mostram um contador, por exemplo quantos problemas estão abertos.
• Toda seção termina com a aba Comandos: os comandos daquela parte, com o que fazem e um exemplo pronto para copiar.
• A seção e a aba ficam no endereço da página. Dá para mandar o link direto de uma aba para alguém do time.
• Quase tudo se atualiza em tempo real: você vê o agente trabalhando sem recarregar a página.
• Quando a língua do conteúdo do projeto é diferente da língua do painel, aparece o botão Traduzir no topo da página. Veja abaixo.
• Quem tem o papel Leitura vê um aviso no topo e não encontra os botões que mudam algo.

Língua do conteúdo

Tudo o que o Faundr registra no projeto (Visão, Stack, arquitetura, funcionalidades, decisões, achados, bilhetes de passagem, design.md) é escrito numa língua só, a língua do conteúdo: inglês ou português. Ela vale para o projeto inteiro, seja qual for a língua em que cada pessoa conversa com o agente. O agente continua respondendo a cada pessoa na língua dela.

• Onde escolher: em Configurações → Geral, no card Língua do conteúdo. Num projeto novo, ela começa pela língua da tela; num projeto antigo ainda sem língua, fica definida na próxima sessão do agente, pela língua de quem estiver trabalhando.
• Trocar depois vale só para o conteúdo novo. O que já existe fica como está. Para reescrever na língua nova, peça ao agente (/faundr:overview, /faundr:stack, "desenhe a arquitetura do projeto", /faundr:design, /faundr:design-showcase). Cada um lê o projeto de novo e gasta tokens do seu plano de IA, mais ou menos o mesmo que da primeira vez; o card mostra quanto cada um gastou da última vez.
• Traduzir: quem lê o painel na outra língua pode usar o botão Traduzir para português (ou Traduzir para inglês) no topo da página do projeto. A tradução é feita pelo tradutor que vem no navegador (Chrome), no seu computador, sem gastar tokens. Código, caminhos de arquivo e comandos ficam como estão. Na primeira vez, o navegador baixa o tradutor e o botão mostra o progresso. Para voltar ao texto de antes, clique em Mostrar original. O botão só aparece quando o navegador tem o tradutor.

Visão

A Visão é o resumo do projeto em linguagem para quem não programa. Ela é escrita pelo agente a partir do próprio código e dos documentos, quando você roda /faundr:overview.

Abas

No Resumo aparece também quando a Visão foi escrita e em que commit.

Arquitetura

A arquitetura tem um item próprio no menu do projeto, Arquitetura: um canvas sempre aberto, com zoom e arrastar como os outros canvas do painel. Ele mostra as partes do sistema e como elas conversam, em camadas: quem usa, telas, servidor, dados e serviços de fora. É opcional e aparece quando você pede ao agente, no começo do projeto ou com "desenhe a arquitetura do projeto".

• Clique numa peça para abrir a explicação: o que ela é, de onde recebe e para onde manda, onde mora no código e se já existe.
• Planejado x construído: no início de cada sessão, o plugin confere sozinho (sem IA) se cada parte já existe no código. A que ainda é só plano aparece apagada, e o cabeçalho diz quantas partes já existem. O canvas se atualiza sozinho.
• Fora do plano: o botão no canto lista as pastas com código que não estão em nenhuma parte (sem testes, docs, configuração nem imagens). Quando surge uma pasta nova, o agente avisa no terminal e sugere em qual parte ela entra; a arquitetura só muda com o seu OK. Se uma pasta fica fora do plano de propósito (ex.: scripts de uso único), clique em Fora de propósito nela, com um motivo se quiser: ela sai da lista na hora, a conferência para de avisar sobre ela e fica numa lista recolhida com quem marcou, o motivo e o botão Voltar. Isso vale só para o Fora do plano: a pasta continua no Mapa do código e nas checagens. Para tirar uma pasta de tudo (código de terceiros, arquivos gerados), use o .faundrignore. Só quem edita o projeto marca ou volta.
• Encaixar pastas novas sozinho: interruptor no painel Fora do plano, desligado por padrão. Ligado, quando surge uma pasta nova o agente põe a pasta na parte mais provável da arquitetura sem perguntar e avisa em uma linha onde pôs (se nenhuma parte servir, ele sugere em vez de criar uma parte nova). Desligado, ele só sugere e espera o seu OK.

Num projeto que está começando

Sem código ainda, conte a ideia ao agente ou use /faundr:planning <ideia>. Ele faz poucas perguntas de produto (quem usa, o momento principal, o que entra na primeira versão), mostra um resumo para você aprovar e, com o OK, escreve a Visão a partir da conversa: as partes do sistema entram como Planejado, as etapas vão para Funcionalidades (a primeira como a atual) e, se você quiser, a arquitetura aparece desenhada em Arquitetura, no menu do projeto. Conforme o código aparece, o /faundr:overview atualiza a Visão a partir do projeto de verdade.

Manter a Visão em dia

Você não precisa lembrar de atualizar. Quando o projeto muda o suficiente para a Visão ficar desatualizada, o Faundr pede ao agente, no fim de uma resposta, para atualizá-la (uma vez por sessão). Para forçar a qualquer momento, rode /faundr:overview.

Com o modo econômico ligado (em Configurações → Geral), a Visão e a Stack deixam de se atualizar sozinhas no fim das respostas e ficam só para quando você pedir. Veja Configurações.

Comandos da Visão

Stack

A Stack mostra onde cada parte do projeto roda e com o quê. Ela tem duas camadas:

• A leitura automática, sem IA, feita no início de cada sessão: pacotes, arquivos de configuração de deploy e variáveis de ambiente (só os nomes).
• A explicação da IA, em linguagem clara, quando você roda /faundr:stack. Ela completa o que os arquivos não dizem: conte ao agente, por exemplo, onde o domínio está registrado ou que o deploy é automático pelo GitHub.

No topo de todas as abas há uma linha de estado: "Revisada pela IA em…" ou "Lida automaticamente dos arquivos, sem a explicação da IA". Se os arquivos mudaram depois da revisão, aparece a etiqueta Mudou desde a revisão, dizendo o que entrou e o que saiu, com o botão para atualizar.

Abas

Variáveis: cada uma está onde precisa?

O problema mais comum de um app que "funciona no meu computador e não no ar" é uma variável de ambiente faltando em algum lugar. O card Cada variável está onde precisa? cruza quatro lugares para cada variável:

E aponta os problemas:

• Quebra no ar: o código usa, mas a hospedagem não tem. O app publicado vai falhar.
• Falta no seu computador: o código usa, mas o seu .env não tem.
• Fora do arquivo de exemplo: existe, mas ninguém documentou.
• Sobrando: está configurada, mas o código não usa mais.

A coluna No ar só aparece depois de !faundr env-check --hosting, que consulta a hospedagem pela CLI do provedor (ela precisa estar logada no seu computador).

Na lista de variáveis, a etiqueta Navegador marca as que vão para o navegador, ou seja, que qualquer pessoa consegue ver (prefixos como VITE_ e NEXT_PUBLIC_). Elas nunca devem guardar segredos.

Comandos da Stack