# Promovaweb > A Promovaweb é uma iniciativa focada em Martech, IA e infraestrutura soberana (Self-Hosted). ## Recursos Principais - [Planos](https://promovaweb.com/planos): Martech, IA Makers, Founders, DevOps. - [Blog](https://promovaweb.com/blog): Artigos técnicos profundos sobre automação, CRM e desenvolvimento. - [Podcast](https://promovaweb.com/podcasts): PromovaCast - Discussões sobre o futuro da tecnologia e negócios. - [Ebooks](https://promovaweb.com/ebooks): Materiais aprofundados sobre os mesmos temas. - [Changelog](https://promovaweb.com/changelog): Registro público de atualizações dos sistemas da Promovaweb. ## Stack Tecnológica - Astro, Tailwind CSS, TypeScript, n8n, Mautic, Chatwoot, Metabase. ## Opcional - [Contato](https://promovaweb.com/contato): Fale com a equipe. - [Termos](https://promovaweb.com/terms): Termos de uso do site. - [Conteúdo integral](https://promovaweb.com/llms-full.txt): versão completa do conteúdo editorial publicado. --- # Conteúdo integral Este arquivo reúne o texto integral do conteúdo editorial publicado no site. Cada seção informa a URL absoluta da página correspondente. --- ## Blog ### Escrever código à mão com agentes de IA vale a pena? - URL: https://promovaweb.com/blog/agentes-codigo-manual-excecao - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda quando escrever código à mão continua útil com agentes de IA e como comparar implementação, testes e manutenção na revisão. Leia o artigo. Corrigir uma mensagem de erro no código pode levar menos tempo do que explicar ao agente onde ela aparece. Isso acontece num trecho que você conhece, com uma alteração pequena e um teste já disponível. Em outra tarefa, localizar as chamadas e escrever uma primeira implementação pode consumir horas. Tratar as duas situações como se exigissem o mesmo modo de trabalho atrapalha a escolha entre editar e delegar. Eu usaria o agente onde a delegação reduz o trabalho total da alteração. A pergunta inclui o tempo de orientar e revisar, além do tempo que você levaria para escrever. A facilidade de gerar código não torna uma edição direta um problema. ## Direto ao ponto Escrever código à mão continua útil para uma correção localizada, para investigar uma falha e para aprender o funcionamento de um trecho. O agente oferece outra forma de produzir a implementação. Você pode alternar entre as duas na mesma tarefa, preservando o teste que demonstra o resultado. A delegação deixa de economizar trabalho quando a revisão precisa desfazer mudanças adicionais que você não solicitou. Para mim, a correção dessa mensagem deve permanecer pequena e compreensível. A alteração precisa ter tamanho compatível com o problema. ## Código manual na correção de uma mensagem Considere um formulário hipotético que aceita uma data de nascimento. Ao receber `31/02/2026`, ele informa apenas que houve um erro. Você quer explicar que a data não existe, mantendo a validação atual e o comportamento dos demais campos. O trecho responsável já está localizado e o teste existente reproduz essa entrada. Editar a mensagem diretamente pode concluir a implementação. O agente também pode fazer a alteração, mas não há necessidade de transformar uma linha conhecida numa tarefa extensa para justificar o uso da ferramenta. Uma proposta que reescreve o formulário exige conferir se ela preservou a validação da data vazia e o modo de apresentar os demais erros. A nova organização pode funcionar, mas a correção da mensagem não explica por que os outros componentes precisariam mudar. A edição localizada muda o retorno esperado, enquanto a reorganização altera componentes que participam de outras situações. Recusar esse trabalho adicional mantém a revisão ligada ao problema que você queria corrigir. O artigo sobre [revisão de código gerado por IA com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao) aprofunda a leitura dessas alterações no repositório. ## A investigação também pode ser delegada Agora considere que a mensagem vem de um serviço que você ainda não conhece. Localizar o retorno e identificar os pontos que o utilizam exige leitura. O agente pode pesquisar o repositório e apresentar os arquivos relevantes, permitindo que você acompanhe a investigação sem começar por uma busca manual em cada diretório. Essa colaboração não obriga a delegar a edição final. Você pode aproveitar a pesquisa, abrir o trecho indicado e fazer a correção. Também pode escrever o teste e deixar a implementação com o agente. Dividir a tarefa dessa forma permite usar a ferramenta no trabalho para o qual ela foi útil. A explicação gerada precisa corresponder ao arquivo encontrado. Uma mensagem exibida na interface pode ser produzida no servidor e traduzida por outro componente. Conferir essa relação impede corrigir somente a demonstração visual enquanto a resposta original continua incorreta em outra tela. O artigo sobre [Codex e Claude Code em projetos separados no Herdr](https://promovaweb.com/blog/herdr-codex-claude-projetos) acompanha a organização das sessões usadas nesse trabalho. O estudo da [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding) se relaciona a essa construção acompanhada. Você aprende a orientar a investigação e a interpretar a alteração, em vez de medir a prática pela quantidade de código delegada. ## O exemplo inválido precisa chegar ao teste Um teste que confirma a existência do campo de data não demonstra a correção da mensagem. A entrada `31/02/2026` precisa percorrer a validação e produzir o retorno combinado. O mesmo exemplo permite avaliar a edição direta e a implementação do agente. A data ausente merece outro teste porque representa outra situação. Uma alteração que troca qualquer erro pelo texto “data inexistente” resolveria a demonstração inicial e pioraria o formulário vazio. Você identifica essa diferença pela relação entre as entradas e as mensagens, sem precisar reorganizar o formulário inteiro. Nesse ponto, eu manteria a conferência tão localizada quanto a correção. Acrescentar testes dos comportamentos afetados permite verificar o que mudou. Um relatório longo sobre toda a aplicação não esclarece se o retorno daquela validação ficou correto. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) mostra como registrar o comportamento que o teste deverá verificar. O artigo sobre [construir com IA além da escrita de código](https://promovaweb.com/blog/construir-com-ia-alem-codigo) desenvolve essa relação entre a tarefa e a entrega. O resultado da implementação interessa ao produto. A autoria de cada linha não responde sozinha se o trabalho foi concluído. ## Digitar também pode fazer parte do aprendizado Durante o estudo, você pode escrever a pequena função que examina a data e acompanhar sua execução com `31/02/2026`. Ao localizar a condição que recusa a entrada, você compreende por que a mensagem aparece. Esse exercício tem uma finalidade de aprendizado, mesmo que o agente pudesse produzir a função rapidamente. O agente pode explicar a função ou sugerir outra implementação. A explicação ganha utilidade quando você consegue acompanhar o caminho no código. Copiar uma resposta sem identificar a condição responsável pela data inválida deixa a mesma dúvida para a próxima correção. Acompanhar a investigação ao vivo é uma opção quando o trecho ultrapassa o que você consegue avaliar. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) permite trabalhar na execução com orientação técnica. Para continuar estudando a construção com agentes, o [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) reúne o caminho educacional relacionado. ### Apps nativos voltaram a valer a pena com agentes de IA? - URL: https://promovaweb.com/blog/apps-nativos-vs-web-ia - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como agentes de IA permitem comparar a migração de React Native para apps nativos com a atualização do aplicativo existente. Leia o artigo. A atualização de um framework mobile pode obrigar você a mexer em boa parte de um aplicativo que já funciona. Nessa hora, manter a mesma tecnologia também custa trabalho. Com agentes de código, experimentar apps nativos em Swift ou Kotlin começa a caber nessa conversa, mesmo que você tenha escolhido uma base compartilhada para evitar desenvolver o produto duas vezes. Eu considero útil poder experimentar essa troca com o aplicativo atual como referência. Ela permite examinar uma alternativa que poderia ser descartada só pelo esforço inicial de programação. O resultado ainda precisa justificar a troca para o seu produto. ## Direto ao ponto Os agentes de IA tornam os apps nativos uma alternativa mais acessível para experimentar e implementar. O agente pode reproduzir funcionalidades já definidas usando o aplicativo existente como referência de comportamento. Isso permite comparar duas implementações funcionando, em vez de escolher apenas pela estimativa de código a escrever. A manutenção de versões separadas para iOS e Android continua fazendo parte da escolha. Para mim, a migração merece consideração quando resolve um problema do aplicativo atual ou acompanha uma atualização grande que você já teria de realizar. Uma aplicação web que atende bem aos clientes não ganha motivo para virar nativa só porque o agente consegue reescrevê-la. ## A comparação com apps nativos no Shop A [migração do Shop relatada pela Shopify](https://shopify.engineering/shop-app-migration) considerou duas alternativas para o aplicativo. A adoção da nova arquitetura do React Native exigiria rever integrações nativas e a renderização. Os engenheiros da Shopify experimentaram desenvolver diretamente em SwiftUI e Jetpack Compose como alternativa a esse investimento. Um engenheiro produziu a prova de conceito para iOS em uma semana. A migração até as lojas levou 12 semanas, com seis engenheiros no núcleo inicial e participação posterior de outros grupos. O aplicativo anterior serviu como referência para os agentes, mas a revisão continuou exigindo especialistas nativos. A diferença está no ponto de partida: a Shopify já tinha um produto conhecido e trabalho de atualização pela frente. Você pode aplicar esse raciocínio ao seu projeto sem usar o prazo da empresa como previsão. A comparação útil inclui o trabalho necessário para continuar na tecnologia atual, além do trabalho da alternativa. Em um aplicativo hipotético, imagine uma integração com o sistema operacional que depende de um módulo mantido separadamente. Atualizar o framework pode exigir adaptar esse módulo também. Uma versão nativa permite implementar a integração diretamente com os recursos da plataforma, mas traz outra organização de código. O experimento deve mostrar se essa mudança simplifica a funcionalidade que motivou a troca. ## O aplicativo existente dá uma referência ao agente Recriar uma tela conhecida oferece ao agente um comportamento para reproduzir. O código atual mostra os campos e as chamadas ao servidor. A aplicação aberta mostra o comportamento esperado. Você consegue apontar o que deve permanecer e o que quer alterar, sem descrever toda a experiência do zero. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) explica como registrar os comportamentos que orientarão a implementação. Essa referência também evita confundir reprodução com redesenho. Considere a confirmação de uma compra: mudar a linguagem da interface não deveria mudar a autorização da compra no servidor. Uma sugestão do agente para acrescentar uma etapa precisa ser examinada como alteração do produto, mesmo que a tela pareça melhor. A [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding) se relaciona a esse trabalho de construção com agentes. O estudo da implementação precisa acompanhar a leitura do sistema existente, porque uma reescrita aparentemente equivalente pode aceitar uma compra que o código anterior recusava por falta de autorização. ## A atualização chega ao celular de um cliente Um protótipo costuma começar com uma instalação limpa. O cliente recebe uma atualização sobre o histórico de compras e as configurações que já estavam no aparelho. Essa diferença muda o teste: a nova versão precisa reconhecer o que a anterior deixou, ou conduzir a transição de maneira compreensível. No Shop, preservar a sessão de login e as notificações fazia parte da migração. Os engenheiros também verificaram os eventos usados por outros sistemas. Uma interface semelhante, portanto, era apenas uma parte da equivalência buscada. Você pode experimentar essa diferença no aplicativo hipotético de compras. Uma compra concluída na versão anterior precisa continuar acessível após a atualização. O botão para repetir a compra deve respeitar os preços atuais. A tela nova pode abrir corretamente e ainda mostrar informação antiga se a leitura do histórico armazenado no aparelho mudar. É esse comportamento que interessa conferir, junto da aparência. A escolha do nativo também não leva o servidor para dentro do celular. O serviço continua autorizando consultas e recebendo alterações. No artigo sobre [infraestrutura em projetos de Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders), aprofundo o trabalho que acompanha uma aplicação publicada. Trocar a interface mantém essas dependências no projeto. ## Duas versões precisam receber a mesma mudança Uma base compartilhada permite reunir parte da implementação de iOS e Android. Ao separar as versões, uma alteração do produto exige trabalho nas duas. O agente pode produzir esse código, mas você ainda acompanha se ambas entregam a funcionalidade combinada. Imagine acrescentar uma nova opção de entrega à compra. Ela pode aparecer no iPhone enquanto a versão para Android aguarda correção. O suporte então recebe dúvidas diferentes para o mesmo produto. Quando você mantém um aplicativo com poucos desenvolvedores, eu incluiria essa coordenação na comparação, em vez de medir somente o tempo até a primeira versão nativa. O artigo sobre [construir com IA além do código](https://promovaweb.com/blog/construir-com-ia-alem-codigo) desenvolve o trabalho de conduzir essas entregas. A web oferece outro caminho para um painel administrativo consultado pelo navegador. Uma alteração publicada no servidor pode chegar à interface sem distribuir uma versão pela loja. Esse percurso pode combinar melhor com um produto acessado por link e atualizado com frequência. O artigo sobre [escolher Laravel em projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) trata da relação entre a tecnologia escolhida e o trabalho que você assume depois. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) é um caminho para estudar a construção desses produtos com IA. Para um aplicativo existente, cuja atualização já exige rever a arquitetura, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) permite examinar esse projeto e organizar a sequência de trabalho. ### Como expor seu produto ao agente do usuário com MCP? - URL: https://promovaweb.com/blog/cli-mcp-agente-usuario - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como oferecer consultas e ações por MCP ao assistente do cliente, com permissões, registros e revisão do resultado no sistema. Leia o artigo. Seu cliente pode ter um assistente para preparar a agenda e consultar os documentos do trabalho. Ao entrar no seu produto, porém, ele volta a procurar o contato em várias telas. Oferecer uma consulta por MCP permite que aquele assistente acesse uma tarefa da aplicação, sem exigir que você construa outra conversa dentro do produto para a mesma finalidade. Eu começaria por uma consulta que já tem utilidade na interface. A integração deve oferecer ao assistente uma ação reconhecível, com um retorno que o cliente consiga conferir. Acrescentar ferramentas sem ligar cada uma a uma tarefa deixa a implementação pronta sem explicar por que alguém a usaria. ## Direto ao ponto O MCP (Model Context Protocol) permite expor ferramentas que um agente pode descobrir e chamar. A descrição informa a ação e suas entradas para que o agente prepare a chamada ao servidor, responsável por executar a consulta ou alteração na aplicação. O agente do cliente pode então utilizar essa ação durante uma conversa que já estava em andamento. O produto continua aplicando suas permissões. A descrição da ferramenta explica o que ela faz, mas não autoriza uma consulta nem define a identidade do cliente. A implementação precisa usar o acesso correspondente à identidade autenticada pelo cliente. ## Uma consulta útil fora das telas do produto Considere um sistema hipotético de atendimento. O cliente quer saber o último assunto tratado com um contato para preparar a próxima reunião. Hoje ele abre o cadastro, localiza a conversa e lê o histórico. Uma ferramenta pode devolver o atendimento mais recente daquele contato, incluindo a data e uma referência para abrir a conversa original. O assistente recebe essa informação enquanto prepara a reunião. Você mantém a consulta no produto e oferece outro modo de acessá-la. A referência para a conversa permite verificar o resultado quando o resumo estiver incompleto ou o cliente quiser ler a troca inteira. O artigo sobre [classificação de conversas no Chatwoot com Jev](https://promovaweb.com/blog/jev-classificar-conversas-chatwoot) distingue a interpretação da mensagem das ações posteriores no atendimento. Para mim, esse acesso oferece uma razão concreta para criar a integração. O cliente utiliza a informação junto das outras tarefas que já acompanha pelo assistente. O benefício não exige que toda navegação da aplicação seja substituída por uma conversa. A [especificação de ferramentas do MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) descreve o nome da ferramenta, os esquemas das entradas e os resultados. Também determina validação e controle de acesso no servidor. Essas características permitem apresentar uma consulta utilizável pelo agente, com a execução mantida na aplicação. ## API, terminal e ferramenta MCP Uma interface de programação de aplicações, ou API, oferece acesso ao sistema para outras implementações. Uma ferramenta MCP apresenta uma ação ao agente e pode usar essa interface na execução. Você não precisa criar outra lógica de consulta se já existe um serviço adequado para buscar o atendimento. Uma interface de linha de comando, ou CLI, atende ao uso pelo terminal. Ela pode ser útil para tarefas técnicas e também participar de uma integração com agentes. O cliente que quer preparar uma reunião, porém, não precisa aprender o comando utilizado internamente para receber o resultado. Esses caminhos podem compartilhar a lógica do produto e oferecer formas diferentes de interação. A escolha depende de onde a tarefa começa. Expor um comando e expor uma ferramenta MCP não são a mesma entrega: o assistente precisa descobrir a ação e interpretar suas entradas e seu retorno. Na consulta de atendimento, o primeiro trabalho é delimitar qual informação o agente recebe, evitando devolver todo o histórico para uma dúvida sobre o contato mais recente. O artigo sobre [Jev e histórico de leads no Mautic](https://promovaweb.com/blog/jev-historico-leads-mautic) desenvolve a leitura das interações registradas sem tratar cada ação como intenção de compra. ## A credencial não pode ampliar a consulta O cliente que acessa apenas os contatos da própria empresa deve manter esse alcance ao conectar o assistente. Uma integração com credencial administrativa pode consultar outros registros se o servidor não aplicar a autorização correspondente. O nome da ferramenta não impede essa exposição. Você consegue verificar o isolamento com dois contatos de empresas distintas. A mesma identidade que consulta o primeiro deve receber a recusa ao tentar abrir o segundo. O resultado precisa corresponder ao acesso concedido na aplicação, preservando a consulta autorizada sem liberar outros históricos. Uma informação sensível também não precisa aparecer inteira no retorno. Para preparar a reunião, a data e o assunto do último atendimento podem ser suficientes. Acrescentar campos sem utilidade para a tarefa aumenta o conjunto de informações compartilhado com o assistente. ## Ler o histórico e enviar uma mensagem A consulta pode servir de base para preparar um texto. Enviar esse texto altera o atendimento e exige uma autorização própria. Você pode oferecer ferramentas separadas para as duas ações, mantendo a consulta disponível sem conceder envio por consequência. Quando a empresa exige revisão, o conjunto autorizado precisa corresponder ao conteúdo enviado e ao destinatário. Acrescentar outro contato depois da aprovação muda a ação. O sistema deve tratar essa diferença de acordo com o processo definido para o atendimento. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) mostra como descrever os estados de uma mensagem preparada, cancelada ou já em envio. Uma falha de conexão durante o envio também exige acompanhamento. O assistente pode ficar sem resposta mesmo quando a mensagem saiu. A identificação da tentativa permite investigar o resultado e evitar repetir automaticamente a comunicação. A leitura sobre [o custo previsível de um agente de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel) aprofunda o trabalho que acompanha essas integrações. ## Um primeiro acesso para o assistente do cliente Eu manteria a consulta inicial restrita à leitura para examinar a utilidade do retorno e a autorização aplicada. Você consegue comparar o resultado com a conversa original e ouvir se a informação serviu à preparação da reunião. Essa experiência fornece uma pergunta específica para a próxima ferramenta. O [Plano Martech da Promovaweb](https://promovaweb.com/planos/martech) se relaciona ao estudo de automação e integração entre sistemas. O [hub de planos da Promovaweb](https://promovaweb.com/planos) reúne os caminhos por objetivo. Para um produto existente que precisa organizar as ações oferecidas aos assistentes, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) permite examinar essa preparação. ### Por que specs valem mais que a sintaxe com agentes? - URL: https://promovaweb.com/blog/especs-linguagem-natural-agentes - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda por que specs claras valem mais que a sintaxe quando agentes de IA geram código e como descrever o comportamento do sistema. Leia o artigo. “Envie amanhã às nove” parece uma instrução suficiente até você precisar definir qual fuso horário o sistema deve usar. O cliente está em São Paulo, o servidor usa outro fuso e a mensagem pode ser cancelada durante a espera. Quando as specs não definem esses comportamentos, um agente pode escolher uma interpretação e transformá-la em código. Eu prefiro levar essas escolhas para a especificação. Assim você consegue discutir o comportamento do produto sem procurar cada interpretação dentro da implementação gerada. As specs registram o que o sistema deve fazer numa situação conhecida. ## Direto ao ponto As specs são especificações que descrevem o comportamento esperado de uma funcionalidade. Com agentes de código, elas permitem orientar a geração e verificar uma implementação a partir da mesma descrição. A sintaxe continua necessária para executar o sistema, enquanto você descreve a intenção e as condições da tarefa em linguagem natural. No agendamento, a especificação precisa indicar o fuso adotado e o comportamento de cancelamento. Também deve explicar a resposta quando o serviço de mensagens não confirma o envio. Uma descrição que só repete “agendar mensagens” deixa essas escolhas para a implementação, seja ela escrita por você ou pelo agente. ## O fuso horário definido nas specs Considere um sistema hipotético que permite programar uma mensagem para um contato. O cliente escolhe a data e o horário no formulário. A aplicação registra o instante de execução e o exibe novamente na confirmação. A descrição pode afirmar que o horário será interpretado no fuso configurado para aquela empresa. Com o fuso da empresa definido como UTC−3 no exemplo, um envio às nove corresponde ao meio-dia em UTC (Tempo Universal Coordenado). A confirmação precisa voltar a mostrar nove horas para o cliente. Esses dois horários permitem verificar a conversão e a apresentação do mesmo agendamento. Escrever essa descrição em português ou em inglês não muda a necessidade de indicar o fuso. O agente pode interpretar qualquer uma das línguas, mas não recupera uma escolha do produto que ficou ausente. A descrição do fuso permite testar a conversão, enquanto repetir a importância do envio pontual deixa essa definição ausente. O artigo sobre [construir com IA além do código](https://promovaweb.com/blog/construir-com-ia-alem-codigo) aprofunda a relação entre intenção e implementação. Nesse exemplo, a contribuição da especificação é permitir que você examine o significado do horário na descrição da tarefa, acompanhando depois sua tradução para o código. ## Cancelar durante a espera ou durante o envio Um agendamento pendente pode receber o cancelamento e sair da execução programada. Depois que o serviço começa a transmitir a mensagem, a aplicação talvez já não consiga interromper essa tentativa. A interface precisa distinguir essas situações para não prometer uma ação que o sistema deixou de controlar. Para mim, esse trecho merece uma descrição própria. O botão “cancelar” permanece simples na tela, mas a resposta depende do estado do envio. A especificação pode delimitar que a confirmação de cancelamento só aparece depois de o estado registrado impedir o início do envio. O executor precisa respeitar esse estado mesmo que já tenha buscado o item para processar. O teste com o agendamento aguardando execução confirma o cancelamento aceito. Outra tentativa, realizada depois de iniciar o envio, deve produzir o retorno previsto para um trabalho já iniciado, em vez de copiar a mensagem de sucesso da primeira situação. Uma mudança descoberta nessa conferência também altera a descrição. Manter a especificação antiga enquanto o código usa outro comportamento deixa a próxima tarefa com duas referências incompatíveis. O documento precisa acompanhar a funcionalidade aceita, sem preservar uma promessa que o produto deixou de cumprir. O artigo sobre [repertório técnico com IA](https://promovaweb.com/blog/repertorio-para-ia-desenvolvimento) acompanha outro caso de solicitações que disputam o mesmo registro. ## Uma resposta ausente não confirma um envio cancelado Durante a transmissão, a conexão pode cair e impedir o retorno do serviço. Você sabe que a tentativa começou, mas ainda não sabe se a mensagem chegou. O agendamento precisa representar essa situação sem informar automaticamente que nada foi enviado. Repetir a tentativa pode produzir uma duplicação. A especificação deve indicar como a aplicação acompanha a tentativa anterior, conforme o serviço integrado permite. Uma identificação persistente da tentativa pode permitir consultar o resultado ou reconhecer um envio já processado. Esse comportamento precisa corresponder aos recursos reais da integração. O artigo sobre [ferramentas MCP para o assistente do cliente](https://promovaweb.com/blog/cli-mcp-agente-usuario) examina a separação entre consultar um histórico e autorizar uma mensagem. O agente pode implementar a repetição de um envio ao encontrar uma falha de rede. Sem a descrição dessa situação, a solução pode parecer coerente numa leitura isolada e produzir duas mensagens para o cliente. A [revisão de código gerado por IA](https://promovaweb.com/blog/laravel-vibe-coding-revisao) permite localizar essa interpretação nos arquivos alterados. ## Uma especificação que cabe numa tarefa O envio individual e seu cancelamento formam uma funcionalidade delimitada. Acrescentar distribuição para grupos muda o conjunto de destinatários e a forma de acompanhar os resultados. Você pode manter esse trabalho em outra tarefa, evitando que a implementação inicial inclua comportamentos que ainda não foram discutidos. A descrição também precisa dizer que o envio para grupos está fora dessa versão. Isso permite distinguir uma ausência intencional de uma funcionalidade incompleta. O agente recebe o envio individual como limite da implementação, permitindo que você recuse código acrescentado para distribuir mensagens a grupos. Para essa funcionalidade, eu manteria o exemplo de horário e os dois estados de cancelamento junto dos testes correspondentes. Você consegue reler a especificação e encontrar o comportamento que motivou cada teste, sem repetir o objetivo geral em todas as seções. A [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding), presente no caminho de estudo do [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers), se relaciona à construção dessas tarefas com agentes. Quando um sistema existente tem funcionalidades misturadas e precisa organizar a sequência de implementação, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) oferece uma análise do produto. ### Como a franquia de 1.000 entregas muda seu WhatsApp? - URL: https://promovaweb.com/blog/franquia-whatsapp-custo-atendimento - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como a franquia de 1.000 entregas por número muda o custo do atendimento WhatsApp a partir de outubro e o que medir no seu dia. Leia o artigo. O relatório do WhatsApp pode mostrar dois mil atendimentos no mês sem esclarecer quanto da franquia você consumiu e quanto vai pagar pelas respostas. Uma conversa curta e outra com várias trocas entram como um atendimento cada, embora o número de mensagens recebidas pelo cliente seja diferente. A partir de 1º de outubro de 2026, a Meta oferece mil mensagens de serviço gratuitas por número comercial a cada mês e cobra pelas seguintes. A franquia considera as mensagens entregues, por isso o volume de atendimentos sozinho fica insuficiente para calcular essa despesa. Na previsão do seu serviço, eu separaria a tarifa do WhatsApp da manutenção do atendimento automatizado. Uma conversa com três respostas consome um volume diferente de outra com doze, mesmo quando ambas resolvem a mesma dúvida. O preço do canal precisa acompanhar esse volume para que você consiga explicar a cobrança ao cliente. ## Direto ao ponto Cada número comercial tem sua própria franquia mensal de mil mensagens de serviço. O saldo não acumula para o mês seguinte e não abate mensagens de utilidade nem de autenticação, que seguem a cobrança das respectivas categorias. Para destinatários no Brasil, a tarifa de serviço após a franquia é de R$ 0,0350 por mensagem entregue, sem outra isenção aplicável. O preço do conector e o processamento do agente ficam fora desse cálculo, como explica a leitura sobre [o custo do WhatsApp em agentes de IA](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia). ## Um atendimento pode consumir várias mensagens Considere um atendimento hipotético no qual o agente confirma o nome do cliente, consulta uma cobrança e envia a segunda via. Se essas respostas chegam em três mensagens separadas, o número usa três unidades da franquia de serviço, desde que todas sejam classificadas nessa categoria. No seu relatório, dois mil atendimentos com três respostas de serviço por cliente correspondem a seis mil mensagens, quando todas são entregues. Se o mês seguinte registra os mesmos atendimentos com seis respostas cada, o volume dobra para doze mil mensagens e você precisa projetar a cobrança com esse volume, descontadas a franquia e as isenções aplicáveis. Essa comparação exige preservar o identificador de cada mensagem e o registro de entrega. Na integração com o [n8n](https://promovaweb.com/ferramentas/n8n), o retorno da solicitação de envio e a confirmação de entrega precisam ser distinguidos: a primeira resposta confirma a tentativa aceita pela plataforma, enquanto o status posterior de entrega ou leitura informa que a mensagem chegou. ## Como calcular o excedente de um número A [documentação de preços da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing) confirma a franquia e publica a tabela com vigência em outubro. Para uma estimativa em reais, você precisa usar a tabela em BRL e conferir o mercado do destinatário, pois a tarifa brasileira não se aplica automaticamente a clientes de outros países. No exemplo da calculadora da Conversa Labs, dois mil atendimentos com doze respostas de serviço entregues por atendimento resultam em 24 mil mensagens no mês. Com um único número e a franquia integral disponível, sem outras isenções, 23 mil mensagens recebem cobrança e o cálculo de 23.000 × R$ 0,0350 resulta em R$ 805. O número de atendimentos permanece o mesmo do exemplo anterior, mas o volume de respostas é quatro vezes maior. Você consegue verificar esse custo pela média de mensagens de serviço entregues por atendimento, sem assumir que toda conversa consome uma quantidade fixa. ## A franquia pertence ao número usado no atendimento Dois números comerciais têm franquias separadas, mesmo quando pertencem à mesma empresa. Se um número entrega oitocentas mensagens de serviço no mês e outro entrega mil e duzentas, as duzentas unidades não utilizadas no primeiro não compensam o excedente do segundo. Para esse cenário hipotético, o primeiro número fica dentro da franquia e o segundo tem duzentas mensagens cobradas, sem outra isenção. Na tarifa brasileira em reais, o excedente corresponde a R$ 7, mesmo que a soma dos dois números seja de duas mil mensagens. Mensagens individuais e mensagens de grupo compartilham a franquia do mesmo número. Em um grupo, cada destinatário que recebe a mensagem consome uma unidade, por isso o registro de um único envio não descreve sozinho o consumo dessa franquia. ## A janela de atendimento e a categoria da mensagem A janela de atendimento de 24 horas é reiniciada quando o cliente envia uma mensagem. As respostas de serviço continuam restritas a essa janela, mas, a partir de outubro, a gratuidade depende da franquia disponível e de outras isenções que possam se aplicar. Uma mensagem de utilidade, como uma confirmação enviada por template, tem cobrança própria e não usa as mil unidades de serviço. A Meta também cobra essa categoria dentro da janela de atendimento a partir de outubro, por isso você precisa separar as categorias no relatório. O artigo sobre [conexões oficiais e não oficiais do WhatsApp](https://promovaweb.com/blog/whatsapp-oficial-api-nao-oficial) explica como a janela também participa da retomada de uma conversa interrompida. | Categoria para destinatários no Brasil | Tarifa em BRL a partir de 01/10/2026 | | --- | ---: | | Serviço, após a franquia e sem outra isenção | R$ 0,0350 | | Utilidade | R$ 0,0350 | | Autenticação | R$ 0,0350 | | Marketing | R$ 0,3217 | A igualdade entre as três primeiras tarifas não torna as categorias equivalentes. A franquia é exclusiva de serviço. Nas mensagens individuais, utilidade e autenticação têm faixas de preço por volume, conforme a tabela oficial aplicável. Mensagens de utilidade em grupos não recebem esses descontos. ## O custo do agente continua fora da franquia Uma assinatura de plataforma pode continuar sendo cobrada mesmo durante um mês no qual todas as respostas de serviço ficam gratuitas. O processamento do agente também pode gerar despesa a cada interação, conforme o provedor usado e a quantidade de texto processada. O artigo sobre [classificar conversas no Chatwoot com Jev](https://promovaweb.com/blog/jev-classificar-conversas-chatwoot) acompanha uma integração cujo retorno orienta o atendimento. Eu considero a manutenção ao avaliar uma automação de atendimento, porque uma mensagem com falha exige investigação da conexão e uma pergunta sem resposta pode exigir que um atendente assuma a conversa. A leitura sobre [como prever o custo de um agente de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel) explica as despesas do atendimento automatizado que ficam fora da tarifa do canal. No seu orçamento, a cobrança da Meta pode ocupar uma linha própria, ao lado da assinatura contratada e do processamento do agente. O diretório de [ferramentas da Promovaweb](https://promovaweb.com/ferramentas) permite consultar as aplicações citadas nas integrações, mas o preço de cada serviço precisa vir da contratação correspondente. ## Conferir as mensagens entregues no seu relatório A comparação entre dois meses deve mostrar as mensagens de serviço entregues por número e as categorias que receberam cobrança. Com essa separação, você consegue explicar por que a fatura aumentou mesmo quando o volume de atendimentos ficou estável. Na comparação com a fatura, eu partiria do volume entregue por cada número, aplicando a franquia e a categoria correspondente. Essa separação permite localizar a diferença que precisa de investigação, inclusive uma mudança na quantidade de respostas por atendimento. Para estudar as integrações que registram esses retornos, conheça o [Plano Martech da Promovaweb](https://promovaweb.com/planos/martech). ### Como agentes de IA mudam o desenvolvimento de software? - URL: https://promovaweb.com/blog/ia-transformacao-desenvolvimento-software - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como agentes de IA transformam o desenvolvimento de software, do código manual à revisão, e o efeito no trabalho do desenvolvedor. Leia agora. Uma tarefa que chegava ao editor para você escrever a implementação pode agora chegar como uma alteração já produzida por agentes de IA. Você abre os arquivos para compreender o que foi feito, executa a aplicação e compara o resultado com a funcionalidade que queria entregar. O trabalho continua no repositório, mas o ponto de entrada mudou. Eu considero essa mudança útil quando a tarefa está delimitada o suficiente para permitir uma revisão real. A geração pode terminar rapidamente e deixar uma alteração maior do que você consegue examinar. Nesse caso, a facilidade de produzir código criou mais trabalho sem concluir a funcionalidade. ## Direto ao ponto Os agentes de IA podem pesquisar o repositório, escrever uma implementação e executar testes. Isso permite delegar partes da construção e experimentar tecnologias que exigiriam mais esforço inicial de programação. Você continua definindo a tarefa e verificando o comportamento entregue ao produto. A mudança mais relevante está na forma de distribuir esse trabalho. A especificação orienta a implementação, os arquivos mostram o que mudou e a aplicação executada permite conferir o resultado. Esses elementos precisam corresponder entre si para que uma alteração gerada esteja pronta para publicação. ## Do formulário desejado à alteração recebida Considere um cadastro hipotético de clientes, separado por empresa. A tarefa descreve os campos e a permissão necessária para consultar cada registro. O agente pode localizar a estrutura existente e acrescentar o formulário, utilizando os componentes que o produto já oferece. Você recebe a implementação e consegue abrir o cadastro esperado. A demonstração confirma esse acesso, mas não examina a tentativa de uma empresa consultar o registro de outra. O teste precisa chegar a essa situação porque o isolamento faz parte da funcionalidade, mesmo que não apareça na tela inicial. Uma entrega que acrescenta permissões administrativas para fazer o formulário funcionar muda o alcance do acesso. A revisão deve identificar essa alteração no servidor. Aceitar a interface pela aparência deixaria acesso a cadastros de outras empresas. Para mim, a delegação funciona melhor quando você consegue relacionar a mudança a uma situação como essa. O artigo sobre [revisão de código gerado por IA](https://promovaweb.com/blog/laravel-vibe-coding-revisao) desenvolve a leitura dos arquivos junto da verificação do comportamento. ## Uma referência para os agentes fora da conversa A descrição do cadastro pode indicar que a consulta usa a empresa associada à identidade autenticada. Também pode registrar a resposta esperada para uma tentativa sem autorização. O agente recebe essas condições como referência para implementar a consulta. Você retoma a mesma descrição ao revisar o acesso gerado. Esse registro preserva a descrição da funcionalidade fora da conversa com o agente. Uma mudança aceita na funcionalidade precisa chegar à especificação, permitindo que a tarefa seguinte encontre o comportamento atual. Uma autorização descrita de forma diferente daquela implementada pode orientar a próxima alteração para o acesso errado. A linguagem natural permite discutir o produto com exemplos, enquanto o código realiza a consulta. O artigo sobre [specs no trabalho com agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) examina um agendamento para mostrar como o fuso e o cancelamento precisam aparecer nessa descrição. Você também pode editar diretamente uma parte conhecida, pois delegar a primeira implementação não obriga a delegar cada correção. Uma mensagem localizada pode ser alterada à mão, mantendo o mesmo teste que demonstra o resultado desejado. O artigo sobre [escrever código à mão com agentes de IA](https://promovaweb.com/blog/agentes-codigo-manual-excecao) compara a edição localizada com a investigação delegada. ## Experimentar outra tecnologia com uma funcionalidade conhecida Um aplicativo existente oferece uma referência para experimentar uma versão nativa. Você conhece as telas e consegue observar os percursos que precisam permanecer. O agente pode apoiar a reprodução desses comportamentos em outra implementação, permitindo comparar um trecho funcionando. A pergunta precisa incluir o trabalho de continuar na tecnologia atual. Uma atualização grande do framework pode exigir mudanças nas integrações, enquanto uma migração nativa oferece outro modo de organizar o aplicativo. O artigo sobre [apps nativos com agentes de IA](https://promovaweb.com/blog/apps-nativos-vs-web-ia) desenvolve essa comparação e a manutenção de versões separadas. Uma troca de linguagem num serviço oferece outro experimento delimitado. Preservar a chamada permite comparar a resposta e medir o processamento sem alterar toda a aplicação. O agente reduz o esforço de produzir a alternativa, mas a comparação ainda precisa demonstrar uma melhoria para a necessidade que motivou o teste. ## O produto pode oferecer uma tarefa ao assistente do cliente A integração com agentes também muda a forma de utilizar uma funcionalidade. Um cliente que prepara uma reunião pode consultar o último atendimento pelo assistente que já utiliza. O seu produto oferece a consulta e mantém a autorização correspondente à identidade conectada. O [MCP (Model Context Protocol)](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) permite expor ferramentas para essa interação. A implementação continua responsável por validar a chamada e aplicar o acesso. Conhecer o nome da consulta não concede permissão para abrir outros históricos. Essa possibilidade não exige substituir toda a interface por uma conversa. Você pode oferecer a consulta ao assistente e manter a tela como referência para abrir a conversa original. A utilidade aparece na tarefa atendida fora da navegação habitual do produto. ## Compreender a alteração continua fazendo parte do estudo Uma implementação pronta pode esconder uma pergunta que o teste ainda não fez, como a tentativa de outra empresa acessar um cadastro ou duas reservas chegarem ao mesmo tempo. Aprender a reconhecer essas situações permite orientar a investigação e avaliar o retorno do agente. A [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding) se relaciona à construção acompanhada dessas tarefas. Durante o estudo, eu manteria a implementação pequena o suficiente para explicar o caminho entre a chamada e o resultado. Essa compreensão fornece uma referência para a alteração seguinte. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) reúne o caminho educacional para construir com agentes. Para um sistema já existente que precisa organizar a sequência de trabalho, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) permite examinar produto e arquitetura. ### Como a OpenAI levou agentes de IA para o usuário comum? - URL: https://promovaweb.com/blog/openai-agentes-usuario-comum - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como o Dot da OpenAI aproxima agentes de IA da rotina de escritório e o que muda na configuração, nas permissões e na revisão. Leia o artigo. Na noite do DevDay 2026, habilitei o Dot para experimentar os agentes da OpenAI e fui dormir. Pela manhã, ele já tinha me avisado sobre mensagens recebidas de madrugada e indicado uma que merecia revisão. O e-mail já estava conectado ao ChatGPT, então não precisei montar uma automação para receber aquele aviso. Essa foi a parte do lançamento que mais me interessou. Eu prefiro ambientes nos quais posso instalar ferramentas e escrever minhas próprias integrações, mas um cliente pode só querer responder uma mensagem ou preparar uma proposta, sem configurar um servidor. ## Direto ao ponto A OpenAI aproximou os agentes da rotina de escritório ao oferecer o Dot dentro da experiência do ChatGPT, com um computador hospedado para executar o trabalho. Você pode começar por uma tarefa usando os aplicativos conectados, conforme as permissões concedidas e a disponibilidade no seu plano. Eu considero relevante tornar esse uso acessível a um público que não instala nem mantém agentes. Uma ferramenta com menos possibilidades de personalização pode atender bem uma tarefa desse público. A comparação precisa considerar o trabalho que você quer realizar, além das integrações que consegue acrescentar. ## A configuração não era a tarefa que eu queria fazer No meu teste, o e-mail já conectado permitiu observar o primeiro aviso sem instalar um servidor nem criar um fluxo. A conexão continuava sendo necessária, mas não havia outra configuração técnica entre habilitar o agente e acompanhar aquela consulta. Você que constrói automações conhece o trabalho de manter um ambiente próprio. Pode escolher as ferramentas e ligar sistemas que ainda não estão disponíveis numa interface pronta. Essa liberdade interessa a você que precisa dessas integrações e consegue cuidar da instalação. O cliente que quer preparar uma proposta tem outra tarefa. Ele pode usar um serviço hospedado justamente para concentrar o trabalho no documento, sem assumir a instalação e a manutenção de um servidor. Avaliar esse uso pela quantidade de recursos configuráveis ignora o motivo pelo qual ele contratou a ferramenta. O artigo sobre [memória, skills e ferramentas no Hermes Agent](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao) apresenta outro caminho de construção. A leitura faz sentido para você que precisa entender e organizar um ambiente próprio. A existência desse caminho não reduz a utilidade de uma experiência pronta para uma tarefa atendida por ela. ## Uma capacidade parcial pode atender a rotina Na minha comparação inicial, usei “um terço” para expressar a impressão de capacidade diante de um ambiente com mais possibilidades de configuração. Era uma impressão, sem medição entre ferramentas. Mesmo assim, o aviso sobre o e-mail já oferecia um uso que eu queria acompanhar. Uma proposta comercial mostra essa diferença de necessidade. Num exemplo hipotético, você descreve o serviço e utiliza o agente para preparar o documento. O trabalho termina com um texto que precisa ter os valores e as condições corretos. A qualidade desse documento orienta a avaliação da ferramenta utilizada. Uma possibilidade de configuração que não participa dessa tarefa pode continuar disponível em outra ferramenta sem fazer falta naquele uso. Para mim, essa é uma comparação mais útil ao apresentar um agente a um cliente: observar a entrega que ele consegue utilizar e as limitações que realmente aparecem durante o trabalho. O estudo também deve acompanhar o objetivo. O [hub de planos da Promovaweb](https://promovaweb.com/planos) reúne caminhos para construir sistemas e trabalhar com automação. Aprender a criar uma integração própria atende a uma necessidade diferente de aprender a revisar uma proposta preparada pelo assistente. ## O acesso dos agentes aos aplicativos conectados A [apresentação oficial dos dots](https://openai.com/index/introducing-dots/) informa que você escolhe os aplicativos acessíveis e gerencia as permissões no ChatGPT. A pesquisa proativa em segundo plano é restrita à leitura, enquanto ações que enviam mensagens ou alteram documentos têm permissões próprias. Isso explica o alcance do meu primeiro aviso: o agente indicou um e-mail para eu abrir e responder. Consultar a mensagem permitiu chamar minha atenção para ela. Enviar uma resposta seria outra ação, com uma consequência diferente para o remetente. Você precisa considerar o ponto de partida do cliente ao demonstrar a ferramenta. Sem a conexão de e-mail, ele não recebe o mesmo resultado por simplesmente habilitar o agente. Uma integração com o sistema interno da empresa também pode exigir um trabalho que não fez parte do meu teste. O artigo sobre [oferecer ferramentas MCP ao agente do cliente](https://promovaweb.com/blog/cli-mcp-agente-usuario) examina como expor uma tarefa do produto mantendo sua autorização. O artigo sobre [construir com IA além da escrita de código](https://promovaweb.com/blog/construir-com-ia-alem-codigo) desenvolve a relação entre a tarefa e a entrega. No escritório, essa relação aparece na mensagem original e no documento preparado, permitindo conferir o que o agente interpretou e o que realizou. ## Respeitar o cliente que não quer configurar um agente A ressalva que faço a você que trabalha com tecnologia é tratar esse uso com respeito. O cliente que não programa pode ter uma necessidade legítima de consultar documentos ou preparar propostas. Ele não precisa adotar o seu interesse pela arquitetura para utilizar uma ferramenta no trabalho. O documento também exige revisão, mesmo quando foi preparado numa interface simples. Você confere o valor de cada serviço e as condições que pretende oferecer. A facilidade de começar muda o caminho até o rascunho, sem tornar uma proposta incorreta aceitável. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) explica como registrar o comportamento esperado para orientar e conferir a execução. A disponibilidade ainda limita o acesso: a OpenAI anunciou a distribuição inicial para planos Pro e Business Premium em mercados elegíveis, com beta empresarial sujeito à habilitação do administrador. Você deve conferir o ambiente disponível para o cliente, evitando apresentar o recurso como liberado para todos. Eu continuaria acompanhando a consulta de e-mails no meu uso, preservando a possibilidade de abrir a mensagem original. Para estudar a construção de agentes e sistemas, o [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) oferece o caminho relacionado. Quando a necessidade do cliente exige uma integração própria, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) permite examinar essa construção. ### Como ouvir o cliente para investigar o churn no SaaS? - URL: https://promovaweb.com/blog/ouvir-cliente-metricas-churn-saas - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como conversas e métricas de churn ajudam a identificar dificuldades de uso antes do cancelamento e orientar mudanças no SaaS. Leia o artigo. Um cliente começa o cadastro no seu SaaS, preenche os dados pessoais e para na tela que solicita informações da empresa. No exemplo hipotético, ele não retoma essa etapa e cancela algumas semanas depois, mas o histórico de uso não explica, sozinho, o motivo do cancelamento (churn). Eu compararia a conversa com as etapas registradas para entender o que o cliente pretendia realizar e o que conseguiu fazer no produto. ## Direto ao ponto As métricas mostram a etapa que o cliente interrompeu, enquanto a conversa permite investigar o motivo. Essa diferença orienta a pergunta sobre a última tentativa: você pode voltar ao formulário abandonado e ouvir o que ele pretendia concluir, sem apresentar uma causa pronta para o cancelamento. A correção precisa responder à dificuldade encontrada e receber acompanhamento no mesmo percurso. Concluir mais cadastros demonstra uma mudança no uso daquela tela. Se o produto oferecer um período gratuito, a [comunicação do fim do trial](https://promovaweb.com/blog/trial-saas-teste-gratuito) é outra etapa do percurso que você pode investigar. A redução de churn exige observar os cancelamentos e a continuidade da assinatura, sem atribuir esse resultado automaticamente à correção. ## Como as métricas de uso ajudam a analisar o churn O histórico da configuração inicial permite localizar a última etapa concluída. Num exemplo hipotético, o cliente preenche os campos pessoais e abandona a tela que solicita informações da empresa. Você encontra o ponto da interrupção, mas ainda não sabe se faltava uma informação, se o campo causou dúvida ou se ele interrompeu o trabalho por outro motivo. As [gravações de sessão do Microsoft Clarity](https://learn.microsoft.com/en-us/clarity/session-recordings/recordings-overview) permitem observar interações registradas no site por meio da reconstrução visual do HTML e de ações como cliques e rolagens. Você pode rever a navegação até uma tela e usar esse percurso na conversa sobre a tarefa interrompida. A gravação mostra ações visíveis, enquanto a explicação do motivo continua com o cliente. Um cadastro interrompido orienta a conversa sobre a etapa que faltou concluir. Já uma função acessada uma única vez permite investigar se o resultado correspondeu à tarefa. Você pode apresentar o percurso observado e ouvir a explicação do cliente, evitando sugerir a causa durante a pergunta. A resposta pode revelar uma orientação ausente ou uma dificuldade do produto que o registro de navegação não explica. ## Reserve tempo para conversar com clientes Eu recomendo reservar dois dias por mês para sessões de feedback. Você pode reunir clientes em uma chamada, conversar em um grupo ou marcar encontros individuais. Escolha um formato que permita ouvir exemplos de uso, sem transformar a conversa em uma apresentação de novidades. Na conversa sobre aquela tentativa, o cliente pode mostrar que procurava uma informação da empresa que não tinha disponível. Esse relato muda a investigação: talvez o formulário exija um preenchimento que poderia ficar para outra etapa. Você consegue discutir a necessidade do campo a partir do trabalho interrompido, em vez de perguntar se o cliente gostaria de uma função imaginada durante a chamada. Durante a chamada, uma demonstração da tarefa oferece material para conferir o relato. O cliente pode abrir a tela utilizada, mostrar o trecho que não entendeu e explicar a solução improvisada. Uma pergunta sobre a última tentativa produz uma conversa diferente de uma votação sobre funções futuras: você acompanha o problema atual e registra o resultado esperado. Na revisão mensal, agrupe os relatos pela tarefa e compare as etapas mencionadas com os acessos e as conclusões registrados. A repetição de uma dificuldade nas conversas e no percurso de uso justifica investigar aquela tarefa com outros clientes. Quando as fontes mostram situações diferentes, a comparação precisa considerar a versão do produto e o período de cada tentativa. Uma visita curta não confirma abandono, assim como uma reclamação isolada não explica o uso dos demais clientes. O artigo sobre [lançamentos frequentes e valor percebido no SaaS](https://promovaweb.com/blog/excesso-lancamentos-saas-percepcao-valor) trata do impacto do volume de novidades na percepção do produto. ## Quando a adoção não acompanha os lançamentos Se três novidades seguidas não mudaram o uso, pause a fila de recursos e investigue os lançamentos recentes. Confira se os clientes souberam das mudanças, tentaram usá-las e conseguiram concluir a tarefa. O diagnóstico pode apontar para orientação, descoberta da função ou um problema no próprio fluxo. A investigação orienta o trabalho seguinte: uma função pouco conhecida precisa de explicação, enquanto uma tarefa interrompida por um erro exige correção no percurso. Para acrescentar uma função, confira nas conversas e no uso observado qual necessidade ela atenderá e como o cliente chegará ao resultado esperado. O texto sobre [cadência de lançamento](https://promovaweb.com/blog/cadencia-lancamento-saas) desenvolve uma forma de distribuir comunicação, estabilização e trabalho de desenvolvimento. ## Acompanhe a tarefa depois da alteração Uma correção precisa de acompanhamento no mesmo percurso utilizado na investigação. Em outro exemplo hipotético, você acrescenta uma orientação ao formulário e confere quantos clientes concluem aquela etapa. O registro deve separar as tentativas realizadas na versão anterior das tentativas realizadas após a mudança, para você comparar situações equivalentes. A conclusão do formulário pode aumentar sem alterar os cancelamentos do período. Isso não invalida a correção da interface, mas impede atribuir a ela uma redução de churn ainda não observada. Você precisa acompanhar a continuidade do uso e voltar à conversa sobre a tarefa que motivou a assinatura. No registro da alteração, eu manteria o relato original, a tela afetada e o resultado esperado. Esses itens permitem retomar a investigação quando o uso não muda e explicam por qual motivo aquela função recebeu atenção. A anotação também evita reabrir a mesma discussão como se nenhum cliente tivesse apresentado a dificuldade. ## Leve os relatos para o backlog No backlog, eu daria prioridade à dificuldade que aparece em conversas distintas e também no percurso registrado. A tarefa deve explicar qual etapa será alterada e como você acompanhará seu efeito. A responsabilidade pela mudança permanece com você, seguindo a separação apresentada no artigo sobre [construir software com IA](https://promovaweb.com/blog/construir-com-ia-alem-codigo). Uma reclamação sobre o cadastro pode orientar uma mudança nesse formulário, sem justificar uma reformulação de todas as telas do produto. Para você que já conduz um produto e quer organizar gestão, operação e relacionamento com clientes, o [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma) apresenta os caminhos para essa etapa. O [hub de planos da Promovaweb](https://promovaweb.com/planos) reúne as opções por objetivo. ### Por que o repertório vale mais com IA no desenvolvimento? - URL: https://promovaweb.com/blog/repertorio-para-ia-desenvolvimento - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda por que a facilidade de gerar código aumenta o valor do repertório de arquitetura, visão de produto e responsabilidade operacional. Leia o artigo. Dois clientes recebem a confirmação do mesmo horário. Na demonstração do sistema, uma reserva isolada funcionou e o agente apresentou o teste correspondente. O problema aparece quando as solicitações chegam juntas, pois as duas podem encontrar a sala disponível durante a consulta e gravar a reserva logo depois. Esse exemplo hipotético mostra uma função do repertório técnico: reconhecer uma situação que a demonstração ainda não examinou. Eu considero essa capacidade parte do aprendizado com agentes. A ferramenta pode escrever e investigar a implementação, enquanto você aprende a formular a pergunta que permite verificar o comportamento do produto. ## Direto ao ponto O repertório permite relacionar uma falha observada a um mecanismo da aplicação. Na reserva duplicada, a relação entre consultar disponibilidade e gravar a ocupação orienta a investigação. A pergunta sobre solicitações simultâneas muda o teste necessário, mesmo quando o formulário parece concluído. Você desenvolve esse conhecimento ao acompanhar correções e compreender por que uma solução funciona. A explicação do agente pode participar do estudo, mas precisa chegar ao código e a uma reprodução da falha. Uma resposta plausível sobre concorrência ainda não demonstra a causa naquele sistema. ## Entre a consulta e a gravação Considere um sistema de reserva de salas com horários fixos. A aplicação consulta se a sala está disponível às dez e, em seguida, registra a ocupação. Uma tentativa isolada conclui essas etapas e apresenta a confirmação na tela. Duas solicitações podem realizar a consulta enquanto o horário ainda está livre. Ambas recebem uma resposta positiva e tentam gravar a ocupação. O resultado depende de como a implementação e o banco tratam essa disputa. Uma verificação feita só na interface não impede que duas chamadas cheguem ao servidor. O artigo sobre [Supabase no backend de projetos de Vibe Coding](https://promovaweb.com/blog/supabase-backend-vibe-coding) apresenta o banco e a autorização das chamadas como partes da aplicação. Você pode examinar a consulta e a gravação para localizar onde a duplicação deveria ser recusada. Num modelo de horários fixos, a combinação entre sala e horário precisa representar uma única ocupação, conforme o comportamento definido para aquele produto. Reservas por intervalos exigem examinar também a sobreposição, pois dois horários de início diferentes podem ocupar parte do mesmo período. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) explica como registrar essas condições e relacioná-las aos testes. Para mim, o aprendizado está nessa relação entre o comportamento desejado e a forma de registrá-lo. Conhecer o nome de um recurso do banco não resolve sozinho a reserva. Você precisa compreender qual combinação não pode ser repetida e como a aplicação responde à tentativa recusada. ## Um teste simultâneo não é duas reservas em sequência O primeiro cliente reserva o horário e o segundo tenta depois. Essa execução verifica a consulta de uma ocupação já registrada. Ela pode funcionar mesmo numa implementação que aceita duas gravações concorrentes, pois as tentativas não disputaram o horário ao mesmo tempo. Para investigar a duplicação, o teste precisa exercitar essa disputa. O agente pode produzir um teste chamado “reservas simultâneas” e ainda executar as chamadas em sequência. A revisão deve acompanhar a execução efetiva, em vez de aceitar o nome como comprovação. O resultado esperado também precisa ser definido. Uma confirmação e uma recusa por indisponibilidade preservam a única ocupação no exemplo de horário fixo. Duas confirmações indicam que o teste reproduziu a falha, mesmo que a segunda gravação tenha substituído a primeira no banco. O artigo sobre [revisão de código gerado por IA](https://promovaweb.com/blog/laravel-vibe-coding-revisao) aprofunda a relação entre a alteração e o teste executado. Nesse caso, você consegue avaliar a correção pela resposta das duas tentativas e pela ocupação registrada depois delas. ## O agente pode encontrar a pergunta que você não fez A investigação não precisa começar por uma hipótese humana. O agente pode identificar a consulta seguida de gravação e apontar a possibilidade de disputa. Você pode aproveitar a indicação para examinar o trecho e solicitar uma reprodução. Essa colaboração é útil para estudar uma implementação desconhecida. A resposta precisa mostrar o caminho entre a chamada e o registro da reserva, permitindo verificar onde as duas tentativas encontraram o horário livre. Uma explicação que apenas recomenda melhorar a concorrência não oferece essa relação. A [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding) se relaciona à construção acompanhada com agentes. O estudo pode partir de uma falha pequena que você consegue reproduzir, sem exigir domínio de toda a aplicação para compreender o trecho responsável. ## A correção muda a resposta ao segundo cliente Recusar a duplicação no servidor é uma parte da alteração. O cliente cuja tentativa perdeu a disputa precisa receber uma explicação e conseguir escolher outro horário. Mostrar uma mensagem genérica de erro deixaria o banco correto e a experiência de reserva incompleta. O cancelamento também merece atenção porque devolve um horário à disponibilidade. A correção deve considerar como esse caminho altera a ocupação e se uma reserva cancelada continua aparecendo como ativa. Você identifica essas relações ao seguir os trechos que utilizam o mesmo registro, mantendo a revisão ligada à alteração real. Depois da investigação, eu registraria as duas tentativas e o teste que reproduziu a disputa. Essa referência permite retomar o aprendizado numa alteração futura. Também preserva a diferença entre a solução para horários fixos e um produto que aceita intervalos de duração variável. ## Repertório ligado a uma falha que você compreendeu O artigo sobre [construir com IA além do código](https://promovaweb.com/blog/construir-com-ia-alem-codigo) desenvolve o trabalho de orientar a implementação. Na reserva, esse trabalho inclui explicar a relação entre a disponibilidade mostrada e a ocupação registrada, além de compreender a resposta apresentada ao segundo cliente. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) oferece o caminho educacional relacionado à construção com agentes. Quando você precisa acompanhar a investigação com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) permite trabalhar durante a execução. ### Como usar Rust e caixa-preta no desenvolvimento com IA? - URL: https://promovaweb.com/blog/rust-ia-caixa-preta - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda como avaliar Rust gerado por IA com testes de caixa-preta, comparação de recursos e revisão da implementação para manutenção. Leia o artigo. Um serviço pode receber a mesma requisição e devolver a mesma resposta depois de ser reescrito. Para o sistema que chama esse serviço, a troca de linguagem quase não aparece. Um teste de caixa-preta permite observar essa compatibilidade pelas entradas e saídas. Você pode usar essa comparação ao experimentar Rust com um agente, preservando a integração existente. Eu consideraria esse experimento para um serviço cujo consumo de memória ou tempo de processamento já merece investigação. A reescrita precisa responder a essa necessidade. Escolher Rust por conseguir gerar a primeira versão desloca a atenção para uma linguagem sem explicar o problema que ela resolveria. ## Direto ao ponto Os testes de caixa-preta examinam o comportamento pelas entradas e saídas do serviço. Eles permitem comparar uma versão gerada em Rust com a implementação atual, mantendo a chamada conhecida. O consumo de recursos precisa ser medido nas condições de uso que motivaram a reescrita. A interface preservada permite experimentar a troca em uma parte do sistema. Você ainda precisa revisar o código e prever como corrigir a versão nova. Um serviço que produz a resposta esperada num teste pode ter problemas internos que aquele exemplo não mostrou. ## Uma implementação nova atrás da mesma chamada Considere um serviço hipotético que recebe um arquivo tabular e devolve a quantidade de registros válidos. A aplicação que o utiliza conhece o endereço da chamada, o formato aceito e o retorno. Reescrever o processamento em Rust pode manter essa comunicação. Você consegue enviar o mesmo arquivo às duas versões e comparar a quantidade retornada. A conferência também inclui o comportamento diante de uma coluna ausente. Uma versão que calcula a quantidade de linhas corretamente e aceita um formato inválido alterou a integração, mesmo que o resultado do arquivo válido coincida. A compatibilidade precisa considerar os erros que o sistema chamador já trata. Se a implementação nova devolve uma resposta diferente para uma coluna obrigatória ausente, a aplicação pode deixar de mostrar a orientação ao cliente. O teste de caixa-preta permite observar esse retorno diretamente, sem exigir que ambas usem a mesma estrutura interna. O artigo sobre [specs para agentes](https://promovaweb.com/blog/especs-linguagem-natural-agentes) explica como registrar as respostas esperadas para orientar a implementação. Para mim, preservar a chamada durante o experimento facilita atribuir as diferenças à implementação. Mudar a linguagem e o formato de retorno ao mesmo tempo acrescenta outra mudança a investigar. Uma troca delimitada mantém a pergunta ligada ao processamento que você queria melhorar. ## O arquivo pequeno não descreve o consumo do serviço Uma demonstração com poucas linhas pode terminar rapidamente nas duas versões. O consumo que motivou a reescrita talvez apareça apenas com arquivos grandes. Medir uma entrada pequena não informa como o processamento se comporta no volume recebido em produção. A leitura pode carregar o arquivo inteiro na memória ou processá-lo em partes. Essa escolha da implementação afeta o consumo, além da linguagem utilizada. Você precisa examinar o que o agente gerou para compreender qual comportamento explica o resultado medido. Outro teste recebe vários arquivos ao mesmo tempo. Uma implementação que processa bem um arquivo isolado pode reservar memória para todas as solicitações simultâneas. Nesse cenário, a medição precisa mostrar a carga aplicada e o período observado, permitindo comparar execuções com as mesmas condições. A leitura sobre [infraestrutura em projetos de Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) aprofunda o acompanhamento do serviço publicado. O consumo de uma demonstração não permite calcular sozinho a capacidade necessária para atender os clientes. ## O que o teste de caixa-preta não mostra A resposta correta confirma o comportamento observado para aquela entrada. Ela não revela se a implementação duplicou o arquivo na memória, deixou de liberar um recurso ou ignorou um erro num caminho ainda não exercitado. A revisão precisa acompanhar o processamento responsável pela saída. Você pode usar o agente para localizar a leitura e explicar o tratamento de falhas. Essa pesquisa é útil quando aponta o trecho que precisa ser examinado. A explicação deve corresponder ao código efetivo, porque uma descrição de como o serviço deveria funcionar não demonstra como a implementação funciona. O artigo sobre [revisão de código gerado por IA](https://promovaweb.com/blog/laravel-vibe-coding-revisao) desenvolve essa conferência. Na reescrita, os testes de compatibilidade e a leitura dos arquivos cumprem funções complementares: um observa a resposta entregue à integração, a outra examina o caminho que a produz. ## Rust não torna qualquer código gerado correto A [documentação oficial de Unsafe Rust](https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html) explica que certas operações exigem garantias adicionais na implementação. Uma compilação aceita não substitui a revisão dessas condições. Você precisa compreender essas condições no trecho ou obter uma revisão especializada. Mesmo um código sem essas operações pode conter um erro no cálculo da quantidade de registros ou no tratamento de um arquivo incompleto. A linguagem não conhece a quantidade que o seu produto deveria retornar. Você precisa registrar os exemplos esperados e investigar uma divergência com a implementação atual. Ao considerar a publicação, eu incluiria a capacidade de corrigir essa versão. Um agente pode produzir outra tentativa, mas a manutenção precisa conseguir explicar a causa da falha. Continuar com a implementação conhecida também é uma alternativa quando o experimento não demonstra uma melhoria relevante para o serviço. O artigo sobre [código manual no trabalho com agentes](https://promovaweb.com/blog/agentes-codigo-manual-excecao) compara a edição direta com o trabalho total de delegar e revisar. ## Um serviço delimitado para estudar a troca A [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding) se relaciona à construção e à revisão com agentes. Para estudar uma troca de implementação, você pode partir de um serviço pequeno com entradas conhecidas e um consumo que consiga medir, evitando reescrever toda a aplicação na mesma tarefa. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) reúne esse caminho educacional. Quando você precisa de orientação para investigar o serviço e compreender o trecho gerado, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) oferece acompanhamento durante a execução. ### WhatsApp oficial ou API não oficial: qual arquitetura usar? - URL: https://promovaweb.com/blog/whatsapp-oficial-api-nao-oficial - Publicado em: 2026-09-30T12:00:00-03:00 - Descrição: Entenda a diferença entre Cloud API oficial, conexão não oficial e caminho híbrido para escolher a arquitetura do WhatsApp com segurança. Leia agora. Você envia uma resposta pelo painel de atendimento, mas o cliente continua esperando. Em um exemplo hipotético, o conector perdeu a sessão e a mensagem ficou pendente. A cobrança por mensagem pode ser pequena, mas você precisa avaliar como essa arquitetura permite investigar a falha e retomar a conversa. Na comparação entre a Cloud API oficial e uma conexão não oficial, eu começaria pela recuperação desse atendimento. Você precisa saber como identificar uma mensagem não entregue e qual suporte pode investigar a interrupção. A proposta do fornecedor deve explicar essa responsabilidade junto com o preço da arquitetura escolhida. ## Direto ao ponto A Cloud API usa a conexão oficial da plataforma, enquanto uma integração que automatiza o WhatsApp Web depende da sessão utilizada por esse conector. Você precisa conhecer o procedimento de retomada de cada caminho e o suporte contratado. A mensalidade pode parecer menor enquanto a recuperação exige acesso manual ao celular e investigação das conversas pendentes. A coexistência oficial do WhatsApp Business App com a Cloud API permite continuar usando o aplicativo. Ela é uma configuração diferente de combinar a Cloud API com automação não oficial. A proposta deve identificar as conexões instaladas, porque a palavra “híbrido” não esclarece essa diferença. ## Quando a mensagem fica pendente O aceite de um envio pela API confirma uma tentativa, enquanto o status de entrega informa o resultado posterior. Uma mensagem entregue dispensa reenvio. Já uma falha registrada permite investigar o motivo apresentado pela plataforma, preservando a identificação daquela tentativa para acompanhar a recuperação. A [referência de webhooks publicada pela Meta](https://www.postman.com/meta/whatsapp-business-platform/folder/vzaxn16/webhook-payload-reference) diferencia os estados de envio, entrega, leitura e falha. O webhook é a notificação que a plataforma transmite à sua integração. O painel precisa receber essa notificação e associá-la à mensagem correspondente para mostrar o andamento ao atendente. Uma ausência de atualização também merece investigação: a integração pode ter enviado a resposta e falhado ao registrar o retorno. Repetir o texto nesse momento pode duplicar a comunicação. Para comparar fornecedores, acompanhe uma demonstração do histórico de uma mensagem, incluindo horário, identificação do envio e retorno disponível. Eu incluiria essa demonstração na avaliação do painel. ## Arquitetura oficial e suporte contratado A Cloud API é o caminho oficial da plataforma para integrar mensagens a outros sistemas. O painel de atendimento, o conector e a automação acrescentam componentes à conexão. Uma interrupção pode exigir investigação nesses componentes mesmo quando a conexão utilizada é oficial. Na proposta, confira qual empresa atende você quando o painel apresenta erro, como ela acessa o histórico de execução e quais situações encaminha à Meta. Contratar uma plataforma que utiliza a Cloud API não informa, por si só, o horário do suporte nem o prazo de resposta. Essas condições precisam aparecer na oferta contratada. A [Política de Mensagens do WhatsApp Business](https://whatsappbusiness.com/policy/) exige templates aprovados para envios fora da janela de atendimento de 24 horas, reiniciada por uma nova mensagem do cliente. O destinatário também precisa autorizar o recebimento de novas comunicações, independentemente da aprovação do texto do template. Isso afeta a recuperação de uma conversa interrompida. Depois de resolver a falha, você precisa conferir se ainda pode responder pela janela de atendimento ou se o contato exige um template aprovado. O procedimento de retomada deve considerar o horário da conversa, além do estado da conexão. ## Conexão não oficial e manutenção da sessão Neste comparativo, conexão não oficial significa uma integração que automatiza uma sessão do WhatsApp Web fora da Cloud API. O nome comercial do conector pode esconder essa diferença. Um produto pode oferecer vários modos de conexão, por isso a avaliação deve identificar o modo utilizado no seu número. Uma demonstração de envio mostra que a mensagem saiu naquela tentativa. Para conhecer a manutenção, você precisa acompanhar também o procedimento de reconexão: o alerta de sessão encerrada, a autorização do novo acesso pelo celular e a apresentação das mensagens que aguardavam envio no painel. O fornecedor deve explicar o comportamento da implementação que oferece, inclusive suas limitações. Se a recuperação exigir uma ação no celular, registre o nome da pessoa que terá acesso ao aparelho durante o horário de atendimento. Uma assinatura pequena pode vir acompanhada desse trabalho manual. O tempo gasto para localizar conversas interrompidas e reconectar o número entra no custo da operação, ainda que não apareça como cobrança por mensagem. O artigo sobre [prever o custo de um agente de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel) desenvolve essa estimativa de processamento e manutenção. Eu compararia esse procedimento com a recuperação demonstrada pelo fornecedor oficial. O resultado depende do serviço contratado e da integração instalada. Usar uma conexão não oficial também não equivale a receber uma autorização da Meta para aquele método de automação. ## Coexistência oficial e uso combinado A coexistência oficial permite integrar um número do WhatsApp Business App à Cloud API e continuar utilizando o aplicativo. A [documentação de integração do Business App](https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users/) descreve esse funcionamento. A disponibilidade para o seu número precisa ser verificada durante a integração. A coexistência descrita nessa documentação utiliza o caminho oficial. Já uma proposta que combina a Cloud API com automação não oficial do WhatsApp Web precisa explicar separadamente o funcionamento de cada conexão. A palavra “híbrido” na apresentação comercial não informa quais caminhos foram instalados. Com dois caminhos, acompanhe onde aparecem as respostas enviadas por cada um. Em um exemplo hipotético, um atendente responde pelo aplicativo enquanto a automação prepara outra mensagem no painel. A integração precisa demonstrar como registra essas ações e como você interrompe o envio automático quando assume a conversa. A presença de duas conexões não comprova que uma recupera a falha da outra. O artigo sobre [Jev na classificação de conversas do Chatwoot](https://promovaweb.com/blog/jev-classificar-conversas-chatwoot) distingue a interpretação da mensagem das ações que encaminham o atendimento. ## Compare a proposta com o atendimento realizado A planilha de comparação pode separar a tarifa da plataforma, a assinatura do painel e o trabalho de manutenção. Para calcular a primeira parte, use as categorias e condições vigentes para o número. O artigo sobre a [franquia e o custo do atendimento no WhatsApp](https://promovaweb.com/blog/franquia-whatsapp-custo-atendimento) desenvolve esse cálculo com um exemplo identificado. Na assinatura, confira os números incluídos, os atendentes permitidos e os serviços cobrados à parte. Para estimar a manutenção, use o procedimento de recuperação apresentado pelo fornecedor e as horas disponíveis para esse trabalho. Uma mensalidade menor pode exigir uma contratação adicional para investigar falhas ou manter a integração. Se houver um agente de IA, inclua o processamento do modelo e as execuções da automação. O artigo sobre [custos de agentes na API do WhatsApp](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia) distingue o processamento do modelo da tarifa de mensagens. Você pode consultar as [ferramentas para automação da Promovaweb](https://promovaweb.com/ferramentas) para conhecer os componentes utilizados, mas a comparação financeira precisa usar os preços e o suporte da proposta recebida. Para mim, a escolha fica fundamentada quando você consegue acompanhar uma entrega, explicar a retomada de uma conversa e estimar o trabalho necessário para manter esse atendimento. Leve essas verificações à comparação dos fornecedores. Para desenvolver integrações de atendimento com acompanhamento, conheça o [Plano Martech da Promovaweb](https://promovaweb.com/planos/martech). ### Como criar uma cadência de lançamento que educa o cliente? - URL: https://promovaweb.com/blog/cadencia-lancamento-saas - Publicado em: 2026-09-29T12:00:00-03:00 - Descrição: Veja como comunicação, estabilização e desenvolvimento formam uma cadência de lançamento para seus clientes acompanharem as novidades. Leia o artigo. Uma novidade chega antes de a anterior estar explicada, por isso você divide a atenção entre comunicar, corrigir e desenvolver. O cliente tenta acompanhar as mudanças enquanto o próximo lançamento já entra em preparação. Uma cadência reserva espaço para cada etapa. Eu proponho um ciclo de três semanas para organizar lançamentos: comunicação, estabilização e desenvolvimento. Use o intervalo como referência e ajuste sua duração conforme o uso do produto, a capacidade de atendimento e o tamanho das mudanças. ## Direto ao ponto Distribua o trabalho de lançamento em etapas reconhecíveis. Reserve tempo para apresentar a novidade, conferir seu comportamento em produção e iniciar o próximo recurso. A proposta de três semanas que apresento oferece um exemplo para montar esse calendário. Cada SaaS precisa ajustar o intervalo ao próprio uso. Correções urgentes continuam no fluxo de trabalho atual. A cadência reserva tempo para planejar novidades e comunicação, sem adiar uma correção que afeta o uso do produto. ## Organize o ritmo antes de encher o backlog Ao desenvolver com Vibe Coding, você pode colocar uma tela, uma integração ou um ajuste em funcionamento com menos trabalho manual de código. O backlog ainda precisa de uma ordem baseada no que os clientes usam e no que você consegue acompanhar depois da publicação. O texto sobre [infraestrutura para projetos de Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) mostra quais serviços acompanham o projeto depois da primeira publicação. Comece pelo roadmap que já existe. Registre o que entrou em produção, quais tarefas a mudança atende e quais dependências ainda aguardam revisão. A lista permite escolher uma novidade que caiba no período seguinte e adiar ideias sem confirmação de uso. O desenvolvimento mais rápido também aumenta o trabalho de organização do produto. Você define o comportamento esperado, acompanha a implementação e confere o resultado antes de apresentar a mudança ao cliente. A cadência reserva lugar no calendário para esse acompanhamento. O artigo sobre [como a IA mudou o trabalho de desenvolvimento de software](https://promovaweb.com/blog/construir-com-ia-alem-codigo) explica por que essa conferência continua com você. ## Experimente a cadência de três semanas Na primeira semana, apresente o lançamento. Prepare uma demonstração, uma explicação por email ou uma conversa com os clientes que usam aquela parte do sistema. Mostre onde encontrar a novidade e qual tarefa ela permite concluir. Registre quantos clientes receberam a explicação e quantos chegaram à tarefa final. Se muitos receberam o aviso e poucos concluíram a tarefa, confira se encontraram a função e se o percurso levou ao resultado esperado. Na semana seguinte, acompanhe o que aconteceu depois da publicação. Confira erros nos registros, responda às dúvidas recebidas e repita os percursos que a mudança afetou. Quando alguém não encontra a função ou interrompe a tarefa, registre a tela e a etapa para investigar. Durante a estabilização, registre o nome de cada profissional e o erro que ele verificará. Agrupe os casos pelo percurso afetado. O registro conecta comunicação, estabilização e desenvolvimento e mostra o item que ainda precisa de conferência no ciclo atual. A terceira semana fica reservada ao desenvolvimento do próximo recurso escolhido. Escreva o comportamento esperado, implemente a mudança e mantenha a validação perto do código. Com essa sequência, você inclui explicação e estabilização na rotina do produto, sem deixar as duas atividades para quando surgir tempo. Esse desenho resulta em um intervalo de aproximadamente três semanas entre novidades planejadas. A frequência pode ser quinzenal ou mensal conforme o uso do produto. Eu ajustaria o período depois de conferir a comunicação e o acompanhamento de cada lançamento. Você não precisa dividir cada etapa em sete dias. Um ajuste pequeno pode ser comunicado e estabilizado em menos tempo, enquanto uma mudança em cadastro, cobrança ou acesso exige acompanhamento prolongado. O calendário serve para reservar espaço à comunicação e aos testes. Registre o que ocupou mais tempo e ajuste o ciclo seguinte conforme os lançamentos que os clientes usaram. ## Use a comunicação para mostrar o que mudou Uma atualização precisa chegar ao cliente junto de uma explicação útil. Diga qual tarefa mudou, onde está a função e o que o cliente deve conferir depois de usar. O anúncio ganha precisão quando parte de uma ação real no produto, em vez de uma lista de recursos recém-publicados. Na revisão de projetos com Vibe Coding, compare o comportamento entregue com o que foi especificado. Esse cuidado evita apresentar uma tela nova sem confirmar como ela se comporta nas rotas que a reutilizam. A [revisão de código gerado com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao) trata da conferência do comportamento implementado. ## Ajuste o ciclo com o uso observado Compare os acessos à novidade com as tarefas concluídas e converse com clientes que tentaram usá-la. Relacione o relato ao percurso registrado e ao problema que motivou a criação do recurso. Use essa conferência para definir a próxima etapa do roadmap: prepare uma demonstração melhor para a função pouco compreendida, corrija erros reproduzíveis e valide necessidades com clientes antes de incluí-las no próximo ciclo de desenvolvimento. O artigo sobre [como ouvir o cliente e acompanhar métricas de uso](https://promovaweb.com/blog/ouvir-cliente-metricas-churn-saas) detalha como combinar conversa e registros antes de escolher uma nova entrega. Para você que constrói um SaaS com apoio de agentes e quer organizar especificação, implementação e revisão, o [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) reúne a formação para essa prática. O [Guia de Vibe Coding da Promovaweb](https://promovaweb.com/vibe-coding) apresenta o percurso de especificar, construir e conferir uma aplicação. ### Como lançamentos frequentes mudam o valor percebido no SaaS? - URL: https://promovaweb.com/blog/excesso-lancamentos-saas-percepcao-valor - Publicado em: 2026-09-28T12:00:00-03:00 - Descrição: Veja como lançamentos sem explicação podem dificultar o uso, enfraquecer o valor percebido e orientar ajustes no ritmo do seu SaaS. Leia o artigo. Você abre o [ClickUp](https://promovaweb.com/ferramentas/clickup) e encontra dois lançamentos de recursos publicados em menos de uma semana. Ainda tenta entender a primeira novidade quando a segunda chega. A lista de atualizações cresce, mas você não sabe qual mudança merece atenção na sua rotina. Eu chamo de over-delivery a publicação de recursos sem considerar o que o cliente consegue aprender e incorporar ao trabalho. O problema aparece quando a capacidade de desenvolver define o calendário do produto. Cada lançamento precisa chegar ao cliente com uma explicação e uma tarefa útil para a rotina dele. Sem esse intervalo, a novidade seguinte disputa atenção com a anterior e o marketing perde uma história clara para apresentar. ## Direto ao ponto Lançamentos frequentes sem comunicação podem deixar o cliente sem referência sobre o que mudou e quando aquilo será útil. A percepção de valor depende de reconhecer o que o produto permite fazer. A lista de recursos, sozinha, não demonstra esse uso. Ao planejar o próximo recurso, inclua o trabalho de apresentar o que já está no ar. Quando a adoção ficar baixa, investigue se o cliente recebeu explicação e conseguiu encontrar a função antes de acrescentar outra novidade. ## Quando o calendário de desenvolvimento ocupa a tela Eu acompanho o ClickUp com frequência e não tinha assimilado a primeira novidade quando a segunda chegou. Essa foi minha reação como usuário, não uma medição de adoção dos clientes da ferramenta. Você pode observar a mesma questão no seu SaaS sem concluir que todo lançamento frequente causa cancelamento. Confira se os clientes encontraram a função, se a experimentaram e qual tarefa concluíram. Se os registros não responderem a essas perguntas, converse com clientes que usam o produto. Quando outra novidade é publicada sem que a anterior tenha recebido uma explicação clara, o cliente precisa descobrir sozinho o que mudou e como aquilo se encaixa no trabalho dele. Parte da atenção vai para procurar a função, interpretar o anúncio e avaliar se precisa alterar a própria rotina. ## Como lançamentos frequentes afetam o uso Uma novidade precisa de espaço para ser apresentada. Você pode explicar o problema que ela resolve, mostrar onde fica e acompanhar as dúvidas recebidas. Se vários anúncios chegam juntos, cada um disputa espaço no email, na demonstração e na conversa com clientes. Separe as etapas no acompanhamento: clientes que viram o anúncio, abriram a função e concluíram a tarefa. Se chegam à página do recurso e não tentam usá-lo, revise a explicação e o acesso. Se começam e interrompem a tarefa, repita o percurso e investigue a interface. Se concluem a tarefa, mas não voltam a usar a função, pergunte se ela resolveu uma necessidade recorrente. Esses sinais ajudam a localizar a dificuldade sem atribuí-la automaticamente ao volume de lançamentos. O artigo sobre [como criar uma cadência de lançamento](https://promovaweb.com/blog/cadencia-lancamento-saas) desenvolve uma organização possível para comunicação, estabilização e desenvolvimento. Em uma consultoria que acompanhei, 70 de 90 usuários novos abandonaram a plataforma. A análise daquele caso apontou falta de uma experiência coesa, apesar de o sistema funcionar. Esse número não é uma taxa de mercado e não prova que a frequência de lançamentos, sozinha, causou o abandono. O caso mostra a diferença entre qualidade técnica e experiência de uso. Um produto pode funcionar e ainda deixar o cliente sem orientação sobre a próxima etapa. Acompanhe a primeira tarefa concluída, as telas visitadas e as dúvidas que aparecem depois do lançamento. Para um produto com período gratuito, o artigo sobre [comunicar o fim do trial de um SaaS](https://promovaweb.com/blog/trial-saas-teste-gratuito) examina uma comunicação ligada ao uso e à contratação. ## Coloque explicação junto da novidade Quando uma atualização entra no produto, prepare também a forma de apresentá-la. Mostre uma tarefa concreta, indique onde a função aparece e diga o resultado esperado. O cliente precisa relacionar o anúncio à atividade que já realiza. Ao apresentar a atualização, confira se você consegue explicar a mudança sem listar telas como se cada uma fosse um benefício. Quando a demonstração não mostra uma tarefa, volte ao motivo que levou o recurso ao roadmap. Se a mudança atender a uma necessidade pontual, explique-a aos clientes que usam aquela função. Se ela alterar o percurso principal, revise as instruções de entrada e o guia de uso. A extensão da comunicação acompanha o efeito da mudança no produto. Se ela modificar condições de acesso ou cobrança, confira também os [termos de uso do MVP de SaaS](https://promovaweb.com/blog/termos-uso-mvp-saas). ## Escolha o próximo lançamento pelo uso Quando uma novidade recebe poucos acessos, confira o anúncio, a tela e a tarefa que ela deveria atender. Pergunte aos clientes se encontraram a função e em qual etapa interromperam o uso. Essa conversa pode revelar uma explicação ausente, um problema no percurso ou uma necessidade diferente. Eu compararia essas respostas com as métricas antes de propor outro recurso. Se os clientes não entenderam uma função já publicada, uma demonstração pode resolver a dificuldade. Quando o produto não permite concluir a tarefa, o roadmap pode incluir uma mudança que resolva essa limitação. O texto sobre [como ouvir o cliente e ler métricas de uso](https://promovaweb.com/blog/ouvir-cliente-metricas-churn-saas) mostra como investigar a adoção antes de escolher a próxima melhoria. Para você que administra um SaaS e quer organizar a gestão do produto, o [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma) aborda operação, contratos e precificação. O [hub de planos da Promovaweb](https://promovaweb.com/planos) apresenta as formações por objetivo. ### Como a IA muda o trabalho do desenvolvedor de software? - URL: https://promovaweb.com/blog/construir-com-ia-alem-codigo - Publicado em: 2026-09-22T00:00:00Z - Descrição: Entenda como agentes de código mudam o trabalho do desenvolvedor e por que um projeto pequeno conecta aprendizado e responsabilidade. Leia agora. Você abre o Codex, descreve uma funcionalidade e acompanha o agente explorar o projeto. Ao revisar a implementação e os testes, você percebe que aprovou uma mudança sem escrever cada linha e começa a se perguntar qual parte daquele trabalho ainda depende do seu conhecimento como desenvolvedor. Essa dúvida pesa quando você construiu sua identidade profissional aprendendo a implementar uma API, modelar um banco e encontrar falhas. Agora, o agente também consegue investigar o repositório, alterar vários arquivos e corrigir a própria implementação após um teste falhar. Para mim, o valor do desenvolvedor aparece ao compreender a tarefa do cliente, delimitar o comportamento esperado e conferir se o sistema publicado resolve o problema. A IA amplia a capacidade de execução, mas a responsabilidade pelo propósito do produto e pelas consequências do uso continua com você. ## Direto ao ponto O produto final é um sistema que permite ao cliente concluir uma tarefa e o código é uma das peças usadas para chegar a esse resultado. Quando o agente escreve parte da implementação, você delimita a funcionalidade e verifica na aplicação se o cliente consegue usá-la. Os fundamentos técnicos continuam necessários porque uma tela funcionando não confirma que os registros foram salvos ou que as permissões separam os acessos. Para estudar essas partes, escolha um projeto pequeno cuja tarefa principal você consiga acompanhar do início ao fim. ## A quantidade de código deixou de explicar o trabalho As centenas de linhas que um agente escreve durante uma sessão impressionam no terminal, mas não informam se a funcionalidade deveria existir. Você ainda precisa conferir se o fluxo corresponde à rotina do cliente e se a manutenção cabe no orçamento disponível. Os levantamentos disponíveis também não autorizam uma conclusão simples sobre produtividade. No [Stack Overflow Developer Survey de 2025](https://survey.stackoverflow.co/2025/ai), 84% dos participantes usavam ou planejavam usar ferramentas de IA no desenvolvimento, mas 46% declararam desconfiar da precisão das respostas. Um [experimento da METR](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) acompanhou 16 desenvolvedores experientes em projetos conhecidos por eles e encontrou aumento de 19% no tempo das tarefas quando as ferramentas de IA estavam disponíveis. O resultado descreve o início de 2025. Na [atualização de fevereiro de 2026](https://metr.org/blog/2026-02-24-uplift-update/), a METR identifica problemas de seleção e medição no experimento posterior, que impedem uma estimativa confiável do ganho atual. O agente pode terminar uma implementação depressa e você pode gastar a sessão seguinte desfazendo uma abstração inadequada ou procurando uma permissão esquecida. Também pode reduzir o tempo de implementação quando recebe uma funcionalidade delimitada, encontra testes confiáveis e opera em um repositório organizado. A [pesquisa DORA de 2025](https://dora.dev/research/2025/dora-report/) descreve a IA como amplificadora do sistema de desenvolvimento existente. No repositório, isso exige atenção aos arquivos e aos testes que orientam o agente, porque uma alteração baseada em instruções contraditórias pode aumentar o trabalho de revisão. Quando você deixa de usar linhas de código como medida principal, a verificação muda para a tarefa que motivou o projeto e para a capacidade do cliente de concluí-la. Essa conferência aproxima a técnica do produto e impede que uma sessão movimentada seja confundida com uma aplicação útil. ## O desenvolvedor não ganha autonomia só com agentes Você pode passar o dia distribuindo tarefas para o Claude Code ou para o Codex e continuar distante do produto. Quando a especificação chega pronta e ninguém conferiu a rotina do cliente, o agente pode implementar uma demanda mal compreendida, mesmo que execute corretamente cada instrução. Ao converter um ticket em prompt, você ainda pode estar executando uma tarefa cuja prioridade e comportamento foram definidos sem a sua participação. O agente altera os arquivos e executa os testes, enquanto você continua dependendo de uma especificação pronta para começar. Mesmo quando você acompanha [Codex e Claude por projeto no Herdr](https://promovaweb.com/blog/herdr-codex-claude-projetos), os painéis ajudam a localizar as execuções, mas não confirmam que a funcionalidade resolve a tarefa do cliente. É por isso que eu insisto em modelagem e validação antes de ampliar a implementação. Você precisa entender a tarefa do cliente para reconhecer uma especificação incompleta, inclusive quando o agente entrega exatamente o comportamento descrito nela. Você trabalha com autonomia ao acompanhar uma dificuldade observada pelo cliente até a aplicação publicada. Durante o uso, ele pode encontrar uma situação ausente da especificação e cabe a você investigar se a funcionalidade precisa mudar. ## Um projeto pequeno reúne técnica e produto Na Promovaweb, eu trabalho com alunos que programam há anos e com alunos vindos da automação, do marketing, da infraestrutura ou da gestão. Essa diferença de formação importa durante a construção, porque conhecer o processo do cliente e saber implementar o sistema são conhecimentos que nem sempre chegam juntos. No trabalho com backend, por exemplo, você pode usar o agente para montar uma primeira tela, ligar o formulário à API e preparar os estados de erro. A revisão visual ainda pode exigir outro especialista e as convenções descritas na análise sobre [Laravel em projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) ajudam você a organizar os componentes e revisar a implementação. Os fundamentos aparecem durante esse teste, quando você precisa separar o acesso de dois clientes aos registros ou descobrir por que a aplicação funciona no notebook, mas falha no ambiente publicado. O artigo sobre a [infraestrutura necessária em projetos de Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) aprofunda as dependências que aparecem depois da primeira publicação. Eu prefiro o aprendizado dentro de um produto pequeno porque uma tarefa real orienta o estudo. Ao investigar uma falha reproduzida na tela com o agente, você encontra o trecho de código que precisa compreender e identifica quando será necessária uma revisão especializada. ## Delegar a implementação não transfere a responsabilidade Um sistema que manipula pagamentos exige conferência do valor, da permissão e do estado gravado depois de uma tentativa recusada. O agente pode implementar o fluxo e escrever testes, mas você e a empresa que publica o sistema continuam responsáveis pela cobrança e pelo acesso liberado. Uma tela pode funcionar durante a demonstração e ainda permitir que um cliente consulte o registro de outro. Você precisa reproduzir essa tentativa de acesso no teste e conferir a autorização no servidor, pois a aparência da interface não comprova a separação dos registros entre clientes. O [relato da OpenAI sobre computação científica](https://openai.com/index/scientific-computing-agentic-ai/) descreve oito projetos que usaram agentes para modernizar software técnico. Os participantes relatam redução do esforço de engenharia em algumas tarefas, acompanhada pela necessidade de verificar os resultados e manter responsabilidade duradoura sobre as ferramentas produzidas. Uma solicitação que mistura cobrança e relatórios pode produzir uma mudança extensa, difícil de compreender mesmo quando os testes existentes passam. Dividir a implementação permite revisar cada comportamento afetado, como mostra o texto sobre [revisão de código gerado por IA com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao). ## Escolha algo pequeno o bastante para terminar Com o agente gerando código, você pode se animar a acrescentar um painel administrativo e integrações que o cliente ainda não precisa usar. Cada parte parece barata durante a implementação, mas exige revisão e manutenção depois de publicada. Eu prefiro começar por uma tarefa que o cliente já realiza e consiga concluir ao abrir a aplicação, como registrar ou consultar uma informação. Esse percurso permite estudar o banco e as permissões com uma finalidade definida, sem acrescentar funcionalidades para necessidades que você ainda não confirmou. Depois de publicar essa primeira versão, acompanhe o cliente usando a aplicação e observe o ponto no qual ele precisa voltar à planilha ou enviar uma mensagem para concluir o trabalho. Investigue o que falta na tela ou no registro salvo para que ele consiga terminar a tarefa e use essa informação ao definir a próxima alteração. Para estudar durante a construção, conheça a [Formação Vibe Coding da Promovaweb](https://promovaweb.com/formacoes/vibe-coding), que faz parte do [Plano IA Makers](https://promovaweb.com/planos/ia-makers). Para delimitar a primeira versão de um projeto que você já tem, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) é uma alternativa para definir o produto mínimo viável e sua arquitetura. ### Como usar o Jev para classificar conversas no Chatwoot? - URL: https://promovaweb.com/blog/jev-classificar-conversas-chatwoot - Publicado em: 2026-09-21 - Descrição: Veja como usar Jev, n8n e Chatwoot para classificar conversas, aplicar labels controladas e encaminhar com revisão humana no atendimento. Leia agora. No Chatwoot, você pode usar o Jev para classificar o assunto de uma conversa entre opções definidas por você, como dúvida comercial, problema técnico ou solicitação de cancelamento. O modelo recebe as mensagens selecionadas, responde à pergunta configurada e devolve uma categoria para o workflow. Você pode usar essa classificação para organizar os atendimentos no [Chatwoot](https://promovaweb.com/ferramentas/chatwoot). O cliente envia mensagens pelo WhatsApp, pelo email ou pelo chat do site e o histórico fica disponível para os atendentes. Com o [n8n](https://promovaweb.com/ferramentas/n8n) conectando o Chatwoot ao Jev, esse histórico pode ser analisado para atribuir tags conforme o assunto da conversa. As tags permitem que você filtre os atendimentos e encontre conversas sobre o mesmo tema. A automação relaciona cada categoria retornada pelo Jev à label correspondente no Chatwoot, que usa esse nome para as marcações. A responsabilidade pela aplicação dessas respostas continua com você, como desenvolve o artigo sobre [o trabalho do desenvolvedor com IA](https://promovaweb.com/blog/construir-com-ia-alem-codigo). ## Direto ao ponto Envie ao Jev apenas as mensagens necessárias para classificar o assunto. No n8n, associe a categoria a uma label permitida e preserve as marcações existentes antes de atualizar a conversa no Chatwoot. ## Classificando o assunto de uma conversa Considere um cliente que envia a mensagem: “Troquei de celular e não consigo acessar o aplicativo”. Você pode enviar esse texto ao Jev e perguntar qual categoria descreve melhor a solicitação, oferecendo alternativas como `autenticacao`, `financeiro`, `comercial` e `outro`. Nesse exemplo, o problema relatado favorece a categoria `autenticacao`. O n8n recebe a classificação e pode aplicar a label correspondente à conversa no Chatwoot. Ao filtrar os atendimentos por essa label, você encontra o caso junto de outras solicitações sobre autenticação. Algumas mensagens dependem do histórico anterior. Se o cliente escrever apenas “continua acontecendo”, recupere as mensagens que explicam o problema antes de chamar o Jev. No n8n, mantenha a sequência que permite relacionar essa resposta à solicitação original. O rótulo `autenticacao` permite filtrar o caso. Para encaminhá-lo ao suporte de acesso, configure a atribuição no workflow ou nas automações do Chatwoot. O atendente ainda precisa conferir se o cliente esqueceu a senha, perdeu o segundo fator ou teve a sessão encerrada, pois a primeira mensagem não identifica a causa. ## Preparando as mensagens no n8n A análise precisa receber as mensagens que descrevem o assunto atual do atendimento. No exemplo do cliente que trocou de celular, a primeira mensagem já permite reconhecer uma dificuldade de acesso. Se a conversa continuar, você pode incluir a pergunta do atendente e a resposta do cliente para esclarecer o que aconteceu. Considere esta sequência: > **Cliente:** Troquei de celular e não consigo acessar o aplicativo. > > **Atendente:** Você recebe alguma mensagem de erro? > > **Cliente:** O aplicativo solicita um código, mas meu autenticador ficou no celular antigo. A última resposta esclarece que a dificuldade envolve a autenticação. Ao enviar somente essa mensagem ao Jev, o modelo perde parte da explicação. Preserve a sequência e registre o papel do remetente em cada trecho para que a classificação considere a solicitação inicial e a resposta do atendente. Um estado preparado para a análise poderia ter este formato: ```json { "messages": [ { "sender": "customer", "text": "Troquei de celular e não consigo acessar o aplicativo." }, { "sender": "agent", "text": "Você recebe alguma mensagem de erro?" }, { "sender": "customer", "text": "O aplicativo solicita um código, mas meu autenticador ficou no celular antigo." } ] } ``` Esse JSON ilustra uma estrutura organizada no n8n. Preencha os campos com as mensagens recuperadas do Chatwoot, mantendo a ordem da conversa e a distinção entre cliente e atendente. Conserve no workflow os IDs exigidos pela API para atualizar a conversa correta. Eles não precisam acompanhar o texto enviado ao Jev. Retire nome, telefone e email dos campos e dos trechos das mensagens quando essas informações não ajudarem a identificar o assunto. As labels existentes podem permanecer no n8n durante a análise. A preparação das mensagens e do estado segue a separação mostrada no artigo sobre [histórico de leads no Mautic com Jev](https://promovaweb.com/blog/jev-historico-leads-mautic). Quando o Jev devolver a classificação, o workflow terá essas marcações disponíveis para preparar a atualização sem remover tags que continuam válidas. ## Definindo as categorias da conversa Com as mensagens organizadas, você pode usar uma pergunta do tipo `Choice` para classificar o assunto. Esse tipo de pergunta recebe uma lista de alternativas e devolve a opção selecionada, acompanhada da distribuição de probabilidades e de uma medida de confiança. As alternativas devem representar os assuntos que você quer identificar no Chatwoot. Para a dificuldade de autenticação do exemplo, podemos trabalhar com quatro categorias: ```json { "questions": { "assunto": { "type": "choice", "instructions": "Qual categoria descreve melhor a solicitação atual do cliente? Considere a sequência das mensagens e use outro quando nenhuma categoria corresponder ao assunto.", "criteria": { "autenticacao": "Dificuldades para acessar o aplicativo, recuperar senha ou concluir o segundo fator.", "financeiro": "Dúvidas ou problemas com cobranças, pagamentos, notas fiscais e reembolsos.", "comercial": "Interesse em preços, planos, contratação ou demonstração do serviço.", "outro": "Assunto fora das categorias disponíveis ou informação insuficiente para classificar." } } } } ``` Esse trecho representa o campo `questions` da chamada ao Jev. As mensagens preparadas no n8n compõem o campo `state`, permitindo que o modelo avalie a pergunta sobre o histórico recebido. Na conversa do exemplo, a troca de celular e a dificuldade para obter o código apontam para `autenticacao`. O modelo classifica o assunto, mas não precisa descobrir como recuperar o acesso. A investigação e as orientações ao cliente continuam no atendimento. As descrições também ajudam a distinguir categorias próximas. Uma pergunta sobre o preço de um plano pertence a `comercial`, enquanto uma reclamação sobre cobrança duplicada pertence a `financeiro`. Se esses assuntos estiverem descritos de forma ambígua, você poderá receber classificações inconsistentes mesmo com uma lista curta. O `Choice` seleciona um assunto por pergunta. Para marcar também a urgência, crie uma avaliação separada com opções próprias. Assim, uma conversa pode receber uma label de assunto e outra de prioridade sem combinar categorias, como `financeiro-urgente`. Antes de integrar a atualização, confira se os nomes usados nas alternativas correspondem às labels cadastradas no Chatwoot. Essa correspondência permite aplicar a categoria escolhida sem criar variações de grafia para o mesmo assunto. ## Aplicando a classificação como label no Chatwoot Depois de receber a resposta do Jev, o n8n precisa conferir se a categoria corresponde a uma label autorizada para essa automação. No exemplo do cliente que trocou de celular, a classificação `autenticacao` pode ser aplicada à conversa identificada no início do workflow. Antes da atualização, consulte as labels atuais. Eu preservaria as marcações de outras finalidades porque a API do Chatwoot substitui a lista associada à conversa, e enviar apenas `autenticacao` pode apagá-las. Esse comportamento está descrito na [documentação do endpoint de labels](https://developers.chatwoot.com/api-reference/conversations/add-labels). Suponha que o atendimento já tenha a label `cliente-ativo`. Inclua essa marcação e o novo assunto no corpo da requisição para manter ambas na conversa: ```json { "labels": [ "cliente-ativo", "autenticacao" ] } ``` No Node HTTP Request do n8n, a atualização usa o método `POST` neste caminho da sua instalação: ```text /api/v1/accounts/{account_id}/conversations/{conversation_id}/labels ``` Os IDs selecionam o workspace e a conversa. A autenticação usa o header `api_access_token` e as permissões do usuário associado ao token. A documentação citada especifica esses campos. Para futuras classificações, defina quais labels o workflow pode substituir. Se ele administra o assunto atual da conversa, uma nova categoria pode substituir a anterior aplicada pela própria automação. Marcações adicionadas pelo atendente para outras finalidades precisam ser preservadas. Acumular todas as categorias retornadas ao longo do atendimento pode deixar assuntos antigos nos filtros. Você também pode condicionar a atualização à confiança retornada pelo Jev. Quando o resultado não atender ao limite que você testou, mantenha as marcações e encaminhe a classificação para conferência. A opção `outro` deve receber um tratamento definido no workflow, como uma revisão pelo atendente. Depois da chamada, confira a resposta da API e as labels exibidas na conversa. No exemplo, `cliente-ativo` deve continuar presente, acompanhada de `autenticacao`. ## Testando com conversas já atendidas Para conferir as classificações, selecione conversas cujo assunto você consiga identificar pelo histórico. Inclua falhas de autenticação, dúvidas comerciais e problemas financeiros, além de mensagens incompletas que exigiram esclarecimentos do atendente. Na primeira execução, guarde as respostas do Jev sem atualizar as labels. Compare a categoria escolhida com as mensagens enviadas ao modelo. Se usar apenas o início de um atendimento, avalie o resultado considerando as informações disponíveis naquele momento, pois a conversa completa pode revelar detalhes que o modelo ainda não recebeu. No exemplo da troca de celular, o histórico aponta para uma dificuldade de autenticação. Se o Jev escolher `comercial`, confira se as mensagens chegaram na ordem correta e se a descrição de `autenticacao` contempla esse tipo de solicitação. Ajuste uma descrição por vez e repita a análise sobre os mesmos casos para acompanhar o efeito da mudança. “Quero falar sobre meu plano” pode se referir à contratação, a uma cobrança ou ao uso do serviço. Se a classificação for `outro` ou não atingir o limite conferido nos testes, configure o n8n para abrir uma tarefa de revisão antes de atualizar a label. Depois de revisar as classificações, eu testaria a atualização em uma conversa reservada para isso. Adicione uma label que deva ser preservada, execute o fluxo e confira se ela continua presente junto da categoria retornada pelo Jev. Execute o mesmo caso novamente para verificar se o workflow mantém as labels esperadas. Depois, simule uma mudança de assunto e confira se a categoria anterior é substituída conforme a configuração, preservando as marcações que o atendente adicionou para outras finalidades. Ao começar a classificar atendimentos reais, acompanhe as correções feitas pelos atendentes. Se dúvidas sobre preço estiverem recebendo `financeiro`, por exemplo, revise a distinção entre essa categoria e `comercial` usando as mensagens que produziram a confusão. Se o atendimento também começa pelo WhatsApp, o artigo sobre [custo de um agente de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel) mostra como manter uma etapa humana no fluxo comercial. Para outra integração de mensagens, veja como avaliar a [entregabilidade de emails transacionais](https://promovaweb.com/blog/entregabilidade-email-transacional). O [Plano Martech da Promovaweb](https://promovaweb.com/planos/martech) aprofunda a construção de automações de marketing e atendimento com essas ferramentas. ### Como o Jev analisa o histórico de leads no Mautic? - URL: https://promovaweb.com/blog/jev-historico-leads-mautic - Publicado em: 2026-09-21 - Descrição: Veja como combinar Mautic, n8n e Jev para interpretar o histórico dos leads, medir intenção comercial e encaminhar cada contato no fluxo certo. Leia agora. O Jev, modelo da TypeSafe AI, avalia informações com perguntas definidas e devolve respostas estruturadas para o software. No Mautic, o histórico de um contato reúne cliques em emails, visitas a páginas e respostas a formulários. Você pode enviar uma seleção dessas interações ao Jev, definir o que deseja avaliar e limitar as respostas possíveis a uma categoria de interesse ou a uma nota de engajamento. Esse funcionamento permite analisar o histórico de um lead registrado no [Mautic](https://promovaweb.com/ferramentas/mautic). Os cliques em emails, as visitas a páginas do site e os formulários enviados fornecem informações para avaliar quais assuntos despertam interesse e se há sinais de uma possível contratação. Com o [n8n](https://promovaweb.com/ferramentas/n8n) conectando as ferramentas, você pode preparar esse histórico, enviá-lo ao Jev e usar as classificações para atualizar o contato no Mautic. Um interesse identificado pode orientar a entrada em um segmento ou a escolha de uma campanha, conforme as condições configuradas no workflow. ## Direto ao ponto Considere um contato que recebeu uma sequência de emails sobre automação. Nos últimos dias, ele clicou em um conteúdo sobre integração de sistemas, visitou uma página de serviço no seu site e perguntou, em um formulário, se consegue integrar o CRM ao Mautic. O histórico do Mautic reúne essas interações. Você pode usar cada evento nas campanhas e enviar uma seleção ao Jev para avaliar o comportamento do contato durante o período escolhido. Antes da chamada, o n8n prepara cada registro com seu tipo e sua data. Neste exemplo, um clique mantém o assunto do email, uma visita inclui o título da página e o envio do formulário conserva o texto escrito pelo contato. Assim, o Jev compara as interações sem tratar uma visita como confirmação de leitura. Com esse histórico, você pode perguntar ao Jev qual assunto predomina e se a mensagem do formulário indica interesse em contratar o serviço. As respostas ficam em campos separados: a classificação seleciona uma campanha e a avaliação comercial sinaliza o contato ao vendedor. A pergunta sobre compatibilidade ainda deixa prazo e orçamento em aberto. A classificação pode orientar o acompanhamento, mas defina quais campos do formulário e quais interações justificam cada ação no workflow. ## Preparando o histórico do Mautic no n8n Para enviar o histórico ao Jev, selecione as interações que ajudam a responder às perguntas da análise. Se o objetivo é avaliar o interesse recente por um serviço, o n8n pode reunir os cliques nos emails da campanha, as visitas às páginas relacionadas e as respostas dos formulários dentro de um período definido por você. Preserve a data e o significado de cada interação. Um endereço de página pode revelar pouco quando contém apenas um código, enquanto o título informa qual serviço foi apresentado. Nos emails, o assunto e o destino do link clicado ajudam a identificar o conteúdo que despertou interesse. O clique difere da aceitação da mensagem pelo servidor, tratada no artigo sobre [entregabilidade de email](https://promovaweb.com/blog/entregabilidade-email-transacional). Para o contato do exemplo, o n8n pode organizar as interações desta forma: ```json { "periodo_analisado": "últimos 14 dias", "interacoes": [ { "dias_atras": 6, "tipo": "clique_email", "assunto": "Integração entre sistemas", "destino": "Artigo sobre integração de CRM com automação de marketing" }, { "dias_atras": 3, "tipo": "visita_pagina", "titulo": "Serviço de integração de sistemas" }, { "dias_atras": 1, "tipo": "envio_formulario", "mensagem": "Vocês conseguem integrar nosso CRM com o Mautic?" } ] } ``` Esse JSON ilustra uma estrutura preparada no n8n. Os nomes dos campos descrevem o histórico e precisam receber os registros recuperados da sua instalação. O registro informa uma visita à página, sem afirmar que o lead leu todo o conteúdo. Já a mensagem do formulário é explícita: ele quer saber sobre a integração do CRM com o Mautic. Mantenha essa diferença ao formular perguntas sobre as interações registradas. Você pode manter o identificador do contato no próprio workflow para atualizar o registro depois da análise. O nome, o email e o telefone não precisam acompanhar esse exemplo, pois as perguntas tratam do assunto procurado e dos sinais comerciais presentes no histórico. ## Definindo as perguntas que o Jev vai responder Com o histórico organizado, avalie o assunto de interesse e os sinais de contratação separadamente. O contato perguntou sobre integrar o CRM ao Mautic, o que identifica o serviço procurado. Ainda assim, ele pode estar comparando fornecedores ou apenas pesquisando possibilidades. Para classificar o assunto, usamos uma pergunta do tipo `Choice`. Você fornece as categorias e descreve o significado de cada uma. Neste exemplo, as alternativas são integração de sistemas, campanhas de marketing e informação insuficiente para classificar. A avaliação comercial usa uma pergunta do tipo `Noul`, que retorna um valor entre zero e um. A pergunta precisa descrever o comportamento procurado, como a presença de sinais de que o contato está considerando contratar o serviço. O trecho abaixo representa o campo `questions` da chamada: ```json { "questions": { "assunto_principal": { "type": "choice", "instructions": "Qual assunto de interesse combina melhor com as interações do contato?", "criteria": { "integracao_sistemas": "Conectar ferramentas, sincronizar registros ou automatizar a troca de informações entre sistemas.", "campanhas_marketing": "Criar campanhas, segmentar contatos ou organizar sequências de emails.", "indefinido": "O histórico não permite escolher uma das categorias anteriores." } }, "interesse_contratacao": { "type": "noul", "instructions": "O histórico apresenta sinais de que o contato está considerando contratar o serviço de integração de sistemas? Considere o conteúdo do formulário e a sequência das interações. Visitas e cliques isolados não confirmam interesse em contratar." } } } ``` As categorias precisam corresponder aos assuntos das suas campanhas. Se a empresa oferece outros serviços, acrescente alternativas com descrições que permitam distingui-las. Use `indefinido` quando o histórico não oferecer informação suficiente para escolher uma categoria. No exemplo, a pergunta sobre conectar o CRM ao Mautic combina com `integracao_sistemas`. O resultado comercial ainda é uma estimativa: confira a resposta com contatos já analisados antes de usá-la para acionar o vendedor. ## Usando as respostas para atualizar o contato no Mautic Depois da análise, o n8n relaciona as respostas do Jev ao contato que forneceu o histórico. O identificador preservado no início do workflow permite atualizar esse registro no Mautic, enquanto cada classificação alimenta uma condição da automação. A conferência do comportamento continua com você, seguindo a responsabilidade descrita no artigo sobre [desenvolvimento de software com IA](https://promovaweb.com/blog/construir-com-ia-alem-codigo). Suponha que o modelo selecione `integracao_sistemas` como assunto principal. Você pode gravar esse resultado em um campo personalizado e configurar um segmento com os contatos que possuem esse interesse. Uma campanha associada ao segmento pode apresentar exemplos de integrações, explicar o serviço e convidar o lead a informar quais ferramentas deseja conectar. A avaliação comercial pode orientar uma ação separada. Para demonstrar a lógica, considere um limite ilustrativo de `0.80`: acima dele, o workflow sinaliza o contato para acompanhamento comercial. Esse número precisa ser ajustado com históricos que você já conhece, comparando as respostas do modelo com a análise feita pelo vendedor. No contato do exemplo, o texto do formulário sobre integrar o CRM ao Mautic deve acompanhar a sinalização. O vendedor recebe a classificação junto da dúvida original e pode solicitar os nomes do CRM e dos campos que precisam ser sincronizados. O resultado também pode ser inconclusivo. Se o Jev selecionar `indefinido`, você pode manter o contato sem um novo interesse atribuído e repetir a análise depois de outra interação relevante. Antes de substituir uma classificação anterior, confira se o histórico enviado cobre um período suficiente para justificar a mudança. Para testar o fluxo, comece gravando as classificações em campos que ainda não acionem campanhas. Compare os resultados com o histórico de cada contato e observe quais perguntas produzem respostas úteis. Depois dessa conferência, conecte os campos aos segmentos e às ações comerciais. ## Testando a classificação antes de acionar campanhas Antes de usar as respostas do Jev para movimentar os contatos, selecione alguns históricos que você consiga conferir. Inclua contatos que perguntaram sobre contratação, outros que interagiram apenas com conteúdos educativos e casos com poucas informações. Essa variedade permite observar como o modelo responde quando o interesse está explícito e quando depende de interpretação. Execute o workflow mantendo desativadas as ações que enviam emails ou notificam o vendedor. Para cada contato, guarde o histórico enviado, as perguntas utilizadas e as respostas recebidas. Compare a classificação com as interações originais, verificando se o assunto selecionado corresponde ao conteúdo acessado. No exemplo do formulário, a dúvida sobre integrar o CRM ao Mautic aponta para interesse em integração de sistemas. Um contato que clicou em um único artigo sobre o tema oferece menos indícios. Se os dois receberem avaliações comerciais semelhantes, revise a pergunta e confira quais interações pesaram no resultado. Confira o significado de cada registro antes de atribuir um erro ao Jev: o envio de um email registra uma ação da campanha, enquanto o clique registra uma interação do contato. Se o estado não distinguir os eventos, a avaliação poderá considerar atividades que o lead nunca realizou. Altere uma pergunta ou uma descrição de categoria por vez e repita a análise sobre os mesmos históricos. Você conseguirá comparar os resultados e identificar o efeito de cada ajuste. Os limites usados no n8n devem acompanhar essa verificação, especialmente quando uma classificação puder iniciar contato comercial. Depois dos testes, eu ativaria uma ação por vez e acompanharia os primeiros resultados. Se o workflow incluir um contato no segmento de integração de sistemas, confira a atualização no Mautic e qual campanha esse segmento pode iniciar. Para ver como o Jev também pode classificar mensagens de atendimento, leia o artigo sobre [conversas do Chatwoot](https://promovaweb.com/blog/jev-classificar-conversas-chatwoot). Se sua automação conduz contatos até um vendedor pelo WhatsApp, veja como organizar o [custo e a passagem humana do agente](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel). Eu recomendo o [Plano Martech da Promovaweb](https://promovaweb.com/planos/martech) para aprofundar a construção de automações de marketing e atendimento com essas ferramentas. O caminho inclui montar os workflows, interpretar os registros e acompanhar o resultado comercial sem entregar todo o processo ao modelo. ### Entregabilidade de email: por que a mensagem não chega? - URL: https://promovaweb.com/blog/entregabilidade-email-transacional - Publicado em: 2026-09-08T05:15:00Z - Descrição: Entenda a entregabilidade do email transacional: confira SPF, DKIM, DMARC e os logs de envio para investigar mensagens que não chegam. Leia o artigo. O cliente solicita a recuperação de senha e não encontra a mensagem. A aplicação registrou o envio e o serviço de email mostra `delivered`. O problema de entregabilidade continua aberto: esse estado confirma que o servidor destinatário aceitou a mensagem, mas não informa se o email foi para a caixa de entrada, para outra aba ou para o spam. Na Promovaweb, eu uso o serviço de email da Cloudflare para mensagens transacionais e mantenho a newsletter na AWS. Cada fluxo precisa ser acompanhado pelo domínio, pela autenticação e pelos logs, sem tratar o botão “enviar” como confirmação de leitura. ## Direto ao ponto A investigação segue o percurso da mensagem. O log da aplicação confirma a chamada ao serviço e a resposta do servidor destinatário mostra aceitação ou rejeição. Se houve aceitação, os cabeçalhos, a reputação e o posicionamento na caixa postal indicam a próxima leitura. No DNS, SPF declara as origens autorizadas e DKIM publica a chave usada para conferir a assinatura. DMARC relaciona essa autenticação ao domínio visível e informa como tratar falhas. BIMI pode exibir o logo em provedores compatíveis, mas não coloca a mensagem na caixa de entrada. ## A aplicação precisa registrar o primeiro envio Comece pelo evento que deveria gerar a mensagem. No fluxo de recuperação de senha, associe o identificador da solicitação ao template, ao destinatário e à resposta devolvida pelo serviço de email. Não grave a senha, o token completo nem conteúdo sensível no log. Uma resposta aceita pelo serviço mostra que a aplicação atravessou a primeira etapa. Uma falha de autenticação na API ou no SMTP termina ali. Corrija credenciais e configuração sem procurar o email no spam, pois ele ainda não chegou ao servidor destinatário. Quando existe nova tentativa, preserve o mesmo identificador funcional e registre cada chamada. Isso permite descobrir se o cliente recebeu duas mensagens depois que a primeira resposta demorou. Para recuperação de senha, o sistema também precisa definir qual token continua válido. Num backend como o [Supabase](https://promovaweb.com/blog/supabase-backend-vibe-coding), confira essa validade no serviço de autenticação, além do estado de envio. O template também participa da investigação: confira se o remetente e os links correspondem ao que o cliente espera receber. Uma mensagem aceita pelo servidor ainda pode apresentar um endereço quebrado. O artigo sobre [criação de templates com React Email](https://promovaweb.com/blog/react-email-processo-vibe-coding) acompanha a conferência do HTML, do botão e da saída plain text. ## A entregabilidade continua depois da aceitação O serviço de envio tenta entregar a mensagem ao servidor responsável pelo domínio do destinatário. A resposta pode indicar aceitação, rejeição temporária ou rejeição permanente. Leia o código e o texto devolvidos, pois “falhou” sozinho não diferencia endereço inexistente de política de autenticação. No envio pelo Email Service da Cloudflare, `delivery failed` registra uma falha de entrega, enquanto `rejected` indica destinatário na lista de supressão. Esse segundo estado não significa que o servidor destinatário recusou a mensagem. A [documentação dos logs](https://developers.cloudflare.com/email-service/observability/logs/) distingue esses estados de `delivered`. `Delivered` confirma a aceitação pelo servidor destinatário. Se o cliente não encontra a mensagem, procure nas outras abas e no spam, depois envie um teste equivalente para um endereço controlado. O serviço de envio não enxerga necessariamente a pasta escolhida pelo provedor. Um bounce permanente exige retirar ou corrigir o endereço conforme a resposta recebida. Repetir mensagens para caixas inexistentes piora a qualidade do fluxo e aumenta o volume de falhas associado ao remetente. ## O DNS mostra se o domínio autorizou o envio SPF fica num registro TXT e autoriza servidores a usar o domínio do remetente de envelope, informado no comando `MAIL FROM`. Esse domínio pode diferir do remetente visível na mensagem, conforme a [especificação SPF](https://www.rfc-editor.org/rfc/rfc7208.html). Ao adicionar um serviço, confira a política desse domínio e mantenha um único registro SPF nele. DKIM adiciona uma assinatura ao cabeçalho. O destinatário consulta a chave pública no DNS e confere se a assinatura corresponde à mensagem. Cada serviço costuma fornecer um seletor e os registros que devem ser publicados. DMARC verifica o alinhamento entre o domínio visível no remetente e o domínio autenticado por SPF ou DKIM. A política pode começar em `p=none` para coleta de relatórios e avançar para quarentena ou rejeição depois que as origens legítimas estão identificadas. Envie uma mensagem de teste para um endereço controlado por você e abra os cabeçalhos completos. Procure os resultados de SPF, DKIM e DMARC. Uma marca verde no painel do remetente não substitui o que o servidor destinatário registrou naquela mensagem. ## Relatórios DMARC revelam origens esquecidas Os relatórios agregados mostram quais servidores tentaram enviar pelo domínio e como passaram pelas verificações. Uma ferramenta antiga de suporte ou marketing pode continuar enviando depois que a configuração principal mudou. Confronte cada origem com a lista de serviços autorizados: autentique as origens legítimas e investigue as não reconhecidas antes de ajustar a política do domínio. Não avance imediatamente de observação para rejeição sem ler os relatórios. Uma origem legítima sem autenticação alinhada por SPF nem por DKIM pode ter mensagens rejeitadas quando a política endurece. Corrija os fluxos conhecidos e acompanhe o efeito. Reclamações e bounces também afetam a reputação do domínio. Remova endereços inválidos e processe cancelamentos, pois a autenticação não compensa uma lista de envio mal cuidada. ## BIMI identifica a marca em provedores compatíveis BIMI publica uma referência ao logo para provedores que oferecem esse recurso. A configuração exige DMARC em quarentena ou rejeição, aplicado integralmente, e um SVG Tiny PS. Alguns destinos exigem certificado, como explica o [guia de implementação do BIMI Group](https://bimigroup.org/implementation-guide/). O logo não comprova entregabilidade. Ele pode aparecer apenas depois que autenticação, política e requisitos do provedor estão atendidos. Use BIMI como identificação visual, sem colocá-lo no lugar de SPF, DKIM ou DMARC. Se a imagem não aparece, confira o registro, o arquivo e as exigências do destino. Não altere a política de email apenas para exibir o logo sem verificar o efeito sobre os envios legítimos. ## O Email Service muda o provedor, não a identidade Na [documentação consultada em 3 de outubro de 2026](https://developers.cloudflare.com/email-service/get-started/send-emails/), o Email Sending da Cloudflare ainda aparece como beta. Ele recebe mensagens por binding de Workers, API REST ou SMTP autenticado e exige que o domínio use DNS da Cloudflare. No vídeo, o painel do meu ambiente exibia um limite diário de 20 mil mensagens. Esse número pertence àquela configuração. A Cloudflare informa que limites variam com o histórico de envio e podem ser ajustados. Consulte a [documentação atual de limites](https://developers.cloudflare.com/email-service/platform/limits/) e o valor exibido no seu painel. Ao trocar o serviço, confira as credenciais e os registros de autenticação fornecidos pelo novo provedor. A política SPF depende do domínio de envelope usado no envio. Confira também templates, callbacks e tratamento de bounce: manter o mesmo remetente visível não conserva automaticamente a reputação dos IPs de envio. O artigo sobre [serviços da Cloudflare sem prender a stack](https://promovaweb.com/blog/servicos-cloudflare-sem-prender-stack) mostra como testar essa substituição por função. Para templates construídos com código, [React Email na stack de Vibe Coding](https://promovaweb.com/blog/react-email-stack-vibe-coder) percorre a geração da mensagem. ## Quando o log diz delivered e o cliente diz não recebi Abra a execução da aplicação e confirme o destinatário. Localize a tentativa no serviço de email e leia a resposta do servidor. Depois examine os cabeçalhos de uma mensagem equivalente recebida num endereço de teste. Se o servidor rejeitou, siga o código registrado. Se aceitou, peça ao cliente para procurar em spam e outras abas, sem afirmar que a mensagem chegou à caixa principal. Compare domínio, assunto e remetente com envios anteriores. Confira os relatórios DMARC e o histórico de bounces. Observe se uma mudança de provedor, volume ou template coincide com o início das falhas. Essa sequência produz uma hipótese que pode ser testada no próximo envio. As [ferramentas da Promovaweb](https://promovaweb.com/ferramentas) apresentam as funções de email e automação usadas na stack. A [Formação DevOps](https://promovaweb.com/devops) desenvolve DNS, publicação e observabilidade. Para configurar SPF, DKIM e DMARC no seu ambiente com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) mantém você no editor e no terminal durante a execução. Comece pelo último estado confirmado e siga a mensagem pela aplicação, pelo serviço de envio e pelo servidor destinatário para corrigir a integração que falhou ou investigar o posicionamento após a aceitação. Os resultados de autenticação nos cabeçalhos ajudam nessa leitura, mas você ainda precisa conferir a caixa postal para saber onde a mensagem foi colocada. ### O que a nota 40 do PageSpeed mostrou no meu site Astro? - URL: https://promovaweb.com/blog/astro-pagespeed-nota-mobile - Publicado em: 2026-09-07T12:00:00-03:00 - Descrição: Entenda o que a nota 40 do PageSpeed revelou no meu site Astro e como usei Claude para corrigir o desempenho sem confundir mobile e desktop. Leia. A nota mobile do PageSpeed Insights marcou 40 no site da Promovaweb já migrado para Astro. O relatório mostrou que trocar de framework não encerra o trabalho feito pelo navegador. Levei o relatório ao Claude para localizar alterações na implementação. Depois da intervenção, obtive 100/100 no desktop, mas os resultados são de modalidades diferentes e não permitem comparar os dois momentos. ## Direto ao ponto A nota mobile de 40 motivou a intervenção com Claude no site já migrado. O resumo preserva esse percurso, mas não traz o relatório original nem identifica os arquivos alterados. Para repetir a investigação no seu projeto, relacione cada apontamento ao recurso publicado e confira o resultado no navegador. Ao repetir esse trabalho no seu site, mantenha a mesma URL, a mesma modalidade e a versão publicada. Compare os indicadores além da pontuação. Uma execução isolada pode variar por rede, processamento e ambiente do teste. ## O relatório do PageSpeed precisa manter URL, modalidade e versão PageSpeed Insights combina uma análise de laboratório do Lighthouse com medições de acessos reais quando elas estão disponíveis. A [documentação do Google](https://developers.google.com/speed/docs/insights/v5/about) separa essas duas origens. Registre a URL, o horário, a modalidade mobile e os itens apontados. Anote também o commit que estava publicado. Esses campos impedem a comparação de uma versão nova com um relatório antigo atribuído à alteração errada. Mobile e desktop usam condições distintas. O resultado 100/100 no desktop confirma aquela execução depois da intervenção. Ele não prova que o mobile saiu de 40 para 100, pois a fonte não registra essa nota final. Como o Lighthouse documenta [variação entre execuções](https://github.com/GoogleChrome/lighthouse/blob/main/docs/variability.md), repita medições em condições semelhantes antes de interpretar uma diferença pequena. Variações mais amplas nos indicadores podem orientar a inspeção do recurso correspondente. ## Cada apontamento precisa levar a um arquivo Entregue ao agente o relatório junto do repositório e da URL testada. A resposta precisa identificar o recurso, mostrar onde ele é produzido e explicar o efeito esperado da alteração. “Otimizei a página” não oferece material suficiente para revisão. Quando o relatório destaca a imagem grande do topo, confira na aba Network qual arquivo chegou à página e localize a referência no componente ou no Markdown. Compare o formato e as dimensões do arquivo com os bytes transferidos para confirmar o que a página realmente carregou. O agente pode reduzir a imagem ou gerar outra versão. Compare os arquivos alterados e abra a página numa largura mobile. A fotografia precisa continuar legível e o espaço reservado deve evitar deslocamentos durante o carregamento. Uma mudança num componente compartilhado pode alcançar outras rotas, por isso localize seus usos e teste as páginas afetadas antes de publicar. O artigo sobre [Astro e WordPress após a migração](https://promovaweb.com/blog/astro-wordpress-trinta-dias-migracao) mostra por que a revisão visual acompanha a edição por arquivos. ## HTML pronto não elimina imagens e JavaScript Na configuração estática que uso, o Astro produz o HTML durante o build. O navegador ainda baixa fontes, imagens, estilos e qualquer JavaScript enviado pelos componentes interativos. Ao avaliar a [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders), separe esse carregamento do trabalho executado pelo backend. Os recursos enviados ao celular influenciam o tempo até a página ficar visível e utilizável. Astro também oferece [renderização sob demanda](https://docs.astro.build/en/guides/on-demand-rendering/), então confira a configuração real para saber se a página foi pré-renderizada ou processada durante o acesso. A marca do framework, sozinha, não informa qual opção o projeto usa. Componentes React podem gerar HTML sem carregar toda a biblioteca no cliente. As [diretivas de cliente](https://docs.astro.build/en/guides/framework-components/) definem quando a interatividade chega ao navegador. Retire JavaScript somente depois de confirmar que o botão, o menu ou o formulário continua executando sua função. Eu uso React na Promovaweb porque ele faz parte da implementação escolhida. Ele não é requisito para um site Astro. O relatório deve levar você ao componente que realmente executa no navegador, não a uma remoção genérica da integração. ## A pasta da imagem muda o tratamento recebido Astro processa imagens usadas pelos recursos próprios de imagem. Arquivos mantidos na pasta pública são copiados sem a mesma transformação automática, conforme a [documentação oficial](https://docs.astro.build/en/guides/images/). No [blog em Markdown com agentes](https://promovaweb.com/blog/markdown-blog-agentes-ia), confira também o metadado que aponta para a capa: trocar o arquivo no disco não altera uma referência escrita no artigo. Abra a requisição no navegador e compare o endereço recebido com o caminho usado no projeto. Uma versão otimizada pode existir no repositório enquanto a página continua apontando para o arquivo original da pasta pública. Depois da correção, confira o tamanho transferido e as dimensões exibidas. Verifique também o build. Um conjunto grande de fotografias pode aumentar o processamento durante a compilação e a hospedagem precisa terminar essa etapa antes de publicar o conteúdo novo. Na escolha de [hospedagem para o primeiro projeto](https://promovaweb.com/blog/hospedagem-para-iniciantes), o ambiente precisa executar e recuperar a publicação. Uma imagem menor não chega ao visitante se o deploy falhou e a página ainda serve a versão anterior. ## Feche a investigação na página publicada Depois de enviar a alteração, acompanhe o build até o fim. Abra a URL pública, navegue pelo celular e repita o PageSpeed na modalidade mobile. Compare os mesmos indicadores com o relatório preservado. Teste também o comportamento alterado. Abra o menu, envie o formulário e percorra os links principais. Uma página pode ganhar pontos ao retirar código necessário e perder a ação que levava o visitante ao conteúdo. O [Vibe Coding](https://promovaweb.com/vibe-coding) exige essa passagem entre instrução, alteração e teste. No [Plano IA Makers](https://promovaweb.com/planos/ia-makers), você aprende a revisar o trabalho do agente e publicar sistemas com uma forma explícita de conferência. Quando o relatório aponta um recurso que você não consegue relacionar aos arquivos, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) permite investigar a página com você operando o editor e o terminal. Minha nota 40 motivou o uso do relatório com Claude, seguido de commit e deploy. O resultado desktop de 100/100 pertence à medição relatada depois desse trabalho. No seu site, encerre a revisão repetindo o teste mobile na URL publicada e conferindo a função do componente alterado. ### Como acessar o Herdr na VPS pelo computador e celular? - URL: https://promovaweb.com/blog/herdr-ambiente-computador-celular - Publicado em: 2026-09-07T12:00:00Z - Descrição: Entenda como acessar o Herdr na VPS com o Termius pelo computador ou celular e quais tarefas exigem tela maior para a revisão. Continue a leitura. Uso o [Termius](https://promovaweb.com/ferramentas/termius) para entrar nas minhas máquinas remotas pelo computador e pelo celular. O Herdr fica na VPS, junto dos terminais dos projetos. Ao trocar de aparelho, eu mudo a tela de acesso, não a máquina que executa o trabalho. Essa separação torna o celular útil para consultar uma saída ou responder a uma pergunta curta. Ela não transforma uma tela pequena no melhor lugar para comparar muitos arquivos ou revisar uma interface inteira. ## Direto ao ponto Você acessa o Herdr na VPS por um cliente SSH (Secure Shell) instalado no computador ou no celular, enquanto o repositório, as dependências e os agentes permanecem no servidor. O aparelho envia os comandos e exibe as respostas. Antes de usar esse acesso fora da mesa, proteja a conexão, identifique a máquina e prepare uma forma de recuperar a sessão. No celular, limite-se a ações que você consegue ler e conferir naquela tela. ## O processamento permanece na VPS Uma aplicação Laravel, seus containers e os agentes de código executam na VPS no ambiente descrito. O notebook não precisa carregar essas dependências quando funciona apenas como cliente do terminal remoto. O artigo sobre [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) separa aplicação, banco e arquivos para conferir quais componentes estão naquela máquina. Isso permite abrir o mesmo ambiente num computador Windows, num notebook Linux ou num celular. Os comandos continuam sendo interpretados pelo sistema do servidor. Um aparelho modesto consegue acompanhar a tarefa porque não executa o build localmente. No meu uso, essa distribuição libera o notebook para edição de vídeo enquanto os processos do projeto permanecem na máquina remota. A experiência pertence ao meu fluxo. Ela não informa que qualquer VPS terá capacidade para compilar ou executar todos os projetos. Ao [escolher o provedor de VPS](https://promovaweb.com/blog/escolher-provedor-vps), confira CPU, memória e disco do servidor. Se um build consome toda a memória, trocar o dispositivo de acesso não resolve a falta de recurso. A investigação continua na VPS. ## Do endereço da VPS ao workspace correto Termius é o cliente usado para estabelecer a sessão SSH. Depois do acesso, você abre o Herdr no ambiente remoto e localiza o workspace do projeto. As ferramentas cumprem funções diferentes. Cadastre o host com um nome que identifique a máquina, como `developer-01`. Antes de executar qualquer comando, confirme o hostname e o diretório atual. Um terminal aberto com sucesso ainda pode estar conectado ao servidor errado. Ao trocar do computador para o celular, leia as últimas linhas da sessão. O agente pode ter terminado, falhado ou parado diante de uma pergunta. A interface preservada permite retomar essa leitura sem iniciar outra execução. O artigo da Promovaweb sobre [sessões na VPS com o notebook fechado](https://promovaweb.com/blog/herdr-sessoes-vps-notebook) explica o que continua ativo e o que precisa ser conferido depois de uma reinicialização. ## O celular atende consulta e intervenção curta Uma pergunta objetiva do agente cabe bem no celular quando a resposta já está documentada no projeto. Você abre o painel, lê o trecho anterior e responde sem mover o ambiente para outro computador. Logs curtos também funcionam nessa tela. Consulte a última saída de um serviço, confirme se o deploy terminou ou verifique se o agente aguarda sua participação. Evite editar um comando longo sem conseguir revisar todos os caracteres. O teclado virtual aumenta a chance de enviar símbolos incorretos. Comandos administrativos, alterações de firewall e ações sobre volumes merecem uma tela que permita reler a linha inteira e comparar a documentação. Se a mudança exigir comparação de arquivos, retome a sessão no computador, onde você consegue ler as alterações antes de executá-las. O processo continua durante a troca de tela enquanto a VPS e o servidor do Herdr permanecem ativos. ## A tela maior devolve a revisão do conjunto No computador, você consegue observar o terminal ao lado da comparação dos arquivos e da página renderizada. Essa disposição importa quando uma tarefa altera código, testes e interface. Abra o workspace correto e confira o estado do Git antes de ler o resumo do agente. Compare cada arquivo, execute os testes e navegue pelas rotas afetadas antes de aceitar a mudança. Painéis separados não isolam arquivos. Em [Codex e Claude por projeto no Herdr](https://promovaweb.com/blog/herdr-codex-claude-projetos), mostro como conferir diretório, área de trabalho e alterações antes de responder aos agentes. ## Proteja o acesso antes de sair da rede local Use chave SSH protegida e restrinja a porta administrativa por firewall, VPN ou uma lista de endereços. Não publique senha ou chave privada no repositório nem a envie nas mensagens para o agente. Uma solução como [Tailscale](https://promovaweb.com/ferramentas/tailscale) pode colocar o acesso numa rede privada entre seus dispositivos e a VPS. Teste o retorno antes de fechar o acesso público para evitar retirar sua única forma de administração. Durante alterações no SSH, mantenha uma sessão aberta e prepare o console do provedor para recuperação. Depois use uma segunda conexão, no computador ou no celular, para confirmar a nova configuração. Se o aparelho for perdido, revogue a chave ou o dispositivo autorizado. Proteja a tela com senha e mantenha as credenciais no armazenamento seguro do sistema. ## Troque de aparelho sem perder a referência Antes de sair do computador, deixe o workspace nomeado e o terminal no projeto correto. Registre a tarefa em andamento e o teste esperado. No celular, essa referência permite distinguir uma pergunta do agente de uma saída antiga. Ao voltar para a tela maior, releia a intervenção feita pelo telefone. Consulte o histórico, o estado do Git e a comparação dos arquivos. A sessão mostra a sequência necessária para essa revisão. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) desenvolve a base de servidores e acesso remoto. Quando existe uma tarefa técnica específica para investigar, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) permite que você opere o próprio editor e terminal com orientação ao vivo. Computador e celular abrem o mesmo ambiente remoto, mas atendem momentos diferentes. Use o celular para acompanhar e reserve o computador para comparar arquivos e interface. O servidor do Herdr mantém os processos durante a desconexão, conforme a [documentação de acesso remoto](https://herdr.dev/docs/persistence-remote/). Ao voltar, leia a última saída: o agente pode estar esperando sua resposta. ### Como uso Markdown e agentes de IA no blog com Astro? - URL: https://promovaweb.com/blog/markdown-blog-agentes-ia - Publicado em: 2026-09-04T12:00:00-03:00 - Descrição: Conheça meu trabalho com Markdown e agentes de IA no blog, da separação dos assuntos à manutenção de informações compartilhadas nos arquivos. Leia. Uma transcrição pode trazer a migração do site, a produção do blog e uma falha de desempenho na mesma gravação. Se eu orientar o agente a separar esses assuntos em artigos Markdown, ele pode produzir três textos parecidos, repetir a abertura e distribuir o mesmo argumento entre títulos diferentes. No blog da Promovaweb, eu uso Markdown para manter cada artigo como um arquivo revisável. O formato facilita a comparação das alterações, mas não escolhe o assunto nem garante uma voz humana. O trabalho editorial começa ao separar a pergunta de cada peça. ## Direto ao ponto Markdown funciona bem no meu fluxo porque Codex e Claude conseguem ler o conteúdo junto da implementação do site. Para trabalhar a partir de uma transcrição, preserve a fonte recebida e prepare uma base para os artigos. Antes de publicar, compare a redação com a fonte e leia o conjunto para encontrar repetições. Os metadados ligam o texto à data, à imagem, ao assunto e a outros conteúdos. Informações compartilhadas podem ficar em arquivos estruturados. Uma fonte canônica reduz versões divergentes quando você compara o resultado final com o valor registrado nela. ## A gravação não define a arquitetura do artigo Uma fala acompanha o tempo da apresentação, enquanto o artigo precisa seguir a pergunta do leitor. Se a gravação percorre a migração do WordPress, o Markdown e o PageSpeed, repetir essa ordem em três posts recria a mesma história sem respeitar o foco de cada texto. Neste conjunto, a rotina de edição orienta a comparação entre Astro e WordPress, enquanto fontes e arquivos servem de base ao texto sobre Markdown. A nota mobile de 40 conduz a análise de desempenho. Ao preparar os artigos, vincule cada fato à pergunta da peça para não repetir o mesmo argumento sob outro título. Mantenha a transcrição original intacta e corrija a grafia numa cópia separada. Ao encontrar uma opinião em primeira pessoa, volte ao trecho de origem. Se a experiência apareceu apenas no rascunho do agente, retire a atribuição antes de continuar o artigo. Esse cuidado também evita três introduções com “eu fiz, depois aconteceu”. A primeira pessoa entra apenas quando existe uso ou preferência confirmada. O restante fala diretamente com você e explica o mecanismo que pode ser conferido. ## O Markdown expõe o que mudou Um artigo em Markdown combina prosa, headings, links e metadados. Quando o agente altera um parágrafo, a comparação dos arquivos mostra exatamente quais palavras saíram e quais entraram. Você pode recusar aquela frase e conservar as alterações corretas no restante do arquivo. Essa transparência não resolve uma redação fraca. Um arquivo pode passar no Markdownlint e continuar cheio de frases simétricas, enumerações e conclusões genéricas. O lint encontra problemas de marcação. A leitura editorial encontra ritmo mecânico, tese repetida e voz distante. Compare também o arquivo com a página renderizada. Ali você encontra link para rota ausente, heading grande no celular ou capa incompatível com o assunto. A publicação exige a conferência do Markdown e do resultado visual. O artigo da Promovaweb sobre [Astro e WordPress após a migração](https://promovaweb.com/blog/astro-wordpress-trinta-dias-migracao) mostra como essa edição por arquivos alterou meu trabalho. A escolha continua pessoal: se o painel visual atende melhor redatores e editores, WordPress permanece válido. ## Metadados não devem aparecer como parágrafo público No frontmatter, o artigo registra os metadados usados pelo site para construir páginas e relacionar os conteúdos. Você recebe o resultado sem precisar conhecer o processo interno de catalogação. Antes de editar, o agente precisa conhecer o schema para não retirar o post da coleção com uma data incompatível, quebrar a navegação com uma tag fora da taxonomia ou deixar a página sem capa ao referenciar uma imagem inexistente. Depois da alteração, valide o arquivo e consulte a página gerada. Compare o corpo sincronizado com o mestre editorial para impedir que duas versões do mesmo artigo evoluam separadamente. No deploy, confira também se o endereço público serve a versão recém-compilada. Arquivos JSON entram quando várias páginas consultam a mesma informação estruturada. Um preço, um destino ou uma lista de ferramentas não deve ser atualizado manualmente em cinco lugares se o site já possui uma origem própria para esse conteúdo. Na [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders), frontend, banco e armazenamento têm funções próprias. Um JSON compilado com o site não registra um novo cadastro enviado pelo visitante. ## Uma correção mostra se a fonte é realmente única Imagine um preço exibido na página de um plano e no artigo que o apresenta. Altere o valor na fonte usada pelas duas páginas, gere o site local e abra cada endereço. Se o preço foi copiado para dentro do artigo, será preciso atualizar essa passagem também: um arquivo JSON não corrige prosa que deixou de consultá-lo. Se uma página continua com o valor antigo, descubra se ela possui conteúdo duplicado ou se o processo deixou de ler a fonte. Corrigir somente a página mascara a divergência e prepara outra inconsistência na atualização seguinte. O Git preserva o histórico dessa mudança. A mensagem registra o motivo e a comparação dos arquivos mostra o valor anterior e o novo. Para recuperar uma alteração, consulte o commit correspondente e confira a fonte atual antes de reaplicá-la. O ambiente escolhido para [hospedar o primeiro projeto](https://promovaweb.com/blog/hospedagem-para-iniciantes) precisa permitir gerar e publicar essa correção. ## O agente precisa receber limites editoriais Um comando curto como “escreva três artigos” deixa escolhas demais implícitas. Forneça a base correspondente, as diretrizes do canal, a pergunta principal e os links permitidos. No [Vibe Coding](https://promovaweb.com/vibe-coding), especificação, revisão e teste continuam sob sua responsabilidade. Para uma revisão, indique também quais arquivos podem ser alterados e quais fontes devem permanecer intactas. Depois, leia os artigos lado a lado. Procure aberturas equivalentes, headings com a mesma construção e fechamentos que apenas trocam o nome da oferta. Essa comparação de conjunto permite encontrar repetições que a leitura isolada deixa passar. O artigo sobre [a nota mobile no site Astro](https://promovaweb.com/blog/astro-pagespeed-nota-mobile) mostra outro papel do agente: trabalhar a partir de um relatório técnico e devolver uma alteração que ainda precisa ser testada. Em ambos os casos, o arquivo aproxima fonte, mudança e conferência. No [Plano IA Makers](https://promovaweb.com/planos/ia-makers), você aprende a especificar e revisar sistemas construídos com agentes. Se o seu site já mistura publicação, automações e componentes difíceis de localizar, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) documenta a jornada atual antes de ampliar a implementação. Eu escolhi Markdown para o blog porque os agentes já trabalhavam comigo nos arquivos da implementação. Essa escolha permite aproximar conteúdo e código no repositório. Para aproveitar o formato na publicação, preserve a fonte, compare as alterações e confira a página: são tarefas que o arquivo, sozinho, não executa. ### Como acompanhar Codex e Claude por projeto no Herdr? - URL: https://promovaweb.com/blog/herdr-codex-claude-projetos - Publicado em: 2026-09-04T12:00:00Z - Descrição: Veja como acompanhar Codex e Claude no Herdr, separar os terminais por projeto e identificar tarefas que precisam da sua resposta. Continue a leitura. No projeto Notas, mantenho o [Claude](https://promovaweb.com/ferramentas/claude-code) e o [Codex](https://promovaweb.com/ferramentas/codex-cli) em terminais separados. A lateral do Herdr permite localizá-los, mas não impede que ambos alterem o mesmo arquivo. No Herdr, workspace, aba e painel mostram onde cada terminal está aberto. Se dois agentes usam o mesmo diretório, compartilham os arquivos e a branch daquele checkout. Confira o caminho em cada painel: a disposição na tela não estabelece uma área de trabalho separada no Git. ## Direto ao ponto Use um workspace do Herdr para agrupar os terminais de um projeto e dê nomes que revelem o trabalho de cada agente. Antes de responder, confira o diretório atual, a tarefa exibida e os arquivos modificados. O painel mostra onde a execução está, e o Git mostra o que ela alcançou. Eu identifico painéis como `specs` e `brand` no projeto Notas. O nome distingue a especificação da marca, mas os arquivos continuam compartilhados se os dois terminais usam o mesmo diretório. Trocar a branch nesse checkout também afeta os dois. Para trabalhar simultaneamente em branches distintas, use diretórios de [worktrees separados](https://git-scm.com/docs/git-worktree). ## O nome do painel deve responder ao que está acontecendo Um rótulo como `terminal 2` perde utilidade quando cinco execuções ficam abertas. Prefira o objeto de trabalho: `specs`, `brand`, `api` ou `tests`. O nome identifica a tarefa mesmo depois que a posição do painel muda na tela. Dentro do terminal, confirme o caminho do projeto, pois diretórios com nomes parecidos podem apontar para repositórios diferentes. Antes de autorizar outra alteração, consulte o estado do Git e leia os arquivos já modificados. No meu exemplo, Codex e Claude aparecem na mesma interface porque participam do projeto Notas. Eu não concluo, a partir disso, que cada agente recebeu uma branch ou um worktree. A fonte registra os painéis, não o método usado para separar arquivos. Se as tarefas podem alterar a mesma implementação, delimite os arquivos de cada execução ou crie áreas de trabalho separadas no Git. Uma instrução escrita no prompt orienta o agente. A separação no repositório reduz a chance de uma alteração sobrescrever a outra. ## O estado visual exige leitura do terminal Herdr reconhece agentes pelos processos e pode interpretar a saída visível do terminal. Quando existe uma integração que informa o estado diretamente, essa informação substitui a leitura da tela, conforme a [documentação de agentes](https://herdr.dev/docs/agents/). O reconhecimento pode falhar depois de uma mudança na interface do agente, então confira a mensagem quando ela divergir do indicador. Abra o terminal e leia a última mensagem. O agente pode estar executando um comando, aguardando uma resposta, apresentando um erro ou concluído. Cada estado exige uma ação diferente. Quando há uma pergunta, recupere a tarefa original antes de responder. Uma escolha sobre schema, permissão ou arquivo pode alterar o alcance da implementação. Responder apenas para liberar o agente transfere uma definição importante para uma mensagem improvisada. Quando há erro, preserve a saída. Ela informa o comando, o arquivo ou o serviço que falhou. Iniciar a mesma tarefa em outro painel sem entender essa saída duplica o trabalho e dificulta comparar as alterações. ## Codex e Claude precisam de limites no mesmo projeto Imagine Claude revisando a identidade visual enquanto Codex altera o schema do [blog em Markdown](https://promovaweb.com/blog/markdown-blog-agentes-ia). Os temas parecem separados, mas ambos podem modificar um componente que renderiza a marca e lê o frontmatter. A divisão pelo nome dos painéis não protege esse arquivo compartilhado. Defina o alcance antes de iniciar. Numa tarefa de `brand`, informe os assets e componentes visuais permitidos. Para `specs`, indique os documentos de requisito e mantenha a implementação fora do escopo até a revisão. Depois compare os arquivos modificados em cada área. Se uma tarefa depende da outra, conclua a primeira revisão antes de liberar a seguinte. Um schema ainda instável pode fazer o agente de interface adaptar componentes a uma estrutura que será descartada minutos depois. O artigo da Promovaweb sobre [sessões na VPS com o notebook fechado](https://promovaweb.com/blog/herdr-sessoes-vps-notebook) explica por que os terminais continuam disponíveis. Continuidade aumenta a necessidade de registrar o alcance, pois uma execução pode permanecer aberta durante a mudança de dispositivo. ## A conclusão do agente abre a revisão Quando Codex ou Claude informa que terminou, leia o resumo e compare os arquivos alterados. O texto da resposta pode omitir uma mudança indireta feita por formatação, geração ou instalação de dependência. Escolha o teste conforme a tarefa. Uma alteração no schema exige validação da coleção, enquanto um [componente compartilhado do site](https://promovaweb.com/blog/astro-wordpress-trinta-dias-migracao) exige inspeção das páginas e larguras afetadas. Numa integração, reproduza os comportamentos de sucesso e falha. Em seguida, confira novamente o estado do Git e devolva a tarefa ao agente se houver arquivos inesperados, registrando o caminho, a saída do teste e o comportamento observado. O agente executa no terminal e Herdr mostra a sessão correspondente. Você aceita o resultado depois de ler a comparação dos arquivos e a saída dos testes. ## Um workspace por projeto reduz trocas de diretório Um workspace por projeto reduz a troca acidental de diretório, enquanto abas separam implementação, testes e logs. Painéis permitem observar duas execuções relacionadas sem abrir várias janelas SSH. Eu uso workspaces porque trabalho com agentes diferentes na mesma máquina remota. A lateral mostra qual terminal aguarda resposta, e o diretório confirma o projeto do próximo comando. A revisão continua apoiada na especificação, na comparação dos arquivos e nos testes. O acesso pelo [computador e pelo celular](https://promovaweb.com/blog/herdr-ambiente-computador-celular) amplia os lugares onde posso consultar esses estados. Para comparar muitas alterações, a tela maior e o terminal completo continuam mais adequados. No [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers), você aprende a especificar e revisar aplicações com agentes. Se uma tarefa técnica precisa ser investigada ao vivo no seu ambiente, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) mantém você no editor e no terminal durante o trabalho. No Herdr, o nome do painel leva você à tarefa. O repositório mostra o alcance nos arquivos alterados e confirma o resultado na saída do teste. Essa leitura evita atribuir à interface um isolamento que ela não oferece. ### Como usar AI Gateway, Vectorize e Agents na Cloudflare? - URL: https://promovaweb.com/blog/cloudflare-ai-gateway-vectorize-agents - Publicado em: 2026-09-03T18:00:00Z - Descrição: Entenda o papel de AI Gateway, Vectorize e Agents, como eles se combinam e quando separar observabilidade, busca e estado na sua aplicação. Leia agora. Uma instância do Agents SDK pode devolver um comando antigo, embora a resposta pareça plausível na tela. Nesse caso, a falha pode estar na chamada enviada ao modelo, nos trechos recuperados da documentação ou no histórico da sessão. O AI Gateway registra a chamada feita ao modelo, o Vectorize devolve trechos próximos da pergunta e o Agents SDK conserva o estado da interação. Uma chave comum permite relacionar a resposta à chamada, ao documento e à sessão. ## Direto ao ponto O gateway registra a chamada, mas não avalia se a resposta serve ao cliente. A busca vetorial aplica os filtros enviados pela aplicação, porém não define sozinha quais documentos cada sessão pode acessar. O runtime conserva o estado configurado. Você precisa relacionar a sessão às permissões atuais antes de recuperar os trechos e encaminhar o atendimento. Eu recomendo os serviços da Cloudflare quando cada componente atende a uma função da aplicação. Numa resposta errada, você precisa acompanhar a pergunta pela chamada ao modelo, pelos trechos recuperados e pelo estado da sessão. Abra cada registro e identifique a sessão correspondente para conferir se os três serviços participam desse percurso. ## Reconstrua a resposta que saiu errada Comece pelo identificador exibido junto da execução. Ele deve acompanhar a pergunta desde o backend, passar pela busca e aparecer no registro da chamada ao modelo. Sem esse vínculo, o suporte vê telas separadas e tenta adivinhar se a falha começou na recuperação ou na geração. Abra primeiro o conteúdo enviado ao modelo e compare as instruções com o provedor e o modelo configurados. Confira também a quantidade de tokens antes de investigar a resposta. O [AI Gateway](https://developers.cloudflare.com/ai-gateway/) centraliza chamadas de modelos da Cloudflare e de provedores externos, além de oferecer logs, cache, limites e tentativas adicionais. Esses registros mostram o que trafegou pelo gateway. Eles não informam se a versão do manual era a correta nem se o cliente tinha permissão para acessá-la. Uma resposta barata e rápida ainda pode usar uma fonte inadequada. ## Volte do trecho recuperado ao documento original O Vectorize guarda embeddings e retorna itens próximos ao vetor consultado. Em RAG (Retrieval-Augmented Generation), o índice costuma preservar um identificador que leva ao documento ou ao trecho de origem. Esse vínculo permite abrir o material usado pela resposta. O artigo sobre [Supabase como backend para Vibe Coding](https://promovaweb.com/blog/supabase-backend-vibe-coding) apresenta outra composição com busca vetorial dentro do PostgreSQL. Ao encontrar o comando antigo, abra o documento indicado pelo resultado e confira a data da versão indexada. Se a restrição ficou num fragmento e o exemplo em outro, ajuste a divisão antes de repetir a pergunta. Compare duas sessões com permissões diferentes para confirmar que o filtro não mistura documentos de clientes. Depois altere um documento, reconstrua o vetor e confira se a busca retorna a versão atual. Essa sequência testa autorização e atualização, falhas que uma consulta isolada não revela. A base original deve continuar disponível fora do índice. Se o Vectorize for substituído, você precisará gerar embeddings novamente a partir desses documentos e reconstruir metadados, filtros e relação com cada cliente. Exportar apenas os vetores não preserva necessariamente o material necessário para explicar uma resposta. ## Limite o estado mantido pelos Agents O Agents SDK usa Durable Objects para oferecer estado, sessões, WebSockets e agendamento. O estado guarda o identificador de uma sessão ou acompanha uma tarefa longa conforme a configuração escolhida. Não armazene toda mensagem de forma permanente só porque existe espaço para isso. Defina qual informação a próxima interação recupera, por quanto tempo e com qual chave de separação. Ao abrir duas sessões, a pergunta do primeiro cliente não pode aparecer na segunda. Ao revogar acesso a um documento, uma tarefa agendada depois da revogação deve respeitar a permissão atual. Defina uma forma de remoção do histórico compatível com a política da aplicação. Se o agente transforma uma troca de mensagens em resumo, registre a origem e a data usadas. Um resumo antigo pode continuar influenciando respostas mesmo depois que as mensagens foram retiradas da interface. ## Trate cache e tentativas como comportamento do produto O cache do gateway pode reduzir chamadas repetidas, mas uma resposta ligada a permissão ou conteúdo recente não deve reaparecer para a sessão errada. A chave usada no cache precisa distinguir os elementos que alteram a resposta. Uma pergunta igual não representa necessariamente a mesma consulta quando cliente, versão do documento ou acesso mudam. Defina quando o gateway fará uma nova tentativa. Se o modelo não respondeu, repetir a chamada pode ser adequado. Se a primeira execução produziu uma ação externa e a resposta se perdeu, uma repetição pode criar outro efeito. Separe geração de texto de ações com cobrança, envio ou alteração de cadastro. Você pode consultar latência, custo e falhas no AI Gateway e relacionar esses registros ao evento externo. A resposta do modelo, sozinha, não confirma que uma cobrança ou alteração de cadastro ocorreu antes da nova tentativa. ## Use cada serviço somente onde ele esclarece a aplicação Uma busca interna sem histórico duradouro usa Vectorize e um gateway sem Agents. Um chatbot sem base documental pode manter estado e logs sem índice vetorial. Uma chamada isolada ao modelo passa apenas pelo gateway quando não existe recuperação nem sessão. A dependência criada por essa integração também pesa na minha recomendação da Cloudflare. Para substituir o Vectorize, preserve os documentos que reconstruirão o índice. Ao trocar o runtime, confira o formato escolhido para o histórico. A chamada ao modelo precisa continuar acessível pela interface usada na nova composição. O artigo da Promovaweb sobre [serviços da Cloudflare sem prender a stack](https://promovaweb.com/blog/servicos-cloudflare-sem-prender-stack) detalha essa forma de testar substituições. O percurso entre [Pages, Workers, R2 e Hyperdrive](https://promovaweb.com/blog/cloudflare-pages-workers-r2-hyperdrive) mostra como identificar uma chamada entre serviços. Para projetos criados com IA, [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) explica por que banco, arquivos e filas precisam sair do computador usado no protótipo. No [Vibe Coding](https://promovaweb.com/vibe-coding), cada integração criada com IA continua sujeita a especificação, revisão e teste. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) desenvolve essa prática. Quando busca, histórico e chamadas ao modelo já se misturam numa aplicação existente, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) organiza a jornada e documenta a função de cada integração. Quando uma resposta sair errada, refaça o percurso com a pergunta conhecida, o trecho recuperado e o estado da sessão. Esse teste mostra se cada serviço cumpre uma função útil ou apenas amplia o painel. ### Como combinar Cloudflare Pages, Workers, R2 e Hyperdrive? - URL: https://promovaweb.com/blog/cloudflare-pages-workers-r2-hyperdrive - Publicado em: 2026-09-03T17:00:00Z - Descrição: Veja como Pages, Workers, R2 e Hyperdrive participam da mesma aplicação, a função de cada serviço e os limites que você deve acompanhar. Leia agora. Uma publicação no Cloudflare Pages pode terminar assim que o navegador recebe os arquivos gerados pelo Astro. Já um formulário com anexo continua pelo Cloudflare Workers, grava um objeto no R2 e consulta um banco externo pelo Hyperdrive. O percurso da requisição define os componentes necessários. No site da Promovaweb, eu uso o [Cloudflare Pages](https://promovaweb.com/ferramentas/cloudflare-pages) ligado ao repositório Git. Ali, a publicação estática termina no deploy. Para explicar Workers, R2 e Hyperdrive juntos, vou acompanhar outra jornada: o envio de um documento privado por um cliente. ## Direto ao ponto Pages serve o frontend produzido pelo build. No envio do formulário, o Worker valida a requisição, grava o documento no R2 e acessa o PostgreSQL ou MySQL externo por conexões reutilizadas pelo Hyperdrive. O log precisa relacionar essas etapas ao mesmo identificador. Os quatro serviços podem compor a arquitetura sem exigir adoção conjunta. Neste exemplo, R2 recebe o documento enviado e Hyperdrive conecta o banco externo. Em outra aplicação, o bucket pode servir arquivos existentes sem formulário de upload. Escolha a menor composição que complete a jornada e permita localizar uma falha. ## A publicação termina antes do cadastro O [Astro](https://promovaweb.com/ferramentas/astro) gera HTML, CSS e JavaScript durante o build. Pages publica esse resultado e relaciona a versão ao commit quando o projeto usa integração com Git. Se a página quebrar depois do deploy, compare o erro com as mudanças do commit que publicou os arquivos. Para projetos novos, a [documentação do Pages](https://developers.cloudflare.com/pages/) recomenda Workers, que também publica arquivos estáticos. O cadastro enviado pelo visitante não pertence a esses arquivos. Quando o formulário leva nome, email e documento, a aplicação precisa receber conteúdo novo depois da publicação. Colocar uma credencial no JavaScript do navegador permitiria que qualquer pessoa inspecionasse a chave, por isso o envio segue para um Worker. O código que usa segredos e grava conteúdo persistente precisa executar fora do navegador. Essa separação também participa de uma futura mudança de fornecedor, detalhada em [serviços da Cloudflare sem prender a stack](https://promovaweb.com/blog/servicos-cloudflare-sem-prender-stack). ## Como os Cloudflare Workers validam um envio antes de gravar o anexo O Worker recebe os campos, confere a sessão do cliente e valida tipo e tamanho do anexo. A origem permitida no navegador não substitui autorização, pois outra aplicação consegue chamar o endereço diretamente. O backend precisa relacionar a sessão ao cadastro que será alterado. Uma chamada externa também pode terminar de três formas diferentes. O provedor recusa a requisição, aceita o trabalho e responde, ou aceita o trabalho sem devolver a resposta no tempo esperado. Repetir o envio sem distinguir esses estados pode gravar o mesmo cadastro mais de uma vez. Inclua um identificador na requisição e preserve-o no log da função. Quando a interface mostra uma falha, esse valor permite encontrar a execução correspondente. O artigo sobre [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) desenvolve essa passagem entre código gerado, serviços externos e resultados que precisam ser conferidos. ## O arquivo não pode depender do próximo deploy Depois da validação, o Worker grava o documento num bucket do R2. O arquivo fica separado do resultado estático do build, portanto uma nova publicação não o remove. O cadastro guarda o identificador necessário para localizar o objeto. Um download privado pode passar novamente pelo Worker. A função confere a sessão e só então devolve o arquivo. Outra opção é emitir uma URL assinada pela interface compatível com S3. Durante a validade, qualquer pessoa que receba o endereço consegue usá-lo, por isso o prazo e o lugar onde a URL aparece fazem parte da implementação. Teste a autorização com duas sessões: o primeiro cliente envia e abre o documento, enquanto o segundo recebe a recusa prevista ao usar o mesmo identificador. Encontrar o objeto no bucket confirma a gravação, mas não a autorização. ## A consulta ainda chega ao banco de origem O Hyperdrive recebe a conexão do Worker e reutiliza conexões com o PostgreSQL ou MySQL. Isso reduz etapas de transporte, criptografia e autenticação que seriam repetidas a cada abertura. O banco continua hospedado fora da Cloudflare, com a latência e a capacidade definidas na origem. O cache de consultas exige atenção especial. Uma escrita não invalida automaticamente toda leitura armazenada, conforme a [documentação do Hyperdrive](https://developers.cloudflare.com/hyperdrive/concepts/how-hyperdrive-works/). Se o cadastro acabou de mudar, uma consulta pode mostrar a versão anterior até a expiração configurada. Reproduza a sequência real: atualize o cadastro e consulte-o logo depois. Para uma leitura que precisa refletir a gravação imediatamente, use a configuração sem cache indicada pela documentação. Compare também a conexão inicial com as chamadas seguintes para observar o efeito do pool. Região, suporte e recuperação da máquina que mantém esse banco estão detalhados em [como escolher um provedor de VPS](https://promovaweb.com/blog/escolher-provedor-vps). Hyperdrive encurta etapas da conexão, mas não corrige uma consulta sem índice, um servidor sem capacidade ou uma origem distante da região atendida. ## Filas entram depois da resposta ao navegador Alguns trabalhos não precisam manter o cliente esperando. A função pode gravar o cadastro, publicar uma mensagem numa fila e devolver um identificador. Outro processo lê a mensagem e executa uma tarefa demorada, como extrair conteúdo do documento. Uma mensagem pode reaparecer depois de uma falha. O consumidor precisa reconhecer o trabalho já concluído para não enviar outra notificação nem repetir uma cobrança. A aplicação define esse comportamento. A fila conserva o item pendente, mas não descobre sozinha se o efeito anterior já ocorreu. O artigo sobre [AI Gateway, Vectorize e Agents](https://promovaweb.com/blog/cloudflare-ai-gateway-vectorize-agents) examina a mesma distinção quando uma chamada ao modelo participa da tarefa. D1 atende outra função. Ele oferece um banco SQL baseado em SQLite dentro do ecossistema da Cloudflare. Escolhê-lo no lugar do PostgreSQL externo muda o modelo de armazenamento e de acesso, enquanto adicionar uma fila apenas separa o recebimento do processamento posterior. ## Confira a jornada inteira depois do deploy Abra a página publicada, envie um documento e acompanhe o mesmo identificador no Worker. Confirme a linha no banco, abra o objeto com a sessão correta e tente repetir o acesso com outro cliente. Em seguida, altere o cadastro e verifique se a leitura pelo Hyperdrive mostra o conteúdo novo. Na conferência final, o commit identifica a interface publicada, o log do Worker mostra a validação, o bucket contém o objeto e o banco guarda o cadastro. Se uma etapa falha, o identificador da requisição leva você ao registro correspondente. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) ensina a publicar, observar e recuperar esse tipo de aplicação. Para uma segunda leitura recorrente sobre uma arquitetura já ativa, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia) acompanha infraestrutura, deploy e comportamento do sistema. Eu gosto da praticidade da Cloudflare no site da Promovaweb. Para uma aplicação dinâmica, você precisa saber qual serviço responde por cada etapa e acompanhar a jornada do navegador ao banco. ### Quais serviços da Cloudflare usar sem prender sua stack? - URL: https://promovaweb.com/blog/servicos-cloudflare-sem-prender-stack - Publicado em: 2026-09-03T16:00:00Z - Descrição: Entenda como escolher serviços da Cloudflare por função, avaliar dependências e testar a migração de cada componente da sua stack. Leia o artigo. Você entra na Cloudflare para configurar o DNS (Domain Name System) e encontra serviços capazes de publicar o site, executar código e guardar arquivos. A barra lateral coloca todas as opções próximas. A arquitetura só precisa daquelas que participam de uma jornada identificada na aplicação. Eu uso o [Cloudflare Pages](https://promovaweb.com/ferramentas/cloudflare-pages) para publicar o site da Promovaweb em Astro. Essa experiência confirma que a plataforma atende à nossa publicação. Nos outros componentes, prefiro adotar uma função de cada vez e registrar o que precisarei alterar para substituí-la. ## Direto ao ponto Os serviços da Cloudflare fazem sentido na stack quando atendem a uma necessidade e você sabe como substituí-los. DNS, CDN (Content Delivery Network) e WAF (Web Application Firewall) alteram o caminho do tráfego. Publicação e código podem ser reconstruídos a partir do repositório, enquanto arquivos, tabelas, mensagens e vetores exigem transporte ou recriação. Trocar uma camada de entrada exige reproduzir registros, certificados, filtros e cache. Num serviço que guarda arquivos ou cadastros, você também exporta o conteúdo, adapta o código e testa a aplicação no destino. ## Comece pelo percurso que já existe Num site institucional gerado com [Astro](https://promovaweb.com/ferramentas/astro), o repositório preserva o código e a configuração do build, enquanto o Pages publica o resultado. Se a hospedagem mudar, esses arquivos continuam disponíveis, mas domínio e configurações específicas do provedor precisam ser recriados. Quando você acrescenta um formulário com anexo, o navegador envia campos para uma função, o arquivo segue para um bucket e o cadastro recebe um identificador. A aplicação ganha conteúdo que não existe no Git e precisa permanecer após uma nova publicação. Durante a troca de armazenamento, você também precisa manter a associação entre o cliente e o arquivo autorizado. O percurso está desenvolvido em [Pages, Workers, R2 e Hyperdrive na mesma aplicação](https://promovaweb.com/blog/cloudflare-pages-workers-r2-hyperdrive). Esse percurso revela o que cada produto acrescenta. Ele também impede que a arquitetura nasça da lista do painel. Se o site não recebe arquivos, não há motivo para incluir um bucket no desenho. Se uma página não executa lógica dinâmica, o frontend estático pode ser suficiente. ## Separe configuração, código e conteúdo persistente Um binding fornece um serviço ao Worker por uma variável do ambiente. O código pode chamar `env.BUCKET` sem enviar uma credencial do R2 ao navegador. A integração reduz configuração manual, mas também liga aquela função à interface oferecida pelo runtime. Antes de adotar o binding, localize os trechos que o chamam. Concentre o acesso ao armazenamento numa função da aplicação para reduzir o alcance de uma futura adaptação. Chamadas diretas em cada rota espalham a substituição por mais arquivos e testes. Para o conteúdo persistente, verifique se existe uma forma de exportá-lo e reconstruir suas relações. O R2 oferece uma API compatível com S3, com diferenças documentadas entre operações. Copiar objetos não preserva sozinho as permissões, os endereços públicos nem os identificadores gravados no banco. O mesmo raciocínio vale para D1. O SQL baseado em SQLite facilita a leitura do schema e dos registros, enquanto chamadas feitas pelo binding continuam específicas do ambiente. Uma exportação bem-sucedida comprova que o conteúdo saiu. A aplicação só está pronta depois que consulta, gravação e autorização funcionam no destino. ## Faça a troca em miniatura antes de depender do serviço Um teste de saída não precisa migrar o sistema inteiro. Reproduza o formulário com anexo num ambiente separado: envie o arquivo e o cadastro, transporte o objeto ao destino e tente abrir o documento primeiro com a sessão autorizada e depois com outro cliente. Durante o ensaio, uma biblioteca pode gravar o objeto no R2 e não oferecer suporte a outra operação necessária na API S3. O endereço assinado também pode mudar de formato, enquanto o cache continua servindo a versão anterior depois da troca do DNS. Cada diferença aponta a adaptação necessária no código ou na configuração. Para uma camada de entrada, observe o comportamento depois da resolução do domínio. Copie os registros e prepare o certificado, depois envie requisições que exercitem redirecionamentos e filtros do WAF. Confira se os cabeçalhos esperados chegam e se o cache devolve o conteúdo atualizado. ## Mantenha o banco acessível por outro caminho O Hyperdrive mantém conexões reutilizáveis com um PostgreSQL ou MySQL externo e reduz o custo de abri-las pela rede. Ao retirar o serviço, o banco continua na hospedagem escolhida, mas o backend precisa substituir esse caminho de conexão. A alternativa pode usar outro pool compatível com o ambiente de execução. Essa mudança altera as credenciais, a quantidade de conexões e o tempo das consultas. Confira se a origem aceita a carga esperada. Região, suporte e recuperação também entram na escolha do servidor, como detalho em [como escolher um provedor de VPS](https://promovaweb.com/blog/escolher-provedor-vps). Quando autenticação, arquivos e banco vêm de uma plataforma integrada, cada parte merece uma conferência própria. A comparação entre [Supabase Cloud e self-hosted](https://promovaweb.com/blog/supabase-cloud-self-hosted) mostra por que transportar PostgreSQL não transporta automaticamente login e objetos do Storage. ## Use a Cloudflare sem transformar o painel em arquitetura Eu continuo recomendando a Cloudflare para funções que atendem uma necessidade real. No site da Promovaweb, Pages resolve a publicação do resultado gerado pelo Astro e mantém o deploy relacionado ao repositório. Essa escolha tem uma função delimitada e uma forma conhecida de reconstrução. Ao avaliar outro serviço, registre qual jornada usa o componente e que conteúdo permanece nele. Defina também o comportamento que precisa sobreviver a uma substituição e teste uma versão pequena da troca. No caso de IA, o artigo sobre [AI Gateway, Vectorize e Agents](https://promovaweb.com/blog/cloudflare-ai-gateway-vectorize-agents) acompanha a pergunta até os registros mantidos em cada componente. Você precisa reconstruir esse percurso para conferir a resposta depois de uma migração. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) desenvolve a base para publicar, observar e recuperar aplicações. Se a stack existente já mistura bindings, armazenamento e configurações próprias do provedor, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) relaciona cada integração à jornada principal e documenta o que precisa permanecer durante uma alteração. Antes de ativar o próximo serviço, reproduza numa cópia da aplicação a ação que ele vai atender. Envie o documento, consulte o cadastro ou abra a resposta esperada. O comportamento que você precisa preservar durante uma substituição aparece nessa jornada e orienta a configuração do componente. ### Supabase Cloud ou self-hosted: qual vale a pena usar? - URL: https://promovaweb.com/blog/supabase-cloud-self-hosted - Publicado em: 2026-09-03T13:00:00Z - Descrição: Compare Supabase Cloud e self-hosted pelo custo do servidor, dos backups e das horas de manutenção necessárias para sua aplicação. Leia o artigo. Imagine uma falha num domingo, às 15h20: você tenta entrar na aplicação, mas o Auth não alcança o PostgreSQL. Numa instalação self-hosted do [Supabase](https://promovaweb.com/ferramentas/supabase), cabe a você abrir os logs, localizar o componente que parou e restaurar o acesso dentro do prazo combinado com os clientes. A comparação entre Supabase Cloud e self-hosted precisa incluir o atendimento dessa falha. Além de pagar pelo servidor, você precisa reservar horas para investigar, atualizar e recuperar o ambiente. A assinatura do serviço gerenciado pode compensar parte desse trabalho, conforme os componentes administrados pelo fornecedor. ## Direto ao ponto Minha preferência é o Supabase Cloud quando a instalação própria não atende uma exigência específica. O serviço gerenciado mantém a plataforma, enquanto você continua responsável pelo schema, pelas queries e pelas permissões da aplicação. A cobrança varia com assinatura, compute e recursos adicionais. Self-hosted faz sentido quando uma exigência mantém a infraestrutura numa rede ou localização determinada e a empresa consegue operá-la. Inclua no orçamento o servidor, as cópias externas e as horas de monitoramento, atualização e atendimento fora do horário comercial. ## Antes do incidente, existe uma rotina invisível A [documentação de self-hosting](https://supabase.com/docs/guides/self-hosting) usa Docker para instalar os componentes na infraestrutura escolhida. O ambiente iniciado pela CLI durante o desenvolvimento não representa sozinho uma instalação pronta para tráfego público. Os serviços evoluem em conjunto. Uma atualização precisa preservar a comunicação entre Auth, PostgreSQL, API e Storage. Voltar a imagem de um container não desfaz necessariamente uma migração aplicada ao banco, por isso o procedimento deve incluir compatibilidade de schema e sequência de retorno. Mesmo sem indisponibilidade visível, o servidor recebe atualizações e os volumes crescem. Certificados também vencem. Abra o resultado da rotina de cópia e restaure um arquivo em outro ambiente, pois a execução agendada pode falhar durante semanas sem chegar ao cliente. Esse trabalho fundamenta minha ressalva sobre instalar apenas para evitar uma mensalidade. O código aberto permite executar o Supabase em infraestrutura própria. Ele não fornece as horas nem o plantão necessários para manter essa instalação. ## Às 15h25, o log precisa indicar onde procurar O cliente informa que não consegue entrar. A primeira leitura separa falha no frontend, Auth indisponível e conexão recusada pelo PostgreSQL. Logs com horário e identificador permitem acompanhar a tentativa e comparar o relato recebido pelo suporte. Se o disco estiver cheio, liberar espaço pode devolver gravações temporariamente. A correção completa inclui localizar o crescimento, preservar os arquivos necessários e impedir que a rotina de backup ocupe o mesmo volume até interrompê-lo novamente. Se uma atualização incompatível atingiu o Auth, você precisa saber quais imagens estavam ativas e quais alterações chegaram ao banco. A recuperação usa registros técnicos preparados antes do domingo. Sem versão anotada e procedimento ensaiado, cada comando aumenta a incerteza. Uma aplicação que aceita algumas horas parada permite outra resposta. Um produto pago com prazo curto exige disponibilidade, monitoramento e um profissional capaz de agir. O valor dessa capacidade pertence ao custo mensal do self-hosted. ## Às 15h40, restaurar o banco ainda não devolve o contrato O backup do PostgreSQL não inclui os objetos enviados pela API do Storage. Ele preserva metadados, mas o arquivo precisa de uma cópia própria, conforme a [documentação de backups](https://supabase.com/docs/guides/platform/backups). Um ensaio de recuperação deve abrir uma jornada, não terminar no comando do banco. Restaure o PostgreSQL num ambiente separado, recupere os objetos e faça login com um cliente de teste. Consulte o cadastro e abra o contrato ligado a ele. O conjunto self-hosted padrão não traz o serviço de backups gerenciados nem o PITR (Point-in-Time Recovery) administrado do Cloud. Você pode construir retenção e recuperação próprias. Inclua armazenamento fora do servidor principal e tempo para testar cada etapa. No Cloud, confira quais recursos o projeto contratou e como estão configurados retenção e PITR. O nome da assinatura não informa sozinho se uma restauração também recuperará os arquivos do Storage. ## A fatura do Cloud tem mais de uma linha Na [página de preços do Supabase](https://supabase.com/pricing), consultada em 3 de outubro de 2026, o plano Pro começa em US$ 25 mensais e inclui US$ 10 em créditos de compute. A fatura também pode incluir consumo adicional, outros projetos e recursos contratados. Cada projeto executa sua instância de banco dentro da estrutura administrativa do serviço. Um ambiente extra pode acrescentar compute mesmo com a assinatura ativa. Projete desenvolvimento, homologação e produção de acordo com o uso pretendido. O Cloud mantém componentes da plataforma, mas não corrige uma query lenta. Antes de aumentar compute, abra o plano de execução, observe índices e confira quantas conexões o backend mantém. Revise também as policies de RLS e conserve a chave administrativa fora do navegador. O artigo da Promovaweb sobre [o backend do Supabase](https://promovaweb.com/blog/supabase-backend-vibe-coding) acompanha login, linha e arquivo pela aplicação. Essas responsabilidades permanecem com você nos dois formatos de hospedagem. ## Calcule o self-hosted com horas observadas Use uma atualização e uma restauração de teste para obter uma primeira medida. Registre preparação, execução, conferência e correção. Acrescente o acompanhamento das versões e a disponibilidade necessária para atender uma falha dentro do prazo prometido. O servidor exige capacidade de processamento e memória, espaço em disco e rede, além de um destino externo para as cópias. Uma instalação que precisa sobreviver à falha da máquina principal requer outra composição. O artigo sobre [como escolher um provedor de VPS](https://promovaweb.com/blog/escolher-provedor-vps) relaciona região, suporte e recuperação a essa escolha. A análise de [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) mostra o que conferir quando banco e arquivos ocupam serviços separados. Compare essas horas com a fatura prevista do Cloud usando a mesma jornada e o mesmo compromisso de recuperação. Hospedagem própria pode custar menos em moeda e mais em atenção técnica. Serviço gerenciado pode custar mais em assinatura e liberar os desenvolvedores da manutenção da plataforma. ## Quando a instalação própria se justifica Uma rede isolada pode exigir que todos os componentes funcionem dentro da infraestrutura da empresa. Um contrato também pode determinar localização ou forma de acesso aos registros. Examine a exigência concreta antes de concluir que o Cloud não atende. Capacidade existente muda a comparação. Uma empresa que já mantém PostgreSQL, containers, observabilidade e atendimento de incidentes consegue incorporar o Supabase à mesma rotina. Ainda precisa considerar os componentes adicionais e testar a recuperação completa. A explicação sobre [hospedagem para o primeiro projeto](https://promovaweb.com/blog/hospedagem-para-iniciantes) separa as tarefas cobertas pelo provedor daquelas que continuam com você. Não recomendo instalar o Supabase na infraestrutura da empresa apenas para reduzir uma mensalidade. O Cloud costuma compensar enquanto sua prioridade for desenvolver a aplicação. A instalação própria se justifica quando a empresa precisa do controle e pode assumir a manutenção contínua. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) desenvolve a base para manter servidores e testar recuperação. Para acompanhar uma aplicação já publicada, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia) oferece uma segunda leitura recorrente sobre arquitetura, infraestrutura e deploy. ### O que o Supabase oferece para projetos de Vibe Coding? - URL: https://promovaweb.com/blog/supabase-backend-vibe-coding - Publicado em: 2026-09-03T12:00:00Z - Descrição: Entenda como PostgreSQL, Auth, Storage, Realtime e Edge Functions formam o backend do Supabase e o que você ainda precisa revisar. Leia o artigo. Um protótipo criado por Vibe Coding aceita cadastro, login e upload em poucas horas. A tela funcionando pode esconder três permissões diferentes: acessar a aplicação, consultar uma linha no PostgreSQL e abrir um objeto no Storage. O Supabase reúne essas partes, mas a revisão precisa separá-las. Eu recomendo o [Supabase](https://promovaweb.com/ferramentas/supabase) para aplicações web e móveis porque ele mantém PostgreSQL, autenticação e arquivos no mesmo projeto. Essa proximidade reduz integrações iniciais. Ela também exige que você entenda qual componente autorizou cada ação antes de publicar o sistema. ## Direto ao ponto O Supabase oferece um backend baseado em PostgreSQL, com autenticação, armazenamento de arquivos e recursos de comunicação em tempo real. Você ainda precisa modelar tabelas, escrever policies de RLS (Row Level Security), proteger chaves administrativas e preparar a recuperação dos arquivos. Revise esse backend por uma jornada de teste: crie uma sessão, grave o próprio perfil, envie um contrato e receba uma atualização na tela. Em cada etapa, use uma segunda sessão para tentar o mesmo acesso. Assim você confere se a integração funciona e se a separação entre clientes foi preservada. ## O login identifica o cliente O Auth administra identidades e emite tokens para a sessão. Depois do login, o frontend envia esse token nas chamadas feitas às APIs do projeto. O banco usa a identidade da sessão durante a avaliação das policies. Autenticação e autorização não são equivalentes. Um cliente autenticado pode continuar sem permissão para abrir o contrato de outro cliente. Esse limite deve existir no banco ou no backend que medeia a leitura, pois esconder um botão na interface não impede uma chamada direta ao endereço. Uma chave administrativa contorna a RLS e precisa permanecer fora do navegador. Revise o bundle publicado e as variáveis expostas pelo framework. A chave pública adequada trabalha junto da sessão, enquanto segredos usados por integrações ficam numa função ou num backend protegido. ## A policy controla a linha no PostgreSQL PostgREST expõe tabelas pela API REST e `pg_graphql` oferece consultas GraphQL. Essas interfaces permitem que o frontend leia e grave sem abrir uma conexão administrativa com o PostgreSQL. A policy de RLS define quais linhas ficam disponíveis para a sessão. Na tabela de perfis, relacione o identificador do cliente ao usuário autenticado e teste com duas sessões. Ao ler e alterar o próprio perfil na primeira, você confere o acesso autorizado. Na segunda, a consulta precisa ocultar a linha alheia. Uma lista vazia pode ser o resultado correto da policy de leitura, mesmo quando a API responde sem erro. O papel `postgres` no serviço Cloud possui privilégios administrativos com restrições descritas na [documentação de superusuário](https://supabase.com/docs/guides/database/postgres/roles-superuser). O acesso ao PostgreSQL continua amplo, porém a plataforma gerenciada preserva limites operacionais. Trate extensões e comandos administrativos de acordo com o suporte atual do serviço. ## O arquivo fica no Storage e seus metadados no PostgreSQL Depois de criar o perfil, o cliente envia um contrato. Storage guarda o objeto num bucket e mantém metadados no PostgreSQL. A aplicação grava a relação entre arquivo e cadastro, além da política usada para permitir a leitura. Uma URL assinada concede acesso durante a validade a qualquer cliente que a possua. Para conferir a sessão a cada download, sirva o arquivo por uma função autenticada. Em ambos os casos, teste o endereço fora da sessão original e depois do prazo configurado. A recuperação merece um ensaio separado. O backup do banco inclui os metadados, mas não os objetos do Storage, conforme a [documentação de backups](https://supabase.com/docs/guides/platform/backups). Restaurar a linha do contrato sem restaurar o arquivo deixa a interface apontando para um objeto ausente. Prepare uma cópia externa dos objetos e restaure ambos num ambiente de teste. O cliente deve entrar, consultar o perfil e abrir o contrato recuperado. Esse percurso mede o que a cópia realmente devolve à aplicação. O artigo sobre [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) acompanha os testes separados para banco e upload. ## A atualização em tempo real respeita a mesma permissão Realtime envia presença, broadcast e alterações do banco por WebSocket. Num quadro colaborativo, o navegador recebe uma atualização sem recarregar a página. Nas alterações de tabelas, a RLS controla quais registros podem chegar à sessão. Broadcast e Presence exigem configuração de canais privados e policies próprias, conforme a [documentação de autorização do Realtime](https://supabase.com/docs/guides/realtime/authorization). Abra duas sessões e altere um registro visível apenas para a primeira. A atualização deve chegar ao cliente autorizado e permanecer ausente na outra sessão. Em seguida, interrompa a conexão e verifique como a interface busca o estado atual ao retornar. Para busca semântica, `pgvector` mantém embeddings no PostgreSQL. Preserve a relação do vetor com o documento original e aplique os filtros de acesso antes de enviar os trechos ao modelo. Uma consulta semelhante não pode atravessar a separação entre clientes. A explicação sobre [Vectorize e os serviços de IA da Cloudflare](https://promovaweb.com/blog/cloudflare-ai-gateway-vectorize-agents) examina essa relação entre documento, filtro e resposta numa arquitetura diferente. ## A função protege a credencial e a fila executa o trabalho demorado Uma Edge Function executa JavaScript ou TypeScript sobre Deno. Ela pode receber um webhook de pagamento e usar uma credencial privada para consultar o provedor. O log deve relacionar o identificador do evento à resposta externa, sem registrar o segredo. Para trabalho demorado, Supabase Queues usa `pgmq` no PostgreSQL. A função grava a mensagem, devolve um identificador e permite que outro processo continue depois. Como uma mensagem pode reaparecer, o consumidor reconhece o evento já processado antes de repetir uma cobrança ou notificação. Esses componentes não corrigem uma jornada indefinida. Especifique a resposta para webhook inválido, provedor lento e tarefa repetida. Depois execute cada situação no ambiente de teste e confira banco, log e efeito externo. ## O backend escolhe entre conexão direta e pool Uma aplicação [Laravel](https://promovaweb.com/ferramentas/laravel) persistente pode usar conexão direta ou o Supavisor em modo de sessão, conforme a rede e a duração das conexões. Funções serverless costumam usar o pool em modo de transação. Esse modo não aceita prepared statements, portanto a biblioteca precisa receber a configuração compatível. Timeouts e espera por conexão não se resolvem apenas com outro endereço. Consulte o tempo das queries, o número de sessões abertas e o plano de execução. O artigo da Promovaweb sobre [Laravel para Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) mostra como as convenções do framework apoiam essa revisão. ## Revise o Supabase pela jornada do cliente Eu considero a portabilidade maior no PostgreSQL do que nos serviços integrados. O banco preserva ferramentas conhecidas para transportar schema e tabelas, enquanto Auth, Storage, Realtime e funções carregam configurações próprias. Por isso, um `pg_dump` concluído não demonstra que login, arquivos e eventos funcionam no outro ambiente. A comparação entre [Supabase Cloud e self-hosted](https://promovaweb.com/blog/supabase-cloud-self-hosted) desenvolve essa responsabilidade. No [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers), essa revisão acompanha a construção de aplicações com IA. Para um protótipo existente com banco e integrações difíceis de explicar, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) documenta a jornada principal e identifica onde cada componente participa. Depois da restauração, abra novamente as duas sessões. O primeiro cliente deve encontrar o perfil e o contrato recuperados, enquanto o segundo continua sem acesso a eles. A recuperação precisa preservar os registros e as permissões que você conferiu antes de copiar o ambiente. ### Como escolher hospedagem para o seu primeiro projeto? - URL: https://promovaweb.com/blog/hospedagem-para-iniciantes - Publicado em: 2026-09-02T13:00:00Z - Descrição: Escolha a primeira hospedagem pela manutenção que você consegue fazer, com painel, suporte, backup e sinais para migrar da VPS simples. Confira agora. A tela de contratação informa a capacidade de processamento e o espaço disponível em disco. Depois do pagamento, você recebe um endereço IP e uma senha temporária para uma máquina vazia, mas o projeto que funcionava em `localhost` ainda precisa responder pelo domínio, receber HTTPS e continuar acessível depois de uma atualização. A qualidade da sua primeira hospedagem aparece nessa manutenção, não no tamanho do catálogo. Na primeira VPS autogerenciada, confira se o painel oferece console de recuperação e se a documentação explica como usá-lo. Verifique também se o suporte cobre falhas de rede ou do painel, já que você administra o código, o banco e os containers. A escolha precisa caber na manutenção que você consegue assumir. ## Direto ao ponto Abra o painel da hospedagem e localize o console de recuperação. Confira também como criar uma cópia da VPS, quanto custa renovar o plano e qual parte do suporte cobre falhas na rede ou no painel. HostGator e Hostinger oferecem uma experiência mais guiada para essa fase, mas preços e condições comerciais devem ser consultados na página atual de cada fornecedor. A VPS simples atende o código e o banco enquanto você consegue restaurar os dois no prazo aceito pelo cliente. Quando o PostgreSQL fica em outro host, avalie uma rede privada e restrinja as conexões por firewall e credenciais. O cluster se justifica quando a manutenção de uma máquina não pode retirar toda a aplicação do ar. ## O console do painel vale mais depois da falha do SSH Uma configuração incorreta do firewall pode encerrar seu acesso pelo terminal logo depois da atualização. Nesse instante, o console do provedor permite abrir a máquina por outro caminho, corrigir a porta e testar o SSH novamente. Sem esse recurso, uma falha pequena obriga você a acionar o suporte e esperar o atendimento. Você também precisa saber onde termina a responsabilidade do provedor. A empresa pode corrigir uma indisponibilidade da rede ou uma falha no painel. Um erro no container, no banco ou no código pertence à administração da aplicação. Essa separação evita abrir um chamado esperando uma correção que somente você consegue executar. O [guia da Promovaweb para corrigir o OpenSSH no Debian](https://promovaweb.com/blog/corrigir-cve-openssh-debian-sem-reiniciar) acompanha uma atualização com a sessão atual preservada e uma segunda conexão usada como teste. Para comandos longos, o artigo sobre [tmux no terminal](https://promovaweb.com/blog/tmux-produtividade-terminal) mostra como manter o processo ativo no servidor quando o notebook perde a conexão. ## A VPS exige uma rotina diferente da hospedagem compartilhada Uma hospedagem compartilhada costuma publicar WordPress e email numa instalação preparada. Na VPS, você administra uma máquina virtual e instala o sistema operacional, o Docker, o proxy e os serviços usados pelo projeto. A distribuição dos recursos físicos depende do plano contratado. Imagens prontas encurtam essa instalação, mas não explicam onde os volumes ficam nem como recuperar os registros gravados. O documento da aplicação precisa ligar a configuração ao que existe no servidor. Anote o domínio, o endereço da máquina e o volume do PostgreSQL. Guarde a chave de acesso num gerenciador adequado. Registre o comando que inicia os serviços e a tela usada para confirmar que a aplicação respondeu depois da publicação. O arquivo de composição do Docker liga cada imagem à rede usada pelo serviço e ao volume montado no host, mas não carrega o conteúdo do banco. Para testar uma cópia exportada do PostgreSQL, restaure o arquivo em outra máquina. Com o ambiente isolado do servidor original, você abre o login e consulta um cadastro que existia antes do backup. Depois, crie outro registro para conferir também a gravação no banco recuperado. Projetos criados com IA exigem a mesma conferência, pois o deploy pode esconder alterações no banco ou no armazenamento. A [revisão de Laravel no Vibe Coding](https://promovaweb.com/blog/laravel-vibe-coding-revisao) explica como comparar os arquivos modificados e testar o comportamento gerado. A análise sobre [Laravel para projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) mostra por que uma estrutura conhecida facilita localizar autenticação, filas e migrations. ## Painel e suporte ajudam a construir sua rotina HostGator e Hostinger podem atender um WordPress, um n8n ou uma aplicação pequena quando você ainda está formando a rotina de manutenção. Minha preferência pela HostGator considera a comunidade, o suporte próximo e a presença no Brasil. Essa escolha não dispensa o teste de restauração: a hospedagem continua adequada enquanto você consegue recuperar o ambiente e explicar a manutenção. Eu também conferiria a localização do servidor, a cobertura do suporte e o custo de renovação. Uma plataforma mais ampla não corrige falta de rotina. O painel da AWS ou da Oracle Cloud reúne serviços com permissões e cobranças próprias. Esse catálogo atende um sistema que usa computação, banco gerenciado e armazenamento do mesmo fornecedor. Para uma única VPS, ele pode acrescentar telas sem mudar o procedimento de restauração. ## A segunda máquina precisa resolver um limite observado A migração ganha sentido quando a VPS continua sem capacidade depois dos ajustes, quando o banco exige recursos diferentes ou quando uma atualização do host não pode interromper todo o serviço. A rede privada também se torna relevante ao separar a aplicação do PostgreSQL. [Hetzner](https://promovaweb.com/ferramentas/hetzner) e DigitalOcean oferecem recursos para ligar esses hosts, enquanto Oracle Cloud e AWS reúnem computação e serviços administrados no mesmo catálogo. Uma segunda réplica dentro da mesma VPS continua sujeita ao disco e à rede daquela máquina. Hosts diferentes criam outra possibilidade de recuperação, desde que banco e arquivos permaneçam acessíveis durante a saída de um deles. A mudança também acrescenta sistemas operacionais, logs e acessos para manter, então o teste de restauração deve justificar a complexidade nova. Você pode executar uma restauração de laboratório enquanto a hospedagem atual está funcionando. Publique uma cópia, abra os logs e refaça a jornada principal sem consultar o servidor original. O resultado mostra quais tarefas já fazem parte da sua rotina e quais exigem acompanhamento. No [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo), você trabalha no próprio terminal com orientação ao vivo para configurar Docker, deploy ou infraestrutura. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) aprofunda o uso do terminal na administração e na manutenção de servidores. O [vídeo sobre provedores de VPS](https://youtu.be/CYCY-FycXJo) compara a primeira hospedagem com ambientes distribuídos para você relacionar cada opção à próxima manutenção que pretende assumir. ### Qual infraestrutura uma aplicação de Vibe Coding precisa? - URL: https://promovaweb.com/blog/infraestrutura-vibe-coders - Publicado em: 2026-09-02T12:30:00Z - Descrição: Entenda a infraestrutura de banco, arquivos, filas, APIs e recuperação da aplicação criada com Vibe Coding depois do primeiro deploy. Continue a leitura. Você abre a aplicação de Vibe Coding no navegador local e o cadastro aparece. No primeiro deploy, a infraestrutura pode revelar o que ainda falta: o vídeo ocupa o disco, a resposta do modelo ultrapassa o limite da requisição e o cadastro some quando o container é recriado. O [Vibe Coding](https://promovaweb.com/vibe-coding) reduz o trabalho necessário para chegar a uma versão utilizável. A continuidade dessa versão depende de escolhas que o agente não assume por você: onde o PostgreSQL grava os registros, como os uploads sobrevivem ao deploy e qual processo retoma uma tarefa interrompida. Você enxerga a infraestrutura ao acompanhar uma jornada completa fora do editor. ## Direto ao ponto Siga o caminho de uma ação importante, como o envio de um documento. A aplicação registra o cadastro no banco, envia o arquivo ao armazenamento e coloca o processamento posterior numa fila. Cada etapa precisa deixar um estado que você consiga consultar depois de uma falha. A cópia de segurança só tem utilidade comprovada quando esse caminho funciona num ambiente restaurado. Uma VPS pode executar o código, com os registros num PostgreSQL gerenciado e os arquivos num object storage. Essa divisão faz sentido quando o disco local limita os uploads ou quando a restauração do banco exige uma rotina própria. Cada fornecedor acrescentado também traz uma credencial, uma fatura e uma conexão sujeita a falha. ## A infraestrutura aparece depois do deploy No ambiente local, o Docker pode instalar o PostgreSQL e gravar uploads no disco do notebook. Durante o deploy, você pode recriar o container a partir de uma nova imagem. A execução nova precisa receber as variáveis e montar o volume no mesmo destino. Um arquivo gravado somente dentro do container removido desaparece nessa troca, mesmo que a tela continue funcionando para novos cadastros. Você encontra outro tipo de falha quando uma migration interrompida impede o código novo de ler registros antigos. Uma credencial copiada manualmente também pode deixar produção diferente do ambiente usado no teste. A [revisão da Promovaweb sobre código gerado com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao) mostra como comparar os arquivos modificados e repetir no navegador a jornada afetada. Um diagrama da requisição liga o formulário ao PostgreSQL ou ao armazenamento e aponta a variável usada pelo container. Ao publicar outra imagem, você confere se o volume permaneceu montado e se a mesma jornada continua acessando os registros anteriores. ## Banco e upload exigem testes diferentes Num sistema de assinatura, o PostgreSQL pode ligar o cadastro do cliente à cobrança mensal e às permissões liberadas pelo plano. Quando você instala o banco na mesma VPS, simplifica o ambiente inicial, mas concentra registros e manutenção naquele host. Um serviço gerenciado assume instalação e atualização, enquanto você continua responsável por conferir os acessos e testar a restauração. Restaure uma cópia em outro ambiente e abra o login. Consulte um cadastro anterior ao backup sem recorrer ao servidor principal e confira o histórico preservado. Depois, crie outro registro para testar a gravação. Essa sequência verifica o banco de um modo que a mensagem “backup concluído” não consegue. A explicação sobre [Laravel para projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) localiza autenticação, filas e migrations dentro da estrutura do framework. O upload exige outra leitura. Um cliente pode enviar vídeos até ocupar o volume da VPS com a CPU ainda livre. O object storage retira esses arquivos do disco local, porém o código precisa registrar o endereço recebido e mostrar uma falha compreensível quando o serviço recusa o envio. Uma permissão ampla ou uma URL pública criada por engano pode expor um documento que deveria pertencer somente ao cliente autenticado. A interface precisa permitir uma nova tentativa quando o armazenamento recusar o upload. Se o arquivo for obrigatório para concluir o cadastro, a tela aguarda a confirmação antes de mostrar a conclusão. Esses comportamentos pertencem ao software e precisam aparecer nos testes, pois infraestrutura e produto se encontram nessa tela. ## A fila tira o processamento da espera do navegador O navegador não deve permanecer aberto até o fim do processamento de um vídeo. A aplicação grava a tarefa na fila, responde ao cliente e deixa o worker executar a etapa demorada. Uma interrupção pode devolver a mensagem para nova tentativa. O consumidor precisa reconhecer eventos já processados para não repetir uma cobrança ou o envio de um email. O agente pode criar o job e o worker. Você ainda define quantas tentativas são aceitas, quanto tempo o processamento pode usar e qual chave identifica a mesma solicitação. O histórico da fila deve mostrar a última execução e a resposta do serviço. No [processo de Vibe Coding com React Email](https://promovaweb.com/blog/react-email-processo-vibe-coding), o componente gera o HTML e permite conferir a mensagem que seguirá para o provedor de envio. CPU e memória não explicam uma consulta recusada pelo banco nem uma resposta lenta da API de IA. Um identificador de requisição permite localizar o mesmo evento no log da aplicação e depois na fila ou na integração externa. O registro precisa mostrar o serviço chamado, a duração e a resposta recebida sem gravar senha ou token. Agentes com acesso ao servidor ampliam a superfície de manutenção. O artigo sobre [memória, skills e ferramentas do Hermes Agent](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao) explica como delimitar comandos e conservar um histórico consultável das execuções. ## Meu LMS separa cada serviço pelo trabalho que ele faz No meu LMS, a aplicação roda na Hetzner e usa o Supabase para o banco da aplicação. A Cloudflare entrega os arquivos, enquanto os serviços do Google executam as funções de IA. Se uma aula não abrir, consulte o log para identificar se falhou o banco, a leitura do arquivo ou a chamada de IA. Essa composição não serve como modelo universal. Uma aplicação menor pode manter o código e os workers na VPS, usar um PostgreSQL gerenciado e enviar uploads para um serviço externo. O teste do upload e o log da requisição devem confirmar que a troca preservou o caminho usado pelo aluno. Se a separação não corrige um limite observado, ela apenas amplia o número de acessos e cobranças. Desenhe a jornada que já está publicada e escreva ao lado de cada conexão qual credencial o container usa e qual log registra uma recusa. O [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) transforma esse percurso numa sequência técnica documentada, relacionando cada serviço à infraestrutura usada pelo produto. O [Plano IA Makers da Promovaweb](https://promovaweb.com/planos/ia-makers) acompanha o desenvolvimento de aplicações com IA desde a funcionalidade até o ambiente publicado. O [vídeo sobre provedores de VPS](https://youtu.be/CYCY-FycXJo) compara uma máquina única, um cluster e uma composição entre fornecedores. Assista com o caminho da requisição aberto ao lado e marque cada serviço necessário para a jornada funcionar depois do deploy. ### Como escolher um provedor de VPS para a sua aplicação? - URL: https://promovaweb.com/blog/escolher-provedor-vps - Publicado em: 2026-09-02T12:00:00Z - Descrição: Compare provedores de VPS pela arquitetura e manutenção, do servidor único ao cluster, e relacione a escolha à recuperação do projeto. Confira agora. Duas aplicações podem usar menos de 20% da CPU e exigir infraestruturas bem diferentes. Pense num relatório interno que pode aguardar algumas horas até o servidor voltar. Num checkout durante uma campanha, a mesma interrupção pode deixar pagamentos sem confirmação na aplicação. Você vê um gráfico semelhante nas duas VPS, mas precisa combinar prazos de recuperação diferentes para cada serviço. Na comparação entre provedores, eu considero a importância da aplicação e a manutenção que você consegue assumir. A configuração da máquina precisa comportar o uso previsto, mas também deve permitir recuperar o serviço dentro do prazo combinado. Um catálogo amplo pode oferecer um banco gerenciado para você separar o PostgreSQL da aplicação. Num sistema pequeno, o console de recuperação permite acessar a VPS quando a conexão SSH falha. A utilidade de cada recurso depende do que você precisa administrar naquele ambiente. ## Direto ao ponto Uma VPS única pode atender quando você consegue restaurar a aplicação dentro do prazo combinado. O [Docker Swarm](https://promovaweb.com/ferramentas/docker-swarm) instalado em uma só máquina publica os containers conforme o arquivo da stack, porém todos continuam sujeitos à falha desse host. Num cluster, outra réplica pode receber a requisição se o encaminhamento permanecer disponível e ela conseguir acessar o banco e os arquivos após a saída de uma máquina. Para começar com uma VPS, eu prefiro a HostGator pelo suporte próximo e pela comunidade local. Hetzner e DigitalOcean entram na comparação quando você precisa de rede privada entre hosts ou quer provisioná-los por API. Oracle Cloud e AWS podem fazer sentido quando a arquitetura também depende de serviços gerenciados desses fornecedores. Compare a configuração disponível na região escolhida e o trabalho necessário para manter sua aplicação nesse ambiente. ## A mesma VPS pode servir ao relatório e falhar no checkout No exemplo do relatório, a consulta pode aguardar a restauração porque existe um intervalo até o próximo uso. No checkout, o cliente espera a confirmação da compra e pode procurar atendimento ao ver uma cobrança sem acesso liberado. Você precisa explicar quanto tempo o serviço pode ficar indisponível e como a aplicação reconhecerá os pagamentos recebidos durante esse intervalo. Você consegue testar a recuperação restaurando uma cópia fora do servidor principal e procurando a última venda gravada. O horário desse registro mostra quanto histórico o backup preservou. O tempo gasto até conseguir concluir uma nova compra mostra a duração da restauração, que pode terminar mesmo com vendas recentes ausentes do banco recuperado. Um webhook que não chegou à aplicação também não está automaticamente na fila. No ambiente de teste, confira se o fornecedor tenta enviar a confirmação novamente ou oferece uma consulta para recuperar o pagamento. A aplicação precisa reconhecer uma confirmação repetida para evitar a duplicação da venda. Sem esse mecanismo, o retorno da VPS pode exigir conferência manual dos pagamentos recebidos durante a interrupção. ## Uma stack organizada ainda pode parar numa só máquina Uma aplicação pode concentrar o proxy, o banco e os serviços de processamento numa única VPS. O proxy encaminha a requisição ao container da aplicação, que consulta o PostgreSQL e envia o trabalho demorado à fila. Separar esses processos facilita a atualização de cada serviço, mas a indisponibilidade do host interrompe todos eles. Duas réplicas dentro dessa VPS continuam usando a mesma máquina. No Swarm solo, o mesmo host administra o cluster e executa os serviços. O arquivo da stack descreve como publicar os containers e pode continuar útil quando outras máquinas forem adicionadas. Você consegue observar o limite dessa configuração ao desligar a VPS de laboratório: não existe outro host disponível para assumir o serviço. Manter acesso administrativo faz parte da recuperação. O [guia da Promovaweb para corrigir o OpenSSH no Debian](https://promovaweb.com/blog/corrigir-cve-openssh-debian-sem-reiniciar) explica o cuidado de preservar a sessão atual e conferir uma segunda conexão durante a manutenção. Para acompanhar comandos demorados, o artigo sobre [tmux no terminal](https://promovaweb.com/blog/tmux-produtividade-terminal) mostra como retomar uma sessão quando a conexão do notebook cai. O servidor precisa continuar funcionando para essa sessão permanecer disponível. ## O cluster precisa provar a saída de um host Três máquinas podem distribuir réplicas, mas você precisa conferir quais delas administram o Swarm. Com três managers, dois precisam continuar se comunicando para o cluster reorganizar os serviços após uma falha. Se o único manager ficar indisponível, os containers nos workers podem continuar executando, porém o Swarm não consegue realocar as tarefas. A [documentação de administração do Docker Swarm](https://docs.docker.com/engine/swarm/admin_guide/) explica essa exigência de maioria entre managers. O teste de continuidade precisa acompanhar uma requisição após a retirada de um host de laboratório. Uma réplica acessível ainda pode falhar ao consultar um PostgreSQL que estava na máquina retirada. Os arquivos enviados pelos clientes também precisam continuar disponíveis no armazenamento usado pela aplicação. Você confere a recuperação ao concluir a jornada, incluindo a leitura do registro e do anexo. Cada host acrescenta um sistema operacional para atualizar e novos logs para consultar. A restauração precisa de um procedimento compreendido por você, inclusive se a falha atingir o banco. Agentes instalados no servidor também executam comandos com as permissões disponíveis, tema desenvolvido no artigo sobre [memória, skills e ferramentas do Hermes Agent](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao). ## O provedor muda quando a manutenção muda No primeiro servidor, confira como acessar o console quando o SSH estiver indisponível. Uma reinstalação documentada ajuda você a reconstruir a máquina, mas o backup ainda precisa preservar o histórico da aplicação. A rede privada entra na comparação quando banco e aplicação ficam em hosts diferentes. Com um serviço gerenciado, parte da manutenção fica com o fornecedor conforme o contrato daquele serviço. Os componentes podem mudar de provedor em momentos diferentes. O código pode permanecer na VPS e consultar um PostgreSQL gerenciado, com os uploads armazenados num serviço externo. Você precisará acompanhar a conexão entre esses serviços e o efeito de uma interrupção em cada fornecedor. A análise de [Laravel em projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) examina as convenções de banco e filas usadas para organizar a aplicação no repositório. O procedimento de restauração mostra quais recursos você precisa procurar no provedor. Para revisar a arquitetura e acompanhar as alterações do ambiente ao longo do projeto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia) oferece acompanhamento técnico recorrente. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) desenvolve a prática de servidores e manutenção usada nessa comparação. No [vídeo sobre provedores de VPS](https://youtu.be/CYCY-FycXJo), eu apresento as opções guiadas e as plataformas para arquiteturas distribuídas. Assista com o prazo de recuperação e o procedimento de restauração da sua aplicação ao lado para comparar os fornecedores a partir do serviço que você precisa manter. ### Astro ou WordPress: o que aprendi após 30 dias de uso? - URL: https://promovaweb.com/blog/astro-wordpress-trinta-dias-migracao - Publicado em: 2026-09-01T12:00:00-03:00 - Descrição: Compare Astro e WordPress pela edição de artigos, pelos componentes e pela manutenção do site após minha migração para um fluxo com agentes de IA. Leia. Migrei o site da Promovaweb do WordPress para o [Astro](https://promovaweb.com/ferramentas/astro) porque Codex e Claude já trabalhavam comigo nos arquivos do repositório. Cerca de trinta dias depois, a edição dos artigos mostrava como esse fluxo se encaixava no meu trabalho. No WordPress, eu abriria o painel e alteraria os blocos. No fluxo que adotei, os artigos ficam em Markdown e a publicação segue pelo Git. Essa forma combina com meu trabalho atual. Para você, a melhor plataforma depende do lugar onde a edição realmente acontece. ## Direto ao ponto Eu prefiro Astro quando conteúdo e implementação já são mantidos em arquivos e os agentes participam desse trabalho. Continuo indicando WordPress para você que precisa editar pelo painel visual. O editor usado toda semana pesa mais que uma comparação abstrata entre tecnologias. A migração também transfere responsabilidades. No Astro, eu preciso conferir o Markdown, o build e a página publicada. WordPress concentra a edição no painel e possui outro conjunto de atualizações, plugins e hospedagem. Nenhuma escolha retira a manutenção do site. ## Uma correção de artigo mostra a diferença Imagine que o preço citado num artigo mudou. No WordPress, você localiza a publicação no painel, edita o bloco e visualiza o resultado. Permissões e histórico dependem da configuração adotada no site. No blog da Promovaweb, a edição ocorre no arquivo Markdown correspondente. O texto e os metadados ficam próximos, e o Git mostra as linhas removidas e adicionadas. Antes de aceitar a mudança proposta por um agente, compare esse conteúdo com a fonte usada no artigo. O arquivo não mostra toda a página. Depois do deploy, abra o endereço publicado para inspecionar a apresentação e testar os links e a imagem. Uma correção pode estar certa no Markdown e aparecer quebrada na interface por causa de um componente ou estilo. Minha preferência pelo Astro vem do trabalho com agentes nos arquivos do site. Para você que escreve diariamente no painel, transferir cada ajuste para o repositório pode dificultar a edição. Confira se será possível corrigir um artigo e visualizar a página com os acessos disponíveis. ## Componentes ampliam o alcance de uma alteração O site usa componentes React e estilos em Tailwind CSS. Um botão compartilhado pode ser alterado uma vez e reaparecer em várias páginas. O Git revela a definição modificada, enquanto a revisão visual precisa alcançar os lugares que reutilizam o componente. Trocar a cor do botão numa página clara parece simples. Em outra seção, o mesmo componente pode ficar sobre um fundo escuro e perder contraste. Abra as duas páginas, teste o foco pelo teclado e confirme que a ação continua funcionando. WordPress também reutiliza conteúdo: os [padrões sincronizados](https://wordpress.org/documentation/article/reusable-blocks/) atualizam conjuntos de blocos em vários lugares. Na edição visual, você cria o padrão no painel e confere as páginas que o utilizam. React foi uma escolha da Promovaweb, não uma exigência do Astro. O framework aceita [diferentes integrações de frontend](https://docs.astro.build/en/guides/framework-components/). Os componentes podem gerar HTML estático, enquanto as diretivas de cliente declaradas na implementação determinam o carregamento de JavaScript para interatividade. ## No Astro, o Git não publica sozinho No meu fluxo, enviar uma alteração aciona o build e o deploy. O registro no Git confirma que o arquivo chegou ao repositório. Ele não confirma que a compilação terminou nem que o endereço público mostra a versão nova. Quando o build falha, abra o relatório da execução e localize o arquivo indicado. Repetir a edição do artigo sem ler essa saída mistura um problema de conteúdo com uma falha de dependência, schema ou componente. A [nota mobile do site já migrado](https://promovaweb.com/blog/astro-pagespeed-nota-mobile) mostra outra conferência necessária depois de uma publicação concluída: o carregamento no navegador. Na configuração estática da Promovaweb, o HTML é preparado durante a compilação. Astro também permite [renderização sob demanda](https://docs.astro.build/en/guides/on-demand-rendering/). Uma página processada a cada acesso exige conferir onde esse processamento acontecerá e se a hospedagem oferece o runtime necessário. A comparação sobre [hospedagem para iniciantes](https://promovaweb.com/blog/hospedagem-para-iniciantes) parte justamente da manutenção que você consegue executar. Um blog estático e uma aplicação que grava cadastros não devem receber a mesma infraestrutura por conveniência. ## WordPress pode continuar como editor Migrar a construção das páginas não obriga você a abandonar o painel. A documentação do Astro explica a integração com [WordPress como CMS](https://docs.astro.build/en/guides/cms/wordpress/). O Astro consulta o conteúdo e produz a interface, enquanto redatores e editores mantêm o painel conhecido. Essa combinação preserva o painel e acrescenta uma integração. Você precisa conferir autenticação, disponibilidade da API e atualização do conteúdo no build ou na renderização escolhida. O WordPress continua ativo e precisa ser mantido. Minha escolha foi levar os artigos para Markdown porque eu já editava o site por arquivos com agentes. Se a publicação e a correção ocorrem pelo painel, manter o WordPress como origem preserva esse processo durante uma eventual mudança gradual. ## Trinta dias depois, eu escolheria pelo fluxo Astro combinou com a forma como eu escrevo e altero a Promovaweb. Os artigos ficam ao lado da implementação, e Codex e Claude consultam conteúdo e código no repositório. Essa proximidade explica minha preferência. Antes de publicar uma alteração no seu site, compare as linhas modificadas e abra a página correspondente. WordPress continua indicado quando a edição visual é central. A API REST também permite integrações externas, então a escolha não se resume a painel manual contra automação. Observe onde os redatores escrevem, como os editores revisam e se eles conseguem corrigir uma página sem interromper a publicação. O artigo sobre [Markdown e agentes de IA no blog](https://promovaweb.com/blog/markdown-blog-agentes-ia) mostra como os arquivos participam da produção editorial. Para aplicações que misturam site e funções dinâmicas, [infraestrutura para Vibe Coding](https://promovaweb.com/blog/infraestrutura-vibe-coders) separa frontend, banco e armazenamento. No [Plano IA Makers](https://promovaweb.com/planos/ia-makers), você aprende a construir e revisar sistemas com agentes. Quando a migração envolve componentes, build e deploy já existentes, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura) documenta a jornada atual e o alcance técnico da mudança. Antes de migrar, faça a mesma correção nas duas opções, localize o histórico e confira a página final. As etapas mostram qual plataforma cabe no seu ritmo de publicação. ### Como o Herdr mantém sessões na VPS com notebook fechado? - URL: https://promovaweb.com/blog/herdr-sessoes-vps-notebook - Publicado em: 2026-09-01T12:00:00Z - Descrição: Entenda o que continua rodando na VPS ao fechar o notebook com o Herdr e como conferir a sessão ao retornar ao trabalho no terminal. Continue a leitura. Depois de um fim de semana, voltei à máquina Developer 01 e encontrei o trabalho com Docker e Ansible no ponto onde eu havia parado. Essa continuidade explica por que mantenho meu ambiente de desenvolvimento numa VPS e acesso os terminais pelo Herdr. Fechar o notebook interrompe o acesso pelo cliente local. O processo continua na máquina remota enquanto o servidor e a sessão permanecem ativos. Essa distinção parece pequena até você confundir uma desconexão com uma execução terminada. ## Direto ao ponto Herdr separa a interface usada no seu dispositivo do servidor que mantém os processos. Ao fechar o notebook, você perde a visualização naquele aparelho. A VPS continua executando o terminal e o agente conforme o estado deixado na máquina remota. Uma sessão preservada pode conter um agente aguardando sua resposta. Reinicialização da VPS, processo encerrado e falta de recursos também interrompem o trabalho. Ao retornar, confira a máquina, o processo e a última saída antes de concluir que a tarefa ainda está avançando. ## O notebook fecha somente uma ponta da conexão No acesso remoto, seu notebook abre uma conexão SSH (Secure Shell) com a VPS. Um cliente como o [Termius](https://promovaweb.com/ferramentas/termius) envia os comandos digitados na tela local, mas eles são executados no Linux remoto. Repositório, dependências e processos ficam no servidor. Herdr possui cliente e servidor: o cliente apresenta workspaces, abas e painéis, enquanto os terminais permanecem ativos na VPS depois que a interface fecha. Desconectar o aparelho não envia um sinal para encerrar cada processo aberto. Você pode comprovar a separação com uma tarefa segura de teste. Inicie um comando que grave horário num arquivo por alguns minutos, desconecte o notebook e volte depois. O arquivo deve mostrar as gravações feitas durante a ausência. Faça o ensaio num ambiente sem informação de cliente e sem tarefa destrutiva. O objetivo é observar a continuidade da sessão, não testar a recuperação de produção pela primeira vez. ## Um agente aberto pode estar parado A sessão permanecer visível não informa que o Codex ou o Claude continua processando. O agente pode ter concluído, encontrado uma falha ou apresentado uma pergunta. O terminal preserva esse estado para sua leitura. Ao retornar, abra o workspace correto e leia as últimas linhas antes de enviar outro comando. Procure a saída do teste, a pergunta pendente ou a mensagem de erro. Iniciar outra execução sem essa leitura pode repetir trabalho e alterar os mesmos arquivos. No meu uso, a continuidade vale porque posso retomar o raciocínio junto do histórico exibido no terminal. Ela não transforma uma tarefa longa em autonomia ilimitada. Ao retomar, compare os arquivos alterados, execute os testes correspondentes e confira o resultado. O artigo da Promovaweb sobre [Codex e Claude por projeto no Herdr](https://promovaweb.com/blog/herdr-codex-claude-projetos) detalha como identificar os terminais antes de responder a um agente. ## Reiniciar a VPS muda o problema A reinicialização da VPS encerra os processos do sistema, enquanto fechar o notebook interrompe o acesso local. Serviços configurados para iniciar no boot podem voltar, mas a restauração visual do workspace não prova que todos os comandos retomaram do mesmo ponto, como explica a [documentação de restauração](https://herdr.dev/docs/session-state/). Depois de uma reinicialização, confira o horário de atividade do servidor, os processos esperados e os logs de cada serviço. Um container pode voltar automaticamente enquanto um comando iniciado num terminal permanece encerrado. A falta de memória pode encerrar um processo na VPS, mesmo sem reinicialização. Ao [escolher um provedor de VPS](https://promovaweb.com/blog/escolher-provedor-vps), confira a capacidade e monitore os logs durante o build. Um terminal preservado pode mostrar o erro depois que a execução já terminou. Se o trabalho precisa voltar depois de uma reinicialização, configure sua execução como serviço, job ou pipeline. A aplicação também precisa gravar o andamento e saber retomá-lo para evitar repetir uma etapa concluída. Um processo iniciado no boot não recupera automaticamente o ponto anterior. ## O tmux continua útil Nas edições Desktop e Server, o SetupVibe mantém Herdr e tmux, que podem coexistir: Herdr organiza workspaces e mostra agentes na interface, enquanto o [tmux preserva sessões no terminal](https://promovaweb.com/blog/tmux-produtividade-terminal) com comandos conhecidos e acesso por diferentes clientes. Minha preferência pelo Herdr acompanha a visualização dos projetos e agentes. Em manutenção remota, tmux continua útil para preservar logs e uma sequência de comandos que outro profissional pode retomar. Teste a recuperação do acesso numa máquina de laboratório. Anote o endereço da VPS, a chave usada, o workspace e o comando necessário para abrir a sessão. Depois conecte outro cliente, confirme o hostname e mantenha as credenciais num gerenciador fora do repositório. ## Retome pelo estado, não pela memória Ao voltar ao notebook, confirme a máquina, abra o workspace e leia a última saída do agente. Responda à pergunta com base no projeto, examine a saída se houve erro ou compare os arquivos depois da conclusão. Rode o teste relacionado antes de continuar a implementação. O acesso pelo [computador e pelo celular](https://promovaweb.com/blog/herdr-ambiente-computador-celular) usa a mesma separação entre dispositivo e servidor, mas a tela pequena funciona melhor para consulta e respostas curtas. Para revisar muitas alterações, prefira o computador. A [Formação DevOps da Promovaweb](https://promovaweb.com/devops) desenvolve a base para manter servidores, acesso e recuperação. Numa investigação técnica ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo) permite que você opere o próprio terminal com orientação. O fim de semana na Developer 01 mostrou o valor da sessão preservada para mim. O teste que você deve repetir é mais simples: desconecte, retorne e confira processo, saída e arquivo. Assim, fechar o notebook vira uma mudança de tela, não uma suposição sobre o servidor. ### Por que o Omarchy 4 pode combinar com Vibe Coding? - URL: https://promovaweb.com/blog/omarchy-4-vibe-coding - Publicado em: 2026-08-26T12:00:00Z - Descrição: O Omarchy 4 reúne workspaces, atalhos, agentes e uma shell baseada em Quickshell para Vibe Coding. Veja como avaliar esse ambiente no seu trabalho. Leia. Na minha rotina de Vibe Coding, o workspace do Specsfy fica com o navegador, o editor e o agente na mesma disposição e, quando troco para o LMS, não preciso fechar o primeiro projeto para abrir o segundo. No Omarchy 4, a tecla `Super + 2` me devolve a área de trabalho para retomar a revisão sem reconstruir a tela, e o ganho que observo está nessa retomada concreta, não numa promessa de que qualquer tarefa ficará mais rápida. A combinação interessa no Omarchy 4 porque aproxima as ferramentas da revisão de código. O sistema não substitui essa leitura. O workspace reúne navegador, editor, terminal e agente numa mesma tela. Você abre a tarefa, localiza os arquivos alterados e confere os testes sem remontar a cena. ## Direto ao ponto O Omarchy 4 pode combinar com Vibe Coding quando você quer tratar cada projeto como uma área de trabalho própria. Na documentação oficial atual, `Super + 1` a `Super + 4` trocam de workspace. `Super + Return` abre o terminal, e `Super + K` revela os atalhos. Essa sequência reduz a dependência do mouse, mas exige adaptação à lógica do Hyprland. O Specsfy fica com um workspace próprio, que reúne navegador e editor, terminal e agente. Outro workspace guarda o LMS. Quando o agente termina uma etapa, leio os arquivos alterados, rodo os testes e confiro o resultado na tela para retomar a tarefa pelo ponto que ainda precisa de revisão. O Omarchy 4 não elimina a necessidade de organizar o trabalho. Ele oferece uma forma específica de fazer isso: se você prefere menus e botões guiando cada ação, os atalhos e as janelas lado a lado exigem adaptação. Para acompanhar vários agentes durante o dia, teste se consegue localizar o projeto, o terminal e a alteração pendente sem procurar cada janela com o mouse. ## Um workspace do Omarchy 4 para cada projeto Cada workspace guarda uma tarefa com suas próprias referências. O Specsfy reúne navegador e editor, terminal e agente no mesmo espaço, enquanto o LMS guarda outra sequência de telas e arquivos. Ao alternar entre `Super + 1` e `Super + 2`, retomo cada projeto sem reconstruir a cena anterior. Os quatro atalhos oficiais para workspaces não obrigam você a manter quatro projetos abertos. Eles oferecem pontos previsíveis para separar o site da Promovaweb, o LMS, o Specsfy e uma tarefa temporária, e a quantidade real de áreas de trabalho depende da sua rotina. Cada workspace precisa conservar as páginas, o terminal e o editor consultados para uma tarefa específica. Com essa composição, a troca de número preserva a cena de trabalho em vez de abrir uma área vazia. ## Atalhos para acompanhar o trabalho Os atalhos mudam a postura diante da tela. No [manual oficial de hotkeys do Omarchy](https://omarchy.org/manual/hotkeys/), `Super + K` mostra a lista de comandos, `Super + Space` abre o menu, `Super + Return` abre o terminal e `Super + Arrow` move o foco entre as janelas. A mão procura menos botões, mas a cabeça precisa saber qual tarefa está sendo retomada. Na demonstração do vídeo, alguns nomes de teclas aparecem de outra maneira, como `Super + Enter` para o terminal. A tabela publicada neste artigo segue o manual atual, enquanto a gravação continua como relato da minha rotina. Assim, você consegue testar o comando na versão instalada sem confundir a experiência pessoal com a referência oficial. Você não precisa decorar os comandos no primeiro contato. Ao esquecer uma combinação, abra `Super + K`, escolha a ação na lista e repita o movimento até a mão associar a tecla à tarefa. O ganho está na repetição ligada a um projeto real, não em colecionar atalhos. ## O agente ocupa o mesmo espaço No workspace do Omarchy, o agente pode ficar ao lado do editor e do navegador, com a solicitação, os arquivos alterados e o comportamento da aplicação visíveis na mesma área. Quando o agente termina uma etapa, o próximo trabalho não é aceitar a resposta sem leitura. Eu abro os arquivos alterados, acompanho os testes e comparo o comportamento da aplicação com o que precisava ser entregue. Essa rotina aproxima o agente do projeto, mas mantém a revisão comigo. Esse cuidado vale também para um agente que leia arquivos, abra aplicações ou rode comandos. No artigo sobre [Hermes Agent](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao), eu mostro como memória, skills e ferramentas deixam o retorno visível no terminal e nos arquivos. O Omarchy muda a disposição da tela, mas a responsabilidade pela leitura continua no mesmo lugar. Essa proximidade também torna as permissões visíveis. Quando o agente abre o navegador, altera um tema ou instala um plugin, eu preciso saber qual arquivo mudou e qual comando foi executado. O [manual de plugins do Omarchy](https://github.com/basecamp/omarchy/blob/quattro/manual/32-shell-plugins.md) orienta revisar extensões de terceiros na ativação, prática que combina com a revisão do código. ## A escolha depende da tarefa A [página oficial de releases](https://github.com/basecamp/omarchy/releases/tag/v4.0.1) registra a `v4.0.1` como versão mais recente do Omarchy 4, publicada em 25 de agosto de 2026. Esse detalhe importa porque atalhos e plugins mudam, e você precisa consultar a documentação correspondente à instalação. Na divisão de trabalho que faço, o macOS fica com a câmera e as ferramentas das aulas e reuniões. O Windows continua ligado ao editor de vídeo e o Omarchy recebe o navegador, o terminal e o agente ao lado do editor para revisar uma tela do site ou do Specsfy. Cada plataforma acompanha a tarefa do dia, sem precisar vencer uma disputa entre sistemas. ## Os notebooks da experiência Um Galaxy Book 4 com processador i5 e 8 GB de memória aparece na gravação como a máquina usada para registrar a experiência. O Asus Vivobook com 16 GB fica como meu computador principal para o Omarchy, e esses números descrevem os equipamentos que eu usei, sem garantir o mesmo resultado em outra máquina. A experiência em um notebook não se transforma em especificação para todas as máquinas. O resultado depende de memória e processador, além de drivers, armazenamento e periféricos. Por isso, teste abrir o workspace, carregar editor e navegador e acompanhar o agente sem travar a revisão. Um workspace também pode guardar uma sessão de terminal que continua ligada ao projeto. Em um fluxo com [tmux](https://promovaweb.com/blog/tmux-produtividade-terminal), a janela do terminal vira o lugar para abrir comandos e acompanhar logs, testes e processos longos. Isso complementa os workspaces do Omarchy, porque a separação acontece na área de trabalho e dentro do terminal. ## Um teste que cabe na rotina Uma forma de testar o Omarchy sem misturar a experiência com a máquina principal é usar um notebook secundário. Instale a versão atual, leia o [manual oficial de atualizações](https://omarchy.org/manual/updates/) e observe a inicialização do workspace, a abertura do editor e a execução de uma tarefa simples. O teste precisa deixar visível o tempo que você leva para retomar o projeto e o que ainda exige mouse ou pesquisa. Para uma rotina com vários projetos, a combinação de workspaces, atalhos e agentes vale um teste controlado. Comece pela página de [Vibe Coding da Promovaweb](https://promovaweb.com/vibe-coding), confira o [Plano IA Makers](https://promovaweb.com/planos/ia-makers) e use o manual do Omarchy para comparar a instalação com o trabalho que você realmente faz. O sistema entra como ferramenta para acompanhar uma tarefa concreta, não como promessa de substituir todas as outras. ### Como comparar custo, latência e velocidade de modelos? - URL: https://promovaweb.com/blog/comparacao-gpt-luna-terra-custo-latencia - Publicado em: 2026-08-15T00:00:00Z - Descrição: Compare Luna max e Terra high por preço, latência e velocidade de saída. Veja como ler o custo de cada tarefa com os números publicados. Leia agora. Você pode olhar para o preço de um modelo, ignorar a latência e calcular um gasto baixo para cada token. Depois, a primeira resposta demora tanto que o trabalho perde ritmo. Também pode escolher o modelo que responde primeiro e pagar mais quando a quantidade de texto cresce. A comparação entre GPT-5.6 Luna (max) e GPT-5.6 Terra (high) mostra essa troca com números publicados, não com uma promessa geral de superioridade. Luna aparece com US$ 0,17 por 1 milhão de tokens e 165,6 tokens por segundo. Terra aparece com US$ 1,74 e 118,5 tokens por segundo. No tempo até o primeiro token, a latência muda a ordem: Terra aparece com 3,56 segundos e Luna max com 137,60 segundos. O custo por resultado precisa juntar preço, volume e tempo útil. ## Direto ao ponto Luna max parece mais atraente quando a tarefa consome muitos tokens e a velocidade de saída pesa no tempo total. Terra parece mais adequado quando você precisa começar a ler a resposta rapidamente. O preço por token abre a análise, mas a cobrança de entrada, saída e cache e o tempo até o primeiro token mostram quanto essa escolha realmente serve ao trabalho. ## Latência muda o custo do trabalho O tempo até o primeiro token mede a espera até a resposta começar. Na comparação consultada, Terra chega a 3,56 segundos, enquanto Luna max leva 137,60 segundos. A diferença muda o tempo útil de uma tarefa curta, principalmente quando você precisa ler o início para formular a próxima instrução. Uma tarefa com várias respostas pode consumir poucos tokens por chamada e ainda perder bastante tempo na espera inicial. Outra tarefa pode gerar um documento longo, aceitar uma espera maior e se beneficiar da velocidade de Luna depois do início. O mesmo preço unitário serve a trabalhos com ritmos muito diferentes. Por isso, eu registraria o tempo até a primeira resposta junto do custo e da quantidade de tokens. Essa medida mostra se o valor menor por token chega como economia real ou apenas troca dinheiro por espera. A [metodologia da Artificial Analysis](https://artificialanalysis.ai/methodology) separa esses componentes ao descrever cobrança e custo por tarefa. ## O preço por token só abre a medição Luna max custa US$ 0,17 por 1 milhão de tokens na página consultada. Terra custa US$ 1,74 pela mesma unidade. A diferença é relevante para uma integração que gera muitas respostas, mas o preço unitário não informa quantos tokens cada tarefa vai consumir nem quanto tempo você vai esperar pela resposta inicial. Uma aplicação pode enviar uma pergunta curta e receber poucas linhas. Outra pode incluir arquivos, instruções extensas e histórico antes de solicitar uma análise. A mesma tabela de preços serve aos dois casos, mas o gasto por chamada fica diferente. O volume de entrada já muda o valor antes de o modelo começar a escrever. Eu não usaria o US$ 0,17 como promessa de economia automática. O número é um ponto de partida para comparar o fornecedor. A economia aparece quando o modelo mantém qualidade suficiente para a tarefa, consome um volume adequado e entrega num intervalo que o trabalho suporta. ## Entrada, saída e cache mudam o gasto A [metodologia da Artificial Analysis](https://artificialanalysis.ai/methodology) informa que entrada, saída e cache participam da cobrança. A comparação combinada usa a proporção de 7:2:1 para cache hit, entrada e saída. Essa fórmula explica por que o preço mostrado no quadro não representa uma chamada isolada com qualquer formato de prompt. Tokens de entrada incluem o que você envia ao modelo e podem crescer com arquivos, histórico e instruções repetidas. Tokens de saída correspondem ao texto gerado, incluindo uma explicação curta ou um documento extenso. O cache reduz o custo de parte do material reaproveitado, quando a integração e o serviço mantêm essa condição. O histórico extenso entra na medição do gasto, porque cada chamada recebe mais material. Um agente que gera respostas longas pode consumir mais tokens de saída. Uma aplicação que repete instruções pode ter parte do conteúdo aproveitada no cache. A leitura precisa acompanhar essas superfícies, não somente o preço que aparece no catálogo. ## Velocidade de saída aparece depois da largada Luna max aparece com 165,6 tokens por segundo e Terra com 118,5 tokens por segundo. Essa medida mostra a velocidade durante a geração. Ela não substitui o tempo até o primeiro token, porque a resposta pode começar tarde e depois ser produzida num ritmo maior. Para uma resposta longa, a velocidade de Luna pode reduzir o intervalo entre o primeiro trecho e o final do documento. Em perguntas curtas, a espera até o primeiro token ocupa uma parte maior da experiência. Terra entrega o início em 3,56 segundos na comparação, e isso pode ser mais importante que a velocidade posterior. Quando você acompanha o tempo total, separe pelo menos esses dois momentos. O primeiro mostra quando a resposta se torna utilizável para orientar a próxima ação. O segundo mostra quanto tempo a geração leva depois do início. Misturar os dois produz uma leitura imprecisa do trabalho. ## O custo por tarefa depende do volume A metodologia informa que o custo por tarefa considera a quantidade de tokens consumida pelos modelos no conjunto de avaliações. Essa métrica é diferente do preço por token. Um modelo pode ter um preço unitário mais baixo e produzir uma resposta que consome mais tokens. Outro pode custar mais por unidade e resolver a mesma solicitação com menos texto. O tamanho da resposta não é o único ponto. A tarefa pode exigir reasoning, leitura de imagem, comparação de arquivos ou uma explicação detalhada. O modelo precisa receber o material, processar a solicitação e gerar a saída. O uso real revela a relação entre esses volumes. O índice publicado pela Artificial Analysis reúne nove avaliações e mostra Luna com 52 e Terra com 50. Eu trataria essa pontuação como consulta ao conjunto avaliado. Para escolher um modelo para o seu projeto, compare o prompt e os arquivos enviados, o tempo de espera até a resposta e a qualidade do que você consegue aproveitar dentro do custo total. ## Uma medição que cabe no trabalho Você não precisa começar com uma planilha complexa. Separe uma tarefa que representa o uso real e registre o horário do envio, o momento do primeiro token, o momento do último token, os tokens de entrada e os tokens de saída. Repita o mesmo prompt nos dois modelos e preserve o arquivo usado na comparação. Depois, compare a resposta com o trabalho que ela deveria atender. Ela precisa trazer a informação usada na próxima ação, evitar uma nova instrução e produzir um arquivo que passe pela sua conferência. O preço menor só importa quando a saída atende ao trabalho sem criar novas correções que consomem tempo. Uma medição curta representa chat e suporte. Uma resposta longa ou uma tarefa técnica com arquivos exige uma medição que acompanhe o trabalho inteiro. A comparação fica mais útil quando cada teste representa o fluxo que você realmente pretende manter. ## O modelo participa de um sistema maior A escolha de Luna max ou Terra não fica isolada no campo do fornecedor. Ela entra numa aplicação que vai do prompt ao histórico, passa por cache e armazenamento e ainda cruza fila e revisão. O artigo sobre [memória, skills e ferramentas no Hermes Agent](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao) mostra como o modelo participa de uma operação maior. A resposta precisa chegar ao lugar certo e preservar informações que o próximo trabalho vai usar. Num agente de atendimento, o volume de mensagens e o tamanho do histórico alteram o gasto. O artigo sobre [custo previsível em agentes de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel) trata essa relação como parte da operação. O modelo escolhido precisa caber no fluxo de mensagens, no tempo aceito e na forma de acompanhar o consumo. Esse raciocínio também serve para uma rotina de [Vibe Coding](https://promovaweb.com/vibe-coding). O prompt, os arquivos do projeto e a revisão da resposta formam o trabalho inteiro. O modelo participa da geração, mas a utilidade aparece quando você consegue conferir e aplicar o resultado. Eu começaria medindo uma tarefa curta, observando o tempo até a resposta inicial, e uma tarefa longa. Na longa, compararia volume, tempo total e velocidade de saída. Num documento extenso, o preço menor e a geração rápida de Luna entram diretamente na medição. Num chat com perguntas sucessivas, o início rápido de Terra ocupa o primeiro lugar. Esses números mostram qual modelo serve ao trabalho. Se a sua rotina envolve desenvolvimento, agentes e SaaS, o [Plano IA Makers](https://promovaweb.com/planos/ia-makers) reúne esse tipo de trabalho em uma trilha própria. Antes de trocar o modelo da integração, confirme os preços na fonte e compare a tarefa que você realmente executa. A fotografia consultada em 15 de agosto de 2026 serve para esta análise, não para prometer o mesmo valor no futuro. ### Como o React Email coloca o email na stack do Vibe Coder? - URL: https://promovaweb.com/blog/react-email-stack-vibe-coder - Publicado em: 2026-08-14T13:30:00Z - Descrição: Entenda como o React Email coloca templates na stack do Vibe Coder com React, Tailwind e TypeScript, mantendo limites técnicos visíveis. Leia agora. O email costuma ficar fora da stack principal do produto e recebe uma rotina separada de criação. A aplicação usa React enquanto a mensagem segue outro caminho para montar, revisar e publicar o layout. O [React Email](https://react.email/) aproxima o template do código da aplicação e mantém a criação dentro da stack principal. Componentes, props, TypeScript e Tailwind entram na mensagem enquanto HTML e plain text formam a saída para envio. ## Direto ao ponto Para o Vibe Coder, a principal mudança do React Email é a continuidade da stack de criação. Você trabalha com componentes e estilos conhecidos sem fingir que o email funciona como página web. Na criação e manutenção dos templates, você abre o componente, localiza o estilo e ajusta o layout dentro do projeto. A IA pode gerar uma primeira versão, mas HTML, plain text, links e apresentação ainda precisam de conferência. ## O template entra no projeto junto com o produto Uma aplicação SaaS reúne telas, rotas, clientes e permissões no mesmo produto. As mensagens de boas-vindas e cobrança fazem parte dessa experiência junto do convite de acesso. Quando os templates ficam fora da aplicação, uma alteração simples exige reunir arquivos e ferramentas diferentes. Uma prop muda no modelo do usuário, o texto acompanha a mudança e a imagem da campanha recebe outro endereço. O React Email aproxima o template desse fluxo sem transformar o email em uma página web. O arquivo recebe props, usa componentes conhecidos e participa do mesmo histórico de mudanças da aplicação. Esse movimento combina com a forma de trabalhar do [Vibe Coding](https://promovaweb.com/vibe-coding). A IA lê os componentes disponíveis no projeto e trabalha em uma estrutura que você consegue abrir no editor. ## Componentes aproximam identidade e conteúdo Um email reúne partes com funções próprias e cada trecho atende uma etapa da mensagem. O React Email oferece componentes nomeados para organizar cada parte dentro do template. Os nomes dos componentes deixam a identidade visual ligada ao conteúdo do template. Um `Button` recebe URL e texto por props enquanto um `Heading` pode apresentar o nome da oferta. A mesma estrutura também pode receber variações de conteúdo sem duplicar o layout inteiro. Uma mensagem de convite pode trocar o nome da empresa, a data e o endereço da confirmação. O [hub de ferramentas da Promovaweb](https://promovaweb.com/ferramentas) reúne tecnologias usadas em diferentes partes da stack. Para você, essa coerência reduz a distância entre código, conteúdo e apresentação. ## A IA encontra uma estrutura que você consegue ler A IA trabalha melhor com um objeto definido, uma entrada clara e uma saída que você consegue conferir. Isso vale para um template de email com hierarquia, conteúdo, props e limites visuais explícitos. Uma solicitação ligada a componentes oferece uma superfície concreta de trabalho. Você pode descrever um `Container`, uma `Section`, um `Heading`, dois blocos de `Text` e um `Button` com URL validada. TypeScript lista os valores usados pelo template e torna suas interfaces mais legíveis. O componente pode declarar nome, empresa, link e texto de preview antes do envio. Essa forma de trabalhar não transforma a IA em revisora final do email. A [formação IA Makers da Promovaweb](https://promovaweb.com/formacoes/iamakers) apresenta Vibe Coding como um fluxo de especificação, desenvolvimento, teste e publicação. ## A manutenção acompanha a campanha O primeiro template quase sempre parece simples porque reúne saudação, imagem, explicação e botão. A complexidade aparece depois, quando o produto precisa enviar mensagens diferentes para cada situação. Um cliente pode receber boas-vindas, outro pode receber confirmação de pagamento e outro pode precisar recuperar acesso. As mensagens compartilham marca e componentes, mas usam valores e ações diferentes. Quando os templates vivem na mesma stack, você localiza essas diferenças no código. Uma prop controla o título, uma condição define a seção exibida e um componente compartilhado mantém o rodapé. O artigo [sobre escolher Laravel para projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) trata de uma ideia próxima sobre stacks reconhecíveis. No email, componentes e props deixam a manutenção mais concentrada e simples de descrever para a IA. O texto sobre [testar código gerado por IA com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao) mostra o passo seguinte à geração: abrir o código e conferir o comportamento. Eu começaria essa leitura no componente, no HTML renderizado e na apresentação nos clientes. ## A continuidade termina na caixa de entrada Usar a stack da aplicação não muda a forma como os principais clientes de email interpretam HTML. O React Email informa testes nesses clientes sem garantir apresentação idêntica para todo template. O componente `Tailwind` também documenta limites para estilos usados em clientes de email. A documentação cita o `pixelBasedPreset` para situações nas quais a unidade `rem` cria diferença visual. Essa parte precisa entrar no fluxo do produto desde a primeira versão. Você escolhe os clientes principais e depois confere HTML, plain text e apresentação. O linter de links, o verificador de compatibilidade e a análise de spam apoiam essa revisão. O [utilitário de renderização](https://react.email/docs/utilities/render) mostra como converter o componente para HTML e plain text. A saída gerada vira uma superfície de comparação entre versões do template. Se um botão perde espaço, uma imagem ultrapassa a largura ou o plain text omite a chamada principal, você volta ao componente responsável. ## Quando colocar o email na stack vale a pena Eu colocaria o React Email na stack quando a mensagem participa da experiência do produto. Isso acontece quando o email recebe valores da aplicação, usa variações ou precisa acompanhar a identidade visual. A ferramenta também serve para projetos pequenos que já usam React, Tailwind e TypeScript. Um email simples e pontual pode continuar em um editor próprio quando a separação não cria retrabalho. O React Email coloca o template perto do código e mantém a caixa de entrada como parte da tarefa. Você ganha uma forma conhecida de compor a mensagem e continua lendo HTML e conferindo clientes. Essa é a boa notícia para o Vibe Coder porque o email entra na stack sem esconder suas limitações. A criação fica próxima do trabalho diário com componentes, estilos e props antes do envio. ### Por que o React Email muda a criação de emails modernos? - URL: https://promovaweb.com/blog/react-email-processo-vibe-coding - Publicado em: 2026-08-14T13:00:00Z - Descrição: Veja como o React Email aproxima React, Tailwind e TypeScript da criação de emails, preserva componentes e exige conferência nos clientes. Leia agora. Você já pode criar interfaces com React, organizar estilos com Tailwind e tipar props usando TypeScript. Ao montar um email, porém, você encontra HTML específico, suporte desigual para CSS e clientes com interpretações diferentes. O [React Email](https://react.email/) aproxima essas tarefas sem tratar a caixa de entrada como um navegador. A ferramenta oferece componentes como `Html`, `Body`, `Container`, `Text`, `Button` e `Tailwind` dentro de uma stack familiar. ## Direto ao ponto O React Email muda o ponto de partida porque coloca React, Tailwind e TypeScript no começo da criação. Você escreve componentes, define props e renderiza a saída para HTML ou plain text. Essa aproximação não elimina a conferência porque Gmail, Outlook, Apple Mail e outros clientes interpretam HTML com recursos próprios. A mudança aparece na forma de manter o template e não em uma promessa de apresentação idêntica. ## A criação de email começa com restrições diferentes Uma interface web costuma funcionar dentro de um navegador com suporte amplo para HTML, CSS e JavaScript. O email chega a destinos com engines diferentes e configurações próprias para imagens, fontes, links e modo escuro. Essa diferença altera o trabalho desde o primeiro arquivo do template. Você precisa planejar a composição visual, a saída plain text e os clientes relevantes para a mensagem. O [repositório do React Email](https://github.com/resend/react-email) apresenta componentes para criar emails com React e TypeScript. A documentação também reúne recursos de Tailwind e ferramentas para conferir a saída. Essa estrutura combina com Vibe Coding porque a IA e você conseguem reconhecer os objetos do template. A autoria fica próxima da stack web enquanto as limitações próprias do email permanecem visíveis. ## O componente muda o ponto de partida O React Email oferece componentes que nomeiam partes recorrentes do email e tornam a leitura do template mais direta. Componentes como Container e Section ajudam você a localizar a responsabilidade de cada trecho. Esse vocabulário aponta o arquivo e o trecho que a IA precisa alterar durante o desenvolvimento. Você pode indicar um `Heading` para o título e um `Button` para uma URL específica. Os componentes não resolvem sozinhos a mensagem, o conteúdo ou a composição visual do email. Eles mantêm cada parte no lugar correspondente e oferecem uma superfície concreta para revisar. Se o botão apresenta espaçamento errado, você procura o `Button` e acompanha suas propriedades. Se uma divisão visual precisa mudar, você examina a `Section` sem percorrer uma tabela extensa. No [Vibe Coding da Promovaweb](https://promovaweb.com/vibe-coding), essa estrutura mantém o diálogo com a IA ligado ao projeto. Você descreve a alteração, abre o arquivo modificado e compara o resultado com a intenção original. ## Tailwind e TypeScript mantêm a stack reconhecível O Tailwind aproxima a definição visual do componente e mantém classes de estilo junto do elemento que recebe a alteração. Para você que já usa essa abordagem em interfaces, o template exige menos troca entre arquivos. O próprio React Email documenta o componente [Tailwind](https://react.email/docs/components/tailwind) e registra limites importantes para alguns clientes. A documentação também cita o `pixelBasedPreset` para situações nas quais `rem` produz diferença visual. TypeScript acrescenta uma camada de leitura porque a interface de props explicita os valores recebidos pelo template. Nomes como username e company deixam os valores do botão visíveis antes da renderização. Essa combinação aproxima a intenção do código e deixa a revisão concentrada no arquivo alterado. A IA pode sugerir uma prop para uma variação, mas você confere o tipo e renderiza o template antes do envio. ## Compatibilidade continua sendo parte da criação O React Email informa testes em vários clientes conhecidos de email e apresenta essa cobertura na documentação. Essa informação não promete a mesma apresentação para toda versão, dispositivo ou configuração. O mesmo HTML pode receber interpretações diferentes entre clientes de email. Uma propriedade CSS pode ser ignorada, uma imagem pode mudar de largura e uma fonte pode cair para outra família. Por isso, a conferência entra no fluxo desde o começo da criação. Você escolhe os clientes relevantes, renderiza uma versão, observa o resultado e ajusta o componente. A documentação do React Email também apresenta recursos para conferir HTML e CSS, validar links e analisar spam. Esses recursos apoiam a revisão sem substituir a leitura da mensagem nas superfícies que recebem o email. ## Renderizar é uma etapa, não o encerramento O [utilitário de renderização](https://react.email/docs/utilities/render) mostra como transformar um componente React em HTML. A mesma documentação apresenta a conversão para plain text para mensagens lidas sem HTML. Criar o componente representa apenas uma parte do trabalho com email. O template precisa produzir HTML legível, plain text coerente, links válidos e imagens com texto alternativo. A renderização oferece uma superfície útil para comparar versões do mesmo template. Você altera uma prop, troca uma classe do Tailwind, renderiza novamente e observa a diferença no HTML. Se o layout perde espaçamento ou o botão fica sem contraste, o HTML gerado aponta o componente responsável. Esse fluxo aproxima a autoria da stack web sem tratar a caixa de entrada como uma tela de navegador. ## O que muda para o Vibe Coding Eu vejo a principal mudança do React Email no ponto de partida da criação. Você usa React, Tailwind e TypeScript presentes no projeto sem abandonar as exigências próprias da caixa de entrada. A IA pode gerar uma primeira versão, propor componentes e sugerir estilos para o template. Você continua responsável por conferir a estrutura, revisar o conteúdo e observar a saída nos clientes relevantes. A [formação IA Makers da Promovaweb](https://promovaweb.com/formacoes/iamakers) apresenta Vibe Coding como desenvolvimento acompanhado por especificação, implementação, teste e publicação. O React Email se encaixa nesse fluxo porque transforma o template em uma peça legível e conferível. Eu usaria essa proximidade para comparar [por que escolher Laravel para projetos de Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) e [como testar código gerado por IA com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao). Esses textos mostram como localizar o controller, abrir o teste e conferir o comportamento alterado. O React Email não elimina a parte difícil da criação de emails. Ele coloca essa parte perto da stack web, com componentes reconhecíveis e uma saída que você consegue examinar. ### Por que escolher Laravel para projetos de Vibe Coding? - URL: https://promovaweb.com/blog/escolher-laravel-vibe-coding - Publicado em: 2026-08-12T13:00:00Z - Descrição: Entenda por que o Laravel oferece arquitetura e convenções para sistemas com IA. Veja como localizar o código e revisar o comportamento. Leia agora. Eu vou trabalhar com Laravel, Node e Astro nesta série. Para começar, escolhi o Laravel porque ele deixa a arquitetura do sistema visível enquanto você desenvolve com IA. A rota recebe a requisição, o middleware confere o acesso, a policy define a permissão e a migration registra a mudança do banco. Esses nomes ajudam você a descrever uma alteração e, depois, localizar o que o agente modificou. Quando aprendi a dirigir, fiz autoescola em um Fox vermelho. Aquele carro me ensinou a sair, frear, subir uma ladeira e observar o trânsito. O modelo mudou, mas os fundamentos continuaram comigo. Quero usar o Laravel na Promovaweb do mesmo jeito: como um framework concreto para você aprender a estrutura de uma aplicação e reconhecer os mesmos problemas quando trabalhar com Node, Python ou outra stack. ## Direto ao ponto Escolhi o Laravel para Vibe Coding porque ele oferece uma estrutura conhecida para o código gerado pela IA. Você consegue indicar onde uma permissão deve ser aplicada, como uma mudança no banco será registrada e qual teste deve confirmar o comportamento. A documentação e as convenções do framework também oferecem referências que o agente consegue consultar durante o trabalho. Essa escolha ganha valor depois que a primeira tela fica pronta. Um sistema recebe novos recursos, muda a estrutura do banco, processa tarefas em segundo plano e precisa preservar permissões já existentes. O Laravel distribui essas responsabilidades por partes reconhecíveis do projeto, o que permite revisar a alteração no arquivo certo e conferir o resultado com testes. ## Um framework dá nomes ao sistema que a IA modifica Uma instrução como “crie uma área para administrar os membros de uma empresa” abre vários trabalhos dentro da aplicação. Existe a tela, a rota usada para gravar o formulário, a validação dos campos e a permissão que separa um membro comum de um administrador. Quando o projeto segue as convenções do Laravel, cada responsabilidade possui um nome que você pode citar na instrução enviada ao agente e encontrar no repositório. Esse vocabulário muda a qualidade da revisão. Você pode abrir a policy para conferir a autorização, ler a migration associada ao novo campo e executar o teste que reproduz o acesso permitido e a recusa. A resposta escrita pelo agente explica o trabalho realizado, enquanto os arquivos registram o comportamento que a aplicação executará. Eu considero esse aprendizado mais útil do que decorar a sintaxe de PHP. A IA consegue escrever uma função, completar um controller e sugerir um teste. Você precisa reconhecer a função de cada parte para conferir se o conjunto ainda representa o sistema que pretende colocar em uso. ## O projeto continua compreensível depois do primeiro prompt A primeira versão costuma caber numa instrução curta: cadastro, painel e alguns botões. Depois chegam os convites entre membros, as assinaturas, os emails e as tarefas que devem rodar fora da requisição principal. Um projeto improvisado espalha essas responsabilidades pelos arquivos criados durante cada alteração. O Laravel oferece lugares conhecidos para cada uma delas. Quando você adiciona a data de aceite de um convite, a migration mostra como o banco mudou e a policy revela qual membro pode concluir a ação. Se o convite também envia um email, o job mantém esse trabalho fora da resposta principal. O teste reúne essas partes num comportamento executável, então uma nova sessão com a IA consegue reconstruir a mudança pelos arquivos do repositório, mesmo depois que o histórico do chat anterior foi encerrado. O framework também impõe limites úteis ao agente. Um arquivo fora da pasta esperada, uma classe com nome incompatível ou uma migration mal formada pode produzir uma falha visível. A convenção oferece uma forma de localizar o desvio e corrigi-lo na mesma parte do projeto. ## Laravel Boost conecta o agente ao projeto e à documentação O Laravel existe há anos, possui documentação extensa e mantém convenções adotadas por uma comunidade ampla. Quando um agente encontra uma rota, uma Form Request ou uma relação do Eloquent, ele pode consultar material público sobre aquela estrutura. O mesmo trabalho fica mais difícil num projeto cuja arquitetura foi criada durante instruções sucessivas e nunca recebeu documentação. O [Laravel Boost](https://laravel.com/docs/13.x/boost) aproxima ainda mais o framework dos agentes de código. Ele fornece acesso a informações da aplicação e à documentação correspondente. O agente consegue consultar rotas, configurações e o esquema do banco enquanto trabalha. Esse acesso oferece uma fonte mais precisa para a implementação. A comparação dos arquivos alterados e a execução dos testes continuam necessárias. Eu uso esse acesso para aproximar a implementação do projeto real. O agente consulta os arquivos, escreve a alteração e executa as verificações. Durante o trabalho, acompanho a estrutura escolhida, a permissão aplicada e o comportamento que será entregue. ## Starter kits encurtam o caminho até uma aplicação real Login, recuperação de senha, validação e navegação responsiva aparecem cedo num sistema usado por clientes. Um projeto novo também precisa manter a integração entre o backend e a interface enquanto essas telas evoluem. Os [starter kits do Laravel](https://laravel.com/docs/13.x/starter-kits) entregam uma estrutura inicial com escolhas conhecidas pela comunidade. Você ainda define como os membros entram e o que cada papel pode fazer. Ao adicionar um convite para a empresa, por exemplo, a autenticação do starter kit já oferece arquivos de rota e de interface que podem ser abertos no repositório. O agente modifica essa base, e você confere a nova permissão e a tela do convite nos arquivos ligados ao recurso. Essa base também evita que cada novo projeto invente uma forma diferente de resolver tarefas comuns. Eu prefiro aproveitar um componente mantido pelo framework ou pela comunidade quando ele atende ao sistema. A implementação autoral fica reservada para a parte que realmente diferencia o produto. A estrutura continua exigindo leitura. O agente pode colocar uma autorização na policy correta e escrever uma condição incompatível com o requisito. O arquivo conhecido facilita a conferência, e o teste precisa reproduzir tanto o acesso aceito quanto a tentativa recusada. ## Telescope, filas e testes acompanham o sistema funcionando O código pode parecer correto durante a leitura e falhar quando recebe uma requisição real. O [Laravel Telescope](https://laravel.com/docs/13.x/telescope) mostra requisições, exceções, consultas ao banco e jobs dentro da aplicação. Quando uma tela demora ou uma tarefa falha, você consegue abrir o painel e identificar a requisição, a consulta ou o job associado ao problema. As filas retiram trabalhos demorados da resposta principal. Um email, uma importação ou um processamento pesado pode ser executado por um job, com tentativas e falhas registradas. O Laravel oferece essa estrutura e permite que o agente implemente a tarefa dentro de um mecanismo já conhecido. Os testes fecham a revisão pelo comportamento. No artigo sobre [como testar código gerado por IA com Laravel](https://promovaweb.com/blog/laravel-vibe-coding-revisao), mostro com mais detalhe como policies, migrations e testes ajudam a conferir uma alteração. Aqui, eles cumprem outra função no argumento: fazem parte da arquitetura que você aprende no Laravel e reconhece em outros frameworks. ## O que você aprende continua útil fora do Laravel Node, Python, Ruby e outras stacks organizam as mesmas responsabilidades com nomes e implementações próprios. Uma chamada HTTP ainda precisa chegar a uma rota, a entrada precisa ser validada e uma permissão precisa recusar o acesso indevido. O trabalho demorado também precisa sair da resposta principal, e um teste deve reproduzir o comportamento esperado. Depois de acompanhar essas partes no Laravel, você consegue procurá-las no framework usado pelo próximo projeto. Essa é a relação com a autoescola. O Fox vermelho foi o carro concreto usado para aprender a dirigir. O Laravel é o framework concreto que escolhi para explicar arquitetura no Vibe Coding. Trocar de stack exige conhecer novos comandos e novas convenções, enquanto rotas, autorizações, filas, migrations e testes continuam respondendo a necessidades reconhecíveis. A [formação IA Makers da Promovaweb](https://promovaweb.com/formacoes/iamakers) trabalha esse desenvolvimento acompanhado, da especificação à publicação do sistema. Você também pode conhecer a nossa abordagem de [Vibe Coding](https://promovaweb.com/vibe-coding) e ler como um agente usa [memória, skills e ferramentas](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao) para continuar uma tarefa. O Laravel entra nessa rotina como a estrutura que dá nome ao trabalho, deixa os arquivos localizáveis e permite conferir o que a IA alterou. ### Como testar o código gerado por IA usando o Laravel? - URL: https://promovaweb.com/blog/laravel-vibe-coding-revisao - Publicado em: 2026-08-12T12:00:00Z - Descrição: Veja como Laravel deixa permissões, migrations e testes visíveis para revisar código gerado por IA sem confiar apenas na tela pronta. Leia o artigo. Numa aula de [Laravel](https://promovaweb.com/ferramentas/laravel) sobre arquitetura de sistemas, eu contei que mexi numa verificação de segurança e bloqueei o acesso de colegas à aplicação. Eu queria ajustar uma condição, mas perdi de vista as telas afetadas. O teste encontrou o problema enquanto a mudança ainda estava no repositório. Sem esse retorno, a primeira notícia viria do suporte, depois de uma tentativa de login recusada. Levo esse episódio para o Vibe Coding. A IA pode criar a tela e escrever os arquivos em pouco tempo, mas uma aplicação continua precisando de permissões, registros preservados, testes e uma forma de investigar falhas. Eu [escolho o Laravel para trabalhar com Vibe Coding](https://promovaweb.com/blog/escolher-laravel-vibe-coding) porque ele deixa essas partes em lugares conhecidos. O framework não confere a qualidade da alteração por mim. Ele só desloca a revisão da memória do chat para os arquivos que definem o comportamento da aplicação. ## Direto ao ponto O Laravel permite revisar código gerado por IA quando você consegue localizar a mudança pelo efeito que ela produz. Uma permissão pode ficar em uma policy, uma alteração no banco em uma migration e o comportamento esperado em um teste de feature. Esses lugares não substituem a leitura, mas mostram onde procurar. Quando você envia à IA uma instrução para criar uma função, a pergunta não termina em “a tela está abrindo?”. Ela continua no acesso que deve ser aceito ou negado, no registro que será criado e no teste que precisa falhar quando outra alteração quebrar aquele comportamento. O framework deixa esse diálogo registrado no repositório. ## Laravel deixa a permissão fora do formulário Pense numa área onde um membro de um grupo edita um artigo. A IA pode montar o formulário, carregar os registros e devolver uma mensagem de sucesso. Ainda falta uma pergunta que o formulário não responde: esse membro pode editar qualquer artigo ou somente os artigos do grupo ao qual pertence? No Laravel, uma policy concentra essa autorização. Você abre a classe, compara a condição com o requisito e testa dois casos: uma edição aceita e outra recusada. A [Form Request](https://laravel.com/docs/13.x/validation) pode validar a entrada e também avaliar a autorização da requisição. Eu prefiro revisar por esse caminho porque uma condição espalhada pelo controller, pelo componente e pela consulta ao banco fica difícil de perceber na próxima interação com o agente. A policy não impede que alguém escreva uma condição ruim. Ela cria um arquivo que você pode abrir, discutir e cobrir com um teste ligado ao acesso real. ## A requisição percorre mais que a página aberta Middleware examina a requisição no caminho até a rota ou o controller. O Laravel já inclui middleware para autenticação e proteção contra falsificação de requisição. A [documentação oficial](https://laravel.com/docs/13.x/middleware) mostra que ele pode recusar uma entrada sem autenticação ou deixá-la seguir. Essa separação aparece quando você revisa uma área administrativa. A rota pode exigir autenticação. A policy pode decidir se você, já autenticado, executa uma ação sobre determinado registro. A request pode validar o conteúdo enviado. São três perguntas diferentes. Se a IA altera apenas a tela, você ainda precisa verificar se as três partes continuam coerentes com o que a aplicação promete. Você não precisa decorar toda a arquitetura do Laravel. Precisa saber apontar a parte afetada e abri-la depois que a IA termina. ## A migration registra o que mudou no banco Uma coluna nova no formulário também cria uma responsabilidade no banco. A migration torna essa alteração visível no histórico do projeto. Quando a IA acrescenta um campo, eu quero ver qual tipo foi escolhido, se registros antigos podem ficar sem valor e se uma reversão preserva a aplicação em um estado consistente. A tela preenchida não responde a essas perguntas. Esse cuidado importa mais quando o sistema já tem clientes e registros salvos. Um campo obrigatório pode quebrar uma edição antiga. A revisão começa pelo efeito esperado, passa pela migration e termina no teste que cria ou atualiza o registro naquele estado. No Laravel, a estrutura do projeto permite encontrar migrations e modelos, mas o conteúdo ainda precisa ser lido. Framework não converte um requisito mal definido em comportamento confiável. Ele reduz a distância entre a frase que explica a mudança e o arquivo que você precisa conferir. ## Um teste vale mais que a confirmação do agente O agente pode resumir bem o que fez. O resumo não mostra se uma permissão foi mantida, se a validação recusou um campo inválido ou se a migration mudou uma criação existente. O teste permite executar essas situações de novo. O Laravel separa testes unitários de testes de feature. Os unitários avaliam uma parte isolada do código. Os testes de feature podem atravessar uma porção maior da aplicação, incluindo uma requisição HTTP. Para mudanças que envolvem rota, autenticação e autorização, eu começo pelo comportamento que você encontra no navegador. [A documentação de testes](https://laravel.com/docs/13.x/testing) explica essa diferença e mostra o suporte do framework a Pest e PHPUnit. O teste não prova que todo o sistema está certo. Ele preserva uma condição que você escolheu manter. Quando outra alteração remove por engano uma permissão ou quebra a criação de um registro, o teste vira a parte do repositório que contesta a resposta do agente. É melhor do que uma instrução vaga, porque o comportamento esperado está escrito e pode falhar. No artigo sobre [como o Hermes Agent usa memória, skills e ferramentas](https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao), eu trato a saída do agente como algo que precisa ser aberto e conferido. O Laravel oferece uma estrutura útil para repetir essa conferência em aplicações web. ## O aceite continua com você Eu uso o Laravel como trilho de revisão porque ele dá nomes para a instrução da a IA. Você descreve a ação, a permissão e o comportamento que o teste deve confirmar. Depois abre a comparação dos arquivos, lê a autorização alterada, executa o teste e confere a migration. A [IA Makers da Promovaweb](https://promovaweb.com/formacoes/iamakers) trabalha essa relação entre implementação assistida e revisão técnica. A IA escreve parte do código. o entendimento da arquitetura e o aceite permanecem com você. ### Quais mudanças o n8n 3.0 traz a instalações e workflows? - URL: https://promovaweb.com/blog/n8n-3-breaking-changes-self-hosted-workflows - Publicado em: 2026-08-01T12:00:00Z - Descrição: Veja o que o n8n 3.0 muda em instalações, workflows e segurança, quais recursos serão removidos e o que ainda depende de documentação. Leia agora. *Atualizado em 3 de agosto de 2026, depois da consulta à documentação oficial das breaking changes.* O n8n 3.0 remove três Nodes usados há anos, exige Docker para instalação self-hosted e desliga o helper `$getPairedItem`. A versão está prevista para outubro de 2026, e as mudanças alcançam a forma como você instala o n8n, constrói automações e administra segurança. Esses anúncios apontam para uma direção comum. O n8n está reduzindo caminhos antigos para concentrar o suporte em formas mais definidas de instalar a ferramenta, escrever código e relacionar itens dentro de um workflow. Se os seus ambientes ainda carregam componentes legados, você precisará localizá-los na revisão da próxima atualização. A diferença entre identificar e migrar define o cuidado necessário agora. Algumas dependências já podem ser encontradas, porém a página oficial ainda promete detalhes e guias. Este artigo preserva esse limite para não transformar um anúncio incompleto em procedimento de atualização. ## Direto ao ponto O n8n 3.0 concentra a implantação self-hosted em Docker, substitui Nodes genéricos por componentes com funções mais específicas e amplia padrões ligados a credenciais e chaves. Essas três mudanças reduzem compatibilidade antiga para manter caminhos técnicos mais definidos. Comece pela lista de dependências conhecidas. Você já pode localizar instalações por `npm` ou `npx n8n`, workflows com `Function`, `Function Item` ou `Item Lists`, expressões com `$getPairedItem` e chamadas por `Execute Workflow`. Como a página ainda receberá detalhes e guias, separe as substituições indicadas dos procedimentos que continuam pendentes. ## Docker define o caminho self-hosted mantido pelo n8n A exigência de Docker é o sinal mais claro dessa concentração. Na versão 3.0, a execução por `npm` e pelo comando `npx n8n` deixará de receber suporte. Se o seu ambiente ainda é iniciado diretamente pelo Node.js, você precisará mudar a forma de implantação para atualizar. Essa escolha coloca imagem, persistência e atualização sobre a mesma base suportada, reduzindo as variações que a documentação e a manutenção do n8n precisam considerar. Para você, a consequência aparece no registro de cada cliente: cada ambiente precisa mostrar como o processo é iniciado e onde ficam os arquivos e o banco usados pela instalação. A documentação cita o Docker Compose como a opção provavelmente mais simples para uso local e informa que o procedimento detalhado ainda será publicado. Neste momento, identifique as instalações por `npm` ou `npx n8n` e aguarde o guia oficial para executar a troca. Quando a versão estiver disponível, a migração precisará de backup conferido e teste em ambiente separado. Esse [trabalho de infraestrutura](https://promovaweb.com/blog/infraestrutura-vibe-coders) merece estudo próprio porque o container não substitui persistência, backup nem recuperação. A [Trilha DevOps](https://promovaweb.com/devops) aprofunda a relação entre servidor, Docker e manutenção que você assume ao hospedar aplicações para clientes. ## Function e Item Lists dão lugar a Nodes específicos Nos workflows, a redução de caminhos antigos aparece na retirada de três Nodes. A [documentação técnica do n8n](https://docs.n8n.io/) explica como a ferramenta coordena um evento até o resultado da automação. Na [página oficial da versão 3.0](https://docs.n8n.io/changelog/v30-breaking-changes/), `Function`, `Function Item` e `Item Lists` aparecem entre os Nodes que serão removidos. O destino de `Function` e `Function Item` será o `Code node`, mas o modo de execução preserva uma diferença importante. `Run Once for All Items` recebe o conjunto de itens em uma execução. `Run Once for Each Item` executa o código separadamente para cada item. Tratar essa troca como simples mudança de nome pode alterar a entrada disponível ao código e mudar a saída do workflow. No `Item Lists`, o destino depende da configuração atual. `Split Out` separa valores que estavam dentro de um item. `Aggregate` e `Summarize` combinam ou resumem valores, enquanto `Sort`, `Limit` e `Remove Duplicates` alteram a composição da lista. Os nomes específicos permitem reconhecer a função daquela etapa diretamente no editor. Na revisão, compare a entrada atual, a configuração do `Item Lists` e a saída esperada. Um workflow que termina sem erro ainda pode produzir uma lista diferente se a agregação, a ordenação ou o limite forem reconstruídos com outra configuração. A conferência precisa chegar aos itens resultantes, em vez de parar no sinal verde da execução. ## Item linking exige conferir a relação entre entrada e saída O helper depreciado `$getPairedItem` também será removido. A orientação oficial aponta para o item linking padrão por meio de `pairedItem` ou de uma expressão como `$("").item`, conforme a forma usada para recuperar o item relacionado. Esse ponto merece atenção porque a ligação entre itens pode falhar sem produzir um erro óbvio. O workflow executa, o Node devolve conteúdo e a expressão encontra um valor, mas esse valor pode pertencer a outro item da entrada. Na [operação de um agente de WhatsApp](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel), essa diferença pode associar um campo ao contato errado mesmo quando todas as etapas aparecem concluídas. A verificação útil compara pares conhecidos. Você escolhe entradas com valores distintos, acompanha a saída e confirma se cada resultado preserva a relação esperada. Esse teste ainda dependerá da versão e do workflow real, porém a lista de usos de `$getPairedItem` já pode mostrar quais automações merecem essa conferência. ## Execute Workflow ainda tem uma lacuna importante A documentação informa que o comportamento antigo do `Execute Workflow` será removido, mas não explica qual comportamento está sendo tratado nem como a conversão funcionará. Essa lacuna precisa ficar separada das substituições já conhecidas para que uma linha do anúncio não vire orientação inventada. Hoje, você já pode localizar workflows que chamam outros workflows e registrar o payload recebido, o comportamento de espera e a saída que alimenta a etapa seguinte. Esse material oferece uma base de comparação quando os detalhes forem publicados, sem alterar produção agora. A mudança só deve ser definida depois da documentação completa e de um teste da versão 3.0 em ambiente separado. Até lá, trate qualquer instrução sobre opção, modo de espera ou formato de entrada como hipótese, não como procedimento. ## Segurança aparece no anúncio antes dos detalhes A versão 3.0 também anuncia tratamento mais restrito para nomes considerados arriscados em recursos. Credenciais terão um comportamento revisto, e a rotação de chaves virá habilitada por padrão. A página ainda não explica quais configurações serão alteradas nem o que você precisará revisar durante a atualização. Esse grupo aponta para outra redução de comportamentos permissivos acumulados ao longo do tempo. O anúncio mostra a direção, mas ainda não oferece a especificação necessária para orientar uma mudança em produção. Por isso, evite transformar frases gerais sobre segurança em comandos, variáveis ou promessas de proteção automática. Essa lacuna merece registro em cada ambiente que você mantém. Você precisará comparar a chave de criptografia, as credenciais salvas e os nomes usados nos recursos com o guia futuro. No [Plano Martech](https://promovaweb.com/planos/martech), essa responsabilidade técnica aparece ligada à automação entregue ao cliente, porque o workflow continua dependendo da forma como o ambiente guarda acesso e recebe manutenção. ## Recursos descontinuados reduzem outras superfícies mantidas O Chat Hub será retirado, e a importação de workflows por URL deixará de existir dentro do editor. Para importar um workflow, a documentação preserva a cópia e colagem, o arquivo local, a interface de linha de comando e a Public API como alternativas. Cada forma de importação exige suporte, precisa acompanhar mudanças do editor e ainda carrega falhas próprias. Quando o n8n remove uma entrada antiga e mantém caminhos que já fazem parte do produto, a manutenção fica concentrada nas opções que continuarão documentadas. A página também informa que Nodes sem funcionamento serão removidos, mas não apresenta seus nomes. Completar essa lista com memória de versões anteriores ou relatos de terceiros criaria uma certeza que a fonte ainda não oferece. Essa lista só pode avançar nesse ponto quando a relação oficial estiver disponível. ## O que você já pode identificar nos ambientes atuais Comece pela forma de implantação. Cada ambiente precisa mostrar se o n8n está em Docker ou se ainda depende de uma instalação iniciada por Node.js. Essa informação separa os clientes que já usam a base exigida daqueles que precisarão de uma mudança estrutural. Nos workflows, procure `Function` e `Function Item` porque os dois serão substituídos pelo `Code node`, com modos de execução diferentes. Em outra busca, localize `Item Lists` e `$getPairedItem`, cujas substituições dependem do uso atual. Nas chamadas por `Execute Workflow`, registre a entrada, a espera e a saída. Esse material não executa a migração, mas mostra onde um teste da versão 3.0 deverá comparar comportamento e resultado. Por fim, separe as partes que a página ainda descreve de forma geral. Credenciais e chaves ficam no grupo de segurança. Nomes considerados arriscados, Nodes sem funcionamento e o comportamento antigo de `Execute Workflow` permanecem como pendências sem procedimento publicado. Se esses itens forem escondidos dentro de uma tarefa chamada apenas “atualizar n8n”, você perde a diferença entre trabalho conhecido e investigação futura. ## A migração ainda depende da próxima versão da documentação O anúncio atual oferece substituições claras para alguns Nodes e alternativas para a importação por URL. Em outros pontos, ele informa somente que o comportamento mudará. Essa diferença define duas colunas na lista de acompanhamento: dependência conhecida e procedimento ainda não publicado. A própria página informa que receberá detalhes, guias de migração e links conforme a versão 3.0 se aproximar. Como o lançamento está previsto para outubro de 2026, uma nova conferência da fonte será necessária na atualização deste artigo e na preparação de qualquer janela de manutenção com cliente. Quando a versão estiver disponível, o próximo trabalho será testar em ambiente separado, preservar backup e comparar as saídas dos workflows selecionados. Até lá, a contribuição mais útil deste anúncio está em mostrar a direção do n8n e revelar onde cada instalação ainda depende de caminhos antigos. Eu vou acompanhar essas mudanças porque elas afetam tanto a ferramenta quanto a responsabilidade de mantê-la para clientes. Você que administra n8n para clientes tem o mesmo motivo para acompanhar: entre no [Discord da Promovaweb](https://promovaweb.com/discord) para discutir os detalhes conforme forem publicados. ### Como o Hermes Agent usa memória, skills e ferramentas? - URL: https://promovaweb.com/blog/hermes-agent-memoria-skills-execucao - Publicado em: 2026-07-21T12:00:00Z - Descrição: Entenda como o Hermes Agent combina ferramentas, memória, skills e canais para executar tarefas reais com limites de revisão e segurança. Confira agora. O primeiro texto que o Hermes preparou para este artigo passou no validador de termos e continuou ruim. Quando abri o `README.md` e comparei a abertura com o LinkedIn, encontrei headings demais, recursos enfileirados e a mesma cena nos dois canais. O terminal confirmava o vocabulário permitido, mas a comparação dos arquivos revelou a falha editorial que o comando não avaliava. A correção exigiu reler as orientações do projeto, comparar os dois textos e reescrever os arquivos completos. Essa falha mostra uma parte importante do uso de agentes de IA: o Hermes consegue executar comandos e deixar o trabalho no repositório, mas a qualidade editorial ainda depende de uma leitura capaz de perceber aquilo que o teste mecânico não mede. ## Direto ao ponto O Hermes Agent é um agente de IA de código aberto criado pela Nous Research. Nesta produção, eu o acessei pelo Telegram, o modelo interpretou a mensagem e as ferramentas abriram o repositório no computador configurado. Cada chamada devolveu um resultado real, e qualquer falha permaneceria no terminal para que eu pudesse repetir o comando e conferir o estado do arquivo. Esse retorno pode ser um arquivo lido, a saída de um comando ou o conteúdo extraído de uma página. O agente continua o trabalho com o que a ferramenta devolveu. Se o comando falha, a falha precisa permanecer visível. Se o arquivo foi alterado, você precisa conseguir abrir a mudança e executar novamente a validação. ## Do Telegram ao arquivo que você consegue abrir Esta base começou com uma mensagem curta enviada pelo Telegram, e o Hermes abriu o repositório até encontrar o `AGENTS.md`. Esse índice indicava o diretório `content/` e as instruções editoriais que precisavam ser lidas. Se o agente ignorasse o arquivo, a base poderia surgir na pasta errada. A comparação do Git confirmou o caminho correto e mostrou quais trechos ainda estavam pendentes. O arquivo alterado oferece uma prova melhor que a explicação do chat. Na primeira base, por exemplo, o validador encontrou 72 erros e indicou o caminho e a linha de cada ocorrência. Usei essa saída para revisar os arquivos, executei o mesmo comando e conferi que nenhum erro conhecido permanecia. A segunda falha exigiu outra leitura. Embora os comandos estivessem verdes, o blog parecia um resumo da documentação e o LinkedIn repetia a mesma cena em tamanho menor. O usuário recusou as duas peças, e a revisão voltou à estrutura completa porque uma busca por palavras proibidas não avalia voz nem função de canal. ## As ferramentas mostram até onde o Hermes pode ir O [repositório oficial do Hermes Agent](https://github.com/NousResearch/hermes-agent) descreve o ciclo usado para chamar ferramentas e devolver o resultado ao modelo. No terminal, isso permite executar um teste e ler a saída. Nas ferramentas de arquivo, permite localizar o documento certo, fazer a alteração e mostrar o que mudou. A permissão precisa acompanhar a tarefa. Uma pesquisa pública pode usar busca e extração de páginas sem receber acesso ao servidor de produção. Uma manutenção em VPS precisa de terminal, mas também precisa indicar o diretório permitido, o comando de verificação e o estado esperado ao final. Sem essa delimitação, fica difícil confirmar se o agente alterou arquivos fora da pasta autorizada. Na página de [ferramentas da Promovaweb](https://promovaweb.com/ferramentas), cada sistema aparece pela função que cumpre. A mesma leitura serve para configurar o Hermes. A ferramenta entra porque aproxima uma evidência necessária, como o arquivo alterado ou o retorno de um endpoint, e não para aumentar uma lista de capacidades. ## Skills e memória guardam coisas diferentes Uma skill registra um procedimento que pode ser usado novamente. Ela explica quais arquivos precisam ser lidos, como o trabalho deve avançar, que falha já ocorreu e qual comando confirma o resultado. O Hermes carrega essa instrução quando a tarefa exige aquele procedimento, sem enviar toda a biblioteca ao modelo em cada mensagem. A memória persistente guarda informações que continuam úteis entre sessões, como a preferência pelo Português do Brasil. O método editorial desta produção pertence às skills, enquanto o README registra o estado atual do artigo e deixa claro o que ainda precisa ser revisto. Essa separação evita que uma informação temporária vire instrução permanente. Também facilita a troca do modelo, porque parte do aprendizado continua nos arquivos, nas skills e nos testes. É a mesma disciplina aplicada em [Vibe Coding](https://promovaweb.com/vibe-coding): você descreve o comportamento esperado, acompanha a alteração e confere o resultado no sistema. Uma skill pode envelhecer. Se o projeto muda o nome de uma pasta ou acrescenta uma nova verificação, o arquivo precisa ser atualizado. Caso contrário, o agente repetirá um procedimento antigo com muita confiança. A revisão da skill faz parte da manutenção, assim como a revisão de código e documentação. ## Gateway e cron levam o Hermes para outras rotinas O [gateway de mensagens](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/) permite falar com o mesmo agente por plataformas como Telegram, Discord e Slack. Nesta produção, a mensagem chegou pelo celular e os arquivos surgiram no computador configurado, onde o Git mostrou cada alteração. O canal mudou o ponto de acesso, mas as permissões continuaram definidas no backend. O cron executa tarefas em horários definidos. Uma rotina pode consultar uma fonte e entregar um relatório em um canal, desde que o erro também gere uma saída visível. Se a consulta falhar e nada for entregue, o silêncio não pode ser tratado como sucesso. ## O validador verde ainda precisa de leitura A [documentação de segurança](https://hermes-agent.nousresearch.com/docs/user-guide/security) apresenta aprovações para comandos sensíveis e mecanismos de isolamento conforme o backend usado. Essas proteções controlam parte da execução. Elas não avaliam se um artigo soa como relatório, se dois canais repetem a mesma estrutura ou se uma frase tecnicamente correta está distante da voz do autor. Foi exatamente o que ocorreu aqui. O primeiro validador encontrou termos proibidos e indicou as linhas, enquanto a execução seguinte terminou sem novas ocorrências. A leitura integral ainda encontrou enumerações disfarçadas, explicações abstratas e uma conclusão montada para fechar o outline, porque o script não foi criado para reconhecer a voz do autor. Eu uso o teste mecânico para localizar erros conhecidos e a leitura integral para avaliar o raciocínio. Se o texto parece uma sequência de requisitos, eu volto ao fato vivido, explico o mecanismo e mostro onde conferir. Se o LinkedIn apenas resume o blog, mudo o momento de entrada e a função do argumento. A saída verde chega durante o trabalho, não no final da responsabilidade. O mesmo cuidado vale para automações de atendimento. No artigo sobre [agente WhatsApp com custo previsível](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel), o histórico permite retomar o que o cliente escreveu, e a passagem humana define quando o sistema precisa encaminhar a mensagem. Sem histórico e limite explícito, a automação pode responder bem em um teste e falhar justamente no atendimento que exige continuidade. ## Como testar o Hermes em um projeto Comece com uma alteração pequena em um arquivo conhecido. A mensagem precisa indicar a pasta permitida, a fonte oficial e o comando que tem que terminar sem erro. Depois, abra a comparação dos arquivos alterados, execute novamente o teste e não use o resumo do agente como comprovante da mudança. O terminal pode ficar ao lado dos logs durante essa conferência. O artigo sobre [tmux e produtividade no terminal](https://promovaweb.com/blog/tmux-produtividade-terminal) mostra como manter sessões e saídas acessíveis enquanto o trabalho continua. O histórico do terminal explica o que foi executado, e o Git mostra o que permaneceu no repositório. Quando a tarefa cresce, acrescente novas ferramentas somente depois de entender a evidência necessária. O [Plano IA Makers](https://promovaweb.com/formacoes/iamakers) trabalha essa relação entre especificação, desenvolvimento com IA e revisão técnica. O agente participa da execução, enquanto o aceite continua ligado ao arquivo, ao teste e à leitura do profissional responsável pela publicação. Nesta produção da Promovaweb, o Hermes mostrou utilidade durante a revisão da versão recusada. Eu pude abrir o trabalho, localizar a falha, devolver a peça e executar outra leitura sobre os mesmos arquivos. Essa capacidade de corrigir um artefato verificável é a minha primeira conferência ao avaliar um agente para trabalhar em um repositório. ### Como corrigir a CVE do OpenSSH no Debian sem reiniciar? - URL: https://promovaweb.com/blog/corrigir-cve-openssh-debian-sem-reiniciar - Publicado em: 2026-07-17T12:00:00Z - Descrição: Corrija o OpenSSH no Debian 12 ou 13 sem reiniciar o servidor. Veja como validar a revisão, reiniciar apenas o SSH e testar o novo acesso. Leia o guia. O email do CERT.br chegou depois que uma varredura do OpenSSH encontrou a porta 22 aberta em um servidor de laboratório da Promovaweb. A máquina usava Debian 12, estava ligada havia 721 dias e anunciava `OpenSSH_9.2p1 Debian-2+deb12u2`. Eu gravei a manutenção no vídeo [Como corrigir Vulnerabilidade SSH](https://www.youtube.com/watch?v=z6JwRlwZpIU), incluindo uma primeira tentativa que falhou e a conferência do Docker no final. Os servidores de produção ficavam atrás do firewall e não apareceram no aviso, por isso o laboratório também mostrou a diferença prática criada pelo controle de acesso. ## Direto ao ponto O Debian 12 recebeu a correção da CVE-2024-6387 em `1:9.2p1-2+deb12u3`, e o servidor citado ainda usava `deb12u2`. A manutenção atualiza os índices do APT, instala a revisão candidata do OpenSSH e reinicia somente o `ssh.service`, sem reboot do computador. No Debian 13, você deve seguir a candidata oferecida pelos repositórios atuais do Trixie, pois a numeração pertence a outra linha do OpenSSH. Mantenha a sessão atual aberta, valide a configuração com `sshd -t`, confira `KillMode=process` e encerre o terminal antigo apenas depois que uma segunda conexão autenticar. ## O `deb12u2` do alerta ainda ficava abaixo da correção A [DSA-5724-1 do Debian](https://www.debian.org/security/2024/dsa-5724) descreve uma condição de corrida no tratador de sinais do `sshd`. Sob as condições registradas no aviso, uma conexão sem autenticação concluída dentro do `LoginGraceTime` pode alcançar código inseguro no processo privilegiado. O mesmo documento fixa `1:9.2p1-2+deb12u3` como a primeira revisão corrigida para o Debian 12 Bookworm. O `deb12u2` informado pelo CERT.br já trazia o ajuste da CVE-2023-48795, mas ainda não continha o patch do Debian para a regreSSHion. Na consulta de 17 de julho de 2026, o [rastreador da CVE-2024-6387](https://security-tracker.debian.org/tracker/CVE-2024-6387) mostra `1:9.2p1-2+deb12u10` no Debian 12 e `1:10.0p1-7+deb13u4` no Debian 13. Essas revisões podem avançar, então eu instalo a candidata atual do repositório oficial em vez de procurar manualmente o mínimo publicado em 2024. ## O banner `OpenSSH_9.2p1` não confirma o patch O OpenSSH corrigiu a falha na linha upstream 9.8, conforme a [nota oficial da versão](https://www.openssh.com/txt/release-9.8). O Debian preserva a versão-base e incorpora patches por backport, portanto um Bookworm corrigido ainda pode anunciar `OpenSSH_9.2p1`. Verifique o trecho completo da revisão, como `Debian-2+deb12u10`, porque ele identifica o trabalho mantido pela distribuição. O `dpkg-query` mostra a versão instalada no host, e o `apt-cache policy` informa qual revisão o APT oferece naquele momento. Um scanner remoto pode reconhecer apenas parte do banner e manter o host como possivelmente vulnerável depois da manutenção. A resposta técnica precisa registrar a revisão Debian completa, o horário do upgrade e uma nova conexão aceita pelo processo iniciado depois da instalação. ## O laboratório exposto explica por que o CERT.br encontrou a máquina O servidor do vídeo ficava aberto para testes e homologações, com a porta 22 visível na internet. O CERT.br conseguiu iniciar uma conexão, ler o banner e comparar a versão, enquanto os hosts de produção atrás do firewall não responderam à mesma varredura. O firewall reduz a superfície pública, mas não substitui a atualização do software em uma máquina autorizada a receber conexões. Uma VPN ou uma lista restrita de IPs também pode retirar a porta administrativa da internet aberta, desde que o acesso de recuperação continue documentado e testado. ## Confira a distribuição e a revisão do OpenSSH Comece identificando a distribuição e comparando a revisão instalada com a candidata dos repositórios. Estes comandos não alteram o servidor e mostram se a máquina usa Debian 12 ou 13, qual revisão está no disco e qual versão o APT pretende instalar. ```bash cat /etc/os-release dpkg-query -W -f='${Version}\n' openssh-server apt-cache policy openssh-server ``` No laboratório do vídeo, a revisão instalada terminava em `deb12u2`, abaixo do mínimo corrigido `deb12u3`. No Debian 13, a candidata deve pertencer à linha corrigida do Trixie e, na data desta publicação, a página do [`openssh-server` no Debian 13](https://packages.debian.org/trixie/openssh-server) mostra `1:10.0p1-7+deb13u4`. Uma candidata ainda vulnerável indica que as fontes do APT precisam de revisão, e a instalação deve parar nesse ponto. Um arquivo `.deb` obtido fora da cadeia assinada cria outra exposição, enquanto `bookworm-security` ou `trixie-security` mantém a atualização ligada aos repositórios do Debian. No teste seguinte, o próprio `sshd` lê a configuração sem reiniciar o serviço. A ausência de saída indica que a sintaxe foi aceita, enquanto uma mensagem de erro precisa ser corrigida com a sessão atual ainda aberta. ```bash sudo sshd -t ``` ## A primeira tentativa do vídeo falhou por causa dos índices do APT Na gravação, eu executei `apt-get install --only-upgrade openssh-server`, mas o APT não encontrou alguns arquivos necessários. O próprio erro apontou para índices antigos, então executei `apt-get update` e repeti a instalação com sucesso. Essa cena é útil porque mostra o motivo de atualizar os índices na mesma janela da manutenção. Um `apt-get update` executado horas atrás ainda pode deixar a instalação sem a referência atual do repositório, e a saída do APT deve orientar a próxima ação. No guia, eu nomeio os três componentes do OpenSSH para deixar o escopo explícito. O APT também pode atualizar o OpenSSL e bibliotecas relacionadas quando essas dependências forem necessárias para os componentes selecionados. ```bash sudo apt update sudo apt install --only-upgrade \ openssh-server \ openssh-client \ openssh-sftp-server ``` O `--only-upgrade` limita a solicitação aos componentes já instalados, mas não impede o APT de atualizar dependências exigidas por eles. No vídeo, a tela também informou que outras 113 atualizações permaneceriam pendentes, pois aquela manutenção cuidava especificamente do SSH. ## Reinicie somente o SSH e preserve uma saída de recuperação A unidade padrão do SSH no Debian usa `KillMode=process`, opção que encerra o processo principal sem matar os processos filhos das sessões autenticadas. O [manual do Debian sobre serviços Unix](https://www.debian.org/doc/manuals/debian-handbook/unix-services.en.html) apresenta essa configuração, mas um override local pode alterar o comportamento efetivo. Confira o valor, repita o teste da configuração e mantenha aberto o console web do provedor quando ele estiver disponível. Depois execute o restart do serviço e leia o estado completo, sem reinicializar a VPS. ```bash sudo systemctl show ssh -p KillMode sudo sshd -t sudo systemctl restart ssh sudo systemctl --no-pager --full status ssh ``` A saída esperada do primeiro comando é `KillMode=process`, e o estado final deve mostrar `active (running)`. Outra configuração exige uma forma de recuperação já acessível, pois o restart pode encerrar a sessão usada para administrar a máquina. Use `systemctl restart ssh` nesta manutenção remota e não execute `systemctl stop ssh`. O `stop` interrompe o serviço sem iniciá-lo novamente, o que pode retirar o acesso administrativo e obrigar você a recorrer ao console do provedor. ## Teste outro login e confira o Docker A primeira sessão fica em um prompt conhecido enquanto outro terminal abre para o teste. A segunda conexão precisa usar o mesmo endereço e a mesma porta da rotina normal, pois um teste local não atravessa a rota, o firewall nem a autenticação vistos pela rede. Depois do login, eu confiro a revisão instalada, o horário de início do processo principal e os containers em execução. Esses registros conectam os arquivos atualizados ao serviço que aceitou a nova sessão e mostram se o Docker permaneceu ativo naquele host. ```bash dpkg-query -W -f='${Version}\n' openssh-server systemctl show ssh -p ExecMainStartTimestamp -p MainPID docker ps ``` No laboratório gravado, o `docker ps` continuou mostrando os containers depois do restart do SSH. Essa observação vale para a manutenção registrada, mas uma atualização diferente, um hook local ou outra mudança simultânea pode produzir outro resultado e precisa ser conferida no próprio servidor. O [tmux para produtividade no terminal](https://promovaweb.com/blog/tmux-produtividade-terminal) ajuda a preservar a sessão e o histórico durante uma investigação remota. Ele não substitui o segundo login nem o console do provedor, mas reduz a reconstrução do trabalho quando a conexão local oscila. ## A correção e a investigação cumprem funções diferentes O email do CERT.br afirma que o host está possivelmente vulnerável e explica que a entidade não testou a informação recebida dos parceiros. A revisão antiga exige atualização, mas não permite declarar que alguém executou código no servidor. A aplicação do patch fica separada da análise de comprometimento, porque a instalação não apaga um acesso anterior. Os registros do serviço, o histórico de autenticação, os logins recentes e as chaves autorizadas oferecem uma primeira leitura defensiva do período indicado no alerta. ```bash sudo journalctl -u ssh --since "2026-07-15 00:00:00" sudo less /var/log/auth.log last -ai sudo find /root /home \ -path '*/.ssh/authorized_keys' \ -type f -ls ``` Procure autenticações desconhecidas, nomes de usuário inesperados, chaves novas e horários incompatíveis com o uso do laboratório. Um log ou uma chave suspeita deve ser preservada para análise autorizada, pois apagar arquivos ou limpar logs remove o histórico necessário para entender o alcance. Uma confirmação de acesso indevido como root exige reinstalação a partir de uma base confiável e troca das credenciais alcançáveis pelo host. Esse trabalho pode exigir uma [consultoria de infraestrutura](https://promovaweb.com/comercial) quando a empresa não tem um profissional preparado para conduzir a resposta ao incidente. ## Os 721 dias de uptime deixaram uma lição de manutenção A máquina do vídeo era um laboratório, por isso permaneceu ligada e acumulou revisões pendentes por quase dois anos. Esse histórico explica o `deb12u2`, mas não serve como referência para um servidor de produção que atende clientes e precisa de uma janela recorrente de manutenção. Na [Trilha DevOps da Promovaweb](https://promovaweb.com/devops), eu conecto terminal, firewall, atualização e observabilidade porque cada mudança precisa deixar uma verificação. O [grupo técnico do Discord da Promovaweb](https://promovaweb.com/discord) também permite discutir a rotina sem publicar IP, domínio, credencial ou trecho sensível de log. O encerramento desta correção cabe em quatro registros: revisão atual instalada, configuração aceita, `ssh.service` iniciado depois do upgrade e nova conexão autenticada. Com esses quatro registros, você confirma o processo novo, verifica as aplicações daquele host e mantém a investigação de possível acesso indevido em uma trilha separada. ### Por que o tmux melhora a produtividade no terminal? - URL: https://promovaweb.com/blog/tmux-produtividade-terminal - Publicado em: 2026-07-13T12:00:00Z - Descrição: Veja como sessões nomeadas no tmux preservam seu trabalho, reduzem reconstruções após pausas e deixam o terminal mais produtivo. Continue a leitura. Eu volto ao terminal depois do almoço e encontro uma coleção de abas locais sem nome, dois acessos SSH fechados e um processo cujo estado ficou para trás. O [tmux na stack da Promovaweb](https://promovaweb.com/ferramentas/tmux) muda essa retomada porque mantém a sessão no servidor, com o diretório aberto e os programas em execução, mesmo quando o cliente usado para enxergar a sessão foi desconectado. A mudança aparece nos minutos que você deixa de gastar remontando a mesa antes de continuar o trabalho. Quando a sessão recebe o nome do projeto e cada janela representa uma frente reconhecível, você retoma o log que estava lendo e confere o processo que ficou rodando sem procurar pistas no histórico local nem reabrir as abas fechadas. ## Direto ao ponto O tmux melhora a produtividade no terminal ao preservar o estado intermediário do trabalho e reduzir a reconstrução depois de uma pausa ou queda de SSH. Sessões agrupam o projeto, janelas separam frentes de execução e painéis colocam o terminal ativo ao lado do log ou do teste necessário para revisar o resultado. Essa persistência depende do processo servidor do tmux continuar ativo. Uma reinicialização da máquina ou o encerramento de todas as sessões remove esse estado, portanto a ferramenta complementa documentação e monitoramento sem assumir a função deles. ## A sessão preserva a mesa de trabalho do terminal O tmux usa uma arquitetura formada por servidor e clientes, conforme explica o [guia oficial de introdução](https://github.com/tmux/tmux/wiki/Getting-Started). O servidor mantém sessões e programas, enquanto cada cliente apresenta esse ambiente em um terminal que pode sair e retornar depois. Trate uma sessão nomeada como a mesa de um projeto: o nome identifica a frente que você precisa retomar. Dentro dela, deixe o servidor de desenvolvimento em uma janela e abra outra para investigar logs, sem misturar programas de projetos diferentes na mesma tela. A continuidade preserva o estado intermediário que ainda não merecia virar documentação. Um diretório aberto, uma busca em andamento ou a saída recente de um teste permanecem disponíveis para a próxima leitura, o que reduz o esforço de descobrir onde a atividade havia parado. ## Janelas e painéis precisam cumprir uma função visível Uma janela representa uma área lógica dentro da sessão e pode conter um ou mais painéis. Eu uso janelas para separar frentes que raramente preciso observar juntas, como edição de código e administração de um servidor remoto. Os painéis funcionam melhor quando dois logs ou telas precisam ficar próximos na mesma etapa. Um terminal amplo pode receber o trabalho ativo, enquanto um painel menor exibe o log ou os testes usados para conferir o efeito daquela execução. A fragmentação perde utilidade quando cada canto da tela recebe um programa sem relação com a leitura atual. Uma grade cheia reduz a área disponível e obriga os olhos a procurar informação, por isso eu abro outra janela quando a atividade já não depende do mesmo log ou da mesma tela. ## Detach e attach reduzem o custo de uma queda de SSH O manual oficial registra que uma sessão pode ser desconectada e retomada depois, inclusive quando uma conexão SSH termina por falha de rede. O [manual do tmux](https://man.openbsd.org/tmux.1) também descreve que os programas continuam ativos após o detach enquanto o servidor e a sessão permanecerem disponíveis. Essa propriedade muda uma tarefa longa em um VPS porque o processo remoto deixa de depender da janela local usada para acompanhá-lo. Se a internet oscilar, eu restabeleço o acesso ao servidor e volto à sessão existente para conferir a saída que foi produzida durante a ausência. O tmux também reduz o custo de uma pausa planejada. Posso sair do cliente no fim de uma etapa e retomar a mesma sessão em outro computador, desde que ambos alcancem a máquina na qual o servidor do tmux está rodando. Durante uma manutenção remota, a sessão preserva o terminal e a saída que eu ainda preciso conferir, mas não prova que um novo acesso funciona. O guia sobre [como corrigir a CVE do OpenSSH no Debian sem reiniciar](https://promovaweb.com/blog/corrigir-cve-openssh-debian-sem-reiniciar) mostra o tmux ao lado de um segundo login, que continua necessário para confirmar a conexão depois do restart do SSH. ## A persistência termina junto do servidor do tmux O estado de uma sessão vive na memória do processo servidor e desaparece quando esse processo termina. A [documentação de perguntas frequentes](https://github.com/tmux/tmux/wiki/FAQ) deixa claro que um servidor encerrado ou interrompido leva suas sessões junto com ele. Esse limite separa continuidade operacional de recuperação duradoura. Um runbook registra como repetir uma tarefa, o monitoramento registra sinais ao longo do tempo e uma issue guarda o histórico necessário para a próxima análise técnica. O tmux preserva o intervalo entre duas ações, sem tratar a tela aberta como registro permanente. Uma investigação importante ainda precisa registrar log, print ou comando fora da sessão, especialmente quando outro profissional assumirá o servidor ou revisará a mudança. ## Agentes de IA ficam ao lado dos testes e dos logs No desenvolvimento assistido por IA, eu posso manter o agente em um painel e reservar outro para testes ou logs. A proximidade reduz trocas de janela durante a revisão, pois a sugestão aparece perto do teste ou do log que confirma ou contesta o resultado. O painel aberto não concede permissão para executar qualquer comando e também não valida o código produzido. Eu ainda leio os arquivos alterados, acompanho o teste e interrompo a execução quando a mudança alcança uma área que deveria permanecer fora da tarefa. Essa rotina combina com a [formação de DevOps](https://promovaweb.com/devops), onde o terminal aparece ligado a servidores e observabilidade. A disciplina de nomear sessões e conferir testes reduz o custo das retomadas sem esconder o trabalho técnico. ## Uma sessão pequena revela o ganho de continuidade Inicie com uma sessão nomeada para um projeto real e mantenha nela duas áreas fáceis de reconhecer. Uma janela recebe o trabalho ativo, enquanto outra guarda o log ou o processo necessário para acompanhar a execução. Depois de uma pausa, você percebe quanto tempo leva para encontrar a sessão e entender o que ainda está rodando. Se o nome não indicar o projeto ou se os painéis exigirem procura demais, a própria retomada mostra o ajuste necessário para a próxima sessão. Os [materiais da Promovaweb](https://promovaweb.com/materiais) ampliam essa prática com demonstrações técnicas, enquanto o [Instalador da Promovaweb](https://promovaweb.com/instalador) reúne aplicações usadas em servidores. As duas páginas permitem continuar pelo uso real do terminal sem transformar o tmux em uma coleção de atalhos desconectados da rotina. O sinal mais claro surge logo após o attach, quando a ferramenta deixa de chamar atenção e a atividade volta a ser legível. Eu encontro o projeto, vejo o que permaneceu em execução e retomo a leitura do ponto exato da pausa, sem remontar a mesa do terminal. ### Como deixar o custo do agente WhatsApp previsível? - URL: https://promovaweb.com/blog/agente-whatsapp-custo-previsivel - Publicado em: 2026-07-09T13:00:00Z - Descrição: Entenda como criar um agente WhatsApp econômico, com triagem precisa, histórico no CRM, n8n e passagem humana clara no atendimento de venda. Leia agora. Numa imobiliária que usa WhatsApp como canal principal, o agente pode responder todos os contatos e ainda deixar o vendedor com trabalho repetido. Eu verifico a qualidade abrindo o CRM para saber quantas mensagens foram necessárias até registrar o imóvel procurado e chamar o corretor. Eu desenharia esse agente como uma triagem comercial guiada pela resposta anterior do lead. Cada pergunta deve preencher um campo necessário no CRM ou aproximar o atendimento do corretor, pois uma mensagem sem função aumenta a fatura e alonga a coleta. ## Direto ao ponto Um agente WhatsApp econômico usa cada resposta para confirmar uma informação que altera a próxima etapa do atendimento. Na imobiliária, isso significa registrar no CRM o imóvel procurado e encaminhar o lead quando o corretor já consegue propor uma visita sem repetir a triagem. O desenho dinâmico muda a rota conforme o lead responde, mas mantém no n8n as etapas que precisam deixar histórico de execução. A IA interpreta a mensagem escrita pelo cliente e o CRM guarda o resumo comercial usado pelo vendedor para continuar o atendimento. ## O WhatsApp cobra mensagem e muda o desenho A página oficial de [preços da WhatsApp Business Platform](https://whatsappbusiness.com/products/platform-pricing/) informa que a cobrança considera a mensagem entregue e varia conforme o mercado de destino e a categoria. A partir de 1º de outubro de 2026, as respostas de serviço também serão cobradas, por isso confirmações repetidas deixam uma marca direta na fatura do atendimento. O post anterior sobre [custo por mensagem nos agentes de IA](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia) detalha essa simulação financeira. Aqui eu abro o desenho do atendimento para mostrar como uma pergunta altera a rota, qual resumo deve chegar ao CRM e qual sinal chama o vendedor. ## Dinâmico é mudar a rota pelo sinal do lead Um agente fixo pergunta sempre a mesma coisa, mesmo quando o lead já explicou parte do que procura. O contato interessado em alugar um apartamento numa região específica pode seguir direto para a confirmação da faixa de preço e da possibilidade de visita. O agente dinâmico trabalha com estados de atendimento, porque cada resposta altera a informação que ainda falta. Um contato em pesquisa recebe uma explicação curta, enquanto o lead que aceitou a faixa de preço pode gerar o resumo no CRM e seguir para o corretor. ## Econômico é usar cada mensagem com uma função Mensagens que apenas parecem educadas, mas não aproximam o atendimento de uma próxima ação, merecem atenção primeiro. O agente pode agradecer a informação recebida e fazer a pergunta seguinte na mesma resposta, desde que o texto continue fácil de ler no celular. Também evito transformar a coleta inicial em um interrogatório longo. Uma única resposta pode confirmar se o lead procura compra ou aluguel e solicitar a região desejada, porque essas informações definem quais imóveis o agente pode apresentar na etapa seguinte. ## Assertivo é responder com limite claro Um agente assertivo não tenta manter o atendimento aberto indefinidamente. Ele oferece uma explicação curta ao contato que ainda pesquisa e chama o vendedor assim que o lead aceita uma faixa de preço ou solicita uma visita. Esse limite preserva a experiência do lead e a rentabilidade do projeto. A automação que tenta negociar uma exceção sem chamar o vendedor envia respostas adicionais e pode atrasar o retorno humano até o interesse esfriar. ## O n8n deve executar a parte rastreável No Setupkit da Promovaweb, o n8n usa o PostgreSQL para guardar o estado da aplicação e o Redis para coordenar as execuções em modo fila. Esse desenho deixa um caminho de investigação quando o webhook recebe a mensagem, mas a atualização esperada não aparece no CRM. A IA interpreta a mensagem escrita pelo lead, e o n8n executa as ações previsíveis. O workflow verifica se o telefone está registrado e grava no CRM a região procurada, recusando o envio quando falta uma dessas informações para escolher a próxima etapa. ## O CRM precisa receber um resumo que ajude a vender Uma transcrição inteira do WhatsApp obriga o vendedor a refazer a leitura que o agente já deveria ter concluído. Ao abrir o contato no CRM, o corretor precisa encontrar o imóvel procurado e saber se o lead aceitou a faixa de preço apresentada ou solicitou uma visita. Um resumo específico permite ao corretor retomar o atendimento pelo ponto que motivou o encaminhamento. Se o lead aceitou visitar um apartamento no sábado, o vendedor confirma o horário em vez de perguntar outra vez qual região interessa. ## A passagem humana faz parte da economia Um agente barato no papel pode ficar caro ao segurar o lead além do necessário. Cada resposta adicional aumenta a cobrança da plataforma e o consumo do modelo de IA, além de adiar a entrada do vendedor quando já existe possibilidade de visita. Por isso, eu trataria a passagem humana como parte do cálculo econômico. O contato em pesquisa pode receber uma explicação e encerrar o atendimento, enquanto o lead que solicita uma visita deve chegar ao vendedor com o imóvel procurado já registrado no CRM. ## Como eu testaria a oferta recorrente Para transformar o agente em oferta recorrente, eu usaria atendimentos já feitos pela empresa como casos de teste. A comparação mostra qual pergunta poderia ser agrupada com a resposta anterior e qual mensagem deveria acionar o vendedor responsável. Depois eu dividiria o total de mensagens enviadas pela quantidade de atendimentos e conferiria quantos casos chegaram ao vendedor com um resumo aproveitável no CRM. Essa medida expõe uma triagem cara com mais clareza do que uma demonstração feita com um lead fictício que segue o roteiro sem desvios. ## A Martech acompanha o caminho da mensagem No [Plano Martech](https://promovaweb.com/planos/martech), eu acompanho o caminho da mensagem recebida no WhatsApp até o registro criado no CRM. O aluno consegue conferir o custo do atendimento e identificar qual etapa exige manutenção quando o resumo chega incompleto ao vendedor. O hub de [ferramentas da Promovaweb](https://promovaweb.com/ferramentas) apresenta a função das aplicações usadas nessa automação. No [Co-work da Comunidade Promovaweb](https://promovaweb.com/comunidade), a configuração pode ser revisada com a tela aberta para reproduzir a falha que impediu a atualização do CRM. ## A revisão necessária para colocar o agente no ar Não aprove um agente de WhatsApp apenas pela resposta exibida na demonstração. Abra uma amostra de atendimentos e compare a quantidade de mensagens enviadas com o resumo gravado no CRM, observando se o corretor foi chamado assim que o lead aceitou uma visita. Se a amostra mostrar uma pergunta repetida ou um encaminhamento tardio, o agente ainda precisa de ajuste para receber volume. A arquitetura pode seguir para [uma revisão comercial](https://promovaweb.com/comercial), e o artigo sobre [quando abrir CNPJ para empresa de tecnologia](https://promovaweb.com/blog/quando-abrir-cnpj-tecnologia) amplia a análise da oferta recorrente para a formalização da atividade. ### Como escolher CNAE para empresa de tecnologia SaaS? - URL: https://promovaweb.com/blog/cnae-empresa-tecnologia-saas - Publicado em: 2026-07-09T12:00:00Z - Descrição: Veja como pensar CNAE para empresa de tecnologia, SaaS, suporte e marketing sem misturar atividades que encarecem a abertura do CNPJ. Leia agora. Uma agência pode escolher um CNAE para automação recorrente e descobrir na emissão da nota que a atividade cadastrada descreve outro tipo de serviço. Eu prefiro encontrar essa divergência durante a abertura, com a proposta comercial na mesa, pois a correção posterior pode exigir alteração do contrato social. O CNAE é a classificação usada para identificar as atividades econômicas da empresa. A seleção precisa refletir o que será faturado e considerar as exigências do município, sem copiar a lista de códigos de outra software house. ## Direto ao ponto A escolha começa pela oferta que gera a maior parte da receita e pela forma usada para cobrar o cliente. Uma assinatura de software exige uma leitura diferente de um projeto sob encomenda, por isso o contador precisa conhecer o contrato e a descrição prevista para a nota fiscal. Atividades secundárias entram quando representam serviços que a empresa realmente pretende faturar. Cada código adicional deve corresponder a uma oferta identificável, pois algumas atividades podem alterar o licenciamento municipal ou a tributação. ## O CNAE principal deve representar a receita principal O CNAE principal deve representar a atividade predominante da empresa conforme a orientação contábil aplicável ao caso. Se a receita vem de assinatura de software, essa informação precisa comandar a reunião em vez de uma atividade eventual de consultoria. Uma lista pronta de códigos para empresas de tecnologia não substitui essa comparação. A descrição oficial precisa ser confrontada com o serviço contratado e com o município da sede, pois uma expressão parecida pode abranger uma atividade diferente daquela realizada. ## CNAE secundário amplia coerência, não bagunça a empresa Um CNAE secundário faz sentido ao cobrir uma oferta complementar com possibilidade real de faturamento. A agência que vende automação e também presta treinamento pode levar os dois contratos ao contador para verificar como cada serviço deve aparecer no cadastro. Uma ideia futura não precisa ocupar o contrato social desde a abertura. Incluir atividades distantes da receita atual aumenta a superfície de licenciamento e dificulta explicar ao cliente qual serviço a empresa presta. ## Software, SaaS e desenvolvimento exigem leituras diferentes Uma empresa que desenvolve um sistema sob encomenda assume obrigações diferentes daquelas presentes numa assinatura SaaS. O primeiro contrato descreve um projeto para um cliente, enquanto a assinatura concede acesso recorrente a um software mantido pela própria empresa. Essa diferença altera a redação do contrato e a descrição do documento fiscal. Leve ao contador uma proposta de cada oferta ativa para que a classificação acompanhe a forma usada na cobrança. ## Suporte técnico e instalação também entram na análise Orientar o uso de um sistema é diferente de implantar a infraestrutura usada pelo cliente. Uma proposta que inclui a publicação do [n8n](https://promovaweb.com/ferramentas/n8n) precisa descrever a responsabilidade técnica assumida pela agência e o suporte incluído depois da instalação. O mesmo cuidado vale para o [Chatwoot](https://promovaweb.com/ferramentas/chatwoot), pois configurar a aplicação pode incluir manutenção recorrente. O contrato e a nota devem representar o serviço efetivamente prestado, e o contador traduz essa descrição para a classificação adequada. ## Marketing, conteúdo e educação exigem cuidado próprio Uma empresa técnica pode manter uma assinatura de software e também vender uma formação. A atividade de ensino merece análise própria, porque o documento fiscal e as exigências municipais podem ser diferentes daqueles usados na licença do software. O mesmo raciocínio se aplica a uma agência que acrescenta marketing à oferta de automação. A atividade só deve entrar no cadastro depois de confirmar que existe um contrato correspondente e que a empresa pretende faturá-lo no horizonte próximo. ## Atividades misturadas encarecem a correção Uma atividade regulada pode exigir licença ou registro profissional que não faria parte de uma empresa dedicada a software. Incluir esse código apenas para ampliar possibilidades cria obrigações sem relação com a receita atual. Mantenha o cadastro próximo das ofertas comprovadas por propostas e contratos. Quando a empresa inaugurar outra linha de serviço, o contador pode avaliar a alteração cadastral com base numa venda concreta. ## Rio de Janeiro, Distrito Federal e município importam O município participa da consulta de viabilidade e pode definir exigências de licenciamento para a atividade declarada. Uma sede virtual barata perde utilidade se o endereço não aceita o serviço ou se a empresa precisa manter presença em outra cidade. Compare a emissão de nota e o custo de manutenção com a rotina real dos sócios. Benefício fiscal ou programa de inovação só entra na análise depois de confirmar elegibilidade e duração em fonte oficial do município. ## Como chegar melhor na reunião com o contador Leve ao contador os contratos ou propostas das ofertas que devem gerar receita nos meses seguintes. Cada documento mostra o que será feito e como a empresa cobrará pelo serviço, oferecendo uma base melhor do que o rótulo genérico “tecnologia”. O contador pode então indicar a atividade principal e as atividades secundárias compatíveis com o caso. Depois da orientação, eu conferiria cada descrição na [busca oficial da Concla](https://concla.ibge.gov.br/busca-online-cnae.html) e guardaria a justificativa junto dos documentos da abertura. ## O cluster acompanha a estrutura da empresa O artigo sobre [quando abrir CNPJ para empresa de tecnologia](https://promovaweb.com/blog/quando-abrir-cnpj-tecnologia) situa a exigência do cliente e a escolha do endereço. Essa leitura vem primeiro para empresas que ainda comparam o custo da formalização com o trabalho como profissional autônomo. O texto sobre [MEI ou Simples para empresa de tecnologia](https://promovaweb.com/blog/mei-simples-tecnologia-impostos) aprofunda a atividade permitida e o limite de receita. Ele é útil para empresas já formalizadas que precisam verificar se a oferta continua compatível com o enquadramento atual. ## Próxima revisão prática Abra o contrato social ou o rascunho da abertura e escreva, em uma frase, a origem principal da receita. Se a frase tentar abarcar toda atividade digital possível, refaça a descrição a partir da oferta que já tem cliente e preço definidos. O [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma) trabalha a ligação entre oferta e estrutura empresarial. Uma [reunião comercial com a Promovaweb](https://promovaweb.com/comercial) também pode organizar o escopo da automação que será apresentado ao contador e ao advogado. ### Como usar IA jurídica no SaaS sem delegar revisão? - URL: https://promovaweb.com/blog/ia-juridica-saas-revisao - Publicado em: 2026-07-09T12:00:00Z - Descrição: Veja como usar IA jurídica para revisar termos de SaaS com fontes oficiais e perguntas para advogado sem substituir análise profissional. Revise hoje. Uma IA jurídica pode produzir uma minuta bem formatada sem conhecer a tela exibida no fim do trial. Eu desconfio desse acabamento quando o texto descreve cancelamento imediato, mas o SaaS ainda depende de uma solicitação enviada ao suporte. Eu uso o modelo para preparar a consulta e localizar perguntas que precisam de uma tela ou de um documento real para responder. A conclusão sobre uma obrigação contratual permanece com o profissional habilitado, apoiado pelas telas e pelos documentos reais do software. ## Direto ao ponto A IA jurídica pode comparar uma minuta com o fluxo de cadastro e apontar trechos sem correspondência na interface. Ela também pode localizar fontes oficiais e formular perguntas, desde que cada referência seja aberta e conferida pelo responsável pela revisão. Uma descrição curta do SaaS não oferece base suficiente para avaliar o documento. O prompt precisa incluir a tela do aceite e o comportamento da assinatura, enquanto a revisão final permanece com o advogado quando houver obrigação jurídica relevante. ## A IA precisa do escopo do SaaS Um modelo não consegue revisar um software descrito apenas como “plataforma de gestão”. A entrada precisa identificar o usuário e mostrar a ação executada no cadastro, além do estado exibido depois do fim do trial. Anexe o texto do checkbox e o email transacional usado pelo SaaS. Esses artefatos permitem comparar a minuta com a informação realmente apresentada durante o uso. ## Fonte oficial reduz resposta solta Quando o tema é Brasil, eu começo pelas versões oficiais da [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) e do [Marco Civil da Internet](https://www.planalto.gov.br/ccivil_03/_ato2011-2014/2014/lei/l12965.htm). O [Código de Defesa do Consumidor](https://www.planalto.gov.br/ccivil_03/leis/l8078compilado.htm) e o [Código Civil](https://www.planalto.gov.br/ccivil_03/leis/2002/l10406compilada.htm) também podem integrar a pesquisa conforme a relação jurídica examinada. Copiar a lei inteira para o prompt não transforma a resposta em parecer. Eu solicito a indicação do artigo utilizado e abro a fonte para verificar se o trecho existe e se a interpretação não extrapola o texto legal. ## O prompt prepara perguntas para a revisão O prompt bom reúne perguntas sobre o aceite e a cobrança exibidos no fluxo fornecido ao modelo. A resposta precisa indicar qual tela ou fonte levou a cada alerta, permitindo que o responsável reproduza a situação no SaaS. Depois separaria mudanças de interface das questões destinadas ao advogado. Uma divergência no email pode ser corrigida na copy, enquanto a redação de uma obrigação contratual exige análise profissional. ## Alerta da IA não é parecer Um alerta produzido pela IA é uma hipótese para conferência. A afirmação precisa ser rastreada até a fonte e comparada com o comportamento do SaaS, pois o modelo pode misturar relações de consumo e contratos entre empresas. Leve ao especialista a tela e o trecho da minuta que gerou a dúvida. Essa preparação permite discutir uma cláusula específica sem apresentar a resposta do modelo como conclusão jurídica. ## Modelo de empresa grande precisa de adaptação O termo de uma empresa maior pode revelar temas que merecem pesquisa, mas descreve outra oferta e outra capacidade de suporte. Uma cláusula de marketplace não deve entrar num SaaS simples apenas porque o texto parece completo. Instruir a IA a identificar diferenças entre o modelo externo e o fluxo fornecido produz um roteiro de revisão, não uma autorização para copiar cláusulas ou redação protegida. ## IA jurídica também compara termo e interface As condições do SaaS aparecem no documento e nas ações disponíveis na interface. A revisão precisa verificar se o botão de cancelamento e o estado final do trial correspondem ao texto aceito pelo usuário. Forneça capturas dessas telas e inclua uma tabela de divergências com a localização exata de cada frase. Depois, abra o software para confirmar os apontamentos, pois a IA também pode interpretar incorretamente uma imagem ou um estado incompleto. ## O que levar para um especialista Leve ao especialista a minuta atual e o fluxo do cadastro até o cancelamento. Inclua as capturas do checkout e do fim do trial, pois essas telas demonstram a condição apresentada ao usuário. Também registre uma situação que já chegou ao suporte, como uma solicitação de exclusão ou uma cobrança contestada. O caso concreto mostra onde a interface e o documento produziram interpretações diferentes. ## A preparação jurídica acompanha a oferta No [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma), a discussão parte da oferta e do suporte prometido ao cliente. A IA pode registrar perguntas, mas o escopo comercial precisa estar definido para que o advogado examine uma relação real. Um [atendimento comercial com a Promovaweb](https://promovaweb.com/comercial) pode organizar a jornada do SaaS e as telas e os documentos que seguirão para revisão especializada. O trabalho permanece limitado ao desenho da oferta e não substitui a atividade jurídica. ## Os termos e o trial fornecem as superfícies O texto sobre [termos de uso no MVP](https://promovaweb.com/blog/termos-uso-mvp-saas) mostra onde o aceite aparece na validação externa. Essa superfície fornece uma entrada concreta para a comparação feita pela IA. O artigo sobre [trial de SaaS](https://promovaweb.com/blog/trial-saas-teste-gratuito) aprofunda a duração e o estado final do acesso. Se a aplicação também usa agentes no WhatsApp, o texto sobre [custo por mensagem na WhatsApp API](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia) acrescenta a cobrança variável à oferta revisada. Use a IA jurídica para produzir perguntas rastreáveis e conferir divergências. A minuta publicável precisa de revisão profissional quando cria obrigações ou afeta direitos do usuário. ### MEI ou Simples serve para empresa de tecnologia SaaS? - URL: https://promovaweb.com/blog/mei-simples-tecnologia-impostos - Publicado em: 2026-07-09T12:00:00Z - Descrição: Compare MEI, Simples Nacional e porte da empresa de tecnologia para evitar desenquadramento, imposto extra e retrabalho contábil em 2026. Leia agora. O MEI pode parecer suficiente durante a primeira venda, mas a compatibilidade depende da ocupação exercida e da receita acumulada no ano. Eu abriria o cadastro mensalmente para comparar o faturamento com o limite proporcional e verificar se a descrição das notas corresponde à ocupação permitida. Esse cuidado é especialmente importante em serviços tecnológicos, pois nem toda atividade de desenvolvimento ou consultoria aparece na lista do MEI. Usar uma ocupação parecida apenas para obter o cadastro cria divergência entre o serviço contratado e o enquadramento informado ao governo. ## Direto ao ponto O MEI serve apenas quando a ocupação está autorizada e a receita respeita o limite correspondente aos meses de atividade. O Portal do Empreendedor informa o teto anual de `R$ 81 mil` e calcula `R$ 6.750` para cada mês no ano da formalização. Uma empresa que ultrapassa esse limite ou começa a exercer outra atividade precisa discutir o desenquadramento com o contador. A migração planejada permite ajustar a forma empresarial e a rotina fiscal com base nos contratos que continuarão ativos. ## MEI não tem o mesmo papel que ME O MEI é o empresário individual enquadrado no Simei, enquanto ME e EPP indicam portes definidos pela receita bruta. A Lei Complementar 123/2006 estabelece até `R$ 360 mil` para microempresa e até `R$ 4,8 milhões` para empresa de pequeno porte. O desenquadramento do Simei exige análise além da troca de uma sigla. O contador verifica os efeitos sobre a forma empresarial e as obrigações fiscais, considerando a atividade que a empresa continuará exercendo. ## O limite do MEI precisa ser proporcional O limite anual não fica inteiro para uma formalização realizada no meio do ano. Um MEI aberto em julho considera seis meses de atividade até dezembro, o que corresponde a `R$ 40.500` pelo cálculo mensal informado no Portal do Empreendedor. Mantenha uma planilha simples com a receita bruta acumulada e a previsão dos contratos já assinados. Quando a projeção se aproximar do teto proporcional, o contador consegue preparar a mudança sem esperar o fechamento do ano. ## Tecnologia precisa olhar atividade permitida O Portal do Empreendedor mantém uma lista de ocupações permitidas para o MEI. O fato de um emissor aceitar texto livre na nota não altera a ocupação cadastrada, portanto a descrição do serviço deve permanecer coerente com a atividade autorizada. Um contrato de desenvolvimento de software merece atenção porque a atividade pode não caber no enquadramento escolhido, e a nota emitida fora da ocupação permitida vira motivo de questionamento na malha fiscal. Eu levo o contrato ao contador e consulto a lista oficial do Portal do Empreendedor, em vez de selecionar uma ocupação genérica por semelhança de nome. ## Recebimento e faturamento precisam conversar O extrato bancário pode incluir transferência entre bancos do mesmo titular ou estorno, por isso movimentação e receita bruta não são sinônimos. Cada entrada precisa ter documento que explique sua origem para que o contador consiga separar faturamento de uma movimentação sem natureza comercial. Concilie o extrato com as notas emitidas ao final de cada mês. Uma diferença sem comprovante deve ser investigada enquanto o contrato e o recibo ainda estão acessíveis, evitando reconstruir o histórico meses depois. ## Desenquadramento saudável é melhor que susto fiscal O desenquadramento planejado começa ao perceber que os contratos assinados levarão a receita além do limite. O contador consegue calcular a data e os efeitos aplicáveis ao caso, além de orientar quais cadastros comerciais precisam ser atualizados. Esperar o excesso aparecer na declaração reduz o tempo disponível para ajustar preço e custo contábil. Eu incluiria a nova despesa mensal na proposta dos contratos seguintes e manteria uma reserva para a transição. ## Simples Nacional não dispensa acompanhamento O Simples Nacional é um regime compartilhado de arrecadação aplicável às microempresas e empresas de pequeno porte que cumprem seus requisitos. A guia unificada simplifica o recolhimento, mas não define sozinha qual anexo ou alíquota se aplica ao serviço tecnológico. O contador precisa considerar a atividade e a receita acumulada, além de verificar se a folha altera o cálculo pelo Fator R. Serviços prestados ao exterior e mudanças relacionadas ao IBS e à CBS também exigem análise específica. ## Pró-labore e distribuição de lucros precisam aparecer no contrato O pró-labore remunera o trabalho do sócio, enquanto a distribuição depende do lucro apurado pela contabilidade. Tratar toda retirada como distribuição sem escrituração compatível pode gerar questionamento fiscal e recolhimentos adicionais. Uma porcentagem encontrada num artigo não define esses valores. O contador calcula a retirada com base na atividade e na escrituração, enquanto o advogado revisa as cláusulas societárias quando existe mais de um sócio. ## Reforma tributária aumenta a necessidade de revisão A Receita Federal informou que a opção pelo Simples para 2027 ocorre entre 1º e 30 de setembro de 2026. No mesmo período, a empresa pode escolher o recolhimento regular do IBS e da CBS para o primeiro semestre de 2027, conforme as condições divulgadas pelo Comitê Gestor. Essa janela exige uma revisão contábil das vendas previstas para 2027. Uma empresa que atende clientes interessados em créditos tributários precisa simular os dois caminhos com documentos e projeções, sem presumir que o regime regular será melhor. ## Como eu organizaria a revisão O relatório de receita bruta, conciliado mês a mês com as notas emitidas, é o ponto de partida que eu uso nessa revisão. Em seguida, os contratos ativos e a previsão de faturamento até dezembro seguem para o contador. Esses documentos permitem comparar o limite do MEI com a receita projetada e calcular os efeitos de uma migração. Se houver sociedade, o contrato social segue para revisão jurídica separada da apuração tributária. ## O restante do cluster orienta a formalização O artigo sobre [quando abrir CNPJ para empresa de tecnologia](https://promovaweb.com/blog/quando-abrir-cnpj-tecnologia) trata da exigência do cliente e do custo de manutenção. Essa leitura oferece um ponto de partida ao profissional autônomo que ainda compara a formalização com a forma atual de contratação. A leitura sobre [CNAE para empresa de tecnologia e SaaS](https://promovaweb.com/blog/cnae-empresa-tecnologia-saas) examina a atividade declarada e sua relação com a oferta. Esse passo é necessário quando o serviço vendido não corresponde à ocupação cadastrada no MEI. ## Revisão prática com documentos na mesa Use este artigo para preparar a próxima reunião contábil, sem tratá-lo como cálculo individual. Leve o relatório de receita e as notas emitidas, pois esses documentos permitem verificar o limite e planejar uma eventual migração. No [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma), a estrutura empresarial é discutida junto da oferta e do contrato. Uma [reunião comercial com a Promovaweb](https://promovaweb.com/comercial) pode organizar o escopo técnico da venda que será apresentado ao contador e ao advogado. ### Quando abrir CNPJ para empresa de tecnologia digital? - URL: https://promovaweb.com/blog/quando-abrir-cnpj-tecnologia - Publicado em: 2026-07-09T12:00:00Z - Descrição: Entenda quando abrir CNPJ para tecnologia, quais sinais observar e como estruturar endereço, contador e atividade sem criar custo futuro. Leia agora. Uma proposta de automação pode avançar bem até o cliente informar que só contrata fornecedor com CNPJ e nota fiscal. Eu costumo tratar esse momento como um sinal comercial objetivo, pois a venda já exige uma estrutura diferente daquela usada para receber como profissional autônomo. Abrir a empresa com pressa também cria trabalho desnecessário. Um endereço inadequado ou uma atividade econômica incompatível com o serviço pode exigir alteração cadastral justamente durante a validação de uma plataforma ou a assinatura do primeiro contrato. ## Direto ao ponto Abrir CNPJ faz sentido quando o contrato exige nota fiscal ou quando uma plataforma solicita comprovação empresarial para liberar um recurso necessário ao serviço. A análise também precisa comparar o custo de manter a empresa com a tributação e as obrigações aplicáveis ao trabalho realizado como profissional autônomo. Leve para o contador uma descrição simples da oferta e uma estimativa de receita para os meses seguintes. Com isso, o profissional pode orientar a natureza jurídica, as atividades econômicas e o regime tributário sem partir de um formulário preenchido às cegas. ## O sinal mais claro vem do cliente e da nota fiscal O cliente fornece o sinal mais claro ao incluir CNPJ e nota fiscal no processo de contratação. A negociação fica parada se o fornecedor não consegue concluir o cadastro ou emitir o documento fiscal correspondente ao serviço descrito na proposta. Esse cenário aparece tanto numa automação de WhatsApp quanto no desenvolvimento de um sistema sob encomenda. O contrato identifica a empresa responsável pelo serviço e a nota registra a receita, portanto os dois documentos precisam refletir a mesma atividade exercida. ## Plataforma também força a revisão Algumas plataformas solicitam documentos durante a verificação da empresa ou a adesão a programas específicos. Como as exigências mudam, eu abro a documentação vigente da plataforma e comparo o nome empresarial e o contato oficial com os registros públicos. Essa conferência evita descobrir uma divergência durante a implantação do canal do cliente. Se o painel recusar o documento, o responsável técnico consegue verificar se a diferença está no nome cadastrado ou no telefone usado pela empresa, em vez de atribuir a falha à integração. ## Endereço do CNPJ também entra na escolha O endereço merece atenção mesmo numa empresa que presta serviços pela internet. O comprovante usado na abertura precisa ser compatível com a atividade e com as exigências municipais, além de considerar que parte das informações cadastrais pode ser consultada publicamente. Uma sede virtual pode atender empresas sem recepção física, desde que o local aceite a atividade e cumpra as exigências da prefeitura. Confirme a viabilidade na Redesim e pergunte ao contador como o município trata a emissão de nota naquele endereço. ## Atividade econômica não deve ficar para depois O Cadastro Nacional de Atividades Econômicas descreve as atividades exercidas pela empresa. Copiar os códigos de outra agência pode deixar o contrato social distante da oferta e produzir uma descrição de nota fiscal difícil de explicar ao cliente. Comece pelos contratos que a empresa espera assinar no próximo semestre. O contador pode traduzir cada serviço recorrente para a classificação aplicável e separar a atividade predominante daquelas que funcionam como complemento real da receita. ## Contador não entra só para abrir a empresa A [Redesim](https://www.gov.br/empresas-e-negocios/pt-br/redesim) centraliza a consulta de viabilidade e as etapas de inscrição e licenciamento. A abertura termina com uma empresa que continuará enviando declarações e emitindo documentos fiscais, por isso o trabalho do contador não se encerra no protocolo inicial. O artigo sobre [MEI ou Simples para empresa de tecnologia](https://promovaweb.com/blog/mei-simples-tecnologia-impostos) aprofunda o limite de receita e a migração para outra estrutura. Nesta etapa, confirme qual acompanhamento mensal está incluído no contrato contábil e como serão feitas as alterações futuras. ## CNPJ barato pode sair caro Uma abertura anunciada como gratuita pode estar vinculada a mensalidade mínima ou multa de cancelamento. Abra o contrato contábil e procure o prazo de permanência, além de confirmar quais serviços geram cobrança adicional. O formato online pode funcionar bem quando o atendimento compreende a oferta tecnológica e responde dentro do prazo necessário. O teste prático ocorre ao perguntar como o escritório trataria uma nova atividade de SaaS ou uma nota de serviço para cliente no exterior. ## A revisão que eu faria na abertura Coloque o contrato mais provável na mesa e escreva qual serviço será faturado no primeiro semestre. Essa descrição permite conferir se o nome empresarial e a atividade econômica combinam com a nota que o cliente receberá. Abra também a consulta de viabilidade do endereço e mantenha o email empresarial sob controle do próprio negócio. Se houver sociedade, o advogado precisa discutir administração e saída de sócio com base na relação real entre os participantes. ## Fontes oficiais que ajudam na conferência A [Lei Complementar 123/2006](https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp123.htm) reúne disposições sobre microempresa e empresa de pequeno porte. Para a atividade econômica, a busca oficial da Concla permite consultar a descrição de cada código, embora a aplicação ao caso deva ser revisada pelo contador. Essas fontes permitem chegar à reunião profissional com perguntas mais específicas. Você consegue mostrar a oferta e o município da sede, enquanto o contador calcula o enquadramento tributário aplicável à empresa. ## O próximo passo depois do CNPJ Depois de reconhecer a necessidade do CNPJ, a próxima revisão identifica qual atividade representa a receita da empresa. O artigo sobre [CNAE para empresa de tecnologia e SaaS](https://promovaweb.com/blog/cnae-empresa-tecnologia-saas) mostra como ligar a oferta ao contrato social e à nota fiscal. O [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma) trabalha a relação entre oferta e estrutura empresarial ao longo da formação. Quando a empresa já vende uma automação recorrente, uma [reunião comercial com a Promovaweb](https://promovaweb.com/comercial) pode organizar o escopo que será levado ao contador ou ao advogado. ### Quando termos de uso entram no MVP de SaaS com usuário? - URL: https://promovaweb.com/blog/termos-uso-mvp-saas - Publicado em: 2026-07-09T12:00:00Z - Descrição: Entenda quando termos de uso no MVP organizam aceite, privacidade, trial e contrato do SaaS sem travar validação. Revise o básico com calma hoje. Um MVP pode funcionar bem no computador do criador e apresentar outra realidade ao receber o primeiro usuário externo. A tela de cadastro cria uma relação verificável, por isso o acesso oferecido e o comportamento esperado do software precisam de um registro compatível com o teste. Eu não adiaria toda validação até existir um contrato extenso. Também não liberaria o uso externo com uma tela que promete acesso gratuito enquanto o documento disponível descreve uma assinatura paga. ## Direto ao ponto Termos de uso entram no MVP quando um usuário externo recebe acesso e aceita condições para utilizar o software. O documento precisa corresponder ao que a interface oferece e explicar a duração do teste ou a cobrança que pode surgir durante o uso. A primeira versão deve partir do trajeto de cadastro e do estado exibido ao final do trial. A IA pode levantar perguntas sobre essas telas, mas um profissional habilitado precisa revisar trechos que criam obrigação contratual ou exposição jurídica relevante. ## O acesso externo exige um combinado visível Um teste interno permite ajustar a interface sem prometer continuidade a terceiros. A liberação para um cliente muda essa superfície, pois o usuário precisa saber qual funcionalidade está disponível e até quando o acesso permanecerá ativo. O termo registra esse combinado e oferece uma referência para o suporte. Quando o cliente solicita uma funcionalidade ausente, o atendente consegue comparar a solicitação com o escopo apresentado no cadastro. ## A tela precisa combinar com o contrato Um termo isolado não corrige uma interface contraditória. Se a página oferece teste gratuito e o documento descreve cobrança imediata, o usuário encontra duas condições para a mesma jornada. Abra o cadastro e siga até a tela exibida no fim do trial. O checkbox de aceite e o email de confirmação precisam repetir a duração e a condição de cobrança sem esconder a informação numa página distante. ## Política de privacidade aparece cedo quando há informação pessoal A [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) alcança o tratamento de informações relacionadas a um titular identificado ou identificável. Um MVP que recebe nome e email já precisa mapear a finalidade dessa coleta e o caminho percorrido pelo cadastro. A política de privacidade deve refletir esse fluxo e indicar um canal para o titular exercer os direitos aplicáveis. A redação não pode prometer eliminação imediata em toda situação, pois a retenção pode depender de obrigação legal ou de outra hipótese prevista na própria lei. ## Código Civil e consumidor entram no combinado O [Código Civil](https://www.planalto.gov.br/ccivil_03/leis/2002/l10406compilada.htm) integra a análise das obrigações assumidas no contrato. O [Código de Defesa do Consumidor](https://www.planalto.gov.br/ccivil_03/leis/l8078compilado.htm) merece revisão quando a relação concreta se enquadra como consumo e a oferta pública influencia a expectativa do usuário. Essas leis não autorizam uma conclusão individual neste artigo. Elas mostram por que a informação exibida sobre cancelamento ou cobrança precisa ser levada ao advogado junto da minuta e das telas correspondentes. ## Modelo genérico costuma desviar a revisão Um modelo público pode sugerir temas a investigar, mas carrega a oferta e a estrutura da empresa que o publicou. A troca do nome da marca não adapta a cobrança nem o suporte daquele documento ao MVP em revisão. Use o modelo para formular perguntas e volte à interface para encontrar as respostas. O advogado precisa ver como o usuário entra e qual estado aparece no fim do acesso para redigir uma cláusula compatível com o software. ## Prompt bom transforma escopo em pergunta A IA pode ler o fluxo do MVP e perguntar onde o aceite é registrado ou qual tela informa o fim do trial. Essa preparação torna a consulta mais específica porque o especialista recebe a dúvida junto da superfície correspondente. Não publique a minuta produzida pelo modelo sem revisão humana. Uma resposta fluente pode citar uma fonte inadequada ou descrever um cancelamento que ainda não existe na aplicação. ## O mínimo útil para um MVP SaaS O mínimo útil depende do comportamento já disponível no MVP. O termo deve identificar a empresa e explicar o acesso oferecido, enquanto a interface registra o aceite e apresenta um canal de contato acessível. Uma cobrança recorrente exige uma revisão mais detalhada da jornada. O checkout e o email de confirmação precisam mostrar o preço e a renovação, e o termo deve refletir o cancelamento realmente implementado no software. ## A revisão acompanha o lançamento No [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma), eu relaciono a oferta do SaaS com o contrato apresentado ao cliente. A definição do suporte e do preço fornece o material que seguirá para a revisão jurídica. Um [atendimento comercial com a Promovaweb](https://promovaweb.com/comercial) pode organizar a jornada do software e registrar as dúvidas que serão encaminhadas ao advogado. Essa etapa não substitui assessoria jurídica e permanece concentrada na oferta e no funcionamento da aplicação. ## O trial e a IA ampliam a revisão O artigo sobre [trial de SaaS e teste gratuito](https://promovaweb.com/blog/trial-saas-teste-gratuito) aprofunda o estado exibido no fim do período. Essa leitura é necessária quando o MVP oferece acesso temporário ou inicia cobrança depois do teste. O texto sobre [IA jurídica no SaaS](https://promovaweb.com/blog/ia-juridica-saas-revisao) mostra como preparar uma consulta sem delegar a conclusão ao modelo. Se o software também usa WhatsApp, o artigo sobre [WhatsApp API nos agentes de IA](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia) acrescenta o custo variável que pode afetar a oferta. Os termos registram o comportamento que o usuário encontra no MVP. A versão publicável precisa partir da tela real e receber revisão profissional compatível com as obrigações assumidas pelo SaaS. ### Como avisar o fim do trial gratuito em um SaaS real? - URL: https://promovaweb.com/blog/trial-saas-teste-gratuito - Publicado em: 2026-07-09T12:00:00Z - Descrição: Veja como trial SaaS deve explicar prazo, acesso, cobrança e histórico para reduzir conflito no fim do teste gratuito. Revise esse combinado hoje. Um trial parece simples até o usuário cadastrar clientes e chegar ao último dia sem saber qual tela aparecerá depois. A incerteza aumenta quando existe cartão registrado, pois o cliente não consegue distinguir suspensão de acesso e início de cobrança. Eu trato o trial como parte da oferta e da experiência contratual do SaaS. A interface precisa mostrar o prazo restante e exibir com antecedência o estado final descrito nos termos de uso. ## Direto ao ponto O trial precisa informar a duração e o comportamento do acesso no fim do período. Se houver cobrança automática ou possibilidade de exportação, essas condições devem aparecer na interface e no documento aceito pelo usuário. O aviso final não pode surgir apenas depois que a aplicação recusa a entrada. Eu exibiria a data de término durante o uso e enviaria uma confirmação próxima ao encerramento, respeitando o que foi prometido no cadastro. ## O teste gratuito começa pela expectativa Uma página que promete 30 dias estabelece uma referência temporal objetiva. O painel precisa mostrar a data final e indicar se a aplicação ficará somente para leitura ou se o login será suspenso. Essa informação também orienta a profundidade do teste. O usuário consegue escolher se deve importar uma base de clientes depois de entender o que ocorrerá com os registros ao final do período. ## A tela precisa exibir a data do encerramento Uma etiqueta com a palavra `teste` não informa a data nem o efeito do encerramento. O painel pode exibir os dias restantes e levar à página do plano, permitindo que o usuário revise a condição sem interromper a tarefa atual. Inclua essa informação no onboarding e no email de boas-vindas. Ao abrir a assinatura, você precisa encontrar a mesma data e a mesma descrição do estado final. ## O fim do período precisa ter texto escrito O termo de uso deve descrever o estado realmente implementado no fim do trial. Se o SaaS permite somente leitura por sete dias, a tela final precisa oferecer esse acesso e mostrar o prazo correspondente. O [Código de Defesa do Consumidor](https://www.planalto.gov.br/ccivil_03/leis/l8078compilado.htm) integra a análise quando existe uma relação de consumo. A oferta e a informação apresentada ao usuário devem ser levadas ao advogado junto da interface, sem presumir neste artigo a aplicação ao caso individual. ## Cobrança automática exige cuidado maior Um trial com cartão cadastrado pode iniciar uma cobrança ao final do período, conforme a oferta apresentada. O checkout precisa destacar a data e o preço da primeira cobrança, além de indicar o caminho de cancelamento disponível no SaaS. Repita essa informação no email de confirmação e na página da assinatura. A cláusula contratual continua necessária, mas não deve ser a única superfície capaz de explicar a cobrança. ## Histórico criado durante o teste também importa Um trial pode receber cadastros de clientes e arquivos usados no trabalho diário. O fim do acesso não apaga a responsabilidade sobre as informações pessoais tratadas durante o teste. A política de privacidade deve explicar a finalidade e a retenção conforme o trajeto das informações no SaaS. Quando a [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) se aplica, o titular também precisa encontrar um canal para exercer os direitos cabíveis. ## Trial sem limite vira suporte confuso O teste gratuito precisa indicar o suporte incluído durante o período. Se a oferta cobre apenas dúvidas sobre o uso, o usuário não deve descobrir no atendimento que uma integração personalizada exige contratação separada. Essa distinção permite avaliar o software sem transformar o trial numa implantação gratuita. O suporte consegue responder a falhas da aplicação e encaminhar solicitações de projeto para a área comercial. ## Como eu escreveria o combinado na prática Comece pela frase exibida na interface e reproduza o período nos termos de uso. Em seguida, teste o encerramento no ambiente de homologação para confirmar que o estado final corresponde ao texto publicado. Revise também os emails disparados pela aplicação. Uma mensagem próxima ao fim deve informar a data e levar à página na qual o usuário escolhe o plano ou encerra o teste. ## Quando o trial precisa de revisão jurídica O trial merece revisão especializada quando envolve cobrança automática ou tratamento de informações pessoais. A integração com sistemas do cliente também pode criar obrigações que não aparecem num teste isolado da aplicação. Leve ao advogado o cadastro e a tela da assinatura, junto do email de boas-vindas e do estado final. Esses artefatos mostram o que o usuário viu e permitem comparar a minuta com o comportamento implementado. ## A oferta define o desenho do trial No [Plano Founders da Promovaweb](https://promovaweb.com/planos/founders-2-turma), o trial deriva do preço e do suporte previstos na oferta. O teste deve permitir que o usuário experimente a utilidade principal do SaaS sem prometer uma implantação que o plano não inclui. O conjunto de [formações da Promovaweb](https://promovaweb.com/planos) também cobre a construção técnica e a aquisição do usuário. Essa integração permite testar a jornada inteira e registrar qual área assumirá cada ajuste encontrado. ## Os termos e a IA completam a revisão O texto sobre [termos de uso no MVP](https://promovaweb.com/blog/termos-uso-mvp-saas) explica como o aceite entra na validação externa. Essa leitura é útil quando o trial ainda não registra qual versão do documento foi aceita. O artigo sobre [IA jurídica no SaaS](https://promovaweb.com/blog/ia-juridica-saas-revisao) separa preparação automatizada e revisão profissional. Se o trial usa atendimento pelo WhatsApp, o texto sobre [WhatsApp API e custo de agentes de IA](https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia) acrescenta a despesa variável à análise da oferta. Um bom trial termina com o estado previsto desde o cadastro. A tela final precisa permitir que o usuário escolha o caminho disponível sem descobrir uma condição diferente daquela aceita no início. ### Quanto custa usar WhatsApp API em agentes de IA hoje? - URL: https://promovaweb.com/blog/whatsapp-api-custo-agentes-ia - Publicado em: 2026-07-09T12:00:00Z - Descrição: Entenda como o custo por mensagem no WhatsApp muda agentes de IA, qualifica leads e entra na precificação de fluxos comerciais com n8n. Leia agora. Eu abro o relatório de uma automação de WhatsApp e procuro duas informações: quantas mensagens a empresa enviou e quantas visitas o atendimento gerou. A partir de 1º de outubro de 2026, as respostas de serviço enviadas por uma empresa serão cobradas por mensagem entregue, por isso a troca inteira precisa aparecer no orçamento do agente de IA. O exemplo da imobiliária deixa esse cálculo fácil de enxergar, porque o lead raramente chega pronto para comprar. Ele pode começar perguntando sobre aluguel e mudar para compra depois de falar sobre financiamento, o que exige mais mensagens até o corretor receber um contato com possibilidade de visita. ## Direto ao ponto O valor `US$ 0,0068` por mensagem entregue funciona como referência provisória para a simulação, pois a Meta informou que publicará a tarifa válida em outubro até 1º de setembro de 2026. Com o câmbio hipotético de `R$ 5,15` por dólar, uma resposta fica perto de `R$ 0,035` e `100.000` respostas aproximam a fatura mensal de `R$ 3.500,00`. Esse número deve entrar ao lado dos demais custos recorrentes da automação. O dono da agência precisa comparar a despesa das mensagens com as visitas geradas, acrescentar o servidor usado pelo n8n e estimar quantas horas serão consumidas na manutenção mensal. ## O WhatsApp entra no orçamento por mensagem entregue A página pública de [preços da WhatsApp Business Platform](https://whatsappbusiness.com/products/platform-pricing/) explica que a cobrança ocorre quando a mensagem é entregue e que a tarifa varia conforme a categoria e o país do destinatário. A documentação da Meta sobre [mensagens não template](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/non-template-messages/) aponta 1º de outubro de 2026 como data de início da cobrança pelas respostas de serviço dentro da janela de atendimento. Essa data importa porque as respostas de serviço dentro da janela de 24 horas não eram cobradas desde novembro de 2024. A partir da mudança, eu trataria cada envio como parte do custo do atendimento e compararia a quantidade de mensagens com o encaminhamento registrado no CRM. ## O valor pequeno muda com o volume Uma mensagem a `R$ 0,035` quase desaparece no orçamento do primeiro contato. A multiplicação revela o efeito: um atendimento com dez respostas custa cerca de `R$ 0,35`, enquanto mil respostas distribuídas pela carteira de leads levam a despesa para perto de `R$ 35,00`. A leitura muda quando você abre o relatório mensal do atendimento. Com `10.000` mensagens, a simulação chega perto de `R$ 350,00`, enquanto `100.000` envios levam a despesa para aproximadamente `R$ 3.500,00` sem considerar o modelo de IA nem o servidor usado pela automação. ## O agente de IA pode conversar demais Automações de WhatsApp costumam confundir simpatia com uma sequência de respostas curtas. O agente agradece cada mensagem e repete o que acabou de receber, mas demora para registrar no CRM se o lead procura compra ou aluguel e se já existe motivo para agendar uma visita. Essa troca longa de mensagens já piorava a experiência, porque o lead precisava atravessar respostas demais para chegar ao que queria. Com a cobrança por mensagem, o mesmo defeito entra na fatura e obriga o responsável comercial a perguntar se o agente está qualificando ou apenas mantendo o atendimento ocupado. ## A imobiliária mostra a diferença entre lead e visita Na simulação, `400` dos `1.000` leads mensais fazem uma consulta inicial e encerram o atendimento depois de poucas respostas. Com uma média de oito mensagens enviadas pela imobiliária, esse grupo custa perto de `R$ 112,00` e mostra quanto se paga até mesmo pelos contatos que não chegam à visita. Outros `450` leads avançam pela triagem e recebem uma média de `24` mensagens durante o atendimento. A despesa desse grupo chega a aproximadamente `R$ 378,00`, pois o agente precisa registrar o tipo de imóvel desejado e confirmar se a faixa de preço disponível permite uma visita. Os `150` contatos restantes avançam até o agendamento e podem receber `45` mensagens para conciliar a visita ou esclarecer uma dúvida sobre financiamento. Esse grupo custa perto de `R$ 236,25` e leva a simulação mensal a `R$ 726,25` em respostas de serviço. O custo médio fica em torno de `R$ 0,73` por lead, e a leitura fica mais interessante quando a imobiliária gera `80` visitas a partir desses contatos. Nesse cenário, eu olho para um custo aproximado de `R$ 9,08` por visita e considero o número defensável quando o corretor recebe leads com intenção mais clara. ## O atendimento mais caro nem sempre é melhor Um atendimento com `8` mensagens pode custar perto de `R$ 0,28` quando o agente recebe a região e o tipo de imóvel logo no primeiro contato. A mesma tarifa leva um atendimento com `20` respostas a `R$ 0,70`, enquanto uma troca prolongada por `40` envios aproxima o custo de `R$ 1,40`. O problema não está no lead que precisa de mais explicação, porque algumas compras realmente exigem atendimento maior. A falha aparece quando o agente usa `40` mensagens para descobrir que o lead não tinha perfil, não aceitou a faixa de preço ou só queria uma informação que caberia em uma resposta mais bem escrita. ## A precificação precisa sair da mensagem isolada A tarifa da Meta entra como uma das linhas do orçamento do agente. Em outra linha entram o servidor e o uso do modelo de IA, enquanto as horas de suporte cobrem a investigação de uma execução com falha e o ajuste do prompt quando a resposta enviada não corresponde ao histórico do lead. O `stack.yaml` do n8n no Setupkit da Promovaweb usa o PostgreSQL para guardar o estado da aplicação e o Redis para coordenar a execução em modo fila. Quando uma mensagem não chega ao CRM, o responsável técnico precisa encontrar a execução no n8n e conferir se a falha ocorreu no webhook, na chamada ao modelo ou na atualização do contato. ## Como eu mediria o agente na proposta Comece pela quantidade de mensagens que a empresa envia em cada atendimento e divida a despesa mensal pelo número de visitas geradas. Depois compare esse resultado com a taxa de encaminhamento ao vendedor, pois um volume alto de respostas com poucas visitas denuncia uma triagem longa que não aproxima o lead do corretor. Separe também a cobrança da WhatsApp API do consumo do modelo de IA e das horas de manutenção do n8n. O CRM fecha a verificação ao mostrar quantos atendimentos produziram um resumo capaz de orientar a próxima ação do corretor. ## A formação liga o cálculo à rotina comercial No [Plano Martech](https://promovaweb.com/planos/martech), eu mostro como a mensagem recebida no WhatsApp percorre o n8n até atualizar o contato no CRM. O aluno consegue acompanhar o custo do atendimento e definir qual profissional revisará o fluxo quando o histórico chegar incompleto ao vendedor. O hub de [ferramentas do ecossistema Promovaweb](https://promovaweb.com/ferramentas) apresenta as aplicações usadas nessa automação e a função de cada uma. Você pode conferir as mensagens no WhatsApp, abrir a execução no n8n e verificar no CRM qual resumo o corretor recebeu. Na implantação, eu trato o atendimento como um serviço comercial apoiado por uma rotina técnica de manutenção. No [Co-work da Comunidade Promovaweb](https://promovaweb.com/comunidade), a agência pode revisar a configuração, localizar uma resposta errada e estimar o suporte mensal. ## O próximo passo é medir o atendimento que já existe Abra uma amostra de atendimentos e meça quantas respostas a empresa envia para cada tipo de lead. Ao ler o histórico, marque o ponto no qual o agente repete uma informação ou continua escrevendo mesmo depois de já ter a região procurada e a faixa de preço aceita para chamar o corretor. Essa leitura mostra quais confirmações podem sair e quais perguntas cabem na mesma resposta sem prejudicar o entendimento. Os casos com dúvida sobre o custo mensal ou sobre a responsabilidade pelo suporte podem seguir para [uma revisão comercial](https://promovaweb.com/comercial), enquanto o CRM recebe um encerramento objetivo para o lead que não tem perfil. O cálculo também orienta o desenho do agente, tema que eu aprofundo em [como deixar o custo do agente WhatsApp previsível](https://promovaweb.com/blog/agente-whatsapp-custo-previsivel). Quando a automação se tornar um serviço recorrente, a leitura sobre [quando abrir CNPJ para empresa de tecnologia](https://promovaweb.com/blog/quando-abrir-cnpj-tecnologia) amplia a análise para a formalização da atividade. O custo por mensagem fornece uma medida concreta da qualidade do atendimento. Um agente que registra o imóvel procurado e encaminha o lead no momento correto pode manter um custo defensável, enquanto uma sequência de confirmações inúteis aumenta a fatura sem gerar mais visitas. --- ## Glossário ### Abilities: as capacidades que um agente pode usar - URL: https://promovaweb.com/glossario/abilities - Descrição: Abilities são as capacidades que um agente pode usar para executar tarefas. Entenda a relação com permissões, a definição de escopo e o uso de ferramentas. ## O que são abilities Abilities são as capacidades que um [agente de IA](/glossario/agente-de-ia/) pode usar para executar tarefas. Cada ability define o que o agente consegue fazer dentro do ambiente: consultar dados, executar comandos, acessar uma aplicação. A ability é parte da configuração do agente. O ambiente decide quais capacidades estão disponíveis. Um agente com abilities de leitura pode não ter as de escrita. O escopo da capacidade orienta o que ele pode fazer. ## Capacidade e permissão A ability define o que está disponível, e a permissão controla a execução. Uma capacidade pode existir sem autorização para todas as ações que ela envolve. O [harness](/glossario/harness/) aplica os limites. O agente pode solicitar uma ação, mas a permissão define se ela acontece. Capacidade e permissão trabalham juntas: a ability oferece o caminho, e a autorização decide se o agente pode percorrê-lo.

Um agente tem a ability de enviar mensagens. Ele solicita o envio de um comunicado, mas a política do ambiente exige aprovação para ações desse tipo.

A ability oferece a capacidade, e a permissão controla a execução. O envio acontece após a aprovação. Capacidade e autorização definem juntas o que o agente faz.

## Definir o escopo das abilities As abilities devem ser definidas com escopo claro. Cada capacidade deve descrever o que faz e dentro de quais limites. Um escopo bem definido evita que o agente use uma capacidade além do pretendido. A revisão acompanha a evolução do agente. Novas capacidades podem ser adicionadas, e outras desativadas. O conjunto de abilities reflete o que o agente precisa para cumprir a tarefa sem exceder o escopo. ## Abilities e autonomia As abilities participam da [autonomia do agente](/glossario/autonomia-de-agente/). Com mais capacidades, o agente pode avançar em tarefas maiores. O equilíbrio entre capacidade e controle define quanto o agente opera sem supervisão. A combinação de abilities, permissões e instrução orienta o comportamento. O agente usa as capacidades disponíveis dentro dos limites definidos. A verificação do resultado confirma que a tarefa foi executada como esperado. Para definir as abilities do seu agente com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a configuração das capacidades e das permissões. ### Adoção: o uso real que confirma o valor do produto - URL: https://promovaweb.com/glossario/adocao - Descrição: Adoção é o uso real de uma funcionalidade ou de um produto pelos usuários. Veja como medir e distinguir do lançamento o que revela a falta de uso. ## O que é adoção Adoção é o uso real de uma funcionalidade ou de um produto pelos usuários. Ela descreve o momento no qual alguém recebe a novidade, integra o recurso à própria rotina e o usa de forma recorrente. O termo distingue dois momentos do produto. O lançamento torna a funcionalidade disponível e a adoção confirma que ela encontrou uso. Um recurso pode ser publicado, visto e, ainda assim, nunca adotado. É essa distância que o acompanhamento precisa enxergar. ## Lançar não garante adoção A capacidade de produzir avançou muito, mas a absorção pelo usuário continua em outro ritmo. Você pode publicar recursos excelentes em sequência e observar pouquíssimo uso, porque o cliente não acompanha o volume ou não enxerga a necessidade daquela novidade. Um caso típico aparece em produtos com lançamentos frequentes. Cada funcionalidade tem potencial, porém nenhuma recebe a atenção e a comunicação necessárias para virar hábito. O resultado é uma pilha de recursos disponíveis e uma base de usuários que não mudou de comportamento.

Você acompanha as métricas e percebe que cada novidade recebe acesso na primeira semana e depois desaparece. Nenhuma das três vira uso recorrente.

O problema não está na técnica. A comunicação não preparou o usuário, e o ritmo não permitiu absorver cada mudança. A falta de adoção indica que é hora de conversar antes de lançar mais.

## Medir adoção com uso real A adoção se mede pelo comportamento, não pela intenção. Você observa quantos usuários abrem a funcionalidade, com que frequência retornam e quanto tempo dedicam a ela. Essas medidas separam o acesso curioso do uso habitual. Métricas de rotas acessadas, módulos utilizados e perfis completados mostram onde o produto é ignorado. Quando três lançamentos seguidos não geram adoção, a conclusão é direta: o produto precisa de conversa e explicação, não de mais camadas. ## Adoção e percepção de valor A [percepção de valor](/glossario/percepcao-de-valor/) surge do uso. Um usuário que adota uma funcionalidade enxerga o produto trabalhando a favor dele, e essa experiência mantém a permanência. Sem adoção, o valor técnico existe, mas o cliente não o percebe. A adoção também aparece ligada ao [onboarding](/glossario/onboarding/) e ao [ciclo de lançamento](/glossario/ciclo-de-lancamento/). Uma primeira experiência clara mostra o caminho do uso, e um ritmo cadenciado dá tempo para cada novidade virar hábito. Para entender como o seu produto está sendo usado e onde a adoção falha, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a análise do comportamento de uso. ### Agente de IA: sistema que age a partir de um modelo - URL: https://promovaweb.com/glossario/agente-de-ia - Descrição: Agente de IA usa um modelo para orientar ações e acompanhar resultados. Entenda ferramentas, autonomia, permissões e condições para encerrar a tarefa. ## O que é um agente de IA Agente de IA é um sistema que utiliza um modelo para orientar ações em direção a um objetivo e considerar os resultados antes de continuar. Essas ações dependem das ferramentas e das permissões disponibilizadas pela aplicação. O termo tem usos diferentes no mercado. Para entender um produto específico, observe o que o modelo pode escolher durante a execução, quais etapas estão fixadas no código e como o sistema determina que deve encerrar o trabalho. ## Acompanhar o resultado de cada ação Num ciclo de execução, o modelo pode solicitar uma consulta, receber o retorno e selecionar o próximo passo. O resultado da ferramenta oferece informação sobre o ambiente que precisa orientar a continuação. Uma resposta em texto dizendo que um teste foi executado não substitui o resultado da execução. A aplicação deve permitir relacionar a solicitação à chamada realizada e ao retorno que efetivamente recebeu.

O agente solicita uma suíte de testes e recebe um identificador de processo em andamento. Esse retorno confirma o início, mas ainda não informa se os testes passaram.

Antes de concluir a tarefa, o agente precisa acompanhar o processo e examinar o resultado final. Reiniciar a suíte ou declarar sucesso apenas com o identificador não responde ao objetivo de verificar o código.

## Autonomia não amplia permissões A possibilidade de escolher o próximo passo não autoriza ações fora do escopo. Um agente preparado para ler arquivos pode precisar de outra permissão para editá-los ou executar comandos. Essas restrições devem ser aplicadas pelo ambiente e pela implementação das ferramentas. Instruções em texto ajudam a comunicar a tarefa, mas não substituem a verificação que impede uma chamada indevida. ## Definir condições de encerramento O sistema precisa reconhecer quando o resultado solicitado foi verificado e quando uma tentativa não pode continuar. Limites de duração, chamadas ou consumo ajudam a controlar execuções que repetem ações sem produzir informação nova. Atingir um limite não significa completar a tarefa. O retorno deve indicar o que foi feito, qual resultado foi confirmado e qual parte permanece incompleta, permitindo uma continuação coerente. ## Avaliar o caminho e o resultado Uma interface de chat pode abrigar esse ciclo, enquanto outra aplicação pode executar o agente sem conversa contínua. O formato da interface não determina, sozinho, a autonomia ou o alcance das ferramentas. Para revisar um agente que repete chamadas ou encerra tarefas sem conferência, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite examinar o fluxo com orientação ao vivo. A investigação pode relacionar objetivo, chamadas e resultados registrados pela aplicação. ### Alerta: aviso sobre uma condição monitorada - URL: https://promovaweb.com/glossario/alerta - Descrição: Alerta sinaliza uma condição monitorada. Entenda avaliação, tempo de espera, envio de notificações e como testar falha, ausência de coleta e recuperação. ## O que é um alerta Alerta é uma sinalização de que uma condição acompanhada pelo monitoramento foi atendida. Ele pode indicar aumento de falhas, falta de espaço ou ausência de uma coleta esperada, conforme a configuração usada pelo sistema. O aviso recebido por email ou outro canal faz parte do percurso de notificação. Você precisa conferir tanto a condição avaliada quanto o envio, porque um alerta pode estar ativo no painel sem que a mensagem tenha chegado ao destino. ## A condição precisa dizer o que está sendo observado Uma condição pode comparar uma medida com um limite e exigir que ela permaneça assim por determinado tempo. No Prometheus, a duração configurada com for mantém o alerta pendente até que a condição continue atendida nas avaliações durante esse período. O intervalo usado para calcular a medida é outra configuração. Uma taxa calculada sobre cinco minutos e uma espera de dez minutos para ativar o alerta descrevem duas janelas diferentes, que influenciam o momento do aviso.

A condição permanece acima do limite pelo tempo configurado, e o painel mostra o alerta ativo. O canal de notificação usa uma credencial expirada e recusa o envio.

A avaliação funcionou, mas a comunicação falhou. O teste precisa conferir a chegada da mensagem e o erro do canal, em vez de considerar o estado ativo suficiente para concluir que o aviso foi recebido.

## Agrupamento e silenciamento alteram o envio Ferramentas como o Alertmanager podem agrupar ocorrências relacionadas, encaminhá-las a destinos diferentes ou silenciar notificações. Essas configurações evitam mensagens repetidas, mas precisam corresponder ao serviço e ao período pretendidos. Um silenciamento esquecido pode esconder avisos depois da manutenção. Registre seu alcance e sua duração e confira o retorno das notificações, sem interpretar a ausência de mensagens como recuperação automática da aplicação. ## Escolher limite e duração exige observar o serviço Um limite muito próximo da variação habitual pode produzir avisos frequentes sem uma ação útil. Uma espera longa demais pode adiar o conhecimento de uma interrupção que precisa de atendimento rápido. Compare a condição com o comportamento observado e com a consequência para a tarefa atendida. O objetivo é permitir uma ação definida, como investigar a fila ou conferir a comunicação com o banco, e não gerar um aviso para toda oscilação numérica. ## Falta de informação também exige tratamento Uma coleta interrompida pode deixar a consulta sem amostras para avaliar. Dependendo da ferramenta, essa situação tem um estado próprio ou exige uma condição adicional, portanto não presuma que ela será tratada como valor zero. Teste o comportamento diante de ausência de coleta e de erro na consulta. O sistema de monitoramento também pode falhar, e essa possibilidade precisa ficar visível no percurso de acompanhamento. ## Conferir falha e recuperação Simule uma condição controlada, acompanhe a avaliação e verifique a mensagem no destino previsto. Confira se o aviso identifica o serviço, o período e o que observar primeiro, sem expor credenciais ou informações desnecessárias. Depois de recuperar a condição, observe a mudança de estado e a notificação de resolução, quando configurada. Para revisar alertas e cobertura de monitoramento ao longo do projeto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode oferecer acompanhamento técnico recorrente. ### Alucinação: resposta plausível sem apoio nas informações - URL: https://promovaweb.com/glossario/alucinacao - Descrição: Alucinação é uma saída de IA incorreta ou sem apoio suficiente. Entenda referências inventadas, limites das fontes e formas de conferir antes de usar. ## O que é alucinação em IA Alucinação é uma saída gerada que apresenta informação incorreta ou sem apoio suficiente como se fosse adequada à tarefa. Ela pode incluir uma referência inventada, uma relação inexistente ou uma afirmação que contradiz o material fornecido. O uso do termo varia entre pesquisas e produtos, mas a verificação precisa examinar o erro concreto. Uma resposta sem citação não é automaticamente falsa, assim como uma resposta acompanhada de links não é automaticamente correta. ## A aparência de certeza não confirma o fato Um modelo pode produzir uma explicação detalhada para uma função que não está disponível na biblioteca utilizada. A qualidade da redação não demonstra que o nome ou o comportamento descrito foi conferido. Também não é necessário atribuir intenção humana ao erro. O problema operacional é a aplicação aceitar a informação como válida sem uma verificação correspondente ao uso que fará dela.

O assistente recomenda uma opção de configuração e inclui um link real para o manual. Ao abrir a página, você encontra o assunto geral, mas nenhuma menção à opção recomendada.

O endereço correto não confirma a orientação específica. A investigação precisa procurar a opção na documentação da versão utilizada e testar sua existência antes de alterar o projeto.

## Investigar o material que chegou ao modelo Uma fonte ausente, um trecho incompleto ou uma versão incorreta podem contribuir para a resposta inadequada. Confira a entrada efetiva antes de concluir que a falha seria resolvida apenas mudando a instrução. No [grounding](/glossario/grounding/), a resposta deve manter vínculo com informações verificáveis. Mesmo assim, o modelo pode omitir uma condição ou extrapolar o trecho, e a própria fonte pode estar desatualizada. ## Permitir reconhecer informação insuficiente Uma tarefa pode instruir o modelo a indicar quando o material não permite concluir o que foi solicitado. Essa alternativa evita exigir uma resposta específica em todos os casos, mas seu funcionamento ainda precisa ser avaliado. Inclua perguntas que a base não consegue responder e observe se a aplicação reconhece a ausência. Repetir somente perguntas com resposta disponível deixa esse comportamento sem conferência. ## Verificar conforme o uso da resposta Para código, confira nomes e versões e execute o cenário relevante num ambiente preparado. Para uma afirmação documental, abra a fonte e compare o trecho com a orientação produzida. Para investigar sugestões incorretas num assistente de programação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite revisar o código e as referências com orientação ao vivo. A sessão pode transformar a afirmação em uma verificação concreta no projeto. ### Ambiente local: onde o projeto roda durante o desenvolvimento - URL: https://promovaweb.com/glossario/ambiente-local - Descrição: Ambiente local reúne ferramentas e serviços usados no desenvolvimento. Entenda configuração, localhost, containers e diferenças em relação à produção. ## O conjunto usado durante o desenvolvimento Ambiente local é o conjunto de código, ferramentas, dependências e serviços que você utiliza na sua máquina para desenvolver uma aplicação. Ele pode incluir runtime, banco, servidor de desenvolvimento e arquivos de configuração. A composição depende do projeto. Alguns componentes podem executar em containers, e outros podem ser acessados remotamente. Nesse caso, a experiência de desenvolvimento combina recursos locais e externos. A existência de uma página aberta em `localhost` não comprova que todas as operações ficam no computador. Antes de testar um cadastro, confira quais serviços a aplicação utiliza. Um formulário local pode enviar uma chamada para uma API real se estiver configurado com esse destino. Separar ambientes também exige conferir endereços e credenciais. ## Iniciar o projeto conforme sua configuração Esse comando executa o script `dev` definido no `package.json` do projeto. Confira o conteúdo desse script para identificar a ferramenta iniciada e siga a documentação de instalação, configuração e serviços auxiliares. O nome `dev`, sozinho, não informa se o comando inicia apenas a interface ou também outros processos. Um servidor de desenvolvimento pode observar arquivos e atualizar a página após alterações, conforme a ferramenta utilizada. Quando você muda uma configuração que só é lida na inicialização, pode precisar reiniciar o processo para conferir seu efeito. Compare o comportamento observado com a forma de atualização documentada para aquele arquivo.

Você modifica o texto de um campo e confere o resultado no navegador local. Depois, envia um cadastro fictício e observa a chamada ao serviço de testes. A alteração pode ser examinada antes de entrar no site público.

Também é necessário executar as verificações do projeto. A página aparecer corretamente no modo de desenvolvimento não comprova que o build de produção terminará sem erros.

## Localhost no navegador e no container `localhost` representa o próprio ambiente de rede do processo que o utiliza. No navegador do computador, costuma apontar para esse computador. Dentro de um container, normalmente aponta para o próprio container, e não automaticamente para o host. Por isso, um endereço que funciona no navegador pode falhar quando usado pelo backend em container. Confira a rede, o nome do serviço e a publicação de portas. A documentação da ferramenta define a forma de comunicação entre esses ambientes. ## Aproximar o desenvolvimento do destino Versões de runtime, extensões e bibliotecas podem mudar o comportamento. Um arquivo de lock e a declaração das versões ajudam a reproduzir a instalação. Serviços externos também precisam ter configurações compatíveis com os testes pretendidos. Diferenças de sistema operacional podem afetar caminhos, permissões e distinção entre maiúsculas e minúsculas nos nomes de arquivos. Uma importação que funciona em um computador pode falhar em outro. O build e os testes devem contemplar o ambiente de publicação quando isso for relevante. ## Como conferir o ambiente Siga os comandos documentados a partir do diretório correto. Verifique versões, parâmetros obrigatórios e serviços em execução, usando valores fictícios nos testes. Quando houver falha, compare o ambiente efetivo com o esperado pelo projeto. O verbete de [configuração](/glossario/configuracao/) explica como os endereços e limites utilizados pela aplicação podem variar entre os ambientes. ### API: contrato de comunicação entre sistemas - URL: https://promovaweb.com/glossario/api - Descrição: A API define como um programa utiliza funções de outro. Entenda o contrato de comunicação, acompanhe o exemplo de cadastro e confira respostas recebidas. ## O que uma API permite fazer A API (Application Programming Interface, ou interface de programação de aplicações) define como um programa pode utilizar funções de outro. Ela descreve quais ações estão disponíveis e como o programa deve chamar cada uma. Existem APIs de bibliotecas, de sistemas operacionais e de serviços acessados pela internet. Imagine um formulário que envia um novo contato para um sistema de atendimento. A API desse sistema pode oferecer uma função de cadastro que exige nome e email. Você configura a integração conforme a documentação, envia os campos no formato esperado e interpreta a resposta para saber se o cadastro foi aceito. Nesse exemplo, um email obrigatório ausente pode causar a recusa do cadastro. A mensagem devolvida depende da implementação: algumas APIs identificam o campo que precisa de correção, outras retornam uma explicação genérica. Por isso, testar a integração inclui conferir um cadastro válido e observar o comportamento quando falta uma informação obrigatória. ## Como funciona o contrato de uma API web O contrato é a descrição do comportamento que a integração pode esperar. Nas APIs que usam HTTP (Hypertext Transfer Protocol), o programa cliente envia uma requisição ao servidor e recebe uma resposta. O método informa a ação pretendida: `GET` costuma ser usado para consultar um recurso, e `POST` pode enviar um cadastro para processamento. O endereço de acesso, chamado de endpoint, identifica onde a requisição será recebida. Copiar esse endereço para a integração ainda deixa parte da configuração em aberto. A documentação precisa informar, por exemplo, se o nome do contato deve ser enviado no campo `name` ou no campo `nome`. Dois campos com o mesmo significado para você podem ser nomes diferentes para o programa que recebe a requisição. O contrato também define o formato da mensagem, e o JSON (JavaScript Object Notation) é uma possibilidade comum para representar campos e valores. Uma API pode aceitar outros formatos, por isso a integração precisa seguir o formato documentado pelo serviço. Quando o serviço exige uma credencial, a documentação informa como enviá-la junto da requisição. Conhecer o endereço do serviço não concede permissão para consultar ou alterar os registros. ## API, backend e implementação O backend é a parte da aplicação que executa a lógica no servidor. No exemplo do formulário, ele pode validar o email e gravar o contato no banco. A API define a forma de acessar essa função, permitindo que o formulário use o cadastro sem conhecer as tabelas ou o código que faz a gravação. Uma alteração interna pode preservar a integração quando mantém o contrato. Trocar a tabela usada para gravar os contatos, por exemplo, não exige necessariamente mudar o formulário. Já remover o campo `name` e aceitar somente `nome` exige adaptar as integrações que ainda enviam o nome antigo. Atualizar a documentação explica a mudança, mas o código de cada integração também precisa ser compatível. ## Exemplo de cadastro e leitura da resposta

Considere uma API que aceita nome e email e devolve um identificador após gravar o contato. Ao testar o formulário, você envia um cadastro fictício e recebe o código 201, acompanhado do identificador 845. Esse código indica que um recurso foi criado. O identificador permite consultar o contato e conferir se o nome e o email foram gravados como esperado.

Agora, repita o teste no ambiente de desenvolvimento com o email vazio. Nesse exemplo, a API exige o email e deve recusar a criação. Você confere a resposta recebida e verifica se o formulário mostra uma orientação para corrigir o campo. Exibir uma confirmação de cadastro apesar dessa recusa esconderia a falha do visitante.

O código `202 Accepted` tem outro significado: o servidor aceitou a requisição, mas o processamento pode continuar depois da resposta, como acontece em algumas importações de contatos. Nesse caso, você consulta o acompanhamento previsto pelo serviço para descobrir se a importação terminou ou encontrou erros, pois a aceitação inicial não confirma a criação de todos os contatos. ## O que conferir quando a integração falha Compare a requisição enviada com a chamada descrita na documentação do serviço. Confira o endereço, o método e os nomes dos campos obrigatórios. Quando houver autenticação, verifique se a credencial continua válida e tem permissão para cadastrar. Leia o código de status junto com o conteúdo da resposta, pois um servidor pode responder e informar que o cadastro foi recusado. Quando a resposta indicar sucesso, confira também o resultado esperado no sistema de destino, especialmente quando houver processamento posterior. Testar com um contato fictício em ambiente de desenvolvimento permite observar esses comportamentos sem alterar cadastros de clientes. Para examinar a mensagem que a integração envia ao servidor, consulte a explicação sobre [a requisição que chama uma API](/glossario/requisicao/). ### Artefato: resultado do processo de build - URL: https://promovaweb.com/glossario/artefato - Descrição: Artefato é uma saída armazenável do desenvolvimento. Veja como identificar pacotes e imagens, conferir sua origem e preservar versões para deploy. ## O que é um artefato Artefato é uma saída produzida durante o desenvolvimento ou a entrega de software que pode ser armazenada e utilizada depois. Uma imagem de container, um pacote de instalação e um relatório de testes são exemplos, embora tenham finalidades diferentes. No fluxo de publicação, o termo costuma indicar o resultado que será instalado no ambiente. Você precisa identificar qual artefato contém a aplicação e quais arquivos apenas registram as verificações feitas durante sua preparação. ## A saída precisa estar associada à origem O nome de um arquivo não informa, sozinho, como ele foi produzido. Para relacionar um pacote à alteração esperada, o processo pode registrar o commit, a execução do build e as versões das dependências utilizadas. Essas informações ajudam a investigar uma diferença entre o código revisado e o serviço instalado. Sem essa associação, dois arquivos chamados aplicação-final podem representar construções diferentes, e escolher pelo nome ou pelo horário do download pode levar ao resultado errado.

O build gera o pacote da versão 1.4.0, que é armazenado com um identificador de conteúdo. O ambiente de staging recebe esse pacote e executa a conferência do cadastro.

Depois da validação, a produção recebe o mesmo pacote armazenado. Refazer o build com dependências diferentes produziria outro resultado e exigiria conferir se a nova saída ainda corresponde à versão testada.

## Nome de versão e identidade do conteúdo Uma versão ou tag facilita a comunicação, mas é preciso conferir se o armazenamento permite substituir o conteúdo associado a esse nome. No caso de imagens, atualizar uma tag mutável pode associar o mesmo nome a outra imagem, enquanto o digest identifica o conteúdo correspondente. Compare a referência obtida no destino com aquela registrada durante a validação. Um nome igual não é suficiente quando a ferramenta permite substituí-lo, e a conferência de integridade também não prova, sozinha, que o software veio de uma origem confiável. ## Relacione o relatório à versão testada Um relatório pode mostrar quais testes falharam e ajudar a reproduzir o problema. Para ser útil, ele precisa estar associado à execução e à versão testada, sem ser confundido com o pacote que será instalado. Também confira o conteúdo antes de disponibilizá-lo. Logs e relatórios podem conter campos recebidos durante os testes, por isso o armazenamento e as permissões precisam corresponder ao que esses arquivos expõem. ## Retenção e recuperação de versões O armazenamento pode remover artefatos depois de um prazo ou de uma limpeza. Se a recuperação depende de reinstalar a versão anterior, esse resultado precisa continuar acessível junto das informações necessárias à sua execução. O cache do build atende a outra finalidade e pode ser descartado. Usá-lo como único lugar para recuperar uma release torna a publicação dependente de arquivos que o próprio processo pode apagar para economizar espaço. ## Identidade e conteúdo do artefato recebido Baixe o resultado pelo caminho que o ambiente usará, confira sua identidade e verifique se ele contém os arquivos esperados. Execute as verificações compatíveis com sua finalidade, pois abrir um relatório e iniciar uma aplicação comprovam coisas diferentes. O [deploy](/glossario/deploy/) deve registrar qual resultado foi instalado para permitir comparação posterior. Para revisar a preparação e o uso desses pacotes com acompanhamento ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode atender uma tarefa delimitada do seu processo de publicação. ### Atomicidade: todas as alterações ou nenhuma - URL: https://promovaweb.com/glossario/atomicidade - Descrição: Atomicidade permite confirmar ou cancelar alterações como uma unidade. Entenda o escopo da transação, os limites da garantia e um exemplo de rollback. ## Confirmar o conjunto ou cancelar suas alterações Atomicidade é a propriedade transacional que permite tratar um conjunto de alterações como uma unidade. Dentro do escopo coberto pela transação, a confirmação mantém o conjunto, e o cancelamento desfaz suas alterações transacionais. O bloco não deve terminar com apenas uma parte desse conjunto confirmada. Imagine uma rotina que cria uma turma e exige registrar sua primeira matrícula no mesmo procedimento. Se a matrícula for recusada, manter a turma criada por essa tentativa deixaria o cadastro incompleto. Agrupar as duas gravações permite cancelar a criação da turma junto com a tentativa de matrícula. A garantia depende de as etapas participarem da mesma transação e de o código tratar o caminho de falha corretamente. Gravações realizadas por conexões separadas ou já confirmadas não entram automaticamente nesse mesmo grupo. ## Um exemplo de cancelamento O exemplo pressupõe tabelas compatíveis, o estudante 7 existente e o identificador 10 disponível para a turma. Ele executa `ROLLBACK` para mostrar o efeito do cancelamento. Ao final, a turma e a matrícula criadas dentro desse bloco não devem permanecer como alterações confirmadas.

A primeira gravação funciona, mas a segunda recebe um valor inválido e é recusada. A aplicação encerra a transação pelo caminho de cancelamento. A turma criada nesse conjunto não deve ficar sozinha no banco.

Se o código confirmar a primeira etapa antes de iniciar a segunda, o agrupamento já foi perdido. Um rollback posterior não desfaz automaticamente a confirmação anterior.

## Atomicidade não significa simultaneidade física Os comandos podem executar em sequência e consumir tempo. A propriedade descreve a confirmação ou o cancelamento da unidade, não a execução de todas as instruções no mesmo instante. O banco utiliza mecanismos internos para oferecer essa garantia. A visibilidade entre transações também envolve isolamento. Duas consultas feitas dentro da mesma transação podem ou não enxergar uma alteração confirmada por outra entre elas, dependendo do nível de isolamento. Agrupar as gravações para confirmação conjunta não define, sozinho, o que cada consulta consegue ler. ## O limite da unidade transacional Um email enviado e uma chamada a uma API externa não são desfeitos pelo rollback do banco. Se a rotina executa esses efeitos antes da confirmação, eles podem permanecer mesmo após o cancelamento das gravações. A aplicação precisa coordenar esse trabalho adicional. Nem todo efeito interno volta ao valor anterior. No PostgreSQL, valores consumidos de sequências podem deixar lacunas após uma transação cancelada. Isso não significa que uma linha parcialmente confirmada tenha permanecido. ## Como conferir a garantia Em desenvolvimento, provoque uma falha após uma gravação inicial e consulte o resultado depois de encerrar a transação. Confira todas as tabelas envolvidas, a conexão utilizada e a ausência de confirmações intermediárias. Compare os registros, sem exigir que contadores técnicos nunca avancem. O verbete de [transação](/glossario/transacao/) explica como delimitar a unidade e separar suas garantias dos efeitos externos. ### Áudio bidirecional: conversar com a IA em dois sentidos - URL: https://promovaweb.com/glossario/audio-bidirecional - Descrição: Áudio bidirecional permite conversar com a IA em dois sentidos. Entenda entrada de voz, resposta falada, interrupção e a verificação do que foi dito. ## O que é áudio bidirecional Áudio bidirecional é a capacidade de conversar com a IA em dois sentidos: o usuário fala, e a IA responde em áudio. O formato aproxima a interação de uma conversa entre pessoas, com entrada falada e resposta falada no mesmo fluxo. Esse formato vai além de reproduzir uma resposta pronta. A IA recebe a fala do usuário, interpreta e devolve em voz. A conversa pode continuar com novas perguntas, transformando a interface em uma troca natural. ## Ouvir e responder A entrada falada é convertida em texto ou processada diretamente, e a resposta é gerada em áudio. A qualidade da conversa depende do reconhecimento da fala, da resposta do modelo e da síntese da voz. Ruído, sotaque e contexto podem mudar o que foi entendido. A aplicação deve permitir confirmar e corrigir a interpretação. Uma conversa que entende errado sem oferecer correção pode levar a um resultado equivocado.

O usuário fala o que precisa ser feito em uma reunião. O assistente reconhece a fala e responde em áudio com o resumo do que entendeu.

Se o reconhecimento falhar, o usuário pode corrigir. A conversa continua até a tarefa ser entendida corretamente e registrada.

## Interação e latência A conversa por voz depende de resposta rápida. O usuário espera ouvir a resposta sem longas pausas. A latência entre falar, processar e ouvir influencia a naturalidade da interação. O formato também permite interrupção. O usuário pode falar enquanto a IA responde, e o sistema precisa lidar com a sobreposição. O comportamento varia conforme a implementação da aplicação. ## Voz e texto juntos A voz não precisa substituir o texto. O registro escrito continua útil para revisar, compartilhar e arquivar. Um produto pode oferecer a conversa por voz e manter o histórico em texto para consulta. O uso da voz faz sentido quando a interação falada melhora a experiência: mãos ocupadas, leitura de conteúdo ou a naturalidade da conversa. A escolha depende do produto e de quem usa. Para integrar conversa por voz ao seu fluxo com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a implementação da entrada e da resposta em áudio. ### Autenticação: verificação da identidade antes do acesso - URL: https://promovaweb.com/glossario/autenticacao - Descrição: Autenticação verifica uma identidade por suas credenciais. Entenda login, sessões, múltiplos fatores e por que autenticar não concede todas as permissões. ## Definição Autenticação é a verificação de uma identidade apresentada a um sistema por meio de credenciais ou outras comprovações. No login de uma aplicação, ela associa o acesso ao perfil autenticado, sem conceder automaticamente todas as ações disponíveis. O mecanismo valida a comprovação aceita pelo serviço. Isso não confirma a identidade civil do titular, e uma credencial obtida indevidamente pode permitir que terceiros se apresentem como responsáveis pelo acesso. ## Além da tela de login Uma senha é uma forma conhecida de autenticação, mas programas também podem apresentar chaves ou certificados. O tipo de cliente e os recursos acessados influenciam a escolha do mecanismo e a maneira de guardar suas credenciais. A autenticação multifator combina categorias diferentes de comprovação. Solicitar duas senhas continua dependendo de algo que você sabe, enquanto combinar senha e um dispositivo autenticador acrescenta outra categoria. ## O que acontece depois de entrar Muitas aplicações criam uma [sessão](/glossario/sessao/) após o login e usam sua identificação nas chamadas seguintes. Outras validam tokens ou credenciais em cada requisição, sem exigir que você preencha novamente a tela de login. Expiração e revogação fazem parte desse ciclo. Uma tela que continua aberta pode conter informações já carregadas, mas isso não comprova que o servidor aceitará a próxima operação protegida.

O navegador ainda exibe os campos, mas a sessão usada para acessar o serviço expirou. Ao enviar o formulário, a aplicação precisa reconhecer a resposta do servidor e solicitar nova autenticação.

Manter o botão visível não mantém a sessão válida. A aplicação precisa tratar a interrupção e informar o que aconteceu, sem apresentar o envio como concluído.

## Identidade e permissão precisam ser conferidas Depois de validar as credenciais, a aplicação ainda verifica a [autorização](/glossario/autorizacao/) para a ação solicitada. Você pode consultar seu próprio projeto e não ter permissão para alterar projetos de outra organização. Conteúdo público pode admitir acesso anônimo de propósito. Uma página de apresentação pode abrir normalmente para visitantes, enquanto a edição de um cadastro exige identidade autenticada. Os testes precisam distinguir esses acessos para verificar a proteção prevista em cada recurso. Se precisar revisar login, sessão e tratamento de acesso no seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar esses comportamentos com acompanhamento técnico. ### Autonomia de agente: o alcance das ações sem supervisão - URL: https://promovaweb.com/glossario/autonomia-de-agente - Descrição: Autonomia de agente descreve o quanto um agente decide e executa sem supervisão. Veja o papel das ferramentas e da instrução no controle da execução. ## O que é autonomia de agente Autonomia de agente descreve o quanto um [agente de IA](/glossario/agente-de-ia/) decide e executa sem supervisão. Um modelo pode apenas responder, ou pode escolher ferramentas, executar passos e seguir até o objetivo com pouca intervenção. O termo define um espectro, não uma chave ligada ou desligada. Em um extremo, o agente espera cada instrução. No outro, ele recebe a meta e conclui tarefas adjacentes por iniciativa própria. O [harness](/glossario/harness/) e as permissões do ambiente determinam o ponto onde a execução fica nesse espectro. ## A autonomia varia entre ferramentas Modelos diferentes tratam a mesma instrução de formas distintas. Um agente mais proativo percebe nuances não descritas e executa etapas adicionais. Um agente mais contido aguarda instrução clara e não avança quando a especificação fica incompleta. Essa diferença não é qualidade nem defeito em si. Ela define qual modelo combina com o fluxo de cada usuário: aquele que prefere delegar e se afastar se ajusta melhor a um agente autônomo, enquanto o que quer acompanhar cada passo escolhe a condução passo a passo.

Você solicita a revisão de uma tela e informa apenas o comportamento esperado. Um agente proativo corrige o layout e o texto de apoio, enquanto outro aplica somente a mudança descrita e aguarda o próximo passo.

A autonomia explica a diferença. O usuário que acompanha a execução pode preferir o agente contido, enquanto o que delega espera que o trabalho adicional seja feito por iniciativa do modelo.

## Autonomia não amplia permissões O poder de escolher o próximo passo não autoriza ações fora do escopo. Um agente que lê arquivos pode precisar de permissão para editá-los ou executar comandos. Essas restrições são aplicadas pelo ambiente e pela implementação das ferramentas. Instruções em texto comunicam a tarefa, mas não substituem a verificação que impede uma chamada indevida. A autonomia decide a forma de executar e as permissões decidem o que pode ser executado. ## Escolher o nível conforme a tarefa Você ajusta a autonomia pela instrução, pelo escopo e pelos pontos de aprovação. Uma tarefa bem definida favorece um agente que avança com confiança, enquanto um trabalho sensível exige conferência em cada etapa. O controle existe nos dois perfis, por meios diferentes: no agente contido, a falta de instrução interrompe a execução, enquanto no proativo a iniciativa pode executar etapas além do solicitado. Para desenhar um agente com a autonomia adequada ao seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite acompanhar o comportamento do modelo com orientação ao vivo. ### Autorização: o que uma identidade pode fazer - URL: https://promovaweb.com/glossario/autorizacao - Descrição: Autorização verifica as ações permitidas sobre um recurso do sistema. Veja permissões por projeto, controles no servidor e a diferença em relação ao login. ## Definição Autorização é a verificação de quais ações são permitidas sobre determinado recurso. Para autorizar a edição de um projeto, por exemplo, a aplicação pode exigir uma identidade autenticada com o papel de editor e um vínculo com aquele projeto. Uma política também pode permitir acesso anônimo, como a leitura de uma página pública. Para operações protegidas, reconhecer a identidade pela [autenticação](/glossario/autenticacao/) é uma etapa distinta de conferir o que ela pode fazer. ## A permissão inclui o recurso A permissão para editar precisa delimitar os projetos acessíveis ao perfil autenticado. Verificar somente o papel de editor pode permitir uma alteração sobre um registro de outra organização, mesmo que a aplicação pretendesse restringir a edição aos projetos vinculados. O servidor deve relacionar a identidade validada ao recurso solicitado. Aceitar como prova de identidade um campo livre enviado pelo cliente permitiria que a própria chamada escolhesse a identidade usada na operação.

Ana envia uma alteração com o identificador do projeto Beta. Embora tenha o papel de editora, seu perfil está vinculado apenas ao projeto Alfa.

O servidor precisa recusar a alteração e preservar o projeto Beta. O papel de editor e a existência do projeto são insuficientes nesse caso, pois falta o vínculo exigido para o acesso.

## A interface apresenta as ações permitidas Ocultar ações indisponíveis informa o que você pode fazer na tela. A API correspondente também precisa aplicar a autorização no [backend](/glossario/backend/), pois outra chamada pode chegar diretamente ao serviço. A verificação deve alcançar cada caminho que realiza a ação, inclusive integrações e tarefas executadas por serviços. Uma segunda entrada que grava o mesmo recurso sem conferir a permissão pode contornar o controle aplicado na tela principal. ## Verificar mudanças de permissão Remover o vínculo de Ana com o projeto Alfa precisa repercutir no acesso conforme o mecanismo definido pela aplicação. Se as permissões estiverem copiadas em um token ainda aceito, a mudança pode depender de expiração, revogação ou outra consulta prevista no desenho do sistema. Nos testes do seu ambiente, compare leitura e alteração sobre recursos próprios e de outra organização, usando perfis preparados para isso. Confira também que uma chamada recusada não modificou o registro, pois a mensagem exibida não comprova esse resultado. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar a revisão dessas verificações no código, relacionando os papéis da aplicação aos recursos efetivamente acessados. ### Avaliação de IA: o que é um eval - URL: https://promovaweb.com/glossario/avaliacao-de-ia-eval - Descrição: Eval examina o comportamento de uma aplicação de IA com casos definidos. Entenda resultados esperados, formas de avaliação e limites de médias e amostras. ## O que é um eval Eval, abreviação de evaluation, é um procedimento para examinar o comportamento de um modelo ou de uma aplicação de IA com casos e condições definidos. A comparação utiliza respostas registradas e verificações que podem ser repetidas ao avaliar outra versão. O alcance pode incluir uma resposta isolada ou um fluxo com busca e ferramentas. Declare qual parte está sendo avaliada para evitar atribuir ao modelo uma falha causada pela recuperação ou considerar a aplicação inteira aprovada por um teste restrito. ## Definir o resultado antes de medir Uma tarefa de classificação pode ter categorias esperadas por caso. Já uma explicação em linguagem natural pode aceitar várias formulações, desde que preserve as informações necessárias e não acrescente afirmações incompatíveis. A forma de avaliação deve refletir essa diferença. Comparar textos literalmente pode reprovar uma resposta correta com outras palavras, enquanto verificar apenas o formato pode aceitar uma classificação errada.

O documento informa uma data de criação e outra de entrega, e a tarefa solicita a data de entrega. O modelo devolve a data de criação num JSON bem formado, usando o campo esperado.

A validação estrutural passa, mas o caso falha na extração da informação solicitada. O relatório precisa separar essas duas verificações para mostrar qual comportamento exige correção.

## Escolher casos que representem o uso Inclua entradas comuns e situações que possam mudar o resultado, como descrições incompletas ou categorias próximas. Casos sem informação suficiente também ajudam a conferir quando a aplicação deve solicitar esclarecimento. Reserve exemplos que não foram usados para ajustar continuamente a instrução. Acertar apenas o conjunto observado durante os ajustes pode esconder uma adaptação excessiva àquelas entradas. ## Conferir o avaliador e a variação Algumas verificações podem ser feitas por código, enquanto outras exigem leitura humana ou avaliação por outro modelo. Um avaliador automático precisa ser conferido com exemplos conhecidos para mostrar quais diferenças ele identifica e quais deixa passar. Resultados também podem variar entre execuções. Registre a versão do modelo, a instrução e as condições da chamada, e repita os casos necessários para entender se uma diferença é consistente. ## Examinar falhas além da média Um resultado agregado pode esconder erros recorrentes num grupo de perguntas. Leia as divergências e considere o efeito de cada falha na aplicação antes de aceitar uma alteração apenas porque a média aumentou. Para construir avaliações de um assistente usado no desenvolvimento, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a preparação dos cenários. A sessão pode relacionar os resultados esperados às verificações executadas no projeto. ### Backend: a lógica e os registros do sistema - URL: https://promovaweb.com/glossario/backend - Descrição: Backend executa a lógica da aplicação no lado do servidor, mesmo sem tela aberta. Entenda validação, permissões e a relação com API e banco de dados. ## A lógica executada no servidor Backend é a parte da aplicação que executa funções no servidor, como conferir permissões, validar cadastros e acessar registros. Ele pode atender à interface, servir integrações e executar tarefas sem uma tela aberta. A organização depende do produto e das funções oferecidas. Imagine um sistema de contatos que permite editar apenas os registros da sua organização. O frontend apresenta o formulário, mas o backend precisa relacionar o perfil autenticado à organização proprietária do contato antes de gravar a alteração. Receber o identificador de um contato não comprova que aquele perfil pode modificá-lo. O backend também pode trabalhar fora de uma requisição imediata. Uma rotina agendada pode enviar lembretes, e um worker pode processar uma importação recebida anteriormente. Essas tarefas pertencem à aplicação mesmo quando o navegador já foi fechado. ## O que acontece em um cadastro Um cadastro costuma começar pela leitura e validação dos campos. O backend confere se as informações exigidas estão presentes e se os valores atendem aos formatos e limites previstos. Quando a função exige autenticação, ele também identifica o perfil e verifica suas permissões. Depois dessas verificações, o código pode gravar o registro e montar a resposta. Se várias gravações precisam acontecer juntas, uma transação pode reunir essas alterações no banco. A escolha depende do comportamento esperado quando alguma etapa falha.

Você envia nome e email pelo formulário. O backend identifica sua organização pela sessão autenticada e cria o contato com esse vínculo. A resposta inclui o identificador necessário para abrir o cadastro.

Em um teste separado, um perfil de outra organização tenta alterar esse contato. O backend deve conferir a permissão e recusar o acesso ao registro. A ausência do botão na interface daquele perfil não substitui a verificação no servidor.

A validação precisa considerar também o conteúdo já armazenado. Um email com formato correto pode pertencer a outro cadastro, e a aplicação pode exigir exclusividade desse endereço. Essa condição precisa ser tratada durante a gravação para contemplar chamadas simultâneas que tentam cadastrar o mesmo email. ## Backend, API, banco e servidor A API define como outros programas acessam funções oferecidas pelo backend. O backend implementa essas funções e devolve os resultados previstos no contrato, como um identificador após a criação de um contato ou uma resposta de recusa para um email já cadastrado. O banco armazena e consulta registros, enquanto o código da aplicação coordena as operações do produto. Parte das garantias também pode estar no banco, como uma restrição de unicidade. Backend e banco são componentes relacionados, com responsabilidades que precisam ser explícitas. Servidor pode indicar o processo que atende à comunicação ou a máquina que hospeda o software. Uma única aplicação pode executar em diversos processos e máquinas. A quantidade de servidores não define, por si só, como a lógica do backend está organizada. ## Integrações e processamento posterior Ao chamar um serviço externo, o backend atua como cliente daquela API. Ele pode usar uma credencial mantida no ambiente do servidor, sem incluí-la nos arquivos enviados ao navegador. Se a integração falhar, o tratamento depende da operação e das possibilidades de nova tentativa. Considere um contato já gravado quando a conexão com o navegador é interrompida. O cadastro existe, mas a interface não recebeu a confirmação. Repetir a chamada pode duplicar o registro se o backend não reconhecer a tentativa anterior. ## Como verificar o comportamento Em desenvolvimento, teste uma entrada válida, uma entrada recusada e um perfil sem a permissão necessária. Confira a resposta e as alterações no banco. Para tarefas posteriores, acompanhe também o resultado do processamento, pois aceitar uma chamada não significa concluir todas as etapas. Organizar o código por responsabilidades facilita localizar essas verificações, mas a separação sozinha não garante que uma mudança preserve o comportamento. Um teste de integração pode tentar o cadastro com email repetido e conferir tanto a recusa quanto a ausência de uma segunda gravação. O verbete de [API](/glossario/api/) detalha a parte desse comportamento que fica disponível aos outros programas. ### Backlog: a lista ordenada do trabalho do produto - URL: https://promovaweb.com/glossario/backlog - Descrição: Backlog é a lista única e ordenada do trabalho que um produto precisa receber. Veja como descrever itens e manter a lista viva no ciclo de lançamento. ## O que é backlog Backlog é a lista única e ordenada do trabalho que um produto precisa receber. Ele reúne funcionalidades, melhorias, correções e trabalho técnico, descritos em itens que variam de intenções amplas a tarefas prontas para execução. A palavra backlog originalmente nomeava o tronco que ficava ao fundo da lareira e queimava devagar. Com o tempo, o sentido virou o de pendências acumuladas, e o desenvolvimento ágil a adotou para a lista ordenada de trabalho do produto. ## A ordem define o que entra primeiro O backlog não é uma caixa de ideias aleatórias, pois a posição de cada item comunica prioridade. Os itens mais relevantes para o usuário e para o produto ficam no topo, prontos para o próximo [ciclo de lançamento](/glossario/ciclo-de-lancamento/), enquanto os demais esperam a vez. A ordem transforma a lista em um plano de trabalho. Você ordena por valor percebido, por dependência ou por aprendizado pretendido. Uma funcionalidade que resolve uma fricção diária costuma subir, enquanto uma ideia sem validação permanece abaixo até você entender se vale o investimento.

O item de exportação avançada fica no topo do backlog por parecer importante. Após o lançamento, as métricas mostram que poucos usuários abrem o recurso.

Você reposiciona a melhoria de integração, que aparece com mais uso e mais solicitações, para o topo da lista. A ordem do backlog acompanha o que as métricas e as conversas com o cliente revelam.

## Relacionar backlog, milestones e requisitos O backlog descreve o trabalho e os [milestones](/glossario/milestone/) organizam o percurso. Você agrupa itens em marcos que representam uma versão ou um estágio do produto, e usa os [requisitos](/glossario/requisito/) para detalhar o comportamento esperado de cada funcionalidade. Um item vago no topo gera retrabalho na hora da construção. Antes de entrar no ciclo, o item precisa de descrição suficiente para orientar a especificação e a conferência da entrega. A revisão do backlog mantém esse nível de detalhe alinhado ao momento de cada item. ## Manter o backlog vivo O backlog muda o tempo todo. Após cada release, você remove o que foi entregue, incorpora o aprendizado do uso e acrescenta novas intenções. Ele nunca fica parado, porque o entendimento do produto também não fica. Um backlog com itens relevantes e ordenados se destaca pela praticidade, superando uma lista longa de tudo que já foi pensado. Você mantém a lista útil revisando o que permanece, descartando o que perdeu sentido e preservando apenas o que ainda orienta o desenvolvimento. Para revisar a trajetória e a priorização do seu produto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a definição do percurso. ### Backoff: espaçar as novas tentativas - URL: https://promovaweb.com/glossario/backoff - Descrição: Backoff define a espera entre novas tentativas. Entenda intervalos fixos, crescimento exponencial, jitter e limites para repetir chamadas a um serviço. ## O que é backoff Backoff é a estratégia que define quanto esperar antes de uma nova tentativa depois de uma falha. Em uma automação que consulta uma API, ele evita que o [retry](/glossario/retry/) repita chamadas continuamente enquanto o serviço ainda está indisponível ou recusando o volume recebido. Essa espera controla a frequência das tentativas, mas não corrige a chamada nem garante a recuperação do destino. Você precisa combinar o intervalo com os tipos de falha que permitem repetição e com o tratamento previsto quando o resultado continua ausente. ## Espera fixa e crescimento exponencial Um backoff fixo mantém o mesmo intervalo entre as tentativas, como três segundos depois de cada falha. No exponencial, cada intervalo dobra em relação ao anterior quando o fator é dois. Na espera linear, cada tentativa acrescenta o mesmo intervalo ao anterior. No crescimento exponencial, o intervalo é multiplicado por um fator, que pode ser dois.

A chamada inicial falha, e a automação espera um segundo antes da segunda tentativa. Se ela também falhar, espera dois segundos antes da terceira e quatro antes da quarta.

Essas esperas somam sete segundos, além do tempo gasto nas próprias chamadas. Se a quarta tentativa falhar e esse for o limite configurado, o workflow registra a pendência e encerra a repetição.

## O teto do intervalo e o prazo total O crescimento pode ter um teto para impedir que as pausas fiquem excessivamente longas. Depois de alcançar esse teto, a estratégia continua respeitando o máximo definido, mas ainda precisa de um limite de tentativas ou de duração total. Também confira como a ferramenta calcula o total de tentativas. Uma configuração com quatro chamadas inclui a inicial e permite até três repetições. Outra configuração pode permitir quatro novas chamadas depois da inicial. ## Jitter distribui as novas chamadas Quando muitas execuções falham juntas e usam intervalos idênticos, elas podem voltar a chamar o destino ao mesmo tempo. O jitter acrescenta uma variação aleatória às esperas para distribuir essas tentativas, conforme o cálculo oferecido pela ferramenta. Imagine cem exportações que consultam o mesmo armazenamento após uma interrupção. Espaçar todas por exatamente dois segundos ainda pode criar um novo pico no mesmo instante, enquanto intervalos variados distribuem as consultas ao longo de uma faixa de tempo. ## A orientação do serviço também precisa ser respeitada Uma resposta pode informar por quanto tempo o cliente deve aguardar, como acontece com o header `Retry-After` em algumas APIs. A estratégia local precisa considerar essa orientação documentada, em vez de repetir antes do prazo apenas porque o próximo intervalo calculado seria menor. A [idempotência](/glossario/idempotencia/) continua necessária quando a chamada pode produzir efeitos repetidos. Esperar dez segundos antes de reenviar uma criação não impede que ela seja duplicada se a primeira tentativa já tiver concluído no destino. ## Como conferir a aplicação do backoff Registre os horários das falhas, os intervalos escolhidos e o início de cada nova tentativa. Compare esses registros com o limite total para saber se a automação está esperando e encerrando a repetição conforme o planejado. Uma tentativa bem-sucedida depois de uma pausa não comprova que a pausa resolveu a causa. O resultado mostra que aquela chamada funcionou, enquanto a investigação do serviço explica por que as anteriores falharam. ### Backup: cópia mantida para recuperação - URL: https://promovaweb.com/glossario/backup - Descrição: Backup preserva conteúdo para recuperação. Entenda cobertura, consistência, retenção e separação das cópias, além do que conferir num teste de restauração. ## O que é backup Backup é uma cópia de conteúdo mantida para permitir sua recuperação depois de uma perda ou alteração indesejada. Pode preservar documentos, registros de um banco ou configurações, conforme o que foi incluído e o método usado. Você precisa saber qual perda aquela cópia permite enfrentar. Uma segunda pasta no mesmo disco pode ajudar a recuperar um arquivo apagado, mas desaparece junto com o original se o disco inteiro deixar de funcionar. ## Definir o conteúdo que precisa voltar Uma aplicação pode guardar cadastros no banco e anexos em outro armazenamento. Copiar apenas o banco recupera as referências aos anexos, mas não recria os arquivos que ficaram fora da cópia. Confira também as configurações e os meios de acesso necessários à recuperação. Se o backup está criptografado, a chave precisa continuar disponível por um caminho protegido, inclusive quando o servidor original não puder ser acessado.

A restauração recupera o cadastro e o nome do documento enviado. Ao abrir o anexo, a aplicação informa que o arquivo não existe, pois a rotina de backup incluía apenas o banco.

O teste identifica uma parte ausente da cobertura. A rotina precisa preservar também os anexos e conferir sua correspondência com os registros recuperados.

## A cópia precisa representar um estado utilizável Copiar arquivos enquanto eles mudam pode misturar estados de momentos diferentes. Em bancos como o PostgreSQL, a cópia comum do diretório exige condições específicas, enquanto ferramentas de backup e snapshots consistentes têm procedimentos próprios. Não interprete o término da transferência como comprovação de consistência. Use um método suportado pelo banco e confira suas exigências, especialmente quando o conteúdo está distribuído por mais de um volume. ## Frequência e retenção atendem a perguntas diferentes A frequência influencia a distância entre o conteúdo atual e o ponto que você consegue recuperar. A retenção define por quanto tempo versões anteriores continuam disponíveis, o que importa quando uma alteração indevida demora a ser descoberta. Uma cópia recente pode já conter o erro que você deseja desfazer. Manter apenas a última versão pode impedir a recuperação de um estado anterior, mesmo que todas as execuções da rotina tenham terminado com sucesso. ## Separação e acesso fazem parte da proteção Guardar a cópia em outro destino reduz a dependência do armazenamento original, mas a separação precisa ser analisada conforme a falha prevista. Se a mesma credencial permite apagar original e cópia, uma exclusão indevida pode atingir ambos. O acesso ao backup também merece controle porque ele pode conter as mesmas informações sensíveis da aplicação. Durante a recuperação, permissões e chaves precisam permitir a leitura pelo procedimento autorizado, sem deixar o conteúdo exposto. ## Testar a recuperação do que foi preservado Restaure uma cópia em um ambiente isolado e confira registros e arquivos conhecidos. Registre o ponto recuperado, as partes ausentes e o tempo necessário, para comparar o resultado com o objetivo de [RPO](/glossario/rpo/) e com o prazo de retorno esperado. Quando a rotina exige acompanhamento periódico, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a revisão da infraestrutura. A análise deve incluir o resultado dos testes de restauração, além do status das cópias. ### Balanceamento de carga: distribuição de trabalho - URL: https://promovaweb.com/glossario/balanceamento-de-carga - Descrição: Balanceamento de carga distribui tráfego entre destinos conforme uma política. Entenda verificações de saúde e os limites da capacidade disponível. ## O que é balanceamento de carga Balanceamento de carga é a distribuição de tráfego ou trabalho entre destinos conforme uma política. Em uma aplicação web, um balanceador pode receber chamadas e encaminhá-las a diferentes instâncias que atendem ao mesmo serviço. Você usa essa distribuição para aproveitar os destinos disponíveis, mas ela não cria capacidade de processamento sozinha. Se todas as instâncias dependem de um banco saturado, espalhar as chamadas não elimina essa limitação. ## A política escolhe o destino de cada encaminhamento Uma política pode alternar destinos, considerar conexões ativas ou usar pesos configurados. A escolha precisa corresponder ao tipo de atendimento, pois chamadas distintas podem exigir quantidades muito diferentes de trabalho. No round-robin, alternar requisições não garante consumo idêntico nas instâncias. Uma exportação demorada pode ocupar mais recursos que várias consultas pequenas, mesmo quando a quantidade de chamadas parece equilibrada.

Uma instância continua respondendo à página usada na verificação de saúde, mas perdeu acesso ao armazenamento de anexos. O balanceador mantém o destino elegível, e parte dos uploads falha.

O teste atual não cobre essa dependência. A investigação precisa relacionar os erros à instância e rever a verificação, sem interpretar uma resposta superficial como funcionamento de toda a aplicação.

## Detecção de falha tem cobertura e intervalo Uma verificação ativa consulta o destino periodicamente, enquanto a detecção passiva observa falhas no tráfego atendido. A disponibilidade desses mecanismos e suas condições dependem do balanceador usado. A retirada do destino não precisa ser instantânea e não desfaz chamadas já afetadas. Confira o intervalo, a quantidade de falhas exigida e o comportamento quando nenhum destino satisfaz a verificação, pois esse último caso varia entre produtos. ## Sessões e conexões exigem tratamento próprio Chamadas sucessivas podem chegar a instâncias diferentes. Se uma sessão ou um arquivo existe apenas na primeira instância, a seguinte pode não encontrar o estado necessário ao atendimento. Afinidade pode tentar manter determinadas chamadas no mesmo destino, mas não substitui a análise do que acontece quando ele desaparece. Conexões longas também podem permanecer num destino mesmo após novas instâncias entrarem no conjunto. ## Retirar uma instância sem perder o trabalho Uma remoção planejada pode parar novos encaminhamentos e permitir que chamadas em andamento terminem. Esse esvaziamento depende do suporte e dos tempos configurados, que precisam considerar tarefas longas. A repetição de uma chamada em outro destino também merece cuidado. Se a primeira tentativa já produziu um efeito, uma nova tentativa pode duplicá-lo quando a aplicação não trata essa possibilidade. ## Conferir a distribuição e a reação a falhas Acompanhe volume, duração e erros por destino, além do total do serviço. Em teste, retire uma instância e observe as chamadas em andamento, as novas chamadas e o retorno do destino ao atendimento. A [escala horizontal](/glossario/escala-horizontal/) trata da quantidade de instâncias que podem receber esse trabalho. Para revisar a distribuição e as falhas observadas ao longo do projeto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar o acompanhamento da infraestrutura. ### Batch: um grupo de itens como unidade de trabalho - URL: https://promovaweb.com/glossario/batch - Descrição: Batch agrupa itens para processamento. Veja como tamanho do lote, chamadas à API, resultados parciais e novas tentativas se relacionam numa automação. ## O que é um batch Batch é um grupo de itens tratado como uma unidade de processamento. Uma automação pode dividir uma lista de inscrições em lotes para enviar campos a uma API, gerar arquivos ou controlar quantos itens entram em cada repetição. O agrupamento define o tamanho de cada parte do trabalho, mas não determina como os itens serão executados internamente. Um lote de vinte inscrições pode ser processado item por item ou enviado de uma vez, dependendo do componente e do serviço de destino. ## Agrupar no workflow e enviar em lote são ações diferentes Dividir a entrada em batches não reduz automaticamente o número de chamadas. Se o Node seguinte faz uma chamada para cada inscrição, uma lista de cem itens ainda pode produzir cem chamadas, mesmo organizada em grupos de dez. Uma API que aceita vários itens por requisição pode reduzir esse total. Nesse caso, o workflow precisa montar o corpo de acordo com o contrato do endpoint, pois agrupar os itens visualmente não transforma uma API de cadastro individual em uma API de cadastro em lote.

A entrada é dividida em grupos de três, três, três e um item. O último grupo continua válido se o processamento aceitar lotes menores que o tamanho máximo.

Uma integração que envia o grupo inteiro pode realizar quatro chamadas. Outra que envia cada item separadamente fará dez, apesar de receber os mesmos quatro grupos. Confira as chamadas feitas pelo Node seguinte para distinguir o agrupamento local do envio em lote à API.

## Quantidade de itens e tamanho em bytes O limite do serviço pode considerar tanto o número de itens quanto o tamanho total da requisição. Dez registros pequenos e dez arquivos extensos representam quantidades iguais de itens, mas podem exigir memória e tráfego muito diferentes. A duração também influencia a escolha. Um lote maior pode demorar mais para produzir uma resposta, ultrapassar um [timeout](/glossario/timeout/) ou tornar a recuperação mais trabalhosa quando o destino aceita apenas parte do conteúdo. ## O resultado pode variar dentro do lote Algumas APIs informam sucesso ou falha para cada item, enquanto outras aceitam ou recusam todo o grupo. A [atomicidade](/glossario/atomicidade/) precisa ser garantida pelo serviço ou pela implementação, e não pode ser inferida da palavra batch. O envio em lote do Amazon SQS é um exemplo de contrato que pode devolver itens aceitos e recusados na mesma resposta, inclusive com status HTTP de sucesso. A integração precisa ler os resultados individuais para saber o que ainda exige tratamento. Se oito inscrições forem aceitas e duas recusadas, repetir as dez pode duplicar as oito primeiras. A recuperação deve usar os identificadores e o comportamento de repetição documentado, preservando os resultados já concluídos. ## Lotes não controlam sozinhos a frequência Processar grupos pequenos continuamente ainda pode ultrapassar o [rate limit](/glossario/rate-limit/) da API. O controle precisa considerar as pausas entre chamadas e também outras execuções que usam a mesma cota. No n8n, o Loop Over Items permite trabalhar com grupos, mas o fluxo ao redor dele define a chamada e a espera. O tamanho do batch e a [concorrência](/glossario/concorrencia/) devem ser conferidos separadamente. ## Como testar o processamento em lote Use uma lista que não seja divisível pelo tamanho escolhido e inclua um item que será recusado no ambiente de teste. Confira se o último grupo foi processado e se o relatório distingue cada sucesso de cada falha. Depois, repita apenas o trabalho que o contrato permite recuperar e consulte o destino. A conferência deve mostrar quais itens existem, quais continuam pendentes e se algum foi criado novamente durante a recuperação. ### Biblioteca: funcionalidades reutilizáveis no código - URL: https://promovaweb.com/glossario/biblioteca - Descrição: Biblioteca oferece funcionalidades reutilizáveis para outros programas. Entenda chamadas, contratos, dependências e a diferença entre biblioteca e pacote. ## Código reutilizável para uma função Biblioteca é um conjunto de funcionalidades que outros programas podem utilizar. Ela pode oferecer recursos para formatar datas, validar estruturas ou produzir arquivos, entre muitas outras finalidades. Seu código chama a interface disponível e utiliza o resultado conforme o contrato da biblioteca. A biblioteca pode ser mantida pelo projeto, acompanhar a linguagem ou ser distribuída por terceiros. Ela não precisa estar publicada em um registro público. O que caracteriza seu uso é o reaproveitamento de funcionalidades por outro código. Imagine que várias partes da aplicação precisam exibir datas no mesmo formato. Uma função compartilhada pode concentrar esse comportamento. Assim, cada tela fornece a data e recebe a representação definida para aquele uso. ## Interface, argumentos e retorno O exemplo pressupõe que o arquivo local exporte a função indicada. Ele não corresponde a um pacote que você precisa instalar. O contrato dessa função deve explicar os valores aceitos, o formato retornado e o tratamento de entradas inválidas. O contrato também informa como obter o resultado: uma função pode devolver o texto diretamente, enquanto outra retorna uma promise que será resolvida depois. No exemplo de formatação, confira como a função responde a uma data inválida e se exige configuração de idioma ou fuso. Esses comportamentos determinam como o código que a chama deve tratar o retorno. ## Biblioteca, pacote e framework Pacote é uma unidade de distribuição. Ele pode conter uma biblioteca, uma ferramenta de terminal, arquivos de tipos ou outros recursos. Portanto, nem todo pacote instalado é uma biblioteca chamada diretamente pelo seu código. Framework costuma oferecer uma estrutura mais ampla para organizar a aplicação e chamar funções definidas por você em pontos previstos. Uma biblioteca geralmente é chamada pelo programa para executar tarefas. Essa distinção é útil, mas produtos reais podem combinar características dos dois.

Você atualiza a dependência e confere os textos produzidos nas telas. Uma mudança na API ou no tratamento de fuso pode alterar o resultado esperado. O teste precisa examinar o comportamento utilizado pelo projeto.

A publicação de uma versão nova não muda automaticamente a cópia já instalada. A alteração acontece quando o processo de instalação ou atualização seleciona essa versão, conforme as declarações e o arquivo de lock.

## O que conferir antes de usar Leia a documentação da versão escolhida e verifique a compatibilidade com o runtime do projeto. Confira também licença, manutenção e dependências adicionais. Uma biblioteca popular ainda pode não atender ao formato ou ambiente de que você precisa. Registre a dependência pelo mecanismo do projeto e teste as funções que entram no comportamento da aplicação. Evite pressupor que toda funcionalidade está correta apenas por vir de um pacote externo. O verbete de [framework](/glossario/framework/) explica uma forma diferente de organizar o reaproveitamento de software. ### Body HTTP: conteúdo transportado no corpo da mensagem - URL: https://promovaweb.com/glossario/body-http - Descrição: Body HTTP é o corpo de uma requisição ou resposta. Entenda os formatos possíveis, a relação com Content-Type e os casos sem conteúdo para interpretar. ## Onde fica o conteúdo da mensagem Body HTTP é o corpo de uma requisição ou resposta, a parte que pode transportar conteúdo como um formulário, uma imagem ou um documento. Os cabeçalhos descrevem aspectos da mensagem, enquanto o corpo contém o material que será interpretado pela aplicação. Nem toda mensagem possui corpo. Quando você envia um cadastro, o corpo da requisição pode carregar nome e email. A resposta pode trazer outro corpo, com o identificador do contato criado. São conteúdos diferentes, mesmo quando os dois usam o mesmo formato. Uma consulta também pode receber conteúdo no corpo da resposta sem enviar um corpo na requisição. É o caso de uma chamada `GET` que solicita uma página pelo endereço. A função de cada mensagem determina o que precisa ser transportado. ## O formato precisa corresponder ao conteúdo O cabeçalho `Content-Type` declara o tipo do conteúdo, como `application/json` para um corpo em JSON. Um formulário com arquivos pode usar `multipart/form-data` para reunir campos e arquivos em partes distintas da mesma mensagem. A escolha precisa corresponder à representação aceita pelo serviço. Escolher um cabeçalho não transforma o conteúdo automaticamente. Uma mensagem declarada como JSON pode ser recusada quando o corpo não segue essa sintaxe. A API precisa documentar os formatos aceitos e distinguir um formato não aceito de um conteúdo inválido dentro do formato previsto. Esse trecho mostra apenas o corpo. O método, o endereço e os cabeçalhos pertencem a outras partes da requisição. Para que o cadastro funcione, o endpoint precisa aceitar os campos apresentados e os tipos de cada valor. ## Corpo enviado e corpo recebido

Você envia o nome Ana e a opção de receber a newsletter. O servidor confere esses valores e cria o cadastro. Na resposta, ele pode devolver um corpo com o identificador 42 e o nome gravado.

O conteúdo da resposta não precisa repetir todos os campos recebidos. A integração deve ler a estrutura documentada para aquela chamada, sem assumir que entrada e saída são iguais.

O corpo também pode ser um arquivo binário, como uma fotografia. Por isso, tentar converter qualquer resposta em JSON pode produzir um erro de leitura. Primeiro identifique o conteúdo esperado e o tipo efetivamente recebido. ## Quando não há corpo para interpretar Uma resposta `204 No Content` comunica sucesso sem conteúdo adicional. A resposta a `HEAD` também não entrega o corpo que acompanharia um `GET`. Essas ausências seguem a semântica HTTP e não indicam uma falha de transporte. Em requisições `GET`, o corpo não tem uma semântica geral definida para aplicações. Para filtros de consulta, siga os parâmetros documentados na URL. Acrescentar um corpo sem previsão no contrato pode resultar em rejeição ou em conteúdo ignorado pelo serviço. ## Como investigar um corpo inesperado Na aba Network do navegador, confira o status e o `Content-Type` junto com o conteúdo recebido. Uma integração que espera JSON pode ter recebido uma página HTML de login ou de erro de um intermediário. Nesse caso, a falha não está necessariamente no parser usado pela aplicação. Compare também os campos com o contrato e confira limites de tamanho para uploads. Um JSON legível ainda pode estar incompleto para a chamada. O verbete de [header HTTP](/glossario/header-http/) explica os campos que descrevem essa mensagem. ### Branch: linha de desenvolvimento separada - URL: https://promovaweb.com/glossario/branch - Descrição: Branch identifica uma linha de desenvolvimento no Git, por uma referência móvel para um commit. Entenda relação com o remoto e integração do trabalho. ## O que é uma branch Branch é uma linha de desenvolvimento representada, no Git, por uma referência móvel para um commit. Ela permite organizar uma correção ou um recurso e acompanhar seu histórico sem alterar automaticamente a referência da linha principal. Duas branches podem apontar para o mesmo commit e compartilhar todo o histórico até aquele ponto. Quando você registra um novo commit na branch ativa, essa referência avança, enquanto a outra pode continuar apontando para o estado anterior. ## A referência e os arquivos que você edita A árvore de trabalho é o conjunto de arquivos apresentado para edição. Trocar de branch atualiza esse conjunto conforme a referência escolhida, respeitando as condições para preservar modificações locais. Alterações ainda sem commit não ficam automaticamente isoladas pela branch. Elas podem acompanhar a troca quando o Git consegue preservá-las, ou impedir a troca quando o destino sobrescreveria o trabalho.

Você modifica uma mensagem, mas ainda não registra um commit. Ao trocar para uma branch compatível com essa edição, o arquivo continua modificado na árvore de trabalho.

A troca não guardou a edição exclusivamente na branch anterior. Conferir o status permite perceber esse estado antes de registrar a mensagem junto de uma mudança diferente.

## Branch local e referência do remoto Uma branch local e uma referência como origin/main têm funções diferentes. A segunda representa a informação local conhecida sobre a branch daquele remoto, que pode estar desatualizada até uma nova consulta. Enviar commits e receber atualizações são ações separadas da criação da branch. O nome igual nos dois lugares também não comprova que ambos apontam para o mesmo commit naquele momento. ## Integrar o trabalho e revisar o resultado O [merge](/glossario/merge/) é uma forma de incorporar uma linha de desenvolvimento a outra. Um pull request organiza a proposta e sua revisão na plataforma, mas não é, por si só, uma estratégia adicional de integração do Git. A branch facilita organizar o trabalho, porém não garante estabilidade da linha principal. Essa estabilidade depende do conteúdo integrado, da revisão e das verificações aplicadas ao resultado combinado. ## Conferir a branch antes de continuar Use o status para identificar a branch ativa e as modificações ainda sem commit. Confira também qual referência serviu de origem, pois iniciar a correção sobre uma base antiga pode incluir diferenças que não faziam parte da tarefa. Uma branch tampouco cria um banco, servidor ou ambiente de execução separado. Para trabalhar com arquivos simultaneamente em diretórios diferentes, o Git oferece worktrees adicionais, enquanto o isolamento da aplicação exige configuração própria. ### Bug: o comportamento indesejado de uma aplicação - URL: https://promovaweb.com/glossario/bug - Descrição: Bug é um comportamento indesejado de uma aplicação. Entenda reprodução, investigação, correção e a relação entre falha, regressão e teste. ## O que é um bug Bug é um comportamento indesejado de uma aplicação. A função não entrega o resultado esperado, ou o sistema age de forma diferente do que foi definido. O bug pode aparecer como erro, resultado errado ou falha de interação. O bug tem uma causa. Descobrir a causa exige investigação: entender o que foi feito, em que condição o comportamento acontece e qual parte do sistema produz o resultado. A correção vem depois do entendimento. ## Reproduzir para investigar Investigar um bug começa pela reprodução. Repetir o comportamento com um passo a passo confiável permite observar a causa sem adivinhar. Sem reprodução, a correção pode mirar o lugar errado. Os [logs](/glossario/log/) e o contexto ajudam. O registro do que aconteceu antes do erro orienta a investigação. Reproduzir, observar e comparar o resultado esperado com o obtido reduz a área de busca.

O painel mostra um total que não corresponde aos registros da base. Nenhum erro aparece, mas o número está errado.

A investigação confere de onde o total vem e como é calculado. Reproduzir com dados conhecidos permite ver onde o cálculo divergiu e corrigir a causa, não apenas o número na tela.

## Corrigir com confiança A correção resolve a causa do comportamento indesejado. Depois de corrigir, o teste confirma que o bug desapareceu e que nada mais quebrou. O [teste unitário](/glossario/teste-unitario/) ajuda a fixar o comportamento esperado. A correção vira uma mudança no projeto. O [pull request](/glossario/pull-request/) documenta o que foi alterado e permite a revisão. O contexto do bug e o motivo da mudança ficam registrados para quem revisa e para o futuro. ## Bug, regressão e prevenção Uma [regressão](/glossario/regressao/) é um bug que surgiu após uma mudança. Testes automatizados ajudam a detectar regressões cedo. Uma mudança que quebra algo que funcionava aparece no teste antes de chegar a produção. A prevenção acompanha a prática. Testar as mudanças, revisar o código e manter os testes atualizados reduzem a quantidade de bugs. O objetivo não é eliminar toda falha, mas detectar e corrigir com agilidade. Para investigar e corrigir bugs com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a reprodução, a causa e a verificação da correção. ### Build: preparação do código para execução - URL: https://promovaweb.com/glossario/build - Descrição: Build prepara código e recursos para distribuição. Entenda entradas, dependências, cache, artefatos e o que conferir antes de instalar o resultado. ## O que é build Build é o processo que prepara o código e os recursos de um projeto para execução ou distribuição. Um site pode transformar arquivos de desenvolvimento em páginas, scripts e estilos, enquanto uma aplicação pode reunir seu código e suas dependências em uma imagem de container. O resultado é um [artefato](/glossario/artefato/) que outras etapas poderão armazenar ou instalar. Você precisa conhecer a saída esperada, porque a mensagem de sucesso só confirma que as etapas configuradas terminaram, sem comprovar que o serviço já está disponível. ## O código é uma das entradas Além do código, a construção pode depender de bibliotecas, ferramentas, arquivos de configuração e recursos obtidos durante a execução. Uma versão diferente de uma dependência pode alterar a saída mesmo quando nenhum arquivo do projeto foi editado. Por isso, registre o commit e as versões das entradas usadas no build. O arquivo de dependências fixa algumas versões, mas uma imagem de base ou um download externo ainda pode variar se sua origem não estiver identificada. ## Compilar, preparar e empacotar A compilação transforma código para uma representação que outro programa poderá executar. Ela pode fazer parte do build, junto com atividades como preparar imagens, copiar arquivos necessários e montar o pacote final. Os testes só fazem parte desse processo quando estiverem configurados. Um comando chamado build pode gerar os arquivos sem executar testes de comportamento, e uma etapa ignorada não foi validada apenas porque o comando terminou sem erro.

A construção termina e gera a imagem da versão 1.4.0. O processo de cópia, porém, não incluiu o arquivo usado para montar a confirmação enviada por email.

A página inicial abre normalmente, mas o envio falha ao procurar esse arquivo. Conferir o conteúdo da imagem e testar o envio permite localizar uma ausência que o sucesso do build não detectou.

## Cache reaproveita trabalho anterior Um build pode usar cache para evitar repetir etapas cujas entradas foram consideradas inalteradas. Isso reduz trabalho, mas exige entender quais mudanças invalidam cada resultado armazenado. No Docker, a ordem das instruções e os arquivos usados influenciam esse reaproveitamento. Refazer tudo sem cache pode ajudar uma investigação, mas não substitui a correção da dependência ou da entrada que estava sendo interpretada de forma errada. ## Onde o resultado ficou A saída pode permanecer na máquina de construção, ser exportada como arquivo ou enviada a um armazenamento remoto. A opção depende da ferramenta e da configuração, portanto o término da construção não informa sozinho onde outra máquina poderá obter o resultado. Confira o nome, o identificador do conteúdo e o destino efetivo. Um pacote gerado apenas no computador local não fica automaticamente disponível para o servidor de produção, mesmo que ambos usem a mesma referência de versão. ## Do build ao serviço em execução O [deploy](/glossario/deploy/) instala ou disponibiliza o resultado no ambiente escolhido. Nessa etapa entram condições que a construção talvez não tenha exercitado, como permissões, credenciais e acesso aos serviços externos. Antes da disponibilização, execute o artefato em um ambiente de validação e percorra uma função que dependa dos arquivos preparados. Quando a dificuldade estiver na configuração da construção ou da publicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite investigar essa tarefa com orientação técnica ao vivo. ### Cache: cópias reutilizadas com validade - URL: https://promovaweb.com/glossario/cache - Descrição: Cache reutiliza respostas e resultados armazenados. Entenda acertos, expiração e como evitar conteúdo desatualizado ou compartilhado indevidamente. ## O que é cache Cache é o armazenamento de cópias ou resultados para reutilização em consultas posteriores. Ele pode evitar uma nova leitura na origem ou o recálculo de uma resposta, conforme a política adotada pela aplicação. Você encontra caches no navegador, em serviços intermediários e dentro de aplicações. Cada um pode ter uma política própria, então limpar uma dessas camadas não significa remover todas as cópias existentes. ## Acerto, ausência e preenchimento Um acerto, ou cache hit, acontece quando a consulta encontra uma entrada que pode reutilizar. Uma ausência, ou cache miss, exige outro caminho para obter o resultado, como consultar a origem e guardar uma nova entrada. Esse percurso precisa estar previsto pela aplicação. Se o cache fica indisponível ou perde suas entradas, o serviço de origem pode receber um volume maior de consultas e não ter capacidade para responder no mesmo ritmo.

Você atualiza o horário de atendimento na origem. Uma cópia anterior continua sendo reutilizada porque sua política ainda permite atendê-la sem consultar a mudança.

O diagnóstico compara a origem e as camadas que entregam a página. A correção precisa tratar a validade ou a invalidação da cópia relevante, em vez de repetir a mesma alteração no conteúdo original.

## Expiração e revalidação têm funções diferentes Um prazo de validade define por quanto tempo uma entrada pode ser considerada reutilizável conforme a política. A expiração não precisa implicar descarte físico imediato, pois alguns mecanismos podem verificar novamente a entrada armazenada. No cache HTTP, uma revalidação pode receber a confirmação de que o conteúdo não mudou. A resposta 304 permite reutilizar o corpo armazenado, enquanto uma alteração pode exigir receber uma representação nova. ## A chave precisa distinguir as respostas O cache precisa identificar quais consultas podem compartilhar o mesmo resultado. Ignorar um idioma, filtro ou identidade que altera a resposta pode fazer uma chamada receber conteúdo preparado para outra situação. Respostas personalizadas exigem atenção particular ao armazenamento compartilhado. Teste as variações relevantes e confira as políticas que impedem entregar conteúdo de uma sessão a outra, além da validade temporal. ## Interpretar as diretivas HTTP A diretiva no-cache exige revalidação antes da reutilização de uma resposta armazenada. Já no-store orienta que a resposta não seja armazenada, portanto as duas não expressam o mesmo comportamento. A configuração precisa corresponder ao conteúdo servido e às camadas envolvidas. Um header enviado pela aplicação não comprova sozinho que um cache intermediário está seguindo a política esperada, especialmente quando possui configuração própria. ## Medir reutilização e conferir atualização Observe acertos, ausências e tempo de resposta junto da carga na origem. Uma proporção alta de acertos não demonstra qualidade quando a resposta reutilizada está incorreta ou indevidamente compartilhada. Atualize um conteúdo controlado e confira quando a mudança aparece pelos caminhos previstos. Para revisar esse comportamento e sua relação com a infraestrutura, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar o acompanhamento recorrente do projeto. ### Caminho: a parte da URL que identifica o recurso - URL: https://promovaweb.com/glossario/caminho - Descrição: Caminho é a parte da URL que identifica o recurso. Entenda a organização da API, o papel do verbo e a leitura do caminho para entender a chamada. ## O que é caminho Caminho é a parte da [URL](/glossario/url/) que identifica o recurso acessado. Em uma API, o caminho aponta o que existe: usuários, pedidos, pets. O restante da URL informa protocolo e domínio. O caminho é a base da leitura da chamada. Ao olhar para o caminho, dá para entender o que a chamada está acessando. O recurso identificado pelo caminho completa o sentido com o método aplicado. ## Caminho e verbo O caminho identifica o recurso, e o [método](/glossario/metodo-http/) comunica a ação. A mesma URL com métodos diferentes executa operações diferentes sobre o mesmo recurso. A combinação define a chamada. Um caminho claro lido junto do verbo comunica a intenção. `GET /pets` consulta, e `POST /pets` cria. O caminho aponta o alvo, e o verbo informa o que está sendo feito. ## Caminhos que se aprofundam O caminho pode ter vários níveis. Um recurso pode conter outros dentro dele. O caminho aninhado comunica a relação entre os recursos, como um pedido dentro de um usuário. Cada nível adiciona contexto. Um caminho bem desenhado se lê como uma frase. Identificar o recurso, o elemento e a relação ajuda quem consome a API a entender a chamada.

Um caminho como `/users/5/deals/2` identifica a negociação 2 do usuário 5. O caminho comunica a relação entre os recursos.

Olhando para o caminho e o verbo, dá para entender o que a chamada faz. A URL bem desenhada orienta quem consome a API.

## Desenhar o caminho O bom caminho usa nomes que comunicam o recurso. Palavras claras e hierarquia consistente facilitam a leitura. O padrão seguido pela API torna o caminho previsível. O caminho autoexplicativo reduz a dependência de documentação. Quem olha para a URL entende o que ela acessa. A organização dos caminhos é parte do desenho da API. Para desenhar os caminhos da sua API de forma clara, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na modelagem dos recursos e das rotas. ### CDN: entrega de conteúdo a partir de pontos de presença - URL: https://promovaweb.com/glossario/cdn - Descrição: CDN distribui o atendimento de conteúdo por pontos de presença. Entenda cache, origem, atualização de arquivos e cuidados com respostas personalizadas. ## Definição CDN, ou Content Delivery Network, é uma rede distribuída que participa da entrega de conteúdo aos clientes. Seus pontos de presença podem responder com cópias armazenadas ou encaminhar a solicitação à origem. A escolha depende da configuração do serviço e da existência de uma cópia que possa atender àquela consulta. O ponto escolhido depende de roteamento, disponibilidade e políticas da rede. Ele não precisa ser o servidor geograficamente mais próximo, embora reduzir o percurso e o tempo de resposta seja uma das finalidades dessa distribuição. ## A relação com a origem A origem é o serviço de onde a CDN obtém o conteúdo que precisa buscar. Ela pode ser uma aplicação, um armazenamento de arquivos ou uma infraestrutura com várias máquinas, sem corresponder necessariamente a um único servidor. Uma cópia disponível em um ponto não significa que todos os outros já a tenham. Novas consultas, expiração e remoção de objetos podem provocar outras buscas, portanto a origem ainda precisa suportar o atendimento que chega até ela. ## Escolher o que pode ser compartilhado Imagens públicas e arquivos estáticos costumam permitir reutilização entre clientes. Já uma página com conteúdo vinculado ao perfil exige cuidado para que o [cache](/glossario/cache/) compartilhado não entregue a resposta de uma sessão autenticada a outra. A configuração precisa distinguir respostas públicas de conteúdo associado à sessão autenticada. Ao testar uma página de cadastro, confira se uma segunda sessão recebe apenas o conteúdo autorizado para ela. Ter uma CDN diante da aplicação não torna automaticamente correto armazenar qualquer página ou resposta de API.

A aplicação entrega o arquivo novo na origem, mas uma cópia anterior ainda está válida no cache. Parte dos acessos continua recebendo o estilo antigo, mesmo depois do deploy.

Você confere os cabeçalhos e o atendimento da CDN antes de repetir a publicação. Usar nomes de arquivos versionados permite que a página nova solicite outro endereço enquanto as cópias anteriores ainda existem.

## Verificar o comportamento observado Compare a resposta recebida, sua idade quando informada e os indicadores de cache documentados pelo fornecedor. Uma resposta isolada descreve aquele atendimento, sem comprovar o estado de todos os pontos de presença. Durante uma indisponibilidade da origem, algumas cópias podem continuar sendo entregues, conforme sua validade e a configuração. Operações que precisam da aplicação continuam dependentes dela, mesmo que imagens e estilos ainda abram. Para planejar cache e publicação da sua aplicação, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) oferece acompanhamento para avaliar essa configuração junto à infraestrutura. ### Chave de idempotência: reconhecer a mesma operação - URL: https://promovaweb.com/glossario/chave-de-idempotencia - Descrição: Chave de idempotência identifica tentativas da mesma ação. Entenda como reutilizá-la, respeitar seu escopo e conferir validade e respostas da API. ## O que é uma chave de idempotência Chave de idempotência é um identificador usado por uma API para relacionar várias tentativas à mesma ação. Você gera ou obtém a chave antes da chamada e a preserva quando repete aquela ação, conforme o contrato oferecido pelo servidor. Ela é útil quando a aplicação perde a resposta e não sabe se o destino concluiu uma criação. Uma nova tentativa com a mesma chave pode ser reconhecida como repetição, permitindo recuperar o resultado sem criar outro registro, desde que o serviço implemente esse comportamento. ## A chave pertence à ação, não a cada tentativa Imagine uma solicitação de exportação identificada como `exp-824`. A primeira chamada e seu [retry](/glossario/retry/) pertencem à mesma solicitação, enquanto uma nova exportação feita depois representa outra ação e precisa de sua própria identidade. Gerar uma chave nova toda vez que a rede falha elimina essa associação. O servidor pode tratar cada tentativa como uma criação diferente, mesmo que o corpo contenha os mesmos campos.

A aplicação envia a criação com a chave exp-824, e o servidor registra a exportação. A conexão cai antes de a aplicação receber o identificador do arquivo em preparação.

A nova tentativa conserva a chave exp-824 e os mesmos parâmetros. Conforme o contrato desse exemplo, o servidor retorna a exportação já criada, permitindo continuar o acompanhamento da mesma solicitação.

## O contrato define o reconhecimento Algumas APIs recebem a chave em um header, como `Idempotency-Key`, enquanto outras usam um parâmetro próprio. Confira onde o identificador deve ser enviado e qual é seu escopo, pois o reconhecimento pode depender do endpoint, da credencial ou de outra associação definida pelo serviço. O destino também pode comparar o conteúdo das tentativas. Na Stripe, reutilizar uma chave com parâmetros diferentes pode gerar erro, evitando que uma atualização diferente seja confundida com a chamada original. Duas tentativas simultâneas exigem um comportamento definido para a ação ainda em processamento. Você não deve presumir que ambas receberão imediatamente uma resposta idêntica, já que a API pode informar conflito ou exigir nova consulta enquanto a primeira chamada não termina. ## A retenção limita por quanto tempo a chave é reconhecida O serviço pode remover o registro de uma chave depois do período documentado. Reutilizar esse valor após a remoção pode produzir uma nova ação, por isso uma tarefa recuperada muito tempo depois exige consultar o destino e conferir a validade da associação. O registro do resultado também depende de a API ter iniciado o processamento. A Stripe documenta condições nas quais a execução nem começa e o resultado idempotente não é registrado, como falhas de validação anteriores ao processamento. ## Identificar a ação não concede acesso A chave não substitui a credencial que autoriza a chamada. Ela deve identificar a solicitação sem carregar senhas ou informações pessoais desnecessárias, e precisa ficar disponível para a aplicação recuperar a tentativa depois de uma interrupção. A [idempotência](/glossario/idempotencia/) também pode existir sem esse tipo de chave, como em uma atualização que define um valor fixo. O identificador é um mecanismo possível para implementar a propriedade, não sua definição. ## Como conferir a integração Em um ambiente de teste, envie a mesma ação com a mesma chave e compare o identificador e o estado do recurso no destino. Verifique também a resposta para parâmetros diferentes, repetição simultânea e recuperação após o prazo de retenção documentado. O resultado deve demonstrar que tentativas da mesma ação permanecem associadas e que ações distintas recebem identidades próprias. Apenas ver o header na chamada não comprova que o servidor o reconheceu. ### Chave estrangeira: referência a uma chave válida - URL: https://promovaweb.com/glossario/chave-estrangeira - Descrição: Chave estrangeira confere referências entre registros. Entenda vínculos obrigatórios, valores nulos e o efeito de excluir ou alterar a linha referenciada. ## Uma referência conferida pelo banco Chave estrangeira é uma coluna ou combinação de colunas sujeita a uma restrição de referência. Ela relaciona valores a uma chave válida, normalmente de outra tabela. Quando o vínculo é informado, o banco confere se existe um registro correspondente na chave referenciada. Em um sistema de cursos, uma matrícula pode guardar o identificador do estudante inscrito. A chave estrangeira impede que esse identificador aponte para um cadastro inexistente. O nome da coluna, sozinho, não cria essa garantia. A referência pode apontar para uma chave primária ou outra chave elegível segundo o banco. Também pode apontar para a própria tabela, como uma categoria que referencia sua categoria superior. O modelo precisa definir qual associação faz sentido. ## Um vínculo obrigatório `REFERENCES` declara a referência, e `NOT NULL` exige que ela seja informada. Sem a restrição de não nulo, uma chave estrangeira simples pode permitir ausência de vínculo. Uma matrícula sem identificador e outra com identificador inexistente são recusadas por restrições diferentes nesse exemplo.

Uma matrícula com estudante_id 7 atende à referência. Ao tentar usar estudante_id 99, a restrição deve recusar a gravação. Isso impede que o relacionamento dependa apenas de uma consulta anterior feita pela aplicação.

A existência do cadastro 7 não comprova que a inscrição naquele curso está permitida. Se o produto aceita apenas estudantes com matrícula ativa, a aplicação também precisa conferir essa condição antes de criar outra matrícula.

## O que acontece ao remover o registro referenciado A ação depende da configuração. O banco pode impedir a remoção, propagar a exclusão com `CASCADE` ou atribuir nulo quando essa alternativa for permitida. Não existe uma consequência única para toda chave estrangeira. Essa escolha precisa corresponder ao uso dos registros. Excluir um estudante e apagar automaticamente suas matrículas pode contrariar a necessidade de manter histórico. A estrutura deve refletir o comportamento definido para a aplicação antes de receber os cadastros reais. ## Restrição e consulta têm funções diferentes Uma chave estrangeira não cria automaticamente todas as consultas necessárias. A aplicação ainda precisa selecionar e combinar registros para apresentar uma matrícula com o nome do estudante. A restrição garante a relação declarada, enquanto a consulta define o resultado lido. Também é preciso conferir a configuração do banco. No SQLite, por exemplo, a aplicação deve verificar se a fiscalização de chaves estrangeiras está habilitada para a conexão. Declarar a sintaxe sem conferir sua aplicação pode deixar uma expectativa sem efeito. ## Como verificar o vínculo No banco de desenvolvimento do exemplo, tente gravar matrículas com o estudante 7, com o estudante inexistente 99 e sem estudante informado. Compare as mensagens e os registros persistidos para distinguir referência válida, referência inexistente e ausência proibida. Depois, teste a exclusão do cadastro referenciado conforme a ação configurada, conferindo também o que acontece com a matrícula. Quando a referência for composta, prepare os testes com a combinação completa de colunas. A existência de cada valor isolado em linhas diferentes não comprova a existência da combinação referenciada. O verbete de [relacionamento](/glossario/relacionamento/) explica como o vínculo técnico representa uma associação do modelo. ### Chave primária: identidade única de cada linha - URL: https://promovaweb.com/glossario/chave-primaria - Descrição: Chave primária identifica cada linha de uma tabela. Entenda unicidade, valores não nulos, chaves compostas e a diferença entre identidade e descrição. ## A identidade de uma linha Chave primária é a coluna ou combinação de colunas escolhida para identificar cada linha de uma tabela. Em bancos relacionais como PostgreSQL, a restrição exige valores únicos e não nulos. Duas linhas não podem compartilhar a mesma combinação de chave primária. Considere dois contatos chamados Ana Silva. O nome descreve os cadastros, mas não permite distingui-los com segurança. Identificadores diferentes permitem consultar e atualizar cada linha, mesmo quando outros campos coincidem. Essa identidade deve ser adequada ao uso da aplicação. Um número sequencial e um UUID são alternativas comuns, mas não representam as únicas possibilidades. A escolha considera também geração, tamanho, referências e manutenção do identificador. ## Declarar a chave no banco No exemplo, a coluna `id` identifica a linha, mas a declaração não configura geração automática de números no PostgreSQL. A inserção precisa fornecer esse valor explicitamente. Para delegar a geração ao banco, seria necessário configurar um mecanismo apropriado, como uma coluna de identidade.

Os dois registros podem conter o mesmo nome, mas a chave permite selecionar apenas o contato 7. Ao corrigir o nome desse cadastro, você pode manter o identificador e preservar as referências existentes, sem alterar o contato 8.

Uma tentativa de inserir outra linha com id 7 deve ser recusada pela restrição. O teste deve acontecer em um banco de desenvolvimento, com registros preparados para essa conferência.

## Chave simples e composta Uma chave simples usa uma coluna. Uma chave composta usa mais de uma, como a combinação de identificador do curso e identificador da pessoa em uma matrícula. Nessa combinação, cada valor pode se repetir isoladamente, desde que o par continue único. Uma tabela pode ter outras restrições de unicidade além da chave primária. Por exemplo, `id` pode ser a chave primária, enquanto `UNIQUE` impede repetir um código externo informado. A tabela continua tendo uma única chave primária, mesmo com outras colunas sujeitas à unicidade. ## Estabilidade não é imutabilidade automática Escolher um valor estável facilita manter referências, mas a declaração `PRIMARY KEY` não torna a coluna automaticamente imutável. Atualizações podem ser permitidas conforme as restrições e as ações configuradas nas referências. O projeto precisa definir se essa alteração faz sentido. Usar email ou nome como identidade pode exigir lidar com mudanças e duplicidades legítimas. Uma chave técnica separa a identidade interna dessas descrições, quando essa organização atende ao modelo. O identificador também não concede permissão de acesso ao registro. ## Como conferir a identidade Consulte a definição da tabela e verifique quais colunas formam a chave. Teste duplicidade e ausência em um ambiente apropriado. Depois, confira se as consultas da aplicação usam a identidade correta, especialmente quando a chave é composta. O verbete de [chave estrangeira](/glossario/chave-estrangeira/) explica como outra tabela pode referenciar essa identidade. ### Churn: a saída de clientes que revela valor não percebido - URL: https://promovaweb.com/glossario/churn - Descrição: Churn é a saída de clientes de um produto ou serviço ao longo do tempo. Entenda como medir a perda e usar o onboarding e a adoção para reduzi-la. ## O que é churn Churn é a saída de clientes de um produto ou serviço em um período. No modelo de assinatura, o termo descreve o cancelamento ou a não renovação do plano, medido pela proporção de clientes que deixam de pagar em relação ao total. O número isolado informa pouco. Ele ganha sentido quando você o relaciona ao motivo da saída, ao perfil dos clientes perdidos e ao momento do ciclo no qual eles abandonam o produto. Um churn alto concentrado em novos usuários aponta para um problema de entrada, enquanto a perda de clientes antigos costuma indicar estagnação do valor percebido. ## A saída antecede o cancelamento O cancelamento é o último passo de um processo. Antes dele, o cliente reduz o uso, deixa de abrir funcionalidades e perde o hábito de voltar ao sistema. Observar esses sinais permite agir enquanto ainda existe relação. Um usuário que não completa o próprio perfil raramente vira um cliente engajado. Da mesma forma, quando lançamentos seguidos não geram uso, a sensação de estar distante do produto cresce. O churn frequentemente vem dessa distância acumulada.

Você nem termina de explorar o primeiro lançamento quando o segundo chega. As novidades se acumulam sem que você entenda como cada uma se aplica à sua rotina.

Você começa a questionar se o valor que assina compensa e considera procurar outra opção. A dúvida sobre o retorno do produto é um alerta de churn, mesmo antes de qualquer cancelamento.

## O valor percebido determina a permanência Um cliente permanece quando enxerga o sistema como inovador, atualizado e suficiente para resolver o que precisa. Essa percepção se forma com um ritmo de lançamento que o usuário acompanha, com a explicação de cada novidade e com a escuta do que ele realmente usa. Você pode gerar valor técnico e mesmo assim perder o cliente, se ele não perceber esse valor. A métrica honesta de sucesso não é a quantidade de entregas, mas o quanto o cliente reconhece do que o produto oferece. Esse reconhecimento mantém viva a renovação. ## Como reduzir o churn na prática Reserve momentos para ouvir o cliente e entender como ele usa o sistema. Observe as [métricas de uso](/glossario/metrica/), os módulos ignorados e a conclusão do [onboarding](/glossario/onboarding/). Quando a adoção não vem, o caminho é conversar antes de lançar mais. Uma boa parte do churn se evita reforçando a primeira experiência. Um cliente que entende o valor do produto nas primeiras semanas dificilmente cancela por desconhecimento. Para revisar a experiência de entrada e o fluxo de uso do seu produto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise junto à implementação. ### Ciclo de lançamento: a cadência que dá tempo para cada novidade - URL: https://promovaweb.com/glossario/ciclo-de-lancamento - Descrição: Ciclo de lançamento é a cadência previsível de releases que dá tempo ao usuário para absorver cada novidade lançada. Veja como estruturar essa cadência. ## O que é ciclo de lançamento Ciclo de lançamento é a cadência previsível com que um produto publica novas versões. Ele estrutura o ritmo de releases para dar tempo ao usuário de absorver cada novidade, em vez de publicar funcionalidades em sequência sem espaço de compreensão. O ciclo reúne três frentes que costumam andar separadas: a comunicação do que foi lançado, a estabilização do que existe e o desenvolvimento de novos recursos. Juntas, elas compõem um ritmo único, repetido com previsibilidade. ## Por que a cadência importa Quando a produção avança mais rápido que a absorção, o usuário se perde. Você publica duas novidades em uma semana e o cliente não entende nenhuma das duas, porque não teve tempo de testar a primeira. A cadência devolve esse tempo. Um ritmo previsível educa o usuário. Ele aprende que todo início de mês chega uma novidade com explicação, e aguarda o lançamento com expectativa. A previsibilidade transforma a surpresa em hábito de consumo.

Na primeira semana, você lança o recurso e dedica o tempo a lives, vídeos e mensagens que explicam o uso. Na segunda, você estabiliza o sistema com testes e correções.

Depois, você volta ao desenvolvimento de novos recursos. O usuário recebe cada novidade com explicação, e o produto mantém um ritmo saudável e previsível ao longo do mês.

## Estruturar o ciclo em fases Um ciclo simples se divide em três partes. A comunicação do lançamento garante que o usuário saiba o que chegou e como aquilo impacta a rotina dele. A estabilização corrige o que surgiu e prepara o terreno, e o desenvolvimento constrói os próximos recursos. Correções menores podem sair fora do ciclo sem comprometer a cadência. O que o ciclo protege são as novidades que dependem de explicação, para que nenhuma release fique sem o tempo de comunicação que a adoção exige. ## O ciclo favorece a percepção de valor Um ciclo cadenciado favorece a [adoção](/glossario/adocao/) e a [percepção de valor](/glossario/percepcao-de-valor/). Cada novidade chega com explicação, e o cliente entende o uso e enxerga o produto como atualizado e suficiente. Essa leitura mantém a permanência e reduz o [churn](/glossario/churn/). O ciclo também dialoga com o [backlog](/glossario/backlog/) e os [milestones](/glossario/milestone/). Você planeja a trajetória, escolhe a cadência e comunica cada ponto alcançado. Para desenhar o ritmo de lançamentos do seu produto e estruturar a comunicação de cada release, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a definição do percurso. ### CLI: comandos de texto para interagir com ferramentas - URL: https://promovaweb.com/glossario/cli - Descrição: CLI permite usar ferramentas por comandos de texto, com ação e parâmetros. Entenda programa, subcomando, argumentos, opções e a leitura da saída com Git. ## Interagir com uma ferramenta por comandos CLI significa Command-Line Interface, ou interface de linha de comando, uma forma de utilizar um programa por instruções textuais. Você informa a ação e seus parâmetros, e a ferramenta devolve resultados ou solicita informações adicionais. O Git, por exemplo, oferece comandos para consultar o repositório e registrar alterações. A interface textual permite executar essas funções no terminal e também em scripts. O comportamento continua dependendo da operação solicitada e do ambiente de execução. Uma CLI pode coexistir com uma interface gráfica ou uma API. São formas diferentes de acessar funções de uma ferramenta. Ter uma CLI não significa que todo comando possa executar sem interação, pois alguns podem solicitar confirmação ou autenticação. ## Como ler uma linha de comando `git` identifica o programa. `status` é o subcomando que consulta o estado do repositório, e `--short` solicita uma saída compacta. Esse exemplo é de leitura e não registra nem publica alterações. Argumentos posicionais fornecem valores conforme a posição esperada, como um caminho de arquivo. Opções ajustam o comportamento e frequentemente começam com hífens. Uma opção também pode receber um valor, por isso a documentação da ferramenta determina como interpretar a linha.

Ao executar git status dentro de um deles, a ferramenta consulta aquele repositório. Em outra pasta, o resultado pode pertencer a outro projeto ou informar que não existe repositório disponível.

Antes de interpretar a saída, confira o diretório atual. Um comando correto no projeto errado pode apresentar um resultado coerente que não responde à consulta pretendida.

## Saída de texto e código de saída Programas de terminal podem escrever resultados na saída padrão e diagnósticos na saída de erro. Também devolvem um código ao processo que os iniciou. Em muitas ferramentas, zero indica sucesso e outro valor indica uma condição que precisa ser tratada. O significado exato depende do programa. Uma ferramenta de busca pode usar um código distinto para “nenhum resultado” sem representar uma falha interna. Scripts precisam seguir essa convenção em vez de procurar apenas uma palavra no texto impresso. Quando houver saída estruturada, como JSON, ela costuma ser mais adequada para outro programa interpretar. Uma tabela feita para leitura humana pode mudar de espaçamento ou formatação. Confira as opções documentadas antes de automatizar sua leitura. ## CLI, shell e terminal Ao digitar `git status --short` no terminal, você fornece ao shell a linha que ele interpreta para iniciar o Git. O Git reconhece seu subcomando e a opção, executa a consulta e escreve o resultado apresentado no terminal. A CLI define os comandos e parâmetros aceitos nessa interação. Antes de usar um comando pela primeira vez, consulte a opção `--help` e confirme em qual pasta ele será executado. Para inspecionar o efeito de `git clean`, use `git clean -n` e revise a lista antes de executar a remoção. Se o caminho tiver espaços, informe-o entre aspas para que o shell o interprete como um argumento só. O verbete de [terminal](/glossario/terminal/) explica essa interação. ### Cliente em uma aplicação web - URL: https://promovaweb.com/glossario/cliente - Descrição: Cliente é o programa que inicia a comunicação com um serviço. Entenda o papel do navegador, das automações e do backend ao enviar uma requisição. ## O que significa ser cliente de um serviço Cliente é o programa que inicia uma comunicação para utilizar um serviço oferecido por outro programa. Na web, o navegador assume esse papel quando solicita uma página ou envia um formulário. Aplicativos de celular, comandos de terminal e automações também podem atuar como clientes. Imagine que você consulta o endereço de uma loja pelo celular. O aplicativo envia uma requisição ao serviço de localização e interpreta a resposta para indicar o caminho. Nessa comunicação, o aplicativo é o cliente e o serviço de localização recebe a chamada. Essa distinção evita uma confusão comum em projetos comerciais: “cliente” também pode designar o comprador de um produto. Em protocolos e APIs, o termo identifica o papel do programa que inicia a comunicação. ## O que o cliente faz com a resposta Um cliente HTTP monta a requisição conforme o serviço que pretende acessar. Ele informa o endereço e o método, além dos campos e das credenciais exigidos naquela operação. Depois, interpreta o status, os cabeçalhos e o conteúdo recebido. Em uma interface, essa interpretação pode atualizar uma lista ou mostrar uma mensagem de erro. Em uma automação, pode determinar se a próxima etapa será executada. O papel de cliente não exige uma tela: um programa que consulta uma API todas as noites também exerce esse papel. Os estados de carregamento, confirmação e erro precisam ser implementados na interface. O navegador não infere automaticamente que uma resposta significa “cadastro concluído” para o seu produto. Você define esse comportamento conforme o contrato da API e testa as situações previstas. ## Um formulário como exemplo

Você preenche nome e email e aciona o botão de cadastro. O código da página reúne os campos, envia a requisição e aguarda o retorno. Nesse trecho, o navegador atua como cliente da API.

Se o servidor recusar o email, a interface deve apresentar uma orientação compatível com a resposta. Se o contato for criado, ela pode mostrar a confirmação. Os dois comportamentos dependem do código da aplicação e precisam ser conferidos durante o desenvolvimento.

Uma interrupção da conexão pode impedir que a resposta chegue, mesmo depois da gravação do contato. Nesse caso, o cliente sabe que não recebeu a confirmação, mas ainda não sabe se o servidor criou o cadastro. Reenviar imediatamente pode duplicá-lo quando o serviço não reconhece tentativas da mesma solicitação. ## Cliente, frontend e backend Frontend designa a interface da aplicação. Cliente designa o lado que inicia uma troca com um serviço. O navegador costuma reunir os dois, mas um backend também pode ser cliente quando consulta uma API externa. Considere um sistema de vendas que calcula o frete por meio de uma transportadora. Ele atende a requisição do navegador como servidor e chama a transportadora como cliente. Você identifica o papel observando cada comunicação separadamente, sem classificar o sistema inteiro com uma única palavra. ## Como observar a comunicação Abra a aba Network nas ferramentas do navegador e selecione a requisição. O painel mostra qual endereço foi consultado e qual resposta chegou. Um status HTTP de erro confirma que um servidor respondeu. Uma falha de conexão pode interromper a comunicação antes de qualquer retorno. Parte do conteúdo pode vir de uma cópia em cache ou ser produzida localmente. Isso pode fazer parte do funcionamento esperado da aplicação. Para investigar um resultado desatualizado, confira a origem daquele conteúdo e a política de atualização adotada antes de concluir que o servidor deixou de responder. A explicação de [requisição HTTP](/glossario/requisicao/) detalha a mensagem que o cliente prepara para chamar o serviço. ### Cloud: computação entregue como serviço pela internet - URL: https://promovaweb.com/glossario/cloud - Descrição: Cloud entrega computação como serviço pela internet. Entenda infraestrutura sob demanda, ambiente remoto, escalabilidade e a diferença para o servidor próprio. ## O que é cloud Cloud, ou computação em nuvem, é o modelo em que recursos de computação — servidores, armazenamento, bancos de dados e serviços — são entregues sob demanda pela internet. Em vez de comprar e manter hardware, você contrata capacidade de um provedor. Esse modelo permite começar com pouco e aumentar conforme a necessidade. O mesmo conceito de provisionar um [servidor](/glossario/servidor/) pode ser executado por uma chamada ou um painel, sem a preocupação de adquirir máquinas físicas. ## Infraestrutura sob demanda No cloud, a infraestrutura é entregue como serviço. Você escolhe tamanho, localização e configuração e recebe o recurso pronto para uso. A capacidade pode ser ajustada depois, conforme o tráfego ou a necessidade do projeto. A [máquina virtual](/glossario/maquina-virtual/) é um dos blocos comuns desse modelo. O provedor gerencia o hardware, e você gerencia o sistema que roda na máquina contratada.

Uma tarefa longa de automação precisa continuar mesmo se o laptop for fechado. Em vez de depender da máquina local, você executa a tarefa em um ambiente remoto provisionado no cloud.

O trabalho acontece no servidor contratado, e você acompanha o resultado depois. O ambiente local não precisa ficar ligado para a tarefa avançar.

## Cloud, VPS e servidor próprio Uma VPS pode ser o primeiro passo da nuvem: um servidor virtual dedicado dentro de um provedor. A diferença está no nível de gestão. No cloud gerenciado, o provedor cuida de partes da infraestrutura. Na VPS, você administra o sistema operacional e os serviços. A escolha depende do controle desejado. Mais controle exige mais manutenção. Menos controle significa delegar partes da operação ao provedor. ## Escalabilidade e custo O cloud permite escalar recursos conforme a demanda. A capacidade pode crescer em momentos de pico e reduzir em períodos calmos. Essa flexibilidade altera o modelo de custo, que passa a depender do consumo. Planejar o consumo evita surpresas. A facilidade de provisionar não substitui o acompanhamento do uso. Uma aplicação que recebe mais tráfego pode exigir mais recursos, e isso se reflete na fatura. Para revisar a arquitetura de cloud e os serviços contratados do seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a configuração e a manutenção do ambiente. ### Commit: registro de um estado no histórico - URL: https://promovaweb.com/glossario/commit - Descrição: Commit registra um estado versionado no Git. Entenda a área de preparação, os metadados, a relação com o histórico e a diferença entre registrar e enviar. ## O que é um commit Commit é um registro de um estado versionado do projeto no Git, acompanhado de mensagem e metadados. Ele referencia a árvore de conteúdo e seus commits pais, permitindo reconstruir o histórico e comparar estados. O identificador depende do conteúdo do objeto commit, incluindo seus metadados e relações. Recriar uma alteração com outra mensagem ou outro pai produz um registro diferente, mesmo quando os arquivos finais parecem iguais. ## O conteúdo preparado determina o registro No uso habitual, a área de preparação, também chamada de index ou staging area, define o que entrará no próximo commit. O arquivo editado no disco pode conter mudanças adicionais que ainda não foram incluídas nessa área. Gravar uma edição no arquivo e preparar seu conteúdo para commit são ações diferentes. Depois de preparar um arquivo, uma nova alteração pode deixar parte do conteúdo pronta para registro e outra parte apenas na árvore de trabalho.

Você prepara o arquivo e depois corrige outra condição nele. O teste local passa com o conteúdo atual, mas o commit registra somente a versão preparada anteriormente.

Ao executar os testes a partir do commit, a condição continua incorreta. A conferência precisa comparar o conteúdo preparado com o conteúdo testado antes de considerar o registro completo.

## Mensagem e histórico ajudam a localizar a mudança Uma mensagem útil explica a alteração e o motivo que não fica evidente no código. Reunir mudanças relacionadas facilita examinar o resultado sem misturar uma correção de comportamento com várias edições independentes. O histórico não é necessariamente uma sequência com um único antecessor por registro. Commits de merge relacionam linhas de desenvolvimento, enquanto o primeiro commit de um histórico não possui pai. ## Registrar, enviar e publicar Criar um commit normalmente altera o repositório local. O envio ao remoto compartilha os objetos e atualiza referências conforme o comando e as permissões, sem instalar necessariamente a aplicação em produção. Uma automação pode reagir ao envio e iniciar testes ou deploy, mas esse comportamento pertence à configuração do projeto. A existência do commit não comprova execução dessas etapas nem aprovação de seu conteúdo. ## Conferir o estado que ficará no histórico Leia a [comparação de arquivos preparada para registro](/glossario/diff/) e confira itens ausentes ou incluídos por engano. Depois do commit, consulte o estado preservado e relacione-o aos resultados dos testes. Reverter uma alteração também precisa considerar seu alcance. Uma mudança de código registrada no Git pode ter produzido efeitos no banco ou em serviços externos que não são desfeitos apenas pela alteração dos arquivos. ### Concorrência: tarefas em andamento que se sobrepõem - URL: https://promovaweb.com/glossario/concorrencia - Descrição: Concorrência descreve tarefas em andamento que se sobrepõem. Entenda a diferença para paralelismo, taxa de chamadas e capacidade de processamento. ## O que é concorrência Concorrência descreve tarefas cujo processamento permanece em andamento durante períodos sobrepostos. Uma tarefa pode estar esperando a resposta de uma API enquanto outra usa o processador, sem que as duas executem instruções fisicamente no mesmo instante. O paralelismo acontece quando há execução simultânea, como dois cálculos realizados em núcleos diferentes de CPU. Um sistema pode combinar as duas formas, mas aumentar o número de tarefas em andamento não cria automaticamente mais processadores ou mais capacidade no serviço consultado. ## O limite controla quantas tarefas ficam ativas Um limite de concorrência define quantas tarefas podem ocupar o processamento ao mesmo tempo dentro de determinado escopo. Esse escopo pode ser um worker, um workflow ou o conjunto de execuções de uma aplicação, conforme a ferramenta usada. Se o limite for aplicado individualmente a cada worker, adicionar outro processo pode aumentar o total de tarefas ativas. Por isso, você precisa distinguir a configuração local de um limite global que valha para todos os processos juntos.

Dois relatórios começam a ser gerados, enquanto os outros três aguardam. Quando um dos primeiros termina, outro job pode começar sem precisar esperar que os dois relatórios iniciais sejam concluídos.

Se o limite de duas tarefas fosse local a cada worker, dois workers poderiam manter até quatro jobs ativos. O número configurado só pode ser interpretado junto com seu escopo.

## Concorrência não determina a taxa de chamadas Uma tarefa pode fazer várias chamadas durante sua execução ou passar parte do tempo sem chamar nenhum serviço. Assim, dez workflows ativos não significam necessariamente dez chamadas HTTP simultâneas, e uma única execução pode gerar muitas chamadas em sequência. Considere duas vagas ocupadas por chamadas que duram um segundo cada. Em um exemplo idealizado sem pausas ou outros custos, essas vagas poderiam atender cerca de cento e vinte chamadas por minuto, muito acima de duas chamadas nesse período. O [rate limit](/glossario/rate-limit/) controla uma medida diferente, normalmente a quantidade de chamadas aceita em determinado intervalo. Os dois limites podem precisar trabalhar juntos para que a aplicação use os recursos disponíveis sem ultrapassar a cota do destino. ## Esperar uma API é diferente de calcular um arquivo Tarefas que passam tempo esperando rede podem permitir que o processo avance outros trabalhos durante a espera. Tarefas intensivas em CPU, por sua vez, continuam disputando o tempo de processamento disponível, mesmo quando você aumenta a concorrência configurada. Memória e conexões também limitam o resultado. Gerar vários arquivos grandes ao mesmo tempo disputa a memória disponível. Consultas simultâneas podem esgotar as conexões abertas para o banco. ## Tarefas simultâneas podem alterar o mesmo registro Duas execuções podem ler o mesmo valor antes de qualquer uma registrar uma atualização. Se ambas calcularem um novo total a partir dessa leitura antiga, uma gravação poderá sobrescrever o efeito da outra, conforme o banco e a aplicação tratam a alteração. Limitar a concorrência pode reduzir a frequência desse encontro, mas não substitui a proteção correta da atualização. Quando várias tarefas alteram o mesmo objeto, confira as garantias de transação e a forma de gravar o resultado. ## Como ajustar e conferir o limite Compare o tempo de espera, a duração das tarefas e as recusas dos serviços antes e depois de uma alteração pequena na configuração. Se as tarefas ficarem mais lentas, confira o consumo de CPU e memória e a espera por conexões para identificar o recurso que limita o processamento. Se as falhas aumentarem, leia suas causas antes de atribuir tudo ao volume. Um erro de credencial pode coincidir com o ajuste, enquanto recusas por excesso de chamadas exigem conferir a frequência de acesso ao serviço além do número de tarefas ativas. ### Condição de aceite: o que é e como funciona - URL: https://promovaweb.com/glossario/condicao-de-aceite - Descrição: Condição de aceite descreve o resultado verificável de uma entrega. Veja como formular cenários e distinguir aceite, testes e requisitos de qualidade. ## Definição Condição de aceite é um resultado verificável usado para avaliar se uma entrega atende ao que foi combinado. Ela descreve o que você precisa observar em determinada situação para aceitar o comportamento implementado. O [requisito](/glossario/requisito/) pode estabelecer que um cadastro precisa impedir duplicidades. A condição de aceite desenvolve essa expectativa em um cenário que informa o registro existente, a tentativa realizada e o resultado esperado. ## Descrever o resultado com precisão Expressões como “funcionar bem” deixam a conferência dependente de interpretações individuais. Para um formulário, descreva a resposta exibida e o efeito sobre o registro, pois uma mensagem correta pode acompanhar uma gravação indevida. O formato Dado, Quando e Então separa a situação inicial, a ação e o resultado esperado. Você também pode usar uma lista de condições ou exemplos, desde que o resultado seja suficientemente claro para orientar implementação e revisão.

A tela informa que o email já existe, mas uma segunda linha aparece no banco. A conferência da mensagem passou, enquanto a exigência de impedir duplicidades falhou.

A condição de aceite precisa contemplar os dois efeitos: informar a recusa e manter somente o contato original para aquele email. O teste deve consultar o identificador e os campos desse contato, além de observar a interface, para conferir que a tentativa recusada não criou nem sobrescreveu um cadastro.

## Condição, teste e prontidão Uma condição descreve o comportamento exigido, enquanto o teste define como exercitá-lo e conferir seu resultado. O mesmo comportamento pode precisar de testes diferentes para cobrir a tela, a API e acessos simultâneos. No Scrum, a Definition of Done descreve condições de qualidade para o incremento. Ela pode incluir exigências comuns a várias entregas, enquanto o aceite de um item detalha seu comportamento específico. ## Revisar o alcance da conferência Passar nos cenários escritos não comprova que todas as situações possíveis foram examinadas. Confira também quais casos ficaram de fora e se algum deles altera uma condição importante da entrega. Quando uma expectativa mudar, registre a alteração e ajuste a conferência correspondente. Reescrever o aceite apenas para acomodar um defeito esconderia a diferença entre o resultado necessário e o que foi implementado. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar essa revisão no seu projeto, relacionando os cenários descritos aos efeitos observados na aplicação. ### Condição: expressão lógica que escolhe um caminho - URL: https://promovaweb.com/glossario/condicao - Descrição: Condição avalia valores para escolher uma ação ou caminho. Veja como operadores, tipos, campos ausentes e combinações lógicas afetam uma automação. ## O que é uma condição Condição é uma expressão que avalia valores para determinar se uma ação deve acontecer ou por qual caminho o processamento seguirá. Ela pode conferir se um pagamento foi confirmado, se um campo existe ou se um número está dentro da faixa aceita pelo processo. Em um [workflow](/glossario/workflow/), essa avaliação permite tratar entradas diferentes sem criar uma automação inteira para cada caso. Uma inscrição completa pode seguir para o cadastro, enquanto outra com informações ausentes segue para correção. ## A comparação depende do significado do campo Os operadores expressam a comparação pretendida, como igualdade, maior que, menor que ou presença de um valor. Escolher o operador exige saber o que o campo representa e em qual formato ele chega à automação. O número `10` e o texto `"10"` podem ter comportamentos diferentes conforme a ferramenta e suas opções de conversão. Antes de comparar uma quantidade, confira se o contrato fornece um número ou um texto que precisa ser interpretado, evitando depender de conversões automáticas desconhecidas. A mesma atenção vale para datas e textos. Uma comparação de situação pode distinguir letras maiúsculas de minúsculas, enquanto uma comparação de horário precisa considerar o formato e o fuso usados pela entrada. ## Como combinar duas verificações O operador AND exige que todas as comparações sejam atendidas. Para liberar uma matrícula, você pode exigir pagamento confirmado e turma disponível, de modo que apenas uma dessas informações isolada não seja suficiente. O operador OR aceita que pelo menos uma das comparações seja atendida. Trocar AND por OR nesse exemplo permitiria continuar com pagamento confirmado mesmo sem turma disponível, ou com turma disponível mesmo sem confirmação de pagamento.

A entrada informa pagamento confirmado, mas a turma está indisponível. A condição conjunta resulta em falso e encaminha a inscrição para o tratamento previsto para esse caso.

Esse resultado não significa que o pagamento falhou. Ele informa que a combinação necessária para liberar a matrícula não foi atendida, por isso o motivo precisa ser preservado no encaminhamento.

## Ausência não significa reprovação do negócio Um campo inexistente, um texto vazio e um valor falso não representam necessariamente a mesma situação. A falta da confirmação por uma falha de integração informa que o workflow não recebeu o resultado do pagamento. Para classificá-lo como recusado, seria necessário receber uma resposta com esse significado, conforme o contrato do serviço. A [validação de entrada](/glossario/validacao-de-entrada/) deve identificar essas diferenças antes da ação que depende delas. Você pode separar informações incompletas de resultados válidos negativos, mantendo um tratamento próprio para cada caso. ## O componente define como os caminhos recebem os itens No n8n, o If encaminha os itens conforme o resultado verdadeiro ou falso das comparações. O Switch oferece mais saídas e pode ser configurado para enviar um item a todas as saídas correspondentes, além de definir o destino de uma entrada sem correspondência. Por isso, a existência de uma condição não garante que apenas um caminho executará em qualquer desenho. Confira a configuração do componente e as conexões seguintes, especialmente quando duas saídas podem produzir o mesmo efeito externo. ## Como testar os limites da condição Use entradas que cubram os dois resultados, incluindo campos ausentes e tipos incorretos, além de valores próximos ao limite da comparação. Se ela aceitar quantidades maiores ou iguais a dez, teste nove, dez e onze para conferir a inclusão desse limite. Compare o valor recebido com o caminho realmente percorrido e com o motivo registrado. O teste precisa mostrar tanto que uma entrada válida segue adiante quanto que uma entrada incompleta não é convertida silenciosamente em uma aprovação ou recusa do negócio. ### Configuração: parâmetros que controlam o sistema - URL: https://promovaweb.com/glossario/configuracao - Descrição: Configuração reúne parâmetros usados pela aplicação. Entenda fontes, precedência, leitura no build ou na execução e o cuidado com valores sensíveis. ## Parâmetros que a aplicação utiliza Configuração é o conjunto de parâmetros que orienta o funcionamento de um sistema. Um endereço de serviço, um limite de processamento e o idioma padrão podem ser configuráveis. O código precisa reconhecer esses parâmetros e usá-los nos pontos previstos. O mesmo programa pode consultar um serviço de testes durante o desenvolvimento e outro em produção. A lógica de integração permanece semelhante, mas o destino muda. Essa separação permite ajustar valores sem reescrever toda a função que os utiliza. Nem todo comportamento pode ser alterado pela configuração. Para aceitar um limite de itens por lote, o programa precisa ler esse parâmetro e utilizá-lo ao dividir o trabalho. Criar um nome em um arquivo não muda uma rotina que continua processando todos os itens de uma vez. ## De onde os valores vêm A configuração pode ser fornecida por arquivos, argumentos da CLI, variáveis de ambiente ou serviços próprios. Um projeto pode combinar esses mecanismos. Quando o mesmo parâmetro aparece em vários lugares, a ordem de precedência determina qual valor será utilizado. O exemplo descreve valores hipotéticos. O programa precisa implementar a leitura desses nomes e interpretar o limite como um número. Colocar `50` em um arquivo de configuração não garante que a aplicação recebeu um inteiro válido. ## Quando a configuração é lida Alguns valores são carregados no início do processo. Outros podem ser lidos a cada operação ou incorporados durante o build. Essa diferença determina se uma alteração exige reinício, reconstrução ou atualização por outro mecanismo. Em um frontend estático, um endereço pode ter sido inserido nos arquivos produzidos pelo build. Alterar uma variável no servidor depois disso não modifica automaticamente o JavaScript já gerado. Você precisa conhecer o ciclo de leitura adotado pela ferramenta.

Você altera a configuração para apontar ao ambiente correto, mas as chamadas continuam indo ao endereço anterior. A investigação confere se o processo foi reiniciado e se o valor foi incorporado no build.

Também é preciso verificar a precedência. Um argumento da inicialização pode substituir o arquivo editado, dependendo da aplicação. Confira o endereço utilizado na chamada e a fonte que forneceu esse parâmetro para descobrir por que a alteração não chegou ao processo.

## Configuração pública e valores sensíveis Nem todo parâmetro é secreto. Uma porta local ou um idioma pode ser compartilhado na documentação. Senhas e tokens exigem acesso restrito e não devem ser copiados para arquivos públicos ou logs. Um diagnóstico pode registrar quais parâmetros foram carregados e indicar valores não sensíveis. Para secrets, registre apenas informações suficientes para investigar sem revelar a credencial. Imprimir toda a configuração pode expor acesso a serviços. ## Como verificar os parâmetros Documente nomes obrigatórios, tipos, valores permitidos e comportamento na ausência de configuração. Teste um valor ausente e outro inválido. Quando não houver um padrão adequado, a aplicação pode encerrar com uma explicação clara antes de iniciar o processo que depende daquele valor. Compare também os parâmetros entre desenvolvimento e destino de publicação, sem copiar credenciais entre eles. O verbete de [variável de ambiente](/glossario/variavel-de-ambiente/) detalha um dos mecanismos usados para fornecer esses valores. ### Container: processo isolado com ambiente próprio - URL: https://promovaweb.com/glossario/container - Descrição: Container executa processos isolados a partir de uma imagem. Entenda configuração, parada, remoção, armazenamento e como conferir se a aplicação responde. ## O que é um container Container é um ambiente isolado para executar um processo ou um conjunto de processos. No modelo Linux usual, ele usa o kernel do sistema que o hospeda e recebe uma visão própria de recursos como arquivos, processos e rede, conforme a configuração. Uma aplicação web pode executar dentro de um container enquanto seu banco funciona em outro serviço. Você ainda precisa configurar a comunicação entre essas partes, pois o isolamento não fornece automaticamente credenciais, endereços ou disponibilidade das dependências. ## A imagem fornece a base Uma [imagem de container](/glossario/imagem-de-container/) reúne arquivos e configurações usados na criação. Ela continua existindo depois disso e pode originar várias instâncias, cada uma com sua identidade e suas opções de execução. Essas opções podem definir o comando inicial, variáveis, redes e armazenamento. Dois containers da mesma imagem podem se comportar de maneiras diferentes quando recebem configurações distintas, como o endereço de teste ou de produção de uma API.

Dois containers usam a mesma imagem, mas um recebe o endereço do catálogo de teste e o outro usa o catálogo de produção. O código é o mesmo, enquanto as chamadas seguem para destinos diferentes.

Uma falha no primeiro não exige que o segundo pare. Ambos, porém, podem depender da mesma máquina ou de um serviço externo compartilhado, então o isolamento dos processos não garante independência de todas as falhas.

## Parar e remover têm efeitos diferentes Uma parada encerra a execução, mas normalmente preserva o container e sua camada gravável em disco. Iniciar esse mesmo container novamente permite reencontrar arquivos guardados nessa camada, embora o estado que existia apenas na memória do processo não seja recuperado automaticamente. A remoção elimina a camada gravável associada ao container. Um novo container criado da mesma imagem não recebe as alterações locais do anterior, por isso os arquivos que precisam sobreviver à substituição devem usar armazenamento apropriado, como um volume. ## Persistência precisa corresponder ao caminho usado O [volume](/glossario/volume/) precisa estar ligado ao diretório onde a aplicação realmente grava. Montar um volume em outro caminho não protege os arquivos deixados na camada gravável, mesmo que a configuração mostre um armazenamento associado. Também existem montagens temporárias em memória, como tmpfs, cujo conteúdo desaparece quando a execução termina. Confira o tipo e o destino da montagem antes de concluir que os arquivos serão preservados. ## Isolamento não elimina limites do host Containers no mesmo host usam recursos dessa máquina e podem competir por memória, CPU e armazenamento. Limites e permissões precisam ser configurados conforme a aplicação, e conceder acesso amplo ao host reduz a separação que você pretendia obter. Alguns ambientes de desenvolvimento executam containers Linux dentro de uma máquina virtual intermediária. O kernel compartilhado pertence a esse ambiente Linux, mesmo quando o computador usa outro sistema operacional. ## Como conferir a aplicação Observe o estado do container, os registros do processo e uma chamada representativa à aplicação. Um processo ativo pode estar aguardando uma dependência indisponível, e um teste que só confirma sua existência não demonstra que o cadastro ou a consulta funciona. Ao investigar uma configuração de Docker ou um serviço que encerra após iniciar, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação técnica ao vivo. A tarefa pode partir dos logs e do comportamento observado no seu ambiente. ### Contexto: a informação que acompanha a entrada do modelo - URL: https://promovaweb.com/glossario/contexto - Descrição: Contexto é a informação que acompanha a entrada de um modelo. Entenda a janela disponível, a seleção do que importa e a influência do contexto na resposta. ## O que é contexto Contexto é a informação que acompanha a entrada de um modelo. Além da instrução, o contexto inclui histórico, dados fornecidos e qualquer conteúdo relevante que oriente a resposta. O modelo considera o contexto presente na janela para produzir a saída. A resposta depende do que está disponível. Sem o contexto necessário, o modelo pode responder de forma genérica ou errada. ## O que entra na janela O contexto é limitado pela [janela de contexto](/glossario/janela-de-contexto/) do modelo, medida em [tokens](/glossario/token-de-modelo/). Tudo o que é enviado ocupa espaço. O que não cabe não fica disponível para a resposta. Por isso, a seleção importa. Enviar apenas a informação relevante aproveita melhor a janela. Acumular conteúdo desnecessário ocupa espaço e pode desviar a resposta para detalhes que não importam.

Um agente precisa responder sobre o feedback de um usuário específico. A conversa anterior tem muitas mensagens, mas a informação sobre o feedback relevante ficou fora do que foi enviado.

Sem o contexto necessário, a resposta fica genérica. Recuperar e incluir o feedback correto na janela permite uma resposta que considera o dado que importa.

## Selecionar o que importa O contexto eficaz é selecionado. Em vez de enviar todo o histórico, a aplicação escolhe as partes relevantes para a tarefa. A [recuperação de informação](/glossario/recuperacao-de-informacao/) pode buscar o conteúdo que ajuda a responder. A seleção precisa considerar a tarefa. Uma pergunta sobre um registro exige o dado desse registro, não toda a conversa. O contexto certo é o que sustenta a resposta sem desperdiçar a janela. ## Contexto e memória O contexto é o que acompanha a entrada atual. A memória descreve a retenção de informação para uso futuro. Um sistema pode guardar dados de uma sessão e recuperá-los para o contexto de outra. A distinção ajuda a desenhar a aplicação. O que deve entrar no contexto agora e o que pode ser recuperado quando necessário? A resposta define como o sistema gerencia a informação entre as interações. Para revisar o contexto que a sua aplicação envia ao modelo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na seleção e na gestão da informação. ### Cookie: registro guardado pelo navegador e reenviado ao site - URL: https://promovaweb.com/glossario/cookie - Descrição: Cookie é um valor que o navegador armazena e pode enviar em requisições. Entenda escopo, validade, atributos e a relação com uma sessão autenticada. ## Um valor armazenado pelo navegador Cookie é um pequeno registro que o navegador armazena e pode enviar em requisições, conforme o destino, os atributos e as políticas aplicadas à chamada. Ele pode guardar uma preferência ou um identificador associado a uma sessão. A finalidade depende de como o site utiliza esse valor. Um servidor pode criar o cookie pelo cabeçalho `Set-Cookie`. Nas chamadas seguintes, o navegador envia os valores aplicáveis pelo cabeçalho `Cookie`. JavaScript também pode criar determinados cookies, mas não pode acessar aqueles protegidos com `HttpOnly`. Em um site com duas opções de idioma, um cookie pode guardar a escolha para que a próxima visita apresente os textos naquele idioma. Na área autenticada, outro cookie pode transportar o identificador usado pelo servidor para reconhecer a sessão. A finalidade de cada valor determina seu tratamento: a preferência de idioma não deve ser interpretada como autorização de acesso. ## Criação e reenvio A primeira linha representa um cabeçalho da resposta, e a segunda representa o envio posterior pelo navegador. Os atributos orientam o armazenamento e o envio, mas não são repetidos no cabeçalho `Cookie`. O identificador do exemplo é fictício e não deve ser usado como credencial real. ## O que os atributos controlam `Domain` e `Path` participam do escopo de envio. Sem `Domain`, o cookie fica associado ao host que o definiu. O caminho delimita as requisições correspondentes, mas não deve ser tratado como uma barreira de autorização entre aplicações. `Secure` restringe o envio a conexões seguras, com particularidades de desenvolvimento local previstas pelos navegadores. `HttpOnly` impede o acesso direto pelo JavaScript da página. Esse atributo não impede que o navegador envie o cookie em uma requisição iniciada por script. `SameSite` regula o envio em situações entre sites, usando uma comparação diferente da origem formada por esquema, host e porta. A configuração `SameSite=None` exige `Secure`, enquanto `Lax` e `Strict` restringem outros casos de envio. Ao investigar uma chamada entre sites, confira também as políticas do navegador para cookies de terceiros, pois os atributos não são a única condição aplicada. `Max-Age` e `Expires` definem duração ou expiração. Sem esses atributos, o cookie é considerado de sessão, mas recursos de restauração do navegador podem preservá-lo. Fechar uma aba não é uma forma confiável de encerrar uma sessão autenticada. ## Cookie e estado no servidor

Depois da autenticação, o servidor associa um identificador imprevisível à sessão. O navegador armazena esse identificador em um cookie e o reenvia nas chamadas compatíveis. O servidor consulta o estado correspondente antes de atender à área autenticada.

No logout, a aplicação precisa invalidar a sessão conforme sua arquitetura. Remover apenas um elemento visual da página não encerra o acesso. A próxima chamada autenticada deve refletir o encerramento.

Cookies não são sinônimo de rastreamento, mas podem ser usados para essa finalidade. Confira o valor armazenado, os serviços aos quais ele é enviado e o uso declarado pelo site. Um identificador utilizado para manter o login cumpre uma função diferente de outro usado para relacionar visitas entre sites. ## Como conferir o comportamento Nas ferramentas do navegador, consulte os cookies armazenados e seus atributos. Depois, observe uma requisição para verificar quais valores foram enviados. Um cookie presente no armazenamento pode não ser enviado por causa do domínio, caminho, conexão, política de site ou configuração de credenciais. Evite copiar identificadores de sessão para capturas públicas ou registros de diagnóstico. A explicação de [sessão](/glossario/sessao/) detalha o estado associado a esse identificador e as formas de encerrá-lo. ### CORS: origens autorizadas a ler respostas no navegador - URL: https://promovaweb.com/glossario/cors - Descrição: CORS permite ao navegador ler respostas de outra origem quando o servidor autoriza. Entenda preflight, cabeçalhos e chamadas autenticadas com cookies. ## Quando o navegador pode ler outra origem CORS significa Cross-Origin Resource Sharing, ou compartilhamento de recursos entre origens. É um mecanismo baseado em cabeçalhos HTTP que permite ao servidor autorizar o acesso a respostas por páginas de outras origens. Em chamadas como as feitas com `fetch`, o navegador confere essa autorização para disponibilizar a resposta ao código da página. Imagine uma interface publicada em `https://app.example.com` que consulta `https://api.example.com`. Como os hosts diferem, as origens também diferem. A API precisa enviar a autorização adequada para que o JavaScript da interface possa ler a resposta. Uma chamada funcionar no terminal e falhar no navegador pode indicar essa diferença de ambiente. Ferramentas de terminal não aplicam a política de mesma origem da página. Ainda assim, a mensagem de erro precisa ser investigada, pois uma falha no servidor também pode resultar em resposta sem os cabeçalhos esperados. ## A autorização aparece na resposta O cabeçalho `Access-Control-Allow-Origin` pode conter uma origem específica ou `*` nas situações permitidas. Ele não aceita uma lista de origens separadas por vírgula. Quando o serviço atende várias origens autorizadas, precisa selecionar o valor adequado para cada resposta. O exemplo mostra campos de uma resposta cuja autorização varia conforme a origem da chamada. `Vary: Origin` orienta caches a considerar essa diferença. O servidor deve comparar a origem recebida com suas permissões, sem simplesmente refletir qualquer valor enviado. ## O que é preflight Algumas chamadas exigem uma verificação prévia, chamada de preflight. O navegador envia `OPTIONS` com a origem, o método pretendido e os cabeçalhos relevantes. A resposta precisa autorizar a combinação antes de a chamada principal seguir. Um envio JSON com `Content-Type: application/json` normalmente exige essa verificação em uma chamada entre origens. Outros envios podem acontecer sem preflight, conforme o método e os cabeçalhos utilizados. Para investigar a diferença, compare esses campos na chamada efetiva, sem concluir apenas pela presença de um corpo.

O navegador consulta a autorização por OPTIONS antes do POST. Se a resposta não permitir o método ou os cabeçalhos necessários, o envio principal não acontece. Você pode observar as duas etapas na aba Network.

Em chamadas que dispensam preflight, a requisição pode chegar ao servidor e produzir efeitos mesmo que o navegador recuse a leitura da resposta. Um erro de CORS não comprova, sozinho, que a ação solicitada deixou de acontecer.

## Credenciais exigem configuração específica Chamadas com cookies precisam respeitar tanto a configuração de credenciais do cliente quanto os atributos e as políticas de cookies. Para expor uma resposta a uma chamada com credenciais, a API deve autorizar a origem explicitamente e enviar `Access-Control-Allow-Credentials: true`. O curinga `*` não atende a esse caso. CORS não autentica a chamada nem concede permissão para executar ações no backend. Também não deve ser tratado como proteção geral contra chamadas de outros programas ou contra CSRF. Esses controles têm responsabilidades próprias. ## Como localizar a configuração incorreta Confira a origem real da página, o preflight quando houver e os cabeçalhos da resposta principal. Respostas de erro e redirecionamentos também podem passar por componentes diferentes, que precisam ser considerados na investigação. Usar `mode: 'no-cors'` não libera a leitura do JSON esperado. Esse modo pode produzir uma resposta opaca, indisponível para a interpretação pretendida. O ajuste deve corresponder à arquitetura da integração e à [origem web](/glossario/origem-web/) autorizada pelo serviço. ### CRM: o sistema que organiza a relação com clientes - URL: https://promovaweb.com/glossario/crm - Descrição: CRM organiza a relação com clientes e o acompanhamento de negócios. Entenda contatos, negociações, etapas e como a API expõe os dados de vendas. ## O que é um CRM CRM, de Customer Relationship Management, é o sistema que organiza a relação com clientes. Contatos, negociações e etapas do processo de venda ficam registrados e acompanhados em um só lugar. O CRM ajuda o negócio a não perder oportunidades. Cada contato tem seu histórico, e cada negociação mostra onde está. O acompanhamento organizado permite agir no momento certo. ## Contatos e negociações O CRM guarda os contatos: quem são as pessoas e as empresas com quem o negócio se relaciona. Cada contato pode ter dados, histórico e contexto de uso. A negociação é uma oportunidade de venda associada a um contato. Ela tem um valor e passa por etapas. O acompanhamento mostra em que ponto cada negociação está no processo.

Um contato tem uma negociação em andamento. A negociação aparece no caminho do CRM com a etapa atual e o valor envolvido.

O acompanhamento da negociação orienta o próximo passo. Acessar o contato e a negociação permite avançar no processo com contexto.

## Etapas e processo de venda As negociações passam por etapas. O processo de venda define os passos até o fechamento. Cada etapa indica o estado da negociação e orienta a ação seguinte. A etapa é parte da [regra de negócio](/glossario/regra-de-negocio/). Avançar uma negociação muda o estado. A automação pode acompanhar a etapa e disparar ações conforme o processo definido. ## CRM e integração O CRM conversa com o restante da operação. Uma [landing page](/glossario/landing-page/) pode criar um contato, e uma automação pode atualizar a negociação. A [API](/glossario/api/) do CRM expõe os dados para integração. Um recurso do CRM pode representar o contato, e outro a negociação. O caminho identifica o elemento e o contexto. A integração usa a API para manter o relacionamento atualizado. Para estruturar o CRM e a integração com o seu fluxo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização dos contatos e das negociações. ### Cron: agendamento de tarefas por horário - URL: https://promovaweb.com/glossario/cron - Descrição: Cron agenda tarefas por horário, conhecido nos sistemas Unix e Linux. Aprenda a ler uma expressão e distinguir o disparo da conclusão do processo. ## O que é cron Cron é um mecanismo de agendamento de tarefas por horário, conhecido nos sistemas Unix e Linux. O nome também é usado para a sintaxe de expressões que descrevem recorrências em plataformas de automação e outros agendadores. Uma expressão pode indicar que um relatório deve começar todos os dias às nove da manhã. Ela define os horários previstos para o disparo, enquanto o conteúdo da tarefa determina quais informações serão consultadas e qual arquivo deverá ser produzido. ## Como ler uma expressão de cinco campos Na sintaxe tradicional, a expressão contém cinco campos, nesta ordem: - minuto - hora - dia do mês - mês - dia da semana A expressão abaixo agenda a tarefa todos os dias às nove horas. Os asteriscos mantêm abertos os campos de calendário para todos os valores permitidos. ```text 0 9 * * * ``` O primeiro `0` seleciona o minuto zero e o `9` seleciona a hora nove. Os asteriscos mantêm todos os dias do mês, todos os meses e todos os dias da semana, sem escolher uma data específica. Essa expressão contém apenas a programação de tempo. Em um crontab, a linha também precisa indicar o comando a executar, enquanto uma ferramenta como o n8n usa a expressão para iniciar o workflow configurado. ## O fuso horário muda o instante do disparo Nove horas em São Paulo e nove horas em outra região podem corresponder a instantes diferentes. Para uma rotina diária, você precisa conhecer o fuso usado pelo agendador e comparar os horários do histórico usando a mesma referência. No Schedule Trigger do n8n, o fuso do workflow prevalece quando está configurado, e o fuso da instância é usado como alternativa. A configuração deve acompanhar a necessidade do processo, como emitir um resumo pela manhã no horário da unidade que receberá o arquivo.

O trigger inicia a execução no horário configurado, e o workflow consulta as inscrições do período definido. Se a geração demorar quatro minutos, o arquivo ficará disponível depois das nove, mesmo com o disparo no horário esperado.

Para conferir a rotina, você precisa observar o início da execução e a disponibilidade do relatório. O primeiro horário verifica o agendamento, enquanto o segundo mostra quando o trabalho terminou.

## Recorrência não é intervalo desde a conclusão Uma expressão baseada no relógio não espera necessariamente que a tarefa anterior termine. Se o processo demora sete minutos e o agendamento dispara a cada cinco, pode haver duas execuções simultâneas, conforme o comportamento da ferramenta. Também não interprete qualquer expressão com barra como um intervalo contínuo entre execuções. Na sintaxe tradicional, `*/35` no campo de minutos seleciona os minutos zero e trinta e cinco de cada hora, produzindo intervalos alternados de trinta e cinco e vinte e cinco minutos. ## O que conferir antes de usar o agendamento As variantes de cron podem incluir um campo de segundos e aceitar extensões diferentes. Valide a expressão no agendador usado e confira os próximos horários previstos, principalmente quando combinar restrições de dia do mês e dia da semana. Uma parada do serviço pode impedir um disparo, e a recuperação dos horários perdidos depende da implementação. Teste também o que acontece quando a tarefa falha ou ultrapassa o próximo horário, para saber se a rotina repete, aguarda, acumula ou descarta trabalho. ### CRUD: criação, leitura, atualização e exclusão - URL: https://promovaweb.com/glossario/crud - Descrição: CRUD reúne criação, leitura, atualização e exclusão. Veja essas operações em um cadastro e confira permissões, concorrência e preservação de histórico. ## Quatro operações sobre registros CRUD reúne Create, Read, Update e Delete: criar, ler, atualizar e excluir. A sigla descreve operações básicas sobre registros persistidos. Ela aparece em telas administrativas, APIs e rotinas que manipulam cadastros. Em uma agenda de contatos, a criação acrescenta um cadastro, a leitura permite consultá-lo e a atualização corrige seus campos. A exclusão encerra sua presença conforme a política da aplicação. O efeito físico pode variar quando o sistema utiliza exclusão lógica ou preservação de histórico. A sigla não descreve o processo inteiro de um produto. Aprovar uma matrícula pode exigir a consulta do pagamento e a atualização de seu estado, além da autorização para executar essa ação. O CRUD fornece ações básicas, mas não determina quando cada uma é permitida. ## Uma sequência didática em SQL O exemplo pressupõe uma tabela compatível e um identificador disponível em um banco de testes. As instruções criam, consultam, alteram e removem a mesma linha. Elas demonstram efeitos distintos e não constituem um fluxo que você deva executar sobre um cadastro real. Nas instruções do exemplo, `WHERE id = 12` seleciona o contato que será consultado, alterado ou removido. Sem a condição apropriada, uma atualização pode atingir várias linhas, mesmo que a tela apresente apenas um contato. Confira o filtro recebido pelo backend e a quantidade efetivamente alterada para interpretar o resultado. ## O que uma tela precisa conferir

A interface carrega os campos atuais e permite corrigir o telefone. O servidor confere a permissão, valida o novo valor e grava a atualização. A resposta permite apresentar a confirmação compatível com o resultado.

Se outra chamada alterou o cadastro durante a edição, o sistema precisa definir como tratar essa concorrência. A ação Update não determina qual versão deve prevalecer.

A permissão de leitura também precisa delimitar os contatos acessíveis ao perfil autenticado. Uma listagem deve aplicar esse filtro, mesmo quando a consulta está limitada à primeira página. CRUD não significa disponibilizar toda a tabela a qualquer chamada. ## CRUD e métodos HTTP APIs frequentemente usam `GET` para leitura, `POST` para criação e outros métodos para atualização ou exclusão. Essa correspondência depende do contrato e da semântica HTTP. CRUD é uma classificação de operações, e não um protocolo de transporte. Um `POST` também pode iniciar uma ação que não seja um cadastro simples. Uma exclusão pode ser recusada porque existem referências obrigatórias. A integração precisa conhecer o comportamento real, além do nome da operação. ## Como testar o conjunto Em desenvolvimento, prepare registros conhecidos e execute cada operação com uma conta autorizada. Confira os valores, a quantidade de linhas afetadas e a resposta. Depois, teste entradas inválidas e acessos sem permissão. Para exclusão, examine referências e histórico exigidos pelo produto. Se uma matrícula precisa permanecer no histórico, apagar sua linha elimina informação que o sistema deveria conservar, mesmo quando o banco aceita a remoção. O verbete de [registro](/glossario/registro/) detalha a unidade manipulada por essas operações. ### CSS: a apresentação de documentos estruturados - URL: https://promovaweb.com/glossario/css - Descrição: CSS define a apresentação de páginas web. Entenda seletores, cascata, herança e layout, além de como investigar um estilo que não aparece na interface. ## A apresentação do documento CSS significa Cascading Style Sheets, ou folhas de estilo em cascata. É a linguagem usada para descrever a apresentação de documentos como páginas HTML. Ela define cores e tipografia, controla o espaçamento e determina a disposição dos elementos. Uma lista de produtos pode usar o mesmo conteúdo em uma coluna no celular e em várias colunas em uma tela maior. Ao mudar essa distribuição com CSS, você preserva os elementos HTML que identificam os títulos, preços e links de cada produto. A adaptação visual precisa manter essas informações legíveis e os links acessíveis nas duas larguras. O resultado visual depende da combinação entre estilos do navegador, declarações do projeto e preferências de apresentação. Por isso, uma propriedade escrita em um arquivo não garante que aquele valor será aplicado. A cascata resolve a precedência entre as declarações relevantes. ## Seletores e declarações O seletor identifica os elementos aos quais um bloco de declarações se aplica. Nesse bloco, cada declaração associa uma propriedade a um valor. Uma classe como `.cartao` pode selecionar todos os elementos que receberam esse nome no HTML. O primeiro bloco acrescenta espaço interno, borda e arredondamento aos elementos da classe `cartao`. O segundo altera o tamanho da fonte e a margem superior dos títulos `h2` que já existem dentro desses elementos. Para conferir o resultado, inspecione um cartão e seu título separadamente. ## Por que um estilo pode não ser aplicado A cascata considera fatores como origem da declaração, importância, camadas e especificidade. A ordem no arquivo pode desempatar declarações em condições equivalentes, mas não é a única influência. Acrescentar outra declaração no final nem sempre resolve um conflito. Algumas propriedades são herdadas, como a cor do texto em situações comuns. Outras, como margens, normalmente não são. Se um elemento recebe uma cor sem uma declaração direta, a origem do valor pode estar em um ancestral.

Nas ferramentas do navegador, a declaração de cor aparece riscada porque outra declaração prevaleceu para o título. Você identifica o seletor e o arquivo que forneceram o valor aplicado, em vez de acrescentar outra declaração sem entender o conflito.

Se a declaração esperada não aparece, o seletor pode não corresponder ao HTML ou o arquivo pode não ter sido carregado. A investigação muda conforme o que a inspeção mostra.

## Layout e uso da interface Flexbox e Grid organizam elementos de maneiras diferentes, e media queries permitem aplicar estilos conforme condições como a largura disponível. Ao adaptar uma tela estreita, confira se os textos continuam legíveis e se os controles podem ser acionados mesmo quando todos os blocos já cabem na largura disponível. A ordem visual pode divergir da ordem do documento quando certas propriedades reorganizam os elementos. Essa diferença pode confundir navegação por teclado e leitura assistiva. Teste a sequência de foco depois de alterar a organização visual. Ocultar um botão com CSS também não impede uma chamada direta à API do servidor. Mesmo sem o controle visível, outro cliente pode enviar a requisição, e o backend precisa conferir as permissões antes de alterar o registro. ## Como conferir o resultado Selecione o elemento na aba Elements e consulte Styles e Computed. A primeira mostra declarações aplicadas e conflitos, enquanto a segunda permite consultar valores calculados. Confira também o box model para entender espaço interno, bordas e margens. Teste diferentes larguras, ampliação do texto e navegação pelo teclado. Um layout que funciona com um título curto pode falhar quando recebe conteúdo maior. O verbete de [HTML](/glossario/html/) explica a estrutura sobre a qual esses estilos atuam. ### Cursor de paginação: a continuação de uma busca - URL: https://promovaweb.com/glossario/cursor-de-paginacao - Descrição: Cursor de paginação identifica a continuação de uma consulta. Entenda tokens, referências por identificador e limites ao percorrer listas mutáveis. ## Uma referência para continuar a consulta Cursor de paginação é uma referência usada para continuar a leitura de uma coleção. A API pode devolver um token de continuação ou orientar o uso de um identificador recebido na página anterior. A chamada seguinte fornece essa referência conforme o contrato. O cursor evita que a integração precise tratar toda continuação como um número de página. Ele pode representar os valores de ordenação do último item, um estado temporário no serviço ou outra estratégia. Sua aparência não revela necessariamente o mecanismo utilizado. Um cursor opaco deve ser reutilizado sem interpretação. Já algumas APIs documentam explicitamente parâmetros baseados no identificador de um objeto. Nos dois casos, você precisa seguir a convenção do serviço, sem construir um valor por suposição. ## Cursor de API e cursor SQL O nome também aparece no banco de dados. No PostgreSQL, `DECLARE` cria um cursor SQL, e `FETCH` recupera partes do resultado associado. Esse mecanismo tem condições próprias de sessão e transação, diferentes do contrato de paginação apresentado pela API. Receber um cursor pela API não comprova que o servidor mantém um cursor SQL aberto. A referência pode conter apenas os valores usados para montar a próxima consulta. Você precisa distinguir o que a API promete ao cliente da implementação escolhida para buscar os registros. ## Um exemplo de resposta O exemplo apenas ilustra um contrato possível. A integração envia o valor de `proximo_cursor` na chamada seguinte usando o parâmetro documentado. O nome do campo, o limite e o sinal de término variam entre APIs. Codificar um valor em base64 não o torna secreto nem garante sua integridade. O serviço precisa validar a referência recebida e continuar aplicando as permissões do perfil autenticado. Possuir um cursor não deve conceder acesso adicional à coleção. ## Ordenação e ponto de continuação Uma implementação baseada em chave pode continuar depois do último par de valores ordenados, como data e identificador. Se a página terminar no meio de um grupo com a mesma data, buscar apenas datas posteriores omitiria os itens restantes daquele grupo. O identificador usado como desempate permite distinguir a posição dentro dele, desde que a consulta aplique a mesma ordenação na continuação. Essa estratégia pode evitar alguns deslocamentos causados por novas linhas antes do ponto já percorrido. Ainda assim, mudanças nos campos de ordenação, exclusões e filtros podem alterar os resultados. Cursor não é uma promessa universal de leitura imutável.

A integração guarda os itens recebidos e envia o cursor dessa resposta na próxima chamada, mantendo os filtros da consulta. No exemplo acima, ela usa REFERENCIA_FICTICIA para continuar porque tem_mais está verdadeiro. A exportação termina quando recebe o sinal de encerramento documentado pela API.

Se a execução parar, a retomada depende da validade do cursor e de quais itens já foram gravados no destino. Registrar a continuação antes de concluir a gravação pode fazer a exportação pular os itens pendentes. Repetir uma página já gravada, por sua vez, exige reconhecer os registros existentes para evitar duplicação.

O cursor também pode expirar, e repetir a mesma referência pode observar uma coleção diferente. Defina como retomar uma exportação interrompida conforme o suporte da API, mantendo o registro do que já foi concluído. Guardar apenas o último token não resolve todos esses casos. ## O cursor pertence à consulta Alterar filtros, ordenação ou perfil autenticado enquanto reutiliza uma referência pode ser inválido. Alguns serviços incluem essas condições no token, enquanto outros esperam que a integração as preserve. Confira o contrato antes de misturar parâmetros de consultas distintas. O sinal de término também varia. Uma API pode omitir a continuação, devolver nulo ou fornecer um campo booleano. Não trate qualquer ausência como fim sem verificar se a resposta foi válida e completa. ## Como testar a sequência Prepare uma coleção conhecida com vários registros na mesma data e faça uma página terminar no meio desse grupo. Ao continuar, compare os identificadores para conferir se todos aparecem uma única vez no conjunto estável. Depois, teste as mudanças e interrupções previstas para a integração, incluindo a resposta a uma referência inválida ou expirada. O verbete de [paginação](/glossario/paginacao/) reúne as condições necessárias para interpretar o percurso completo. ### Dados: a informação que a aplicação coleta, guarda e usa - URL: https://promovaweb.com/glossario/dados - Descrição: Dados são a informação que a aplicação coleta, guarda e usa. Entenda origem, estrutura, armazenamento e o cuidado com dados sensíveis. ## O que são dados Dados são a informação que a aplicação coleta, guarda e usa para funcionar. Um cadastro, um pedido, um registro de uso: tudo isso é dado. A aplicação recebe, armazena e transforma esses dados para entregar valor. O dado é a matéria-prima da aplicação. Sem dados, não há usuário, pedido ou resultado. A qualidade do dado influencia a qualidade do que a aplicação entrega. ## Origem e coleta Os dados vêm de diferentes fontes: formulários, integrações, sensores e uso da aplicação. A coleta define o que entra no sistema. Coletar apenas o necessário reduz custo e responsabilidade. A [validação de entrada](/glossario/validacao-de-entrada/) na coleta evita que dados malformados entrem. Um dado errado na entrada se propaga para o resultado. Conferir o que entra é o primeiro passo para manter a qualidade.

O formulário aceita um cadastro sem o e-mail. O registro é salvo, mas a aplicação não consegue enviar notificações para esse usuário.

O dado incompleto foi aceito e virou um registro que não funciona para a finalidade. Validar o necessário na coleta evita guardar dados que não servem para o uso pretendido.

## Estrutura e armazenamento Os dados seguem uma estrutura. A [entidade](/glossario/entidade/) define o que é representado, e o [schema](/glossario/schema/) define a organização. A estrutura facilita guardar, consultar e transformar o dado. O armazenamento escolhe onde o dado fica. Bancos de dados, arquivos e serviços de armazenamento guardam o conteúdo. A escolha acompanha a natureza do dado e a necessidade de consulta e atualização. ## Dados sensíveis e cuidado Dado pessoal ou confidencial exige cuidado. O acesso controlado, o tratamento seguro e a transparência com o usuário fazem parte da responsabilidade. O cuidado reduz o risco de exposição. A [privacidade](/glossario/privacidade/) orienta o tratamento. Coletar o necessário, proteger o acesso e informar o uso constroem confiança. O dado é valioso, e o cuidado com ele faz parte da qualidade da aplicação. Para revisar a estrutura e o tratamento dos dados da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na modelagem e no armazenamento. ### Dashboard: painel visual para acompanhar dados e decisões - URL: https://promovaweb.com/glossario/dashboard - Descrição: Dashboard apresenta dados em um painel visual para acompanhar o que importa. Entenda métricas, filtros, atualização e a leitura do indicador apresentado. ## O que é um dashboard Dashboard é um painel visual que organiza dados em indicadores, gráficos e tabelas para acompanhar o que importa em uma área. Em vez de consultar relatórios inteiros, o usuário encontra em um só lugar os números que ajudam a decidir. O painel pode acompanhar vendas, erros de uma aplicação, desempenho de uma campanha ou qualquer conjunto de [métricas](/glossario/metrica/). O valor está em transformar dados dispersos em uma visão rápida e acionável. ## A origem do dado Um dashboard depende da fonte dos dados. Uma [API](/glossario/api/) ou um banco de dados alimenta o painel com as informações exibidas. A qualidade do painel acompanha a qualidade da origem: um dado errado na fonte aparece errado no gráfico. A atualização também importa. Um painel que mostra o estado de ontem não serve para uma decisão que precisa dos números de agora. A frequência de atualização deve corresponder ao tipo de indicador.

O dashboard mostra as vendas do dia. A consulta muda de fonte, e os números do gráfico passam a vir de outra tabela com critérios diferentes.

O gráfico continua bonito, mas o indicador agora representa outra coisa. Antes de interpretar o número, é preciso confirmar a origem e o cálculo aplicado ao dado exibido.

## Foco e legibilidade Um bom dashboard apresenta poucos indicadores bem escolhidos. Excesso de gráficos dificulta a leitura e esconde o que realmente importa. O painel deve responder às perguntas que o usuário faz com frequência. Os filtros ajudam a explorar o dado sem poluir a tela. Comparar períodos, segmentos ou categorias permite encontrar padrões. A interação complementa a visão geral apresentada. ## Do dado à decisão O painel existe para apoiar a decisão. Um número alto ou baixo precisa ser interpretado no contexto. A queda em uma métrica pode ser esperada em um período ou indicar um problema real. Antes de agir a partir de um gráfico, confirme o que o indicador representa, como foi calculado e quando foi atualizado. O dashboard apresenta informação. A decisão depende do entendimento do contexto. Para revisar os indicadores e as fontes do seu dashboard, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) ajuda a verificar o que está sendo medido e apresentado na sua aplicação. ### Debounce de job: executar apenas a última instância repetida - URL: https://promovaweb.com/glossario/debounce-de-job - Descrição: Debounce de job faz a fila executar somente a última instância quando o mesmo job é reenfileirado várias vezes. Veja o propósito, o limite e a relação com trabalho obsoleto. ## O que é debounce de job Debounce de job é um mecanismo que faz a [fila](/glossario/fila/) executar somente a última instância quando o mesmo [job](/glossario/job/) é reenfileirado várias vezes. As instâncias anteriores são descartadas, e apenas o trabalho mais recente segue para o [worker](/glossario/worker/). O objetivo é evitar processamento obsoleto. Quando uma ação gera várias alterações em sequência, cada uma reenfileira o mesmo job, mas somente o estado final importa. O debounce reduz trabalho repetido e libera capacidade da fila. ## Quando o trabalho anterior fica obsoleto Uma atualização de busca é um caso típico, pois cada mudança no cadastro reenfileira o job de reindexação. Sem o debounce, o worker processaria uma versão antiga das informações e depois outra, quando apenas o estado atual deveria ser refletido. O mesmo acontece em relatórios e integrações. Se várias mensagens chegam em um intervalo curto, apenas a última precisa gerar o resultado. As anteriores descrevem estados que já não existem.

Você edita cinco campos em sequência e cada mudança reenfileira o job de busca. O debounce descarta as quatro primeiras instâncias e mantém a quinta.

O worker indexa o estado final do cadastro. As instâncias descartadas não geraram trabalho, e o resultado corresponde ao conteúdo atual da página.

## Debounce, job único e deduplicação O debounce se relaciona com a [deduplicação](/glossario/deduplicacao/) e com o job único. A deduplicação evita registrar o mesmo item duas vezes, e o job único impede instâncias simultâneas. O debounce se concentra no tempo: quando a mesma instância é repetida, só a última executa. A combinação depende do cenário. Para impedir uma operação financeira duplicada, o job único protege melhor. Para refletir o estado mais recente de uma alteração, o debounce atende. Escolher o mecanismo certo exige entender o que cada um protege. ## O efeito já executado não é desfeito O debounce não desfaz trabalho cujo processamento iniciou antes do descarte. Se a instância anterior já estava em execução, seu efeito pode ter ocorrido, e manter apenas a última não o remove. A conferência do resultado precisa considerar esse caso. Para revisar um job que processa trabalho repetido ou desatualizado, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise do fluxo de fila junto à implementação. ### Deduplicação: tratar ocorrências repetidas - URL: https://promovaweb.com/glossario/deduplicacao - Descrição: Deduplicação reconhece itens ou eventos repetidos. Veja como escolher a identidade, preservar o histórico e tratar concorrência e falhas de processamento. ## O que é deduplicação Deduplicação é a identificação e o tratamento de ocorrências que representam o mesmo item ou evento. Ela permite reconhecer, por exemplo, que dois avisos recebidos por [webhook](/glossario/webhook/) correspondem à mesma confirmação, em vez de tratar cada entrega como um fato novo. O significado de duplicado depende do processo. Duas linhas idênticas em uma importação podem ser repetição acidental, mas duas compras com o mesmo valor e o mesmo cliente podem ser legítimas e precisam continuar separadas. ## A identidade precisa corresponder à ocorrência O identificador do evento costuma ser um ponto de partida quando a origem garante sua unicidade no escopo usado. O código do cliente ou do pagamento identifica outro objeto e pode aparecer em vários eventos diferentes, como confirmação e reembolso. Também confira se a identidade é única entre todas as origens integradas. Se dois serviços podem usar o mesmo valor, a combinação da origem com o identificador evita que uma ocorrência legítima seja descartada como duplicada da outra.

A primeira entrega inicia o processamento da confirmação. Minutos depois, a origem reenvia a notificação com o mesmo identificador, e a automação consulta o registro correspondente.

Se o trabalho já terminou, a repetição pode receber a confirmação prevista pelo contrato. Se houve falha antes da conclusão, o registro precisa permitir recuperar a tarefa, em vez de descartá-la apenas porque o identificador já apareceu.

## Lista atual e histórico de execuções Eliminar duplicados dentro de uma lista resolve apenas a repetição que está presente naquela entrada. Um conjunto guardado somente na memória de uma execução pode desaparecer ao final dela e não reconhecer uma entrega recebida depois. No n8n, o Remove Duplicates oferece comportamentos distintos para comparar itens da entrada atual ou usar informações de execuções anteriores. O modo e o escopo escolhidos precisam corresponder à repetição que você deseja tratar. O histórico também pode ter limite de quantidade, prazo de retenção ou remoção manual. Depois que uma identidade sai desse histórico, uma entrega antiga pode voltar a ser considerada nova, por isso a proteção não deve ser descrita como ilimitada. ## Duas chamadas podem chegar ao mesmo tempo Uma sequência de consultar e depois registrar pode falhar diante de [concorrência](/glossario/concorrencia/). Duas execuções podem consultar a mesma identidade ainda ausente e ambas começar o efeito antes de qualquer uma registrar a ocorrência. Uma forma de coordenar essas execuções é gravar a identidade do evento sob uma restrição de unicidade antes de iniciar o efeito. Se o banco recusar a inserção por duplicidade, o código consulta o estado do evento para saber se ele terminou ou pode ser retomado. A restrição identifica a repetição, mas não confirma se o primeiro envio concluiu a chamada a outro serviço. Esse registro não torna uma chamada externa parte da mesma [transação](/glossario/transacao/) do banco. A recuperação ainda precisa considerar uma execução interrompida depois de registrar a identidade ou depois de realizar o efeito no outro serviço. ## Reconhecer o evento e concluir a tarefa Marcar o evento como concluído antes de realizar sua ação pode impedir a recuperação depois de uma falha. Marcar apenas depois também exige tratar a situação na qual a ação terminou, mas o registro de conclusão não foi gravado. Por isso, o processamento pode precisar distinguir recebido, em andamento e concluído, além de usar [idempotência](/glossario/idempotencia/) no destino. A deduplicação reduz trabalho repetido, enquanto a recuperação precisa preservar o que ainda está pendente. ## Como verificar a deduplicação Teste duas entregas consecutivas e duas simultâneas da mesma ocorrência, acompanhando quantos efeitos aparecem no destino. Inclua uma falha durante o processamento e confirme que a repetição consegue recuperar o trabalho necessário. Envie também eventos distintos do mesmo cliente e confira se ambos continuam válidos. Esse teste mostra se o identificador escolhido reconhece duplicações reais ou está eliminando ocorrências que deveriam ser processadas. ### Delay de job: o atraso planejado para a execução - URL: https://promovaweb.com/glossario/delay-de-job - Descrição: Delay de job atrasa a execução de um job por um intervalo planejado. Veja o propósito do atraso, a diferença em relação ao backoff e os casos de uso em sequências. ## O que é delay de job Delay de job é o atraso planejado antes de um [job](/glossario/job/) ser liberado para execução. O trabalho é enviado à [fila](/glossario/fila/) e permanece aguardando até que o intervalo definido termine, quando então fica disponível para o [worker](/glossario/worker/). O atraso é intencional, definido no envio, e não corrige uma falha nem responde a um erro. Ele define o momento da execução para atender a uma sequência, a uma janela de tempo ou a um limite de carga. ## Suavizar picos e orquestrar sequências Um uso comum é suavizar picos de carga. Em vez de liberar dezenas de jobs ao mesmo tempo, você espaça a liberação por intervalos. O sistema processa aos poucos, e o serviço de destino não recebe um volume concentrado. O delay também orquestra sequências. Um email de confirmação pode aguardar alguns minutos após a criação da compra, dando tempo para o registro ser concluído antes do envio. A sequência usa o atraso para respeitar a ordem do fluxo.

Você envia o job de notificação com um atraso de alguns minutos. O job fica aguardando na fila até o intervalo terminar.

Depois do atraso, o worker executa o envio. O cliente recebe a confirmação em um momento coerente com o fluxo, e a carga do sistema permanece distribuída.

## Delay não é backoff A distinção é essencial. O [backoff](/glossario/backoff/) entra após uma falha: o job tenta novamente depois de um intervalo que cresce ou se repete, permitindo a recuperação do destino. O delay entra no primeiro processamento, conforme o fluxo definido. Usar um no lugar do outro gera comportamento errado. Aplicar delay em um job que falha não espaça as tentativas de forma crescente, e aplicar backoff em uma sequência planejada não respeita a janela intencional. Cada mecanismo responde a uma necessidade própria. ## O atraso define a disponibilidade, não a conclusão O job atrasado fica disponível após o intervalo, mas a execução depende dos workers. Se a fila está ocupada, o trabalho aguarda mais tempo. O delay garante o momento mínimo de espera, não o instante da conclusão. Para revisar o uso de atrasos e sequências no seu fluxo, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise da fila e da distribuição de carga junto à implementação. ### Delegação: transferir a execução e acompanhar o resultado - URL: https://promovaweb.com/glossario/delegacao - Descrição: Delegação é transferir a execução de uma tarefa a um agente e acompanhar o resultado obtido. Veja o que ela exige do usuário e o momento da revisão. ## O que é delegação Delegação é transferir a execução de uma tarefa a um [agente](/glossario/agente-de-ia/) ou a um assistente e acompanhar o resultado. Em vez de executar cada etapa, você entrega o objetivo e confere o que foi produzido. A delegação não remove o trabalho de definir o que precisa ser feito. Ela move a execução para outra parte e mantém o acompanhamento com aquele que recebeu a tarefa. O resultado volta para conferência, e é essa conferência que valida a entrega. ## O que uma boa delegação exige Uma tarefa delegada com qualidade precisa de descrição clara. Você informa o objetivo, o escopo e o resultado esperado, e o agente executa dentro desses limites. Uma [especificação](/glossario/especificacao-spec/) bem escrita orienta o trabalho e reduz idas e voltas. Quando a delegação parte de uma especificação incompleta, o resultado tende a divergir do esperado. O agente pode executar etapas além do necessário, ignorar um limite ou parar antes do ponto combinado. A definição da tarefa é a base da delegação.

Você informa ao agente a proposta da página, as seções desejadas e o limite de ajustes. Ele executa a estrutura e retorna o resultado para conferência.

Você revisa o que foi produzido contra o escopo descrito. A delegação transferiu a execução, mas a conferência do resultado permaneceu com você.

## Delegação e autonomia do agente A delegação se apoia na [autonomia do agente](/glossario/autonomia-de-agente/). Um agente mais autônomo executa a tarefa delegada com menos supervisão, enquanto um mais contido exige instruções passo a passo. A escolha depende do perfil e da tarefa. O usuário que delega e se afasta se beneficia de um agente autônomo. O usuário que acompanha cada etapa prefere uma execução conduzida, mesmo com a tarefa transferida. ## A revisão permanece com você Delegar não transfere a responsabilidade pelo resultado. O trabalho produzido pelo agente precisa ser conferido antes de entrar na entrega. A revisão compara o resultado com a especificação e identifica o que o agente não atendeu. Para acompanhar uma delegação no seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação ao vivo sobre escopo, especificação e conferência do resultado. ### Dependências: os componentes que o projeto usa para funcionar - URL: https://promovaweb.com/glossario/dependencias - Descrição: Dependências são componentes que o projeto usa para funcionar. Entenda bibliotecas, declaração, atualização e o risco de manter dependências desatualizadas. ## O que são dependências Dependências são os componentes externos que um projeto usa para funcionar. Em vez de reescrever tudo, o projeto aproveita bibliotecas, frameworks e serviços prontos. Cada um desses componentes é uma dependência. As dependências precisam ser declaradas e gerenciadas. A declaração permite instalar, versionar e reproduzir o projeto em outro ambiente. Sem declaração, a instalação quebra ou usa versões diferentes entre máquinas. ## Declarar e versionar A [biblioteca](/glossario/biblioteca/) usada no projeto é declarada com a versão esperada. A versão define o comportamento disponível. Declarar a versão certa evita que uma atualização inesperada mude o funcionamento da aplicação. O gerenciador de pacotes cuida da instalação e da resolução. O arquivo de declaração registra o que o projeto precisa. O ambiente de execução instala o conjunto declarado, tornando o projeto reproduzível.

O projeto funciona no computador do desenvolvedor, mas a instalação falha em outra máquina. As dependências usadas não estão declaradas no arquivo do projeto.

Declarar as dependências com as versões corretas permite instalar o mesmo conjunto em qualquer ambiente. O projeto passa a ser reproduzível onde for configurado.

## Atualizar com cuidado As dependências precisam de manutenção. Versões novas corrigem falhas e reduzem riscos de segurança. Uma dependência desatualizada pode conter vulnerabilidades conhecidas. A atualização, porém, precisa ser verificada. Uma versão nova pode introduzir incompatibilidade ou mudar o comportamento. Testar após a atualização confirma que o projeto continua funcionando. A atualização é uma mudança revisada, não uma ação automática. ## Dependências e risco Cada dependência adiciona responsabilidade. O projeto herda o comportamento e os riscos dos componentes que usa. Mais dependências significam mais superfície para atualizar e proteger. Usar apenas o necessário é a prática recomendada. Antes de adicionar uma dependência, vale avaliar se a função não pode ser resolvida de forma simples. Um projeto enxuto é mais fácil de manter e menos exposto a riscos externos. Para revisar as dependências do seu projeto e o risco delas, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na gestão dos componentes usados. ### Deploy: disponibilização de uma versão - URL: https://promovaweb.com/glossario/deploy - Descrição: Deploy disponibiliza uma versão em um ambiente. Entenda preparação, configuração, conferência do serviço e limites da reversão quando a atualização falha. ## O que é deploy Deploy é o processo de instalar ou disponibilizar uma versão de uma aplicação em um ambiente. Ele pode colocar uma página estática no serviço de hospedagem ou atualizar os processos que atendem uma API, conforme a forma de execução do projeto. O [build](/glossario/build/) prepara o resultado que será usado, enquanto o deploy aplica esse resultado ao destino. Gerar um pacote não informa se ele chegou ao servidor nem se a versão nova começou a atender as chamadas. ## Versão, destino e configuração Antes de iniciar, identifique o artefato que será instalado e o ambiente que receberá a mudança. A configuração desse destino precisa fornecer os endereços, as permissões e as credenciais necessárias sem incluir valores de outro ambiente por engano. Você também precisa saber quais etapas modificam o estado persistido. Uma atualização pode instalar código e executar uma migration, e essas duas ações têm consequências diferentes quando a inicialização da nova versão falha.

A versão 1.4.0 é instalada e a página inicial responde. O cadastro usa uma configuração nova que não foi fornecida, então a confirmação não chega ao serviço de email.

O teste do cadastro em staging identifica a falha no envio. Você compara a configuração exigida pela versão 1.4.0 com a configuração fornecida nesse ambiente e repete o cadastro depois do ajuste, conferindo a chegada da confirmação ao destino de teste.

## A instalação pode ocorrer aos poucos Uma atualização pode substituir todas as instâncias de uma vez ou avançar gradualmente, conforme os recursos disponíveis. Durante uma troca gradual, versões diferentes podem atender ao mesmo tempo e precisam conviver com o banco e com as mensagens produzidas pelo sistema. Essa convivência deve ser considerada antes da mudança. Um campo removido do banco pode interromper as instâncias antigas ainda em execução, mesmo que o código novo tenha sido testado isoladamente. ## Verificar o serviço depois da troca Confira a versão efetivamente executada, a inicialização e uma função que represente o uso da aplicação. A resposta da página inicial não confirma necessariamente autenticação, gravação ou acesso a uma API externa. Observe também os erros e o tempo de resposta após a mudança. Um problema que depende de tráfego pode surgir depois do teste inicial, por isso a conferência continua enquanto a versão recebe uso representativo. ## A recuperação depende do que foi alterado Voltar ao artefato anterior pode recuperar uma falha de código, desde que ele continue compatível com o estado atual. Uma migration que removeu conteúdo ou uma chamada que enviou mensagens exige tratamento próprio, pois trocar o executável não desfaz esses efeitos. O procedimento de deploy precisa definir qual falha interrompe a atualização e como recuperar o serviço. Se a nova versão não inicia, confira se o artefato anterior ainda pode usar o banco atual. Quando essa compatibilidade não existe, reinstalar o código antigo pode acrescentar outra falha, pois a recuperação exige tratar também a mudança persistida. ## Registrar o resultado da publicação Guarde a versão aplicada, o destino, o horário e o resultado das verificações. Esse registro permite relacionar uma falha observada ao momento da mudança e conferir se todas as instâncias receberam a versão prevista. Quando a tarefa exigir investigar uma publicação que não inicia ou não responde como esperado, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação ao vivo sobre uma demanda delimitada. O acompanhamento parte do comportamento observado no seu projeto, com o ambiente sob seu controle. ### DevOps: colaboração entre desenvolvimento e operação - URL: https://promovaweb.com/glossario/devops - Descrição: DevOps aproxima desenvolvimento e operação. Entenda colaboração, automação, acompanhamento das mudanças e como falhas do serviço orientam melhorias. ## O que é DevOps DevOps reúne práticas de colaboração, automação e acompanhamento que conectam o desenvolvimento à manutenção de um software em uso. O trabalho considera tanto a mudança no código quanto as condições necessárias para publicá-la e mantê-la funcionando. Você encontra essa relação quando uma alteração exige configurar uma variável, atualizar o banco ou observar um novo tipo de falha. Preparar apenas o código deixa uma parte da mudança sem tratamento, mesmo que o build termine corretamente. ## A mudança precisa ser compreendida até o uso Durante o desenvolvimento, as exigências de instalação e funcionamento precisam ser conhecidas. Depois da publicação, os resultados observados ajudam a corrigir o código, os testes e o procedimento de entrega. Em uma organização, profissionais de desenvolvimento podem trabalhar junto da área que mantém os serviços. Num projeto individual, você pode acumular essas tarefas. Nos dois casos, registre a versão instalada e a configuração exigida por ela para retomar o trabalho com a mesma base.

O código usa uma variável nova, mas o ambiente de produção ainda não a possui. A versão inicia e falha somente quando tenta acessar o serviço externo.

A correção configura o ambiente e acrescenta uma verificação da variável ao processo de publicação. O aprendizado modifica o procedimento, para que a mesma ausência seja percebida numa próxima mudança.

## Automatizar um procedimento que você consegue explicar Builds, testes e instalação de versões podem ser automatizados para repetir etapas conhecidas. Antes disso, o procedimento precisa ter entradas, resultados esperados e um tratamento definido para suas falhas. Uma automação que copia uma sequência mal compreendida também repete seus problemas. Confira os comandos executados, as permissões usadas e a forma de identificar o resultado, para que a investigação não dependa de adivinhar o que aconteceu. ## Acompanhar o comportamento da aplicação O resultado da publicação precisa ser relacionado ao serviço atendido, como concluir uma inscrição ou abrir um arquivo. Um processo ativo ou um teste superficial pode não exercitar a função alterada. Use o [monitoramento](/glossario/monitoramento/) para acompanhar condições relevantes e os registros disponíveis para investigar diferenças. Quando uma falha se repete, o ajuste pode precisar alcançar a aplicação, os testes ou o ambiente, conforme a causa encontrada. ## Ferramentas apoiam práticas e responsabilidades Containers, pipelines e arquivos de infraestrutura são recursos possíveis para executar esse trabalho. Sua presença não demonstra, sozinha, que as mudanças são compreendidas ou que o serviço recebe acompanhamento. Defina como uma falha chega a você, como localizar a versão envolvida e onde consultar o procedimento de recuperação. Esses detalhes permitem agir quando a automação termina com erro ou a aplicação apresenta um comportamento inesperado. ## Avaliar uma mudança completa Acompanhe uma alteração recente desde o código até seu funcionamento e procure etapas cuja execução ou resultado não ficou registrado. Uma melhoria útil pode ser pequena, como identificar o artefato instalado ou acrescentar a conferência de uma configuração obrigatória. Para revisar esse percurso de forma recorrente, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode acompanhar a infraestrutura e o desenvolvimento do projeto. A análise deve partir de dificuldades concretas de publicação e manutenção. ### Diff: diferenças entre duas versões - URL: https://promovaweb.com/glossario/diff - Descrição: Diff compara estados de conteúdo entre duas versões de um arquivo. Entenda o que git diff e --staged mostram e por que um resultado vazio pode enganar. ## Como o Git apresenta diferenças O diff (comparação entre estados de conteúdo) apresenta diferenças entre duas versões. Em arquivos de texto, normalmente mostra linhas removidas, linhas acrescentadas e trechos próximos que ajudam a localizar a alteração. Você precisa conhecer os dois estados comparados para interpretar o resultado. O mesmo arquivo pode ter diferenças distintas entre o último commit, a área de preparação e o conteúdo atual no disco. ## Escolher a comparação correta Sem argumentos, git diff mostra mudanças da árvore de trabalho em relação à área de preparação. Já git diff --staged mostra o conteúdo preparado em relação a HEAD, que normalmente identifica o commit atual. A forma git diff HEAD compara os arquivos rastreados da árvore de trabalho com esse commit. Nenhuma dessas leituras deve substituir a consulta ao status quando você precisa localizar arquivos novos ainda não rastreados. Os comandos consultam o estado sem preparar arquivos ou criar commits. Seus resultados respondem a perguntas diferentes, então um resultado vazio no primeiro não torna os demais desnecessários.

Você altera uma mensagem e inclui essa edição na área de preparação. Como o arquivo no disco está igual ao conteúdo preparado, git diff não mostra diferença.

git diff --staged ainda mostra a mudança em relação ao commit atual. O resultado vazio anterior significava igualdade entre dois estados específicos, não ausência da alteração no projeto.

## Comparar branches exige conhecer a base Uma comparação entre as pontas de duas branches responde ao que difere entre seus estados atuais. Uma comparação a partir do ancestral comum destaca o que uma das linhas acrescentou desde a separação. Essas perspectivas podem produzir resultados diferentes quando ambas avançaram. Em um pull request, confira a base e a forma de comparação usada pela plataforma antes de concluir que uma alteração foi incluída ou removida da proposta. ## Ler além das linhas coloridas Uma mudança pequena pode alterar uma condição usada por várias funções. Leia o trecho completo e suas chamadas quando a comparação não mostrar informação suficiente para entender a consequência. Arquivos binários e conteúdo gerado também podem exigir outra forma de inspeção. A representação textual disponível não garante que todos os efeitos relevantes estejam visíveis naquele painel. ## Relacionar a diferença ao comportamento Use a comparação para localizar alterações que exigem conferência e execute os testes do comportamento modificado. Se uma validação define um limite, confira o valor aceito e aqueles imediatamente abaixo e acima dele. O [commit](/glossario/commit/) registra o estado que poderá ser comparado mais tarde. Manter a relação entre esse registro e os testes evita atribuir à versão final uma conferência feita sobre outro conteúdo. ### Dívida técnica: custo futuro de escolhas técnicas - URL: https://promovaweb.com/glossario/divida-tecnica - Descrição: Dívida técnica aumenta o esforço para modificar um sistema. Entenda como reconhecer esse custo, priorizar correções e separar manutenção de reescrita. ## O que é dívida técnica Dívida técnica descreve o esforço adicional que a estrutura de um sistema impõe às mudanças futuras. Esse esforço pode aparecer quando uma alteração pequena exige entender dependências difíceis de localizar ou modificar vários trechos que deveriam continuar coerentes. A metáfora nomeia esse esforço adicional, sem calcular automaticamente as horas ou o dinheiro necessários para corrigir a estrutura. Para usá-la no projeto, mostre qual trabalho se repete, quais arquivos precisam mudar juntos e por que a implementação atual exige essa manutenção. ## Reconhecer o custo na próxima alteração Uma proposta de reescrita precisa apontar uma dificuldade observada na manutenção. Se a verificação de telefone obrigatório foi copiada para vários cadastros, tornar o preenchimento opcional exige localizar todas as cópias e conferir quais entradas devem receber essa alteração. Nem toda repetição representa o mesmo problema. Um cadastro para envio por SMS precisa de telefone, enquanto uma assinatura de newsletter pode exigir apenas email. Unir essas verificações só porque o código se parece pode fazer uma mudança na newsletter afetar indevidamente o envio de SMS.

Uma mudança no produto torna o telefone obrigatório no cadastro pela tela, na importação e na API. Cada caminho contém uma cópia da validação, e uma atualização altera apenas a tela.

A importação e a API continuam aceitando cadastros sem telefone que a tela já recusa. Você precisa corrigir os três caminhos e avaliar se eles podem chamar a mesma validação. A leitura das colunas da planilha, por exemplo, continua sendo uma etapa própria da importação.

## Entender como a estrutura chegou a esse estado Uma entrega pode adotar uma solução provisória com limitações conhecidas. No exemplo dos cadastros, a duplicação pode ter sido mantida para concluir uma primeira versão. Registre onde estão as cópias, por que permaneceram separadas e qual mudança exigirá reexaminar essa estrutura, para que a manutenção seguinte encontre a justificativa e seu limite. Outras dificuldades aparecem depois que o produto muda ou o domínio fica mais compreendido. O diagnóstico deve considerar esse aprendizado, sem presumir que toda estrutura inadequada resultou de pressa ou descuido. ## Escolher uma correção proporcional Comece pelo trecho que atrapalha uma mudança necessária e compare o esforço de reorganizá-lo com a manutenção que ele continuará exigindo. Código antigo pouco alterado pode permanecer adequado, mesmo sem seguir a preferência técnica atual. Uma lista de melhorias sem vínculo com o trabalho previsto dificulta essa comparação. Descreva a ocorrência concreta, como três arquivos que precisam mudar juntos, e delimite o resultado esperado da correção. ## Conferir se a manutenção ficou mais simples A [refatoração](/glossario/refatoracao/) pode reduzir o custo ao reorganizar o código e preservar seu comportamento. Depois do ajuste, confira os caminhos existentes e observe se a próxima mudança realmente exige menos duplicação ou investigação. Para examinar uma validação espalhada pelo projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite investigar o código com orientação ao vivo. Você opera o editor e pode trabalhar na delimitação e na verificação do ajuste durante a sessão. ### DNS: associação de nomes a registros - URL: https://promovaweb.com/glossario/dns - Descrição: DNS associa nomes a registros usados para localizar serviços. Entenda consultas, cache e por que resolver um nome não comprova que a aplicação funciona. ## Definição DNS é o sistema distribuído que associa nomes a registros. Quando você acessa um serviço pelo nome, uma consulta pode fornecer o [endereço IP](/glossario/endereco-ip/) necessário para iniciar a comunicação, sem que esse endereço precise aparecer na URL digitada. ## Resolvedores e servidores autoritativos O resolvedor recursivo procura a resposta para o cliente e pode reaproveitar uma resposta armazenada. O servidor autoritativo publica os registros da zona sob sua responsabilidade, por isso sua resposta pode diferir daquela guardada pelo resolvedor. O tipo solicitado também importa: A informa IPv4, AAAA informa IPv6 e MX identifica servidores de correio. Um CNAME aponta para outro nome, que ainda precisa ser resolvido até o registro procurado. ## Por que a mudança pode demorar a aparecer As respostas podem ficar em [cache](/glossario/cache/) durante o prazo indicado pelo TTL. Clientes que consultaram em momentos diferentes podem observar valores diferentes enquanto as respostas antigas continuam válidas. Reduzir o TTL depois de alterar o endereço não encurta retroativamente o prazo de uma resposta já guardada. Por isso, uma migração precisa considerar os valores publicados antes da troca e o período de convivência entre os destinos.

Uma consulta ao servidor autoritativo mostra o endereço novo, mas o resolvedor usado pelo seu computador ainda devolve o anterior. Essa diferença explica por que seus testes continuam chegando à instalação antiga.

Antes de modificar novamente o registro, você compara as respostas e o TTL restante. A aplicação nova pode estar funcionando enquanto parte dos clientes ainda utiliza informações anteriores.

## Separar resolução e acesso Uma resposta correta do DNS não comprova que a aplicação aceita conexões. Depois da resolução, o cliente ainda precisa alcançar o serviço e estabelecer a comunicação que a aplicação espera. Abrir o IP diretamente no navegador também pode mudar o teste: o nome participa da seleção do site e da validação do certificado. Ao comparar destinos, preserve o hostname esperado pela aplicação para manter essas condições do acesso original. ## Aplicação no seu projeto Registre o nome consultado, o tipo de registro e o resolvedor usado antes de comparar resultados. No exemplo da migração, isso permite localizar qual consulta ainda retorna o endereço antigo. Se a consulta já retorna o destino esperado, prossiga para a conexão e o atendimento desse destino. Se precisar investigar o acesso à sua aplicação com acompanhamento, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar essa configuração no seu ambiente, com orientação técnica. ### Dockerfile: instruções para construir uma imagem - URL: https://promovaweb.com/glossario/dockerfile - Descrição: Dockerfile descreve a construção de uma imagem. Entenda instruções, contexto de build, comando inicial, cache e cuidados com arquivos e credenciais. ## O que é um Dockerfile Dockerfile é um arquivo de instruções usado para construir uma imagem de container. Ele descreve como preparar os arquivos e a configuração que servirão de base à execução, incluindo a origem do ambiente e o comando previsto para iniciar a aplicação. O arquivo participa do [build](/glossario/build/), mas não representa uma aplicação em execução. Depois de alterá-lo, você precisa gerar outra imagem e criar ou atualizar os containers que usarão esse resultado. ## Instruções de construção e de execução A instrução `FROM` define a base de uma etapa, e `COPY` copia arquivos para a imagem. `RUN` executa comandos durante o build, como instalar uma dependência. Já `CMD` fornece o comando ou os argumentos padrão usados na execução, conforme sua combinação com `ENTRYPOINT`. Essa diferença explica por que uma imagem pode ser construída e falhar apenas ao iniciar. Declarar um comando em `CMD` não o executa durante o build nem comprova que o arquivo indicado estará disponível no ambiente final. Se houver `ENTRYPOINT`, confira também quais argumentos ele receberá.

O Dockerfile copia o projeto, mas declara como comando inicial a execução de outro arquivo. A construção termina porque a declaração do comando não inicia a aplicação.

Ao criar o container, o runtime não encontra o arquivo indicado e encerra o processo. Confira se servidor.js está na imagem e se o comando efetivo aponta para seu caminho. Depois da correção, construa outra imagem e teste a inicialização de uma instância com esse resultado.

## Quais arquivos entram no contexto de build O conjunto de arquivos do build fica disponível ao processo de construção. Na cópia padrão com `COPY`, os arquivos vêm desse conjunto. Um caminho válido no computador não fica automaticamente disponível se estiver fora dele ou tiver sido excluído. A origem muda quando você usa `COPY --from`: os arquivos podem vir de outra etapa, de uma imagem ou de uma fonte de arquivos nomeada. Essa opção permite copiar o resultado compilado de uma etapa anterior sem incluir todas as ferramentas de compilação na imagem final. O arquivo `.dockerignore` permite deixar conteúdo fora do contexto de build. Confira suas exclusões para evitar enviar arquivos desnecessários e para não remover, por engano, um modelo de email ou outro recurso que a aplicação precisa encontrar depois. ## A ordem influencia o cache Uma etapa pode reaproveitar um resultado anterior quando suas entradas continuam compatíveis com o cache. Alterar um arquivo usado cedo na construção pode exigir refazer etapas posteriores, mesmo que apenas uma parte do projeto tenha mudado. Separar a preparação de dependências da cópia de arquivos alterados com frequência pode reduzir trabalho repetido. A organização, porém, precisa respeitar os arquivos realmente exigidos por cada etapa, incluindo manifestos e arquivos que fixam versões. ## Algumas instruções registram configuração Nem toda instrução adiciona uma camada de arquivos. Algumas definem informações que serão usadas ao criar o container, como diretório de trabalho, variáveis e comando padrão. EXPOSE informa uma porta prevista pela imagem, mas não a publica no host. A aplicação precisa escutar no endereço adequado e a execução precisa configurar o acesso pela rede conforme o uso desejado. ## Credenciais não pertencem à construção distribuída Um segredo copiado para a imagem pode permanecer recuperável em camadas, mesmo que uma instrução posterior remova o arquivo. Argumentos e variáveis de build também não devem ser usados como promessa de sigilo para credenciais. Quando o build precisa acessar um recurso privado, use o mecanismo de segredos oferecido pela ferramenta e confira se os comandos não gravam o valor na saída. Esse acesso temporário não substitui a configuração de credenciais necessárias quando a aplicação estiver em execução. ## Validar a imagem produzida Construa a imagem, confira os arquivos esperados e inicie uma instância em teste com as opções necessárias. Leia a mensagem de encerramento e os logs se a aplicação parar, pois o erro pode estar no comando, no conteúdo ou em uma dependência externa. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode orientar uma investigação delimitada de Docker ou deploy ao vivo. Leve o Dockerfile e a diferença observada entre a construção e a execução, preservando as credenciais do projeto. ### Domínio: nome numa hierarquia da internet - URL: https://promovaweb.com/glossario/dominio - Descrição: Domínio é um nome na hierarquia do DNS. Veja a relação entre domínio, subdomínio, registro, hospedagem e os endereços usados para acessar uma aplicação. ## Definição Domínio é um nome organizado na hierarquia do [DNS](/glossario/dns/). Ele permite identificar uma parte dessa estrutura e associar nomes a serviços, sem obrigar você a divulgar os endereços de rede usados por cada instalação. ## Ler o nome por suas partes Em `api.example.com`, `com` corresponde ao domínio de topo, `example.com` está abaixo dele e `api.example.com` é um subdomínio. Os pontos separam os níveis, mas acrescentar um nível não cria automaticamente um servidor ou uma aplicação. Você pode usar nomes distintos para o site, a API e um painel administrativo, mesmo que os três sejam atendidos na mesma máquina. Também pode manter um único nome enquanto a infraestrutura distribui o atendimento entre várias máquinas. ## Registro, DNS e hospedagem Registrar um domínio permite administrá-lo conforme as condições do registro, incluindo sua renovação. Para publicar uma aplicação, ainda é necessário configurar os registros DNS e preparar o serviço que receberá as conexões. Essas funções podem estar em fornecedores diferentes. Mudar a hospedagem não altera automaticamente o DNS, e transferir o registro para outro fornecedor não significa mover os arquivos do site.

O nome com www chega ao site, enquanto o nome sem www não tem o atendimento necessário. A publicação de um deles não configurou automaticamente o outro.

Você confere os registros dos dois nomes, os nomes cobertos pelo certificado e a configuração do servidor. Se escolher um endereço principal, o outro precisa de um redirecionamento correspondente.

## Onde o domínio aparece na URL Uma [URL](/glossario/url/) informa mais que o domínio: ela pode especificar protocolo, porta, caminho e parâmetros. Alterar o caminho de uma página não exige criar um novo domínio, porque essa parte normalmente é interpretada pelo serviço após a conexão. A organização por nomes também não concede permissão de acesso. Um painel publicado em um subdomínio pouco divulgado continua precisando dos controles adequados para suas operações. ## Conferir uma publicação Quando o endereço falhar, verifique qual nome foi usado e quais registros ele apresenta antes de investigar o servidor. Se o nome resolver, prossiga para conexão, certificado e resposta da aplicação, sem atribuir toda falha à configuração de domínio. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar essa conferência no seu projeto, relacionando os nomes publicados à configuração que atende cada um. ### Embedding: representação numérica de conteúdo - URL: https://promovaweb.com/glossario/embedding - Descrição: Embedding representa conteúdo por números usados em comparações. Entenda similaridade, compatibilidade entre vetores e limites da busca semântica. ## O que é um embedding Embedding é uma representação numérica que codifica características de um conteúdo num espaço vetorial. Ela pode ser usada para comparar itens e procurar aproximações relevantes para uma tarefa, como encontrar documentos relacionados a uma pergunta. Em aplicações de texto, um modelo transforma cada trecho numa sequência de números. A busca compara a representação da consulta com as representações armazenadas e ordena candidatos conforme a medida de similaridade escolhida. ## Interpretar a proximidade numérica A proximidade indica semelhança segundo o modelo e a medida utilizados. Ela pode aproximar expressões diferentes sobre o mesmo assunto, mas não demonstra que um trecho responde corretamente à pergunta. O significado da pontuação também depende do mecanismo de busca. Um número alto não deve ser tratado como percentual universal de confiança ou como comprovação de que dois textos são equivalentes.

A pergunta consulta como instalar uma biblioteca. A busca retorna um trecho sobre remover essa mesma biblioteca, com o nome correto e vários termos relacionados ao gerenciador de dependências.

O resultado trata do software correto, mas descreve a ação contrária. A aplicação precisa examinar o procedimento antes de utilizá-lo numa resposta sobre instalação.

## Gerar representações compatíveis Os vetores de consulta e de documentos precisam seguir uma configuração compatível com o modelo utilizado. Dimensão igual não basta, pois modelos diferentes podem atribuir significados diferentes às posições numéricas. Alguns modelos também distinguem a preparação de consultas e documentos. Ao trocar o modelo ou sua configuração, confira a documentação e avalie se os vetores armazenados precisam ser gerados novamente. ## Preservar o trecho e sua origem O embedding não substitui o armazenamento do conteúdo que será apresentado ou fornecido ao modelo de linguagem. Mantenha a associação com o documento, sua versão e o trecho correspondente para conferir o resultado da busca. Quando a fonte muda, uma representação antiga pode continuar recuperando conteúdo que já perdeu validade. Atualização e remoção precisam alcançar o índice, além do arquivo original. ## Avaliar a busca com perguntas conhecidas Compare os resultados com trechos que realmente atendem às perguntas, incluindo casos com palavras parecidas e condições diferentes. A [recuperação de informação](/glossario/recuperacao-de-informacao/) pode combinar busca vetorial com outros mecanismos quando a tarefa exige correspondências específicas. Para investigar uma busca que retorna documentação semelhante, mas inadequada, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite examinar a indexação e os resultados com orientação ao vivo. Você pode conferir a origem dos trechos e os casos usados na avaliação. ### Endereço IP: identificação lógica de uma interface de rede - URL: https://promovaweb.com/glossario/endereco-ip - Descrição: Endereço IP identifica interfaces na comunicação entre sistemas em rede. Entenda IPv4, IPv6 e os limites de usar um IP para localizar um serviço. ## Definição Endereço IP é uma identificação lógica usada para encaminhar tráfego entre interfaces de rede. Ele participa da localização da origem e do destino da comunicação. No mesmo endereço, serviços diferentes podem atender em portas distintas, como um servidor SSH e uma aplicação web. Uma máquina pode ter vários endereços, associados a interfaces ou configurações diferentes. Na comunicação com um serviço TCP ou UDP, você também precisa considerar o protocolo e a [porta](/glossario/porta-de-rede/). ## IPv4 e IPv6 IPv4 usa endereços de 32 bits, normalmente escritos como quatro números separados por pontos. IPv6 usa 128 bits e uma representação hexadecimal com grupos separados por dois-pontos, permitindo um espaço de endereçamento maior. As duas versões podem coexistir na mesma máquina. Se uma aplicação funciona por IPv4 e falha por IPv6, a investigação precisa considerar os registros DNS, as rotas e o atendimento configurado para cada versão. ## Público, privado e fixo Endereços IPv4 privados, como `192.168.1.10`, podem ser reutilizados em redes distintas e não são roteados globalmente na internet. Eles também podem participar de redes interligadas por VPN, desde que o roteamento e a organização dos endereços permitam essa comunicação. Um endereço público não torna toda aplicação acessível. O firewall pode recusar o tráfego, e o processo pode atender somente no loopback, sem receber conexões pela interface pública. Já um endereço fixo descreve uma atribuição estável, que pode existir tanto em uma rede privada quanto no acesso público.

Cada notebook usa um endereço privado na rede local. O roteador pode traduzir as conexões por NAT, fazendo a API observar o mesmo endereço público de origem para os dois.

Se você usar somente esse IP para identificar um perfil, confundirá acessos diferentes. A aplicação precisa de uma identificação apropriada, como a sessão autenticada, para associar cada chamada ao perfil correto.

## O endereço não comprova o atendimento Um [domínio](/glossario/dominio/) pode apontar para vários IPs, e um IP pode atender vários sites. A seleção do site e a validação de seu certificado podem depender do hostname informado pelo cliente. Ao investigar uma falha, confira o endereço de destino, a versão do protocolo e a porta utilizada. Testar um IP diferente daquele resolvido pelo cliente pode levar você a examinar uma máquina que nem participou da tentativa original. Registre também a origem do teste. A conexão feita no próprio servidor pode usar um caminho diferente da conexão feita pelo seu notebook. Se uma funciona e a outra falha, compare a interface atendida e o tráfego permitido entre essas origens e o destino, mantendo o mesmo protocolo e a mesma porta. Se precisar acompanhar esse caminho entre seu computador e o servidor, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação no ambiente do seu projeto. ### Endpoint: ponto de acesso a uma operação ou recurso - URL: https://promovaweb.com/glossario/endpoint - Descrição: Endpoint é um ponto de acesso de um serviço remoto. Entenda endereço base, caminho, método e parâmetros ao configurar ou investigar uma chamada de API. ## O ponto de acesso de um serviço Endpoint é um ponto de acesso a um recurso ou função de um serviço. Em uma API HTTP, ele é identificado por um endereço, e o método participa da definição da operação. A documentação pode usar a palavra para o endereço ou para a combinação de método e caminho. Quando você configura uma integração para consultar contatos, precisa saber qual endereço recebe essa consulta. Conhecer apenas o domínio não define como chamar o serviço. O caminho, o método e as exigências do contrato completam a requisição. Considere uma API fictícia com base em `https://api.example.com/v1`. O caminho `/contatos/42` pode identificar o contato 42 nessa versão. A URL completa permite localizar o recurso, enquanto `GET` expressa a intenção de consultá-lo. ## Endereço base, caminho e parâmetros O endereço base costuma reunir esquema, host e um prefixo comum, como a versão da API. O caminho acrescenta a localização específica do recurso. Parâmetros podem selecionar um registro ou ajustar uma consulta, conforme a estrutura documentada. Em `/contatos/42`, o identificador faz parte do caminho. Em `/contatos?pagina=2`, a página está na consulta da URL. Trocar essas posições não preserva automaticamente o significado, porque a aplicação precisa reconhecer a forma recebida. Essas convenções são exemplos, sem uma forma única de nomear recursos. Uma API pode usar outros caminhos ou atender recursos diferentes no mesmo endereço. Você precisa seguir o contrato do serviço real. ## O endpoint não descreve todo o contrato Além do endereço e do método, uma chamada pode exigir autenticação, campos obrigatórios e cabeçalhos específicos. A documentação também precisa explicar as respostas possíveis. Um endereço correto com conteúdo incompatível ainda pode resultar em recusa.

O serviço oferece um endereço base de testes e outro de produção. O caminho da consulta é semelhante, mas as credenciais e os registros disponíveis podem ser diferentes. A integração precisa combinar o ambiente e a credencial correspondentes.

Se o contato 42 existe apenas no ambiente de testes, consultá-lo em produção pode retornar ausência mesmo com o caminho correto. Confira o endereço base utilizado e procure o registro no ambiente correspondente.

Um endpoint acessível não significa que qualquer perfil autenticado possa usá-lo. O servidor ainda precisa verificar a identidade e a permissão para o recurso solicitado. O identificador de um registro não deve funcionar como autorização. ## Como investigar uma chamada recusada Confira primeiro o endereço completo, incluindo host, prefixo de versão e caminho. Depois, compare o método e os parâmetros com a documentação. Evite testar operações de alteração apenas para descobrir qual verbo é aceito. `404` pode indicar rota ou recurso ausente, além de uma política que não revela sua existência. `405` indica que o método não é permitido naquele recurso e deve vir com os métodos aceitos em `Allow`. Esses códigos são pontos de partida para conferir o contrato. O verbete de [método HTTP](/glossario/metodo-http/) explica como a finalidade da chamada se combina com o endereço acessado. ### Entidade: conceito do domínio com identidade própria - URL: https://promovaweb.com/glossario/entidade - Descrição: Entidade representa um conceito do domínio com ocorrências identificáveis. Entenda identidade, atributos e a relação entre modelo, tabela e registro. ## Um conceito reconhecido pelo sistema Entidade é um conceito do domínio representado no modelo do sistema e cujas ocorrências precisam ser identificadas. Pessoa, curso e matrícula podem ser entidades de uma aplicação de ensino. O modelo descreve seus atributos e relações antes de escolher todos os detalhes de armazenamento. A identidade permite acompanhar a mesma ocorrência ao longo de mudanças. Uma correção de nome pode preservar o identificador do cadastro. O sistema precisa distinguir essa continuidade de dois cadastros diferentes que possuem nomes semelhantes. O uso exato do termo varia entre técnicas de modelagem. Em modelagem relacional, é comum falar no tipo de entidade e em suas ocorrências. Em Domain-Driven Design, a identidade persistente é central para distinguir entidade de objeto de valor. ## Começar pelo comportamento que precisa ser representado Imagine uma escola que oferece várias turmas do mesmo curso. Curso descreve o conteúdo oferecido, turma identifica uma edição com datas próprias e matrícula relaciona um estudante a uma turma. Tratar os três como uma única linha pode dificultar alterações independentes. Você identifica os conceitos perguntando o que precisa ser acompanhado ao longo do tempo. Uma nova turma não é apenas uma troca de nome do curso anterior. Ela pode ter inscrições, datas e participantes próprios, que devem continuar identificáveis.

O estudante de identificador 7 participa de uma turma neste semestre e de outra no seguinte. O cadastro continua representando o mesmo estudante, enquanto as matrículas representam vínculos distintos.

Se o telefone for corrigido, o sistema pode atualizar o cadastro sem recriar as matrículas. Informações históricas de uma matrícula podem exigir preservação separada, conforme a política de registros do produto.

## Entidade, registro e tabela Tabela é uma estrutura de armazenamento, e registro é uma linha concreta nessa estrutura. Uma entidade do modelo pode ser persistida em uma tabela, mas a correspondência não precisa ser de um para um. Herança, histórico e outras necessidades podem distribuir sua representação. Também existem tabelas técnicas que não representam diretamente um conceito principal do negócio. Uma tabela de controle de migrations, por exemplo, atende à operação do software. Ler todas as tabelas como se fossem entidades comerciais produziria um modelo confuso. ## Identidade e atributos Atributos descrevem a entidade, enquanto a identidade distingue sua ocorrência. Usar um nome como identificador pode falhar porque nomes mudam e se repetem. No exemplo da escola, o identificador 7 permite consultar o mesmo cadastro após a correção do nome e preservar suas matrículas. Nem todo conjunto de atributos precisa virar uma entidade. Em determinados modelos, um valor é comparado por seu conteúdo e não possui identidade própria. A aplicação define essa representação pelo uso do conceito, sem considerar apenas o número de campos. ## Como conferir o modelo Percorra situações reais do produto e verifique se cada ocorrência pode ser identificada sem ambiguidade. Teste mudanças de atributos, múltiplos vínculos e preservação de histórico. Se uma correção de nome exige recriar relações, pode haver confusão entre identidade e descrição. Depois, confira como o armazenamento representa essas necessidades. O verbete de [relacionamento](/glossario/relacionamento/) detalha as associações entre os conceitos e suas quantidades permitidas. ### Entrega contínua: versões validadas e prontas - URL: https://promovaweb.com/glossario/entrega-continua - Descrição: Entrega contínua mantém versões prontas para publicação. Entenda artefatos, validação, aprovação e o que precisa permanecer disponível até o deploy. ## O que é entrega contínua Entrega contínua é a prática de manter mudanças verificadas e preparadas para serem disponibilizadas em produção. A preparação acompanha o desenvolvimento, de modo que publicar uma versão não exija descobrir naquele momento como gerar e instalar o resultado. A passagem para produção pode depender de uma autorização manual. Essa autorização escolhe quando executar um procedimento preparado, sem precisar transformar cada publicação numa sequência improvisada de comandos. ## Da integração ao artefato disponível A [integração contínua](/glossario/integracao-continua/) verifica o código combinado, enquanto a entrega inclui a preparação e a validação da versão que poderá ser instalada. O artefato precisa estar identificado e disponível no local usado pelo deploy. Guardar a relação entre revisão, artefato e resultados dos testes permite conferir o que está sendo autorizado. Se o arquivo testado foi substituído ou removido, a aprovação anterior não comprova o conteúdo do novo arquivo.

O pipeline prepara uma imagem e testa a jornada de inscrição em staging. Depois da conferência, a autorização libera o deploy daquela imagem identificada em produção.

A etapa de deploy usa a referência preservada, em vez de buscar qualquer imagem associada a uma tag mutável. Assim, você consegue relacionar a versão instalada ao resultado examinado na aprovação.

## Pronta para instalar exige mais que o build Uma aplicação pode compilar e ainda falhar ao acessar o banco ou interpretar uma configuração do destino. A preparação precisa cobrir as funções relevantes e as dependências exigidas pela mudança, incluindo a compatibilidade de alterações persistidas. O ambiente de teste também tem limites de representação. Uma amostra pequena pode não revelar o tempo necessário para atualizar muitos registros, então essa diferença precisa ser considerada ao preparar o procedimento de produção. ## A espera pode alterar as condições Entre os testes e a publicação, credenciais podem expirar, artefatos podem sair da retenção e o ambiente pode receber outras alterações. Uma versão preparada anteriormente precisa continuar acessível e compatível quando sua instalação for autorizada. Confira essas condições antes de executar o deploy, principalmente depois de uma espera prolongada. O histórico deve mostrar qual resultado foi aprovado e se houve mudanças que exigem uma nova verificação. ## Entrega contínua e implantação contínua Na [implantação contínua](/glossario/implantacao-continua/), as mudanças elegíveis seguem automaticamente até produção quando atendem às verificações configuradas. Na entrega contínua, o processo pode parar com a versão pronta, aguardando a autorização de publicação. Ambas precisam de acompanhamento depois da instalação e de um procedimento para tratar falhas. Automatizar a preparação não demonstra que uma reversão de código conseguirá desfazer alterações já gravadas no banco. ## Conferir o percurso até produção Escolha uma versão preparada e acompanhe sua identificação desde a revisão de origem até o artefato e o destino de teste. Confira se a etapa autorizada consegue obter esse artefato e se o resultado instalado mantém a mesma identidade. Para acompanhar a evolução desse processo, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a revisão recorrente da infraestrutura. O acompanhamento pode partir das etapas que ainda exigem intervenção improvisada durante cada publicação. ### Escala horizontal: mais instâncias para a carga - URL: https://promovaweb.com/glossario/escala-horizontal - Descrição: Escala horizontal ajusta a quantidade de instâncias que atendem um sistema. Entenda distribuição, estado e réplicas sem garantia de ganho proporcional. ## O que é escala horizontal Escala horizontal é o ajuste da quantidade de instâncias que atendem a um trabalho. Adicionar instâncias é chamado de scale out, enquanto reduzir o conjunto é chamado de scale in. Você pode usar esse ajuste numa aplicação web ou em workers que processam tarefas, mas o serviço precisa conseguir distribuir o trabalho. Criar cópias que continuam sem receber chamadas ou tarefas não amplia o atendimento. ## Distribuir conforme o tipo de serviço Uma aplicação HTTP pode usar um [balanceador de carga](/glossario/balanceamento-de-carga/) para encaminhar requisições. Workers podem obter tarefas de uma fila, respeitando os mecanismos de entrega e conclusão oferecidos por ela. A quantidade declarada também pode diferir da quantidade pronta para trabalhar. Uma instância recém-criada ainda pode estar iniciando ou aguardando configuração, então o ajuste precisa conferir disponibilidade efetiva.

Os uploads são salvos apenas no disco da primeira instância. Depois de adicionar duas, algumas consultas são encaminhadas a uma cópia que não possui o arquivo solicitado.

A ampliação expõe a dependência do armazenamento local. A aplicação precisa tratar o acesso aos anexos e a persistência antes de considerar as três instâncias equivalentes para esse atendimento.

## O estado precisa continuar coerente Sessões, arquivos e tarefas em andamento precisam de tratamento compatível com a distribuição. Isso pode envolver um armazenamento compartilhado, particionamento ou outro desenho que defina qual instância atende cada parte. Usar o mesmo banco não resolve automaticamente todos esses aspectos. A aplicação ainda precisa lidar com alterações simultâneas, repetição de tarefas e informações mantidas apenas na memória de uma instância. ## Dependências podem limitar o ganho Mais instâncias podem abrir mais conexões com o mesmo banco ou enviar mais chamadas à mesma API. Se essa dependência já está no limite, aumentar o conjunto pode intensificar a espera e os erros. Instâncias no mesmo host também compartilham recursos físicos. Compare capacidade, duração e falhas sob carga semelhante para verificar quanto do ganho esperado realmente apareceu no serviço. ## Ajustar e reduzir exigem tempo Uma política automática reage às medidas disponíveis e aos tempos de avaliação definidos. Instâncias levam tempo para iniciar, e oscilações frequentes podem criar um ciclo de criação e remoção sem atender bem à demanda. A redução precisa considerar trabalho em andamento e estado local. Retirar uma instância sem permitir concluir ou recuperar suas tarefas pode produzir interrupções que o número menor de requisições não justifica. ## Conferir o resultado do ajuste Acompanhe quantas instâncias ficaram prontas, como receberam trabalho e o que mudou nas dependências. No exemplo dos anexos, consulte o mesmo arquivo pelas três instâncias e confira as respostas. Compare também o consumo e as requisições atendidas por cada uma para identificar cópias prontas que ainda não recebem trabalho. Para revisar capacidade e comportamento conforme a demanda varia, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode acompanhar a infraestrutura. A [escala vertical](/glossario/escala-vertical/) oferece outra forma de ajustar recursos, com condições diferentes de aplicação. ### Escala vertical: mais recursos em uma instância - URL: https://promovaweb.com/glossario/escala-vertical - Descrição: Escala vertical ajusta os recursos de uma instância. Entenda CPU, memória, interrupções possíveis e como conferir se a aplicação aproveitou a mudança. ## O que é escala vertical Escala vertical é o ajuste dos recursos disponíveis por instância, como CPU e memória. A ampliação é chamada de scale up, e a redução é chamada de scale down. O serviço recebe uma instância com outra capacidade, em vez de necessariamente distribuir o trabalho por mais cópias. A plataforma pode ajustar o recurso existente ou exigir sua substituição, conforme o tipo de mudança. ## Identificar o recurso que limita o atendimento Uma aplicação pode ficar lenta por falta de memória, espera de disco ou chamadas demoradas a outro serviço. Aumentar a memória disponível não reduz, por si só, o tempo que uma API externa leva para responder. Relacione o recurso a alterar à etapa que limita a tarefa antes de dimensionar a mudança. Confira as medidas junto do comportamento que precisa melhorar. CPU baixa não descarta uma restrição a um único processador, e memória livre não explica uma consulta que aguarda resposta de uma dependência externa.

A máquina recebe mais memória, mas o container continua com o limite anterior. O processo ainda é encerrado quando ultrapassa esse limite, apesar da capacidade adicional disponível no host.

A investigação precisa conferir a configuração aplicada ao processo. O aumento da infraestrutura, sozinho, não altera necessariamente as restrições usadas pela aplicação.

## Mais processadores não garantem ganho proporcional Um trabalho que executa principalmente numa única sequência pode não aproveitar todos os processadores acrescentados. Outras partes podem continuar limitadas pelo banco ou pela velocidade de leitura do armazenamento. Compare o mesmo tipo de tarefa antes e depois da mudança, incluindo duração e quantidade de falhas sob carga semelhante. No exemplo do container, confira se ele reconhece o novo limite e se conclui a tarefa que antes provocava seu encerramento. O plano contratado e o resultado da execução precisam ser conferidos separadamente. ## A alteração pode exigir interrupção Certas plataformas exigem parar ou recriar a instância para mudar seu tamanho. O procedimento precisa considerar o tempo de retorno, as conexões em andamento e os efeitos sobre endereços e armazenamento. Na alteração documentada de tipo de instância EC2 com volume EBS, por exemplo, é necessário parar a instância. Esse comportamento não deve ser generalizado para toda plataforma, mas mostra por que a conferência do procedimento antecede o ajuste. ## Reduzir também exige conferir compatibilidade Uma redução de memória pode deixar a aplicação sem espaço para picos que não apareceram numa amostra curta. Observe períodos representativos e os limites mínimos exigidos pelo sistema e pelos serviços instalados. Armazenamento pode ter condições diferentes de CPU e memória, inclusive ausência de redução direta. Confira o método suportado para cada recurso, sem presumir que toda ampliação pode ser desfeita pelo mesmo caminho. ## Avaliar o resultado na aplicação Depois do ajuste, confira os recursos reconhecidos pelo sistema e os limites efetivos dos processos. Acompanhe a tarefa que motivou a mudança para verificar se o tempo de resposta e a estabilidade melhoraram. A [escala horizontal](/glossario/escala-horizontal/) trata do número de instâncias e pode exigir outro desenho de distribuição. Para acompanhar essas escolhas com base no consumo e no comportamento observado, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a revisão recorrente da infraestrutura. ### Especificação (spec): descrição organizada do que será implementado - URL: https://promovaweb.com/glossario/especificacao-spec - Descrição: Spec registra o comportamento e os limites esperados para uma implementação. Entenda como descrever cenários e comparar o código com a entrega prevista. ## Definição Especificação é a descrição organizada do comportamento, das condições e dos limites que uma implementação deve atender. Ela reúne informações suficientes para orientar a construção e permitir que você compare o resultado com o que foi definido. A palavra spec pode designar documentos de escopos diferentes, como uma funcionalidade, uma API ou um protocolo. Em desenvolvimento de produto, o alcance precisa estar explícito para que uma descrição local não seja interpretada como padrão aplicável a todo o sistema. ## Organizar as informações da mudança Uma especificação relaciona os [requisitos](/glossario/requisito/) aos cenários de uso. Para uma exportação, por exemplo, ela pode descrever quais registros entram no arquivo, quais permissões são necessárias e como o sistema informa uma falha. Também é útil registrar o que permanece fora da entrega e quais dúvidas ainda precisam de resposta. Uma lacuna declarada permite buscar a informação, enquanto uma suposição escondida pode chegar ao código como comportamento definitivo.

A descrição inicial fala apenas em exportar contatos. A implementação inclui a página visível, mas você esperava todos os resultados do filtro aplicado.

A especificação precisa definir o alcance do arquivo e o tratamento do filtro. Os testes então conferem uma consulta com mais de uma página, para revelar a diferença que uma lista pequena esconderia.

## Usar a spec com ferramentas de IA Uma ferramenta de código precisa receber a especificação pertinente à mudança e as referências necessárias do projeto. Manter o arquivo no repositório não comprova que seu conteúdo foi consultado ou corretamente interpretado pelo agente. Ao revisar, relacione as alterações aos comportamentos descritos e às [condições de aceite](/glossario/condicao-de-aceite/). Uma resposta textual da IA dizendo que cumpriu a tarefa não substitui a conferência da implementação. ## Investigar divergências e atualizar o registro Quando código e especificação diferirem, confira qual deles representa a necessidade válida. A implementação pode estar errada, o texto pode ser ambíguo ou a necessidade pode ter mudado durante o trabalho. Registre a alteração aprovada e ajuste os testes afetados, mantendo o histórico necessário para explicar o comportamento atual. O documento continua útil quando acompanha a evolução do produto, sem ser reescrito apenas para justificar qualquer resultado produzido. O [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a organização do produto quando ainda faltam definições sobre o alcance da primeira versão e suas integrações. ### Evento: uma ocorrência reconhecida por um sistema - URL: https://promovaweb.com/glossario/evento - Descrição: Evento representa uma ocorrência reconhecida por um sistema. Entenda como ele se diferencia da mensagem enviada, do comando e da reação da automação. ## O que é um evento Evento é a representação de uma ocorrência reconhecida por um sistema, como a confirmação de um pagamento ou a conclusão de um upload. Ele descreve algo que aconteceu e pode fornecer informações para que outras partes da aplicação reajam à mudança. Em uma integração, você pode receber um evento de pagamento confirmado e usar essa informação para liberar uma matrícula. A confirmação pertence ao sistema de pagamentos, enquanto a liberação da matrícula é uma ação posterior da automação que recebeu o aviso. ## A ocorrência, a mensagem e a reação A mensagem transporta a descrição do evento até outro componente. Ela pode chegar por [webhook](/glossario/webhook/) ou por uma [fila](/glossario/fila/), e a reação depende do que o sistema de destino foi programado para fazer com aquele tipo de ocorrência. Essas partes podem ter resultados diferentes. O pagamento pode estar confirmado na origem enquanto a mensagem ainda está em uma tentativa de entrega, ou a mensagem pode ter chegado e a liberação da matrícula ter falhado depois.

O serviço de cobrança registra a confirmação de um pagamento e envia o evento à automação. O workflow recebe a notificação, mas não consegue acessar o sistema de matrículas porque a credencial expirou.

O pagamento continua confirmado. Para concluir a matrícula, você precisa corrigir o acesso e recuperar o processamento da notificação, sem tentar cobrar novamente o aluno.

## Como identificar o que aconteceu Uma mensagem de evento costuma informar o tipo da ocorrência, sua origem e o objeto relacionado. Alguns contratos também incluem um identificador do evento e o horário da ocorrência, permitindo distinguir duas mudanças do mesmo pagamento. O código do pagamento identifica o objeto, enquanto o identificador do evento pode distinguir sua confirmação de um reembolso posterior. Usar apenas o código do pagamento para descartar repetições poderia eliminar o reembolso como se fosse uma segunda entrega da confirmação. A especificação [CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md) padroniza atributos para descrever eventos, mas nem toda integração adota esse formato. Você precisa consultar o contrato da origem para saber quais campos identificam a ocorrência e qual combinação deve ser usada na [deduplicação](/glossario/deduplicacao/). ## Um aviso do passado pode chegar depois de uma mudança nova O horário de recebimento pode ser diferente do horário da ocorrência. Uma tentativa de entrega atrasada pode chegar quando o objeto já passou por outra mudança, e o conteúdo do evento pode retratar o estado anterior. Também pode haver mais de uma entrega da mesma ocorrência, dependendo do serviço e de sua política de repetição. A documentação da Stripe, por exemplo, orienta a tratar eventos duplicados e não depender da ordem de entrega dos webhooks. No exemplo da matrícula, receber uma confirmação antiga depois de um reembolso exige verificar qual comportamento o processo prevê. Consultar o estado atual na origem pode ser apropriado para sincronizar o acesso, enquanto manter o histórico de ocorrências exige preservar a sequência e o significado de cada evento. ## Evento e comando têm intenções diferentes Um comando solicita uma ação, como liberar uma matrícula. Um evento informa uma ocorrência, como pagamento confirmado, e pode ser observado por mais de uma integração, cada uma com uma reação própria. Ao investigar uma matrícula ausente, confira separadamente a ocorrência na cobrança, as tentativas de entrega e a execução no destino. A ausência no histórico da automação ainda exige verificar filtros, disponibilidade e retenção dos registros antes de concluir que a mensagem se perdeu. ### Execution: uma execução concreta do workflow - URL: https://promovaweb.com/glossario/execution - Descrição: Execution é uma ocorrência do workflow. Veja como entrada, caminho percorrido, status e histórico ajudam a investigar o resultado de uma automação no n8n. ## O que é uma execution Execution é uma ocorrência do processamento de um [workflow](/glossario/workflow/). O workflow define o processo, enquanto a execução corresponde ao que aconteceu com uma entrada em determinado momento, incluindo as etapas percorridas e o resultado alcançado. Duas inscrições recebidas pelo mesmo formulário podem iniciar execuções diferentes. Uma pode criar um contato novo, e a outra pode encontrar o email já cadastrado e seguir por um caminho que atualiza a inscrição existente. ## O que observar no histórico O histórico de execuções do n8n permite localizar ocorrências pelo status ou horário. Ao abrir um registro mantido pelo workflow, você pode examinar os detalhes disponíveis das etapas e comparar a entrada recebida com o resultado de cada Node. A disponibilidade depende das configurações que mantêm ou removem registros e protegem os campos. A ausência de um registro antigo não demonstra, sozinha, que o workflow nunca executou. Um histórico também pode ocultar campos sensíveis e preservar o status sem mostrar a entrada completa. Para relacionar uma execução ao fato que a originou, preserve um identificador adequado ao processo. Se o formulário, a execução e o contato gravado carregam o código da inscrição, você pode procurar esse mesmo valor nos três locais. Horários próximos ajudam a localizar o intervalo, mas podem reunir inscrições diferentes. ## Execuções manuais, parciais e de produção Uma execução manual começa por uma ação no editor e permite acompanhar o fluxo durante o desenvolvimento. A execução parcial restringe o teste a uma parte do workflow, embora possa precisar executar etapas anteriores para obter a entrada do Node escolhido. As execuções de produção começam automaticamente pelos triggers configurados. No n8n, informações fixadas para teste com data pinning podem ser usadas durante o desenvolvimento, mas são ignoradas em produção, onde as etapas buscam as entradas reais. Por isso, um teste com uma resposta fixa de consulta não comprova que a integração está acessível naquele momento. Ao conferir o fluxo completo, observe quais resultados vieram de serviços externos e quais foram fornecidos apenas para desenvolver a automação.

A execução encontra o contato e tenta enviar uma confirmação. O serviço de mensagens recusa a chamada porque a credencial usada não tem a permissão necessária.

O Node de envio mostra a recusa, mas você ainda precisa comparar a credencial e a permissão exigida. Alterar o texto da mensagem não corrige esse problema de acesso.

## Status concluído e resultado do processo O status da execução descreve como o workflow terminou segundo seu tratamento de erros. Se uma falha foi encaminhada para um caminho alternativo que registra a inscrição para correção, a execução pode concluir sem que a confirmação tenha sido enviada. Você precisa comparar o status com o efeito esperado no sistema de destino. No exemplo da inscrição, isso significa verificar se o contato foi criado, atualizado ou apenas separado para revisão, e não interpretar todos esses resultados como equivalentes. ## O cuidado ao executar novamente Uma execução que falhou no final pode ter realizado ações nas etapas anteriores. Antes de repetir o processamento, confira se já houve cadastro ou envio, pois uma nova tentativa não desfaz automaticamente a anterior. Quando o mesmo evento pode ser processado novamente, o workflow deve reconhecer os efeitos já concluídos. A [idempotência](/glossario/idempotencia/) permite planejar essa repetição sem transformar uma tentativa de recuperação em duplicação de cadastros. ### FAQ: perguntas frequentes que respondem dúvidas comuns - URL: https://promovaweb.com/glossario/faq - Descrição: FAQ reúne perguntas frequentes para responder dúvidas comuns. Entenda pergunta, resposta objetiva, atualização e o uso em páginas e aplicações. ## O que é uma FAQ FAQ é a sigla de Frequently Asked Questions, perguntas frequentes. É uma seção que reúne as dúvidas comuns sobre um produto, serviço ou assunto, com respostas diretas e objetivas. O objetivo é responder rapidamente quem procura ajuda. Em vez de abrir um atendimento ou ler uma documentação inteira, o usuário encontra a pergunta que corresponde à sua dúvida e a resposta que resolve. ## Pergunta e resposta objetiva Uma FAQ funciona quando a pergunta reflete a dúvida real e a resposta entrega o necessário. A pergunta costuma ser formulada como o usuário faria, e a resposta direta resolve sem rodeios. A resposta curta atende ao propósito. Detalhes e exemplos podem ficar em links. Uma resposta longa em uma FAQ dificulta a leitura e desvia do objetivo de resolver rápido a dúvida.

Usuários perguntam repetidamente como exportar os dados do produto. A resposta está espalhada na documentação, e o atendimento recebe as mesmas solicitações todos os dias.

Você adiciona essa pergunta à FAQ com a resposta direta. Você encontra a resposta na página antes de procurar atendimento individual.

## FAQ na página e na aplicação A FAQ aparece em páginas de suporte, em [landing pages](/glossario/landing-page/) e junto do produto. O conteúdo pode ser marcado com dados estruturados, como FAQPage, para que mecanismos de busca apresentem as perguntas e respostas na própria pesquisa. Em aplicações com IA, a FAQ também pode alimentar o contexto de um assistente. As perguntas frequentes ajudam o modelo a responder com base nas dúvidas reais do público. ## Manter a FAQ atualizada Dúvidas mudam conforme o produto evolui. Uma pergunta que não existe mais deve sair, e novos problemas devem entrar. Revisar a FAQ com regularidade mantém o conteúdo alinhado com o uso real. As dúvidas que chegam pelo atendimento são a melhor fonte de novas perguntas. Se a mesma solicitação se repete, ela provavelmente merece uma resposta na FAQ. Para estruturar a FAQ da sua página ou usar as perguntas no contexto de uma aplicação com IA, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção e na manutenção do conteúdo. ### FIFO e LIFO: as ordens de retirada de uma fila - URL: https://promovaweb.com/glossario/fifo-lifo - Descrição: FIFO e LIFO descrevem a ordem de retirada de itens de uma fila. Veja a diferença entre primeiro a entrar e último a entrar, e quando cada ordem atende um caso de uso. ## O que são FIFO e LIFO FIFO e LIFO descrevem a ordem de retirada de itens de uma [fila](/glossario/fila/). FIFO significa primeiro a entrar, primeiro a sair, enquanto LIFO significa último a entrar, primeiro a sair. A escolha define qual item o worker recebe primeiro. A ordem é uma propriedade do mecanismo de fila, não uma garantia automática. Alguns serviços entregam apenas uma ordem aproximada, enquanto outros preservam a ordem exata. O contrato da ferramenta informa qual comportamento está disponível. ## FIFO preserva a ordem de chegada Na ordem FIFO, os itens são retirados na mesma sequência na qual chegaram. O primeiro job enviado é o primeiro processado. Essa ordem é usada quando a sequência de chegada importa, como processar eventos na ordem na qual ocorreram. O FIFO não garante a ordem de conclusão. Dois jobs retirados em sequência podem terminar em tempos diferentes quando executados por workers paralelos. A fila conduz a retirada, e o worker define o tempo de cada execução.

Três eventos chegam em sequência e a fila os entrega na mesma ordem. O worker processa o primeiro, depois o segundo e o terceiro.

Se os eventos fossem retirados fora da ordem, uma atualização poderia sobrescrever outra. A ordem FIFO preserva a sequência de chegada, mesmo que a conclusão de cada um varie.

## LIFO prioriza o item mais recente Na ordem LIFO, o item que chegou por último é retirado primeiro. O mecanismo funciona como uma pilha, na qual o topo recebe a retirada. Essa ordem atende casos nos quais a versão mais recente substitui as anteriores. Um exemplo é uma lista de tarefas na qual a solicitação mais nova deve ser atendida primeiro. A ordem LIFO faz o último item enviado ir para a frente, enquanto os anteriores aguardam a vez. ## Ordem de retirada não é ordem de conclusão Nos dois casos, a fila controla a retirada, e o worker controla a execução. Uma fila FIFO pode ter itens que terminam fora da ordem quando há paralelismo. Uma fila LIFO pode ter o mesmo comportamento. Para revisar a ordem de processamento do seu fluxo e o comportamento dos workers, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise da fila e da concorrência junto à implementação. ### Fila: mensagens e tarefas à espera de processamento - URL: https://promovaweb.com/glossario/fila - Descrição: Fila mantém mensagens ou tarefas aguardando processamento por outro componente. Entenda consumidores, confirmações e limites de ordem e repetição. ## O que é uma fila Fila é uma estrutura ou serviço que mantém mensagens e tarefas disponíveis para processamento posterior. Um componente produz o trabalho, enquanto outro o consome quando tem capacidade, separando o momento da chegada do momento da execução. Em uma aplicação de relatórios, várias solicitações podem chegar durante a manhã, mas a geração dos arquivos pode ocorrer gradualmente. A fila mantém o trabalho aguardando, e os [workers](/glossario/worker/) executam os [jobs](/glossario/job/) conforme sua disponibilidade e configuração. ## Receber uma tarefa não significa concluí-la O ciclo de processamento depende da ferramenta. Algumas filas reservam uma mensagem para um consumidor durante certo período e aguardam que ele confirme a conclusão ou remova a mensagem depois de executar o trabalho. No Amazon SQS, por exemplo, o tempo de invisibilidade mantém a mensagem temporariamente fora das consultas dos demais consumidores. Se o processamento não terminar e a mensagem não for removida antes do fim desse período, ela poderá voltar a ficar disponível. Essa possibilidade exige cuidado com efeitos externos. Um worker pode ter enviado um email e perdido a conexão antes de confirmar a tarefa, fazendo uma nova tentativa receber a mesma mensagem sem saber, apenas pela fila, se o envio anterior aconteceu.

As solicitações são registradas na fila, e os workers geram os arquivos gradualmente. Você acompanha o tempo de espera para saber quando uma exportação recém-chegada poderá começar.

Se a chegada continuar acima da capacidade durante horas, a fila continuará crescendo. Ela preserva a espera conforme suas garantias e limites, mas não cria a capacidade necessária para produzir os relatórios.

## Ordem de retirada e ordem de conclusão A ordem oferecida pela fila precisa ser confirmada no contrato do serviço. Uma fila standard do Amazon SQS, por exemplo, pode entregar mensagens repetidas e fora da ordem de envio, enquanto outros tipos oferecem garantias diferentes. Mesmo que duas tarefas sejam retiradas na ordem A e B, a tarefa B pode terminar primeiro se ambas forem executadas simultaneamente e A demorar mais. Quando uma atualização depende da anterior, essa dependência precisa ser tratada no desenho do processamento. ## A espera tem limites Uma fila pode ter prazo de retenção, limite de tamanho ou políticas para mensagens que falham repetidamente. Essas configurações determinam por quanto tempo o trabalho ficará disponível e o que acontecerá com uma tarefa que nenhum consumidor consegue concluir. O conteúdo da mensagem também precisa continuar utilizável durante a espera. Se ela contém apenas um endereço temporário de arquivo, por exemplo, o worker pode receber a tarefa depois de o endereço expirar, mesmo que a fila tenha preservado a mensagem corretamente. ## Como identificar uma fila que deixou de avançar Observe a idade das mensagens junto com a quantidade de itens aguardando e a taxa de conclusão. A espera pode crescer por ausência de workers, fila pausada, lentidão no destino ou repetição de tarefas que falham, e cada causa exige uma conferência diferente. Escolha uma tarefa identificável e acompanhe sua entrada, o início do processamento e o resultado no destino. Se houver nova tentativa, verifique como a [idempotência](/glossario/idempotencia/) evita duplicar o efeito já produzido, em vez de usar apenas a redução do tamanho da fila como sinal de conclusão. ### FormData: o formato de envio de dados de um formulário - URL: https://promovaweb.com/glossario/formdata - Descrição: FormData organiza o envio de dados de um formulário. Entenda campos, pares de chave e valor, o formato no corpo da requisição e a diferença para o JSON. ## O que é FormData FormData é o formato que organiza o envio dos dados de um [formulário](/glossario/formulario/). Em vez de estruturar o conteúdo em um JSON, o FormData carrega os campos como pares de chave e valor no corpo da requisição. O FormData é comum quando o formulário envia conteúdo direto para o servidor, especialmente com arquivos. O navegador monta o corpo com os campos e os arquivos selecionados, e a requisição leva esse conteúdo ao destino. ## Pares de chave e valor O FormData representa cada campo como um par. O nome do campo é a chave, e o valor digitado é o valor. O corpo da requisição carrega esses pares para o servidor processar. A estrutura permite múltiplos campos. Um formulário de cadastro envia nome, e-mail e telefone como pares. O servidor lê cada chave e usa o valor correspondente. ## FormData e arquivos O FormData também permite enviar arquivos. O campo do arquivo é um dos pares, e o conteúdo é carregado junto. O servidor recebe o arquivo com o contexto do formulário. O envio de arquivos exige o formato correto no corpo. O FormData define o tipo de conteúdo adequado. A integração com um [upload](/glossario/upload/) aproveita o mesmo corpo para campos e arquivos.

Um formulário atualiza dados de um pet e envia uma imagem junto. O campo de texto e o arquivo fazem parte do mesmo envio.

Com o FormData, os campos e a imagem chegam juntos ao servidor. O corpo da requisição carrega o conteúdo, e o servidor processa os dados e o arquivo.

## FormData ou JSON A escolha entre FormData e JSON acompanha o contrato da API. O JSON é estruturado e comum para dados simples. O FormData atende ao envio de formulários com arquivos. O backend define o formato esperado. Conferir a documentação da API evita enviar o conteúdo no formato errado. A requisição correta leva o payload no formato que o servidor entende. Para implementar o envio de formulários e arquivos com o formato certo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção das chamadas. ### Formulário: a interface que coleta dados do usuário - URL: https://promovaweb.com/glossario/formulario - Descrição: Formulário coleta dados do usuário por campos de entrada. Entenda campos, envio, validação e o destino dos dados preenchidos. ## O que é um formulário Formulário é a interface que coleta dados do usuário por campos de entrada. Nome, e-mail, seleção e texto são coletados por elementos que recebem o conteúdo. O usuário preenche e envia. O formulário é o ponto de entrada de muitos dados. Um cadastro, um pedido e uma busca passam por um formulário. A forma como ele é organizado influencia se o usuário completa o envio com facilidade. ## Campos e envio O formulário reúne os campos que o usuário preenche. Cada campo coleta um tipo de conteúdo: texto, número, seleção ou arquivo. O conjunto dos campos define os dados que o formulário entrega. No envio, os dados são coletados e enviados ao destino. O servidor processa o conteúdo e devolve a resposta. O comportamento do envio segue o desenho da aplicação.

Um formulário de cadastro pede nome, e-mail e telefone. O usuário preenche os campos e envia.

Os dados são coletados e enviados ao servidor. O registro é criado com o conteúdo preenchido, e a resposta volta para a interface apresentar o resultado.

## Validar o conteúdo A [validação](/glossario/validacao-de-entrada/) evita que dados incompletos ou incorretos sejam enviados. O formulário confere campos obrigatórios e formatos esperados antes do envio. A validação no navegador orienta o usuário na hora. A validação no servidor também é necessária. O conteúdo pode chegar por outros caminhos, sem passar pela interface. Proteger o servidor contra conteúdo indevido faz parte do [middleware](/glossario/middleware/). ## Formulário claro e acessível Um formulário claro orienta quem preenche. Rótulos identificam cada campo, e o feedback informa erros. Estados de carregamento mostram que o envio está acontecendo. A clareza reduz erros e abandono. Acessibilidade também importa. Campos identificáveis, contraste adequado e navegação por teclado ampliam quem consegue usar. Um formulário acessível entrega o mesmo valor para mais pessoas. Para construir formulários claros e com envio correto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na interface e na integração do envio. ### Framework: estrutura e convenções para a aplicação - URL: https://promovaweb.com/glossario/framework - Descrição: Framework oferece estrutura e convenções prontas para desenvolver aplicações. Entenda seu papel, a relação com bibliotecas e o que precisa ser testado. ## Uma estrutura para desenvolver a aplicação Framework é uma estrutura de software que oferece convenções e componentes para desenvolver aplicações. Ele pode organizar rotas, telas, acesso ao banco ou o ciclo de execução. O alcance varia conforme o framework e o tipo de projeto. Ao criar uma funcionalidade, você utiliza pontos de extensão previstos por essa estrutura. Um framework web pode receber a requisição e chamar o código que você registrou para uma rota. Em uma interface, pode coordenar a atualização dos componentes a partir do estado da aplicação. Isso permite trabalhar sobre mecanismos compartilhados, mas também exige compreender as convenções escolhidas. Um arquivo colocado no local errado ou uma configuração incompatível pode impedir que a funcionalidade participe do ciclo esperado. ## Convenções para rotas, componentes e serviços Uma convenção pode definir onde declarar rotas, como criar componentes ou como registrar serviços. Ela reduz a necessidade de inventar uma organização diferente para cada função. A documentação permite reconhecer o papel de cada parte do projeto. Nem todo framework usa a mesma árvore de pastas ou separa as mesmas responsabilidades. Uma rota pode devolver JSON para outra aplicação, sem renderizar um componente de interface. Consulte as convenções do framework usado e identifique o que cada parte precisa fazer naquele percurso.

Você registra uma rota de consulta e associa o código que seleciona os contatos disponíveis. A estrutura do framework encaminha a chamada para esse código e permite produzir a resposta. A interface apresenta o resultado conforme o formato adotado pelo projeto.

Para limitar o acesso, você utiliza os mecanismos previstos para autenticação e autorização. Teste a consulta com sessões de duas organizações e confira os contatos retornados para cada uma. A rota precisa restringir os registros à organização autorizada para aquela sessão.

## Relação com bibliotecas e runtime Uma biblioteca oferece funcionalidades que seu código utiliza. Um framework tende a coordenar uma parte maior da execução e chamar seu código nos pontos configurados. Na prática, um framework pode incorporar diversas bibliotecas. Runtime é o ambiente que executa o programa. Instalar um framework não substitui a necessidade de uma versão compatível da linguagem e de suas extensões. A documentação de instalação deve informar essa combinação. O framework também pode fornecer ferramentas de build ou comandos de desenvolvimento. Esses recursos pertencem ao conjunto oferecido, mas não tornam todo comportamento específico do produto automático. Cadastro, permissões e integrações ainda precisam de implementação. ## O que verificar no projeto Confira se as convenções ajudam você a localizar uma função e alterar seu comportamento. Uma sequência de camadas sem responsabilidade clara pode dificultar uma mudança simples. A organização deve corresponder às necessidades da aplicação. Antes de atualizar, leia as mudanças de versão e teste os percursos utilizados pelo produto. Uma atualização pode exigir alterações de configuração ou de APIs. O fato de o projeto iniciar não comprova que todas as funções continuam corretas. Para um projeto pequeno, avalie quais recursos serão realmente usados e o trabalho de manutenção introduzido. O tamanho da aplicação sozinho não obriga nem dispensa um framework. A explicação de [biblioteca](/glossario/biblioteca/) permite comparar outra forma de reaproveitar funcionalidades. ### Frontend: a camada da interface - URL: https://promovaweb.com/glossario/frontend - Descrição: Frontend é a camada de interface de uma aplicação. Veja o papel de HTML, CSS e JavaScript, os estados da tela e a relação com as validações do servidor. ## A interface com a qual você interage Frontend é a camada da aplicação que apresenta conteúdo e permite a interação. Na web, inclui a estrutura das páginas, a aparência e o comportamento de elementos como menus e formulários. Também cuida de como a interface comunica carregamento, sucesso e falha. Considere uma tela de cadastro. O frontend apresenta os campos, permite preenchê-los e informa o que falta antes do envio. Depois da resposta do servidor, ele pode mostrar uma confirmação ou orientar a correção de um email recusado. O preenchimento também depende da acessibilidade dos controles. Um campo precisa ter um nome compreensível, receber foco pelo teclado e comunicar erros de forma acessível. Ao testar o cadastro sem o mouse, confira se você consegue alcançar os campos, identificar o erro e voltar ao preenchimento sem perder o que já digitou. ## HTML, CSS e JavaScript HTML descreve a estrutura e o significado dos elementos da página. Um botão, um título e um campo de formulário têm funções diferentes, e a marcação permite que o navegador reconheça essas funções. Escolher o elemento adequado também favorece tecnologias assistivas. CSS define a apresentação, como cores, espaçamento e adaptação a diferentes larguras de tela. JavaScript pode acrescentar comportamento, como atualizar uma lista sem carregar outra página. Nem toda página precisa de JavaScript para entregar seu conteúdo ou enviar um formulário. Uma parte do HTML pode ser produzida no servidor e chegar pronta ao navegador. A renderização no servidor não elimina a existência do frontend: a página entregue continua sendo a interface. Dependendo da arquitetura, o navegador acrescenta interatividade depois do carregamento. ## Validação na tela e no servidor

Você tenta enviar o formulário com o email vazio. A interface informa qual campo falta e permite corrigi-lo antes de chamar o servidor. Essa verificação reduz envios incompletos.

Com os campos preenchidos, o servidor ainda precisa conferir as credenciais. O frontend aguarda o retorno e apresenta o resultado previsto para a autenticação, sem assumir que o preenchimento correto significa acesso autorizado.

Repetir uma verificação de preenchimento nos dois lados pode ser necessário. A validação do frontend orienta a interação, enquanto o servidor precisa validar o que recebe de qualquer cliente. Uma chamada feita por outro programa pode contornar completamente o formulário. Se o perfil autenticado só pode consultar contatos, uma chamada `DELETE /contatos/42` ainda chega ao backend quando outro programa a envia. Confira se a API recusa a requisição e se `GET /contatos/42` continua retornando o contato. Ocultar o botão de exclusão altera a interface, mas não substitui essa verificação. ## A comunicação com o backend Quando usa uma API, o frontend segue o contrato para enviar e interpretar mensagens. Uma mudança interna no backend pode preservar a interface se mantiver esse contrato. Já a alteração de um campo obrigatório pode exigir ajustes nos dois lados. Uma página estática também tem frontend, mesmo sem consultar uma API própria. Ela pode entregar textos e imagens preparados durante o build. A necessidade de comunicação dinâmica depende das funções oferecidas pelo produto. ## Como conferir o comportamento da interface Teste o formulário com campos válidos, campos incompletos e uma resposta de recusa do servidor. Confira se o foco e as mensagens permitem continuar pelo teclado. Simule também uma conexão lenta para observar o estado apresentado durante a espera. Desabilitar temporariamente o botão pode evitar cliques repetidos, mas não garante que o servidor receberá uma única tentativa. Se a confirmação de um cadastro não chegar à tela, repetir o envio pode encontrar um registro já criado. O [backend](/glossario/backend/) precisa reconhecer a repetição conforme o contrato da API, e o teste deve conferir a quantidade de registros produzidos, além da mensagem apresentada. ### Geração de imagens: criar imagens a partir de uma descrição - URL: https://promovaweb.com/glossario/geracao-de-imagens - Descrição: Geração de imagens cria imagens a partir de texto. Entenda descrição, estilo, iteração e a verificação do resultado antes de usar a imagem em um produto. ## O que é geração de imagens Geração de imagens é a criação de imagens a partir de uma descrição em texto. Um modelo recebe a instrução e produz um conteúdo visual que procura corresponder ao que foi pedido, conforme a capacidade do modelo e a configuração utilizada. Essa modalidade amplia o trabalho criativo. Uma ideia descrita em palavras pode se tornar um esboço, uma capa ou uma ilustração sem partir de uma imagem pronta. O resultado, porém, precisa ser revisado antes de ser considerado pronto. ## Escrever uma boa instrução A qualidade da imagem acompanha a clareza da descrição. Informar o assunto, o estilo, a iluminação e o formato esperado orienta o modelo. Uma [instrução](/glossario/prompt/) vaga tende a produzir resultados vagos. O processo costuma envolver iteração. A primeira imagem raramente é a definitiva. Ajustar a descrição e gerar novas versões faz parte do fluxo de trabalho, comparando os resultados com a intenção original.

Você descreve a capa desejada e recebe uma primeira versão. O estilo está distante do que você imaginou, e um elemento aparece deslocado.

Você ajusta a descrição, indica o estilo e gera novas versões. Depois de algumas iterações, a imagem se aproxima da intenção e pode ser revisada para uso final.

## Revisar antes de publicar A imagem gerada pode conter erros ou detalhes que não correspondem ao pedido. A revisão humana compara o conteúdo visual com a intenção e identifica o que precisa ser corrigido ou regenerado. Também é preciso conferir a licença do serviço antes de usar a imagem em um produto comercial. A permissão de uso pode variar conforme a ferramenta, o plano e a finalidade. ## Integração com outras modalidades A geração de imagens conversa com outras capacidades de IA. Um modelo pode descrever uma cena, outro pode gerar a imagem, e outro ainda pode interpretar o conteúdo visual. Combinar modalidades amplia o que é possível construir. Para integrar a geração de imagens ao seu fluxo e revisar o resultado com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a execução e o uso do conteúdo gerado no seu projeto. ### Grounding: resposta ancorada em informações - URL: https://promovaweb.com/glossario/grounding - Descrição: Grounding vincula respostas de IA a informações verificáveis e rastreáveis. Entenda a relação entre afirmação e fonte e os limites da conferência. ## O que é grounding Grounding é a vinculação da resposta de um modelo a informações verificáveis fornecidas para a tarefa. O material pode vir de documentos, resultados de busca ou consultas a sistemas, conforme a aplicação. O conteúdo da resposta precisa corresponder às informações consultadas. Você deve conseguir relacionar uma afirmação ao trecho ou ao resultado que permite confirmá-la. ## Conferir a afirmação e suas condições Uma fonte pode tratar do assunto sem confirmar a conclusão apresentada. Ao examinar a resposta, confira a condição que acompanha a informação, como a versão do produto ou a permissão necessária para executar uma ação. O modelo também pode juntar partes de fontes diferentes e produzir uma conclusão que nenhuma delas afirma. Essa conclusão precisa ser distinguida do conteúdo diretamente informado pelos documentos.

O manual permite exportar relatórios apenas a administradores. A resposta afirma que qualquer perfil pode exportar e inclui o endereço correto do manual.

A referência é real, porém não confirma a orientação. A conferência precisa recuperar a condição de acesso e corrigir a afirmação, mesmo que a busca tenha encontrado a página adequada.

## Distinguir grounding de recuperação A [recuperação de informação](/glossario/recuperacao-de-informacao/) seleciona o material disponível para consulta. O grounding diz respeito ao uso desse material na resposta, sem exigir que ele tenha sido encontrado por busca automática. Você pode fornecer diretamente um trecho e solicitar uma explicação fiel a ele. Já um sistema de [RAG](/glossario/rag/) combina recuperação e geração, mas ainda precisa conferir se o texto produzido preserva o conteúdo recuperado. ## Examinar também a qualidade da fonte Uma resposta pode reproduzir corretamente uma página desatualizada. Nesse caso, existe fidelidade ao trecho, mas a orientação pode não servir à versão atual da aplicação. Confirme origem, data e condições relevantes antes de usar a informação na tarefa. Quando duas fontes divergem, a resposta deve explicitar a diferença ou limitar a conclusão ao que foi possível verificar. ## Preservar o material necessário à conferência Guarde a referência e o trecho fornecido ao modelo para comparar a afirmação com o material disponível naquela execução. No exemplo do painel, isso permite conferir se a exigência de perfil administrador estava presente na entrada. Um link para uma página alterada depois pode não mostrar o mesmo conteúdo, e o registro da entrada, sozinho, não comprova como o modelo interpretou cada trecho. Para revisar um assistente que cita documentação sem respeitar suas condições, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a análise do fluxo. A sessão pode comparar os trechos fornecidos com as afirmações entregues pela aplicação. ### Harness: a camada que transforma um modelo em agente - URL: https://promovaweb.com/glossario/harness - Descrição: Harness é a camada que transforma um modelo em agente, conduzindo chamadas e ferramentas. Veja a diferença entre o modelo e o ambiente que o executa. ## O que é um harness Harness é a camada que transforma um [modelo de IA](/glossario/modelo-de-ia/) em um [agente](/glossario/agente-de-ia/) capaz de executar trabalho. Ele conduz o ciclo de chamadas ao modelo, executa as [ferramentas](/glossario/tool-calling/) solicitadas e gerencia o andamento da conversa. O modelo sozinho produz texto. O harness é o ambiente que permite ao agente ler arquivos, executar comandos, consultar serviços e manter o progresso de uma tarefa com vários passos. A capacidade vem do modelo, e a execução vem da camada ao redor dele. ## O que o harness gerencia O harness cuida do que o modelo não controla. Ele gerencia o histórico e o estado da conversa, aplica políticas de aprovação antes de ações sensíveis e mantém a execução avançando dentro de limites definidos. Aprovações de ferramentas, limites de repetição e condições de parada fazem parte dessa camada. Quando o agente solicita um comando, o harness define se a ação ocorre, se exige confirmação ou se é recusada pelo ambiente.

O modelo solicita a edição do arquivo e informa a mudança pretendida. O harness confere a permissão e executa a alteração, registrando o resultado para a próxima etapa.

A edição aconteceu porque a camada de execução permitiu. Sem o harness, a solicitação do modelo permaneceria apenas uma intenção em texto, sem efeito no projeto.

## Harness, autonomia e especificação O harness participa da [autonomia do agente](/glossario/autonomia-de-agente/). Ele aplica permissões e condições que definem quanto o agente avança sozinho, enquanto o modelo e a instrução determinam a iniciativa. Com uma especificação clara, o agente recebe os limites e os objetivos da tarefa. O harness executa dentro desses limites. A combinação entre instrução, ferramentas, permissões e políticas de parada é o que separa uma resposta interessante de uma execução confiável no projeto. ## Escolher o harness pelo fluxo de trabalho A escolha do harness acompanha o modo de trabalhar de cada usuário. O perfil que prefere delegar e se afastar usa um ambiente que permite maior autonomia. O perfil que acompanha cada passo escolhe uma camada com aprovação em cada ação sensível. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite acompanhar o funcionamento de um harness no seu projeto, com orientação ao vivo sobre ferramentas, permissões e limites de execução. ### Header HTTP: metadados da requisição ou da resposta - URL: https://promovaweb.com/glossario/header-http - Descrição: Header HTTP é um campo de uma requisição ou resposta. Veja as funções de Content-Type, Accept e Authorization e como conferir os cabeçalhos enviados. ## Os campos que descrevem a mensagem HTTP Header HTTP, ou cabeçalho HTTP, é um campo que acompanha uma requisição ou resposta e informa como interpretar ou tratar a comunicação. Cabeçalhos podem declarar o formato do conteúdo, transportar credenciais e orientar o uso de cache. Cada campo tem uma finalidade própria. Ao receber uma resposta com uma imagem, o navegador precisa reconhecer o tipo do arquivo. O cabeçalho `Content-Type` pode declarar `image/png`, enquanto o corpo contém os bytes da imagem. A declaração e o conteúdo precisam ser compatíveis. Esse cabeçalho não é a faixa visual no topo de uma página. O elemento HTML `header` pertence à estrutura do documento, enquanto os headers HTTP fazem parte da mensagem que transporta o documento ou outro recurso. ## Content-Type e Accept têm funções distintas `Content-Type` descreve o formato do conteúdo que acompanha aquela mensagem. Uma requisição pode declarar que envia JSON, e a resposta pode declarar o mesmo formato ou outro. A aplicação deve conferir cada sentido da troca separadamente. `Accept` informa quais tipos de conteúdo o cliente aceita receber. Ele pode ser usado na negociação da representação devolvida, conforme o comportamento do serviço. Solicitar JSON nesse campo não garante que toda resposta, inclusive as produzidas por intermediários, terá esse formato. O trecho apresenta somente três cabeçalhos, sem constituir uma requisição completa. `Authorization` transporta uma credencial fictícia no exemplo. O servidor precisa validar a credencial e conferir o acesso permitido, em vez de aceitar a chamada apenas porque o campo existe. ## Cabeçalhos na prática

Você prepara o corpo JSON e declara seu tipo em Content-Type. A integração inclui a credencial pelo mecanismo previsto na documentação. O serviço recebe os campos e verifica se a chamada pode criar o cadastro.

Se o token estiver vencido, um corpo correto não resolve a autenticação. Se o conteúdo estiver em outro formato, uma credencial válida não corrige sua representação. Cada parte precisa atender ao contrato.

Uma resposta de criação pode indicar em `Location` o endereço do recurso criado, enquanto `Cache-Control` orienta o armazenamento em cache. Ao investigar uma integração, confira os cabeçalhos relevantes junto com o corpo: o identificador pode estar no JSON e o endereço para consulta, em um campo da resposta. ## Nem todo cabeçalho pode ser definido pela página O navegador mantém o controle de campos como `Host` e `Cookie`, que o código da página não pode definir livremente nos cabeçalhos de uma chamada `fetch`. Por isso, copiar todos os campos de uma ferramenta de terminal para o JavaScript pode não reproduzir a requisição. Confira o envio efetivo na aba Network. Na resposta entre origens, um cabeçalho visível na aba Network pode continuar inacessível ao JavaScript. Se a integração precisa ler um campo adicional como `X-Total-Count`, a API pode expô-lo com `Access-Control-Expose-Headers: X-Total-Count`, além de autorizar a leitura da resposta por CORS. Compare o campo recebido com o que o código consegue consultar. Os nomes dos campos HTTP não diferenciam maiúsculas de minúsculas, enquanto os valores seguem a definição de cada cabeçalho. Preserve o conteúdo exigido pelo serviço, especialmente em credenciais, nas quais alterar um caractere pode invalidar a autenticação. ## Como conferir o envio real Abra a seção Headers de uma chamada na aba Network do navegador. Separe os campos enviados dos recebidos e compare-os com a documentação. O que aparece na configuração da aplicação pode diferir do que foi transmitido após a atuação do navegador ou de um intermediário. Ao compartilhar uma captura para investigar o problema, remova tokens e cookies de sessão. Esses valores podem permitir acesso ao perfil autenticado. Para entender a parte transportada junto dos cabeçalhos, consulte [body HTTP](/glossario/body-http/). ### HTML: a estrutura do conteúdo na web - URL: https://promovaweb.com/glossario/html - Descrição: HTML estrutura o conteúdo de páginas web. Entenda elementos, atributos, formulários e semântica em um exemplo que conecta a marcação ao navegador. ## A estrutura e o significado do documento HTML significa HyperText Markup Language, ou linguagem de marcação de hipertexto. Ele descreve a estrutura e o significado do conteúdo de uma página. Um título identifica uma seção, e um link indica o endereço que o navegador pode abrir. Formulários marcam os campos e controles usados para enviar informações. Quando você abre uma página de cadastro, o navegador precisa reconhecer quais partes são campos e qual controle envia o formulário. A marcação fornece essas informações. CSS pode definir a aparência, e JavaScript pode acrescentar comportamento, mas os elementos HTML já oferecem funções próprias. Um link permite navegar, e um botão pode enviar um formulário. Um campo recebe texto, e o navegador já oferece foco e ativação pelo teclado a esses controles quando você escolhe o elemento conforme sua função. ## Elementos, atributos e hierarquia Um elemento é uma parte do documento identificada pela marcação. A tag de abertura pode conter atributos que configuram essa parte. Alguns elementos também têm conteúdo e tag de fechamento, enquanto outros, como `input`, não possuem fechamento separado. A hierarquia indica como os elementos se relacionam, como no formulário que contém rótulos, campos e um botão de envio. Ao interpretar a marcação, o navegador constrói o DOM, uma representação dessa estrutura que ferramentas e scripts podem consultar ou modificar. `} /> No exemplo, `for="nome"` associa o rótulo ao campo identificado por `id="nome"`, enquanto `name="nome"` define o nome usado no envio do valor preenchido. O atributo `required` solicita uma verificação de preenchimento no navegador, mas o servidor ainda precisa validar a entrada recebida. ## O que esse formulário faz

Você preenche o nome e aciona Enviar. O navegador prepara uma requisição POST para o destino indicado no formulário. O backend precisa receber essa chamada e executar o comportamento esperado.

O HTML sozinho não grava o contato no banco nem confirma o cadastro. Sem um backend que receba o formulário e armazene o contato, a página apenas apresenta os campos e envia a requisição ao destino configurado.

O formulário nativo pode funcionar sem JavaScript. A linguagem de marcação também oferece outros comportamentos, como navegação por links e expansão de conteúdo com `details`. A necessidade de scripts depende da interação adicional desejada. ## Semântica e aparência Um título marcado com `h2` informa uma seção do documento. Aumentar uma `div` com CSS pode produzir aparência semelhante, mas não concede automaticamente a mesma semântica. Tecnologias assistivas e ferramentas de leitura utilizam essa estrutura. O navegador também aplica estilos padrão aos elementos. Portanto, a escolha da marcação pode afetar a aparência inicial, mesmo sem uma folha CSS própria. Você pode modificar a apresentação preservando o significado adequado de cada elemento. ## Como conferir o HTML interpretado Na aba Elements, examine a árvore montada pelo navegador. Ela pode diferir do texto original quando há marcação inválida, correções do parser ou alterações feitas por JavaScript. Ver apenas o arquivo fonte não revela necessariamente o estado atual do documento. Confira a associação dos rótulos, a ordem dos títulos e o uso pelo teclado. Um documento sintaticamente aceito ainda pode ter problemas de compreensão ou acessibilidade. O verbete de [CSS](/glossario/css/) explica como a apresentação se aplica à estrutura. ### ID de recurso: o identificador de um elemento específico - URL: https://promovaweb.com/glossario/id-de-recurso - Descrição: ID de recurso identifica um elemento específico dentro de um recurso. Entenda o uso no caminho, a exclusividade do identificador e a referência entre recursos. ## O que é um ID de recurso ID de recurso é o identificador que aponta para um elemento específico dentro de um [recurso](/glossario/recurso/). Enquanto o recurso representa o conjunto, o ID seleciona um elemento: `/pets` é o conjunto, e `/pets/5` é o pet de ID 5. O ID aparece no caminho da chamada e define qual elemento a operação atinge. Sem o ID, a chamada se refere ao conjunto. Com o ID, ela se refere a um elemento específico dentro dele. ## ID e exclusividade O ID precisa distinguir os elementos de um recurso. Cada elemento tem um identificador que o diferencia dos outros. A exclusividade do ID é parte do desenho do recurso. O formato do ID varia conforme a aplicação. Pode ser numérico, textual ou outro tipo. O importante é que identifique o elemento de forma única dentro do recurso. ## ID e autorização O ID aponta o alvo, e a [autorização](/glossario/autorizacao/) controla o acesso. O usuário pode mudar o número no caminho e tentar acessar um elemento que não é dele. A permissão precisa validar a propriedade antes de executar. Quando o recurso pertence a um contexto, o caminho pode incluir a relação. O ID identifica o elemento, e a verificação confirma se ele pertence ao usuário da chamada. O acesso indevido é bloqueado na autorização.

Um usuário acessa uma negociação pelo caminho `/users/5/deals/2`. Ele troca o número para 3 e tenta ver uma negociação que não é dele.

O ID apontou o alvo, mas a autorização precisa confirmar se a negociação pertence ao usuário 5. Sem a verificação, a troca do ID exporia um dado indevido.

## ID e relação entre recursos O ID também conecta recursos. Um [sub-recurso](/glossario/sub-recurso/) aparece dentro do contexto de outro, usando o ID para referenciar o elemento pai. O caminho comunica a relação. A modelagem dos IDs acompanha a realidade do domínio. Um pedido pertence a um usuário, e uma negociação pertence a um contato. O identificador e o contexto no caminho descrevem a relação entre os recursos. Para modelar os IDs e as relações da sua API com segurança, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização e na autorização das chamadas. ### Idempotência: repetição com o mesmo efeito pretendido - URL: https://promovaweb.com/glossario/idempotencia - Descrição: Idempotência preserva o efeito pretendido quando uma ação é repetida. Entenda a diferença entre efeito, resposta, deduplicação e chave de idempotência. ## O que é idempotência Idempotência é a propriedade de uma ação cuja repetição mantém o mesmo efeito pretendido de uma única aplicação. Definir o estado de uma inscrição como confirmada pode ser idempotente, porque repetir essa definição mantém a inscrição confirmada, sem criar outra inscrição. Aumentar um contador em uma unidade tem outro comportamento. Executar esse incremento novamente aumenta o total outra vez, mesmo que o conteúdo da chamada seja idêntico ao anterior. Essa diferença importa quando uma automação precisa repetir trabalho depois de uma falha de comunicação. Você precisa saber se a nova tentativa apenas alcançará o estado esperado ou acrescentará um efeito que já havia acontecido. ## Definir um valor e acrescentar um efeito Uma atualização que define o limite de participantes como vinte pode manter esse valor após várias tentativas equivalentes. Uma atualização que acrescenta vinte vagas, por outro lado, pode aumentar o limite a cada repetição, conforme o contrato implementado. A idempotência pertence à ação completa que você está avaliando. Se a atualização mantém o mesmo estado, mas também envia uma nova confirmação a cada chamada, o envio precisa de tratamento próprio para não se repetir indevidamente.

A primeira tentativa localiza a inscrição I-430 e define seu estado como confirmado. A segunda tentativa aplica a mesma definição à mesma inscrição, que continua confirmada.

Se a automação também envia um certificado, esse envio precisa reconhecer o que já foi realizado. A estabilidade do campo de situação não impede, sozinha, que duas mensagens sejam enviadas.

## A resposta pode mudar Uma ação idempotente não precisa devolver respostas idênticas. Na exclusão de um recurso, a primeira chamada pode informar que ele foi removido, enquanto a seguinte informa que ele já não existe, preservando o efeito pretendido de ausência. Os registros técnicos de cada tentativa também podem ser diferentes. Um servidor pode registrar todas as chamadas em logs sem que isso altere a classificação do efeito solicitado ao recurso, conforme a semântica HTTP. ## Como isso aparece nos métodos HTTP A especificação HTTP define PUT, DELETE e os métodos seguros, como GET, como idempotentes. POST e PATCH não recebem essa garantia geral, embora uma API possa implementar ações específicas com comportamento idempotente. O nome do método não corrige uma implementação que desrespeita seu contrato. Ao integrar um serviço, confira o comportamento documentado e teste o efeito da repetição, principalmente quando a chamada cria registros ou aciona outros sistemas. ## Chave e deduplicação são mecanismos relacionados Uma [chave de idempotência](/glossario/chave-de-idempotencia/) pode permitir que o servidor reconheça tentativas da mesma criação. Esse mecanismo depende de suporte, escopo e retenção no destino, e não é obrigatório para toda ação idempotente. A [deduplicação](/glossario/deduplicacao/) identifica entradas repetidas, mas reconhecer uma entrada não comprova que o trabalho terminou. Uma execução que registrou o evento e falhou antes da ação precisa continuar recuperável. ## Como testar o efeito da repetição Repita a mesma ação sobre o mesmo recurso em um ambiente de teste e compare o estado resultante com o de uma única aplicação. Observe também efeitos adicionais, como arquivos, mensagens e registros criados por etapas seguintes. Inclua uma interrupção depois da ação e antes de registrar a conclusão, pois esse intervalo produz resultados desconhecidos para o cliente. A recuperação deve demonstrar que o trabalho pendente pode terminar sem acrescentar outro efeito já realizado. ### Imagem de container: pacote base para containers - URL: https://promovaweb.com/glossario/imagem-de-container - Descrição: Imagem de container reúne os arquivos usados para criar novas instâncias. Entenda camadas, tags e a diferença entre imagem e execução de um container. ## O que é uma imagem de container Imagem de container é um conjunto preparado de arquivos e configurações usado para criar containers. Ela pode reunir o código da aplicação, bibliotecas e ferramentas necessárias à execução, além de indicar um comando inicial. A imagem é uma base armazenada, enquanto o [container](/glossario/container/) é uma instância criada a partir dela. Baixar a imagem não inicia automaticamente um servidor nem configura todos os serviços externos que a aplicação utiliza. ## Camadas compõem os arquivos disponíveis Uma imagem costuma ser organizada em camadas que registram partes de seu conteúdo. Essas camadas podem ser compartilhadas entre imagens, reduzindo a necessidade de guardar ou transferir novamente arquivos que já estão disponíveis. Ao criar um container, o sistema usa essa base e acrescenta a camada gravável da instância. Uma edição feita ali não altera a imagem original, por isso corrigir um arquivo dentro de um container não distribui a correção aos demais.

Você ajusta esse arquivo dentro do container para investigar uma falha. A aplicação começa a responder, mas o ajuste existe apenas naquela instância.

Quando ela é substituída por outra criada da imagem original, o arquivo antigo volta a ser usado. A correção precisa entrar no processo de construção ou na configuração externa apropriada antes de gerar a próxima instalação.

## Tag é um nome associado ao conteúdo Uma referência como app:1.4.0 usa uma tag para selecionar a imagem. O registry pode permitir que essa associação seja alterada, então dois downloads em momentos diferentes podem obter conteúdos distintos sob o mesmo nome. O digest identifica o conteúdo referenciado e permite conferir qual resultado foi usado. Uma imagem publicada para várias plataformas pode ter uma referência geral e variantes específicas, por isso registre também a plataforma selecionada ao comparar ambientes. ## Plataforma faz parte da compatibilidade Uma imagem construída para uma arquitetura pode não executar diretamente em outra. A disponibilidade de emulação ou de uma variante compatível depende do ambiente e do que foi publicado. Confira o sistema operacional e a arquitetura esperados antes da instalação. Uma falha ao iniciar o executável pode vir dessa incompatibilidade, mesmo que o download tenha terminado e a tag seja a desejada. ## O que deve ficar fora da imagem Arquivos enviados durante o uso e registros que precisam persistir pertencem ao armazenamento da aplicação. A imagem não deve ser tratada como uma cópia atualizada desse conteúdo, pois ela representa o resultado de uma construção específica. Credenciais também exigem tratamento próprio. Copiar um segredo para a imagem pode permitir sua leitura a partir do conteúdo distribuído, mesmo que o arquivo deixe de aparecer na camada final após outra instrução de construção. ## Conferir o resultado distribuído Compare a identidade da imagem com o resultado validado e crie uma instância no ambiente de teste. Confira o comando, a plataforma e uma função que dependa dos arquivos incluídos, porque o nome da tag sozinho não demonstra que a aplicação está correta. Para investigar diferenças entre a imagem construída e o container publicado, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar numa tarefa delimitada com orientação ao vivo. A comparação deve partir do conteúdo e das opções realmente usados no ambiente. ### Implantação contínua: publicação automática - URL: https://promovaweb.com/glossario/implantacao-continua - Descrição: Implantação contínua automatiza o caminho até produção. Entenda mudanças elegíveis, verificações, observação após o deploy e limites da reversão. ## O que é implantação contínua Implantação contínua é a prática de levar automaticamente à produção as mudanças elegíveis que atendem às verificações configuradas. O percurso não exige uma aprovação manual adicional para cada versão depois dessas verificações. Isso não elimina a revisão humana do trabalho. Você pode revisar um pull request antes de integrá-lo, enquanto a automação cuida das etapas posteriores de preparação, instalação e conferência conforme o processo do projeto. ## Definir quais mudanças entram no percurso O pipeline responde aos eventos, branches e condições definidos na configuração. Um commit numa branch de experimento pode executar testes sem acionar o mesmo caminho de publicação usado pelo código integrado. Confira também as dependências entre as etapas. O deploy precisa aguardar as verificações exigidas, pois dois jobs executados em paralelo não estabelecem, por si só, que a publicação depende do sucesso dos testes.

A mudança compila e o pipeline instala a versão. O formulário envia a inscrição sem um campo obrigatório, mas os testes anteriores ao deploy não exercitavam esse envio. A API recusa a inscrição, embora a página carregue normalmente.

Uma verificação controlada após a instalação identifica a falha. O caso exige tratar a versão publicada e acrescentar cobertura para o comportamento ausente, sem interpretar o build bem-sucedido como teste de toda a jornada.

## Os resultados valem para o que foi verificado Cada teste observa um conjunto de entradas e comportamentos num ambiente determinado. A automação pode executar esse conjunto de forma consistente, mas não cria cobertura para funções que ninguém incluiu. Leia quais verificações antecedem a publicação e quais resultados elas exigem. Um comando que continua depois de um erro ou uma etapa opcional pode permitir avançar com uma falha que deveria interromper o percurso. ## Instalar o código e liberar a função Uma versão pode conter uma função desativada por configuração, cuja disponibilidade será ampliada depois. Esse recurso separa a instalação do código da exposição da função, mas precisa ser testado nos estados previstos. Mesmo uma função desativada pode vir acompanhada de mudanças no banco ou em partes compartilhadas da aplicação. A configuração de liberação não substitui a conferência de compatibilidade do restante da versão. ## Acompanhar o serviço depois da mudança Métricas, logs e verificações do percurso atendido ajudam a perceber uma alteração de comportamento após o deploy. A observação precisa relacionar o sintoma à versão instalada, sem atribuir automaticamente toda falha nova à última publicação. O procedimento de recuperação também precisa estar preparado. Uma versão anterior pode ser incompatível com uma migration já executada, e efeitos em serviços externos podem exigir tratamento próprio. ## Conferir o caminho automatizado Em teste, acompanhe uma mudança elegível desde o evento inicial até a identificação da versão instalada. Provoque uma falha controlada numa verificação exigida e confira se o deploy deixa de ocorrer, além de observar o comportamento quando todas passam. A [entrega contínua](/glossario/entrega-continua/) explica como preparar uma versão e tratar as aprovações manuais previstas no percurso até produção. O [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode acompanhar uma revisão da configuração de deploy e dos sinais usados para observar o serviço após a mudança. ### Inferência privada: executar o modelo sem expor o conteúdo - URL: https://promovaweb.com/glossario/inferencia-privada - Descrição: Inferência privada executa o modelo sem expor o conteúdo do cliente. Entenda processamento seguro, criptografia, privacidade no uso e os limites práticos do recurso. ## O que é inferência privada Inferência privada é a execução de um [modelo de IA](/glossario/modelo-de-ia/) com proteções para que o conteúdo do cliente não fique exposto em texto aberto durante o processamento. O objetivo é usar a capacidade do modelo sem abrir mão da confidencialidade dos dados. A [inferência](/glossario/inferencia/) comum envia a entrada ao provedor para produzir a resposta. A versão privada adiciona camadas de proteção para que o provedor ou terceiros não leiam o conteúdo enviado no momento da execução. ## Processamento seguro e privacidade O processamento seguro protege o acesso ao conteúdo durante a execução. A privacidade define quem pode ler os dados e como eles são tratados. Técnicas de proteção buscam manter a entrada e a saída fora do alcance de leitores não autorizados. O resultado pode variar conforme a implementação. Algumas soluções mantêm a execução em ambiente isolado, outras usam proteção por hardware ou métodos criptográficos. A avaliação precisa considerar o que o provedor realmente implementa.

Uma aplicação precisa classificar registros com informações sensíveis. Enviar o conteúdo em texto aberto ao provedor expõe o dado durante o processamento.

Com inferência privada, a execução acontece com proteções que impedem a leitura do conteúdo por quem não deveria acessá-lo. A capacidade do modelo é usada sem abrir o dado em claro.

## Comparar antes de assumir O nome do recurso não comprova sozinho o nível de proteção. Verifique como a entrada é tratada, o que é registrado e quais partes do processo ficam fora do ambiente seguro. O contrato e a documentação determinam a garantia real. Também convém conferir se o resultado é tratado com o mesmo cuidado da entrada. A saída pode conter informação derivada do dado sensível, e a política precisa cobrir o ciclo completo do conteúdo. ## Quando faz sentido usar A inferência privada faz sentido quando o dado exige confidencialidade: informações de saúde, financeiras ou contratuais. Para conteúdo público, o custo e a complexidade das proteções podem não compensar. A escolha combina o valor do dado com o nível de proteção desejado. Uma aplicação com dados públicos pode usar inferência comum, enquanto um fluxo com informação sensível avalia as opções privadas disponíveis. Para revisar o tratamento de dados no fluxo com modelos, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) ajuda a avaliar o uso e a proteção do conteúdo na sua aplicação. ### Inferência: execução do modelo treinado - URL: https://promovaweb.com/glossario/inferencia - Descrição: Inferência usa um modelo treinado para processar uma entrada. Entenda preparação, geração, a diferença para o treinamento e a verificação da saída obtida. ## O que é inferência Inferência é o uso de um modelo treinado para produzir uma saída a partir de uma entrada. Pode resultar numa categoria, numa estimativa numérica ou numa sequência de texto, conforme a tarefa e o modelo executado. Essa execução é uma parte do atendimento da chamada. A aplicação pode buscar registros para preparar a entrada do modelo e, após a execução, precisa interpretar o retorno e verificar se ele pode ser utilizado no fluxo. ## Preparar a entrada antes de executar O modelo precisa receber o formato e as informações esperados pela tarefa. Se um campo necessário for omitido durante a preparação, a execução pode terminar normalmente e ainda produzir um resultado inadequado. Por isso, investigar uma saída incorreta exige conferir o conteúdo efetivamente enviado. O formulário exibido na tela e a entrada recebida pelo modelo podem ser diferentes quando há transformação ou seleção de campos entre essas etapas.

O formulário recebe um título genérico e uma descrição detalhada, mas a integração envia apenas o título ao modelo. A categoria retornada não corresponde ao problema explicado no campo omitido.

Repetir a chamada com esse mesmo conteúdo não recupera a descrição ausente. A investigação precisa conferir a preparação da entrada antes de atribuir toda a falha à capacidade do modelo.

## Usar o modelo não significa treiná-lo novamente Na inferência habitual, os parâmetros aprendidos permanecem fixos. A resposta pode mudar quando você altera o prompt ou fornece outros exemplos, porque o modelo recebe outra entrada, sem que isso represente um novo treinamento. Também existem sistemas que atualizam modelos ao longo do uso, por processos próprios de aprendizado. A existência desses processos precisa ser confirmada na aplicação, sem presumir que toda conversa atualiza automaticamente os parâmetros. ## Execução sob demanda e resultados preparados A aplicação pode executar o modelo quando recebe uma solicitação ou calcular resultados antes para consultas posteriores. No segundo caso, o retorno pode ser rápido porque o trabalho de inferência já ocorreu. Um resultado armazenado precisa ser relacionado à entrada e à versão que o produziram. Quando os registros mudam, devolver uma classificação antiga pode ser inadequado mesmo que ela tenha sido correta no momento do cálculo. ## Conferir qualidade e duração separadamente No exemplo de triagem, use solicitações de teste com encaminhamento esperado conhecido e compare a categoria retornada. Inclua descrições que diferenciem problemas parecidos e confira o conteúdo efetivamente enviado ao modelo. Uma execução rápida que encaminha o atendimento para a categoria errada continua inadequada para essa tarefa. O tempo percebido inclui preparação, espera e processamento, além da transmissão da resposta. Em geração por streaming, receber o primeiro trecho não significa que a resposta inteira terminou. Para investigar uma chamada que devolve resultados inconsistentes, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a execução no editor e no terminal. O trabalho pode comparar a entrada enviada, a configuração utilizada e o retorno que a aplicação recebeu. ### Infraestrutura como código: ambientes descritos em arquivos - URL: https://promovaweb.com/glossario/infraestrutura-como-codigo - Descrição: Infraestrutura como código descreve recursos de ambiente em arquivos revisáveis. Entenda planejamento, aplicação e limites da reprodução de ambientes. ## O que é infraestrutura como código Infraestrutura como código, ou IaC, é a gestão de recursos de infraestrutura por definições que podem ser armazenadas, revisadas e executadas por ferramentas. Esses recursos podem incluir máquinas, redes e armazenamento, conforme a cobertura da solução usada. Você registra como o ambiente deve ser preparado e mantém um histórico das alterações propostas. O arquivo permite revisar a mudança, mas a infraestrutura só é alterada quando um processo a aplica. ## Descrição, planejamento e aplicação Ferramentas declarativas, como o Terraform, trabalham com uma descrição desejada e propõem ações para aproximar os recursos gerenciados dessa configuração. Outras abordagens expressam sequências de procedimentos, portanto IaC não define uma única linguagem ou forma de execução. No Terraform, o plano permite examinar ações propostas antes de aplicá-las. Uma alteração pequena no arquivo pode exigir substituir um recurso, então a leitura precisa considerar o efeito indicado pela ferramenta, além da quantidade de linhas modificadas.

Você altera um atributo imaginando que ele será atualizado na máquina existente. O plano informa que o provedor exige criar outra máquina e remover a anterior.

A publicação da configuração precisa considerar armazenamento e continuidade do serviço. O plano permite perceber essa consequência antes da aplicação, sem assumir que toda edição preserva o recurso atual.

## O ambiente pode mudar fora dos arquivos Uma alteração manual no painel pode deixar o recurso diferente da configuração registrada. Essa divergência, frequentemente chamada de drift, precisa ser analisada para entender se o arquivo deve incorporar a mudança ou se o ambiente deve voltar à configuração prevista. A detecção depende do que a ferramenta gerencia e consegue consultar. Um plano sem ações não comprova o funcionamento da aplicação nem a ausência de diferenças em partes que ficaram fora dessa gestão. ## Reproduzir depende também do destino Os mesmos arquivos podem receber parâmetros diferentes para teste e produção. A criação de uma máquina, por exemplo, pode falhar por falta de quota no destino ou de permissão para usar a imagem especificada. Confira também as dependências que não estão descritas, como um domínio já existente ou uma imagem mantida em outro serviço. Se elas desaparecem, a reprodução pode falhar mesmo com o histórico do repositório preservado. ## Proteger configuração e estado Ferramentas que mantêm um arquivo de estado usam esse registro para relacionar as definições aos recursos gerenciados. A configuração de uma máquina e a identificação da instância existente cumprem funções diferentes nessa associação. O estado pode conter informações sensíveis e precisa de armazenamento e acesso compatíveis com sua função. Ocultar um valor na saída da ferramenta não significa que ele desapareceu dos arquivos persistidos. Separe o tratamento de segredos do versionamento da configuração e confira onde planos, estado e registros da execução são armazenados. ## Conferir o ambiente após aplicar Examine o resultado da aplicação e teste as conexões necessárias ao serviço. Uma execução pode concluir parte das alterações e falhar em outra, exigindo conferir o que já existe antes de repetir o procedimento. O [provisionamento](/glossario/provisionamento/) explica a preparação desses recursos. Para investigar uma divergência entre configuração e ambiente com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar uma tarefa delimitada de infraestrutura. ### Infraestrutura: a base que sustenta a aplicação em execução - URL: https://promovaweb.com/glossario/infraestrutura - Descrição: Infraestrutura é a base que sustenta a aplicação: servidores, rede, armazenamento e serviços. Entenda componentes, ambientes e a relação com o código. ## O que é infraestrutura Infraestrutura é a base que sustenta a aplicação em execução: servidores, rede, armazenamento e os serviços que mantêm tudo funcionando. É o ambiente que recebe o código e o entrega aos usuários. O código define o que a aplicação faz, e a infraestrutura define onde e como ela roda. Sem uma base adequada, uma aplicação bem escrita pode ficar lenta, indisponível ou insegura em produção. ## Os componentes da base A infraestrutura reúne diferentes camadas. O [servidor](/glossario/servidor/) executa a aplicação. A rede conecta os componentes. O armazenamento guarda os dados. Os serviços auxiliares cuidam de tarefas como cache, filas e monitoramento. A escolha dos componentes acompanha a necessidade. Uma aplicação pequena pode rodar em um servidor simples. Um serviço com muitos usuários pode exigir vários servidores, [containers](/glossario/container/) e balanceamento de carga.

O código da aplicação está pronto, mas ainda não existe um servidor configurado para executá-lo em produção. A infraestrutura precisa ser provisionada antes do lançamento.

Você configura o servidor, instala o necessário e faz o deploy. A aplicação passa a estar no ar porque a base foi preparada para recebê-la.

## Infraestrutura e ambientes A aplicação costuma passar por ambientes diferentes: desenvolvimento, teste e produção. Cada um tem sua própria infraestrutura, do ambiente local ao servidor de produção. O comportamento pode mudar entre eles. A preparação da infraestrutura segue o ciclo da aplicação. O [provisionamento](/glossario/provisionamento/) cria os recursos. A manutenção mantém tudo atualizado e seguro. A observação acompanha o funcionamento em produção. ## Infraestrutura como código A configuração da infraestrutura pode ser descrita em arquivos e versionada. A [infraestrutura como código](/glossario/infraestrutura-como-codigo/) permite criar e recriar o ambiente de forma previsível. A base passa a ser tratada com o mesmo cuidado do código. A automação reduz o erro manual. Repetir a criação do ambiente a partir de uma descrição confiável facilita a manutenção e a recuperação. A infraestrutura deixa de depender de configuração feita à mão. Para revisar a infraestrutura do seu projeto e a preparação dos ambientes, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na configuração e na manutenção da base da aplicação. ### Instância: uma execução específica de um sistema - URL: https://promovaweb.com/glossario/instancia - Descrição: Instância é uma execução específica de um sistema ou serviço. Entenda a relação com servidores e máquinas virtuais e a diferença entre vários ambientes. ## O que é uma instância Instância é uma execução específica de um sistema ou serviço. Em vez de descrever o sistema em geral, a instância é a execução concreta dele em um ambiente: um servidor, uma máquina virtual ou um container. A instância roda o sistema de forma independente. Cada execução tem seu estado, sua configuração e seu ciclo de vida. O termo ajuda a falar de uma execução específica dentro de uma infraestrutura. ## Instância e servidor A instância roda sobre um recurso de execução. O [servidor](/glossario/servidor/) é a base que executa. A [máquina virtual](/glossario/maquina-virtual/) entrega um servidor virtual para a instância. O recurso e a execução trabalham juntos. Ao provisionar, você cria uma instância sobre o recurso escolhido. A instância recebe a configuração e passa a executar o sistema. O [provisionamento](/glossario/provisionamento/) prepara essa execução.

Uma aplicação é executada em um servidor. Esse servidor hospeda uma instância do serviço, com a configuração de produção.

A instância atende as chamadas da aplicação. Um reinício recria a execução, e a configuração define o comportamento da instância no ambiente.

## Várias instâncias Uma aplicação pode ter várias instâncias. Cada uma executa o sistema de forma independente. Várias instâncias distribuem carga e aumentam a disponibilidade. O [balanceamento de carga](/glossario/balanceamento-de-carga/) distribui as chamadas entre as instâncias. Se uma instância falha, as outras continuam. A quantidade de instâncias acompanha a demanda. ## Instância e container O [container](/glossario/container/) é uma forma de executar instâncias. Cada container roda uma aplicação de forma isolada. A imagem define o sistema, e a instância é a execução dela. O container torna a instância portátil. A mesma imagem pode gerar várias instâncias em ambientes diferentes. O conceito de instância continua valendo: cada execução é uma instância do sistema. Para configurar e gerenciar as instâncias da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na execução e na manutenção do ambiente. ### Integração contínua: verificações a cada mudança - URL: https://promovaweb.com/glossario/integracao-continua - Descrição: Integração contínua combina mudanças frequentes e verificações automatizadas. Entenda o que um resultado confirma e como investigar falhas no pipeline. ## O que é integração contínua Integração contínua, ou CI, combina a incorporação frequente de mudanças ao código compartilhado com verificações automatizadas. O objetivo é perceber incompatibilidades enquanto as alterações ainda são pequenas o suficiente para investigar sua origem. Executar testes numa branch valida as mudanças isoladas. Se uma branch renomeia um campo usado por outra, integrar com frequência permite descobrir a incompatibilidade enquanto o ajuste ainda envolve poucas alterações. ## O pipeline verifica uma revisão determinada Uma execução pode instalar dependências, gerar o build e executar testes sobre uma revisão identificada do projeto. Eventos como push ou atualização de pull request acionam essa execução conforme a configuração da ferramenta. Confira qual revisão foi testada e quais etapas realmente aconteceram. Um resultado antigo ou uma etapa ignorada por um filtro não demonstra o comportamento da alteração mais recente.

Uma alteração modifica o nome de um campo na resposta da API. Outra acrescenta uma tela que ainda consulta o nome anterior, e ambas passam em testes que usam respostas simuladas antigas.

Ao combinar o trabalho, um teste entre tela e API identifica a incompatibilidade. O caso mostra por que integrar cedo e conferir a comunicação entre componentes complementam os testes isolados.

## Falha registrada e merge impedido são coisas diferentes Uma verificação pode informar falha sem impedir que alguém integre a mudança. No GitHub, as verificações exigidas pela proteção da branch estabelecem condições para o merge, respeitando as permissões e exceções configuradas. Confira essa exigência no repositório, além da existência do workflow. Se um teste indispensável fica opcional, o resultado vermelho pode permanecer visível enquanto a mudança segue para as etapas posteriores. ## O ambiente precisa permitir repetir o resultado Diferenças de versão, dependências ou configuração ajudam a explicar um teste que funciona localmente e falha na automação. O registro da execução deve permitir identificar os comandos, as versões e os parâmetros usados, preservando os segredos. Uma falha intermitente também precisa ser investigada, pois repetir até obter sucesso pode esconder dependência de horário, ordem ou serviço externo. Compare as execuções para descobrir a condição que muda, em vez de tratar o último resultado como explicação dos anteriores. ## Interpretar o resultado e corrigir a causa Leia a etapa que falhou e diferencie erro no código de indisponibilidade do ambiente de testes. Depois do ajuste, execute novamente as verificações sobre a revisão corrigida e confira se os casos relevantes continuam presentes. A [entrega contínua](/glossario/entrega-continua/) amplia esse percurso até a preparação da versão para publicação. Para revisar um pipeline com orientação técnica ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar uma investigação delimitada, como reproduzir uma falha que só aparece na automação. ### Interface: o ponto de contato entre usuário e sistema - URL: https://promovaweb.com/glossario/interface - Descrição: Interface é o ponto de contato entre usuário e sistema. Entenda os elementos de interação, a comunicação com o backend e a diferença entre interface e API. ## O que é uma interface Interface é o ponto de contato entre o usuário e um sistema. Na web, é a página com elementos visuais e de interação: campos, botões, menus e navegação. Por ela, o usuário entende o que pode fazer e recebe o resultado das suas ações. A interface não é apenas o visual. Ela inclui o comportamento da interação: o que acontece quando um botão é clicado, como um formulário responde e como o resultado é apresentado. O visual comunica, e a interação executa. ## Interface e o que está por trás A interface conversa com a aplicação. Ao preencher um formulário, o usuário envia dados que a aplicação processa e devolve um resultado que a interface apresenta. O [frontend](/glossario/frontend/) cuida da interface, e o [backend](/glossario/backend/) cuida da lógica e dos dados. A comunicação entre os dois costuma seguir um contrato. A interface envia uma [requisição](/glossario/requisicao/) e recebe uma resposta. A API define como essa troca acontece. Interface e API são pontos de contato em camadas diferentes.

O usuário preenche o formulário e envia os dados. A interface apresenta o carregamento enquanto a aplicação processa a solicitação.

Quando o resultado chega, a interface atualiza a tela. O formulário é a interface, e o processamento acontece na aplicação por trás dela.

## Interface não é só visual Uma boa interface comunica o que é possível fazer. Rótulos claros, estados de carregamento e mensagens de erro orientam o usuário. A ausência de feedback confunde: um clique sem resposta parece que não funcionou. A interface também precisa ser acessível. Cores, tamanhos e contraste afetam quem enxerga diferente. Uma interface pensada para todos amplia quem consegue usar o produto. ## Quando a interface é outra coisa Nem toda aplicação tem uma interface visual. Um programa de linha de comando ou uma API são pontos de contato sem página gráfica. O termo interface descreve a superfície de interação, qualquer que seja a forma. A escolha da interface acompanha quem usa. Um ser humano pode preferir uma página visual. Outro sistema pode conversar por API. Cada tipo de interface atende a um contexto de uso. Para revisar a interface do seu produto e a comunicação com a aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção e na integração da interface. ### Janela de contexto: limite da interação do modelo - URL: https://promovaweb.com/glossario/janela-de-contexto - Descrição: Janela de contexto limita o conteúdo disponível numa execução do modelo. Entenda histórico, espaço para resposta, excesso de entrada e seleção de trechos. ## O que é a janela de contexto Janela de contexto é a capacidade de conteúdo disponível para o modelo durante uma execução, geralmente expressa em tokens. As condições de uso determinam como entradas, histórico e geração participam desse limite. Na prática, você precisa considerar a chamada completa, não somente a mensagem mais recente. Instruções da aplicação, resultados de ferramentas e documentos selecionados podem ocupar uma parte significativa do espaço disponível. ## Histórico visível e conteúdo enviado Uma interface pode mostrar toda a conversa enquanto envia ao modelo apenas parte dela. A aplicação pode selecionar mensagens, resumir trechos anteriores ou recuperar informações quando forem necessárias. Esses mecanismos permitem continuar o trabalho, mas um resumo pode omitir detalhes relevantes. Quando uma resposta parece ignorar uma exigência anterior, confira se essa exigência ainda está representada na entrada utilizada.

A conversa define que o telefone é opcional para um tipo específico de cadastro. Depois de resumir o histórico, a aplicação conserva a lista de campos, mas omite essa exceção.

O assistente sugere exigir telefone em todos os casos. A revisão precisa recuperar a condição perdida e incluí-la na tarefa atual, em vez de presumir que toda informação visível na conversa permaneceu disponível.

## Reservar espaço para a geração Em muitos modelos, a janela comporta a entrada e a saída da execução, com limites próprios para outros tokens de processamento. O máximo permitido para a resposta também pode ser menor que a capacidade total da janela. Compare os limites de entrada e de geração separadamente ao planejar uma chamada. Uma entrada que cabe sozinha ainda pode deixar espaço insuficiente para o resultado desejado. Consulte os limites correspondentes e confira o motivo de encerramento da resposta antes de tratar um texto interrompido como entrega completa. ## Tratar o excesso conforme a plataforma Uma chamada acima do limite pode ser recusada pela API. Algumas aplicações reduzem ou resumem conteúdo antes do envio, enquanto determinadas condições permitem iniciar a geração e encerrá-la ao atingir a capacidade disponível. Não existe um descarte silencioso universal que funcione da mesma forma em todos os produtos. A integração deve tratar o retorno efetivo e tornar identificável qual material participou da execução. ## Selecionar o que a tarefa precisa Enviar um arquivo inteiro pode ser adequado quando a relação entre seus trechos importa. Em outros casos, selecionar a função alterada e suas dependências permite oferecer informação relevante sem incluir partes desconectadas do trabalho. Caber na janela também não comprova que cada detalhe foi interpretado corretamente. Para revisar como um assistente seleciona arquivos e preserva condições do projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a investigação no editor e no terminal. ### JavaScript: comportamento no navegador e além dele - URL: https://promovaweb.com/glossario/javascript - Descrição: JavaScript executa comportamentos em navegadores e outros ambientes. Entenda eventos, funções e chamadas assíncronas com um exemplo de interface. ## Uma linguagem executada em diferentes ambientes JavaScript é uma linguagem de programação usada em navegadores, servidores e ferramentas. Na interface web, pode reagir a interações, consultar serviços e atualizar o documento. Em outros ambientes, pode processar arquivos, atender requisições ou executar automações. A linguagem oferece construções como variáveis, funções e objetos, às quais o ambiente de execução acrescenta recursos próprios. O navegador, por exemplo, disponibiliza o DOM para interagir com a página, enquanto um runtime de servidor pode oferecer acesso ao sistema de arquivos. Essa diferença significa que um código não funciona automaticamente em qualquer lugar apenas por estar escrito em JavaScript. Uma chamada a `document.querySelector` depende de um documento disponível naquele ambiente. Um script de servidor comum não possui a mesma página do navegador. ## Variáveis, funções e eventos Uma variável associa um nome a um valor que o código pode consultar, enquanto uma função reúne instruções para executar quando for chamada. Um evento representa uma ocorrência, como um clique, à qual o programa pode associar essa função. { mensagem.textContent = 'Preencha o nome para iniciar o cadastro.' }) }`} /> O exemplo pressupõe que os elementos já estejam disponíveis quando o script executar. Ele procura o botão e a área de mensagem, depois associa uma função ao clique. A condição evita acessar elementos inexistentes, mas você ainda precisa conferir se os identificadores correspondem ao HTML. ## Alterar a tela não confirma uma operação

Ao clicar no botão, você aciona a função que altera o texto da área de mensagem. O exemplo termina nessa atualização do documento: não há chamada ao servidor ou gravação de cadastro entre suas instruções.

Para exibir uma confirmação de cadastro, a aplicação precisaria enviar a requisição e interpretar a resposta do servidor. Mostrar uma mensagem de sucesso imediatamente após o clique poderia anunciar algo que ainda não aconteceu.

Ao receber código gerado para uma tela de cadastro, abra a aba Network e acione o envio com valores fictícios. Confira se houve chamada ao backend e se a mensagem apresentada corresponde ao retorno. Uma alteração local do texto pode demonstrar a interface sem ter criado o registro anunciado. ## Operações assíncronas e respostas Chamadas de rede não costumam entregar o resultado imediatamente. JavaScript usa recursos como promises e `async`/`await` para organizar esse processamento. A interface precisa representar a espera e tratar falhas conforme o serviço acessado. Com `fetch`, receber um status HTTP de erro não rejeita automaticamente a promise. Uma resposta `404`, por exemplo, ainda precisa ser examinada pelo código. Já certas falhas de rede impedem a obtenção de uma resposta e seguem outro caminho de tratamento. Links, formulários e controles nativos do HTML oferecem comportamentos que podem atender à interação sem JavaScript adicional. Um formulário com destino e método definidos, por exemplo, pode usar o envio nativo do navegador, desde que o serviço de destino aceite a chamada. ## Como investigar um script que falhou Abra o console e confira a primeira mensagem de erro relevante, incluindo arquivo e linha. Se um seletor não encontrar um elemento, `querySelector` retorna `null`. Verifique o identificador e o momento da execução, em vez de presumir que o clique deixou de existir. Para uma integração, observe também a aba Network. Um script sem erro de sintaxe ainda pode enviar campos incorretos ou interpretar mal uma resposta. O verbete de [frontend](/glossario/frontend/) explica como esses comportamentos participam da interface completa. ### Job: uma unidade de trabalho a executar - URL: https://promovaweb.com/glossario/job - Descrição: Job representa uma tarefa a executar. Entenda sua entrada, seus estados e a relação com filas, workers, novas tentativas e resultados em segundo plano. ## O que é um job Job é uma unidade de trabalho que um sistema precisa executar, frequentemente em segundo plano. Ele representa uma tarefa delimitada, como gerar um relatório de inscrições de determinada turma ou converter um arquivo de vídeo para outro formato. Ao solicitar uma exportação, você pode receber um identificador para acompanhar o processamento sem manter a página esperando pelo arquivo. Esse identificador permite consultar o estado da tarefa e relacionar o resultado à solicitação que a originou. ## A entrada precisa definir o trabalho Um job de relatório pode guardar o código da turma, o período da consulta e o formato de saída. O processo precisa recuperar esses parâmetros quando assumir a tarefa, inclusive depois que você fechar a página. Uma seleção mantida apenas na memória do navegador não estará disponível ao worker. Você também precisa definir se o relatório retratará o momento da solicitação ou o momento da execução. Se o job guardar apenas o código da turma e consultar as inscrições depois, alterações feitas durante a espera poderão aparecer no arquivo, conforme a consulta implementada.

Você solicita a exportação das inscrições da turma T-24. O sistema cria o job com o identificador da turma e informa que o arquivo está aguardando processamento.

Um worker assume a tarefa, consulta as inscrições e grava a planilha. Ao concluir, o sistema associa o endereço do arquivo ao job para que a mesma solicitação possa ser acompanhada até o download.

## Estados e tentativas contam partes diferentes da história Estados como aguardando, em execução, concluído e falho aparecem em sistemas de jobs, mas os nomes e as transições dependem da ferramenta. Também pode haver espera por um horário, por uma dependência ou por uma nova tentativa depois de um erro. Uma tentativa é uma execução do trabalho representado pelo job. A mesma tarefa pode precisar de outra tentativa quando o armazenamento do arquivo estiver temporariamente indisponível, sem que isso represente uma nova solicitação de exportação. O estado falho não prova ausência de efeitos. A planilha pode ter sido gravada antes de uma falha na etapa que registra seu endereço, assim como uma mensagem pode ter sido enviada antes de o sistema conseguir registrar a conclusão. ## Como o job se relaciona com fila e worker A [fila](/glossario/fila/) mantém o trabalho disponível para processamento, e o [worker](/glossario/worker/) executa a tarefa. Criar um job na fila não significa que um processo já começou a produzir o resultado, especialmente quando há outras tarefas aguardando ou nenhum worker disponível. O termo job também aparece em agendadores e outras ferramentas que não seguem exatamente essa estrutura. Para entender um ambiente específico, confira onde a tarefa é registrada, qual processo a executa e como o resultado fica disponível. ## Repetir sem duplicar o resultado Se o job puder ser executado novamente, planeje como reconhecer o resultado já produzido. Uma exportação pode usar um identificador estável de solicitação para associar o arquivo, evitando criar múltiplas versões que a interface não consegue relacionar à mesma tarefa. Essa preparação faz parte da [idempotência](/glossario/idempotencia/), mas não surge apenas por atribuir um nome ao job. O código que grava arquivos, atualiza registros ou envia mensagens precisa respeitar a repetição prevista. ## Como investigar uma tarefa pendente Confira há quanto tempo o job aguarda, se existe uma programação para o futuro e se há workers consumindo a fila correta. Uma fila pausada, uma dependência não concluída ou um limite de processamento também pode explicar a espera. Para um job concluído, confira o resultado concreto, como o arquivo gerado e seu acesso. Para um job falho, compare a tentativa com os efeitos no destino antes de iniciar outra execução. ### Jogo retrô: construir jogos inspirados em gerações antigas - URL: https://promovaweb.com/glossario/jogo-retro - Descrição: Jogo retrô recria o estilo de jogos de gerações antigas. Entenda a proposta, o escopo reduzido e como a IA ajuda a construir jogos simples para aprender e jogar. ## O que é um jogo retrô Jogo retrô é um jogo que recria o estilo visual e técnico de gerações antigas. Gráficos simples, sons característicos e regras diretas remetem aos jogos de arcade e consoles antigos, mas podem ser construídos com ferramentas atuais. O apelo do retrô está na simplicidade. Em vez de um projeto grande, o jogo retrô foca em uma mecânica clara e uma estética definida. Esse escopo reduzido torna o projeto acessível para aprender e para construir em pouco tempo. ## Escopo pequeno, produto completo Um jogo retrô tem começo, meio e fim. A IA pode auxiliar na criação de partes do código, mas o trabalho é iterativo: definir a mecânica, construir a versão, testar e ajustar. O resultado é um produto pequeno que funciona. O escopo pequeno é o grande aliado. Com limites claros, o jogo pode ser terminado e jogado. Projetos ambiciosos demais tendem a ficar incompletos, enquanto um jogo simples concluído entrega a sensação de ter construído algo real.

Você lembra de um jogo simples que jogava quando era criança, mas não encontra mais a versão original. Com a IA, você descreve a mecânica e o estilo desejados.

O projeto começa com uma versão simples. Você testa, ajusta as regras e refina os gráficos até chegar a um jogo funcionando, recriando a experiência que procurava.

## A IA como parceria de construção A IA ajuda a escrever código, sugerir regras e refinar o resultado. Uma [instrução](/glossario/prompt/) clara descreve a mecânica, e a iteração ajusta o que não ficou bom. O jogo cresce em conjunto com a orientação de quem constrói. Testar é parte do processo. Rodar o jogo, jogar e verificar o comportamento permite encontrar falhas que o código sozinho não revela. A revisão do resultado final é indispensável antes de considerar o jogo pronto. ## Por que construir um jogo retrô Construir um jogo retrô é uma forma prática de praticar o desenvolvimento com IA. O projeto pequeno exercita escopo, iteração e teste, habilidades que valem para qualquer produto. E o resultado é algo que se joga. O jogo retrô também é uma porta de entrada para quem quer explorar o que a IA permite fazer. Um conceito simples, uma instrução e algumas iterações podem gerar um jogo jogável e divertido. Para construir o seu jogo retrô com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha o projeto do escopo ao jogo funcionando. ### JSON: dados estruturados em texto - URL: https://promovaweb.com/glossario/json - Descrição: JSON representa valores estruturados em texto simples. Aprenda a ler objetos e listas, distinguir tipos e conferir os campos exigidos por uma API. ## Um formato textual para representar valores JSON, sigla de JavaScript Object Notation, é um formato de texto usado para representar conteúdo estruturado. Ele permite organizar nomes e valores, listas e estruturas aninhadas. APIs e arquivos de configuração usam esse formato para que programas diferentes possam interpretar a mesma representação. Apesar do nome, JSON pode ser usado por programas escritos em diversas linguagens. Uma aplicação em PHP pode produzir o texto, e um programa em Python pode interpretá-lo, desde que respeitem a sintaxe do formato. O significado dos campos também precisa estar combinado no contrato da integração. Imagine uma resposta que descreve um contato e os canais pelos quais ele aceita receber mensagens. JSON permite reunir essas informações em um texto, preservando a diferença entre um nome, um identificador e uma lista de canais. ## Como ler a estrutura As chaves delimitam um objeto, formado por pares de nome e valor. No exemplo, `nome` contém uma string, `id` contém um número e `ativo` contém um booleano. Os nomes dos campos e as strings usam aspas duplas. Os colchetes delimitam uma lista, também chamada de array. A lista `canais` contém duas strings e preserva a ordem dos elementos. O valor `null` representa um valor nulo, cujo significado para o telefone precisa ser definido pelo contrato. JSON também aceita listas de objetos e objetos dentro de outros objetos. Para localizar um campo, você percorre essa estrutura. Um telefone dentro de `contato` não está no mesmo caminho que um telefone colocado na raiz da mensagem. Um documento JSON também pode conter apenas um valor, como `42`, `true` ou `"Ana"`. O formato não exige um objeto na raiz, embora uma API possa exigir essa estrutura para receber os campos de um cadastro. ## Sintaxe válida e cadastro válido

O valor 42 e a string "42" são representações diferentes, embora pareçam semelhantes na leitura. Ambos podem aparecer em um JSON sintaticamente válido. Se a API exige um número, o envio como string pode ser recusado.

Da mesma forma, um objeto sem nome pode ser JSON válido e ainda não atender ao cadastro. Interpretar o texto com sucesso é apenas a primeira conferência, antes de verificar os campos exigidos pela aplicação.

Comentários e vírgulas depois do último elemento não fazem parte da sintaxe JSON. Formatos derivados podem aceitá-los, mas isso não significa que uma API que exige JSON fará o mesmo. Confira o formato exato do arquivo ou serviço utilizado. ## JSON e objeto JavaScript Um objeto JavaScript é uma estrutura em memória. JSON é uma representação textual, que pode ser produzida com `JSON.stringify` e lida com `JSON.parse`. Uma variável que já contém um objeto não precisa ser interpretada novamente como se fosse texto. Funções, `undefined` e instâncias de classes não têm uma representação direta equivalente no formato. Datas costumam ser transmitidas como strings por convenção. Depois de ler o JSON, a aplicação precisa interpretar essa convenção para trabalhar com uma data. ## Cuidados ao trocar valores entre sistemas Identificadores muito grandes podem perder precisão quando interpretados como números em determinadas linguagens. Por esse motivo, alguns contratos usam strings para identificadores numéricos. Preserve o tipo documentado, sem converter um campo apenas por ele conter algarismos. Um campo ausente também não é necessariamente equivalente a um campo com `null`. Em uma atualização, a ausência pode significar “manter o valor”, enquanto `null` pode solicitar sua remoção. Essa diferença pertence ao contrato da API e precisa ser conferida antes do envio. Para investigar um erro, separe a leitura sintática da validação dos campos. O verbete de [serialização](/glossario/serializacao/) explica como o programa produz essa representação e quais valores podem mudar durante a conversão. ### Landing page: página única orientada a uma ação - URL: https://promovaweb.com/glossario/landing-page - Descrição: Landing page é uma página única criada para converter visitantes em uma ação específica. Veja a relação com a oferta e a conferência do resultado. ## O que é uma landing page Landing page é uma página única criada para converter visitantes em uma ação, como cadastro, compra, download ou agendamento. Ela recebe o visitante que clicou em um anúncio, em um email ou em um resultado de busca, e concentra a atenção nesse objetivo. O termo descreve o destino de uma oferta, e a forma visual vem depois. A página alinha o conteúdo ao motivo da visita, remove distrações e conduz o visitante ao próximo passo. A conversão depende dessa coerência entre a promessa e a ação. ## O conteúdo segue a oferta Uma landing page eficiente apresenta a oferta e explica o benefício em linguagem direta. O visitante entende o que recebe, por que recebe e como conclui a ação. Título, descrição e chamada para a próxima ação trabalham juntos. Os elementos técnicos participam dessa leitura. HTML estrutura o conteúdo, CSS apresenta o layout e JavaScript atende as interações. A [estrutura da página](/glossario/frontend/) orienta o visitante, enquanto o [servidor](/glossario/cliente/) recebe e confere a ação enviada.

O visitante chega pelo link de um anúncio, lê a descrição do material e preenche o formulário. O envio registra o contato e libera o acesso ao material.

A página cumpriu o papel de converter. O formulário não era decoração: ele recebeu a informação e o sistema registrou a ação, permitindo conferir quantos visitantes concluíram o cadastro.

## Uma página, um objetivo A landing page foca em uma ação principal. Em vez de abrir vários caminhos, ela mantém o visitante próximo do objetivo e reduz a dispersão. Esse direcionamento facilita a conferência do resultado. A métrica de sucesso acompanha a ação concluída. O número de visitantes que preencheram o cadastro, clicaram no botão ou acessaram o destino mostra se a página está convertendo o que promete. ## Construir e conferir a página A criação de uma landing page combina a descrição do conteúdo com a implementação da interface. Você define a oferta, escreve a copy e constrói a estrutura que apresenta os elementos ao visitante. Para criar ou revisar uma landing page do seu produto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite construir a página com orientação ao vivo, desde a oferta até a conferência do comportamento do visitante. ### Latência: o tempo entre a solicitação e a resposta - URL: https://promovaweb.com/glossario/latencia - Descrição: Latência é o tempo entre a solicitação e a resposta. Entenda a medição, os componentes do atraso e a diferença entre latência e desempenho. ## O que é latência Latência é o tempo entre uma solicitação e a resposta correspondente. Em uma aplicação, mede quanto tempo o usuário espera entre pedir algo e receber o resultado. A latência afeta a experiência. Uma resposta rápida parece natural. Um atraso longo frustra. Para interações, a latência baixa importa. Para tarefas longas, o tempo total pode ser maior sem problema. ## Os componentes do atraso A latência não vem de uma etapa única. A rede, o processamento, as filas e a infraestrutura contribuem. Cada etapa entre a solicitação e a resposta adiciona tempo. Medir onde o tempo é gasto permite agir. Se o atraso está na rede, reduzir o caminho ou usar cache ajuda. Se está no processamento, otimizar o código e a infraestrutura faz diferença. A medição orienta a melhoria.

Uma API demora para responder. O usuário percebe o atraso, mas não sabe onde ele acontece.

A medição mostra o tempo em cada etapa: rede, fila, processamento e resposta. Com o [monitoramento](/glossario/monitoramento/) dos tempos, a etapa mais lenta é identificada e o esforço de melhoria vai para o lugar certo.

## Latência e desempenho Latência e desempenho são conceitos relacionados. A latência mede o tempo de uma solicitação. O desempenho é mais amplo, incluindo também a quantidade de trabalho e o uso de recursos. Reduzir a latência melhora parte do desempenho. A avaliação completa considera também o throughput e a estabilidade. Uma aplicação rápida em um caso pode não sustentar o desempenho sob carga. ## Tempo de resposta e timeout O tempo de resposta se relaciona com o [timeout](/glossario/timeout/). Quando a resposta demora além do limite, a solicitação é encerrada. A configuração do timeout acompanha a latência esperada da operação. Se a latência normal fica próxima do timeout, chamadas legítimas podem ser cortadas. Medir o tempo real ajuda a configurar limites coerentes. A melhoria de latência reduz também a chance de atingir o limite. Para medir e melhorar a latência da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação no monitoramento dos tempos de resposta. ### LLM: modelo de linguagem de grande porte - URL: https://promovaweb.com/glossario/llm - Descrição: LLM é um modelo de linguagem de grande porte. Entenda geração por tokens, uso de instruções, relação com ferramentas e limites das respostas produzidas. ## O que é um LLM LLM significa Large Language Model, ou modelo de linguagem de grande porte. Esse tipo de modelo aprende relações entre unidades de linguagem e pode ser usado para produzir texto, interpretar instruções e transformar conteúdo recebido. Em modelos generativos comuns, a resposta é construída pela produção sucessiva de [tokens](/glossario/token-de-modelo/). O resultado depende da sequência disponível, dos parâmetros aprendidos e da forma configurada para selecionar as próximas unidades. ## Da continuação de texto à resposta de um assistente Um modelo preparado para seguir instruções pode responder a uma tarefa apresentada em mensagens. A aplicação monta a entrada e pode incluir o manual do produto, o retorno de uma ferramenta ou trechos de código que serão considerados na geração. Essa montagem explica por que duas aplicações que utilizam o mesmo modelo podem responder de maneira diferente. Elas podem fornecer instruções distintas, selecionar outros trechos e permitir ações que não estão disponíveis no outro produto.

Você fornece uma função que chama uma biblioteca, mas não inclui a versão instalada. A resposta explica o trecho e sugere um método que existe em outra versão da biblioteca.

A explicação parece coerente, porém o método não está disponível no projeto. Conferir a dependência instalada e executar o caso proposto permite separar uma sugestão plausível de uma alteração utilizável.

## Texto gerado e informação consultada O modelo pode produzir uma resposta sem realizar qualquer consulta externa. Mencionar um endereço ou uma publicação no texto não comprova que a aplicação abriu essa fonte durante a tarefa. Quando existem ferramentas, o sistema pode fornecer seus resultados ao modelo para uma nova resposta. A qualidade dessa resposta continua dependendo da fonte recebida e da interpretação feita, mesmo quando a consulta foi executada corretamente. ## Capacidade e acesso são assuntos separados Alguns modelos aceitam apenas texto, enquanto sistemas multimodais também trabalham com imagens ou áudio. Confira os formatos aceitos pela versão utilizada antes de supor que um arquivo anexado foi interpretado integralmente. A capacidade de sugerir código também não significa autorização para executá-lo. Em um assistente de programação, leitura de arquivos, edição e execução de comandos dependem das ferramentas e permissões concedidas pela aplicação. ## Conferir a resposta no projeto Relacione cada alteração sugerida aos arquivos e às versões realmente utilizados. Uma explicação sobre código pode ajudar a localizar o que precisa de teste, mas a execução do cenário é que permite observar seu comportamento no ambiente preparado. Para revisar código sugerido por um LLM com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar no editor e no terminal durante a sessão. A conferência pode incluir a versão da biblioteca, a alteração proposta e os testes do fluxo afetado. ### Log: registro de eventos de um sistema - URL: https://promovaweb.com/glossario/log - Descrição: Log registra acontecimentos de um sistema. Veja como interpretar mensagens, horários e identificadores, relacionar tentativas e conferir coleta e retenção. ## O que é um log Log é um registro produzido por um sistema sobre algo que aconteceu durante sua execução. Ele pode informar que uma tarefa começou, uma chamada foi recusada ou um arquivo foi gerado, com campos que ajudam a interpretar aquela ocorrência. Uma mensagem isolada mostra apenas o que o componente registrou. Você precisa relacioná-la à tarefa investigada e às outras informações disponíveis, pois o registro de uma falha pode descrever sua consequência sem explicar a causa original. ## Mensagem, horário e identificação O horário situa o evento, enquanto o nome do serviço e o identificador da operação ajudam a encontrá-lo entre muitas execuções. Um nível como INFO ou ERROR indica a classificação usada pela aplicação, cuja convenção precisa ser conhecida. Um formato estruturado permite filtrar campos como `job_id`, `tentativa` e `resultado` separadamente. Ao procurar o mesmo `job_id`, você pode distinguir a primeira tentativa que falhou da segunda que terminou, mesmo que as mensagens tenham sido registradas em horários próximos. Esses nomes são exemplos de campos que a aplicação pode definir.

O log registra que o relatório R-214 foi gerado e que a chamada de envio começou. A mensagem seguinte informa timeout, sem confirmar o resultado do serviço de destino.

Esses registros localizam a etapa cuja resposta faltou. Eles não provam que o destinatário deixou de receber, então a investigação consulta o estado do envio antes de repetir a ação.

## A ordem de chegada pode diferir da ocorrência Mensagens de serviços diferentes podem chegar ao coletor com atraso. Relógios desalinhados e fusos mal interpretados também podem produzir uma sequência aparente que não corresponde ao percurso real. Confira se o campo exibido representa o horário do evento ou o da coleta. Use identificadores e relações entre chamadas para complementar a leitura temporal, especialmente quando vários componentes participam da mesma tarefa. ## Emitir, coletar e preservar Uma aplicação pode escrever na saída do processo, enquanto o ambiente encaminha o conteúdo para armazenamento e busca. A mensagem aparecer no terminal não comprova que ela chegou ao serviço central nem que continuará disponível depois de alguns dias. Filtros de nível, falhas no encaminhamento e políticas de retenção alteram o que você consegue consultar. Ao investigar um intervalo sem registros, confira essas etapas antes de concluir que a aplicação não executou trabalho algum. ## Registre o necessário para investigar Um identificador da tarefa pode permitir localizar a falha sem registrar senhas, tokens ou todo o conteúdo enviado. Campos sensíveis precisam ser omitidos ou tratados de acordo com a finalidade do registro e com as permissões de consulta. Gravar mais mensagens também consome armazenamento e pode dificultar a leitura. Escolha eventos que diferenciem etapas e resultados, preservando os campos necessários para associar uma tentativa à operação correspondente. ## Como conferir a utilidade dos registros Execute uma tarefa controlada e procure suas mensagens no destino usado para investigação. Confira se consegue localizar o início, interpretar o resultado e distinguir uma nova tentativa, inclusive quando simula uma falha. O [trace distribuído](/glossario/trace-distribuido/) pode complementar essa leitura com tempos e relações entre componentes. Para investigar logs de uma aplicação com orientação técnica ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode atender uma demanda delimitada do projeto. ### Loop: repetir operações sobre uma sequência - URL: https://promovaweb.com/glossario/loop - Descrição: Loop repete etapas de um processo sobre itens ou enquanto uma condição permitir. Entenda como definir a parada e tratar falhas durante a repetição. ## O que é um loop Loop é uma repetição de etapas sobre uma coleção de itens ou enquanto uma condição permitir continuar. Cada passagem é chamada de iteração, e o processamento precisa definir qual trabalho será feito nessa passagem e quando a repetição deve terminar. Uma automação pode percorrer inscrições para emitir certificados ou consultar páginas de uma API até receber o sinal de que não há continuação. Nos dois casos existe repetição, mas o primeiro pode conhecer a quantidade de itens desde o início, enquanto o segundo descobre a continuação a cada resposta. ## Repetir sobre uma lista Quando a lista já está disponível, cada iteração pode selecionar um item e aplicar a mesma etapa a ele. O término ocorre quando todos os itens previstos foram tratados, conforme a forma de percorrer a coleção. Isso não determina, sozinho, a ordem de conclusão ou a execução simultânea. Uma implementação pode esperar cada certificado ficar pronto antes de iniciar o próximo, enquanto outra admite várias gerações em andamento, com um limite de [concorrência](/glossario/concorrencia/).

O loop recebe as inscrições A, B e C. Ele gera o certificado de A e depois começa o de B, mas encontra um nome obrigatório ausente nessa segunda inscrição.

Se o erro interromper o workflow, C não será processada nessa execução. Para continuar com as demais, você precisa configurar um tratamento que registre a falha de B e permita avançar, sem marcar seu certificado como concluído.

## Repetir enquanto houver continuação Em uma consulta paginada, a resposta pode trazer um cursor para buscar o próximo grupo de resultados. O loop precisa usar esse cursor na consulta seguinte e terminar quando a API informar que não existe mais continuação. Se a automação repetir sempre o primeiro cursor, ela poderá buscar a mesma página indefinidamente. Conferir apenas se a resposta contém itens não basta quando a condição de término real depende de outro campo do contrato. Um limite adicional de páginas ou de tempo pode interromper uma repetição inesperada, mas atingir esse limite não significa que toda a coleção foi processada. A execução precisa registrar que terminou antes do fim previsto para que você possa investigar e retomar. ## Como o n8n trata os itens Muitos Nodes do n8n já aplicam seu processamento aos itens recebidos, sem exigir um loop desenhado manualmente. Antes de acrescentar uma repetição, confira o comportamento do Node para não repetir uma coleção que ele já processaria inteira. O Loop Over Items permite dividir a entrada em grupos conforme o tamanho configurado. As etapas conectadas processam um grupo e retornam ao componente para continuar, enquanto a saída de conclusão permite seguir depois de terminar os grupos. O [batch](/glossario/batch/) define o agrupamento dos itens, e o loop define a repetição do processamento. Um grupo de dez itens, por exemplo, não informa por si só se as ações internas acontecem simultaneamente ou uma depois da outra. ## Falhas e retomada exigem acompanhamento por item Um resultado geral de falha pode esconder certificados já produzidos antes da interrupção. Recomeçar toda a lista sem reconhecer esses resultados pode repetir arquivos ou notificações de itens concluídos. Acompanhe quais itens terminaram, quais falharam e quais ainda não começaram. Esse registro permite retomar o trabalho conforme a [idempotência](/glossario/idempotencia/) prevista, em vez de presumir que toda execução incompleta deve repetir tudo. ## Como conferir a parada Teste uma lista vazia, uma com um item e outra com três itens quando o tamanho do grupo está configurado como dois. Durante a execução, observe o avanço do índice ou cursor e confira se a etapa posterior ao loop só recebe o resultado quando todas as passagens previstas terminam. Inclua também uma falha no meio da coleção. O teste deve mostrar se o processamento interrompe ou continua e quais itens precisam de recuperação, sem transformar a ausência de erro na última etapa em confirmação de que todos foram concluídos. ### Mapeamento de dados: origem e destino de cada campo - URL: https://promovaweb.com/glossario/mapeamento-de-dados - Descrição: Mapeamento de dados relaciona campos de origem e destino. Veja como conferir nomes, valores ausentes e a associação entre itens de uma integração. ## O que é mapeamento de dados Mapeamento de dados é a correspondência entre campos e estruturas de origem e destino. Ele define, por exemplo, que o nome recebido de um formulário será usado no campo de nome completo do sistema de inscrições, mesmo que as duas ferramentas usem nomes diferentes para esse campo. Você precisa conhecer tanto a entrada quanto o contrato do destino para estabelecer essa correspondência. Dois campos chamados `id` podem identificar objetos diferentes, enquanto `nome_completo` e `name` podem representar a mesma informação em serviços distintos. ## De onde vem cada valor O caminho de origem precisa apontar para o campo correto dentro da estrutura recebida. Um email pode estar diretamente no item ou dentro de um objeto chamado `contato`, e essas duas formas exigem caminhos diferentes na configuração. Considere uma integração fictícia que recebe um cadastro e prepara a inscrição correspondente. O mapeamento abaixo registra a origem de cada campo, preservando o código que identifica a inscrição ao longo do processamento. | Origem | Destino | Significado | | --- | --- | --- | | `inscricao_id` | `externalId` | Código usado para relacionar a inscrição nos dois sistemas | | `nome_completo` | `name` | Nome informado no cadastro | | `contato.email` | `email` | Endereço usado para a confirmação | A tabela não comprova que os valores existem nem que são válidos. Ela mostra a correspondência pretendida, que precisa ser conferida com entradas reais ou amostras representativas antes do envio. ## Ausência, vazio e valor padrão Um campo ausente pode indicar uma entrada incompleta ou uma mudança no formato da origem. Preencher automaticamente com texto vazio nem sempre resolve, pois o destino pode recusar o valor ou interpretar o envio como uma instrução para apagar uma informação existente. Valores padrão só fazem sentido quando representam um comportamento previsto. Um idioma padrão pode ser permitido pelo cadastro, enquanto inventar um email para completar um campo obrigatório impediria que a confirmação chegasse ao destinatário correto.

A integração procurava contato.email, mas a nova resposta usa contato.principal.email. O mapeamento antigo já não encontra o endereço, embora ele ainda exista na resposta.

Ao comparar o corpo recebido com a saída preparada, você identifica a mudança de caminho. A correção precisa atualizar a correspondência e testar também uma entrada sem contato principal.

## Selecionar os campos que seguem adiante No n8n, o Edit Fields permite definir campos e configurar quais informações da entrada permanecem na saída. Essa seleção evita encaminhar conteúdo que a próxima integração não precisa receber, mas também pode remover um identificador necessário às etapas seguintes. Confira o objeto completo produzido pela etapa, incluindo o que foi preservado e o que foi omitido. Um nome corretamente mapeado não compensa a perda do código usado depois para atualizar a mesma inscrição. ## Relacionar listas exige uma identidade comum Quando você combina duas listas, a primeira posição de uma não corresponde necessariamente à primeira posição da outra. Uma consulta pode mudar a ordem, filtrar registros ou não encontrar um dos itens, deslocando a associação baseada apenas na posição. Use a relação definida pelo contrato, como o código da inscrição presente nas duas respostas. Depois de relacionar os registros, a [transformação](/glossario/transformacao-de-dados/) pode ajustar o formato dos valores, mantendo clara a origem de cada informação. ## Como conferir o mapeamento Compare a entrada e a saída com campos preenchidos, ausentes e aninhados, além de listas em ordem diferente. Verifique os tipos e os identificadores usados para atualizar o destino, para que o resultado chegue ao cadastro correspondente. A resposta de sucesso da API comprova apenas que ela aceitou aquela chamada conforme suas verificações. Consulte o registro criado ou alterado para confirmar que o email, o nome e a associação da inscrição ficaram nos campos esperados. ### Máquina virtual: ambiente com sistema operacional próprio - URL: https://promovaweb.com/glossario/maquina-virtual - Descrição: Máquina virtual executa um sistema operacional convidado. Entenda recursos, hipervisor, isolamento e diferenças para containers e servidores físicos. ## O que é uma máquina virtual Máquina virtual, ou VM, é um ambiente de computação que executa um sistema operacional convidado sobre recursos virtualizados. Ela recebe uma representação de processadores, memória, discos e interfaces de rede para executar seus serviços. O hipervisor é a camada que administra essa virtualização. Você trabalha dentro do sistema convidado, enquanto a plataforma controla a relação entre os recursos apresentados e a infraestrutura que os fornece. ## Sistema convidado e host Uma máquina física pode hospedar várias VMs com sistemas operacionais separados. Cada convidado mantém seus processos e configurações, respeitando as capacidades e restrições da plataforma de virtualização. A separação não elimina dependências compartilhadas. Uma indisponibilidade do host ou do armazenamento usado por várias VMs pode atingir todas, mesmo quando seus sistemas operacionais estão configurados corretamente.

Uma VM executa a aplicação e outra mantém o ambiente de testes. Reiniciar o sistema convidado de testes normalmente não exige reiniciar o sistema da aplicação.

Se o host físico perde energia, as duas podem parar. O exemplo distingue a independência dos sistemas convidados da dependência comum da infraestrutura.

## Recursos atribuídos e capacidade observada A quantidade de vCPUs e memória define parte do ambiente disponível, mas não descreve toda sua capacidade. Compartilhamento do processador, limites de armazenamento e condições de rede também influenciam o comportamento da aplicação. Observe o consumo dentro da VM e as informações fornecidas pela plataforma. A lentidão pode vir de uma consulta ou de uma dependência externa, então aumentar a máquina sem localizar a espera pode não melhorar o serviço. ## Diferença para containers Uma VM de sistema executa seu próprio kernel convidado. Um [container](/glossario/container/) Linux convencional isola processos usando o kernel do ambiente que o hospeda, que também pode ser uma VM. As duas formas podem existir juntas, como uma VPS que executa containers de uma aplicação. A escolha depende das necessidades de compatibilidade e isolamento, sem uma substituição obrigatória de uma pela outra. ## Discos e recuperação precisam de atenção própria O armazenamento apresentado à VM pode estar num arquivo, num volume ou em outro serviço da plataforma. Parar, remover ou recriar a máquina pode ter efeitos diferentes sobre esse armazenamento, conforme o procedimento e as opções usadas. Snapshots também têm condições de consistência e dependências de armazenamento. Confira quais partes eles preservam e teste a recuperação, em vez de presumir que a presença de um snapshot cobre qualquer perda do host. ## Conferir o ambiente virtualizado Identifique os recursos atribuídos e confira se o sistema convidado reconhece discos, memória e rede conforme o esperado. Depois, teste a função da aplicação e acompanhe seu consumo para relacionar a alocação ao trabalho atendido. Para revisar o uso de VMs e as dependências do projeto ao longo do tempo, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar o acompanhamento da infraestrutura. A análise deve incluir o comportamento observado e as possibilidades de recuperação. ### Memória: reter informação entre interações com o agente - URL: https://promovaweb.com/glossario/memoria - Descrição: Memória permite reter informação entre interações com um agente. Entenda o que é guardado, como é recuperado e a diferença para o contexto da conversa. ## O que é memória Memória é a capacidade de um sistema reter informação entre interações para uso futuro. Em vez de começar cada conversa do zero, o [agente](/glossario/agente-de-ia/) pode considerar o que já foi aprendido ou informado antes. A memória amplia a continuidade. Um assistente que lembra preferências e histórico entrega respostas mais alinhadas. A retenção, porém, precisa ser desenhada e controlada pela aplicação. ## O que é guardado A memória não é automática. A aplicação decide o que guardar e como recuperar. Preferências, decisões e informações relevantes podem ser armazenadas para uso nas próximas interações. Guardar apenas o que importa reduz o risco. Informação desatualizada ou incorreta, se lembrada, pode orientar uma resposta errada. A revisão do que é retido é parte da manutenção.

O usuário informa que prefere ser chamado pelo primeiro nome e receber resumos no fim do dia. O assistente guarda essas preferências.

Nas próximas interações, o assistente usa a informação lembrada. A memória permite o atendimento contínuo sem que o usuário repita tudo a cada conversa.

## Memória e contexto A [memória](/glossario/memoria/) e o [contexto](/glossario/contexto/) trabalham juntos. O contexto é o que acompanha a entrada atual. A memória fornece a informação retida que pode entrar no contexto quando necessário. A aplicação recupera a memória relevante e a envia no contexto da interação. A [janela de contexto](/glossario/janela-de-contexto/) limita o que pode ser usado de uma vez. Recuperar o que importa aproveita melhor o espaço disponível. ## Retenção e controle A memória envolve controle. O usuário deve saber o que é guardado e ter a possibilidade de revisar ou apagar. Guardar informação sensível sem necessidade amplia a responsabilidade da aplicação. A escolha do que lembrar considera a finalidade. Uma memória útil guarda o que melhora as interações seguintes. Uma memória excessiva guarda dados que podem ficar desatualizados e expostos sem trazer benefício. Para desenhar a memória do seu agente com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a retenção e o uso da informação nas interações. ### Merge: combinação de linhas de desenvolvimento - URL: https://promovaweb.com/glossario/merge - Descrição: Merge integra duas linhas de desenvolvimento no Git em uma só. Entenda fast-forward, conflitos e por que ausência de conflito não garante funcionamento. ## O que é merge Merge é a integração de uma linha de desenvolvimento em outra. No Git, o resultado depende da relação entre os históricos, das alterações existentes e das opções escolhidas para a integração. A branch de destino é aquela que receberá o trabalho. Confira essa direção antes de executar o procedimento, pois integrar a correção na linha principal e atualizar a correção com a linha principal atendem a finalidades diferentes. ## Fast-forward e histórico divergente Quando a referência de destino está num ancestral da origem, um fast-forward pode avançá-la até o commit mais recente sem criar outro registro. Nesse caso, o histórico existente já contém o caminho necessário. Quando as linhas avançaram separadamente, um merge comum combina suas alterações e registra a relação num commit de merge. As opções do comando podem exigir ou impedir determinadas formas de integração.

Uma branch muda o nome de um campo da API e outra modifica uma tela que ainda usa o nome antigo. Como os arquivos são diferentes, o Git pode concluir o merge sem apontar conflito.

A tela integrada falha ao procurar o campo. O resultado exige um teste entre as partes, pois a combinação de texto não interpreta automaticamente a compatibilidade do comportamento.

## Resolver o que o Git não consegue combinar Conflitos podem envolver trechos editados, arquivos removidos ou renomeações. O Git informa as partes que exigem resolução, e você precisa examinar a intenção de cada mudança antes de preparar o resultado. Aceitar um lado inteiro pode apagar uma correção presente no outro. Leia o arquivo final e confira se os marcadores de conflito foram removidos, sem tratar essa remoção como comprovação de que o comportamento ficou correto. ## Preservar o trabalho que já existe Alterações locais anteriores ao merge podem dificultar a integração e sua interrupção. Consulte o status e preserve o trabalho antes de iniciar, principalmente quando os mesmos arquivos podem ser afetados. Se a integração não puder continuar, o procedimento de cancelamento depende do estado encontrado. Não presuma que cancelar reconstruirá perfeitamente edições locais que já estavam misturadas ao processo. ## Conferir o resultado integrado Compare o resultado com os comportamentos que cada branch precisava preservar e execute os testes relevantes. Uma integração concluída informa que o Git produziu o estado solicitado, sem garantir que a aplicação atenda aos casos esperados. O [pull request](/glossario/pull-request/) pode reunir essa revisão na plataforma. Métodos como squash e rebase produzem históricos diferentes do merge comum, então confira a forma escolhida antes de concluir a proposta. ### Método HTTP: a ação solicitada ao servidor - URL: https://promovaweb.com/glossario/metodo-http - Descrição: O método HTTP expressa a ação solicitada ao servidor. Compare GET, POST, PUT, PATCH e DELETE e entenda o efeito de repetir uma chamada sobre o destino. ## A ação expressa pela requisição Método HTTP é o elemento da requisição que expressa a ação pretendida sobre um recurso. `GET`, `POST` e `DELETE` são exemplos. O endereço identifica o destino, e o método participa da definição do que o cliente solicita naquele destino. Ao consultar um contato, você pode usar `GET` em `/contatos/42`. Para solicitar a exclusão, a API pode oferecer `DELETE` no mesmo caminho. A chamada só deve ser feita conforme o contrato, pois trocar o método altera a finalidade da requisição. Os métodos têm significados definidos pelo protocolo, e a implementação precisa respeitá-los. O nome do método não impede, sozinho, um servidor mal implementado de alterar recursos durante uma consulta. Por isso, a documentação e os testes precisam corresponder ao comportamento real. ## Os métodos mais usados `GET` solicita uma representação do recurso. `HEAD` solicita os mesmos cabeçalhos que seriam enviados em uma consulta equivalente, mas sem entregar o corpo. Eles podem ser usados para consultar conteúdo ou suas informações sem solicitar uma alteração no recurso. `POST` solicita o processamento do conteúdo enviado conforme a função do recurso. Criar um contato é um uso comum, mas o método também pode iniciar uma importação ou executar outra operação. Associar todo `POST` exclusivamente à criação limita o significado do protocolo. `PUT` solicita a criação ou substituição do estado do recurso no endereço indicado. `PATCH` aplica modificações conforme o formato de alteração aceito pela API. Para usar um deles, você precisa saber se deve enviar uma representação completa ou uma descrição das mudanças. `DELETE` solicita a remoção da associação entre o endereço e a funcionalidade oferecida pelo recurso. A aplicação pode manter registros internos, históricos ou uma marca de exclusão. O método não promete apagar fisicamente todos os arquivos relacionados. ## Mesmo caminho, chamadas diferentes

Você consulta o contato 42 com GET, conforme a documentação, e confere o identificador e os campos retornados. Para testar uma alteração, usa o método documentado e prepara os valores exigidos. Uma nova consulta permite comparar o resultado com o estado anterior.

Se o serviço responder 405, o método é conhecido, mas não é permitido para aquele recurso. O cabeçalho Allow informa os métodos aceitos. Trocar o verbo por tentativa pode atingir outra função e não substitui a leitura do contrato.

## Segurança semântica e idempotência Um método considerado seguro, como `GET`, não solicita mudança de estado do recurso. Isso não significa ausência absoluta de efeitos, pois o servidor pode registrar o acesso em um log. Significa que a finalidade da chamada é leitura. Idempotência descreve o efeito pretendido de repetir uma chamada. `PUT` e `DELETE` são idempotentes pela semântica HTTP, mas as respostas de duas tentativas podem ser diferentes. Excluir um recurso e repetir a exclusão não precisa produzir o mesmo status nas duas chamadas. `POST` e `PATCH` não oferecem essa propriedade por definição geral. Uma API pode implementar proteção contra repetição, que precisa ser usada conforme sua documentação. Confira essa condição antes de reenviar uma operação após timeout. Para localizar a chamada completa, consulte [endpoint](/glossario/endpoint/) e compare método, endereço e contrato antes do teste. ### Métrica: medida numérica ao longo do tempo - URL: https://promovaweb.com/glossario/metrica - Descrição: Métrica descreve numericamente um comportamento observado. Entenda contadores, valores atuais, taxas, percentuais e limites de médias e comparações. ## O que é uma métrica Métrica é uma medida numérica de um aspecto observado do sistema. Ela pode representar a quantidade de tarefas concluídas, a memória em uso ou a duração das respostas, com uma definição que permita interpretar os valores. O número precisa estar associado ao que foi medido. Você não consegue comparar uma duração em segundos com outra em milissegundos sem conversão, nem interpretar cem falhas sem conhecer o período e o volume de trabalho correspondente. ## Total acumulado e valor atual Um contador acumula ocorrências, como chamadas recebidas, e pode reiniciar quando o processo recomeça. Um gauge representa um valor que pode subir ou descer, como o número de tarefas aguardando execução. Escolher o tipo errado altera a análise. A quantidade atual de tarefas pendentes diminui quando o processamento avança, enquanto o total de tarefas concluídas cresce conforme novas conclusões são registradas.

No primeiro período, dez de cem chamadas falham, representando 10%. No segundo, dez de mil falham, representando 1%, embora a quantidade de falhas seja igual.

A taxa caiu de 10% para 1%, mas dez chamadas falharam nos dois períodos. Ler o percentual junto do total mostra que a proporção diminuiu enquanto a quantidade de falhas permaneceu igual.

## Taxa por segundo não é percentual No Prometheus, a expressão rate aplicada a um contador estima sua taxa média de aumento por segundo dentro da janela escolhida. A consulta rate(erros_totais[5m]) usa os cinco minutos anteriores para calcular erros por segundo, e não o percentual de chamadas que falharam. Para obter uma proporção, erros e total precisam representar a mesma população e intervalos compatíveis. A consulta também deve tratar períodos sem chamadas, em vez de transformar ausência de tráfego automaticamente em sucesso ou falha. ## Médias podem esconder distribuições diferentes Uma média combina as durações observadas, mas não mostra como elas se distribuíram. Muitas respostas rápidas podem compensar numericamente poucas respostas muito lentas, mesmo quando essas últimas prejudicam uma função importante. Um percentil como p95 indica um valor abaixo do qual fica aproximadamente 95% das observações consideradas, conforme o método de cálculo. Ele não representa o pior caso e precisa ser interpretado junto do período, da quantidade de amostras e da forma de agregação. ## Compare a mesma população Filtros e agrupamentos definem quais valores entram na consulta. Misturar testes e produção ou combinar endpoints com comportamentos diferentes pode esconder o serviço que começou a falhar. Confira também lacunas na coleta. Um gráfico sem novas amostras não prova que o consumo caiu para zero, e preencher automaticamente o intervalo vazio pode produzir uma leitura incorreta. ## Do gráfico à investigação Observe o nome, a unidade, o intervalo e os filtros antes de interpretar uma mudança. Depois, relacione o período aos [logs](/glossario/log/) ou traces que podem explicar o comportamento, sem tratar uma variação simultânea como comprovação automática de causa. Para acompanhar métricas e revisar a observabilidade de um projeto ao longo das mudanças, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) oferece análise técnica recorrente. O acompanhamento deve partir das perguntas que os gráficos precisam ajudar a responder. ### Middleware: a camada que processa a requisição antes da ação - URL: https://promovaweb.com/glossario/middleware - Descrição: Middleware processa a requisição antes da ação final. Entenda autenticação, validação e autorização como exemplos e a ordem das camadas. ## O que é middleware Middleware é uma camada que processa a [requisição](/glossario/requisicao/) antes da ação final em uma aplicação. Em vez de cada rota repetir as verificações, o middleware concentra etapas comuns e as aplica no caminho. Uma [autenticação](/glossario/autenticacao/), uma [autorização](/glossario/autorizacao/) ou uma validação podem ser middlewares. A requisição passa por essas camadas antes de chegar à operação que responde. O middleware prepara e protege o caminho. ## Etapas comuns no caminho O middleware executa etapas que se repetem. Conferir se o usuário está autenticado, validar o conteúdo enviado e registrar a chamada são tarefas comuns. Centralizar essas etapas evita repetição em cada rota. Cada middleware pode decidir se a requisição continua. Se a autenticação falhar, a chamada para ali. Se a validação encontrar um erro, a resposta é devolvida antes da ação final. O middleware controla o fluxo.

Uma rota aceita apenas usuários autenticados. A requisição passa pelo middleware de autenticação antes da ação final.

Se o usuário não está autenticado, o middleware interrompe a chamada. A ação final só é executada quando as camadas anteriores permitem a continuidade.

## A ordem das camadas A ordem dos middlewares importa. Cada camada pode alterar a requisição ou interrompê-la. O que é verificado primeiro define o comportamento diante de cada chamada. Colocar a autenticação antes da autorização é comum. O sistema precisa saber quem é o usuário antes de decidir o que ele pode fazer. A ordem das camadas acompanha a lógica de proteção da aplicação. ## Middleware e a estrutura da aplicação O middleware é uma forma de organizar a aplicação. Em vez de repetir verificações dentro de cada rota, as etapas comuns ficam em camadas reutilizáveis. A estrutura fica mais clara e mais fácil de manter. A quantidade de middlewares acompanha a necessidade. Aplicações simples podem ter poucas camadas. Aplicações maiores usam middlewares para autenticação, validação, registro e outras etapas comuns. Para estruturar os middlewares da sua aplicação e a ordem das verificações, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização do caminho da requisição. ### Migration: mudança de estrutura versionável - URL: https://promovaweb.com/glossario/migration - Descrição: Migration registra alterações do banco em arquivos versionáveis. Entenda aplicação, compatibilidade e limites da reversão sobre registros existentes. ## Registrar a evolução do banco Migration é uma alteração do banco descrita em um arquivo que pode ser versionado e executado por uma ferramenta. Ela pode criar uma tabela, acrescentar uma coluna ou modificar uma restrição. Algumas migrations também transformam registros para acompanhar a evolução da estrutura. O projeto mantém uma sequência dessas alterações, e a ferramenta registra quais já foram aplicadas em cada ambiente. Quando você recebe o código, pode executar as etapas pendentes sem reproduzir manualmente cada ajuste. O resultado ainda depende das condições do banco e de eventuais alterações feitas fora desse histórico. Imagine uma atualização que acrescenta a data de nascimento ao cadastro. A migration cria a coluna, e a nova versão da aplicação lê e escreve esse campo. As duas mudanças precisam ser coordenadas para que o código publicado encontre a estrutura esperada. ## Uma alteração com efeito definido O comando pressupõe a existência da tabela e a ausência da coluna. Uma ferramenta de migrations pode executar esse SQL diretamente ou produzir uma instrução equivalente a partir da linguagem do framework. O arquivo e o registro de execução acrescentam organização à alteração. A coluna do exemplo permite nulo, o que acomoda cadastros anteriores sem data informada. Torná-la obrigatória exigiria considerar os valores existentes. Criar uma exigência que nenhuma linha antiga atende pode fazer a execução falhar.

Você aplica a migration e confere se os contatos continuam disponíveis. Depois, cria um cadastro com a nova data e consulta o resultado. O teste cobre tanto a estrutura alterada quanto o comportamento do código que a utiliza.

Se o produto exigir preencher registros antigos, essa transformação precisa ser planejada. A criação da coluna não descobre automaticamente a data de nascimento de cada pessoa.

## Aplicar em um banco existente é um teste próprio Executar toda a sequência em um banco vazio confere a instalação inicial. Atualizar um banco já utilizado confere outra situação, com registros e restrições existentes. As duas verificações podem encontrar falhas diferentes. Considere também o intervalo entre a alteração do banco e a atualização de todos os processos. Se a versão anterior ainda atender requisições, teste seu comportamento com a nova estrutura. O teste da versão nova, sozinho, não cobre essa convivência temporária. O tempo de execução e a interferência em consultas também dependem do banco, do volume e da operação. Uma alteração rápida em poucas linhas pode exigir mais trabalho em uma tabela grande. Consulte o comportamento do comando no banco utilizado e prepare o procedimento de aplicação. ## Reversão não recupera conteúdo automaticamente Uma migration pode oferecer uma operação inversa, mas desfazer a estrutura não equivale a recuperar tudo. Remover uma coluna elimina seus valores, e recriá-la depois não os restaura. Backup e procedimentos de recuperação têm uma finalidade distinta. Também é preciso coordenar a versão da aplicação. Voltar o banco a uma estrutura que o código atual não reconhece pode impedir o funcionamento. Uma migration corretiva pode preservar os valores da coluna que uma inversão destrutiva apagaria. ## Como conferir o histórico Compare migrations aplicadas, estrutura real e versão do código. Teste a instalação inicial e a atualização de um conjunto representativo em desenvolvimento. Não altere silenciosamente uma migration já compartilhada esperando que todos os ambientes a executem novamente. O verbete de [seed](/glossario/seed/) explica como preparar registros de partida depois que a estrutura necessária está disponível. ### Milestone: o marco que estrutura a trajetória do produto - URL: https://promovaweb.com/glossario/milestone - Descrição: Milestone é um marco que estrutura a trajetória do produto em pontos verificáveis. Veja como agrupar trabalho e comunicar a versão atual do produto. ## O que é um milestone Milestone é um marco que aponta um ponto específico na trajetória de um produto. Ele agrupa trabalho relacionado e define um resultado verificável, como concluir uma versão ou alcançar um estágio do sistema. Diferente de uma tarefa que ocupa tempo de execução, o milestone funciona como um indicador de progresso. Ele concentra a atenção no resultado que precisa ser alcançado e permite conferir se o produto está caminhando na direção planejada. ## Agrupar o trabalho em marcos verificáveis O milestone reúne itens do [backlog](/glossario/backlog/) que fazem sentido como um conjunto. Um marco pode representar a versão com as funcionalidades principais, enquanto outro marca a estabilização do sistema ou a liberação de um recurso específico. Para cada marco, você define o resultado esperado e os itens que o compõem. Assim, quando o conjunto é concluído, você confere o que foi entregue contra o que foi planejado, deixando de lado uma impressão geral de que "está quase pronto".

Você define o primeiro milestone como a versão inicial, com os requisitos essenciais para o primeiro uso. Cada funcionalidade ganha um item no backlog associado ao marco.

Ao concluir o conjunto, você compara a entrega com os requisitos. O marco confirma o avanço, enquanto o backlog indica o que ainda separa a versão atual do percurso seguinte.

## Milestones e o ciclo de lançamento Os milestones conversam com o [ciclo de lançamento](/glossario/ciclo-de-lancamento/). Você pode associar um marco a cada release publicado, transformando o percurso em uma sequência de pontos compreensíveis para o usuário. Um marco bem comunicado gera expectativa positiva. O cliente entende o que vem por aí e percebe o produto em movimento, em vez de ver apenas uma lista silenciosa de intenções. A cadência dos marcos mantém esse entendimento. ## Acompanhar o progresso sem enganar O milestone mostra progresso, mas você precisa acompanhar os detalhes que ele esconde. Um marco no caminho crítico pode estar "no prazo" enquanto atividades importantes ficam para trás. Confira o estado real dos itens, em vez de confiar somente na data do marco. Uma prática útil é manter o marco pequeno o suficiente para ser verificado com frequência. Marcos curtos revelam atrasos cedo, enquanto marcos enormes adiam a conferência e escondem problemas até o fim. Para desenhar a trajetória e os marcos do seu produto, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a definição do percurso. ### Mock: substituto controlado em testes - URL: https://promovaweb.com/glossario/mock - Descrição: Mock permite controlar dependências e conferir chamadas em testes. Entenda respostas simuladas, diferenças de nomenclatura e limites da verificação. ## O que é um mock Mock é um substituto controlado usado para verificar como o código interage com uma dependência durante um teste. Ele permite preparar respostas e conferir chamadas, sem exigir que aquela dependência real participe do cenário. O termo também aparece de forma mais ampla nas ferramentas, cobrindo diferentes tipos de simulação. Por isso, observe o que o teste faz: devolver uma resposta fixa e verificar uma interação são operações diferentes, mesmo quando usam a mesma biblioteca. ## Controlar respostas e conferir chamadas Um stub fornece respostas preparadas para o cenário. Na classificação mais estrita, um mock acrescenta expectativas sobre interações, como a chamada que deve ocorrer e os argumentos que ela deve receber. Os nomes das APIs nem sempre seguem essa separação. Ao ler um teste, identifique qual função foi substituída, o retorno configurado e a verificação executada ao final para entender o alcance da simulação.

A aplicação deve solicitar um aviso somente depois de aceitar a inscrição. O teste substitui o envio e apresenta um cadastro inválido, sem acionar o serviço de mensagens.

A verificação espera que nenhuma chamada de envio aconteça. Se o código solicitar o aviso antes de validar o cadastro, esse cenário deve falhar, mesmo que a resposta final da aplicação informe o erro corretamente.

## A simulação precisa representar o contrato Uma resposta preparada pode esconder uma incompatibilidade se usa campos ou tipos diferentes dos retornados pelo serviço. Quando o contrato muda, revise a simulação junto com o código que interpreta o retorno. Prepare também os resultados que alteram o caminho da aplicação, como uma recusa documentada. Repetir apenas o sucesso deixa sem verificação o tratamento que deveria acontecer quando o serviço recusa o envio. ## Evitar interferência entre cenários Chamadas registradas e implementações substituídas podem permanecer disponíveis para o teste seguinte, conforme a ferramenta e a configuração. Limpar o histórico, redefinir o comportamento e restaurar a função original têm finalidades distintas. Um spy também pode observar a função sem impedir sua execução real. Confira esse comportamento antes de usá-lo numa operação de envio, pois registrar a chamada não significa interceptar seu efeito externo. ## Relacionar o teste ao que ele comprova Uma expectativa atendida confirma a interação verificada naquele cenário. Ela não comprova que o provedor recebeu a solicitação ou que entregou a mensagem, e deve ser complementada conforme o alcance necessário do [teste de integração](/glossario/teste-de-integracao/). Para revisar um teste que passa enquanto a integração falha, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação ao vivo para investigar o código e suas simulações. A sessão permite comparar o retorno preparado com o comportamento que a aplicação precisa tratar. ### Modelo de IA: sistema treinado para produzir saídas - URL: https://promovaweb.com/glossario/modelo-de-ia - Descrição: Modelo de IA usa padrões aprendidos no treinamento para produzir os resultados. Entenda sua relação com a aplicação e como conferir a saída obtida. ## O que é um modelo de IA No uso de machine learning, um modelo de IA é uma estrutura computacional ajustada com exemplos para produzir resultados a partir de entradas. O treinamento determina parâmetros usados depois para classificar, estimar ou gerar conteúdo, conforme a tarefa aprendida. Você encontra modelos em aplicações bem diferentes de um chat. Um classificador pode indicar a categoria de um atendimento, enquanto outro modelo transforma um áudio em texto ou produz uma imagem a partir de uma descrição. ## O modelo participa de uma aplicação A aplicação prepara a entrada e determina como utilizar a saída. Também é ela que controla o acesso aos registros, apresenta o resultado e executa as ações permitidas pelo sistema. Um modelo de linguagem não recebe automaticamente acesso aos arquivos do projeto ou ao banco. Esses recursos precisam ser fornecidos pela aplicação, por conteúdo incluído na chamada ou por ferramentas conectadas ao fluxo.

A aplicação aceita as categorias acesso, cobrança e cadastro. O modelo devolve cobrança para uma mensagem que descreve uma falha ao entrar no sistema.

O retorno pertence à lista permitida e passa na validação do formato. Ainda assim, encaminha a mensagem para o atendimento errado, mostrando por que a conferência precisa examinar também o significado da classificação.

## Treinamento e uso têm funções diferentes O treinamento ajusta o modelo a partir dos exemplos e objetivos definidos no processo. A [inferência](/glossario/inferencia/) utiliza o modelo para processar uma entrada, normalmente mantendo os parâmetros aprendidos. Enviar a documentação da versão instalada ou trocar uma instrução pode alterar a resposta sem treinar novamente. Se a sugestão continuar incompatível com a biblioteca do projeto, você pode testar outra configuração ou avaliar um modelo diferente. ## Conferir o resultado na tarefa pretendida Escolha exemplos que representem os casos encontrados no produto e defina o resultado aceitável antes de comparar respostas. Na classificação de atendimento, inclua mensagens ambíguas e categorias próximas, além dos casos que usam exatamente as palavras esperadas. A avaliação deve considerar também o tratamento de falhas na chamada e de saídas que a aplicação não consegue utilizar. Uma resposta isolada adequada não demonstra que o conjunto de situações está atendido. ## Revisar a integração quando o modelo muda Uma substituição pode alterar o tempo de resposta, os formatos aceitos e a interpretação das mesmas entradas. Registre qual modelo foi usado na avaliação e repita os cenários relevantes antes de associar ao novo resultado as verificações do anterior. Para examinar a integração de um modelo numa aplicação criada com IA, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a execução no editor e no terminal. A sessão pode trabalhar a preparação da entrada e os testes que conferem o resultado utilizado pelo sistema. ### Monitoramento: acompanhamento de sinais do sistema - URL: https://promovaweb.com/glossario/monitoramento - Descrição: Monitoramento acompanha condições de um serviço. Veja como escolher sinais, testar disponibilidade, reconhecer falhas de coleta e verificar notificações. ## O que é monitoramento Monitoramento é o acompanhamento sistemático de condições e sinais de um sistema. Ele permite perceber uma aplicação indisponível, um aumento de erros ou o crescimento de uma fila, desde que essas condições estejam cobertas pelas verificações configuradas. Você precisa definir o comportamento que deseja acompanhar antes de escolher um gráfico ou uma ferramenta. Saber que um processo existe responde a uma pergunta diferente de saber se uma inscrição pode ser concluída. ## Observe o serviço por fora e por dentro Uma verificação externa pode acessar a aplicação pelo caminho usado no atendimento real. Sinais internos, como consumo de memória ou duração de consultas, ajudam a interpretar o que ocorre nos componentes. As duas perspectivas se complementam. O servidor pode responder internamente enquanto uma configuração de rede impede o acesso público, ou a página pode abrir enquanto a gravação de um cadastro falha.

O monitor recebe status 200 e considera a chamada bem-sucedida. A integração usada para confirmar reservas está indisponível, mas essa função não participa da verificação.

Uma verificação controlada do percurso de reserva, com destino de teste apropriado, identifica a falha que a página inicial não mostra. Os dois resultados precisam ser interpretados conforme a cobertura de cada teste.

## Coleta bem-sucedida tem um significado limitado No Prometheus, up igual a 1 indica sucesso na coleta de um alvo, enquanto zero indica falha nessa coleta. Esse valor não demonstra, sozinho, que todas as funções da aplicação estão disponíveis. Uma ausência de série também merece interpretação própria. O alvo pode ter saído da configuração ou deixado de fornecer amostras, portanto uma consulta sem resultado não deve ser apresentada automaticamente como serviço saudável. ## Intervalo e local da verificação importam Uma verificação periódica observa momentos específicos e pode não capturar uma interrupção curta entre duas coletas. A localização do monitor também influencia o resultado, pois problemas de rede podem atingir apenas determinados caminhos de acesso. Escolha o intervalo conforme o tempo de percepção necessário e o custo das chamadas. Testes que gravam registros ou enviam mensagens precisam de controle dos efeitos para que o próprio monitoramento não crie operações indevidas. ## Do sinal ao aviso recebido Um painel pode mostrar a falha sem enviar nenhuma notificação. O [alerta](/glossario/alerta/) depende de uma condição configurada e de um percurso de envio que precisa funcionar até o destino previsto. Confira também a condição de falta de informação e o comportamento durante manutenção. Silenciar notificações pode ser adequado por um período, mas não deve ocultar indefinidamente uma coleta interrompida. ## Como verificar a cobertura Simule uma falha controlada em teste e acompanhe o sinal, a condição de alerta e a chegada do aviso. Depois, restaure o serviço e confira se o monitoramento identifica a recuperação. Esse exercício mostra quais funções, falhas de coleta e notificações o monitoramento cobre. Para acompanhar mudanças nesses sinais e nos alertas, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode revisar o projeto dentro do escopo combinado. ### MVP: versão mínima para testar uma hipótese de valor - URL: https://promovaweb.com/glossario/mvp - Descrição: MVP é uma versão preparada para testar hipóteses sobre um produto. Entenda como delimitar o experimento e interpretar resultados sem generalizar. ## Definição MVP significa Minimum Viable Product, ou produto mínimo viável. É uma versão preparada para testar hipóteses sobre um produto e aprender com clientes, usando o esforço necessário para essa investigação. O alcance depende da pergunta que você precisa responder. Uma primeira entrega pode deixar grande parte da visão futura de fora, desde que permita observar o comportamento relevante para a hipótese escolhida. ## Escolher a pergunta antes das funcionalidades Considere um produto que reúne chamados de manutenção recebidos por diferentes canais. Você pode observar se os clientes abrem um chamado pelo novo formulário e consultam por ele o andamento do atendimento. Essa pergunta define quais recursos entram no experimento e quais eventos precisam ser registrados. Configurações administrativas podem ficar de fora, enquanto a exibição de um número de protocolo confirma que o formulário registrou o chamado.

Os clientes abrem chamados, embora os atendentes ainda encaminhem cada um manualmente. Alguns continuam telefonando para acompanhar o atendimento porque não entendem o estado mostrado na página.

Essa observação indica que o acompanhamento precisa ser revisto, mesmo com o envio funcionando. O experimento também não comprova que o atendimento manual suportará um volume maior nem que a futura automação terá o mesmo desempenho.

## Definir como interpretar o resultado Registre a hipótese, o público observado e os sinais que poderiam apoiá-la ou contrariá-la. Elogios à demonstração não equivalem necessariamente ao uso recorrente da aplicação, sobretudo quando o teste exige esforço ou pagamento do cliente. Uma observação pequena pode justificar outra investigação, sem demonstrar a viabilidade do produto em todos os públicos. Compare o resultado com a pergunta inicial e descreva as condições que limitaram o experimento. ## Preservar a atividade que será observada Reduzir funcionalidades não elimina as exigências necessárias ao uso proposto. Se uma falha impede enviar a solicitação, você pode acabar medindo a desistência causada pelo defeito, sem aprender sobre a necessidade que pretendia examinar. O aprendizado orienta a próxima versão: manter, alterar ou abandonar partes da proposta pode ser apropriado conforme o resultado. Acrescentar funcionalidades automaticamente após cada teste não é uma obrigação do conceito. O [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a definição do alcance inicial quando a ideia ainda reúne várias jornadas e integrações possíveis. ### n8n: a plataforma de automação de fluxos de trabalho - URL: https://promovaweb.com/glossario/n8n - Descrição: n8n é uma plataforma de automação de fluxos de trabalho. Entenda nós, conexões, execução e como os fluxos integram serviços e dados. ## O que é o n8n n8n é uma plataforma de automação de fluxos de trabalho. Em vez de escrever código para cada integração, você monta um [workflow](/glossario/workflow/) visual com etapas conectadas. Cada etapa executa uma ação. O n8n conecta serviços e dados. Um fluxo pode receber um evento, consultar uma API e enviar o resultado a outro serviço. A automação acontece sem código manual para cada passo. ## Nós e conexões O fluxo é composto por [nós](/glossario/node/). Cada nó é uma etapa que recebe dados, executa uma ação e entrega o resultado. Os nós se conectam em sequência, formando o caminho da automação. O primeiro nó costuma ser o disparo. O [trigger](/glossario/trigger/) inicia o fluxo por horário, evento ou chamada externa. Os nós seguintes processam os dados e executam as ações.

Um formulário envia um contato novo. O trigger recebe o evento e inicia o fluxo no n8n.

Os nós seguintes consultam os dados, executam a ação e entregam o resultado ao destino. A automação acontece a cada evento, sem ação manual.

## Execução e acompanhamento Cada vez que o trigger dispara, uma [execução](/glossario/execution/) acontece. A execução roda o fluxo do início ao fim. O resultado pode ser conferido e auditado. Acompanhar as execuções mostra o comportamento da automação. Um fluxo pode falhar em uma etapa, e o registro ajuda a entender o motivo. A observação das execuções faz parte da manutenção. ## O n8n no seu fluxo O n8n se encaixa em muitos fluxos de trabalho. Integrar serviços, organizar dados e responder a eventos são usos comuns. A escolha de usar o n8n acompanha a necessidade e a infraestrutura. O n8n é open source e também tem versões gerenciadas. A instalação própria dá controle, enquanto a versão gerenciada cuida da operação. A decisão considera o projeto e o ambiente. Para montar e manter os fluxos de automação no n8n, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção e na manutenção das automações. ### Navegador: a aplicação que apresenta a interface web - URL: https://promovaweb.com/glossario/navegador - Descrição: Navegador é a aplicação que apresenta a interface web. Entenda o cliente, a renderização, os cookies e a relação com o servidor. ## O que é o navegador Navegador é a aplicação que apresenta a interface web. Ele recebe o conteúdo de uma página e o mostra ao usuário. O navegador é o [cliente](/glossario/cliente/) que conversa com o servidor. O navegador interpreta HTML, CSS e JavaScript. O HTML estrutura, o CSS apresenta e o JavaScript dá comportamento. O resultado é a interface que o usuário vê e com a qual interage. ## Navegador e servidor O navegador e o servidor trabalham em pares. O navegador pede o conteúdo por HTTP, e o servidor entrega a resposta. O navegador apresenta o resultado ao usuário. A comunicação acontece pela [requisição](/glossario/requisicao/) e pela resposta. O navegador envia o pedido e recebe o conteúdo. O servidor processa e devolve o que foi solicitado.

O usuário abre o endereço da aplicação. O navegador pede a página ao servidor e recebe o conteúdo.

O navegador interpreta e apresenta a interface. O usuário interage com a página, e novas chamadas acontecem conforme o uso.

## O navegador guarda informação O navegador guarda informações entre as visitas. Os [cookies](/glossario/cookie/) e o armazenamento local mantêm preferências e sessões. Essas informações acompanham as próximas chamadas. A retenção no navegador permite experiências contínuas. O usuário não precisa refazer tudo a cada visita. O controle do que é guardado e por quanto tempo é parte do desenho da aplicação. ## Navegadores diferentes Cada navegador interpreta o conteúdo com suas próprias regras. A mesma página pode apresentar pequenas diferenças entre eles. Versões antigas podem não suportar recursos novos. O teste em navegadores diferentes confirma o comportamento. A aplicação precisa funcionar para quem usa, qualquer que seja o navegador. A compatibilidade faz parte da qualidade da interface. Para revisar a compatibilidade e o comportamento da sua interface nos navegadores, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção e na verificação da aplicação. ### Node: unidade de trabalho no n8n - URL: https://promovaweb.com/glossario/node - Descrição: Node é um componente configurável do n8n que participa de um workflow. Entenda seus parâmetros, os itens de entrada e saída e erros entre etapas. ## O que é um Node no n8n Node é um componente configurável que participa de um [workflow](/glossario/workflow/) do n8n. Ele pode iniciar uma execução, buscar informações, enviar uma mensagem ou controlar o caminho seguido pela automação, conforme o tipo e a ação configurada. Quando você monta um cadastro de inscritos, por exemplo, pode usar um Node para receber o formulário e outro para consultar se o email já existe no sistema de contatos. Cada componente tem parâmetros próprios, e a conexão entre eles determina como os resultados chegam às próximas etapas. O nome também aparece em Node.js, mas representa outro conceito. O [Node.js é um runtime](/glossario/runtime/) de JavaScript, enquanto o Node do n8n é uma peça da automação que você configura no editor. ## Tipo, operação e parâmetros O tipo do Node informa quais funções ele oferece. Um componente de integração pode disponibilizar ações para criar ou consultar contatos. Você seleciona a ação, informa os campos necessários e associa uma credencial compatível. Os parâmetros podem conter valores fixos ou expressões que usam informações recebidas durante a execução. Um endereço de email digitado diretamente no campo será reutilizado, enquanto uma expressão pode buscar o destinatário na inscrição que chegou naquele momento. Essa diferença explica por que um teste aparentemente correto pode enviar todas as confirmações para a mesma pessoa. Ao revisar a configuração, confira se o destinatário vem da entrada atual ou se permaneceu preenchido com o endereço usado no primeiro teste. ## O que entra e o que sai do componente O n8n trabalha com itens que transportam informações entre etapas. Um Node pode receber vários itens e produzir uma quantidade diferente na saída, como ocorre quando uma consulta retorna várias inscrições ou um filtro descarta as que não atendem à condição. Por isso, você precisa observar tanto os campos quanto a quantidade de resultados. Uma saída vazia pode significar que a consulta não encontrou nenhum contato, e a continuação do fluxo deve considerar esse caso em vez de presumir que sempre haverá um identificador disponível.

O formulário envia o nome no campo nome, mas a integração espera nomeCompleto. Uma etapa de mapeamento copia o valor para o campo esperado e preserva o email que será usado no cadastro.

Se o nome estiver ausente, a etapa não deve inventar um valor para completar o objeto. Você precisa encaminhar essa entrada para o tratamento definido pelo workflow antes de chamar a integração.

## Credenciais e comportamento diante de erros Os Nodes que acessam serviços protegidos precisam de credenciais com as permissões necessárias. O n8n oferece um cadastro próprio para essas credenciais, evitando que você tenha de escrever uma chave de API como texto comum em cada etapa que usa o mesmo serviço. Uma falha também exige leitura da configuração. Se o componente foi preparado para continuar por um caminho de erro, as etapas seguintes podem receber informações sobre a falha em vez do contato que você pretendia criar. ## Como verificar um Node Abra a entrada e a saída da etapa durante um teste e compare os campos com a tarefa esperada. Para o cadastro de inscritos, confira o email usado, o identificador devolvido pelo serviço e o comportamento quando o contato já existe. Um erro apresentado no Node de envio pode ter começado no mapeamento anterior. A mensagem da integração localiza o ponto da recusa, mas a comparação entre entrada, parâmetros e saída é que mostra se o problema veio do serviço ou do conteúdo encaminhado pelo workflow. ### Observabilidade: investigação a partir dos sinais - URL: https://promovaweb.com/glossario/observabilidade - Descrição: Observabilidade permite investigar o comportamento de um sistema pelos sinais que ele expõe. Entenda correlação e os limites de coleta e retenção. ## O que é observabilidade Observabilidade é a capacidade de investigar o estado e o comportamento de um sistema a partir dos sinais que ele disponibiliza. Em uma aplicação, isso pode significar descobrir qual etapa concentra a demora de uma tarefa e quais condições acompanham a falha. A quantidade de painéis não mede essa capacidade por si só. Você precisa conseguir formular uma pergunta e encontrar registros que permitam examiná-la, incluindo os limites do que foi coletado. ## A pergunta orienta a consulta Uma pergunta como por que a exportação demora apenas para arquivos grandes exige distinguir tamanho, duração e etapas envolvidas. Um gráfico que reúne todas as exportações pode mostrar a mudança geral sem explicar essa diferença. A instrumentação precisa registrar informações que permitam separar esses casos. Ela pode ser automática em parte, mas detalhes específicos da aplicação talvez precisem ser acrescentados ao código ou à configuração dos sinais.

A duração total aumentou, mas o tempo de geração permaneceu parecido. Os registros associados à tarefa mostram que ela passou mais tempo aguardando o início do processamento.

A investigação segue para a fila e a disponibilidade dos workers. Otimizar a geração do arquivo, sem conferir essa espera, não trataria a parte que aumentou nesse caso.

## Sinais diferentes respondem a perguntas diferentes As [métricas](/glossario/metrica/) permitem observar volumes, taxas e distribuições ao longo do tempo. Logs descrevem eventos registrados, enquanto traces relacionam trechos instrumentados do percurso de uma operação. Uma investigação pode usar apenas alguns desses sinais. O importante é que eles permitam examinar a hipótese, em vez de acumular registros que não distinguem sucesso, falha, espera ou execução. ## Correlacionar exige referências compartilhadas Identificadores da tarefa, do trace ou da requisição ajudam a relacionar registros produzidos em componentes diferentes. O horário sozinho pode ser insuficiente quando várias chamadas chegam ao mesmo tempo ou os relógios não estão alinhados. Confira também a propagação nas chamadas e nas mensagens assíncronas. Se a referência se perde ao entrar na fila, o processamento posterior pode aparecer separado do evento que o originou. ## A investigação depende do que permaneceu disponível Nem toda operação precisa ser preservada integralmente, mas a política de amostragem determina quais traces poderão ser consultados. Retenção, filtros e falhas na coleta também limitam o conjunto disponível. A ausência de um registro não demonstra necessariamente ausência de execução. Registre a lacuna e, quando necessário, reproduza o comportamento de forma controlada com instrumentação adicional, sem inventar uma conclusão que os sinais não permitem. ## Verificar a capacidade de investigar No exemplo das exportações, confira se consegue relacionar a criação da tarefa, o início do processamento e o fim da geração pelo mesmo identificador. Esses registros permitem distinguir espera na fila de tempo de execução. Se falta o instante de início, a duração total sozinha não permite fazer essa separação, e a instrumentação precisa registrar essa etapa. Para revisar essa capacidade ao longo da evolução do projeto, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) oferece acompanhamento técnico recorrente. A análise pode partir de perguntas que hoje não encontram resposta nos registros do sistema. ### Offset: quantos itens pular antes de retornar - URL: https://promovaweb.com/glossario/offset - Descrição: Offset indica quantos itens pular em uma consulta paginada. Entenda o cálculo da página, a ordenação e os efeitos de alterações na lista durante a leitura. ## Quantas linhas pular no resultado Offset é o deslocamento usado para pular uma quantidade de itens antes de devolver uma parte do resultado. Combinado a um limite, permite selecionar trechos de uma lista. Ele se refere à posição no resultado da consulta, não ao valor do identificador dos registros. Se uma consulta ordenada usa limite dez e offset zero, retorna até os dez primeiros itens. Com offset dez, pula os dez primeiros e retorna até os dez seguintes. O filtro e a ordem precisam permanecer coerentes entre essas chamadas. Os identificadores não precisam ser consecutivos. Se existem contatos com IDs 2, 7 e 20, pular uma linha descarta o primeiro item do resultado, e não todos os IDs menores ou iguais a um. Essa diferença separa deslocamento de filtro por chave. ## Como a página é calculada Com páginas numeradas a partir de um, o deslocamento costuma ser calculado por `(pagina - 1) * tamanho`. Para a página três com dez itens, o offset é vinte. A API pode adotar outra convenção, que precisa ser confirmada. `ORDER BY id` oferece uma ordem determinística quando `id` é único. Ordenar apenas por nome pode deixar empates, e a ordem entre linhas empatadas não fica garantida. Acrescentar um desempate evita depender de uma sequência incidental do banco. ## O que muda durante a navegação

Você lê os dez primeiros contatos. Entre essa chamada e a seguinte, um novo contato entra no começo da lista. O contato que ocupava a décima posição fica na décima primeira. Ao pular dez itens, a consulta seguinte devolve esse contato novamente.

Uma remoção antes do deslocamento pode produzir o efeito oposto e fazer um item deixar de aparecer no percurso. Fixar a ordenação resolve empates, mas não congela uma coleção que está mudando.

Esse comportamento pode ser aceitável em algumas interfaces de navegação, mas inadequado para uma exportação que precisa examinar cada registro. A escolha depende do objetivo e das garantias oferecidas pela consulta. ## O custo das páginas distantes O banco precisa considerar as linhas puladas para chegar ao trecho solicitado. Um offset grande pode aumentar o trabalho mesmo quando a resposta contém poucos itens. O plano de execução, os índices e os filtros influenciam esse custo. Não existe um tamanho universal a partir do qual offset deixa de servir. Meça as consultas relevantes e observe como o tempo varia nas páginas mais distantes. A facilidade de acessar uma página arbitrária pode ser útil quando esse comportamento é necessário. ## Quando comparar com cursor Paginação por chave ou cursor pode continuar a partir de valores ordenados, evitando certos deslocamentos e parte do trabalho de pular linhas. Ela exige um contrato e uma ordenação compatíveis. Também não resolve automaticamente toda mudança concorrente ou toda necessidade de fotografia consistente. Em desenvolvimento, crie contatos com a mesma data e compare a ordem retornada. Insira um contato entre consultas e remova outro no início da lista para observar os deslocamentos. Confira também o retorno quando a consulta não encontra itens. O verbete de [cursor de paginação](/glossario/cursor-de-paginacao/) explica outra forma de representar o ponto de continuação. ### Onboarding: a primeira experiência que conecta o usuário ao valor - URL: https://promovaweb.com/glossario/onboarding - Descrição: Onboarding é a experiência que guia o novo usuário ao primeiro valor do produto. Veja como conduzir a entrada, reduzir o abandono e favorecer a adoção. ## O que é onboarding Onboarding é a experiência que conduz o novo usuário ao primeiro valor do produto. Ele combina a configuração inicial, as explicações de uso e uma sequência de ações que mostram como o sistema resolve o problema do cliente. A palavra veio do mundo de recursos humanos, que descrevia a ambientação de novos funcionários. No software, ela nomeia o processo que leva um recém-chegado a se tornar um usuário capaz e engajado, em vez de alguém que abre o sistema uma vez e desiste. ## A ausência de onboarding vira abandono Quando a primeira experiência não tem uma sequência lógica, o usuário se perde. Um produto tecnicamente completo, com dezenas de telas, pode fracassar simplesmente porque ninguém entende por onde começar. Um caso comum aparece em plataformas com muitos recursos. Você abre o sistema, não encontra o caminho para o próprio primeiro resultado e abandona. A funcionalidade existia, mas a entrada não conectou o cliente ao valor que o produto oferece.

Você cria um acesso novo, mas o sistema não orienta as primeiras ações. O usuário não completa nem o próprio perfil e raramente volta ao produto.

O perfil incompleto vira um sinal precoce. Sem o onboarding, o usuário não alcança o valor e dificilmente se torna um cliente engajado. A primeira experiência determinou a permanência.

## Onboarding e adoção se reforçam O onboarding alimenta a [adoção](/glossario/adocao/). Um usuário que entende o produto nas primeiras semanas usa mais, e o uso recorrente confirma o valor percebido. Essa base mantém a permanência e reduz o [churn](/glossario/churn/). Você observa o onboarding pelas [métricas](/glossario/metrica/): quantos usuários completam as etapas, quais módulos são ignorados e quantos voltam depois do primeiro acesso. Esses números mostram onde a primeira experiência facilita e onde ela trava. ## Onboarding contínuo além do primeiro acesso O onboarding não termina no primeiro login. Ele se estende enquanto o usuário repete o uso e consolida o hábito. Uma boa prática é ensinar também os lançamentos, mostrando como cada novidade se aplica à rotina do cliente. Cada release novo pode reabrir a porta do onboarding, apresentando a funcionalidade e seu uso antes de qualquer próximo ciclo. O usuário educado sobre o ritmo do produto percebe valor e permanece. Para revisar a experiência de entrada do seu sistema e o fluxo de uso, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar o ajuste junto à implementação. ### Origem web: esquema, host e porta no modelo de segurança - URL: https://promovaweb.com/glossario/origem-web - Descrição: Origem web combina esquema, host e porta de um endereço acessado. Entenda como comparar URLs e como a origem difere do site considerado pelos cookies. ## A identificação usada para isolar páginas Para URLs HTTP e HTTPS, origem web é a combinação de esquema, host e porta. O navegador usa essa identificação para aplicar restrições entre documentos e serviços. Caminho, consulta e fragmento não fazem parte dessa combinação. Duas páginas em `https://example.com` podem ter caminhos diferentes e continuar na mesma origem. Já `https://app.example.com` usa outro host e, portanto, outra origem. Compartilhar o mesmo domínio principal não torna os endereços equivalentes para essa comparação. No desenvolvimento local, as portas também importam. Uma interface em `http://localhost:3000` e uma API em `http://localhost:8000` pertencem a origens diferentes. Isso explica por que uma chamada local pode exigir configuração de CORS. ## Como comparar duas URLs Como 443 é a porta padrão de HTTPS, os dois primeiros endereços do exemplo têm a mesma origem. O navegador normaliza essa informação ao calcular `location.origin`, que você pode consultar na página aberta para conferir o valor utilizado. A comparação considera o host completo, portanto acrescentar `www` também muda a origem. Um site pode redirecionar entre o endereço com esse prefixo e o endereço sem ele. Nesse caso, confira a URL final para identificar a origem da página efetivamente carregada. ## O que a política de mesma origem restringe A política limita como um documento ou script pode interagir com recursos de outra origem. Uma página não recebe acesso irrestrito ao conteúdo de outra apenas por conhecer seu endereço. Para leitura de respostas de APIs por JavaScript, CORS permite ao servidor declarar autorizações específicas. Isso não impede toda comunicação entre origens. Você pode seguir um link para outro site sem conceder ao script da página anterior acesso irrestrito ao conteúdo do destino. Da mesma forma, conseguir enviar uma requisição não equivale a poder ler sua resposta pelo código da página.

A página abre na porta 3000 e consulta uma API na porta 8000. O navegador compara as origens e reconhece a diferença de porta. A resposta da API precisa autorizar a origem da página pelos cabeçalhos de CORS para que o JavaScript consiga ler o retorno.

Uma ferramenta de terminal pode acessar a mesma API sem aplicar essa política do navegador. O teste no terminal confirma parte da comunicação, mas não comprova que a configuração entre origens está correta para a interface.

## Origem e site não são sinônimos Na comparação de site usada por `SameSite`, o navegador considera o esquema e o domínio registrável. Por exemplo, `https://app.example.com` e `https://api.example.com` pertencem ao mesmo site, mas têm origens diferentes porque seus hosts diferem. A [explicação de site na MDN](https://developer.mozilla.org/en-US/docs/Glossary/Site) detalha essa distinção. Pertencer ao mesmo site não faz todo cookie circular entre os subdomínios. Um cookie definido por `app.example.com` sem o atributo `Domain` fica restrito a esse host. Ele não é enviado a `api.example.com` apenas porque ambos pertencem a `example.com`. Confira o escopo definido por [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie), além de `SameSite`. Cookies também não são isolados por porta da mesma forma que a origem. Por isso, verificar somente `location.origin` não explica todos os casos de envio ou ausência de cookies. Você precisa conferir os atributos e as políticas aplicadas pelo navegador. ## Como investigar uma diferença Compare o esquema, o host e a porta efetiva da página com os do serviço. Confira também redirecionamentos e o endereço final. Em seguida, examine a requisição na aba Network para identificar as origens envolvidas. Quando a leitura da resposta for recusada, consulte [CORS](/glossario/cors/) para entender os cabeçalhos exigidos. Para problemas de sessão, examine também os atributos do cookie, pois a origem é apenas uma parte da análise. ### Orquestração: coordenar etapas de um processo - URL: https://promovaweb.com/glossario/orquestracao - Descrição: Orquestração coordena etapas e serviços de um processo maior. Veja como dependências, estado, falhas e retomada orientam a execução de uma automação. ## O que é orquestração Orquestração é a coordenação de etapas e componentes para realizar um processo. Um coordenador acompanha quais ações podem começar, quais dependem de resultados anteriores e como o processamento deve continuar diante de uma resposta, espera ou falha. Em uma automação de matrícula, você pode consultar a confirmação de pagamento, criar o acesso e enviar as instruções ao aluno. O coordenador relaciona essas etapas para que o envio use um acesso que já foi criado, em vez de presumir que todos os serviços terminarão suas tarefas ao mesmo tempo. ## As dependências definem a progressão Uma etapa que usa o resultado de outra precisa aguardar essa informação antes de executar. O envio de instruções pode exigir o identificador da matrícula, enquanto a preparação de um material e a consulta de informações cadastrais podem ser independentes, conforme o processo. A orquestração pode executar partes independentes simultaneamente quando a plataforma permite e aguardar os resultados necessários antes de continuar. Ter vários caminhos desenhados no editor não comprova, por si só, que eles executam em paralelo, pois a ordem também depende do mecanismo de execução.

O workflow confirma o pagamento na origem e solicita a criação da matrícula. Somente depois de receber o identificador do acesso ele prepara a mensagem com as instruções correspondentes.

Se a criação falhar, a automação registra a pendência para recuperação. Enviar uma mensagem que afirma que o acesso está disponível seria incorreto, mesmo que o serviço de email esteja funcionando.

## O estado permite saber de onde continuar Um processo com várias etapas precisa distinguir o que ainda não começou do que já terminou ou está aguardando retorno. Preservar essa informação permite investigar uma matrícula cuja cobrança foi confirmada, mas cujo acesso ainda não foi criado. O identificador que acompanha o processo também precisa ligar os registros dos serviços participantes. Sem essa associação, horários próximos e mensagens parecidas podem fazer você confundir duas execuções diferentes durante a investigação. ## Falhas entre serviços não têm reversão automática Uma chamada concluída em um serviço não é desfeita apenas porque a etapa seguinte falhou. Se a matrícula foi criada e o envio das instruções falhou, recuperar o envio pode ser suficiente, sem repetir a criação do acesso. Outros processos podem precisar de uma ação compensatória, como cancelar uma reserva que deixou de fazer sentido depois de uma falha posterior. Essa ação precisa ser prevista e acompanhada, pois também pode falhar e não equivale necessariamente a restaurar exatamente o estado anterior. Se a matrícula foi criada e o envio das instruções falhou, uma Saga pode registrar a matrícula e repetir apenas o envio. Se o produto exigir cancelar o acesso, esse efeito compensatório precisa ser implementado e conferido separadamente. Coordenar as chamadas não lhes dá as propriedades de uma [transação](/glossario/transacao/) de banco. ## Orquestração e reação a eventos Na orquestração, o coordenador controla a progressão do conjunto. Em uma coreografia, os serviços reagem aos eventos publicados por outros participantes, sem um controlador central que conduza toda a sequência. Ambas as abordagens precisam tratar duplicações, falhas e acompanhamento. A distinção está em onde a progressão é definida, e não na presença obrigatória de inteligência artificial ou no número de agentes usados. ## Como verificar a coordenação Acompanhe uma execução com os identificadores de cada etapa e provoque uma falha controlada em um serviço de teste. Confira quais ações ocorreram antes da falha e qual parte foi retomada depois. O teste deve demonstrar que uma resposta ausente não é interpretada como sucesso e que a retomada considera os efeitos já realizados. Uma mensagem de erro localiza o ponto observado, mas ainda é preciso comparar entradas, permissões e respostas para determinar sua causa. ### Over-delivery: quando o excesso de lançamentos supera a absorção - URL: https://promovaweb.com/glossario/over-delivery - Descrição: Over-delivery é publicar funcionalidades em volume superior ao que o usuário consegue absorver. Veja como isso afeta a adoção e a percepção de valor. ## O que é over-delivery Over-delivery é a prática de publicar funcionalidades em volume superior ao que o usuário consegue absorver. O software permanece tecnicamente saudável, mas o excesso de novidades supera a capacidade do cliente de entender, testar e adotar cada mudança. O termo descreve um descompasso de ritmo. A produção avança rápido, enquanto a absorção pelo usuário permanece lenta e gradual. Você constrói um funil no qual a parte de cima produz sem parar, enquanto a base recebe quase aos poucos.

Você anuncia uma funcionalidade importante e prepara uma live para explicar o uso. Antes que a maioria dos clientes assista, uma segunda novidade chega na semana seguinte.

Um usuário assíduo nem chega a testar o primeiro recurso. Ele começa a duvidar se o valor que assina compensa e considera procurar outra opção. A capacidade de produção existia, mas a comunicação e a adoção não acompanharam.

## O excesso afeta o negócio, não o código O prejuízo do over-delivery não aparece na camada técnica, pois o sistema não piora por receber atualizações frequentes. O impacto se manifesta na estratégia: o excesso atrapalha o marketing, dilui o destaque de cada novidade e enfraquece a percepção de valor do produto. Quando três lançamentos seguidos não geram adoção, a leitura é clara. Você precisa parar de publicar e começar a conversar. Mostrar como usar o que já existe supera em efeito o acréscimo de camadas ao sistema. ## A produção rápida esconde o problema Um exemplo comum acontece em consultorias. Você acompanha uma plataforma tecnicamente completa, com dezenas de telas funcionais, e descobre que a maioria dos novos usuários abandona o acesso. A causa não está em um erro de código, mas na ausência de uma experiência coesa, sem uma sequência lógica de informações. O excesso de funcionalidades reforça essa sensação. O cliente que chega agora encontra um produto denso, sem uma porta de entrada clara, e desiste antes de alcançar o valor que motivou a assinatura. O ritmo do desenvolvimento avançou sem considerar o ritmo de adoção dos usuários que estão chegando. ## Publicar no ritmo da absorção A solução prática é lançar aos poucos e sempre. Você define um backlog, divide a trajetória em [milestones](/glossario/milestone/) e escolhe uma cadência, como um lançamento quinzenal ou mensal. Depois de cada release, você reserva um período para comunicar e educar, antes de voltar a desenvolver novos recursos. Correções e ajustes menores podem sair fora desse ciclo sem comprometer o padrão. O objetivo é educar o usuário sobre o ritmo das novidades e criar um hábito de consumo, em vez de surpreendê-lo com uma enxurrada de atualizações sem explicação. Para planejar esse ritmo e definir o que realmente entra em cada versão, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a revisão do escopo e das prioridades. ### Paginação: dividir resultados em partes - URL: https://promovaweb.com/glossario/paginacao - Descrição: Paginação divide resultados em partes. Entenda tamanho, ordenação, continuação e como percorrer uma lista sem confundir a primeira página com o total. ## Consultar uma lista por partes Paginação é a divisão de um conjunto de resultados em partes recuperáveis. Em uma API, cada chamada pode devolver um trecho da lista e informações para continuar. Na interface, isso pode aparecer como páginas numeradas, um botão para carregar mais ou rolagem contínua. Uma consulta de contatos pode encontrar milhares de linhas, mas a tela precisa apresentar apenas uma parte por vez. Limitar a resposta reduz o conteúdo transportado e interpretado naquele momento. O trabalho realizado no banco ainda depende da consulta, dos filtros e dos índices. Ler a primeira resposta não equivale a obter a coleção completa. Uma integração de exportação, por exemplo, precisa percorrer a continuação prevista pelo serviço. O encerramento deve seguir o contrato, sem presumir que uma página representa tudo o que existe. ## Tamanho, ordem e continuação O tamanho define quantos itens podem aparecer em cada trecho. A ordenação estabelece a sequência, e a continuação informa como acessar o próximo trecho. Esses três elementos precisam funcionar juntos para que o percurso seja compreensível. Ordenar apenas por um campo que se repete pode deixar empates. Uma consulta por data, por exemplo, pode acrescentar o identificador como desempate. Sem ordem determinística, chamadas sucessivas podem apresentar sobreposição mesmo quando usam os mesmos parâmetros. Nesse exemplo, `id` deve identificar a linha de forma única. `LIMIT` restringe a quantidade, e `OFFSET` define quantas linhas do resultado ordenado serão puladas. A página seguinte usa outro deslocamento, mantendo os filtros e a ordenação. ## Dois mecanismos de continuação Paginação por offset usa uma posição numérica. Ela facilita calcular um deslocamento para páginas numeradas, mas páginas distantes podem exigir trabalho significativo para pular linhas. Mudanças na coleção também podem deslocar os resultados entre chamadas. Paginação por cursor utiliza uma referência de continuação definida pela API. O cursor pode representar os valores do último item ou outro estado do serviço. Ele não é necessariamente um número de página nem garante uma fotografia imutável da coleção.

Você recebe dez contatos, depois outros dez e por fim cinco. A integração segue a indicação de continuação e encerra conforme o contrato. O teste compara os identificadores para detectar repetição ou ausência.

Em um sistema real, novos contatos podem surgir durante esse percurso. Se a exportação exigir um retrato de um instante, será necessário um mecanismo adicional, como uma consulta consistente ou um recurso de exportação do serviço.

## O total pode ser desconhecido Algumas APIs informam o número total de resultados, e outras apenas indicam se há mais páginas. Calcular esse total também pode ter custo. A interface deve trabalhar com os campos retornados, sem inventar quantas páginas restam. Uma página menor que o limite não comprova o término. A [orientação AIP-158 do Google](https://google.aip.dev/158) permite respostas com menos itens que o solicitado, inclusive nenhum, antes do fim da coleção. Nesse contrato, você verifica o campo `next_page_token` para saber se deve continuar. Outras APIs podem adotar outro sinal, que deve estar documentado. ## Como conferir o percurso Prepare um conjunto conhecido e percorra todas as partes, comparando os identificadores recebidos. Repita com filtros e empates na ordenação. Depois, teste alterações na coleção se esse comportamento fizer parte do uso esperado. Os verbetes de [offset](/glossario/offset/) e [cursor de paginação](/glossario/cursor-de-paginacao/) detalham as diferenças entre as duas formas de continuar a leitura. ### Payload: o conteúdo útil transportado pela mensagem - URL: https://promovaweb.com/glossario/payload - Descrição: Payload é o conteúdo transportado por uma mensagem. Entenda sua relação com body, formatos e campos aninhados em um exemplo de notificação de cobrança. ## O conteúdo que a comunicação transporta Payload significa carga útil: o conteúdo transportado para cumprir a finalidade de uma mensagem. Em uma integração de cadastro, pode ser o conjunto de campos do contato. Em uma notificação de pagamento, pode trazer o identificador da cobrança e sua situação. O termo não define um formato. O payload pode ser representado em JSON, texto, um arquivo ou outro formato aceito pelo receptor. Para interpretá-lo, você precisa conhecer tanto a estrutura quanto o significado dos campos. Imagine que um serviço informa que uma cobrança foi paga. A integração recebe uma mensagem com o identificador correspondente e usa essa referência para localizar o registro local. Antes de atualizar a cobrança, precisa reconhecer o tipo da notificação e encontrar os campos previstos para esse evento. ## Um exemplo de mensagem Nesse exemplo, `evt_1042` identifica a notificação, e `cob_85` identifica a cobrança. Os dois valores têm funções diferentes. Usar o identificador do evento para procurar a cobrança faria a integração consultar o registro errado. O campo `valor_centavos` explicita a unidade usada no exemplo. O número `29990` representa R$ 299,90 porque esse contrato fictício utiliza centavos. Outra API pode adotar uma representação diferente, que precisa ser confirmada antes de qualquer cálculo. ## Payload, body e envelope Em uma conversa sobre HTTP, payload frequentemente designa o conteúdo do corpo. Já em uma fila, a mensagem pode conter um envelope com informações de roteamento e uma seção específica para o conteúdo do evento. O limite entre essas partes depende do protocolo e do contrato. Até informações sobre o evento podem aparecer dentro do JSON chamado de payload. Por isso, classificar todos os identificadores como cabeçalhos e todos os valores comerciais como corpo seria uma simplificação incorreta. Leia a estrutura documentada para saber onde cada informação foi colocada. ## Da leitura à atualização do sistema

A integração lê o tipo da mensagem e verifica se reconhece aquele evento. Depois, localiza a cobrança pelo campo específico e aplica a atualização prevista. O identificador da notificação pode ser usado para reconhecer reentregas.

Se a mensagem chegar novamente, o receptor precisa evitar uma segunda aplicação indevida da mesma ação. Essa proteção depende do processamento implementado, pois JSON válido não impede duplicação.

A interpretação do payload também precisa considerar campos ausentes e versões do contrato. Um campo opcional pode não aparecer em todos os eventos. Já a ausência de um identificador obrigatório deve impedir uma atualização baseada em suposições. Reconhecer os campos não comprova a origem da mensagem. Em um [webhook](/glossario/webhook/), o receptor precisa conferir a autenticação ou assinatura conforme a documentação do emissor. Um JSON com o texto `cobranca.paga` não é suficiente para confirmar o pagamento. ## O que conferir quando um campo não é encontrado Compare o conteúdo recebido com a estrutura esperada, incluindo objetos aninhados. `cobranca.id` e um campo `id` na raiz são caminhos diferentes. Confira também se a mensagem pertence ao tipo de evento que a integração sabe processar. Use exemplos fictícios ou registros sem informações pessoais ao compartilhar uma análise. O corpo de uma mensagem pode conter conteúdo sensível mesmo quando os cabeçalhos foram removidos. A explicação de [JSON](/glossario/json/) mostra como percorrer os campos e reconhecer seus tipos. ### Percepção de valor: o valor que o cliente reconhece no produto - URL: https://promovaweb.com/glossario/percepcao-de-valor - Descrição: Percepção de valor é o que o cliente reconhece no produto, além do que o código entrega. Veja como o uso e a comunicação favorecem essa percepção. ## O que é percepção de valor Percepção de valor é o valor que o cliente reconhece no produto, em comparação ao custo e às alternativas disponíveis. Ela descreve a avaliação do usuário sobre o quanto o sistema aprimora o próprio trabalho, indo além do que o código faz. A distinção entre valor técnico e valor percebido orienta esta leitura. Você pode gerar valor técnico, com funcionalidades completas e estáveis, e mesmo assim o cliente não perceber esse valor. A percepção surge do uso, da comunicação e da experiência, e é ela que mantém viva a permanência. ## O valor percebido define a permanência Um cliente permanece quando enxerga o sistema como inovador, atualizado e suficiente para resolver o que precisa. Essa leitura não vem do volume de lançamentos, mas da combinação entre uso real, explicação clara e um ritmo que permite absorver cada novidade. Quando o usuário duvida do retorno, a permanência vacila. A dúvida sobre estar valendo a pena é um sinal de percepção de valor baixa, e ela antecede o [churn](/glossario/churn/). A fidelidade depende do que o cliente reconhece, e não do que foi entregue.

Você lança a integração e aguarda o reconhecimento do cliente. Como a comunicação não explicou o valor da novidade, poucos usuários mudam de comportamento.

O produto ganhou capacidade técnica, mas a percepção de valor permaneceu a mesma. O esforço não se converteu em reconhecimento, porque o usuário não conectou a funcionalidade à própria rotina.

## A comunicação mantém a percepção O valor percebido precisa de explicação. Uma funcionalidade só entra na percepção do cliente quando ele entende como aquilo se aplica ao próprio trabalho. Lives, vídeos, mensagens e orientações de uso cumprem esse papel. A cadência também favorece a percepção. Um ritmo previsível de lançamentos educa o usuário e cria expectativa positiva, enquanto uma enxurrada de novidades sem explicação dilui cada destaque. O reconhecimento cresce quando a release chega acompanhada de orientação de uso. ## Percepção de valor e adoção se conectam A [adoção](/glossario/adocao/) alimenta a percepção de valor. Um usuário que usa e repete o uso enxerga o produto trabalhando a favor dele. O [onboarding](/glossario/onboarding/) mostra o caminho até esse primeiro valor, e o [ciclo de lançamento](/glossario/ciclo-de-lancamento/) dá tempo para cada novidade ser compreendida. Para revisar como o seu produto é percebido e onde o valor técnico não está chegando ao cliente, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar a análise da experiência e da comunicação do produto. ### Performance: o comportamento da aplicação em velocidade e recursos - URL: https://promovaweb.com/glossario/performance - Descrição: Performance mede como a aplicação se comporta em velocidade e recursos. Entenda latência, throughput, medição e a relação com a experiência do usuário. ## O que é performance Performance mede como a aplicação se comporta em velocidade e recursos. Inclui o tempo de resposta, a quantidade de trabalho por unidade de tempo e o uso de recursos como processamento e memória. A performance afeta a experiência e o custo. Uma aplicação lenta frustra o usuário. Uma aplicação que consome muitos recursos custa mais para operar. A avaliação considera os dois lados. ## Medir para melhorar A performance se mede com [métricas](/glossario/metrica/). O tempo de resposta mostra a latência. O throughput mostra a quantidade de trabalho por unidade de tempo. O uso de recursos mostra o custo da operação. A medição contínua acompanha o comportamento. Uma aplicação pode funcionar bem em um teste e degradar sob carga. O [monitoramento](/glossario/monitoramento/) dos indicadores revela onde a performance muda.

A aplicação responde rápido em um teste simples, mas fica lenta quando vários usuários acessam ao mesmo tempo.

A medição sob carga mostra onde o tempo aumenta. Com o indicador, a melhoria vai para a etapa que não sustenta o volume, e o comportamento passa a acompanhar o uso real.

## Performance e experiência A performance influencia a percepção do usuário. Uma resposta rápida parece natural, enquanto um atraso longo frustra. A [latência](/glossario/latencia/) é uma parte da performance que afeta diretamente a interação. O esforço de melhoria acompanha o uso. Uma operação frequente e interativa merece mais cuidado do que uma tarefa rara. Melhorar onde o usuário sente mais impacto entrega mais valor. ## Otimizar com cuidado Uma otimização pode beneficiar uma métrica e piorar outra. Reduzir o tempo de resposta pode aumentar o uso de recursos, ou o contrário. A avaliação considera o efeito completo da mudança. O [cache](/glossario/cache/) é um caminho comum. Armazenar um resultado pronto evita recomputar a cada solicitação. A escolha da otimização considera a natureza da operação e o comportamento desejado. Para medir e melhorar a performance da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação no monitoramento e na otimização dos indicadores. ### Plugin: extensão que adiciona capacidade a uma aplicação - URL: https://promovaweb.com/glossario/plugin - Descrição: Plugin adiciona capacidade a uma aplicação sem reescrevê-la. Entenda extensões, permissões, versionamento e quando o nome muda o comportamento de uma ferramenta. ## O que é um plugin Plugin é um componente que adiciona capacidade a uma aplicação existente sem reescrever o núcleo dela. Em vez de alterar a ferramenta, você instala um complemento que amplia o comportamento dentro das regras da plataforma. Editores, navegadores e sistemas de automação usam plugins para ganhar funções sob medida. Uma mesma ferramenta pode receber diferentes complementos conforme a necessidade de cada projeto, mantendo o núcleo original intacto. ## O que muda com o nome Cada plataforma escolhe um nome: plugin, extensão, add-on ou módulo. A função é parecida, mas as regras de instalação, permissões e ciclo de vida podem mudar. Por isso, a documentação da ferramenta determina como o complemento é distribuído e executado. Um plugin não funciona sozinho. Ele depende do host que o executa. Uma [biblioteca](/glossario/biblioteca/) pode ser incorporada ao seu próprio projeto, enquanto um plugin precisa da aplicação que o carrega.

Uma automação precisa transformar arquivos que chegam em um formato específico. Em vez de reescrever a aplicação, você instala um plugin que faz essa conversão dentro do fluxo existente.

O plugin passa a participar das execuções seguintes. A capacidade foi adicionada ao ambiente, e a aplicação original continuou a mesma.

## Permissões e escopo O plugin recebe acesso conforme as permissões que a plataforma concede. Um complemento que edita arquivos do projeto pode ter mais alcance do que outro que apenas lê dados. O escopo declarado orienta o que o plugin pode fazer. Revisar a origem, a quantidade de downloads e as permissões pedidas antes de instalar reduz o risco de código indesejado. Uma instalação segura considera a confiança no autor e o comportamento esperado da extensão. ## Compatibilidade e manutenção Atualizar a aplicação pode quebrar um plugin desatualizado. A compatibilidade depende da versão do host e do contrato que o plugin usa. Antes de atualizar, verifique se o complemento foi adaptado à versão nova. A quantidade de plugins também afeta a manutenção. Cada complemento adiciona uma superfície de atualização e de possíveis conflitos. Um ambiente enxuto, com apenas os plugins necessários, é mais fácil de manter do que uma lista extensa de complementos pouco usados. Para avaliar quais plugins realmente agregam ao seu fluxo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) ajuda a revisar o ambiente e as extensões usadas no projeto. ### Polling: consultar um serviço de tempos em tempos - URL: https://promovaweb.com/glossario/polling - Descrição: Polling consulta um serviço repetidamente para descobrir mudanças. Veja como intervalo, paginação e retomada afetam a atualização de uma automação. ## O que é polling Polling é a consulta repetida a um serviço para descobrir mudanças ou acompanhar o andamento de uma tarefa. A integração faz uma consulta, interpreta a resposta e volta a perguntar depois do intervalo definido, até encontrar a informação necessária ou encerrar o acompanhamento. Você pode usar esse mecanismo para verificar se um relatório ficou pronto ou se apareceram novas inscrições em uma plataforma. No primeiro caso, as consultas acompanham uma tarefa específica, enquanto no segundo a rotina pode continuar procurando novidades por tempo indeterminado. ## O intervalo define parte da espera Uma mudança que acontece logo depois da consulta pode ficar sem ser percebida até a próxima tentativa. Consultar com maior frequência reduz essa espera potencial, mas também aumenta o número de chamadas que a integração faz ao serviço. Uma consulta a cada cinco minutos representa doze chamadas por hora em um exemplo sem falhas, antes de considerar [paginação](/glossario/paginacao/) ou novas tentativas. Quando cada busca precisa percorrer quatro páginas, o volume pode chegar a quarenta e oito chamadas no mesmo período. Esse cálculo permite comparar a frequência desejada com o [rate limit](/glossario/rate-limit/) da API. O intervalo do agendamento não garante o prazo de detecção, porque indisponibilidade, lentidão e tempo de processamento também entram na espera real.

Uma inscrição aparece às 10h01, depois da primeira consulta. A consulta das 10h05 encontra o registro e inicia seu processamento, produzindo quatro minutos de espera antes dessa descoberta.

Se a consulta das 10h05 falhar, a próxima tentativa precisa recuperar o período ainda não processado. Buscar apenas as inscrições dos últimos cinco minutos às 10h10 pode deixar a inscrição das 10h01 de fora.

## A retomada precisa considerar o que foi processado Uma integração pode guardar um cursor de mudanças ou um marcador de atualização fornecido pela origem. Esse marcador indica de onde continuar e deve avançar somente depois de concluir o processamento correspondente, para que uma interrupção permita recuperar o trecho pendente. Filtros por data exigem conferir se o início e o fim do intervalo entram na consulta, inclusive quando várias atualizações compartilham o mesmo horário. Reconsultar uma pequena faixa anterior e reconhecer os registros já tratados pode ser necessário, dependendo das garantias da API e da precisão de seus horários. Também é preciso percorrer todas as páginas necessárias. Se a coleção tiver várias páginas e a integração gravar o horário atual como concluído depois da primeira resposta, as páginas restantes podem ficar sem processamento mesmo que a chamada tenha retornado sucesso. ## Consultar o estado atual não revela todo o histórico Se um item muda duas vezes entre consultas, uma API que devolve apenas o estado atual pode mostrar somente a última versão. Para acompanhar cada ocorrência intermediária, você precisa de uma fonte que preserve esse histórico, como uma lista de eventos ou um registro de alterações. Algumas APIs permitem consultas condicionais, que evitam transferir novamente uma representação inalterada. A documentação do GitHub, por exemplo, explica o uso de ETag e da resposta `304 Not Modified`, mas o efeito sobre a cota de chamadas depende do serviço e das condições documentadas. ## Como conferir a rotina de consulta Compare os horários da mudança na origem e da descoberta pela integração. Acompanhe a posição de retomada após uma falha e use uma coleção distribuída em duas páginas para conferir se ambas são processadas. Antes de reduzir o intervalo para detectar mudanças mais cedo, confira a cota de chamadas disponível. Quando a origem oferece [webhooks](/glossario/webhook/), eles podem comunicar as mudanças, enquanto o polling permanece como uma conferência periódica do que deveria estar sincronizado. ### Porta de rede: o ponto de comunicação numa máquina - URL: https://promovaweb.com/glossario/porta-de-rede - Descrição: Porta de rede distingue pontos de comunicação em TCP e UDP. Entenda a escuta do processo, o firewall e o encaminhamento entre host, container e proxy. ## Definição Porta de rede é um número usado por protocolos de transporte, como TCP e UDP, para distinguir pontos de comunicação. Ao acessar um serviço, o cliente combina o [endereço IP](/glossario/endereco-ip/), o protocolo e a porta de destino. A porta pertence à configuração da comunicação, sem representar um conector físico. Uma mesma máquina pode atender aplicações diferentes em portas distintas, ou usar um intermediário para encaminhar chamadas recebidas por uma única porta. ## O processo precisa estar escutando Uma aplicação preparada para receber conexões associa sua escuta a um endereço e a uma porta. Escutar em `127.0.0.1` limita esse atendimento ao loopback da máquina, enquanto escutar em `0.0.0.0` normalmente abrange suas interfaces IPv4. O firewall pode restringir o tráfego mesmo quando o processo está escutando. A rede também precisa oferecer um caminho até o endereço utilizado pelo cliente. Por isso, uma conexão que funciona no próprio servidor ainda precisa ser testada a partir do computador que utilizará o serviço. ## O número não comprova o protocolo Números conhecidos facilitam a configuração: HTTPS costuma usar 443, por exemplo. Porém, um processo pode atender outro protocolo nesse número, e TCP e UDP possuem espaços de portas separados. O cliente também usa uma porta de origem, frequentemente atribuída de forma temporária. A conexão é distinguida por informações dos dois lados, permitindo várias comunicações simultâneas com a mesma porta de um servidor.

O processo escuta em 127.0.0.1:8080. Um computador da mesma rede tenta chegar ao endereço de rede do servidor nessa porta, mas essa interface não participa da escuta configurada.

Você confere o endereço associado ao processo antes de alterar o firewall. Para disponibilizar o serviço, a configuração precisa contemplar a interface pretendida e as origens que poderão acessá-la.

## Portas em containers e proxies Uma porta interna de um [container](/glossario/container/) pode ser publicada em outro número no host. Um [proxy reverso](/glossario/proxy-reverso/) também pode receber na porta 443 e encaminhar para uma aplicação na porta 3000. Ao investigar a conexão, descreva cada trecho com endereço, protocolo e porta. Isso evita comparar a porta pública do proxy com a porta interna como se ambas devessem responder no mesmo lugar. Imagine uma publicação da porta 8080 do host para a porta 3000 do container. O cliente acessa o endereço do host na porta 8080, enquanto a aplicação recebe o encaminhamento na porta 3000. Testar apenas a porta 3000 no host não verifica esse percurso. No container com rede própria, publicar a porta também não torna acessível por esse caminho uma aplicação que atende apenas no loopback interno. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar essa conferência, relacionando a escuta dos processos ao tráfego permitido no firewall e aos encaminhamentos do seu ambiente. ### Postman: a ferramenta para testar e explorar APIs - URL: https://promovaweb.com/glossario/postman - Descrição: Postman é uma ferramenta para testar e explorar APIs. Entenda a montagem de requisições, os métodos, as coleções e o uso no dia a dia do desenvolvimento. ## O que é o Postman Postman é uma ferramenta para testar e explorar [APIs](/glossario/api/). Em vez de escrever código para cada chamada, você monta a requisição na interface, escolhe o [método](/glossario/metodo-http/) e envia. A resposta aparece na tela. O Postman facilita o trabalho de quem consome uma API. Testar uma rota, verificar uma resposta e conferir o comportamento fica rápido sem código. A ferramenta centraliza a exploração da API. ## Montar uma requisição No Postman, você informa a [URL](/glossario/url/), escolhe o método e adiciona os dados necessários. Parâmetros, cabeçalhos e corpo completam a chamada. O envio mostra a resposta da API. A mesma requisição pode ser repetida e ajustada. Mudar o método, o corpo ou os parâmetros permite explorar o comportamento da API. O Postman organiza essa exploração.

Uma API expõe um recurso de cadastro. Em vez de escrever um script para testar, você monta a chamada no Postman.

A requisição é enviada e a resposta aparece. Conferir o comportamento da API fica rápido, e a chamada pode ser repetida e ajustada quando necessário.

## Coleções e reutilização O Postman organiza chamadas em coleções. Um grupo de requisições pode ser salvo, reutilizado e compartilhado. As coleções documentam o uso da API no fluxo de trabalho. A coleção também ajuda na repetição. Testar a mesma sequência de chamadas várias vezes fica mais simples. O Postman vira o lugar onde as chamadas da API ficam organizadas. ## Ferramenta, não substituto O Postman é uma ferramenta conveniente, mas a mesma chamada pode ser feita por outros caminhos. A [CLI](/glossario/cli/) e o código também testam a API. A escolha acompanha o fluxo de trabalho. O Postman mostra o comportamento da API para uma chamada. A verificação completa do funcionamento da aplicação inclui testes automatizados no código. A ferramenta complementa, não substitui, o teste real. Para explorar e testar a sua API com o Postman e outras ferramentas, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na montagem e na verificação das chamadas. ### Privacidade: o tratamento dos dados sensíveis do usuário - URL: https://promovaweb.com/glossario/privacidade - Descrição: Privacidade define como os dados do usuário são tratados. Entenda dados pessoais, coleta, consentimento e a diferença para segurança. ## O que é privacidade Privacidade define como os dados do usuário são tratados: o que é coletado, como é usado, onde fica armazenado e quem pode acessar. É a prática de tratar dados pessoais com transparência e dentro dos limites da finalidade. A privacidade não é apenas uma exigência técnica. Ela constrói confiança. Quando uma aplicação trata os dados com cuidado, o usuário se sente seguro para usá-la. Quando o tratamento é opaco, a confiança se perde. ## Coletar apenas o necessário Uma boa prática é coletar somente o que a aplicação precisa. Cada dado extra aumenta a responsabilidade e a superfície de exposição. Um formulário que pede só o essencial protege o usuário e simplifica a manutenção. A finalidade orienta a coleta. Um dado coletado para uma função não deve ser usado para outra sem aviso e base legal. O usuário precisa saber para que serve cada informação.

O formulário de cadastro pede nome, e-mail, telefone, endereço e dados bancários. A aplicação usa apenas o e-mail para login e notificações.

Os dados extras foram coletados sem necessidade. Reduzir a coleta ao essencial protege o usuário e diminui a responsabilidade da aplicação com dados que não usa.

## Privacidade e segurança Privacidade e segurança trabalham juntas, mas são conceitos diferentes. A [segurança](/glossario/seguranca/) protege o acesso: quem pode entrar, o que está protegido contra ataques. A privacidade define como os dados pessoais são tratados. Um sistema seguro pode violar a privacidade se coletar e usar dados além da necessidade. Um sistema privado pode ser inseguro se não proteger o acesso. As duas práticas precisam andar juntas. ## Transparência e controle O usuário deve saber o que é coletado e como é usado. Políticas claras e avisos no momento da coleta ajudam na transparência. O controle permite ao usuário saber o que a aplicação guarda sobre ele. A legislação define obrigações específicas. No Brasil, a LGPD estabelece princípios para o tratamento de dados pessoais. Conhecer a lei aplicável ao produto evita surpresas e orienta o desenho da coleta. Para revisar o tratamento de dados e a privacidade da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na coleta e no uso dos dados do usuário. ### Proatividade: a iniciativa do agente além do solicitado - URL: https://promovaweb.com/glossario/proatividade - Descrição: Proatividade descreve a iniciativa de um agente para executar tarefas além do solicitado. Veja quando ela serve e como ajustá-la na instrução dada. ## O que é proatividade Proatividade descreve a iniciativa de um [agente](/glossario/agente-de-ia/) de executar tarefas além do que foi solicitado. Em vez de apenas responder, o agente percebe nuances da solicitação e conclui etapas adjacentes que julga necessárias. Essa característica aparece quando o agente recebe uma meta e executa trabalho extra por iniciativa própria. Uma solicitação de página pode vir acompanhada de ajustes de layout e de texto, mesmo sem uma instrução específica para cada um. ## A iniciativa varia conforme o agente Modelos diferentes tratam a mesma instrução de formas distintas. Um agente mais proativo completa etapas que não foram descritas, enquanto um mais contido aguarda cada comando e não avança quando a especificação fica incompleta. Essa diferença não define qualidade. Ela define adequação: o usuário que quer delegar e se afastar se beneficia da iniciativa, enquanto o que acompanha o trabalho passo a passo prefere que o agente limite as ações ao solicitado.

Você solicita uma página com a proposta do serviço. O agente proativo ajusta também a ordem das seções e o texto de apoio, sem que você tenha descrito essas etapas.

O resultado entrega trabalho além do solicitado. Você aproveita o acréscimo quando delega, enquanto revisa o ajuste antes de aceitar quando queria apenas a estrutura básica.

## Quando a proatividade incomoda A iniciativa excessiva pode gerar trabalho adicional. Um agente que conclui duas etapas quando você queria apenas uma produz mudanças que precisam ser examinadas antes da aceitação. Para o usuário que já sabe o caminho, o acréscimo vira retrabalho. O custo também pesa, pois ações extras consomem tempo de execução e recursos do modelo. Por isso, delimitar o escopo na instrução controla o quanto o agente adianta por iniciativa própria. ## Ajustar a proatividade pela especificação A instrução orienta a iniciativa. Uma solicitação precisa, com escopo e limites claros, comunica ao agente até onde ele deve avançar. Quando a especificação cobre o comportamento esperado, o agente entende o que permanece fora da execução. Para revisar um agente que adianta além do desejado, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite acompanhar as mudanças propostas e ajustar o escopo com orientação ao vivo. ### Produção: ambiente do uso real do serviço - URL: https://promovaweb.com/glossario/producao - Descrição: Produção atende o uso real de um serviço. Entenda a separação dos ambientes, as consequências das mudanças e o acompanhamento necessário depois do deploy. ## O que é produção Produção é o ambiente que atende o uso real de um serviço. Um portal que recebe inscrições válidas e um sistema interno usado para acompanhar entregas estão em produção, mesmo que apenas o primeiro possa ser acessado pela internet. As alterações nesse ambiente podem afetar tarefas em andamento e informações que precisam ser preservadas. Você precisa saber qual serviço está atendendo essas operações antes de atualizar uma versão, mudar uma configuração ou executar uma verificação. ## O ambiente inclui mais que o servidor Uma aplicação pode usar um banco, um armazenamento de arquivos e uma API externa para completar a mesma tarefa. A continuidade do serviço depende dessas partes e das permissões que permitem acessá-las. Por isso, trocar apenas o código não descreve toda mudança em produção. Uma credencial removida ou um endereço alterado pode interromper uma integração enquanto a aplicação continua iniciando normalmente.

O ambiente chamado testes usa por engano a credencial do serviço real de mensagens. Ao experimentar uma confirmação, a aplicação envia um aviso para um contato verdadeiro.

O nome do ambiente não isolou o efeito. A conferência precisa alcançar o destino das integrações, as credenciais e os registros usados pelo teste, além do endereço da página aberta no navegador.

## Separe acessos e operações de teste Desenvolvimento e staging devem usar os destinos apropriados ao trabalho de validação. Reutilizar uma credencial de produção pode permitir que uma ferramenta de teste altere o serviço real, mesmo quando o banco local está separado. Confira também tarefas automáticas e notificações. Um ambiente de teste restaurado a partir de uma cópia pode recuperar agendamentos que precisam permanecer desativados ou apontar para destinatários controlados. ## A mudança continua depois do deploy O [deploy](/glossario/deploy/) precisa informar qual versão entrou em uso e quais verificações foram realizadas. A observação posterior permite perceber falhas que dependem de volume, de horários específicos ou de uma integração pouco usada durante a validação. Um aumento de erros após a atualização deve ser comparado com os registros anteriores e com as partes alteradas. Confira quais chamadas falharam, qual versão as atendeu e o que os serviços dependentes responderam naquele intervalo. Uma API externa indisponível pode afetar versões diferentes, por isso a proximidade do deploy não determina sozinha a causa. ## Preservar e recuperar o estado O conteúdo criado durante o uso não deve depender apenas dos arquivos do executável. Antes de uma mudança que afete registros ou arquivos, confira como eles são preservados e qual procedimento permite recuperá-los. Teste a restauração do [backup](/glossario/backup/) para conferir o conteúdo recuperado e o tempo necessário ao procedimento. Voltar à versão anterior do código também exige conferir sua compatibilidade com o banco atual e com efeitos que já aconteceram fora da aplicação. ## Como conferir o ambiente real Identifique os endereços, a versão em execução e os serviços usados no percurso de uma tarefa. Use uma verificação controlada e acompanhe seu resultado, evitando criar registros ou disparar mensagens sem saber como serão tratados. O [monitoramento](/glossario/monitoramento/) deve continuar depois dessa conferência inicial. Quando o projeto precisa revisar infraestrutura e continuidade ao longo das mudanças, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) oferece acompanhamento recorrente dentro do escopo combinado. ### Prompt: a entrada que orienta o modelo - URL: https://promovaweb.com/glossario/prompt - Descrição: Prompt reúne instruções e informações para orientar um modelo. Veja como explicitar a tarefa, separar documentos de instruções e avaliar o resultado. ## O que é um prompt Prompt é a entrada de instruções e informações utilizada para orientar um modelo. Ele comunica o trabalho esperado e pode incluir exemplos, documentos e condições que ajudam a interpretar a tarefa. Em uma aplicação de chat, a mensagem digitada é apenas uma parte possível dessa entrada. Instruções fornecidas pelo sistema e trechos recuperados pela aplicação também podem influenciar a resposta, mesmo quando não aparecem no campo de mensagem. ## Explicitar o comportamento esperado Descreva o resultado de forma que seja possível conferir sua adequação. Ao solicitar um formulário, informe os campos necessários e explique quando o cadastro deve ser aceito ou recusado. O formato da resposta merece a mesma atenção quando outro programa irá consumi-la. Uma tarefa de classificação precisa definir quais categorias são válidas e o que deve acontecer quando a entrada não permite escolher uma delas.

A tarefa solicita nome, email e telefone, mas não informa quais campos são obrigatórios. O código gerado exige todos, embora o produto devesse aceitar cadastro sem telefone.

Acrescentar a condição torna o comportamento esperado explícito. O teste com telefone vazio ainda precisa ser executado para conferir se a implementação respeitou essa informação.

## Distinguir material de referência e instrução Um documento fornecido para análise pode conter frases imperativas que pertencem ao próprio documento. A aplicação deve identificar esse material como conteúdo a examinar, evitando apresentá-lo como uma nova orientação da tarefa. Identificar o documento como referência não implementa controles de acesso e execução. Uma instrução para não alterar registros não impede tecnicamente uma ferramenta de escrita que permaneça disponível sem a verificação necessária. Para uma tarefa somente de consulta, confira também quais ações a aplicação permite executar. ## Usar exemplos sem esconder o caso geral Um exemplo pode mostrar o formato esperado e esclarecer uma situação ambígua. Para avaliar a instrução, inclua também entradas diferentes do exemplo, principalmente os casos que exigem recusa ou informação adicional. Ajustar o prompt até acertar uma única entrada não demonstra que os outros casos continuam corretos. No formulário do exemplo, teste o telefone vazio com nome e email válidos e também as entradas sem os campos obrigatórios. Registre qual versão da instrução gerou a implementação conferida para comparar os resultados após novos ajustes. ## Investigar além do texto da tarefa Uma resposta incorreta pode resultar de um documento ausente ou de uma ferramenta que retornou informação incompleta. Acrescentar mais frases ao prompt não corrige automaticamente essas partes da aplicação. Para revisar instruções e testes de um assistente usado no desenvolvimento, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação ao vivo no editor e no terminal. A sessão pode comparar o conteúdo enviado com os comportamentos esperados e investigar a origem das diferenças. ### Protocolo: como sistemas trocam e interpretam mensagens - URL: https://promovaweb.com/glossario/protocolo - Descrição: Protocolo define como sistemas trocam e interpretam mensagens. Entenda a relação entre HTTP, formatos, endereços e as camadas de uma comunicação web. ## Como os sistemas interpretam a comunicação Protocolo define como sistemas trocam e interpretam mensagens. Ele pode especificar a forma de iniciar a comunicação, a estrutura das mensagens e o significado das respostas. Os programas precisam implementar comportamentos compatíveis para que uma mensagem enviada por um lado seja compreendida pelo outro. HTTP é um protocolo usado para solicitar e entregar recursos na web. Ele define, por exemplo, o significado de métodos e códigos de resposta. Já a aplicação define quais campos exige para cadastrar um contato e como informa um email recusado. Essa separação permite que tecnologias diferentes se comuniquem. Um navegador não precisa ser escrito na mesma linguagem do servidor para solicitar uma página. Os dois precisam entender o protocolo e, quando houver uma API, o contrato daquela operação. ## Protocolo, formato e endereço Ao cadastrar um contato por uma API, o endereço indica o destino da chamada, o protocolo HTTP define a troca de mensagens e o formato JSON pode representar os campos enviados. Conhecer apenas o formato do corpo não informa qual método usar ou para onde enviar a requisição. Exigir um email no cadastro pertence ao contrato da aplicação. Acrescentar outro campo obrigatório pode exigir uma atualização do cliente, mesmo que o endereço, o protocolo e o formato permaneçam iguais. Por isso, uma mensagem compatível com HTTP e JSON ainda pode ser recusada por não atender ao cadastro previsto pelo serviço. O programa executa o processamento necessário para participar dessa comunicação. Um servidor HTTP e um navegador são softwares que utilizam o protocolo, enquanto a especificação descreve o comportamento esperado. Por isso, a documentação de HTTP pode orientar a investigação mesmo quando cliente e servidor são produtos diferentes. ## Protocolos trabalham em conjunto Uma conexão web combina funções de diversas camadas. O IP participa do endereçamento e do transporte de pacotes entre redes. Outros protocolos acrescentam propriedades necessárias para a comunicação da aplicação. HTTP/1.1 e HTTP/2 são usados com TCP, e HTTPS acrescenta proteção por TLS. HTTP/3 usa QUIC, que funciona sobre UDP e integra o estabelecimento de comunicação protegida. Portanto, afirmar que toda troca HTTP usa TCP desconsidera essa versão. Você não precisa configurar manualmente todas essas camadas ao abrir uma página. Bibliotecas, navegadores e servidores executam grande parte do trabalho. Entender a separação permite localizar melhor uma falha quando a comunicação não chega ao nível da aplicação. ## Um exemplo de compatibilidade

O navegador estabelece a comunicação e envia uma requisição segundo a versão HTTP utilizada. O servidor interpreta o método e o recurso, depois produz uma resposta. O corpo pode ser HTML, enquanto os cabeçalhos informam como tratá-lo.

Se a conexão não puder ser estabelecida, talvez não exista resposta HTTP para ler. Uma resposta 404 já informa que um servidor recebeu a chamada, mas não encontrou uma representação atual do recurso ou não deseja informar sua existência. Nesse caso, confira o destino e o caminho solicitado, além do tratamento previsto pela aplicação.

## Como separar falha de protocolo e falha da aplicação Um status inesperado ou um corpo vazio não comprova incompatibilidade de protocolo. A resposta pode ser válida e refletir uma recusa da aplicação, uma ausência de conteúdo prevista ou um erro interno. Confira o significado do retorno antes de atribuir a causa à comunicação. Compare o esquema, a porta e o serviço configurados quando a conexão falhar. Quando houver resposta, leia método, status, cabeçalhos e corpo em conjunto. O verbete de [servidor](/glossario/servidor/) explica o papel do programa que atende à chamada. ### Provisionamento: preparação dos recursos do ambiente - URL: https://promovaweb.com/glossario/provisionamento - Descrição: Provisionamento prepara os recursos de um ambiente. Entenda criação, configuração, dependências e como conferir o que está disponível para a aplicação. ## O que é provisionamento Provisionamento é a preparação e disponibilização dos recursos necessários a um ambiente. Pode incluir criar uma máquina, atribuir armazenamento ou disponibilizar um serviço de banco, conforme o que a aplicação exige. O termo aparece com escopos diferentes nas ferramentas, pois algumas incluem também a configuração inicial do sistema. Você precisa conferir o que o procedimento entrega e quais etapas continuam necessárias antes de executar a aplicação. ## Transformar necessidades em recursos disponíveis Uma aplicação que recebe anexos precisa de um local de armazenamento acessível e de permissões para gravar. Se usa um banco separado, a comunicação entre a máquina e esse banco também precisa ser preparada. Descreva essas relações junto dos recursos que serão criados. A existência de cada serviço no painel não demonstra que a aplicação consegue usá-los pela rede e pelas credenciais previstas.

A máquina e o banco foram criados com sucesso. A aplicação não consegue conectar porque o acesso de rede permitido ao banco não inclui a origem da máquina.

O provisionamento dos recursos terminou, mas a preparação do acesso ficou incompleta. O teste da conexão pelo ambiente da aplicação localiza a diferença que o status de criação não revela.

## Respeitar dependências e tempos de preparação Certos recursos precisam existir antes de configurar os seguintes, como uma rede usada pela máquina. Mesmo depois de uma solicitação aceita, o provedor pode precisar de tempo para concluir a criação e tornar o serviço acessível. A automação precisa consultar o resultado e tratar falhas ou espera prolongada. Repetir imediatamente uma solicitação sem verificar o que já foi criado pode produzir recursos duplicados, conforme o comportamento da API. ## Preparar recursos e publicar uma versão O [deploy](/glossario/deploy/) usa um ambiente para instalar ou atualizar a aplicação. Uma única automação pode provisionar esse ambiente e publicar a versão, mas os resultados de cada etapa continuam distintos. Atualizar o código do backend pode usar a máquina já provisionada. Se a nova versão exige mais memória, compare o consumo da instância durante o deploy e após a inicialização. Essa medição distingue uma falha de capacidade de um erro na instalação do pacote. ## Tratar o estado parcial Uma execução pode criar a máquina e falhar ao anexar o armazenamento. O resultado parcial precisa ser identificado, pois uma nova tentativa deve considerar os recursos existentes e as partes ainda ausentes. Antes de remover algo, confira se recebeu conteúdo que precisa ser preservado ou se outro serviço já o utiliza. A limpeza de uma tentativa incompleta não deve presumir que todo recurso criado permanece vazio e sem uso. ## Conferir a preparação pelo caminho da aplicação Teste acesso, armazenamento e conexões a partir do local que executará o serviço. Depois, registre os identificadores e as configurações necessárias para repetir a preparação ou investigar uma diferença futura. A [infraestrutura como código](/glossario/infraestrutura-como-codigo/) pode ajudar a descrever esse trabalho. Para conferir um ambiente preparado com orientação técnica ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar uma tarefa delimitada de instalação e acesso. ### Proxy reverso: intermediário diante dos servidores - URL: https://promovaweb.com/glossario/proxy-reverso - Descrição: Proxy reverso recebe chamadas e as encaminha a servidores internos. Entenda rotas, TLS, cabeçalhos e como investigar falhas entre o proxy e a aplicação. ## Definição Proxy reverso é um intermediário que recebe chamadas destinadas a um serviço e as encaminha a outros servidores. Você pode usá-lo na entrada pública de uma aplicação ou entre serviços internos, conforme a organização da rede. Para o cliente, o endereço acessado é o do proxy. A aplicação de destino, também chamada de upstream nessa configuração, atende outra conexão aberta pelo intermediário. ## Encaminhar por nome e caminho Um proxy pode selecionar o destino pelo hostname ou pelo caminho da requisição. Assim, chamadas para `/api/` podem chegar ao backend enquanto outras recebem os arquivos da interface. O caminho entregue à aplicação depende da configuração: o prefixo pode ser preservado ou removido. Essa diferença precisa corresponder às rotas que o serviço realmente atende, porque alcançar a máquina correta não comprova que a URL encaminhada exista.

O proxy preserva o prefixo e envia /api/clientes ao serviço. A conexão funciona, mas a aplicação não possui essa rota e devolve 404.

Você compara o caminho recebido no backend com o encaminhamento configurado. O ajuste pode estar na transformação da URL, sem exigir uma troca de DNS ou a reinicialização de toda a infraestrutura.

## TLS e cabeçalhos atravessam etapas distintas Quando o proxy encerra a conexão TLS, ele recebe a chamada protegida do cliente e inicia outra comunicação com a aplicação. A configuração de TLS do segundo trecho precisa ser conferida separadamente, pois o HTTPS visto no navegador comprova apenas a proteção até o proxy. Cabeçalhos encaminhados podem informar endereço de origem e protocolo usado pelo cliente. A aplicação precisa confiar nesses valores somente quando recebidos pelos intermediários previstos, pois cabeçalhos fornecidos livremente pelo cliente podem ser falsificados. ## Investigar cada trecho Confira separadamente cliente até proxy e proxy até aplicação. Um destino configurado como `localhost` precisa ser interpretado a partir do ambiente do proxy, sobretudo quando os processos estão em [containers](/glossario/container/) diferentes. Se os controles de acesso ficam no proxy, confira também a conexão direta à aplicação a partir das redes que não deveriam alcançá-la. Uma porta interna publicada no host pode criar outro caminho de entrada. Restrinja esse acesso conforme a arquitetura do projeto e teste se uma chamada recusada pelo proxy também pode chegar diretamente ao backend. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar a análise dos encaminhamentos e das respostas, relacionando a configuração do proxy às rotas do seu projeto. ### Pull request: proposta de mudança para revisão - URL: https://promovaweb.com/glossario/pull-request - Descrição: Pull request reúne uma proposta de mudança para revisão. Entenda origem, destino, novas revisões, verificações e formas de incorporar o trabalho. ## O que é um pull request Pull request é uma proposta, organizada por uma plataforma de colaboração, para incorporar mudanças de uma branch em outra. Ela reúne a comparação dos arquivos, a descrição da alteração e a discussão sobre o trabalho. Você pode usá-lo para explicar uma correção, receber comentários e acompanhar verificações antes da integração. Sua existência não comprova que houve revisão nem que o conteúdo foi aceito. ## Origem e destino delimitam a proposta A branch de origem contém o trabalho proposto, enquanto a base indica onde você pretende incorporá-lo. Uma base incorreta pode fazer a comparação incluir mudanças que não pertencem à tarefa. Confira esses dois lados e descreva o comportamento que será alterado. Uma explicação útil permite relacionar o problema, os arquivos modificados e a forma de verificar o resultado.

A proposta recebe aprovação para uma alteração na mensagem de erro. Depois, um novo commit modifica também a condição que aceita o cadastro.

A aprovação anterior não demonstra que essa condição foi examinada. O conteúdo novo precisa ser revisto, e a plataforma pode exigir outra aprovação conforme a proteção configurada.

## A proposta acompanha novas revisões Commits enviados à branch de origem normalmente atualizam o mesmo pull request. Enquanto isso, a branch de destino pode avançar por outras mudanças e alterar as condições da futura integração. Confira se os testes aprovados correspondem ao conteúdo atual da proposta. Comentários podem apontar para versões anteriores do arquivo, então confira se o ajuste solicitado ainda corresponde ao trecho apresentado. ## Revisão e verificações têm alcances diferentes Um teste automatizado examina os casos configurados, enquanto a revisão pode identificar escopo incorreto ou uma hipótese que o teste não cobre. Os dois resultados precisam ser relacionados à revisão que será integrada. Uma proposta em rascunho permite discutir o trabalho ainda incompleto. No GitHub, ela não pode ser integrada enquanto permanecer nesse estado. A descrição deve distinguir o que já funciona do que falta implementar ou conferir, para que a revisão considere o alcance apresentado. ## Incorporar ou encerrar a proposta A plataforma pode oferecer commit de merge, squash ou rebase, com efeitos diferentes sobre o histórico. Encerrar o pull request sem integrar mantém a discussão registrada, mas não incorpora automaticamente seus arquivos ao destino. A [branch](/glossario/branch/) e a [comparação dos arquivos](/glossario/diff/) ajudam a entender o conteúdo apresentado. Depois da integração, confira o estado produzido e as verificações correspondentes, principalmente quando houve resolução de conflitos ou mudanças adicionais. ### RAG: geração orientada por conteúdo recuperado - URL: https://promovaweb.com/glossario/rag - Descrição: RAG combina recuperação de conteúdo e geração de respostas. Entenda preparação da base, seleção de trechos, atualização e conferência das fontes. ## O que é RAG RAG significa Retrieval-Augmented Generation, ou geração aumentada por recuperação. A abordagem combina a busca de conteúdo com o uso desse material por um modelo para produzir uma resposta. A recuperação oferece informações disponíveis fora dos parâmetros do modelo, como documentação do produto. Isso permite consultar uma coleção atualizada sem exigir um novo treinamento do gerador a cada alteração na base. ## Preparar a base para a consulta O fluxo costuma organizar os documentos para que possam ser encontrados e fornecidos em partes úteis. A divisão em trechos precisa preservar condições que alteram a interpretação, como a versão da ferramenta ou o tipo de acesso descrito. A busca pode ser textual, vetorial ou combinar mecanismos. A escolha depende do conteúdo e das perguntas esperadas, sem obrigatoriedade de usar um banco vetorial em toda implementação.

A base contém duas versões do manual com limites de exportação distintos. A recuperação entrega um trecho de cada versão, e o modelo reúne os números numa mesma orientação.

Os documentos existem, mas a resposta mistura condições incompatíveis. A correção exige identificar a versão pretendida, filtrar os trechos e conferir se a orientação final corresponde à mesma edição.

## Separar falha de busca e falha de geração Quando a resposta está incorreta, examine primeiro o material recuperado. Se o trecho necessário não foi entregue, o problema pode estar na coleção, nos filtros ou na ordenação da busca. Se o material correto estava disponível, confira como a resposta o utilizou. O modelo pode omitir uma exceção ou acrescentar uma afirmação sem apoio, mesmo recebendo o trecho pertinente. ## Manter atualização e acesso no fluxo Alterar o documento original não atualiza automaticamente todas as cópias usadas pela aplicação. O processo precisa tratar a indexação, a remoção de versões antigas e os resultados armazenados que possam continuar sendo reutilizados. A recuperação também deve respeitar as permissões dos documentos. Uma fonte ser relevante para a pergunta não autoriza sua entrega a qualquer pessoa ou a qualquer execução do assistente. ## Avaliar a resposta com o material utilizado Confira se as afirmações encontram apoio nos trechos e se as referências apontam para a versão correspondente. Quando a coleção não contém a resposta, o fluxo precisa permitir reconhecer essa ausência, sem apresentar um conteúdo semelhante como confirmação. Para investigar respostas divergentes numa base consultada por IA, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite examinar busca e geração com orientação ao vivo. A sessão pode acompanhar o material selecionado e sua utilização na resposta final. ### Rate limit: limite de operações por período - URL: https://promovaweb.com/glossario/rate-limit - Descrição: Rate limit restringe chamadas ao longo do tempo. Entenda quantidade, intervalo, escopo, respostas 429 e como coordenar o consumo entre automações. ## O que é rate limit Rate limit é uma restrição à frequência ou à quantidade de chamadas permitidas por um serviço durante determinado período. Ele pode limitar o acesso de uma credencial, de uma organização ou de um recurso específico, conforme o contrato da API. Uma integração que sincroniza inscrições precisa usar essa capacidade disponível sem presumir que cada workflow tem uma cota própria. Se três automações compartilham a mesma credencial, o destino soma as chamadas das três. ## Quantidade, intervalo e escopo Informar sessenta chamadas por minuto descreve apenas parte da política. Você ainda precisa saber como o serviço mede esse minuto, se aceita um pico de chamadas de uma vez e se há outros limites aplicados ao mesmo endpoint. Uma janela fixa reinicia seu cálculo em momentos definidos, enquanto uma janela móvel considera o período recente. Outros mecanismos permitem um pico limitado e repõem gradualmente a capacidade, por isso duas APIs com o mesmo total anunciado podem recusar sequências diferentes de chamadas.

Um workflow consome quarenta chamadas e outro tenta usar mais trinta no mesmo período. Cada fluxo isolado parece estar abaixo de sessenta, mas o consumo combinado ultrapassa a cota.

O controle precisa coordenar os dois envios ou reservar capacidade para cada tarefa. Colocar uma pausa apenas no segundo workflow não informa quanto o primeiro ainda poderá consumir.

## Como interpretar uma recusa O status HTTP `429 Too Many Requests` é usado para indicar excesso de chamadas. A resposta pode trazer informações adicionais, como o prazo de espera e o motivo específico, mas o formato e a presença desses campos dependem do serviço. ```http HTTP/1.1 429 Too Many Requests Retry-After: 30 ``` Nesse exemplo, o header orienta uma espera de trinta segundos antes de nova tentativa. O mesmo header também pode usar uma data HTTP, então a integração precisa interpretar o formato recebido e respeitar as instruções da API. Nem toda falha simultânea é causada pelo rate limit, e nem todo `429` identifica exatamente a mesma restrição. Leia os detalhes da resposta para distinguir o limite global, o limite de um endpoint e outras condições que o fornecedor documentar. ## A concorrência mede outra coisa A [concorrência](/glossario/concorrencia/) controla quantas tarefas ficam em andamento ao mesmo tempo. Uma tarefa rápida pode fazer muitas chamadas em sequência, enquanto várias tarefas lentas podem passar boa parte do tempo aguardando sem realizar novos acessos. Também confira o consumo gerado por [paginação](/glossario/paginacao/) e retries. Uma sincronização que busca dez páginas e repete duas chamadas usa uma parcela maior da cota que a estimativa baseada apenas no número de execuções do workflow. ## Como distribuir o trabalho Uma fila e um controle compartilhado de envio podem distribuir chamadas conforme a capacidade disponível. Separar cem contatos em dez [batches](/glossario/batch/) de dez itens ainda produz cem chamadas se cada contato for enviado individualmente. O lote define o agrupamento do trabalho, enquanto a quantidade de requisições depende de como a integração envia seus itens. Depois de uma recusa, repetir imediatamente pode consumir mais recursos sem produzir resultado. O [backoff](/glossario/backoff/) deve respeitar a orientação do serviço e encerrar conforme os limites definidos para a recuperação. ## Como verificar o consumo Registre o endpoint, o horário, a credencial identificada de forma não sensível e o resultado de cada chamada. Compare o consumo conjunto com o escopo documentado e confira se a espera é aplicada também às novas tentativas. O teste precisa considerar outras automações que usam a mesma cota. Um fluxo que funciona sozinho ainda pode receber recusas quando a importação, a sincronização e o relatório diário executam juntos. ### Recuperação de informação: seleção de conteúdo - URL: https://promovaweb.com/glossario/recuperacao-de-informacao - Descrição: Recuperação de informação busca conteúdo pertinente a uma consulta. Entenda índice, ordenação, filtros e diferenças entre encontrar e gerar respostas. ## O que é recuperação de informação Recuperação de informação é o processo de localizar conteúdo pertinente a uma consulta dentro de uma coleção. O resultado pode ser uma lista de documentos, registros ou trechos que serão apresentados diretamente ou utilizados por outra etapa da aplicação. Ela não exige geração de texto. Um mecanismo de busca que devolve páginas relacionadas já realiza recuperação, enquanto um sistema de [RAG](/glossario/rag/) acrescenta o uso do material encontrado na produção de uma resposta. ## A coleção pesquisada delimita os resultados A busca só consegue devolver o conteúdo acessível ao seu mecanismo de consulta. Se uma página nova ainda não entrou no índice, reformular a pergunta pode não resolver sua ausência nos resultados. Antes de ajustar a ordenação, confira quais documentos foram incluídos e como foram divididos. Um trecho isolado pode perder o título ou a condição que explicava a qual versão a instrução se aplicava.

A documentação nova muda o formato exportado, mas o índice ainda contém apenas a edição anterior. A pergunta retorna um trecho bem relacionado ao assunto e tecnicamente correto para a versão antiga.

A posição no resultado não corrige a falta de atualização. A investigação precisa conferir a coleção indexada e a versão do documento antes de alterar a forma da pergunta.

## Palavras, vetores e combinação de resultados A recuperação textual compara termos conforme a análise configurada, que pode normalizar grafias ou aplicar outros tratamentos linguísticos. A busca vetorial usa [embeddings](/glossario/embedding/) para comparar representações do conteúdo. Essas abordagens respondem de maneira diferente a uma consulta por assunto e a uma consulta por um código exato. Sistemas híbridos combinam resultados dos dois mecanismos, com uma forma explícita de ordenar a lista final. ## Aplicar filtros além da relevância Uma consulta pode precisar limitar a versão, o idioma ou os documentos disponíveis na sessão autenticada. Relevância temática não concede acesso a um conteúdo que a aplicação deveria restringir. O filtro precisa participar do fluxo de recuperação e entrega. Retirar uma referência da resposta final não desfaz a exposição se um documento indevido já foi fornecido ao modelo ou registrado num local acessível. ## Conferir a seleção antes da resposta Use perguntas com documentos esperados e examine quais resultados apareceram nas posições utilizadas pela aplicação. Inclua consultas sem resposta disponível para observar se o mecanismo retorna material apenas parecido. Para revisar a seleção de trechos num assistente, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a investigação da busca. A sessão pode comparar a consulta, os filtros e a coleção efetivamente pesquisada. ### Recurso: a entidade que a API expõe e identifica - URL: https://promovaweb.com/glossario/recurso - Descrição: Recurso é a entidade que a API expõe. Entenda a identificação por URL, a representação no formato escolhido e a operação pelo método HTTP. ## O que é um recurso Recurso é a entidade que uma [API](/glossario/api/) expõe e identifica. Um usuário, um pedido, um pet: cada um é um recurso que a API permite consultar e alterar. O recurso é o alvo das chamadas. O recurso não é a mesma coisa que o dado interno. É a exposição da entidade pela API. A forma como o recurso é identificado e representado define como quem consome a API interage com o conteúdo. ## Identificar o recurso A [URL](/glossario/url/) identifica o recurso. O caminho mostra o tipo de recurso, e o identificador mostra o elemento específico. `/pets` representa o conjunto, e `/pets/5` representa um elemento dentro dele. O método HTTP comunica a operação sobre o recurso. Consultar, criar, substituir ou remover usam verbos diferentes. O recurso é o mesmo, e a ação é definida pelo [método](/glossario/metodo-http/) da chamada. ## Representação do recurso A resposta entrega o recurso em uma representação. O formato mais comum é o [JSON](/glossario/json/), que estrutura o conteúdo em campos e valores. A representação descreve o estado do recurso no momento da chamada. O formato da representação é parte do contrato da API. Quem consome precisa entender a estrutura para usar o conteúdo. A documentação informa os campos e o formato esperado em cada operação.

Uma negociação pertence a um usuário. No caminho `/users/5/deals/2`, o recurso principal é a negociação 2, dentro do contexto do usuário 5.

O caminho identifica a relação entre os recursos. A chamada age sobre o recurso apontado, e o método define a operação executada.

## Recurso e sub-recurso Um recurso pode conter ou se relacionar com outros. O [sub-recurso](/glossario/sub-recurso/) aparece dentro de um contexto no caminho. A relação entre recursos ajuda a organizar a API conforme o domínio. Modelar os recursos acompanha a realidade do negócio. Um usuário com pedidos, uma loja com produtos: cada relação vira um caminho que comunica o contexto. O recurso é a base dessa organização. Para modelar os recursos da sua API e a relação entre eles, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização das chamadas. ### Refatoração: reorganizar sem mudar o comportamento - URL: https://promovaweb.com/glossario/refatoracao - Descrição: Refatoração reorganiza o código preservando seu comportamento. Veja como delimitar a alteração, conferir resultados e separar reorganização de correção. ## O que é refatoração Refatoração é a reorganização da estrutura interna do código sem alterar seu comportamento observável. Uma função pode ser dividida, uma responsabilidade pode mudar de lugar e um nome pode ficar mais preciso, preservando as respostas e os efeitos observados pelas partes que utilizam esse código. Essa preservação define a prática, mas não é garantida pelo nome da tarefa. Se a alteração muda quais cadastros são aceitos, existe também uma mudança funcional que precisa ser identificada e conferida como tal. ## Delimitar o comportamento antes de reorganizar Observe as entradas, as respostas e os efeitos produzidos pelo trecho que será alterado. No caso de uma validação, importa conferir os cadastros recusados e as mensagens retornadas, além dos cadastros aceitos. A ordem das verificações também pode aparecer no resultado. Se dois campos estão incorretos e a aplicação apresenta apenas o primeiro erro, trocar essa ordem pode mudar a resposta mesmo mantendo todas as condições individuais.

Uma função verifica primeiro o preenchimento do nome e depois o do email, retornando uma única mensagem. A proposta extrai essas verificações para funções menores e mantém a chamada da verificação do nome antes da verificação do email.

Quando os dois campos estão vazios, o resultado deve continuar apontando o nome, conforme o comportamento anterior. Um teste apenas com cadastros válidos não detectaria a troca da ordem.

## Fazer alterações que possam ser conferidas Uma sequência de transformações pequenas permite relacionar uma falha à alteração recém-feita. Execute as verificações relevantes antes de começar e novamente depois de cada transformação que precise preservar o resultado. Ferramentas do editor podem ajudar numa renomeação, mas o alcance da operação exige conferência. Um nome usado em configuração, texto gerado ou chamada dinâmica pode não receber a mesma atualização automática feita nas referências reconhecidas pelo editor. ## Tratar testes ausentes e defeitos existentes Quando o comportamento atual não está descrito, prepare casos que permitam observá-lo antes da mudança. Use exemplos representativos dos fluxos afetados, sem concluir que a ausência de testes torna impossível toda reorganização. Se a validação atual aceitar um cadastro que deveria recusar, registre a correção funcional separadamente da extração das funções. Assim, a revisão pode conferir primeiro se a reorganização preservou os resultados e depois qual condição foi corrigida. A recusa nova precisa de um teste próprio, além dos casos que demonstram a preservação. ## Avaliar a estrutura resultante Depois da refatoração, retome uma mudança prevista para o trecho. No formulário do exemplo, localize a validação do email e confira se você consegue alterá-la sem procurar a mesma verificação em várias funções. Avalie também se o código que as chama deixa clara a ordem dos erros, pois dividir o trecho não deve esconder esse comportamento. A relação com [dívida técnica](/glossario/divida-tecnica/) aparece no esforço das próximas mudanças. Para reorganizar um trecho com orientação durante a execução, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar no editor e conferir os comportamentos durante uma sessão ao vivo. ### Registro: a linha concreta de uma tabela - URL: https://promovaweb.com/glossario/registro - Descrição: Registro é uma linha de uma tabela relacional. Entenda valores, consultas, identidade e como conferir quais linhas uma atualização realmente afeta. ## Uma linha concreta na tabela Em uma tabela relacional, registro é uma linha formada pelos valores de suas colunas. Uma tabela de contatos pode ter colunas para identificador, nome e email. Cada linha reúne os valores de uma ocorrência armazenada. O conceito é específico ao uso discutido aqui. A palavra “registro” também aparece em logs e documentos, mas neste verbete indica uma linha de tabela. Essa delimitação permite entender o que uma consulta ou atualização está manipulando. Se a tabela contém três contatos, existem três registros, mesmo que dois tenham o mesmo nome. Para selecionar apenas um deles, use a chave que identifica aquela linha. A posição na listagem pode mudar com a ordenação ou a paginação e não serve como identidade do contato. ## Consultar apenas os campos necessários A consulta seleciona as colunas `id` e `nome` da linha correspondente. Ela não devolve automaticamente todas as colunas da tabela. Se `id` for uma chave única, o resultado terá no máximo uma linha, que pode estar ausente. Uma consulta com filtros mais amplos pode devolver várias linhas. Já consultas com agregações ou junções podem produzir resultados que não correspondem diretamente a um único registro armazenado. Leia a consulta para entender o que cada linha do resultado representa.

Você localiza o registro pelo identificador e confere os campos atuais. A atualização deve atingir a linha pretendida e preservar os valores que não fazem parte da alteração. Depois, uma nova consulta confirma o resultado.

Se o filtro usar apenas um nome compartilhado por vários contatos, a atualização pode atingir mais de uma linha. O problema está na seleção do alvo, mesmo que a tabela possua uma chave primária correta.

## Registro e entidade Entidade descreve um conceito do modelo, como Contato, cuja representação no banco pode ocupar uma ou várias linhas. Um contato com vários telefones, por exemplo, pode ter uma linha de cadastro e outras em uma tabela de telefones relacionados. Nesse desenho, ler somente o cadastro não recupera toda a representação do contato. Históricos também podem registrar diferentes estados ao longo do tempo. Nesse caso, você precisa distinguir a identidade da entidade da identidade de cada versão armazenada. A consulta deve selecionar o estado apropriado para a ação solicitada. ## Valores ausentes e restrições Uma coluna pode aceitar `NULL` para representar ausência de valor, conforme o modelo. Em um campo de quantidade, zero informa uma quantidade conhecida, enquanto a ausência pode indicar que ela ainda não foi informada. Converter os dois para o mesmo valor na leitura ou na atualização apagaria essa diferença. Tipos e restrições limitam o que pode ser gravado. Um campo obrigatório, uma referência e uma restrição de unicidade podem impedir determinada linha. O erro precisa ser tratado pela aplicação, sem assumir que todo conteúdo recebido já está pronto para persistência. ## Como conferir uma operação sobre registros Use um conjunto conhecido em desenvolvimento e confira os filtros antes da alteração. Depois, observe a quantidade de linhas afetadas e consulte o resultado. Se a atualização deveria atingir uma linha e modificou várias, investigue o filtro e as restrições envolvidas. O verbete de [chave primária](/glossario/chave-primaria/) explica como declarar a identidade utilizada para selecionar uma linha de forma única. ### Registry: armazenamento de imagens de container - URL: https://promovaweb.com/glossario/registry - Descrição: Registry armazena e distribui imagens de container. Entenda repositórios, tags, digest, permissões de publicação e leitura e a conferência do download. ## O que é um registry Registry é um serviço que armazena e distribui imagens de container. O processo de build pode enviar uma imagem para ele, permitindo que outra máquina obtenha o conteúdo necessário para criar suas instâncias. Esse serviço pode ser público ou exigir autenticação e permissões. Você precisa conhecer o endereço e a referência da imagem, além de conferir se o ambiente de destino pode acessá-la. ## Registry, repositório e tag Dentro de um registry, um repositório agrupa imagens relacionadas, normalmente pelo nome de uma aplicação. As tags identificam referências dentro desse repositório, como uma versão ou um canal de distribuição. Uma referência fictícia como registry.example.com/portal:1.4.0 combina o endereço do serviço, o repositório portal e a tag 1.4.0. O repositório de imagens tem outra função que o [repositório Git](/glossario/repositorio/), mesmo quando ambos aparecem na mesma plataforma.

A alteração é enviada ao Git, e o build cria a imagem na máquina de integração. A etapa que deveria publicar no registry falha por falta de permissão.

O servidor de execução não encontra a referência esperada no download. Consultar o resultado do envio e o repositório de imagens distingue essa falha de um problema no código da aplicação.

## Publicar e baixar são ações diferentes O push envia a imagem ao registry, enquanto o pull obtém seu conteúdo para o ambiente local. Essas ações podem usar permissões diferentes, e uma credencial aceita para leitura não precisa ter autorização para substituir ou remover imagens. O sucesso da autenticação também não garante acesso a todos os repositórios. Confira a permissão específica e o nome completo usado na chamada quando o serviço recusar uma publicação ou um download. ## Tags podem mudar de associação O registry pode permitir a associação de uma tag existente a outro conteúdo. Se dois servidores baixarem a mesma tag em momentos diferentes, poderão obter imagens distintas, conforme a política de publicação e o cache local. O digest permite selecionar o conteúdo referenciado de forma mais precisa. Já a tag latest não significa automaticamente a versão mais recente ou estável, pois seu significado depende de como ela foi publicada. ## Retenção afeta instalações futuras Uma limpeza pode remover imagens antigas que ainda seriam necessárias para recuperar uma versão. O fato de um container continuar funcionando não comprova que outra máquina conseguirá baixar novamente a imagem usada por ele. Defina a retenção de acordo com as versões que precisam continuar instaláveis. Confira também as dependências de acesso ao registry, pois uma falha de rede ou uma credencial expirada pode impedir a criação de novas instâncias durante uma recuperação. ## O download não realiza o deploy Obter uma imagem deixa seu conteúdo disponível, mas não substitui automaticamente containers já existentes. O [deploy](/glossario/deploy/) precisa selecionar o resultado e aplicar a atualização com as configurações do ambiente. Compare a identidade publicada com aquela realmente usada pelas instâncias. Essa conferência permite localizar uma versão antiga em execução mesmo quando a imagem nova já está armazenada corretamente no registry. ## Como conferir o percurso da imagem Observe a saída do build, o envio ao repositório e o download pelo ambiente que fará a instalação. Cada etapa deve apontar para a imagem prevista, sem presumir que a conclusão de uma delas confirma as seguintes. Quando a publicação falha entre a construção e a execução, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode orientar a investigação dessa tarefa ao vivo. O ponto de partida é a etapa que recusou a ação e a referência que o destino tentou obter. ### Regra de negócio: a restrição do domínio que orienta o sistema - URL: https://promovaweb.com/glossario/regra-de-negocio - Descrição: Regra de negócio expressa condições do domínio que o sistema deve respeitar. Entenda permissões, cálculos, exceções e conferência em diferentes entradas. ## Definição Regra de negócio é uma condição do domínio que orienta ou restringe seu funcionamento. Ela pode definir uma permissão, um cálculo ou uma relação que o sistema precisa respeitar para representar corretamente o produto. Essa condição pode existir antes do software ou ser definida durante sua criação. O que importa é sua justificativa no negócio, independentemente da linguagem de programação escolhida para implementá-la. ## Separar comportamento e mecanismo Uma escola pode estabelecer que uma turma aceita até vinte inscrições confirmadas. Essa condição descreve o funcionamento pretendido, enquanto a forma de verificar a quantidade e registrar cada inscrição pertence à implementação. Trocar o banco ou reorganizar uma função não deveria alterar essa condição sem uma mudança correspondente no produto. Por isso, a [especificação](/glossario/especificacao-spec/) precisa registrar o significado de inscrição confirmada e os estados que participam da quantidade.

As duas chamadas consultam a mesma quantidade antes de gravar e ambas encontram uma vaga. Se cada uma confirmar separadamente sem proteger a verificação, a turma pode terminar com vinte e uma inscrições.

O limite continua em vinte, mas o teste sequencial não revelou o problema. Você precisa conferir também o acesso simultâneo e implementar uma forma consistente de preservá-lo.

## Definir exceções e vigência Se houver permissão para ampliar a turma, descreva a ação autorizada e seu efeito sobre a capacidade. Uma exceção sem definição deixa a aplicação dependente de interpretações diferentes para a mesma situação. Mudanças também podem exigir uma data de vigência ou tratamento para registros anteriores. Alterar a capacidade padrão das novas turmas, por exemplo, não determina automaticamente o que acontece com turmas já abertas. ## Conferir os caminhos de entrada A aplicação pode receber inscrições pela tela e por uma integração. Aplicar a verificação somente no formulário deixa a segunda entrada capaz de produzir um resultado que o negócio não permite. Relacione essa condição aos [requisitos](/glossario/requisito/) e aos testes que a exercitam, incluindo os estados relevantes. O nome da função ou a existência de uma mensagem de recusa não comprovam que todas as gravações a preservam. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar essa conferência no seu código, examinando os caminhos que alteram o mesmo registro. ### Regressão: quando algo que funcionava deixa de funcionar - URL: https://promovaweb.com/glossario/regressao - Descrição: Regressão é a perda de um comportamento que funcionava. Entenda como reproduzir a falha, comparar versões e acrescentar um teste que acompanhe a correção. ## O que é uma regressão Regressão é a perda de um comportamento que funcionava antes de uma mudança. Ela pode atingir o recurso alterado ou aparecer em outro fluxo que depende da mesma condição, mesmo sem modificações diretas nos arquivos desse fluxo. Um defeito recém-descoberto não é necessariamente uma regressão. Para fazer essa distinção, você precisa comparar o resultado atual com uma versão ou condição anterior que atendia ao comportamento esperado. ## Reproduzir a diferença observada Registre a entrada usada, o resultado esperado e o retorno obtido. Uma descrição como “a edição falhou” ainda deixa abertas condições que podem explicar por que o problema aparece apenas em alguns registros. Confira também a versão da aplicação e as dependências do ambiente. Se o mesmo código foi executado com outra configuração, atribuir a falha ao último commit pode levar a uma investigação incorreta.

Uma validação compartilhada começa a exigir um campo no cadastro inicial. O formulário de edição não envia esse campo e recebe uma recusa ao atualizar apenas o telefone.

O teste reproduz a edição de um registro existente com a mesma entrada que funcionava antes. Essa comparação expõe a diferença entre validar um cadastro novo e aceitar uma atualização parcial.

## Investigar as mudanças candidatas O histórico de [commits](/glossario/commit/) permite examinar quais alterações ocorreram entre dois estados conhecidos. A comparação dos arquivos mostra o código modificado, mas a relação entre essas linhas e a falha ainda precisa ser demonstrada. No exemplo, confira onde a validação compartilhada é chamada durante a edição e qual campo exigido causou a recusa da atualização. Quando há muitas versões intermediárias, uma busca com git bisect pode ajudar a localizar a primeira revisão que apresenta o resultado indesejado. A comparação exige um teste confiável e condições compatíveis entre as versões examinadas. ## Acrescentar um teste que reproduza o defeito O cenário novo deve falhar pela causa investigada antes da correção e passar depois dela. Verifique a mensagem da falha para não confundir a reprodução com um erro de preparação, como uma dependência ausente. Confira também os caminhos próximos que a correção pode afetar. No exemplo, aceitar a edição parcial não deve remover automaticamente a exigência válida para o cadastro inicial. ## Interpretar uma falha na suíte Um teste que começou a falhar sinaliza uma diferença a investigar. Instabilidade no ambiente, dependência externa indisponível ou interferência entre testes também podem explicar o resultado, sem demonstrar uma regressão no código alterado. Para reproduzir uma falha que surgiu após uma mudança, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a investigação no editor e no terminal. O trabalho pode incluir a comparação das versões e a construção do cenário que acompanha a correção. ### Relacionamento: associação entre entidades - URL: https://promovaweb.com/glossario/relacionamento - Descrição: Relacionamento associa entidades e define quantos vínculos são permitidos. Entenda cardinalidade, tabelas de associação e restrições no banco relacional. ## Como os conceitos se associam Relacionamento é uma associação definida entre entidades ou suas ocorrências. Um estudante pode participar de turmas, e cada turma pode reunir vários estudantes. O modelo precisa descrever esse vínculo e as quantidades permitidas de cada lado. Essas quantidades são chamadas de cardinalidade. Relações um para um, um para muitos e muitos para muitos representam combinações diferentes. A obrigatoriedade também importa, pois permitir zero vínculos não equivale a exigir pelo menos um. Considere um produto que permite cadastrar participantes antes de escolherem uma turma e abrir turmas ainda sem inscrições. Nesse caso, ambos os cadastros precisam existir sem uma matrícula associada. Quando o produto exige uma inscrição já no cadastro, essa exigência também precisa aparecer no comportamento da aplicação. ## Um para muitos e muitos para muitos Em um modelo com uma organização responsável por vários contatos, cada contato pode guardar a referência a essa organização. A coluna do lado dos contatos permite representar a relação um para muitos. A chave estrangeira pode conferir a existência da organização indicada. Já um estudante pode participar de várias turmas, e cada turma pode reunir vários estudantes. Em um banco relacional, uma tabela de associação, como `matriculas`, representa cada vínculo. Ela também pode guardar informações próprias, como a data da inscrição. O exemplo pressupõe a existência das tabelas referenciadas. A chave composta impede repetir a mesma combinação de estudante e turma. Se o produto permitir várias matrículas históricas nesse mesmo par, a estrutura precisará representar essa condição de outra forma.

A tabela de associação contém um vínculo para cada turma. O cadastro do estudante não precisa ser duplicado para representar a segunda participação. A consulta pode reunir as matrículas e apresentar o histórico.

Se a estrutura permitisse apenas um campo de turma no cadastro da pessoa, a nova inscrição poderia substituir a anterior. O armazenamento não atenderia ao comportamento descrito para esse produto.

## Um para um exige uma restrição adequada Uma chave estrangeira sozinha normalmente permite que várias linhas apontem para o mesmo registro. Para representar um vínculo um para um, pode ser necessária uma restrição de unicidade na referência. A declaração precisa corresponder à cardinalidade pretendida. Também é preciso definir o efeito da exclusão. Remover um lado pode ser recusado, propagar alterações ou encerrar o vínculo, conforme a política adotada. Essas consequências não devem ser deduzidas apenas pelo nome das tabelas. ## Modelo e consulta não são a mesma coisa O relacionamento descreve a associação, enquanto uma consulta escolhe como ler os registros. Um `JOIN` pode combinar linhas mesmo sem uma chave estrangeira declarada. Isso não significa que o banco esteja garantindo a validade daquele vínculo nas gravações. ## Como conferir a cardinalidade Teste zero, um e vários vínculos conforme os casos permitidos. Faça a leitura nos dois sentidos e confira se o modelo preserva todas as ocorrências necessárias. Inclua duplicidade e exclusão nos testes de desenvolvimento. O verbete de [chave estrangeira](/glossario/chave-estrangeira/) explica a restrição usada para conferir referências no banco. ### Release de job: devolver o job à fila sem executar - URL: https://promovaweb.com/glossario/release-de-job - Descrição: Release de job devolve um job à fila sem executar, preservando tentativas para processamento posterior. Veja quando liberar de volta, as condições e a relação com novas tentativas. ## O que é release de job Release de job é a ação de devolver um [job](/glossario/job/) à [fila](/glossario/fila/) sem executá-lo, preservando a tentativa para processamento posterior. O worker identifica que não pode concluir o trabalho no momento e libera o job de volta. A diferença em relação à falha é importante: o release não registra erro nem encerra o ciclo. Ele adia a execução, mantendo o job disponível para uma próxima tentativa quando a condição impedida for resolvida. ## Quando liberar o job de volta O release é usado quando o worker não pode executar a tarefa naquele momento, mas a condição pode mudar. Um serviço temporariamente indisponível, um recurso ocupado ou uma chamada que exige espera são situações nas quais devolver o job faz sentido. A devolução pode ser condicional. O sistema devolve apenas quando uma condição se aplica, e em outros casos segue com o processamento. Essa escolha permite tratar o trabalho de forma específica, sem tratar toda situação como falha.

O worker tenta processar o job e percebe que o serviço de destino está indisponível. Ele devolve o job à fila, preservando a tentativa.

O job aguarda a disponibilidade do serviço e é processado depois. A devolução evitou registrar uma falha permanente e permitiu a execução posterior.

## Release, retry e backoff O release se relaciona com o [retry](/glossario/retry/) e o [backoff](/glossario/backoff/). A devolução pode vir acompanhada de um atraso, espaçando a próxima tentativa. O backoff define esse intervalo após a falha, enquanto o release devolve o job à fila. A combinação entre devolver, atrasar e registrar tentativas define o ciclo de reprocessamento. Sem controle, um job pode voltar à fila indefinidamente ou consumir todas as tentativas sem concluir. O desenho do fluxo define o limite. ## Conferir o que acontece com a tentativa O release preserva ou consome tentativa conforme o mecanismo: alguns sistemas registram a devolução como tentativa, outros não. A conferência do contrato da fila evita supor que o job será processado depois sem considerar o limite de tentativas. Para revisar o ciclo de devolução e retentativa do seu fluxo, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise da fila junto à implementação. ### Release: versão organizada para disponibilização - URL: https://promovaweb.com/glossario/release - Descrição: Release reúne uma versão e suas informações de distribuição. Veja a relação com tags, artefatos, notas de atualização e o deploy em cada ambiente. ## O que é uma release Release é uma versão do software organizada para distribuição ou disponibilização. Ela identifica o que está sendo entregue e pode reunir notas de atualização, instruções e os [artefatos](/glossario/artefato/) correspondentes, conforme a convenção do projeto. As notas permitem consultar o que mudou antes de instalar a versão. Você consegue relacionar uma correção anunciada ao pacote que a contém e conferir as instruções aplicáveis àquela atualização. ## O termo depende do processo adotado No GitHub, uma release se associa a uma tag Git e pode incluir notas e arquivos para download. A tag marca um ponto do histórico, enquanto a release reúne as informações que você consulta para instalar aquela versão. Outros processos empregam o termo de forma mais específica. Na metodologia Twelve-Factor, a release combina o build com a configuração usada na execução, portanto vale conferir o significado adotado pela ferramenta antes de comparar seus registros. ## O número precisa seguir uma convenção Uma versão como 2.1.0 só comunica compatibilidade quando o projeto define e segue a convenção escolhida. No SemVer, mudanças incompatíveis na API pública alteram o primeiro número, novas funções compatíveis alteram o segundo e correções compatíveis alteram o terceiro. Essa numeração não substitui a leitura das notas. A atualização pode exigir uma configuração ou uma etapa de instalação, e a compatibilidade declarada depende da API pública que o projeto se compromete a preservar.

A release 2.1.0 inclui uma exportação de relatórios e o pacote correspondente. Uma empresa instala a atualização em staging, enquanto outra continua usando a versão 2.0.4.

A release está publicada nos dois casos. O registro de deploy de cada empresa informa qual versão está em execução, sem transformar a adoção imediata por todos em condição para a existência da release.

## Notas de atualização precisam orientar o uso Descreva a mudança de comportamento e o que a instalação exige. Uma correção de exportação pode indicar qual arquivo era gerado incorretamente e se relatórios antigos precisam ser refeitos, em vez de apenas listar nomes de arquivos do código. Inclua as limitações conhecidas que afetam a atualização. Uma versão candidata a lançamento também precisa estar identificada como tal para não ser confundida com a versão estável indicada pelo projeto. ## Preserve a associação com o pacote O arquivo disponibilizado precisa corresponder à versão e ao histórico anunciados. Substituir silenciosamente seu conteúdo mantém o mesmo nome para resultados diferentes e dificulta reproduzir uma falha em outra instalação. Confira o identificador do artefato e os arquivos disponíveis antes de divulgar a atualização. Se houver pacotes para plataformas diferentes, o nome e as instruções devem permitir escolher o arquivo compatível com o destino. ## Publicação e adoção são acompanhadas separadamente A release pode existir sem que um serviço hospedado tenha recebido seu [deploy](/glossario/deploy/). O acompanhamento precisa distinguir a disponibilidade do pacote, a instalação em cada ambiente e, quando aplicável, a ativação da função para o público. Para revisar de forma recorrente a preparação das versões e sua continuidade técnica, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a análise do processo. A release continua sendo identificada pelo projeto, e o histórico de cada ambiente informa sua adoção. ### Repositório: arquivos e histórico do projeto - URL: https://promovaweb.com/glossario/repositorio - Descrição: Repositório Git guarda objetos e referências de todo o histórico do projeto. Entenda arquivos de trabalho, remoto e o que o versionamento não preserva. ## O que é um repositório No Git, um repositório armazena objetos e referências que permitem consultar o histórico versionado de um projeto. Commits registram estados, enquanto branches e tags ajudam a localizar pontos desse histórico. A pasta usada para editar costuma reunir uma árvore de trabalho e os metadados do Git. Também existem repositórios bare, sem uma árvore de arquivos preparada para edição, comuns em situações de compartilhamento. ## Arquivos no disco e conteúdo versionado Gravar um arquivo na pasta não significa registrá-lo no histórico. O status permite distinguir alterações rastreadas e arquivos novos, enquanto os commits preservam os estados efetivamente registrados. Arquivos ignorados também podem permanecer apenas no ambiente local. Colocar um caminho no gitignore não remove automaticamente um arquivo já rastreado nem apaga conteúdo que entrou em commits anteriores.

O clone recupera o código, mas a aplicação não encontra os documentos enviados pelos cadastros. Esses arquivos ficavam num armazenamento separado e nunca fizeram parte do histórico Git.

O repositório cumpriu seu papel de preservar o conteúdo versionado. A recuperação do serviço precisa incluir também o armazenamento e o banco que mantêm os registros de uso.

## Local e remoto podem avançar separadamente Um remoto é outro repositório com o qual o seu pode trocar objetos e referências. Ele pode estar num serviço de hospedagem ou em outro local acessível, sem ser obrigatoriamente um servidor público. Seu histórico local pode conter commits ainda não enviados, enquanto o remoto pode receber alterações que você não consultou. Compare as referências depois de atualizar as informações disponíveis, sem presumir sincronização automática. ## Clonar cria outra cópia do repositório A clonagem obtém o conteúdo conforme as opções usadas e prepara referências para acompanhar a origem. Um clone raso pode omitir parte dos commits antigos, e uma clonagem parcial pode buscar determinados objetos apenas quando necessários. A cópia também não inclui automaticamente todos os recursos da plataforma de hospedagem. Discussões, configurações de acesso e artefatos de execução têm formas próprias de armazenamento e recuperação. ## Conferir o que o projeto precisa para funcionar Além de consultar o histórico, identifique dependências, variáveis e serviços necessários para executar a aplicação. Esses requisitos devem estar documentados sem publicar segredos, pois o clone do código não reproduz sozinho todo o ambiente. Os [commits](/glossario/commit/) e as [branches](/glossario/branch/) organizam o trabalho preservado pelo Git. A conferência do repositório começa por separar esse histórico das alterações locais e dos recursos externos que o projeto utiliza. ### Requisição HTTP: a mensagem enviada ao servidor - URL: https://promovaweb.com/glossario/requisicao - Descrição: Requisição HTTP é a mensagem enviada pelo cliente ao servidor. Conheça método, endereço, cabeçalhos e corpo em um exemplo de cadastro de contato. ## O que uma requisição HTTP comunica Requisição HTTP é a mensagem que um cliente envia para solicitar uma operação a um servidor. Abrir uma página, consultar um catálogo e enviar um formulário são situações que podem produzir requisições. A mensagem informa o recurso pretendido e a ação solicitada, além das informações necessárias para executá-la. Ao pesquisar um produto, por exemplo, você digita um termo na interface. A aplicação pode enviar esse termo ao servidor para buscar os itens correspondentes. O texto digitado faz parte da comunicação, mas a requisição também precisa indicar qual serviço deve receber a consulta. Uma página costuma provocar várias requisições. O navegador pode buscar o HTML, as imagens e os arquivos de estilo em chamadas separadas. Por isso, uma falha na imagem não significa necessariamente que a requisição do documento principal também falhou. ## Método, endereço, cabeçalhos e corpo O método HTTP expressa a finalidade da chamada. `GET` solicita uma representação de um recurso, como a lista de produtos. `POST` solicita que o servidor processe o conteúdo enviado, o que pode criar um cadastro ou iniciar outra operação prevista pela aplicação. A URL identifica o destino e pode carregar parâmetros de consulta. Em `/produtos?categoria=livros`, o caminho é `/produtos`, e `categoria=livros` é um parâmetro. A aplicação precisa reconhecer esse nome para aplicar o filtro esperado. Os cabeçalhos descrevem aspectos da mensagem, como o formato declarado em `Content-Type`. No cadastro do exemplo abaixo, esse campo indica JSON, e o corpo contém o nome e o email que serão interpretados pelo servidor. Outras chamadas podem transportar formulários ou arquivos, conforme o contrato da API. Essas partes não são intercambiáveis. Se a documentação exige um campo no corpo, colocá-lo apenas na URL pode não atender à operação. Da mesma forma, declarar JSON no cabeçalho não converte automaticamente um texto qualquer para esse formato. ## Exemplo de envio de um contato O trecho abaixo representa uma requisição HTTP/1.1 para fins didáticos. ```http POST /contatos HTTP/1.1 Host: api.example.com Content-Type: application/json {"nome":"Ana","email":"ana@example.com"} ``` O exemplo usa um domínio reservado para documentação e omite detalhes de transporte. Você normalmente fornece os campos a uma biblioteca HTTP ou ao navegador, que prepara a mensagem completa. A notação HTTP/1.1 permite visualizar as partes, embora versões posteriores do protocolo usem outra representação na conexão.

A integração envia os dois campos ao endpoint de cadastro. O servidor valida o conteúdo e pode responder com 201 depois de criar o contato. Você confere o identificador devolvido e o registro correspondente.

Em outro teste, o email fica vazio. A resposta esperada depende do contrato, mas uma API que exige esse campo deve recusar a criação. A interface precisa interpretar o retorno para orientar a correção.

## Enviar não é confirmar o resultado Uma requisição enviada pode receber uma resposta de erro. Também pode ocorrer uma interrupção antes que o retorno chegue ao cliente. Nesse segundo caso, o servidor pode ter executado a ação solicitada, mesmo que a interface tenha parado de esperar. Antes de repetir uma operação que cria registros, confira como o serviço trata reenvios. Algumas APIs oferecem uma chave de idempotência para reconhecer tentativas da mesma operação. O uso dessa chave segue o contrato específico do serviço. ## Como conferir uma requisição Abra a aba Network, ou Rede, nas ferramentas do navegador e reproduza a ação em desenvolvimento. Confira o método, o endereço, os cabeçalhos relevantes e os campos enviados. Compare os nomes e os formatos com a documentação da API. Depois, leia a [resposta HTTP](/glossario/resposta/) correspondente. Um retorno inesperado pode resultar tanto da montagem da mensagem quanto do processamento no servidor. Alterar o método por tentativa, sem conferir o contrato, pode chamar uma operação diferente da pretendida. ### Requisito: a condição que o sistema deve atender - URL: https://promovaweb.com/glossario/requisito - Descrição: Requisito descreve uma condição específica que o sistema deve atender. Entenda comportamento, qualidade e como transformar necessidades em conferência. ## Definição Requisito é uma condição que o sistema deve atender para responder a uma necessidade ou obrigação. Ele pode descrever uma função, uma qualidade esperada ou uma restrição que limita as soluções possíveis. Ao escrever um requisito, você precisa distinguir a necessidade percebida do comportamento que será conferido. “Organizar contatos” indica uma intenção, mas ainda deixa abertas as operações e as situações que a aplicação deverá atender. ## Da necessidade ao comportamento Uma necessidade pode dar origem a vários requisitos relacionados. Recuperar um contato pelo nome, por exemplo, exige definir como a busca trata nomes parciais e o que acontece quando existem vários resultados ou nenhum registro correspondente. Essas definições ajudam a orientar a implementação sem impor detalhes desnecessários. O requisito pode descrever a busca esperada enquanto a escolha do componente de interface permanece aberta.

A implementação encontra correspondências exatas, mas não encontra Ana Paula quando você informa apenas Paula. A função de busca existe, porém o comportamento necessário ainda não foi atendido.

Você registra que a pesquisa deve aceitar partes do nome e descreve como apresentar os resultados. A conferência seguinte usa nomes completos, parciais e uma consulta sem correspondência.

## Qualidade e restrições também entram Uma expectativa de desempenho precisa informar o cenário de medição. Num exemplo fictício, a busca pode exigir a exibição dos resultados em até dois segundos sobre dez mil contatos, com cinco consultas simultâneas. Ainda é preciso definir o início e o fim da medição: medir apenas o processamento no servidor não inclui o tempo até os nomes aparecerem na tela. Esses números ilustram uma exigência do projeto, não um limite recomendado para qualquer aplicação. Restrições técnicas também podem ser legítimas, como utilizar o mecanismo de autenticação já adotado pela organização. Nesse caso, registre o motivo da obrigação para evitar que uma preferência pessoal seja tratada como condição indispensável do produto. ## Relacionar especificação e testes A [especificação](/glossario/especificacao-spec/) relaciona os requisitos e descreve como cada um orienta a implementação. As [condições de aceite](/glossario/condicao-de-aceite/) descrevem os resultados que você confere na entrega, incluindo os caminhos que devem ser recusados. Se a necessidade mudar, revise também as partes que dependem dela. Alterar o texto sem ajustar testes e implementação deixa o projeto com descrições incompatíveis do comportamento esperado. Quando você ainda precisa organizar necessidades e alcance da primeira versão, o [Diagnóstico de Produto e Arquitetura da Dev Side Studio](https://devsidestudio.com/servicos/diagnostico-de-produto-e-arquitetura/) pode apoiar essa definição antes da construção. ### Resposta HTTP: retorno do servidor - URL: https://promovaweb.com/glossario/resposta - Descrição: Resposta HTTP é o retorno de uma requisição. Entenda status, cabeçalhos e corpo, com exemplos de criação, ausência de conteúdo e processamento pendente. ## O que a resposta HTTP informa Resposta HTTP é a mensagem que um servidor envia em retorno a uma requisição. Ela pode entregar uma página, confirmar a criação de um registro, indicar um redirecionamento ou comunicar uma falha. Ao interpretar o retorno, o cliente considera também o método utilizado e o contrato do serviço acessado. Imagine que você envia um formulário de contato. Receber uma resposta significa que algum servidor devolveu uma mensagem, mas ainda é preciso ler seu significado. O retorno pode confirmar o cadastro ou informar que o email foi recusado. Em uma aplicação com intermediários, a resposta também pode vir de um proxy ou de um serviço de cache. Se a aplicação estiver indisponível, por exemplo, o proxy pode devolver um erro sem que o código de cadastro tenha sido executado. Essa diferença importa ao investigar a origem do problema. ## Como ler status, cabeçalhos e corpo O código de status resume o significado da resposta. `201 Created` informa a criação de um recurso, enquanto `404 Not Found` indica que o servidor não encontrou uma representação atual do recurso ou não deseja informar sua existência. A explicação específica da aplicação pode aparecer no corpo. Os cabeçalhos complementam essa leitura. `Content-Type` informa o formato do conteúdo, e `Location` pode indicar o endereço do recurso criado. Outros cabeçalhos controlam cache ou transportam instruções de sessão, conforme o serviço. O corpo pode conter JSON, HTML, uma imagem ou outro formato. Algumas respostas não têm corpo por definição, como `204 No Content`. Se uma atualização retorna esse status conforme o contrato, a interface deve confirmar o resultado sem tentar ler um objeto JSON inexistente. ## Uma resposta de criação O exemplo representa uma API fictícia e omite detalhes de transporte. O código informa a criação, o cabeçalho `Location` aponta o recurso e o corpo traz os campos que esse contrato escolheu devolver. Outra API pode retornar uma estrutura diferente para a mesma finalidade.

A interface reconhece o status de criação e lê o identificador 42 no corpo. Com essa referência, ela pode exibir o contato criado ou oferecer um link para sua consulta, conforme os caminhos documentados pela API.

Se o contrato prevê esse identificador e ele estiver ausente, existe uma divergência que precisa ser investigada. A ausência de corpo só é uma falha quando o comportamento documentado exige conteúdo naquela resposta.

## Sucesso HTTP e processamento posterior O código `202 Accepted` informa que a requisição foi aceita para processamento. Ele não confirma a conclusão do trabalho. Em uma importação de contatos, a resposta inicial pode chegar enquanto os registros ainda aguardam processamento. Você precisa acompanhar a tarefa pelo mecanismo documentado, como uma consulta de status ou uma notificação posterior. A interface pode mostrar “importação recebida” nesse primeiro momento e reservar a confirmação final para quando o resultado estiver disponível. ## Como tratar falhas sem perder a informação útil Uma resposta de erro pode identificar um campo que precisa de correção. A interface deve apresentar uma orientação adequada à situação, preservando as informações úteis do contrato. Detalhes internos, como consultas do banco e caminhos de arquivos, não devem ser exibidos automaticamente para visitantes. Teste um cadastro válido e um cadastro recusado no ambiente de desenvolvimento. Confira o status, o formato e o conteúdo recebido, além da mensagem apresentada na tela. Se a comunicação terminar sem uma resposta, trate a ausência de confirmação separadamente de uma recusa explícita. A [API](/glossario/api/) define quais retornos você pode esperar e como cada um deve ser interpretado pela integração. ### REST: organização de recursos acessíveis por URL e método - URL: https://promovaweb.com/glossario/rest - Descrição: REST organiza uma API em recursos acessíveis por URL e método HTTP. Entenda recurso, verbo, caminho e como a URL comunica o que a chamada faz. ## O que é REST REST, de Representational State Transfer, é um estilo de organização de [API](/glossario/api/) em que os recursos são acessados por uma combinação de [URL](/glossario/url/) e [método HTTP](/glossario/metodo-http/). A URL identifica o recurso, e o método comunica a ação pretendida. O estilo ajuda a entender a API olhando para a chamada. Em vez de nomes de função abstratos, o caminho identifica o que existe, e o verbo informa o que está sendo feito. A leitura da URL comunica o propósito. ## Recurso e caminho O [recurso](/glossario/recurso/) é o que a API expõe: um usuário, um pedido, um pet. O caminho identifica o recurso e, quando necessário, o elemento específico dentro dele. O método define a operação sobre o caminho. Uma mesma URL pode responder de formas diferentes conforme o verbo. Consultar, criar, substituir ou remover usam métodos distintos sobre o mesmo recurso. A combinação de caminho e método comunica a chamada. ## Caminhos que comunicam O caminho pode se aprofundar para recursos relacionados. Um usuário com seus pedidos pode aparecer em `/users/5/orders`. O identificador do usuário aparece no caminho, e o recurso relacionado completa a leitura. O caminho bem desenhado se lê como uma frase. Identificar o recurso, o elemento e a relação ajuda quem consome a API. A URL comunica a operação e oferece uma primeira orientação sobre a chamada.

Uma URL como `/users/5/deals/2` identifica a negociação 2 do usuário 5. O método aplicado comunica a ação sobre esse recurso.

Olhando para o caminho e o verbo, é possível entender o que a chamada faz. O estilo REST dá essa dinâmica de nomenclatura para que a API seja compreensível.

## Semântica e estado REST se apoia em recurso e estado. O recurso é o que a API expõe, e o estado é a representação atual dele. O HTTP oferece os verbos e os códigos de resposta que expressam a operação. Seguir a semântica dos métodos evita surpresas. Usar GET para consultar, POST para criar e DELETE para remover comunica a intenção. A [idempotência](/glossario/idempotencia/) de alguns métodos orienta o comportamento ao repetir chamadas. Para modelar a sua API seguindo o estilo REST, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização de recursos, caminhos e métodos. ### Restauração: recuperação a partir das cópias - URL: https://promovaweb.com/glossario/restauracao - Descrição: Restauração recupera conteúdo a partir de cópias disponíveis. Veja como escolher o ponto, preparar o destino e conferir registros, anexos e funcionamento. ## O que é restauração Restauração é o processo de recuperar conteúdo a partir das fontes preservadas para essa finalidade. Pode envolver um arquivo, um banco ou várias partes de uma aplicação, dependendo da cobertura do backup e do resultado necessário. O conteúdo recuperado representa um ponto específico, que pode ser anterior à falha. Você precisa reconhecer esse momento para distinguir uma perda posterior à cópia de um erro ocorrido durante a recuperação. ## Escolher a fonte e preparar o destino Identifique qual cópia contém o estado desejado e quais outras partes ela exige. Alguns métodos dependem de uma sequência de arquivos, enquanto outros precisam de chaves, permissões ou uma versão compatível da ferramenta. Prepare o destino de teste separado do ambiente em uso e confira sua identificação antes de executar a recuperação. Recuperar sobre um banco existente pode misturar conteúdos ou substituir informações, conforme o comando e suas opções.

A cópia representa o estado das 14h, e um cadastro foi criado às 14h20. Depois da restauração dessa cópia, a ausência do cadastro é compatível com o ponto recuperado.

Um cadastro confirmado às 13h50, ainda existente às 14h e incluído na cobertura deveria aparecer. A comparação considera o estado representado pela cópia: um cadastro excluído antes das 14h não deve reaparecer apenas porque foi criado anteriormente.

## O formato determina o procedimento No PostgreSQL, um dump SQL em texto é processado por psql, enquanto formatos de arquivo compatíveis usam pg_restore. O nome backup.dump, sozinho, não informa como o arquivo foi produzido nem comprova sua compatibilidade. Confira também permissões e objetos exigidos no destino, como os papéis que recebem a propriedade das tabelas. A execução pode apresentar erros e deixar conteúdo parcial, por isso o resultado precisa incluir a leitura das mensagens da ferramenta. ## Recuperar o banco não recompõe toda a aplicação Anexos, configurações e serviços externos podem ter estados diferentes do banco restaurado. Um registro recuperado pode apontar para um arquivo ausente, ou uma tarefa antiga pode reaparecer como pendente apesar de seu efeito externo já ter acontecido. Antes de liberar o ambiente, confira essas relações e controle tarefas automáticas que poderiam repetir ações. Um teste de restauração também precisa impedir que o ambiente de teste envie mensagens reais por credenciais copiadas da produção. ## Conferir conteúdo e funcionamento Consulte registros conhecidos e exercite funções compatíveis com o objetivo do teste, como abrir um anexo ou localizar uma inscrição. Uma página inicial carregada não demonstra que todas as tabelas, permissões e dependências foram recuperadas. Documente o ponto alcançado e o que permaneceu fora da cobertura. Meça também a duração até o serviço estar disponível e conferido, incluindo a preparação do destino. Quando esse tempo excede o prazo previsto, o teste mostra que o plano de retorno precisa de ajustes, mesmo que todo o conteúdo esperado tenha sido recuperado. ## Preservar o resultado do teste Registre qual [backup](/glossario/backup/) foi usado, o destino, as mensagens da ferramenta e as verificações realizadas. Esses detalhes permitem repetir o exercício quando o banco cresce ou a aplicação muda de versão. Para investigar uma restauração de teste com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar uma tarefa delimitada. O trabalho deve partir de uma cópia identificada e de um destino preparado para a conferência. ### Retry: nova tentativa de uma operação - URL: https://promovaweb.com/glossario/retry - Descrição: Retry repete uma ação após falha ou resultado desconhecido. Veja quando tentar novamente, limitar a repetição e considerar efeitos já realizados. ## O que é retry Retry é uma nova tentativa de executar uma ação depois de uma falha ou de um resultado que o cliente não conseguiu confirmar. Ele pode recuperar uma consulta interrompida por uma indisponibilidade breve, desde que o serviço volte a responder e a chamada continue válida. A repetição também pode acontecer depois de um [timeout](/glossario/timeout/), quando a espera termina sem confirmar o resultado no destino. Nessa situação, você precisa considerar que a ação pode ter sido concluída, mesmo que a aplicação tenha recebido um erro local. ## O motivo da falha orienta a repetição Uma interrupção de rede pode desaparecer na próxima tentativa, enquanto uma chamada sem um campo obrigatório continuará incompleta. O retry deve seguir os erros recuperáveis documentados e o comportamento da ação, sem tratar toda resposta de falha da mesma maneira. Uma credencial expirada pode exigir renovação antes de repetir, e uma recusa por excesso de chamadas pode exigir espera. O tratamento precisa realizar essa correção ou respeitar o intervalo, em vez de reenviar o mesmo conteúdo continuamente.

A consulta recebe uma resposta de indisponibilidade temporária. O workflow registra a falha, espera o intervalo previsto e faz outra tentativa com os mesmos filtros.

Se a resposta seguinte for válida, o processamento continua com os resultados recebidos. Se o limite de recuperação for atingido, a execução registra o período que ficou pendente para uma retomada posterior.

## Quantidade, intervalo e duração total A política precisa definir quantas tentativas serão permitidas e quanto tempo esperar entre elas. O [backoff](/glossario/backoff/) controla as pausas, enquanto um prazo total pode impedir que uma tarefa permaneça tentando além do tempo útil para o processo. Confira se a configuração inclui a chamada inicial no total. Três tentativas e três repetições depois da primeira chamada representam quantidades diferentes de acesso ao serviço e de tempo potencial de espera. Retries em várias camadas também podem se multiplicar. Em um exemplo com três tentativas no workflow e três tentativas internas na biblioteca a cada chamada, o destino pode receber até nove chamadas para a mesma ação. ## A ação anterior pode ter produzido efeito Uma falha de comunicação não equivale à confirmação de que nada aconteceu. O servidor pode ter criado um registro e perdido a conexão antes de devolver seu identificador, deixando o cliente sem o resultado. Nessa situação, repetir uma criação sem proteção pode gerar outro registro. A [idempotência](/glossario/idempotencia/) e a consulta do estado no destino permitem planejar a recuperação conforme as garantias disponíveis, incluindo a reutilização da mesma chave quando a API oferecer esse mecanismo. Também considere os efeitos anteriores de um workflow. Se a falha aconteceu no envio da confirmação, repetir o fluxo inteiro pode refazer um cadastro que já terminou, embora apenas o envio ainda esteja pendente. ## O mesmo erro pode continuar sendo temporário Receber a mesma falha em todas as tentativas não demonstra, sozinho, que ela é permanente. Uma indisponibilidade de alguns minutos pode ultrapassar uma política de recuperação curta e produzir respostas iguais durante todo o intervalo observado. O limite encerra a tentativa automática para aquele processamento, sem diagnosticar por si só a causa. Preserve o erro e o identificador da tarefa para permitir investigação e recuperação depois, conforme o processo previsto. ## Como testar a recuperação Simule uma falha antes da ação e outra depois do efeito, mas antes da confirmação ao cliente. Observe a quantidade de chamadas, os intervalos e o resultado final no destino. Inclua também uma entrada inválida que não deve ser repetida automaticamente. O teste precisa mostrar que a automação recupera falhas previstas sem consumir todas as tentativas em uma chamada que ainda exige correção. ### Rollback de transação: desfazer alterações não confirmadas - URL: https://promovaweb.com/glossario/rollback-de-transacao - Descrição: Rollback cancela alterações de uma transação não confirmada. Entenda seu alcance, o uso de savepoints e os efeitos que não são desfeitos pelo banco. ## Cancelar alterações ainda não confirmadas Rollback de transação é o cancelamento das alterações transacionais que ainda não foram confirmadas. Ele encerra a unidade sem manter suas gravações como resultado definitivo. Operações confirmadas antes dessa transação não são desfeitas por esse comando. Imagine que uma rotina altera um cadastro e depois encontra uma condição que impede a conclusão. Se as mudanças continuam na mesma transação, o cancelamento permite descartá-las. O sistema não precisa publicar a alteração parcial para depois tentar corrigi-la. O escopo é essencial para interpretar o resultado. Um rollback não restaura o banco inteiro a um horário anterior, nem apaga todo efeito produzido pelo programa. Ele atua sobre a unidade transacional correspondente. ## Um exemplo com atualização Se o contato 7 existia, a atualização não deve permanecer confirmada ao final desse exemplo. A transação pode observar suas próprias alterações durante a execução. A leitura por outras sessões também depende do nível de isolamento configurado no banco.

A alteração inicial funciona, mas o vínculo não pode ser criado. A aplicação cancela o conjunto e depois consulta o contato novamente. O nome deve corresponder ao estado que não foi substituído por aquela transação.

Se a alteração já recebeu commit antes da tentativa do vínculo, o rollback posterior não a alcança. Corrigir esse caso exige outra operação e uma revisão do escopo transacional.

## Erro e rollback não são sinônimos universais O efeito de um erro varia conforme o banco, a instrução e a biblioteca utilizada. Alguns mecanismos colocam a transação em estado de falha e exigem cancelamento antes de continuar. Outros podem cancelar apenas uma instrução em determinadas situações. Por isso, o código precisa usar o tratamento recomendado pela ferramenta. Capturar uma exceção e seguir para a confirmação pode preservar um conjunto diferente do pretendido. Testar o caminho de erro faz parte da verificação da operação. ## Cancelamento parcial com savepoint Um savepoint marca um ponto dentro da transação. Bancos que oferecem esse recurso permitem descartar alterações posteriores à marca e manter o trabalho anterior ainda pendente. A confirmação final continua sendo necessária para a parte que será preservada. Considere uma rotina que altera o telefone, cria um savepoint e tenta registrar uma preferência opcional. Se essa última etapa falhar, recuar até a marca pode descartar a preferência sem perder a alteração do telefone, ainda não confirmada. Esse uso só atende ao produto se a preferência puder falhar separadamente. Um vínculo obrigatório exigiria cancelar o conjunto. ## O que não volta com o rollback Emails enviados, arquivos gravados fora do mecanismo transacional e chamadas a outros serviços podem permanecer. No PostgreSQL, valores consumidos de sequências também podem deixar lacunas. O cancelamento das linhas não promete apagar logs ou todos os sinais da execução. Para conferir, provoque uma falha controlada em desenvolvimento e examine tanto os registros quanto os efeitos externos. O verbete de [transação](/glossario/transacao/) explica como escolher o conjunto de operações coberto pela confirmação e pelo cancelamento. ### RPO: perda máxima de conteúdo tolerada - URL: https://promovaweb.com/glossario/rpo - Descrição: RPO define a perda tolerada de alterações em tempo. Entenda a diferença para RTO, o ponto recuperável e por que agendar backups não comprova o objetivo. ## O que é RPO RPO significa Recovery Point Objective, ou objetivo de ponto de recuperação. Ele expressa em tempo a perda de alterações tolerada após uma interrupção, orientando quão recente precisa ser o estado que você consegue recuperar. Um RPO de uma hora estabelece um objetivo para a janela de alterações potencialmente perdidas. Ele não informa quanto tempo a restauração levará nem quantos registros foram criados durante essa hora. ## Objetivo declarado e ponto recuperável O objetivo é definido conforme a consequência de perder alterações para o negócio. O ponto recuperável é aquilo que a estratégia disponível permite reconstruir, e precisa ser conferido para saber se atende ao objetivo. Agendar uma cópia não comprova que ela terminou, chegou ao destino ou poderá ser usada. A execução mais recente pode ter falhado, deixando uma cópia anterior à prevista como única alternativa.

Uma falha acontece às 10h40, e a cópia utilizável mais recente representa as 10h. A janela de quarenta minutos está dentro do objetivo estabelecido.

Se a cópia das 10h falhou e só existe uma cópia utilizável das 9h, a janela aumenta para uma hora e quarenta minutos. O agendamento continuou igual, mas o ponto disponível deixou de atender ao objetivo.

## Intervalo entre cópias não determina toda perda Com cópias a cada oito horas, uma falha poucos minutos depois de uma cópia pode ter uma janela pequena de perda. Essa ocorrência favorável não comprova atendimento a um RPO de uma hora durante todo o intervalo até a próxima cópia. A análise precisa considerar também atrasos e indisponibilidade das cópias. O horário de término do arquivo pode diferir do momento representado pelo conteúdo, então use a referência documentada pelo método de backup. ## Alterações preservadas podem complementar uma cópia Algumas estratégias recuperam uma cópia-base e aplicam registros posteriores de alterações. No PostgreSQL, o arquivamento contínuo de WAL permite esse tipo de recuperação, desde que o conjunto exigido esteja preservado e utilizável. Assim, fazer cópias completas com mais frequência não é a única forma de buscar um ponto mais recente. Atrasos e lacunas no arquivamento também precisam ser acompanhados, pois podem impedir alcançar o momento pretendido. ## Perda de alterações e tempo de retorno são objetivos distintos Uma recuperação pode preservar quase todas as alterações e ainda demorar horas para devolver o serviço. Também pode devolver rapidamente uma aplicação cujo conteúdo está muito desatualizado. O RTO, objetivo de tempo de recuperação, trata do prazo de retorno do serviço. Comparar os dois objetivos mostra se o plano precisa preservar um ponto mais recente ou reduzir o tempo da restauração. ## Como conferir o objetivo na prática Em um teste de [restauração](/glossario/restauracao/), identifique o ponto efetivamente recuperado e compare-o com o momento de interrupção usado no exercício. Registros de teste identificáveis ajudam a conferir quais alterações estão presentes, além dos horários informados pela rotina. Para acompanhar essa conferência conforme o sistema cresce, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar a revisão da infraestrutura. A análise deve usar resultados de recuperação e falhas das rotinas, para que o objetivo declarado corresponda ao que o projeto consegue recuperar. ### Runtime: o ambiente que executa o programa - URL: https://promovaweb.com/glossario/runtime - Descrição: Runtime é o ambiente que executa um programa. Entenda a diferença entre linguagem, APIs, editor e framework e por que versões afetam a compatibilidade. ## O ambiente durante a execução Runtime é o ambiente que permite executar um programa e disponibiliza os recursos necessários para isso. Ele pode incluir mecanismos da linguagem, gerenciamento de memória e APIs do ambiente. A composição depende da tecnologia utilizada. O navegador e o Node.js executam JavaScript com conjuntos próprios de recursos. No navegador, o código pode interagir com o documento apresentado na página. No Node.js, APIs do ambiente permitem tarefas como ler arquivos e criar servidores, conforme as permissões do processo. A palavra também aparece em expressões como “erro em runtime”, que significa erro durante a execução. Nesse uso, ela descreve o momento da falha. O código pode ter passado pela análise ou compilação e ainda encontrar uma condição inválida quando for executado. ## Linguagem e recursos do ambiente As linhas são exemplos separados, destinados aos ambientes indicados nos comentários. No navegador, `window.location.pathname` consulta o caminho da página aberta. No Node.js, `process.version` informa a versão que executa aquela chamada, permitindo compará-la com a exigida pelo projeto. Uma biblioteca escrita em JavaScript pode depender de uma dessas APIs. Por isso, compartilhar a linguagem não garante compatibilidade entre ambientes. A documentação precisa indicar onde o pacote pode executar e quais versões suporta. ## Runtime, editor e framework O editor permite escrever e navegar pelo código. O runtime executa o programa, mesmo quando você inicia essa execução por um botão do editor. O terminal também pode iniciar o mesmo programa sem alterar sua linguagem. Framework fornece organização e funcionalidades sobre um ambiente compatível. Já o runtime oferece a base de execução utilizada por esse código. Atualizar um não equivale automaticamente a atualizar o outro.

O script funciona no servidor porque encontra a API necessária. Ao importar a mesma biblioteca diretamente na página, a execução pode falhar ou o build pode recusar a dependência. O navegador não oferece aquele acesso da mesma forma.

Você precisa escolher uma função compatível com o navegador ou manter o processamento no servidor. Renomear o arquivo não acrescenta ao ambiente uma API que ele não possui.

## Versões também fazem parte do ambiente Uma API pode existir em uma versão e faltar em outra. Recursos da linguagem, módulos nativos e bibliotecas podem exigir uma versão mínima. O ambiente local e o destino de publicação precisam respeitar essas exigências. Containers e gerenciadores de versão podem ajudar a reproduzir a combinação usada pelo projeto. Ainda assim, você precisa declarar as versões e conferir o ambiente efetivo. A presença de um arquivo de configuração não comprova que ele foi aplicado. ## Como investigar uma incompatibilidade Confira a versão que realmente executa o programa e a documentação do recurso ausente. Uma mensagem como `window is not defined` pode indicar código de navegador executado fora dele. Já um módulo não encontrado pode ter outra causa, como instalação incompleta. Teste no ambiente de destino e preserve a separação entre funções da linguagem e APIs externas. O verbete de [ambiente local](/glossario/ambiente-local/) explica como reunir essas dependências durante o desenvolvimento. ### Schema: a estrutura e o namespace do banco - URL: https://promovaweb.com/glossario/schema - Descrição: Schema descreve a estrutura do banco e pode nomear um agrupamento de objetos do sistema. Entenda tabelas, restrições e mudanças sobre registros existentes. ## Estrutura do banco e organização de objetos Schema, ou esquema, pode designar a estrutura do banco: tabelas, colunas, tipos e restrições que definem o armazenamento. Em bancos como PostgreSQL, a palavra também identifica um namespace, um agrupamento nomeado de objetos dentro de um banco. O sentido precisa ser reconhecido na documentação utilizada. A estrutura de uma tabela determina quais campos existem e quais valores são aceitos. Os registros são o conteúdo armazenado nessa estrutura. Criar uma coluna e preencher uma linha são operações diferentes, embora ambas alterem o banco. Ao acrescentar um campo ao formulário para gravá-lo no banco, você precisa preparar o armazenamento correspondente e o código que fará a gravação. Publicar apenas o formulário não cria automaticamente a coluna que o backend pretende usar. ## Tipos e restrições O exemplo declara uma identidade, um nome não nulo e um código externo com restrição de unicidade. No PostgreSQL, `NOT NULL` impede nulo, mas não impede sozinho uma string vazia. Uma restrição adicional como `CHECK (nome <> '')` recusaria a string vazia, embora ainda aceitasse um texto formado apenas por espaços. Da mesma forma, tipos e restrições devem refletir o significado do campo. Um texto que contém uma data não recebe automaticamente todas as garantias de uma coluna de data. A escolha influencia consultas, validações e alterações futuras. ## Schema como namespace no PostgreSQL Um banco PostgreSQL pode conter vários schemas nomeados. Uma tabela pode ser identificada por um nome qualificado, como `atendimento.contatos`. Isso permite organizar objetos e usar nomes iguais em schemas distintos. O caminho de busca, chamado `search_path`, influencia a resolução de nomes não qualificados. Uma consulta a `contatos` pode encontrar um objeto diferente conforme essa configuração. Permissões também precisam ser configuradas, pois a separação por nome não garante isolamento de acesso por si só.

A aplicação espera atendimento.contatos, enquanto uma sessão consulta apenas contatos com outro caminho de busca. A investigação precisa conferir o banco conectado, o schema e a resolução do nome.

Criar outra tabela para eliminar a mensagem de erro pode esconder a configuração incorreta. Primeiro identifique qual objeto a aplicação realmente deveria acessar.

## Alterações precisam considerar os registros existentes Acrescentar `NOT NULL` a uma coluna que já contém valores nulos pode falhar. Antes dessa alteração, você precisa definir como preencher ou corrigir as linhas existentes. Remover uma coluna também afeta o conteúdo armazenado, pois elimina os valores associados a ela. Migrations permitem registrar e aplicar a evolução de forma controlada. Alterações manuais também mudam o schema, mas podem deixar o ambiente diferente do histórico esperado. A comparação entre definição real e migrations identifica essa divergência. ## Como conferir a estrutura Compare a definição das tabelas nos ambientes que deveriam ter a mesma versão. No exemplo de contatos, tente gravar um nome nulo e repetir um código externo para conferir as restrições declaradas. Verifique também o nome qualificado usado nas consultas, pois iniciar a aplicação não comprova que ela acessa a tabela esperada. O verbete de [migration](/glossario/migration/) explica como registrar a evolução dessa estrutura junto do projeto. ### Secret: valores sensíveis com acesso restrito - URL: https://promovaweb.com/glossario/secret - Descrição: Secret é um valor sensível usado por sistemas. Entenda armazenamento, entrega, permissões, rotação e o que fazer quando uma credencial é exposta. ## Um valor cujo acesso precisa ser restrito Secret é uma informação sensível utilizada por um sistema, como senha, token ou chave privada. O acesso a esse valor pode permitir autenticação, assinatura ou uso de recursos protegidos. Sua proteção depende de armazenamento, entrega e permissões adequados. Uma integração pode conhecer publicamente o endereço de uma API e ainda exigir uma credencial privada para utilizá-la. O endereço informa onde chamar o serviço. A credencial pode permitir executar operações, dentro das permissões associadas a ela. Nem toda chave tem a mesma finalidade. Alguns serviços oferecem identificadores publicáveis para uso no navegador, enquanto mantêm credenciais privadas no servidor. A classificação deve seguir a documentação, sem presumir que qualquer nome contendo “key” é secreto ou público. ## Separar valor, armazenamento e uso Um gerenciador de secrets pode limitar a recuperação do valor aos usuários e serviços autorizados e registrar esses acessos. Uma variável de ambiente pode fornecer o valor ao processo, mas você ainda precisa conferir as permissões de leitura do ambiente e dos registros da aplicação. Arquivos locais com credenciais devem ficar fora do código compartilhado e ter acesso limitado. Um arquivo de exemplo pode documentar os nomes necessários com valores fictícios. Ignorar o arquivo no Git evita novos registros acidentais, mas não remove um valor que já entrou no histórico. ## Um exemplo de integração

O backend recebe o token pelo mecanismo de configuração autorizado e o usa na chamada ao serviço. A página do navegador envia a solicitação de cadastro ao backend, sem receber essa credencial privada nos seus arquivos.

Nos logs, a aplicação registra o resultado e um identificador da chamada, sem imprimir o token. Se houver falha de autenticação, a investigação confere validade e permissões por meios que não exponham o valor.

Colocar uma credencial em uma variável durante o build não garante que ela fique no servidor. Algumas ferramentas inserem valores nos arquivos distribuídos ao navegador, onde visitantes podem consultar o conteúdo. Confira os arquivos produzidos para impedir que uma credencial privada seja publicada junto da interface. ## Permissões, duração e rotação Uma credencial deve permitir apenas as operações necessárias ao seu uso. Separar ambientes e integrações facilita revogar um acesso sem afetar todos os demais. Credenciais com duração limitada podem reduzir o tempo de utilização de um valor exposto. Rotação é a substituição planejada do valor e sua atualização nos consumidores. O processo precisa considerar a ativação da nova credencial e a revogação da antiga. Trocar apenas o arquivo local deixa o acesso anterior válido se o serviço ainda o aceitar. ## Quando um secret aparece onde não deveria Se uma credencial foi publicada, apagar a linha não basta. Revogue ou substitua o valor no serviço e confira os acessos associados, conforme as ferramentas disponíveis. Depois, corrija o caminho que causou a exposição. Procure também nos logs e artefatos, sem reproduzir a credencial no relatório. O verbete de [configuração](/glossario/configuracao/) explica como fornecer os parâmetros do sistema preservando a distinção entre valores públicos e sensíveis. ### Seed: popular um ambiente com registros iniciais - URL: https://promovaweb.com/glossario/seed - Descrição: Seed prepara registros iniciais no banco. Entenda registros de referência, exemplos fictícios, repetição da rotina e diferenças em relação às migrations. ## Preparar registros de partida Seed é uma rotina ou um conjunto de instruções para popular o banco com registros iniciais. Ele pode preparar valores necessários ao sistema ou conteúdo fictício para desenvolvimento e demonstração. A finalidade deve estar explícita para evitar misturar esses usos. Um catálogo de situações permitidas pode ser necessário à aplicação. Já contatos fictícios e matrículas de exemplo podem servir apenas para testar telas. Executar as duas rotinas indiscriminadamente em produção criaria conteúdo que não pertence ao uso real. A estrutura precisa existir antes das inserções correspondentes. Migrations preparam ou evoluem tabelas, enquanto seeds trabalham com registros dentro delas. Uma rotina de seed não substitui o histórico de alterações estruturais. ## Um exemplo que insere registros O exemplo pressupõe uma tabela compatível e identificadores ainda disponíveis para inserir as três linhas. Executá-lo novamente no mesmo banco pode violar a chave primária, pois os identificadores 1, 2 e 3 já estarão ocupados. A rotina precisa tratar essa repetição se ela fizer parte do uso previsto. Essa distinção corrige uma expectativa comum: seed não significa “apagar e recriar tudo” nem “ignorar qualquer duplicidade”. O comportamento na repetição precisa ser implementado conforme a finalidade da rotina. ## Repetibilidade e idempotência Uma rotina pode preparar o mesmo cenário quando executada sobre um banco limpo. Isso é repetibilidade do procedimento, mas não garante que duas execuções consecutivas no mesmo banco tenham o mesmo resultado. A segunda pode acrescentar linhas ou encontrar conflitos. Para registros de referência, a rotina pode localizar valores existentes por uma chave estável e criar apenas os ausentes. Em outros casos, pode atualizar campos definidos. O mecanismo deve preservar alterações legítimas que o produto permita fazer depois da instalação.

O seed prepara as situações exigidas pelo sistema usando códigos estáveis. Em uma execução posterior, ele verifica o que já existe antes de inserir. O teste confere se nenhum código foi duplicado.

Se você alterou na tela uma descrição que o produto permite editar, a rotina precisa definir se irá preservá-la ou substituí-la. Restaurar todo texto ao valor inicial não é uma propriedade obrigatória de um seed.

## Exemplos precisam representar os casos testados Três cadastros simples podem permitir abrir uma listagem, mas não exercitam paginação, campos opcionais ou relacionamentos. Prepare cenários que correspondam ao comportamento que você pretende conferir. Valores aleatórios podem ampliar a variedade, mas dificultam reproduzir uma falha quando não há controle da geração. Use registros fictícios e evite incluir credenciais reais no código da rotina. Contas de demonstração precisam ficar restritas ao ambiente previsto. O comando de execução deve permitir identificar claramente qual banco receberá as gravações. ## Como verificar o resultado Execute o seed em um ambiente apropriado e confira quantidade, valores e vínculos criados. Depois, teste sua repetição conforme o comportamento documentado. Se houver atualização de registros existentes, confirme exatamente quais campos podem mudar. O verbete de [migration](/glossario/migration/) explica a evolução da estrutura que essas rotinas utilizam. ### Segurança: proteger acesso, dados e operação da aplicação - URL: https://promovaweb.com/glossario/seguranca - Descrição: Segurança protege acesso, dados e operação de uma aplicação. Entenda autenticação, autorização, proteção de dados e a prática contínua de reduzir riscos. ## O que é segurança Segurança é a prática de proteger o acesso, os dados e a operação de uma aplicação. O objetivo é permitir que os usuários legítimos usem o sistema e impedir que ações indesejadas comprometam o produto. A segurança não é um recurso único. É uma camada que atravessa autenticação, autorização, validação, comunicação e configuração. Cada parte protege um pedaço do sistema, e a soma delas reduz o risco. ## Autenticar e autorizar A [autenticação](/glossario/autenticacao/) confirma quem é o usuário. A [autorização](/glossario/autorizacao/) define o que ele pode fazer. Separar as duas evita que uma pessoa acesse o que não deveria mesmo depois de confirmar a identidade. Um usuário autenticado pode ter permissões diferentes. Autorizar exige conferir o acesso em cada ação sensível. Confiar apenas na autenticação sem validar a permissão abre caminho para acesso indevido.

Uma aplicação usa uma URL aberta para acessar um registro. O usuário pode mudar o número no endereço e tentar ver um registro que não pertence a ele.

Sem autorização, a mudança do número pode expor o dado. Validar o acesso em cada ação protege contra quem tenta acessar o que não deveria.

## Proteger dados e entradas Os dados precisam de proteção no armazenamento e na comunicação. Segredos como senhas e chaves não devem aparecer em código ou logs. A [validação de entrada](/glossario/validacao-de-entrada/) impede que conteúdo malformado comprometa o sistema. A [privacidade](/glossario/privacidade/) caminha junto. Proteger o acesso não basta se os dados são tratados além da necessidade. Segurança e privacidade reduzem juntas a exposição do usuário. ## Segurança é contínua A segurança não se conclui uma vez. Novas vulnerabilidades aparecem, dependências mudam e a aplicação evolui. Revisar configurações, atualizar dependências e testar o comportamento faz parte da manutenção. A prevenção reduz o risco, mas a detecção também importa. Observar o comportamento e registrar atividades ajuda a identificar tentativas de exploração. Um sistema seguro é revisado e acompanhado, não apenas configurado no início. Para revisar a segurança da sua aplicação e reduzir riscos, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na proteção do acesso, dos dados e da operação. ### Serialização: da estrutura em memória ao texto transportável - URL: https://promovaweb.com/glossario/serializacao - Descrição: Serialização converte valores para armazenamento ou transmissão entre sistemas. Veja o exemplo em JSON, a desserialização e os cuidados com tipos e datas. ## Transformar uma estrutura para armazenamento ou envio Serialização é a conversão de valores de um programa para uma representação que possa ser armazenada ou transmitida. Essa representação pode ser textual, como JSON, ou binária. Desserialização é a leitura dessa representação para obter valores que o programa receptor consiga utilizar. Um objeto em memória não atravessa a rede como a mesma instância que existe no programa de origem. Ele precisa ser representado segundo um formato conhecido pelo receptor. O outro programa interpreta essa representação e cria suas próprias estruturas. Imagine um cadastro preparado pela interface. A aplicação reúne os campos em um objeto e gera um texto JSON para o corpo da requisição. O servidor lê esse texto, verifica seus campos e segue com o processamento. ## Uma conversão em JSON Nesse exemplo, `texto` é uma string que representa os campos do contato. `recebido` é outro objeto, criado pela leitura do texto. Para esses valores simples, os campos são preservados, mas a identidade do objeto original não é transportada. Uma biblioteca HTTP pode executar parte dessa conversão automaticamente. Antes de chamar `JSON.stringify`, confira se a ferramenta espera um objeto ou um texto pronto. Serializar uma string que já contém JSON pode criar uma string JSON adicional, com aspas e caracteres de escape inesperados. ## Nem todo valor volta da mesma forma JSON possui um conjunto limitado de tipos. Ao usar `JSON.stringify`, uma propriedade de objeto com valor `undefined` é omitida. Funções também não são preservadas como funções executáveis, e referências circulares provocam erro na conversão padrão. Datas exigem atenção semelhante. Uma instância de `Date` normalmente é representada como uma string durante a serialização JSON. Ao usar `JSON.parse`, você recebe a string, sem reconstruir automaticamente a instância de `Date`.

O servidor envia uma string de data e hora no formato documentado. A interface lê o JSON e encontra esse texto no campo de criação. Para formatar o horário na tela, precisa interpretá-lo conforme a convenção adotada.

Se a integração ignorar o fuso ou presumir outra unidade para um horário numérico, o valor exibido pode ficar incorreto mesmo com o JSON válido. A serialização define a representação, e o contrato explica o significado.

Por isso, serializar e desserializar não garante a preservação de todo tipo ou comportamento disponível na linguagem original. Você precisa escolher uma representação para os valores que o formato não oferece diretamente e testar sua leitura no destino. ## Serialização, mapeamento e proteção Renomear `nome` para `name` é uma transformação de campos. Essa transformação pode ocorrer antes da serialização, mas tem uma finalidade distinta. O formato de transporte pode continuar sendo JSON nas duas situações. Serializar também não oculta o conteúdo. Um texto JSON pode ser lido por qualquer pessoa que tenha acesso a ele. Credenciais e informações pessoais exigem controles próprios de acesso e proteção, independentemente da representação escolhida. ## Como conferir a conversão Use um exemplo fictício com os tipos que sua integração realmente transporta. Compare o valor original, a representação enviada e a estrutura lida no destino. Inclua campos opcionais, valores nulos e datas quando fizerem parte do contrato. Confira ainda se o receptor recebeu texto ou um objeto já interpretado pela biblioteca. Tentar fazer uma segunda leitura no tipo errado pode causar um erro que parece ser do conteúdo. O verbete de [JSON](/glossario/json/) detalha os tipos disponíveis nesse formato. ### Servidor: o papel de oferecer recursos e serviços - URL: https://promovaweb.com/glossario/servidor - Descrição: Servidor é o software que atende outros programas e também pode nomear a máquina que o executa. Veja como esse papel aparece em uma aplicação web. ## O papel de um servidor Servidor é o software que oferece um serviço a outros programas. Um servidor web, por exemplo, recebe requisições HTTP e devolve páginas. Ele também pode disponibilizar arquivos estáticos ou encaminhar chamadas a uma API. A palavra também pode designar a máquina que executa esse software, por isso vale identificar o sentido usado na conversa. Quando você inicia uma aplicação no computador e abre o endereço local no navegador, o processo que atende à requisição exerce o papel de servidor. Essa comunicação pode acontecer inteiramente no ambiente de desenvolvimento, sem publicação na internet. Em uma hospedagem, a mesma máquina pode executar vários processos, como um servidor web e um banco. Também é possível distribuir uma aplicação entre diversas máquinas. Assim, “o servidor do site” pode representar uma estrutura maior do que um único equipamento. ## O que acontece quando chega uma requisição Um processo servidor recebe conexões em um endereço e uma porta configurados. No desenvolvimento local, você pode encontrar um endereço como `http://localhost:3000`. No navegador executado diretamente na sua máquina, `localhost` aponta para ela, e `3000` identifica a porta usada nesse exemplo. Chamadas feitas dentro de containers precisam considerar o ambiente de rede do processo que acessa o serviço. O tratamento da requisição depende do recurso solicitado e da implementação do serviço. Para uma imagem, o servidor pode ler um arquivo já armazenado. Para o catálogo, a aplicação pode consultar os produtos publicados no banco e montar a resposta naquele momento, envolvendo outras dependências no atendimento. Em uma instalação com proxy reverso, a primeira camada que recebe a conexão pode encaminhar a requisição para outro processo. O navegador vê um endereço público, enquanto a aplicação e o banco usam conexões internas. Essa organização explica por que a origem de uma falha nem sempre é o código da página. ## Um catálogo atendido pelo servidor

Você abre uma categoria do catálogo. O navegador solicita os produtos, e a aplicação consulta os registros correspondentes. A resposta informa quais itens aparecem e o preço atual de cada um.

Se o banco estiver indisponível, a aplicação pode devolver uma resposta de erro. Se a própria aplicação não estiver acessível, um proxy pode responder no lugar dela. Para localizar a causa, você precisa identificar qual processo produziu o retorno.

Nem toda resposta exige consultar o banco naquele instante. O servidor pode entregar um arquivo pronto ou aproveitar uma cópia em cache. O comportamento esperado depende de como o conteúdo é produzido e atualizado. ## Servidor, backend e equipamento Backend é a parte da aplicação responsável pela lógica executada no servidor. Ela pode verificar permissões e registrar um cadastro, enquanto o servidor web recebe a comunicação HTTP. Em algumas tecnologias, o mesmo processo reúne essas funções. Já memória, processador e armazenamento são recursos do ambiente que executa o software. Aumentar a memória pode resolver uma falta de capacidade, mas não corrige automaticamente um campo tratado de forma incorreta. Para escolher a correção, relacione o erro registrado ao consumo desses recursos e ao comportamento do código. Um servidor também pode atuar como [cliente](/glossario/cliente/) ao acessar outro serviço. No catálogo, a aplicação pode consultar uma transportadora para calcular o frete. Ela atende ao navegador em uma comunicação e solicita o cálculo em outra. ## Como investigar uma falha Comece pelo horário, pelo endereço acessado e pelo código recebido. Compare essas informações com os logs do servidor web e da aplicação, quando estiverem disponíveis. Um identificador de requisição pode permitir acompanhar a mesma chamada entre os processos. Um processo ativo ainda pode falhar ao consultar o banco ou ficar sem memória durante uma chamada. Relacione a mensagem exibida no navegador aos logs desse processo, ao acesso às dependências e ao consumo dos recursos no mesmo intervalo. ### Sessão: um estado contínuo entre interações - URL: https://promovaweb.com/glossario/sessao - Descrição: Sessão relaciona interações com uma aplicação ao longo do uso. Entenda criação, continuidade, expiração e logout, além da diferença entre sessão e cookie. ## Relacionar interações ao longo do uso Sessão é um estado que permite relacionar várias interações com uma aplicação. Em uma área autenticada, ela pode associar requisições ao perfil que fez login. Também pode existir antes da autenticação, por exemplo para manter um carrinho de compras. HTTP não relaciona automaticamente uma requisição à anterior como parte de uma conta autenticada. A aplicação acrescenta um mecanismo para reconhecer essa continuidade. Um modelo comum usa um identificador em cookie e mantém o estado correspondente no servidor. Ao abrir o painel e depois consultar seu perfil, o navegador pode enviar o mesmo identificador nas duas chamadas. O servidor verifica a sessão e aplica as permissões da conta. Estar autenticado não significa ter acesso a todo registro da aplicação. ## O ciclo de vida da sessão A aplicação cria ou atualiza a sessão conforme a interação. Depois de uma autenticação, deve renovar o identificador quando utiliza esse modelo, evitando manter um valor que já pudesse ser conhecido antes do login. A biblioteca ou o framework costuma oferecer mecanismos para essa renovação. A sessão pode terminar por logout, expiração ou revogação. Um limite de inatividade considera o período sem uso, enquanto um limite absoluto restringe a duração total. O servidor precisa conferir esses limites a cada acesso protegido, inclusive quando uma página antiga ainda apresenta a sessão como válida.

Você faz login, abre duas páginas e altera uma preferência. Cada chamada apresenta o identificador, e o servidor verifica se a sessão continua válida. As permissões da ação são conferidas junto com o perfil reconhecido.

Ao sair, a aplicação invalida o estado autenticado. Uma chamada posterior com o identificador antigo deve deixar de obter o acesso que dependia daquela sessão. Esse comportamento precisa ser testado, além da mudança visual para a tela de login.

## Onde ficam os valores No modelo de sessão armazenada no servidor, o navegador carrega um identificador opaco. O estado pode ficar em memória, em um banco ou em um serviço de armazenamento compartilhado. A escolha afeta disponibilidade e continuidade entre processos. Também existem mecanismos que transportam informações assinadas no cliente, com condições próprias de tamanho, expiração e revogação. Verificar a assinatura permite identificar alterações no conteúdo protegido por ela, mas não torna esse conteúdo necessariamente secreto. Ao escolher o que transportar, considere quais informações poderão ser lidas no cliente e como o acesso será encerrado. ## Sessão e cookie têm papéis diferentes No modelo descrito no exemplo, o cookie transporta o identificador que permite consultar a sessão mantida no servidor. O mecanismo de armazenamento e envio não define sozinho a finalidade do valor: outro cookie pode guardar apenas uma preferência de idioma, sem representar acesso autenticado. A validade do cookie e a validade da sessão precisam ser examinadas separadamente. O navegador pode continuar enviando um identificador cuja sessão já expirou no servidor. Nesse caso, a aplicação deve recusar o acesso protegido e orientar a autenticação novamente. ## Como conferir continuidade e encerramento Em desenvolvimento, teste navegação autenticada, expiração e logout. Confira se o identificador é renovado após login e se perde o acesso esperado depois do encerramento. Deixe um formulário aberto até a sessão expirar e tente enviá-lo: o servidor deve conferir a validade nesse envio, mesmo que a tela ainda indique que o login está ativo. A interface precisa explicar a necessidade de autenticação sem apresentar a alteração recusada como concluída. Evite gravar identificadores completos em logs compartilhados. Eles podem permitir que terceiros reutilizem a sessão enquanto ela estiver válida. O verbete de [cookie](/glossario/cookie/) explica os atributos que controlam o transporte desse valor no navegador. ### Shell: o programa que interpreta comandos - URL: https://promovaweb.com/glossario/shell - Descrição: Shell interpreta comandos e inicia programas. Entenda variáveis, aspas, expansão e ambiente dos processos, além da diferença entre shell e terminal. ## O interpretador da linha de comando Shell é um programa que interpreta comandos e inicia os processos correspondentes. Em shells textuais como Bash e Zsh, você pode executar programas, usar variáveis e combinar instruções. Parte dos comandos é implementada pelo próprio shell, e parte corresponde a executáveis externos. Ao digitar uma linha, você não entrega necessariamente o texto original ao programa chamado. O shell pode expandir variáveis, interpretar aspas e resolver padrões de arquivos antes de iniciar a ferramenta. Entender essa etapa explica muitos comportamentos inesperados no terminal. O shell também pode ler as instruções de um script e executá-las em sequência. A sintaxe do arquivo precisa ser compatível com o interpretador escolhido, por isso um exemplo escrito para Bash pode exigir adaptação para PowerShell ou Fish. ## Variáveis e aspas A primeira linha define uma variável do shell. Na segunda, as aspas duplas permitem expandir seu valor e mantê-lo como um argumento. O formato de `printf` orienta a impressão sem executar uma chamada de rede. No exemplo, trocar as aspas duplas de `"$servico_local"` por aspas simples faria o shell preservar o nome da variável como texto, em vez de consultar seu valor. As aspas duplas permitem essa expansão e mantêm o resultado como um argumento. Retirar as aspas exige considerar as expansões aplicadas pelo shell, especialmente quando o valor contém espaços ou padrões de arquivos. ## Variável local e ambiente do processo Uma variável do shell não é automaticamente disponibilizada aos programas iniciados por ele. O uso de `export` permite incluí-la no ambiente dos processos seguintes. O programa também precisa estar preparado para ler aquele nome. Alterar uma variável em uma janela não atualiza todas as outras sessões nem um processo que já estava executando. Cada processo recebe seu ambiente ao ser iniciado, salvo mecanismos específicos de comunicação. Esse detalhe explica uma configuração que parece ter sido alterada, mas não chegou à aplicação.

Se o valor for dividido em várias palavras pelo shell, o programa pode receber argumentos separados. Manter a expansão entre aspas preserva o caminho como um único argumento nas situações usuais de Bash e Zsh.

Para investigar, confira o valor e a sintaxe usando exemplos sem credenciais. Imprimir uma variável sensível apenas para verificar a expansão pode expor seu conteúdo no histórico ou nos registros da sessão.

## Shell e terminal têm funções distintas O terminal apresenta a interação textual. Dentro dele, pode executar um shell local, uma conexão remota ou outro programa. Trocar o aplicativo de terminal não altera necessariamente o interpretador usado. O prompt costuma indicar que o shell está pronto para receber outra linha. Ele pode mostrar diretório e outros detalhes, mas seu formato é configurável. Não use apenas a aparência do prompt para identificar a máquina ou o ambiente. ## Como conferir um comando Consulte a documentação do shell para expansões e a documentação da ferramenta para seus argumentos. Verifique diretório, aspas e variáveis relevantes antes de executar uma operação que modifica arquivos. Uma linha sintaticamente válida ainda pode apontar para o alvo errado. O verbete de [variável de ambiente](/glossario/variavel-de-ambiente/) detalha como valores são fornecidos aos programas iniciados pelo shell. ### Sign-in: o acesso do usuário à aplicação - URL: https://promovaweb.com/glossario/sign-in - Descrição: Sign-in é o processo de acesso do usuário à aplicação. Entenda autenticação, sessão, fornecedores de identidade e a diferença para a autorização. ## O que é sign-in Sign-in, também chamado de login, é o processo pelo qual o usuário acessa a aplicação com a identidade confirmada. Em vez de entrar sem identificação, o usuário prova quem é e recebe acesso ao que a aplicação oferece. O sign-in é o primeiro passo do acesso. Depois de confirmar a identidade, a aplicação sabe com quem está lidando. Essa identificação permite personalizar e proteger o que cada usuário pode fazer. ## Autenticação e sessão O sign-in usa a [autenticação](/glossario/autenticacao/) para confirmar a identidade. O usuário fornece uma credencial, como senha ou acesso externo, e a aplicação valida. Confirmada a identidade, o acesso é concedido. O acesso costuma ser mantido por uma [sessão](/glossario/sessao/). A sessão guarda o estado do usuário autenticado e tem uma validade. Após o prazo ou o encerramento, o acesso precisa ser renovado.

Uma aplicação guarda dados de cada usuário. Para ver apenas o que é seu, o usuário precisa entrar com a sua conta.

No sign-in, a identidade é confirmada e a sessão inicia. A partir daí, a aplicação mostra o acesso permitido para aquele usuário, protegendo o que não é dele.

## Sign-in com outro provedor A aplicação pode confiar em um fornecedor de identidade. Em vez de criar uma conta própria, o usuário acessa com uma conta que já possui. O provedor confirma a identidade e entrega a informação à aplicação. Esse formato facilita o acesso, mas depende do contrato entre a aplicação e o provedor. O escopo do que é compartilhado deve ser claro. O usuário autoriza o uso da identidade para entrar na aplicação. ## Sign-in e autorização O sign-in confirma quem é o usuário. A [autorização](/glossario/autorizacao/) define o que ele pode fazer. Um usuário autenticado não ganha automaticamente todos os acessos. Separar os dois evita que a identidade confirme acesso indevido. O sign-in entrega a identidade, e a autorização entrega a permissão. A aplicação valida o acesso em cada ação sensível. Para implementar o sign-in e revisar o acesso da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na autenticação e na proteção do acesso. ### Simulador: executar um ambiente parecido com o destino final - URL: https://promovaweb.com/glossario/simulador - Descrição: Simulador reproduz o comportamento de um dispositivo ou ambiente. Entenda a diferença para o ambiente real, os limites da simulação e o uso em testes. ## O que é um simulador Simulador é uma ferramenta que reproduz o comportamento de um dispositivo ou ambiente para desenvolver e testar sem o recurso real. Em vez de usar o aparelho físico, a aplicação roda em um ambiente que imita o comportamento esperado. O simulador acelera o trabalho. Você pode testar vários formatos de tela e revisar o comportamento no simulador antes de testar no dispositivo real. A aproximação, porém, tem limites. ## Próximo do real, mas não idêntico O simulador reproduz o comportamento esperado, mas pode divergir do ambiente real. Desempenho, sensores e detalhes do sistema podem se comportar diferente. Um teste que passa no simulador pode falhar no dispositivo físico. Por isso, o simulador é uma etapa do fluxo, não a última. O teste no ambiente real complementa a verificação. A confiança no resultado aumenta quando o comportamento é conferido no destino final.

Você desenvolve uma aplicação para celular, mas não tem o aparelho à mão. No simulador, você escolhe o modelo e testa o comportamento da aplicação na tela.

O simulador mostra o funcionamento esperado. Antes de publicar, o teste no dispositivo real confirma os detalhes que o simulador não reproduz com fidelidade.

## Simulador, emulador e mock Simulador e emulador são conceitos próximos. O simulador imita o comportamento, enquanto o emulador tenta reproduzir com mais fidelidade o hardware e o sistema. A fronteira varia conforme a ferramenta. O [mock](/glossario/mock/) é outra forma de aproximação: reproduz o comportamento esperado de uma parte do sistema, como uma API, para testes. Cada ferramenta aproxima do real em um nível diferente. ## Quando usar o simulador O simulador faz sentido no desenvolvimento e nos testes iniciais. A rapidez de executar sem o dispositivo real permite iterar com frequência. O custo e a disponibilidade do aparelho físico deixam de ser bloqueio. A combinação é o caminho: usar o simulador para desenvolver e testar rápido, e o ambiente real para confirmar. O [ambiente local](/glossario/ambiente-local/) e o simulador complementam a verificação antes da publicação. Para configurar o simulador e revisar o fluxo de testes da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação no desenvolvimento e na verificação do comportamento. ### Software factory: gatilhos que iniciam o trabalho dos agentes - URL: https://promovaweb.com/glossario/software-factory - Descrição: Software factory inicia sessões de agentes por gatilhos como issue, cron ou falha de CI. Entenda por que começar pequeno e onde o humano continua. ## O que é uma software factory Uma software factory é um sistema de trabalho que inicia [sessões](/glossario/sessao/) de [agentes](/glossario/agente-de-ia/) por gatilhos, em vez de esperar alguém abrir cada tarefa. O gatilho pode ser a criação de uma issue, um horário agendado, uma falha na integração contínua ou o término de outra sessão. Com a fábrica, mais trabalho roda sem espera, e a atenção humana fica para as escolhas que continuam exigindo revisão. ## Por que a fábrica existe Sem uma fábrica, cada sessão começa porque alguém a iniciou. Mesmo o trabalho que roda sozinho espera alguém abrir a sessão, apontar a tarefa e colocá-la em andamento. Quando você quer ganhar cadência além desse ritmo manual, a fábrica inicia a sessão sem essa espera, sem mudar necessariamente o restante do fluxo. ## Gatilhos que iniciam as sessões Os gatilhos comuns aparecem na tabela abaixo, com a sessão que cada um inicia e um exemplo de aplicação. | Gatilho | Sessão iniciada | Exemplo | | --- | --- | --- | | Issue criada ou marcada | Exploração, correção ou implementação | Uma issue marcada para um agente abre uma sessão que cria uma [pull request](/glossario/pull-request/) | | Agendamento por cron | Manutenção recorrente | Uma correção de lint por noite | | Falha de integração contínua ou alerta | Diagnóstico e tentativa de correção | Um build que falha na branch principal inicia uma sessão que localiza o commit e propõe o ajuste | | Término de outra sessão | Trabalho de continuação | Uma pull request aberta por um agente aciona a revisão automática, cujos comentários abrem uma sessão de correção | Cada gatilho fornece a entrada que a sessão vai usar. Uma issue precisa descrever o comportamento esperado, um agendamento precisa dizer qual correção fazer e uma falha de integração contínua precisa apontar o build que quebrou. Quanto mais específica a entrada, mais parecida com o esperado fica a pull request que a sessão abre. ## Começar pequeno Uma fábrica não precisa cobrir o processo inteiro de software. Um único [cron](/glossario/cron/) que executa um tipo de sessão e abre uma pull request revisável já é uma fábrica. Começar assim é útil: um ciclo estreito produz pull requests pequenas e parecidas, e revisar essas mudanças mostra até onde o ciclo pode ser confiado antes de você ampliá-lo.

O cron inicia uma sessão toda noite. O agente escolhe uma correção de lint pendente, ajusta as ocorrências no código e abre uma pull request antes do fim do expediente.

De manhã, você compara os arquivos alterados, ajusta o que ficou errado e decide se o ciclo pode ganhar uma segunda correção. Cada noite acrescenta uma mudança pequena e parecida, e é essa semelhança que facilita conferir o comportamento da fábrica.

## Onde o humano continua Você pode entrar em qualquer ponto da fábrica: escrever e marcar as issues que iniciam sessões, aprovar o plano de implementação ou revisar a pull request no momento do merge. Escolher quais desses pontos permanecem humanos é a pergunta central do desenho, e a resposta muda conforme o trecho do código. Quando nenhuma parte da saída passa por revisão, aquele trecho do código aceita pull requests sem leitura externa. Um ciclo que aplica uma correção de lint por noite e nunca é revisado pode corrigir dez vezes certo e errar na décima primeira, com o erro indo para o merge. Manter ao menos um ponto de revisão faz esse erro aparecer cedo. ## Como conferir a fábrica Compare o que o gatilho iniciou com o que a sessão entregou. No cron noturno, você confere o horário do disparo e compara a correção aplicada com a pull request aberta e com o resultado da [execução](/glossario/execution/). Uma fábrica que produz mudanças pequenas e parecidas torna essa conferência rápida, porque você aprende o padrão do ciclo e identifica a exceção quando ela aparece. Para desenhar a primeira fábrica e definir o que fica sob revisão humana, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia) oferece uma segunda leitura sobre o funcionamento dos agentes, a arquitetura e a forma de acompanhar o resultado. ### SSH: comunicação segura com uma máquina remota - URL: https://promovaweb.com/glossario/ssh - Descrição: SSH permite comunicação remota protegida entre cliente e servidor. Entenda chaves, verificação do host, execução de comandos e limites da sessão aberta. ## Definição SSH, ou Secure Shell, é um protocolo de comunicação remota com proteção criptográfica. Ele permite que um cliente se conecte a um servidor para executar ações autorizadas, como abrir uma sessão de terminal ou encaminhar uma conexão. O programa `ssh` é um cliente desse protocolo e depende de um serviço remoto que aceite o método de autenticação apresentado. A porta TCP 22 é convencional, mas o servidor pode atender em outra porta. ## Reconhecer o servidor e autenticar o usuário Antes de confiar no destino, o cliente verifica a chave do host conforme sua configuração. Em um primeiro acesso, você precisa confirmar a identificação apresentada por um canal confiável, especialmente antes de aceitar uma chave ainda desconhecida. A autenticação do usuário é outra etapa. No uso de chaves, a chave pública autorizada fica associada ao acesso remoto, enquanto a chave privada permanece protegida no lado que comprova esse acesso.

O cliente informa que a chave apresentada difere da conhecida. A reinstalação pode explicar a mudança, mas o aviso sozinho não comprova essa origem.

Você confirma a identificação da nova chave por um acesso administrativo confiável antes de atualizar o registro local. Apagar a informação antiga sem essa conferência eliminaria justamente a comparação que revelou a diferença.

## O que a sessão permite executar Após a autenticação, as permissões do usuário e a configuração do servidor delimitam as ações disponíveis. O acesso pode permitir abrir um shell, executar apenas um comando autorizado ou usar um subsistema específico, sem conceder administração completa da máquina. A criptografia protege o tráfego do canal, mas não transforma um comando incorreto em uma ação adequada. Antes de alterar arquivos ou reiniciar serviços, confira a máquina e o usuário usados, sobretudo quando vários ambientes possuem nomes semelhantes. ## Encerramento e processos remotos Fechar a conexão não comprova que todos os programas iniciados terminaram. Serviços, sessões persistentes de terminal e processos desacoplados podem continuar executando, conforme a forma usada para iniciá-los. Ao acompanhar uma tarefa longa, registre como ela foi iniciada e como consultar seu estado. Essa informação evita tratar a perda da conexão como confirmação de sucesso ou de interrupção da tarefa. Para revisar o acesso remoto e a administração do seu servidor com orientação, você pode usar o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/). ### Staging: ambiente de validação anterior à produção - URL: https://promovaweb.com/glossario/staging - Descrição: Staging permite conferir uma versão candidata antes da instalação em produção. Veja como aproximar ambientes e reconhecer os limites reais dos testes. ## O que é staging Staging é um ambiente preparado para validar uma versão que será instalada em produção. Ele permite percorrer tarefas com configurações representativas e observar o comportamento sem usar o ambiente que atende as operações reais. O termo também aparece como homologação ou pré-produção, conforme a organização. Você precisa conhecer o que esse ambiente reproduz, pois um endereço de preview pode mostrar a interface sem incluir as integrações necessárias para testar uma tarefa completa. ## Aproximar o comportamento e separar os efeitos Versões do runtime, do banco e dos serviços usados pela aplicação influenciam o resultado. Uma consulta aceita pelo banco de desenvolvimento pode se comportar de outra maneira no banco de produção, mesmo quando a biblioteca oferece uma interface parecida para ambos. Ao mesmo tempo, as credenciais e os destinos precisam permanecer adequados ao teste. Reproduzir uma integração não significa enviar mensagens a clientes reais ou gravar no banco que está atendendo o serviço.

O staging recebe o pacote candidato, um banco separado e uma integração de mensagens destinada a testes. Você cria uma reserva, acompanha a gravação e confere a confirmação no destino controlado.

O teste mostra que esse percurso funciona nas condições preparadas. Ele não comprova que a credencial de produção está correta nem que o serviço suportará centenas de reservas simultâneas.

## O conteúdo usado no teste muda o resultado Uma instalação vazia pode esconder problemas encontrados apenas em registros antigos. Uma atualização que muda o formato de um campo precisa ser conferida também com exemplos representativos do conteúdo que já existe. Prefira amostras preparadas para essa finalidade e preserve as restrições de acesso ao material usado. Copiar uma base real sem revisar campos pessoais, credenciais e destinos de notificações pode expor informações ou provocar efeitos fora do ambiente de teste. ## Confira o pacote que seguirá adiante O artefato validado precisa continuar identificado até a publicação. Se a produção recebe outro build, você precisa saber o que mudou entre os dois resultados e quais verificações precisam ser repetidas. Configurações próprias de cada ambiente também merecem comparação. Um teste bem-sucedido com a URL correta em staging não detecta automaticamente um endereço ausente ou incorreto na configuração de produção. ## A escala limita o que foi demonstrado Um ambiente menor pode confirmar o fluxo funcional sem representar o desempenho sob carga. A quantidade de registros, a concorrência e a capacidade das máquinas influenciam comportamentos que talvez não apareçam em um teste individual. Registre essas diferenças com o resultado da validação. Dizer que o cadastro funcionou para as amostras usadas é mais preciso que afirmar que a versão funcionará em qualquer condição de uso. ## Preparar a passagem para produção Depois dos testes, confira as configurações do destino, o procedimento de instalação e a recuperação prevista. O [deploy](/glossario/deploy/) em produção ainda precisa de acompanhamento, porque o ambiente de validação não observa antecipadamente todas as condições do serviço real. Para revisar a separação dos ambientes e o percurso de publicação com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode ajudar numa tarefa definida do projeto. Leve as diferenças já identificadas e o comportamento que precisa ser conferido. ### Status code HTTP: o resultado da resposta em famílias - URL: https://promovaweb.com/glossario/status-code-http - Descrição: Status code HTTP comunica o resultado de uma requisição. Entenda as cinco famílias, os códigos mais comuns e como interpretá-los junto com a resposta. ## O significado do código da resposta Status code HTTP é um código de três algarismos que comunica o resultado ou o andamento de uma requisição. O primeiro algarismo identifica a família, e o código completo informa uma situação mais específica. Ele deve ser interpretado junto com o método, os cabeçalhos e o contrato do serviço. Ao abrir um contato, você pode receber `200 OK` com o registro solicitado. Se o recurso não estiver disponível, pode receber `404 Not Found`. Os dois são respostas HTTP, embora levem a comportamentos diferentes na interface. Uma falha de conexão pode ocorrer sem qualquer código HTTP. Nesse caso, não houve uma resposta acessível ao cliente para classificar. Tratar esse cenário como se fosse automaticamente um `500` esconde uma diferença útil para a investigação. ## As cinco famílias A família `1xx` relata informações sobre o andamento da comunicação. A família `2xx` indica sucesso conforme o significado específico de cada código. A família `3xx` reúne situações que exigem uma ação adicional para concluir a requisição ou utilizar a representação. Ela inclui redirecionamentos e também `304 Not Modified`, que permite reutilizar conteúdo armazenado. Portanto, nem todo `3xx` significa uma nova página para abrir. A família `4xx` indica que o servidor percebeu um problema na requisição ou no acesso solicitado. A família `5xx` indica falha do servidor ao atender uma requisição aparentemente válida. Essas categorias orientam a análise, mas não identificam automaticamente o componente responsável pela causa original. ## Códigos parecidos exigem tratamentos diferentes `201 Created` informa a criação de um recurso. `202 Accepted` informa aceitação para processamento, que pode continuar depois da resposta. `204 No Content` indica sucesso sem conteúdo no corpo, dispensando uma tentativa de leitura de JSON. `401 Unauthorized` indica ausência de credenciais válidas para o recurso. `403 Forbidden` informa que o servidor entendeu a requisição, mas recusa seu atendimento. Repetir o login não resolve necessariamente um `403`, pois o perfil autenticado pode não ter a permissão exigida. `404` pode indicar que o recurso não foi encontrado ou que o servidor não deseja revelar sua existência. `405` indica método não permitido para o recurso. Já `429` informa excesso de requisições e pode vir acompanhado de orientação sobre quando tentar novamente. ## Ler o código junto com o contrato

A API pode responder 200 com uma lista vazia porque a consulta funcionou e não encontrou contatos. Esse resultado é compatível com a consulta da lista.

Já uma consulta a um contato específico pode responder 404 quando ele não está disponível. A diferença depende do recurso consultado, e a interface deve tratar cada resultado conforme o contrato.

Um `200` sozinho não comprova que o conteúdo veio no formato esperado. Um proxy ou uma página de login pode entregar HTML quando a integração esperava JSON. Confira o cabeçalho de tipo e o corpo antes de atribuir sucesso à função do produto. ## Como usar o código na investigação Na aba Network, selecione a chamada e compare o status com o método e o endereço. Leia os detalhes úteis da resposta e relacione o horário aos logs disponíveis. Um código `502`, por exemplo, pode ser produzido por um intermediário ao receber uma resposta inválida de outro servidor. Para definir novas tentativas, considere o efeito da chamada e as instruções da API. Repetir toda resposta `5xx` sem proteção contra duplicação pode executar novamente uma ação já aplicada. O verbete de [resposta HTTP](/glossario/resposta/) reúne as outras partes desse retorno. ### Status: o estado atual de um recurso ou registro - URL: https://promovaweb.com/glossario/status - Descrição: Status indica o estado atual de um recurso ou registro. Entenda os valores possíveis, o uso em filtros e a diferença para o código de resposta HTTP. ## O que é o status Status é o campo que indica o estado atual de um recurso ou registro. Um pedido pode estar pendente, pago ou entregue. Um cadastro pode estar ativo ou inativo. O status descreve em que ponto o registro está. O status é parte do domínio da aplicação. A [regra de negócio](/glossario/regra-de-negocio/) define os valores possíveis e as transições. O conjunto de status acompanha o fluxo do registro dentro do processo. ## Status e filtros O status costuma ser usado como filtro. Uma consulta pode trazer apenas os registros em um estado específico. Buscar pedidos pendentes, contatos ativos ou negociações em andamento usa o status como critério. O filtro orienta a leitura da aplicação. Em vez de trazer todos os registros, a consulta seleciona os que estão em determinado ponto. O status organiza o acesso ao que interessa em cada momento.

Um painel precisa mostrar apenas os pedidos pendentes de confirmação. Cada pedido tem um status que indica em que ponto está.

O filtro seleciona os registros com o status desejado. O painel apresenta só o que interessa, e o status orienta a ação seguinte em cada pedido.

## Transições de status O status não muda sozinho. Uma ação, um evento ou um fluxo altera o estado. A regra define quem pode mudar o status e em quais condições. Cada transição move o registro para outro estado. Um pedido é pago quando o pagamento é confirmado. Uma negociação avança quando a etapa muda. A transição conecta o status ao processo do domínio. ## Status e código de resposta O status de um recurso é diferente do [status code HTTP](/glossario/status-code-http/). O código de resposta indica o resultado de uma chamada, como 200 para sucesso. O status do recurso descreve o estado dele no domínio. A confusão entre os dois pode levar a erros de leitura. Uma chamada pode responder 200 e entregar um recurso pendente. O status do domínio é o que orienta o fluxo de negócio, independente do código da resposta. Para modelar os status e as transições da sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na definição dos estados e dos fluxos. ### Sub-recurso: o recurso que existe dentro do contexto de outro - URL: https://promovaweb.com/glossario/sub-recurso - Descrição: Sub-recurso é um recurso que existe dentro do contexto de outro. Entenda a relação no caminho, o identificador do elemento e a organização da API. ## O que é um sub-recurso Sub-recurso é um recurso que existe dentro do contexto de outro. Em vez de aparecer no topo do caminho, ele é identificado em relação ao recurso pai. A relação fica visível na própria URL. Um exemplo comum é o pedido dentro do usuário: `/users/5/orders`. O sub-recurso pertence ao contexto do usuário. A chamada age sobre o sub-recurso dentro desse contexto. ## O caminho aninhado O caminho aninhado expressa a relação. O recurso pai vem primeiro, e o sub-recurso vem depois. Os identificadores definem o elemento específico dentro de cada nível. O caminho pode se aprofundar conforme a relação. Um sub-recurso pode ter seus próprios sub-recursos. Cada nível adiciona contexto à chamada, e a URL comunica a hierarquia. ## Quando usar sub-recurso O sub-recurso faz sentido quando a relação é forte. O elemento só existe dentro do contexto do pai. A organização do caminho comunica essa dependência e ajuda quem consome a API a entender a relação. A escolha, porém, acompanha o desenho. Um recurso pode aparecer no topo do caminho quando a relação não precisa ser forçada. O uso do sub-recurso é uma decisão de modelagem.

Uma imagem pertence a um pedido específico. O caminho `/users/5/orders/2/upload` aponta o upload dentro do contexto do pedido 2 do usuário 5.

O sub-recurso identifica a relação entre a imagem e o pedido. A chamada age sobre o elemento dentro do contexto informado pela URL.

## Sub-recurso e autorização O contexto no caminho também participa da autorização. O sub-recurso existe dentro do recurso pai, e o acesso precisa confirmar a relação. A troca de um identificador no caminho não deve expor um elemento indevido. A verificação confirma se o sub-recurso pertence ao contexto informado. O ID do pai e o ID do elemento definem o alvo, e a permissão controla o acesso. A combinação de caminho e autorização protege a chamada. Para modelar os sub-recursos da sua API e a relação entre eles, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na organização dos caminhos. ### Tempo real: informação atualizada durante a execução - URL: https://promovaweb.com/glossario/tempo-real - Descrição: Tempo real apresenta informação atualizada enquanto o evento acontece. Entenda atualização contínua, latência, eventos e a diferença para a consulta sob demanda. ## O que é tempo real Tempo real descreve a atualização de informação enquanto o evento acontece. Em vez de esperar uma consulta, os dados chegam e são apresentados próximos do momento em que mudam. O uso varia conforme a necessidade. Um painel de acompanhamento, uma conversa ou uma automação que reage a eventos podem operar em tempo real. O importante é que a atualização aconteça de forma contínua, sem exigir que alguém pergunte a cada vez. ## A informação precisa de uma fonte de mudanças Para apresentar algo em tempo real, a origem precisa informar as mudanças. Um [evento](/glossario/evento/) publicado pela fonte pode alimentar a aplicação. Sem um mecanismo de notificação, a atualização contínua não acontece. Um [webhook](/glossario/webhook/) é um caminho comum: a origem chama um endereço quando algo acontece, e a automação reage. Outro caminho é a conexão persistente, que mantém o canal aberto entre as partes.

Um pedido novo chega na loja. O painel precisa mostrá-lo para o time sem que ninguém atualize a página manualmente.

A origem publica o evento, e a automação atualiza o painel. O pedido aparece em tempo real, e o time recebe a atualização pelo evento.

## Tempo real e latência Tempo real não significa ausência de atraso. Existe sempre uma latência entre o evento e a apresentação. A plataforma, a rede e o processamento contribuem para esse atraso. A atualização é próxima do acontecimento, não instantânea em sentido absoluto. Quando o atraso precisa ser mínimo, a escolha da tecnologia importa. Conexões persistentes e eventos tendem a entregar mais rápido do que a consulta repetida. A avaliação depende do caso e do que o produto exige. ## Escolher o mecanismo certo O mecanismo de tempo real acompanha a natureza do dado. Um fluxo contínuo de eventos pode usar um barramento. Uma integração pontual pode usar um webhook. A consulta sob demanda serve quando a atualização contínua não é necessária. O custo também importa. Manter conexões abertas e processar eventos continuamente consome recursos. Vale a pena quando o produto exige, e deve ser evitado quando uma consulta simples resolve. Para avaliar o melhor mecanismo de tempo real para o seu fluxo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na escolha e na implementação da atualização contínua. ### Terminal: a interface textual de comando - URL: https://promovaweb.com/glossario/terminal - Descrição: Terminal apresenta comandos e resultados em texto. Entenda prompt, sessões locais e remotas e a relação entre terminal, shell e CLI no dia a dia. ## A interface textual de entrada e saída Terminal é uma interface para enviar entrada e receber saída de programas em forma textual. Em computadores atuais, costuma ser apresentado por um emulador de terminal. Ele pode funcionar como aplicativo próprio ou como painel integrado ao editor. Dentro dessa interface, você normalmente encontra um shell, que interpreta os comandos. Também pode haver um programa interativo ou uma sessão remota. A janela é o lugar da interação, mas não define sozinha onde o comando atuará nem qual processo será iniciado. Ao abrir o terminal integrado de um editor, confira o ambiente selecionado. Ele pode estar conectado ao computador local, a um container ou a uma máquina remota. Um comando de arquivo atua no ambiente da sessão, mesmo que a janela esteja no seu computador. ## Prompt, comando e resultado O prompt é o indicador apresentado pelo shell para receber uma nova linha. Ele pode mostrar diretório, nome da máquina ou outros detalhes configurados. Documentações também usam símbolos como `$` para representar o prompt, sem que você deva copiá-los como parte do comando. Esse comando só funciona se Node.js estiver disponível naquela sessão. A saída depende da versão instalada e pode diferir entre ambientes. Uma mensagem de comando não encontrado aponta para ausência do executável ou para sua localização fora do caminho de busca utilizado.

O comando de versão pode retornar valores diferentes nas duas sessões. Cada uma usa os executáveis disponíveis em seu ambiente. O editor pode exibir ambos os terminais sem tornar suas instalações iguais.

Se o projeto funciona em uma sessão e falha na outra, compare versões, diretório atual e configuração. Trocar apenas a aparência do terminal não corrige essas diferenças.

## Nem toda execução termina imediatamente Um servidor de desenvolvimento pode continuar executando e exibindo logs. Enquanto ele ocupa o primeiro plano, o shell não está necessariamente aguardando outro comando. Abrir outra sessão permite executar consultas separadas sem confundir a entrada do servidor com a do shell. Em ambientes usuais, `Ctrl+C` solicita interrupção ao processo em primeiro plano. O programa pode tratar esse sinal de forma própria. Fechar uma aba também pode afetar os processos associados, por isso não deve ser confundido com um mecanismo planejado de operação de serviços. ## Ler a saída com atenção A saída pode trazer resultados, avisos e erros. O código de saída fornece outra informação sobre o término, conforme a convenção da ferramenta. Uma linha com aparência positiva não comprova que o processo concluiu o trabalho esperado. O histórico visual também pode conservar mensagens antigas. Confira qual execução produziu o texto antes de atribuí-lo ao comando atual. Em tarefas longas, horários e identificadores podem ajudar a relacionar a mensagem ao processo correto. ## Como usar a sessão para investigar Confira a máquina ou ambiente conectado, o diretório atual e a ferramenta efetivamente chamada. Depois, relacione o erro ao comando e aos parâmetros utilizados. Ao compartilhar a saída, remova credenciais e informações privadas que possam aparecer nos registros. O verbete de [shell](/glossario/shell/) explica a interpretação da linha, enquanto [CLI](/glossario/cli/) descreve a interface de comandos oferecida por cada ferramenta. ### Teste de integração: verificar o limite entre componentes - URL: https://promovaweb.com/glossario/teste-de-integracao - Descrição: Teste de integração verifica a interação entre partes de um sistema, como app e banco. Entenda o alcance variável e a diferença para um teste local. ## O que é um teste de integração Teste de integração verifica a interação entre partes de um sistema, como a aplicação e o banco ou um cliente HTTP e uma API. A pergunta principal é se essas partes trocam e interpretam as informações conforme o comportamento esperado. O alcance varia entre projetos, por isso o nome precisa vir acompanhado de uma descrição. Um teste pode exercitar dois módulos locais, enquanto outro executa uma comunicação de rede com um serviço preparado para testes. ## Declarar quais partes participam Identifique os componentes executados e os substitutos usados no cenário. Se o cliente HTTP chama uma simulação da API, o resultado informa como ele se comporta diante daquela resposta, sem comprovar o funcionamento do provedor real. Algumas convenções chamam esse caso de integração restrita, enquanto outras reservam o termo para componentes reais combinados. Explicar a montagem do teste evita prometer uma cobertura que ele não oferece.

O cadastro recebe um código de referência que começa com zero. Um teste grava esse valor pela aplicação e o consulta novamente num banco dedicado ao cenário.

Se a configuração converte o campo para número, o zero inicial desaparece. Conferir apenas se a gravação terminou não detectaria a mudança, por isso a comparação precisa examinar o valor recuperado.

## Preparar um cenário repetível O estado inicial deve permitir entender por que a resposta é esperada. Um registro deixado por uma execução anterior pode fazer o teste passar ou falhar por um motivo diferente da interação que ele deveria examinar. Use a preparação e a limpeza adequadas ao ambiente, considerando também execuções paralelas. Quando dois testes alteram o mesmo registro, a ordem de execução pode interferir nos resultados e dificultar a reprodução. ## Conferir a semelhança relevante com produção Um banco de teste com estrutura desatualizada pode aceitar uma gravação que a versão publicada recusa. Aplique as migrations correspondentes e confira os tipos e as restrições envolvidos no comportamento examinado. Não é necessário copiar todos os registros reais para verificar uma interação. Prepare exemplos representativos e trate volume, concorrência e desempenho com cenários próprios quando esses aspectos precisarem ser avaliados. ## Interpretar o alcance do resultado A interface pode participar de um teste de integração, mas sua presença não significa que toda a jornada foi percorrida. Declare o ponto de entrada, o resultado conferido e os serviços que ficaram fora da execução para distinguir esse teste de uma verificação completa do fluxo. Para investigar a diferença entre uma simulação e o serviço usado pela aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite trabalhar nessa comunicação com orientação ao vivo. A sessão pode incluir a preparação do cenário e a leitura dos retornos durante a execução. ### Teste unitário: uma unidade de comportamento - URL: https://promovaweb.com/glossario/teste-unitario - Descrição: Teste unitário verifica uma unidade de comportamento isolada com entradas conhecidas. Entenda preparação, resultado esperado e alcance da cobertura. ## O que é um teste unitário Teste unitário verifica uma unidade de comportamento sob condições conhecidas. Ele prepara uma situação, executa o código e compara o resultado com uma expectativa definida para aquela entrada. Ao testar um cálculo de desconto, por exemplo, você informa o total da compra e confere o desconto devolvido pela função. A unidade pode ser uma função ou um conjunto pequeno de partes que trabalham juntas. O alcance deve ajudar a entender qual comportamento falhou, sem exigir uma correspondência rígida entre cada função e cada teste. ## Preparar, executar e verificar A preparação fornece as entradas e o estado necessário para o cenário. Depois da ação, a verificação compara o resultado observado com o esperado e deve falhar quando essa expectativa não é atendida. Defina o resultado esperado a partir do comportamento especificado para o produto. Se uma compra deve receber 1.000 centavos de desconto, esse é o resultado a comparar com a função. Chamar a própria função para obter a expectativa faria o teste aceitar o mesmo cálculo incorreto dos dois lados da comparação.

A promoção concede 1.000 centavos de desconto em compras a partir de 10.000 centavos. Uma compra de 9.999 deve receber zero de desconto. No mínimo de 10.000 e logo acima, em 10.001, o desconto esperado é 1.000.

Se a implementação exigir valor maior que 10.000, o caso exatamente no limite falha. Um teste apenas com a compra de 10.001 não detectaria essa diferença.

## Escolher os colaboradores do cenário Alguns testes executam colaboradores reais da unidade, enquanto outros usam substitutos como [mocks](/glossario/mock/). As duas abordagens aparecem na prática, e a escolha depende do alcance pretendido e do que precisa ser controlado. Comunicação remota costuma exigir atenção porque pode acrescentar espera e resultados variáveis. Testes pequenos e previsíveis permitem verificações frequentes, mas velocidade sozinha não define se um teste é unitário. ## Evitar resultados dependentes da ordem Um teste pode alterar uma configuração compartilhada e afetar o cenário seguinte. Prepare o estado necessário e restaure o que foi modificado conforme o mecanismo da ferramenta, para que cada resultado tenha uma explicação própria. Datas e horários também precisam de tratamento explícito quando determinam o resultado. Para testar uma promoção que termina às 18h, forneça ao cenário um horário conhecido e confira o comportamento próximo do encerramento. Usar o relógio real faria o teste mudar de resultado ao longo do dia sem nenhuma alteração no código. ## Examinar o que a verificação detecta Leia a comparação final e pergunte qual erro ela conseguiria revelar. No exemplo do desconto, os casos devem distinguir inclusão e exclusão do limite, além de conferir o valor concedido. Cobertura de execução não demonstra que essas diferenças foram examinadas. Uma linha pode ser executada sem que o teste compare o resultado relevante, enquanto entradas ausentes continuam sem verificação. Para revisar testes de uma função gerada ou alterada com IA, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite examinar os resultados esperados e executar os cenários com orientação ao vivo. Você trabalha no editor e confere se as expectativas representam o comportamento pretendido. ### Timeout: limite de espera de uma operação - URL: https://promovaweb.com/glossario/timeout - Descrição: Timeout limita uma espera ou execução. Entenda os diferentes escopos, o resultado desconhecido e os cuidados antes de repetir uma chamada interrompida. ## O que é timeout Timeout é um limite de tempo aplicado a uma espera ou execução. Ele pode determinar quanto a aplicação aguardará uma conexão, a resposta de uma API ou a conclusão de um workflow antes de interromper aquela espera e seguir para o tratamento previsto. Esse limite impede que um processamento aguarde indefinidamente, mas seu significado depende do escopo configurado. Um timeout de conexão e um timeout do workflow inteiro medem partes diferentes do trabalho e podem produzir resultados diferentes. ## O que exatamente está sendo cronometrado O valor configurado precisa ser interpretado junto do instante que inicia a medição e do evento que encerra a espera. Um intervalo sem receber novos bytes pode atingir um limite de inatividade, enquanto uma transferência que continua recebendo conteúdo ainda pode ultrapassar um limite de duração total. Confira qual desses comportamentos a ferramenta documenta. O HTTP Request Node do n8n documenta seu timeout como a espera pelos headers e pelo início da resposta. Já a configuração de timeout do workflow se refere ao limite da execução, portanto os dois valores não devem ser interpretados como controles equivalentes. A unidade também precisa ser conferida. Informar `30` em um campo que espera milissegundos representa uma espera muito diferente de trinta segundos, e um valor aparentemente razoável pode encerrar quase todas as chamadas se a unidade for interpretada incorretamente. ## A espera terminou, mas o resultado pode ser desconhecido Um timeout informa que o limite observado foi atingido. Ele não comprova que o servidor deixou de executar a ação, pois a chamada pode ter chegado e o processamento pode continuar depois que o cliente encerra sua espera.

A aplicação aguarda a confirmação de criação durante cinco segundos. O serviço conclui o registro da exportação depois de seis segundos, quando o cliente já encerrou a espera.

Reenviar a criação como uma solicitação nova pode produzir outra exportação. Se houver uma consulta pelo identificador original ou suporte a chave de idempotência, a aplicação pode recuperar o resultado conforme esse contrato.

## Cancelamento precisa ser confirmado pelo mecanismo adequado Encerrar a conexão local não garante o cancelamento do trabalho remoto. Alguns serviços oferecem uma ação específica para cancelar uma tarefa, mas ela também pode chegar depois de a tarefa terminar ou encontrar uma etapa que já não pode ser desfeita. Por isso, a interface e o workflow precisam distinguir falha de espera de cancelamento confirmado. Mostrar que a ação foi cancelada apenas porque o navegador deixou de aguardar pode contradizer o estado real no serviço. ## Várias camadas podem ter limites diferentes A mesma chamada pode passar pelo navegador, por um proxy e pelo servidor que executa a tarefa. Uma dessas camadas pode encerrar a espera antes das outras, fazendo o cliente receber erro enquanto o processamento continua no destino. Novas tentativas também consomem tempo. Três chamadas com limite de cinco segundos cada, somadas às pausas entre elas, podem ultrapassar o prazo total que você pretendia oferecer para a tarefa. ## Como escolher e verificar o limite Observe a duração das chamadas em condições representativas e o prazo útil do processo. Uma exportação longa pode precisar de processamento em segundo plano com acompanhamento de status, em vez de manter uma única conexão esperando durante toda a geração. Teste uma resposta lenta e confira o que acontece no cliente e no destino depois do limite. Antes de configurar um [retry](/glossario/retry/), verifique como a integração reconhece efeitos já realizados e como informa uma pendência cujo resultado ainda não pôde ser confirmado. ### Token de modelo: unidade de processamento - URL: https://promovaweb.com/glossario/token-de-modelo - Descrição: Token de modelo representa uma unidade de conteúdo. Entenda a tokenização, a quantidade de tokens enviados e recebidos e os limites da janela de contexto. ## O que é um token de modelo Token de modelo é uma unidade usada para representar conteúdo no processamento de um modelo. Em texto, o tokenizador transforma a sequência de caracteres em identificadores que o modelo consegue utilizar. Essa divisão não acompanha obrigatoriamente as palavras que você vê na tela. Uma palavra pode ocupar várias unidades, enquanto pontuação, espaços e outras sequências também influenciam o resultado conforme o tokenizador utilizado. ## A quantidade depende do modelo Tokenizadores usam vocabulários e algoritmos próprios, então o mesmo texto pode produzir quantidades diferentes em modelos distintos. Uma aproximação baseada em palavras pode ajudar numa estimativa inicial, mas não substitui a medição com o tokenizador correspondente. Não existe uma quantidade universal de caracteres por token em português. Código, números e texto em outros idiomas também podem produzir proporções diferentes, mesmo quando os arquivos têm tamanhos semelhantes em bytes.

Você escreve uma pergunta de duas linhas, mas a aplicação envia também a conversa anterior e vários trechos de documentação. O tamanho processado considera esse conteúdo adicional.

Estimar apenas a pergunta faz a previsão parecer menor que a chamada real. A conferência precisa usar a entrada montada pela aplicação, incluindo os elementos que não aparecem na última mensagem.

## Entrada e saída ocupam recursos Os tokens enviados e os produzidos durante a resposta têm funções diferentes na medição do uso. Um limite de saída define quanto a geração pode produzir, sem prometer que o modelo utilizará toda essa quantidade. As condições de cobrança e os limites da janela de contexto dependem do provedor e do modelo. Recursos de cache podem mudar o tratamento do consumo sem significar que o conteúdo deixou de ocupar espaço na janela. ## Estimar conteúdo além do texto simples Definições de ferramentas e mensagens estruturadas podem acrescentar conteúdo à chamada. Quando imagens ou documentos participam da entrada, a forma de contabilização também depende do processamento oferecido pela plataforma. Use a ferramenta de estimativa compatível com o modelo e examine quais elementos ela considera. A previsão anterior à chamada pode diferir do uso informado depois, por isso os dois valores têm finalidades complementares. ## Relacionar a medida ao limite da tarefa A [janela de contexto](/glossario/janela-de-contexto/) determina quanto conteúdo pode participar da execução nas condições do modelo. Reduzir a entrada exige preservar os trechos necessários à tarefa, em vez de retirar informação apenas para diminuir um número. Para investigar uma aplicação que envia histórico ou arquivos em excesso, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) permite examinar a montagem da chamada com orientação ao vivo. Você pode conferir o conteúdo enviado e comparar a estimativa com o uso registrado pela integração. ### Tool calling: solicitação estruturada de ferramenta - URL: https://promovaweb.com/glossario/tool-calling - Descrição: Tool calling permite solicitar ferramentas com argumentos estruturados. Entenda definição, autorização, execução e conferência do resultado da chamada. ## O que é tool calling Tool calling é o mecanismo que permite ao modelo solicitar uma ferramenta por meio de uma chamada estruturada. A solicitação identifica a ação disponível e apresenta argumentos que a implementação usará para executá-la. Uma ferramenta pode consultar registros, ler arquivos ou iniciar uma operação, conforme sua definição. O modelo não recebe automaticamente essas capacidades: a aplicação ou o provedor precisa disponibilizá-las. ## Definir a ferramenta e interpretar a solicitação A descrição informa a finalidade da ferramenta, enquanto o formato dos argumentos indica quais campos ela aceita. O modelo usa essa interface para produzir a solicitação, que ainda precisa ser interpretada e verificada pelo sistema. Nas ferramentas executadas pela aplicação, o código realiza a ação e devolve o resultado para a continuação. Em ferramentas hospedadas, parte desse ciclo pode ocorrer na infraestrutura do provedor, sem uma função local equivalente.

O modelo solicita a leitura de uma tarefa com um identificador existente. A tarefa pertence a um projeto fora do acesso do perfil autenticado.

Validar apenas o tipo do identificador permitiria consultar o registro indevido. A ferramenta precisa aplicar a autorização do projeto antes de devolver qualquer conteúdo, mesmo que o modelo tenha solicitado a chamada corretamente.

## Separar formato e autorização Um schema pode exigir um campo numérico ou uma opção de uma lista. Essa verificação estrutural não comprova que o registro pertence à pessoa autenticada nem que uma alteração é permitida naquele estado. A autorização deve ocorrer na implementação que acessa o recurso. O texto do prompt e a descrição da ferramenta não substituem essa verificação, principalmente quando a ação pode modificar informações persistidas. ## Tratar o retorno como resultado de execução Uma ferramenta pode devolver erro, conteúdo vazio ou um identificador de trabalho ainda em andamento. Cada situação precisa orientar a próxima etapa sem ser convertida automaticamente numa mensagem de sucesso. Se uma operação de escrita demora a responder, repetir a chamada também exige cuidado com seus efeitos. O tratamento deve considerar [idempotência](/glossario/idempotencia/) e a possibilidade de a primeira execução já ter concluído a alteração. ## Conferir a resposta depois da chamada O retorno da ferramenta fornece material para a continuação, mas o modelo ainda pode interpretá-lo incorretamente. Compare a resposta final com o resultado recebido e preserve a relação entre solicitação e execução para investigar diferenças. Para revisar ferramentas de um assistente conectado ao projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a análise no editor e no terminal. A sessão pode conferir argumentos, permissões e retornos antes de ampliar as ações disponíveis. ### Trace distribuído: percurso de uma operação - URL: https://promovaweb.com/glossario/trace-distribuido - Descrição: Trace distribuído relaciona trechos de uma operação entre componentes. Entenda spans, propagação, durações sobrepostas e limites de amostragem e cobertura. ## O que é um trace distribuído Trace distribuído é um registro que relaciona partes instrumentadas de uma operação entre componentes. Ele permite acompanhar, por exemplo, uma chamada recebida por uma API e o trabalho realizado por serviços que participam de sua resposta. Cada parte é registrada como um span, com início, término e informações sobre o trabalho observado. Você consulta essas relações para entender o percurso e localizar intervalos que precisam de investigação. ## Spans representam unidades de trabalho Um span pode representar o atendimento de uma requisição, uma consulta ou uma chamada externa. Ele pode ter spans filhos que detalham atividades realizadas durante seu intervalo, além de atributos e eventos úteis à leitura. Essa estrutura não implica uma sequência única de execução. Duas chamadas podem ocorrer em paralelo, e uma atividade assíncrona pode precisar de uma relação própria para representar seu vínculo com o trabalho que a originou.

A consulta ao catálogo leva 300 milissegundos e a de disponibilidade leva 500. Como os intervalos se sobrepõem, a espera conjunta não corresponde automaticamente à soma de 800 milissegundos.

O span da API inclui a espera e outras etapas, como preparar a resposta. A linha do tempo permite distinguir esse intervalo total dos tempos dos spans filhos, sem somar de novo a mesma espera.

## A referência precisa atravessar os componentes O rastreamento distribuído depende da propagação das informações que associam os spans. Em HTTP, essa associação pode viajar em headers próprios, que o próximo serviço interpreta ao iniciar seu trecho de trabalho. Se um componente perde essa informação, os spans seguintes podem aparecer como outro percurso. O mesmo cuidado se aplica a filas e tarefas assíncronas, cuja instrumentação precisa preservar a relação adequada entre envio e processamento. ## O tempo observado orienta a investigação Um span longo mostra que aquela unidade consumiu mais tempo na observação. Isso não informa sozinho se a demora veio de CPU, espera por conexão, rede ou trabalho realizado em outro serviço. Compare o trecho com seus detalhes e com [logs](/glossario/log/) e métricas do mesmo caso. Um erro no span também precisa ser interpretado conforme a convenção de instrumentação, pois falhas de negócio e falhas técnicas podem ser registradas de maneiras diferentes. ## O percurso disponível pode estar incompleto Uma parte sem instrumentação não ganha detalhes apenas porque os componentes vizinhos possuem spans. A coleta também pode usar amostragem e preservar somente uma seleção de operações, conforme sua política. Por isso, não encontrar um trace específico não comprova que a chamada não aconteceu. Confira a seleção, a retenção e o encaminhamento antes de concluir que houve uma falha no processamento da aplicação. ## Como conferir a instrumentação Na API do exemplo, faça uma consulta de teste e localize seu trace na ferramenta de observabilidade. Confira se as chamadas ao catálogo e à disponibilidade aparecem vinculadas ao atendimento da API e se seus intervalos se sobrepõem. Se uma delas aparecer isolada, examine a propagação entre esses serviços antes de atribuir a demora à consulta. Quando uma lentidão exige analisar esse percurso com orientação ao vivo, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode apoiar uma investigação delimitada. A tarefa deve partir de um caso identificável e dos sinais que estão disponíveis para examiná-lo. ### Transação: unidade de trabalho com garantias - URL: https://promovaweb.com/glossario/transacao - Descrição: Transação reúne operações de banco em uma única unidade de trabalho. Entenda BEGIN, COMMIT, ROLLBACK e o limite das garantias sobre serviços externos. ## Delimitar uma unidade de trabalho no banco Transação delimita uma unidade de trabalho no banco. Quando reúne alterações, permite confirmá-las em conjunto ou cancelar as mudanças cobertas por essa unidade. As garantias e o comportamento diante de falhas dependem do banco e da configuração utilizada. Uma aplicação pode precisar criar uma turma e registrar suas associações obrigatórias. Tratar cada gravação como uma operação independente pode deixar apenas parte do cadastro pronta. Uma transação permite coordenar a confirmação desse conjunto. O código precisa definir quais comandos usam a mesma transação e quando ela termina. Uma chamada externa, outra conexão ou uma gravação já confirmada permanece fora desse conjunto, mesmo quando aparece na mesma função da aplicação. ## Início, operações e conclusão O exemplo pressupõe tabelas compatíveis, o estudante 7 existente e o identificador 10 disponível para criar a turma. Entre `BEGIN` e `COMMIT`, as duas gravações participam do mesmo bloco, cuja confirmação é solicitada ao final. Para cancelar esse conjunto antes da confirmação, `ROLLBACK` descarta suas alterações transacionais. Bibliotecas podem oferecer uma função que abre a transação e gerencia o encerramento. Ainda assim, você precisa saber se um erro provoca cancelamento ou se foi capturado e ignorado pelo código. O comportamento não deve ser presumido apenas pelo nome da função.

A rotina não consegue registrar a matrícula da pessoa 7 na turma 10. Ela deve encerrar a unidade sem deixar confirmada a turma criada nessa tentativa. Depois do cancelamento, consulte as duas tabelas para conferir que nem a turma nem o vínculo foram mantidos.

Se a primeira gravação aconteceu fora da transação, ela pode permanecer. A investigação precisa conferir a conexão e o momento de cada comando, além do tratamento do erro.

## Atomicidade e isolamento Atomicidade trata da confirmação ou do cancelamento do conjunto. Isolamento trata de como transações simultâneas observam e afetam o trabalho umas das outras. Usar uma transação não resolve automaticamente toda disputa por um recurso. Duas operações podem ler a mesma disponibilidade e tentar utilizá-la ao mesmo tempo. O projeto pode precisar de restrições, controle de concorrência ou um nível de isolamento apropriado. A regra de negócio precisa ser testada com chamadas simultâneas quando esse caso for relevante. Transações longas também podem manter recursos ocupados e interferir em outras operações. Evite deixá-las abertas enquanto aguarda uma interação humana ou uma chamada externa demorada. O escopo deve corresponder ao trabalho que o banco precisa confirmar em conjunto. ## Efeitos fora do banco Enviar uma mensagem antes do commit pode anunciar uma operação que depois será cancelada. Enviar apenas depois do commit elimina esse caso, mas ainda deixa a possibilidade de falhar entre a confirmação e o envio. Sistemas que precisam garantir o encaminhamento podem registrar uma tarefa pendente na mesma transação e processá-la depois. O processamento posterior precisa registrar o resultado do envio e tratar novas tentativas sem duplicar o efeito no destino. Uma tarefa pendente no banco permite acompanhar o trabalho, mas não comprova que a mensagem foi entregue. O verbete de [rollback de transação](/glossario/rollback-de-transacao/) detalha o que o cancelamento efetivamente desfaz. ### Transformação de dados: ajustar a entrada ao que o destino exige - URL: https://promovaweb.com/glossario/transformacao-de-dados - Descrição: Transformação de dados ajusta formato, estrutura ou valores. Veja como converter datas e números, preservar o significado e validar a saída da integração. ## O que é transformação de dados Transformação de dados é a alteração do formato, da estrutura ou dos valores recebidos para atender a uma finalidade definida. Uma integração pode converter uma data, calcular a duração em outra unidade ou reunir campos separados em um objeto aceito pelo destino. O [mapeamento](/glossario/mapeamento-de-dados/) identifica de onde vem cada informação e onde ela será usada. A transformação define qual alteração será aplicada durante esse percurso, e as duas tarefas podem acontecer na mesma etapa do workflow. ## O significado vem antes da conversão Um texto formado por algarismos não é necessariamente uma quantidade. O código `00127` pode identificar uma inscrição e precisar conservar os zeros iniciais, enquanto o texto `127` pode representar uma quantidade que será usada em cálculos. Converter ambos automaticamente para número pode eliminar parte de um identificador. Antes de ajustar o tipo, confira o significado do campo e o contrato do destino para saber se a transformação preserva a informação necessária. ## Datas precisam de formato e, quando aplicável, fuso A data `01/03/2026` representa primeiro de março quando a origem usa dia, mês e ano. Interpretá-la como mês, dia e ano produziria três de janeiro, embora ambas as saídas pareçam datas válidas. Horários acrescentam outra necessidade de interpretação. Um instante com fuso pode ser convertido para outra referência, enquanto uma data de aniversário ou uma data de calendário não deve ganhar um deslocamento de horário apenas porque a ferramenta oferece esse recurso.

A origem informa 01/03/2026, e o destino exige 2026-03-01. A transformação reorganiza a representação e preserva a data de primeiro de março, sem acrescentar um horário que não foi informado.

Uma entrada como 31/02/2026 precisa ser recusada ou encaminhada para correção. Reorganizar os caracteres não transforma uma data inexistente em uma data válida.

## Números e unidades exigem leitura completa Separadores decimais e de milhar variam conforme o formato recebido. Substituir toda vírgula por ponto pode funcionar para uma amostra simples e falhar quando a origem envia um valor como `1.234,50`, que exige uma interpretação consistente do formato. Também confira se o destino espera a mesma unidade. Uma duração recebida como noventa segundos e enviada para um campo em minutos precisa representar um minuto e meio, enquanto apenas copiar o número noventa alteraria o significado. Funções de conversão podem aceitar apenas o início de um texto. Em JavaScript, `parseFloat` pode extrair um número e ignorar caracteres finais, por isso obter um resultado numérico não demonstra que a entrada inteira atendia ao formato exigido. ## A estrutura pode mudar sem perder a associação Uma transformação pode dividir uma lista, agrupar resultados ou compor um campo de nome completo. Esses ajustes devem preservar os identificadores necessários para relacionar a saída ao item correto, especialmente quando a quantidade ou a ordem dos itens muda. No n8n, componentes como Edit Fields e Code oferecem formas diferentes de preparar essa saída. Escolha a etapa conforme a alteração necessária e confira também quais campos originais continuam disponíveis depois dela. ## A validação acompanha a transformação Verifique a entrada antes da conversão e confira o resultado depois dela. Um valor ausente pode exigir interrupção ou um padrão explicitamente permitido, enquanto um valor fora da faixa aceita precisa de tratamento mesmo que seu tipo esteja correto. Uma saída em [JSON](/glossario/json/) válido ainda pode conter uma data errada ou uma quantidade na unidade incorreta. A aceitação do formato pelo destino não substitui a comparação com o significado previsto para cada campo. ## Como testar a conversão Use amostras que cubram identificadores com zeros iniciais, formatos de data ambíguos, campos sem valor e números com separadores. Para cada caso, registre a saída esperada e compare com o resultado produzido pela etapa. Confira também uma entrada inválida para observar se ela é recusada ou convertida parcialmente. O teste deve demonstrar que a automação preserva as informações corretas e torna visíveis os casos que precisam de correção na origem. ### Transmissão ao vivo: exibir conteúdo em tempo real para um público - URL: https://promovaweb.com/glossario/transmissao-ao-vivo - Descrição: Transmissão ao vivo exibe conteúdo em tempo real para um público. Entenda produção, distribuição, audiência e a diferença para o conteúdo gravado. ## O que é transmissão ao vivo Transmissão ao vivo, ou live stream, é a exibição de conteúdo em tempo real para um público conectado. O que acontece na origem chega aos espectadores enquanto acontece, sem a edição de um vídeo gravado. A transmissão é usada em eventos, demonstrações e interações com a audiência. O formato traz imediatismo: o público acompanha o que está acontecendo no momento, e a interação pode acontecer durante o conteúdo. ## Produção e distribuição A transmissão depende de captação, processamento e distribuição. A imagem e o som da origem são enviados a uma plataforma, que os distribui para os espectadores. A plataforma cuida de escalar a entrega para o público conectado. O produtor configura o formato, a qualidade e o destino. A plataforma gerencia a entrega. Em muitos casos, a transmissão pode ser integrada com [APIs](/glossario/api/) para iniciar e acompanhar o evento de forma programática.

Uma empresa vai anunciar um produto novo. Em vez de gravar o vídeo, ela transmite ao vivo pela plataforma de streaming.

O público acompanha o anúncio enquanto acontece. A interação acontece durante a transmissão, e o evento termina com os espectadores conectados ao lançamento.

## Audiência e interação A transmissão ao vivo conecta produtor e audiência em tempo real. Os espectadores podem assistir, comentar e participar. Essa proximidade é o valor principal do formato ao vivo em relação ao conteúdo gravado. A interação exige atenção. Moderar comentários, responder dúvidas e conduzir o conteúdo enquanto acontece é parte do trabalho do produtor. A qualidade da transmissão depende tanto da parte técnica quanto da condução. ## Ao vivo, mas não perfeito A transmissão ao vivo acontece sem a chance de refazer. Um erro durante o evento vai ao ar. A preparação reduz riscos: testar a conexão, conferir o áudio e revisar o roteiro antes de começar. O atraso entre a origem e o público não é zero. Existe latência na entrega, e a plataforma define o nível de atraso. O público acompanha quase em tempo real, mas a transmissão não é instantânea em sentido absoluto. Para planejar e executar uma transmissão ao vivo no seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na configuração técnica e na condução do evento. ### Trigger: o início de um workflow - URL: https://promovaweb.com/glossario/trigger - Descrição: Trigger inicia uma automação por horário, evento ou ação manual. Entenda a relação com webhooks, polling e validação dos campos recebidos no n8n. ## O que é um trigger Trigger é o componente que inicia uma automação quando ocorre a condição configurada. Essa condição pode ser um horário, uma chamada recebida de outro serviço ou uma ação manual, e o início cria uma [execução](/glossario/execution/) do workflow com a entrada disponível naquele momento. No n8n, um formulário pode enviar uma chamada para o Webhook Node, enquanto um relatório diário pode começar com o Schedule Trigger. Ambos iniciam workflows, mas você configura e verifica cada entrada de uma forma diferente. ## De onde vem o início da automação O trigger manual permite executar o fluxo sob comando, o que é útil durante a construção e os testes. O agendado acompanha um horário ou intervalo, como a emissão de um resumo às oito da manhã, e depende do fuso configurado para interpretar esse horário. Um trigger de aplicativo pode receber notificações do serviço ou consultar periodicamente se apareceu alguma mudança. Essa consulta é chamada de [polling](/glossario/polling/), e o intervalo entre consultas influencia quanto tempo você espera até a automação reconhecer uma novidade. Já o [webhook](/glossario/webhook/) recebe uma chamada enviada pela origem. Nesse caso, além de configurar o Node, você precisa cadastrar o endereço correto no serviço que fará o envio e conferir o tipo de evento que ele está autorizado a comunicar. ## Receber a chamada não valida o cadastro A autenticação da chamada responde se o remetente apresentou a credencial exigida. Ela não confirma que o email de uma inscrição está preenchido ou que o código da turma existe, pois essas verificações pertencem ao processo que você está automatizando. O trigger pode oferecer filtros e controles de entrada, mas você precisa configurá-los e conhecer seus limites. Os campos que determinam a criação de um cadastro devem passar pela [validação de entrada](/glossario/validacao-de-entrada/) prevista no workflow.

O formulário envia uma chamada autenticada com nome e turma, mas sem email. O trigger recebe a chamada e inicia a execução, porque receber esses campos não equivale a aprovar a inscrição.

A etapa seguinte identifica a ausência do email e encaminha a entrada para correção. Se essa etapa não existir, a falha poderá aparecer apenas quando outro Node tentar enviar a confirmação.

## Teste e produção precisam ser conferidos separadamente O Webhook Node do n8n disponibiliza endereços distintos para teste e produção. Uma chamada que funcionou enquanto você aguardava um evento no editor não comprova que o serviço externo esteja usando a URL de produção ou que a versão correta do workflow esteja publicada. No agendamento, a conferência inclui o fuso horário e a publicação do workflow, conforme a versão do n8n usada no ambiente. Acionar o restante do fluxo manualmente testa o processamento, mas não demonstra que o trigger iniciará a execução no próximo horário previsto. ## Como investigar uma execução que não começou Compare o horário e o identificador do evento na origem com os registros disponíveis no n8n. Verifique o endereço chamado, a resposta recebida pelo remetente e os filtros do trigger antes de concluir que o processamento falhou depois da entrada. Se a origem repetir a entrega, uma nova execução pode começar para a mesma ocorrência. A [deduplicação](/glossario/deduplicacao/) e a [idempotência](/glossario/idempotencia/) ajudam a tratar essa repetição quando enviar duas mensagens ou criar dois cadastros seria um resultado incorreto. ### Túnel de rede: encaminhamento por um caminho intermediário - URL: https://promovaweb.com/glossario/tunel-de-rede - Descrição: Túnel de rede transporta uma comunicação por outro caminho. Entenda encaminhamento SSH, origem, destino, alcance da escuta e limites da criptografia. ## Definição Túnel de rede transporta uma comunicação por outro caminho, usando encapsulamento ou encaminhamento conforme a tecnologia. Ele permite que dois pontos troquem tráfego através de uma conexão intermediária, sem necessariamente publicar o serviço de destino para toda a internet. Tunelamento e criptografia são propriedades diferentes. Um túnel [SSH](/glossario/ssh/) protege o trecho transportado pela conexão SSH, enquanto outras formas de túnel podem não oferecer essa proteção. ## Identificar as duas pontas No encaminhamento local do SSH, um processo escuta em uma porta do seu computador. Quando recebe uma conexão, o cliente encaminha o tráfego pelo canal SSH e o servidor remoto abre a conexão com o destino configurado. Esse destino é interpretado do lado remoto, portanto `127.0.0.1` nessa posição se refere ao loopback do servidor SSH. O endereço usado na escuta local pertence ao computador que executa o cliente.

Você configura um encaminhamento da porta 8080 do seu computador para esse destino. O navegador chega à porta local, e a conexão SSH transporta a comunicação até o servidor que consegue alcançar o painel.

A configuração não publica automaticamente o painel para outros computadores. Ela também não substitui o login que a aplicação exigir ao receber o acesso.

## Ler o encaminhamento antes de usar O comando ilustrativo abaixo exige substituir o usuário e o hostname por valores do seu ambiente. O servidor precisa permitir o encaminhamento, e o painel deve estar atendendo no destino indicado. O primeiro endereço limita a escuta ao loopback local, e `-N` evita abrir um comando remoto. A porta 8080 precisa estar disponível no cliente, e a porta 3000 precisa estar acessível a partir do servidor SSH. Uma conexão SSH estabelecida não comprova que o painel responde. No exemplo, confira a escuta local na porta 8080 e teste o acesso ao painel por esse caminho. Se houver falha, examine também o atendimento na porta 3000 do lado remoto: o encaminhamento pode estar configurado enquanto a aplicação de destino está parada. ## Conferir o alcance do caminho Se o destino estiver em outra máquina além do servidor SSH, a criptografia desse canal não se estende automaticamente ao trecho adicional. A proteção até a aplicação depende também do protocolo utilizado nessa conexão. Ao terminar, confira se o encaminhamento foi encerrado e qual processo ainda mantém a escuta, caso ela permaneça ativa. Conexões compartilhadas ou processos em segundo plano podem ter um ciclo diferente da janela de terminal visível. O [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) pode acompanhar a configuração desse acesso no seu ambiente, verificando origem, destino e alcance da escuta. ### Upload: enviar um arquivo para o servidor - URL: https://promovaweb.com/glossario/upload - Descrição: Upload envia um arquivo do cliente para o servidor. Entenda o envio pelo formulário, o destino do arquivo, os limites e a verificação do conteúdo recebido. ## O que é upload Upload é o envio de um arquivo do cliente para o servidor. Em vez de apenas texto, o usuário envia um documento, uma imagem ou outro conteúdo. O servidor recebe e decide o que fazer com ele. O upload aparece em formulários com arquivos, integrações e envio de mídia. O conteúdo viaja no corpo da requisição até o destino. O destino pode armazenar, processar ou repassar o arquivo. ## Enviar o arquivo O arquivo é enviado pelo formulário, muitas vezes dentro de um [FormData](/glossario/formdata/). O campo de arquivo seleciona o conteúdo, e o envio carrega o arquivo junto com os outros dados. O servidor recebe o corpo da requisição. O destino é definido pelo [endpoint](/glossario/endpoint/) da chamada. O servidor lê o conteúdo e executa a operação correspondente: salvar, processar ou armazenar. O contrato da API define como o envio acontece.

Um formulário atualiza dados de um pet e envia uma imagem. O campo de texto e o arquivo fazem parte do mesmo envio.

O upload carrega a imagem junto com os dados. O servidor armazena o arquivo e associa ao registro. O conteúdo chega ao destino em uma só requisição.

## Verificar o conteúdo recebido O servidor precisa verificar o upload. O tamanho e o tipo do arquivo definem se ele é aceito. Um arquivo grande demais ou inesperado pode ser recusado para proteger a aplicação. A verificação protege contra conteúdo indevido. Um upload sem controle pode introduzir arquivos indesejados. A validação do tamanho, do tipo e do destino reduz o risco da operação. ## Limites e retenção O upload costuma ter limites. O tamanho máximo, o tipo aceito e a quantidade definem o que o servidor aceita. Os limites protegem o armazenamento e o processamento. Depois do envio, o arquivo segue a política de retenção. Pode ser guardado temporariamente ou por tempo definido. A política define por quanto tempo o conteúdo fica disponível e quando é descartado. Para implementar o upload e a verificação do conteúdo na sua aplicação, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação na construção e na proteção do envio. ### URL: localizar recursos pela web - URL: https://promovaweb.com/glossario/url - Descrição: URL localiza um recurso na web. Entenda esquema, host, porta, caminho, consulta e fragmento, além da diferença entre endereços absolutos e relativos. ## O endereço que localiza um recurso URL significa Uniform Resource Locator e identifica como localizar um recurso. Na web, pode apontar para uma página, imagem, arquivo ou operação de API. A URL reúne componentes com funções distintas, e nem todos precisam aparecer explicitamente. Quando você copia um link de busca, ele pode incluir o site, o caminho da pesquisa e o termo consultado. Esses trechos não são apenas uma sequência de palavras. Os separadores permitem que o navegador identifique qual parte representa o destino e qual parte carrega parâmetros. Considere `https://example.com/catalogo?categoria=livros#resultados`. O navegador acessa um recurso do catálogo com um parâmetro de categoria. O fragmento final pode indicar uma seção da página, caso exista um elemento correspondente. ## As partes de uma URL HTTP O esquema `https` indica o mecanismo de acesso. O host `example.com` identifica o servidor pelo nome, embora uma URL também possa usar um endereço IP. Uma porta explícita, como `:8443`, permite indicar um serviço diferente do padrão daquele esquema. O caminho `/catalogo` identifica o recurso dentro desse endereço, sem exigir uma pasta física com esse nome no servidor. A aplicação pode receber esse caminho, consultar os produtos e produzir a página do catálogo a cada chamada. A consulta começa depois de `?` e costuma usar pares de nome e valor. O serviço determina se reconhece `categoria=livros` e como aplica esse parâmetro. Acrescentar um nome arbitrário à URL não cria um filtro automaticamente. O fragmento começa depois de `#` e não é enviado ao servidor na requisição HTTP. Ele pode orientar o navegador ou o código da página. Por isso, colocar um filtro depois de `#` não equivale a enviá-lo como parâmetro de consulta. ## Endereço absoluto e referência relativa Uma URL absoluta informa o destino completo. Uma referência como `/glossario/api/` depende de uma URL base para formar o endereço final. Em uma página comum, ela aponta para esse caminho na mesma origem. Já `imagem.png`, sem barra inicial, é resolvida em relação ao caminho da base. Essa diferença pode explicar uma imagem que funciona na página inicial e falha em uma página interna. O navegador pode estar procurando o arquivo em outro diretório.

Você usa o caminho /catalogo e acrescenta categoria=livros na consulta. A aplicação reconhece o parâmetro e devolve os produtos correspondentes. O fragmento resultados, quando presente, continua sendo interpretado do lado do navegador.

Se o nome documentado for tipo em vez de categoria, o resultado pode vir sem filtro ou a chamada pode ser recusada. A URL pode ser válida e ainda enviar à API um filtro diferente do descrito no exemplo.

## Como montar e conferir um endereço Valores com caracteres especiais precisam ser codificados conforme o componente da URL. Ao programar, use ferramentas como `URL` e `URLSearchParams` para montar a consulta. Concatenar texto manualmente pode transformar um `&` do valor em separador de outro parâmetro. Evite incluir senhas ou tokens na consulta, pois URLs podem aparecer em histórico e registros de acesso. Na investigação, confira o endereço efetivamente enviado na aba Network e compare cada componente com o contrato. O verbete de [origem web](/glossario/origem-web/) explica como esquema, host e porta participam do isolamento entre páginas. ### Uso de computador: agente que opera a interface como uma pessoa - URL: https://promovaweb.com/glossario/uso-de-computador - Descrição: Uso de computador permite que um agente opere a interface como uma pessoa. Entenda navegação, cliques, decisões e os limites de confiabilidade da automação visual. ## O que é uso de computador Uso de computador é a capacidade de um [agente de IA](/glossario/agente-de-ia/) operar uma interface de forma parecida com uma pessoa: abrir aplicações, navegar, clicar e preencher campos. O agente decide o próximo passo a partir do que observa na tela. Essa abordagem é útil quando não existe uma API direta ou quando a tarefa depende da interação visual. Em vez de chamar um endpoint, o agente manipula a interface disponível, como faria um usuário humano. ## Como o agente decide O agente recebe uma representação da interface e escolhe a próxima ação. A decisão considera o objetivo, o estado atual e as ferramentas disponíveis. O [harness](/glossario/harness/) executa a ação escolhida dentro das permissões do ambiente. A interação visual envolve incerteza. A tela pode demorar a carregar, um elemento pode mudar de posição e uma ação pode produzir um resultado inesperado. O agente precisa acompanhar o efeito da própria ação antes de seguir.

Um agente precisa verificar se um cadastro funciona. Sem uma API de teste, ele abre a aplicação, navega até o formulário e preenche os campos seguindo o objetivo.

Se um campo não aparece, o agente precisa decidir como continuar. Acompanhar o resultado de cada passo é parte do trabalho de garantir que a tarefa realmente avançou.

## Confiabilidade e limites A confiabilidade do uso de computador depende da tarefa e da estabilidade da interface. Fluxos simples e previsíveis tendem a funcionar melhor do que fluxos com muitas variações visuais. Quando uma integração estável é possível, a API costuma ser mais confiável do que a automação visual. O uso de computador se destaca nos casos em que a interface é o único caminho disponível. ## Autonomia e aprovação O agente pode operar com autonomia dentro das permissões configuradas. Ações sensíveis podem exigir aprovação humana. A [autonomia do agente](/glossario/autonomia-de-agente/) define quanto ele avança sem supervisão, enquanto a camada de execução aplica os limites. Revisar os passos executados e comparar o resultado com o objetivo ajuda a detectar decisões erradas. Uma automação visual bem acompanhada entrega valor onde a interface é o único ponto de acesso. Para montar e revisar um fluxo com uso de computador no seu projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação durante a navegação e a automação da interface. ### Validação de entrada: condições para valores recebidos - URL: https://promovaweb.com/glossario/validacao-de-entrada - Descrição: Validação de entrada confere valores recebidos pela aplicação. Entenda presença, tipo, formato e limites, com exemplos no formulário e no servidor. ## Conferir o que a aplicação recebe Validação de entrada confere se os valores recebidos têm a presença, o tipo, o formato e os limites exigidos pela aplicação. Um campo de quantidade pode aceitar apenas inteiros positivos, enquanto uma reserva pode exigir que a data final venha depois da inicial. A verificação depende do significado de cada campo e das relações entre eles. Em um cadastro, você pode exigir nome e email. Um campo ausente deve ser tratado de forma diferente de um campo presente com conteúdo incompatível. A resposta precisa orientar a correção conforme o contrato, sem deixar a gravação depender de valores presumidos. As entradas chegam por formulários, APIs, arquivos importados e integrações. Por isso, validar somente a tela deixa outros pontos de entrada sem a mesma verificação. O servidor precisa conferir os valores que utilizará, independentemente de sua origem. ## Sintaxe e significado A validação sintática verifica a forma do valor. Um email pode seguir o formato esperado, e uma quantidade pode ser um número inteiro. Essas conferências não comprovam que o endereço existe ou que aquela quantidade está disponível para a reserva solicitada. A validação semântica considera o significado no produto. Uma reserva pode exigir início anterior ao término e disponibilidade para o período. Um identificador numérico bem formado ainda precisa corresponder a um registro acessível ao perfil autenticado. Autenticação e autorização continuam sendo verificações próprias. Um campo com formato aceito não comprova a identidade apresentada na chamada nem concede permissão para modificar o registro correspondente. ## Um cadastro aceito e outro recusado O código de status e a estrutura do erro dependem do contrato da API. Esse exemplo mostra apenas um corpo possível. A interface não precisa repetir internamente a mesma implementação do servidor, mas deve apresentar uma orientação compatível com o resultado recebido.

No navegador, o formulário informa que o campo está vazio antes do envio. Em outro teste, você chama a API diretamente sem esse campo. O servidor também deve recusar o cadastro, mesmo sem a participação da interface.

Depois, envie um email com formato aceitável. Se a aplicação exige um endereço exclusivo por contato e ele já está cadastrado, a gravação deve ser recusada. O formato aceito permite continuar o processamento, mas não comprova que o endereço está disponível para um novo cadastro.

## Validar não equivale a transformar qualquer conteúdo Uma aplicação pode normalizar um valor antes de validá-lo, como remover espaços externos quando essa transformação é permitida. O contrato precisa informar quais campos recebem esse tratamento e o que será preservado. Alterar silenciosamente um valor pode modificar o significado que você pretendia enviar. Listas de valores aceitos são úteis para campos fechados, como uma situação com opções documentadas. Em campos de texto livre, considere os caracteres legítimos do domínio, inclusive nomes com acentos e pontuação. Uma restrição excessiva pode impedir cadastros válidos. Validação também não substitui consultas parametrizadas no banco ou codificação adequada ao exibir conteúdo. Cada uma dessas medidas trata uma parte do processamento. Aceitar um texto não autoriza inseri-lo diretamente como código ou HTML. ## Entradas aceitas, recusadas e concorrentes Teste um formulário com o campo obrigatório preenchido e depois omitido. Confira também uma quantidade no limite permitido e outra fora dele. Em cada chamada, compare a resposta com o estado persistido, inclusive quando o envio for direto à API. Para atualizações, verifique o tratamento de um campo omitido e de outro enviado como nulo quando o contrato distingue os dois. A exigência de email exclusivo precisa resistir a chamadas simultâneas. Duas consultas iniciais podem encontrar o mesmo endereço disponível e tentar cadastrá-lo em seguida. Uma restrição de unicidade no banco pode impedir a duplicação, e o [backend](/glossario/backend/) precisa tratar a recusa da gravação. ### Variável de ambiente: valores nomeados do processo - URL: https://promovaweb.com/glossario/variavel-de-ambiente - Descrição: Variável de ambiente fornece valores nomeados a um processo. Entenda leitura, arquivos .env, conversão de tipos e o que acontece após alterar um valor. ## Um valor nomeado disponível ao processo Variável de ambiente é um valor associado a um nome no ambiente de um processo. O programa pode ler esse nome para obter configurações como endereço de serviço ou modo de execução. O mecanismo permite fornecer valores sem escrevê-los diretamente na lógica da aplicação. Um processo de desenvolvimento pode receber um endereço local, enquanto outro usa o endereço do serviço de produção. Trocar o endereço muda o destino das chamadas, mas o serviço remoto pode exigir uma credencial ou executar uma versão diferente da API. Por isso, conferir o valor recebido pela aplicação é apenas parte do teste da integração. A aplicação precisa conhecer o nome da variável e interpretar seu conteúdo. Criar `LIMITE_POR_LOTE` não muda um programa que nunca lê esse nome. A documentação deve informar os parâmetros suportados e os valores esperados. ## Fornecimento e leitura Nesse exemplo, a atribuição fornece o valor ao processo Node.js iniciado naquela linha. A saída esperada é `development`. A sintaxe é de shells compatíveis, como Bash e Zsh, e não deve ser copiada sem adaptação para qualquer interpretador. Um processo normalmente recebe uma cópia do ambiente ao iniciar. Mudar o valor em outra sessão ou no shell depois da inicialização não atualiza automaticamente a aplicação já aberta. Reinício ou outro mecanismo explícito pode ser necessário. ## Texto precisa de interpretação Valores de ambiente são normalmente apresentados ao programa como strings. O texto `false` não é o mesmo que o booleano falso, e `50` precisa ser convertido quando a aplicação espera um número. A leitura deve validar tipos, limites e ausência.

O valor esperado é um inteiro positivo. Se a configuração trouxer texto incompatível, a aplicação deve informar o problema ou aplicar um padrão documentado. Usar o valor sem validação pode produzir um comportamento inesperado.

Neste exemplo, a aplicação pode adotar cinquenta itens quando a variável estiver ausente e recusar um valor vazio explicitamente informado. Esse tratamento precisa estar implementado e documentado, pois o mecanismo de variáveis de ambiente não escolhe o padrão nem valida o limite.

## O papel de um arquivo .env Um arquivo `.env` é uma convenção para registrar pares de nome e valor. Ele precisa ser carregado pelo runtime, framework ou ferramenta correspondente. Sua simples presença na pasta não garante que os valores entrarão no ambiente do processo. A sintaxe e a precedência podem variar entre ferramentas. Um valor já fornecido pelo ambiente pode prevalecer sobre o arquivo, conforme o carregador. Consulte o comportamento utilizado no projeto em vez de presumir a mesma precedência para todas as ferramentas. ## Valores públicos, secrets e build Variáveis de ambiente podem conter valores públicos ou sensíveis. O mecanismo não criptografa nem restringe automaticamente o acesso ao conteúdo. Uma ferramenta também pode incorporar certos valores nos arquivos do frontend durante o build, permitindo que visitantes consultem esses valores no navegador. Confira quais nomes são expostos ao navegador e mantenha credenciais privadas fora desse conjunto. Para verificar a configuração, prefira informar presença ou ausência sem imprimir secrets. O verbete de [secret](/glossario/secret/) trata da proteção do valor independentemente de seu mecanismo de entrega. ### Vibe Coding: desenvolvimento orientado por intenção e revisão - URL: https://promovaweb.com/glossario/vibe-coding - Descrição: Vibe Coding usa instruções em linguagem natural para construir software com apoio de IA. Veja a abordagem da Promovaweb, com especificação e revisão. ## Definição O Vibe Coding é um termo usado para descrever a construção de software orientada por instruções em linguagem natural a ferramentas de IA. O uso do nome varia, por isso é importante explicitar a prática apresentada: na Promovaweb, a construção inclui especificação, leitura das alterações e revisão técnica. Você descreve o comportamento desejado e acompanha a implementação proposta pela ferramenta. Você também precisa avaliar as alterações junto aos responsáveis pelo produto e pela manutenção do sistema. ## Orientar uma mudança delimitada Uma instrução útil relaciona a necessidade aos comportamentos esperados e às referências do projeto. Para editar um cadastro, por exemplo, descreva os campos permitidos e o que deve acontecer quando o servidor recusa a alteração. A ferramenta também precisa receber as restrições relevantes da implementação existente. Um componente isolado pode parecer correto e ainda usar uma API incompatível com o [backend](/glossario/backend/) do projeto.

No teste integrado, o servidor recusa a alteração por falta de permissão, mas a tela continua exibindo uma confirmação. A interface foi produzida, porém seu comportamento não corresponde ao resultado da operação.

Você reproduz a recusa e confere como o código interpreta a resposta. O ajuste precisa preservar os campos e informar a falha, conforme a especificação, antes de considerar essa funcionalidade atendida.

## Revisar código e comportamento A [especificação](/glossario/especificacao-spec/) orienta a conferência, mas não comprova sua própria implementação. Leia as alterações relevantes e execute testes que exercitem os efeitos da mudança, incluindo o caminho de erro demonstrado no exemplo. Mudanças menores facilitam relacionar um defeito aos arquivos alterados. Quando a ferramenta amplia o trabalho para partes que não eram necessárias, você também precisa avaliar esse acréscimo, pois ele continuará exigindo manutenção. ## Aprender a investigar o resultado Uma falha pode vir de uma instrução ambígua, de código incorreto ou de uma dependência do ambiente. Repetir a mesma solicitação sem investigar a causa pode produzir alterações sucessivas sem resolver o comportamento observado. A [Formação Vibe Coding](/formacoes/vibe-coding/) acompanha a construção de um sistema de captura de leads, da especificação à publicação e à leitura do uso. Para trabalhar uma dificuldade no seu próprio projeto, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) oferece orientação prática enquanto você opera o editor e o terminal. ### Volume: armazenamento além do ciclo do container - URL: https://promovaweb.com/glossario/volume - Descrição: Volume preserva arquivos além da remoção de um container. Entenda montagem, caminho de gravação, armazenamento local e por que persistência exige backup. ## O que é um volume Volume é um armazenamento gerenciado pelo Docker que pode preservar arquivos além da remoção do container que os utiliza. Ele é associado a um caminho dentro da instância, permitindo que a aplicação leia e grave nesse armazenamento. A persistência depende de usar o volume correto no caminho correto. Criar um volume sem montar o diretório usado pela aplicação não protege o conteúdo que continua sendo gravado na camada local do container. ## O caminho de gravação precisa coincidir Considere uma aplicação configurada para guardar anexos em /app/anexos. Um volume montado em /app/arquivos não recebe automaticamente esses anexos, porque os dois caminhos representam locais diferentes para o processo. Confira a configuração da aplicação e a montagem efetiva na instância. No exemplo, o teste precisa mostrar que um arquivo gravado em /app/anexos chegou ao armazenamento que será preservado na substituição do container. Um nome como anexos-projeto não comprova essa associação nem a permissão de escrita no caminho utilizado.

A instância antiga usa o volume anexos-projeto, enquanto a nova foi configurada com anexos-novo. A aplicação inicia sem mostrar os arquivos anteriores.

Os arquivos podem continuar no primeiro volume. Conferir a associação permite localizar o conteúdo antes de tentar uma restauração ou criar novos registros sobre um armazenamento que não era o destino previsto.

## A montagem muda o conteúdo visível Montar um volume com conteúdo sobre um diretório da imagem torna visíveis os arquivos do volume naquele caminho. Os arquivos que já existiam na imagem podem ficar ocultos pela montagem, sem terem sido apagados da imagem. Um volume novo e vazio pode receber os arquivos existentes no destino conforme o comportamento padrão do Docker. Por isso, encontrar arquivos logo após montar não comprova que você recuperou o armazenamento antigo, e a identidade da montagem precisa ser conferida. ## Local e compartilhado têm alcances diferentes Um volume local fica associado ao armazenamento do host que o fornece. Criar um volume com o mesmo nome em outra máquina não transfere o conteúdo da primeira, e mover a aplicação exige tratar também seus arquivos persistidos. Um driver pode oferecer armazenamento compartilhado ou remoto, conforme a configuração. O acesso pode depender da rede e de permissões no serviço de armazenamento, e a aplicação ainda precisa suportar múltiplas instâncias gravando simultaneamente no mesmo conteúdo. ## Persistência não recupera uma exclusão Uma aplicação com permissão de escrita pode apagar ou alterar arquivos do volume. O armazenamento preserva essas mudanças, inclusive quando foram acidentais, portanto manter o volume não devolve automaticamente uma versão anterior do conteúdo. O [backup](/glossario/backup/) precisa permitir recuperar o que for necessário e ter restauração conferida. Para bancos e outras aplicações que mantêm arquivos em uso, a cópia também precisa respeitar o procedimento de consistência recomendado pelo sistema. ## Como verificar a persistência Em teste, grave um arquivo identificado, confira o volume associado e substitua o container preservando essa montagem. Depois, verifique se o conteúdo reaparece e se a aplicação consegue continuar lendo e gravando no caminho esperado. Confira também as ações de limpeza previstas, pois volumes podem ser removidos explicitamente e alguns volumes anônimos seguem opções de remoção da execução. Para investigar uma montagem ou uma atualização de Docker com orientação ao vivo, consulte o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/). ### Voz: a modalidade que fala e escuta na interação com a IA - URL: https://promovaweb.com/glossario/voz - Descrição: Voz é a modalidade que permite falar e ouvir na interação com a IA. Entenda entrada de fala, resposta falada e o uso em produtos e assistentes. ## O que é a modalidade de voz Voz é a modalidade que permite interagir com a IA falando e ouvindo. O usuário fala para enviar a entrada e ouve a resposta em áudio. O formato aproxima a interação de uma conversa natural. A voz amplia o alcance da IA. Uma resposta que seria lida pode ser ouvida, e uma instrução que seria digitada pode ser falada. A modalidade conversa com o texto e com o áudio, cada um com seu papel. ## Falar e ouvir A entrada falada é captada e processada pelo modelo. A resposta pode ser gerada em texto e convertida em voz ou entregue diretamente em áudio. A conversa continua com novas trocas. A qualidade depende do reconhecimento e da síntese. Uma fala clara tende a ser entendida melhor. Quando a interpretação falha, a confirmação ajuda a corrigir antes que o erro se propague para o resultado.

O usuário fala a tarefa do dia. A IA reconhece a fala, confirma o entendimento e responde em voz com o que foi registrado.

A conversa continua até a tarefa ser entendida corretamente. A confirmação em voz reduz o risco de registrar algo diferente do que foi dito.

## Quando a voz faz sentido A voz agrega quando a interação falada melhora a experiência: mãos ocupadas, leitura de conteúdo longo ou a naturalidade da conversa. Em outros contextos, o texto continua mais adequado. Ambiente e privacidade também importam. Falar em um local ruidoso pode prejudicar o reconhecimento, e conversar em um ambiente público pode expor o conteúdo. A escolha da modalidade considera o contexto de uso. ## Voz e áudio bidirecional A voz pode aparecer em diferentes intensidades. Em um sentido, a IA apenas responde em voz. No [áudio bidirecional](/glossario/audio-bidirecional/), o usuário fala e recebe a resposta em áudio no mesmo fluxo, formando uma conversa contínua. O texto continua sendo o registro confiável. A voz adiciona a interação falada, mas o histórico escrito permite revisar, compartilhar e arquivar o que foi conversado. Para usar a modalidade de voz no seu produto com orientação técnica, o [Desenvolvimento Colaborativo da Dev Side Studio](https://devsidestudio.com/servicos/desenvolvimento-colaborativo/) acompanha a implementação da fala e da resposta em áudio. ### VPN: rede lógica privada sobre outra rede - URL: https://promovaweb.com/glossario/vpn - Descrição: VPN cria conectividade privada sobre uma rede pública. Entenda rotas, túnel completo ou dividido e por que estar conectado não garante acesso a tudo. ## Definição VPN, ou Virtual Private Network, cria conectividade privada sobre outra rede. Em um acesso remoto, ela pode estabelecer um [túnel](/glossario/tunel-de-rede/) para que seu computador alcance recursos internos por um caminho administrado. Implementações de acesso remoto costumam proteger esse caminho com criptografia. A tecnologia e a configuração determinam quais destinos participam da conexão, sem tornar automaticamente todos os dispositivos membros de uma mesma rede local. ## As rotas determinam o tráfego transportado Em um túnel dividido, ou split tunnel, somente os destinos selecionados seguem pela VPN. O restante pode continuar usando a conexão habitual do computador, o que pode ser exatamente o comportamento previsto pela organização. Um túnel completo encaminha a navegação pelo serviço conforme as rotas configuradas. Para conferir o resultado, você precisa considerar as versões de IP e os destinos usados, em vez de concluir que todo tráfego mudou de caminho porque o cliente mostra a conexão ativa. ## DNS e acesso à aplicação Um serviço interno pode depender de um resolvedor [DNS](/glossario/dns/) disponível pela VPN. Ter a rota até o servidor não resolve automaticamente seu nome, assim como resolver o nome não comprova que a conexão será aceita. Também podem existir faixas de endereços sobrepostas entre a rede local e a remota. Nessa situação, o computador pode escolher um caminho diferente do esperado, exigindo conferência das rotas e da organização dos endereços.

O cliente informa conexão ativa, mas a consulta de painel.corp.example.com continua sendo enviada a um resolvedor que desconhece esse nome. O navegador não consegue localizar o serviço para iniciar o acesso.

Você confere qual resolvedor recebeu a consulta e a configuração de DNS fornecida pela VPN. Essa verificação distingue uma falha de resolução de uma recusa de login no painel.

## O túnel tem limites A proteção da VPN se aplica ao trecho que ela transporta. Depois da saída do túnel, protocolos como HTTPS continuam importantes para proteger a comunicação com o serviço, e o operador da VPN não recebe automaticamente o conteúdo de uma conexão HTTPS corretamente protegida. VPN também não concede anonimato nem substitui [autorização](/glossario/autorizacao/). Uma aplicação pode reconhecer seu perfil autenticado e exigir permissões próprias mesmo quando você já alcança sua rede interna. Para organizar acesso remoto e separação entre redes, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) oferece acompanhamento para avaliar a configuração junto à operação dos serviços. ### VPS: servidor virtual com recursos alocados - URL: https://promovaweb.com/glossario/vps - Descrição: VPS é um servidor virtual oferecido por um provedor. Entenda recursos contratados, administração, armazenamento e o que conferir antes de publicar. ## O que é uma VPS VPS significa Virtual Private Server, ou servidor virtual privado. É uma oferta de ambiente virtual com recursos definidos pelo provedor, usada para executar aplicações e serviços com acesso administrativo conforme o contrato. Você recebe um servidor virtual, não a propriedade de uma máquina física exclusiva. A forma de isolamento e a disponibilidade de CPU, memória, armazenamento e rede dependem da tecnologia e da oferta escolhidas. ## Os números do plano precisam de interpretação A quantidade de vCPUs e memória descreve parte da capacidade contratada. O comportamento também depende de limites de disco, tráfego e uso do processador, além de possíveis recursos compartilhados com outras instâncias. Compare essas condições com a aplicação que será executada. Um serviço que grava muitos arquivos pode atingir o limite de armazenamento enquanto ainda possui memória livre, portanto um único número não representa toda a capacidade.

Os novos uploads falham enquanto o consumo de CPU permanece baixo. Ao conferir o volume usado pelo portal, você encontra o espaço ocupado pelos anexos e a falha de gravação registrada pela aplicação. Esses sinais direcionam a investigação ao armazenamento utilizado pelo envio.

A investigação precisa tratar o espaço e sua evolução. Contratar mais CPU, sem mudar a condição do armazenamento, não resolve a falha apresentada nesse caso.

## Administração depende do serviço contratado Em uma VPS não gerenciada, você normalmente configura o sistema e mantém os serviços instalados. Atualizações, controle de acesso e rotina de recuperação precisam estar definidos, além da instalação inicial da aplicação. Uma oferta gerenciada pode incluir parte desse trabalho, mas seu alcance precisa ser confirmado. A existência de suporte do provedor não comprova que ele administra o código, o banco e todas as integrações do projeto. ## Acesso ao servidor e acesso à aplicação O acesso administrativo permite preparar o ambiente, enquanto a aplicação depende de portas, domínio e serviços configurados para o atendimento. Conseguir entrar por SSH não demonstra que o endereço público funciona. Confira a conexão pelo caminho usado na aplicação. Se o site recebe acesso público por um proxy na porta 443, teste o domínio por esse caminho e verifique separadamente a comunicação do proxy com o serviço interno. O banco pode precisar de acesso apenas pela aplicação, sem disponibilizar sua porta na interface pública da VPS. ## Armazenamento e backup têm ciclos próprios Reiniciar, parar e remover uma instância são ações diferentes, com efeitos definidos pelo provedor. O armazenamento pode permanecer associado, ser mantido separado ou ser removido conforme as opções escolhidas. Confira essas condições antes de substituir a VPS e preserve uma recuperação testada fora do cenário de perda previsto. Um backup dependente apenas do mesmo servidor pode ficar indisponível junto com ele. ## Conferir o serviço depois de publicar Observe consumo, espaço livre e comportamento da aplicação depois do [deploy](/glossario/deploy/). Relacione os sintomas aos recursos e dependências envolvidos antes de escolher uma alteração de capacidade. Para acompanhar essa manutenção e revisar mudanças na infraestrutura, o [Conselheiro de Tecnologia da Dev Side Studio](https://devsidestudio.com/servicos/conselheiro-de-tecnologia/) pode apoiar o projeto de forma recorrente. O acompanhamento pode partir do consumo observado e dos testes de recuperação do ambiente. ### Webhook: chamada enviada quando ocorre um evento - URL: https://promovaweb.com/glossario/webhook - Descrição: Webhook envia uma chamada HTTP para avisar sobre um evento ocorrido. Veja como autenticar a origem, confirmar o recebimento e tratar entregas repetidas. ## O que é um webhook Webhook é um mecanismo pelo qual um sistema envia uma chamada HTTP para um endereço configurado para comunicar um [evento](/glossario/evento/). O sistema de destino recebe a mensagem e executa o tratamento previsto para aquela ocorrência, como atualizar uma matrícula depois da confirmação de pagamento. Você configura o endereço de recebimento e informa à origem quais eventos deseja acompanhar. Diferentemente do [polling](/glossario/polling/), a integração não precisa consultar repetidamente se surgiu uma novidade, embora a entrega ainda possa atrasar ou exigir novas tentativas. ## O que a chamada precisa informar A notificação costuma trazer o tipo do evento e informações que identificam o objeto alterado. O contrato do emissor determina se o corpo contém o objeto completo, uma versão resumida ou apenas um identificador que você deverá usar para consultar os detalhes. No exemplo abaixo, os nomes dos campos foram inventados para mostrar essa separação. O identificador `evt-817` representa a ocorrência, enquanto `pag-204` identifica o pagamento relacionado a ela. ```json { "eventoId": "evt-817", "tipo": "pagamento.confirmado", "pagamentoId": "pag-204" } ``` O processamento pode usar o identificador do evento para reconhecer uma segunda entrega e o identificador do pagamento para localizar a matrícula. Essa associação precisa seguir o contrato real da integração, porque os serviços não usam necessariamente esses nomes ou a mesma forma de identificar repetições. ## A origem precisa ser conferida Um endereço público pode receber chamadas de sistemas diferentes do emissor esperado. A integração deve verificar a autenticação ou assinatura documentada pela origem antes de usar a notificação para alterar um cadastro ou liberar um acesso. Quando a assinatura depende do corpo original da chamada, transformar o JSON antes da conferência pode invalidar a verificação. Na Stripe, por exemplo, a conferência usa o corpo bruto recebido. O servidor valida esse conteúdo com o header de assinatura e o segredo associado ao endpoint. ## Confirmar recebimento e concluir o trabalho A resposta HTTP comunica ao emissor como a chamada foi recebida, conforme o contrato da integração. Em um processamento demorado, é comum aceitar a notificação para execução posterior, mas essa resposta não pode ser confundida com a conclusão das ações no sistema de destino. A confirmação enviada antes do registro durável do trabalho cria um intervalo durante o qual uma parada pode deixar a tarefa sem execução. A origem pode considerar a entrega encerrada, por isso a confirmação precisa estar ligada ao registro que permitirá retomar o processamento depois.

A automação recebe o evento e cria a matrícula, mas a resposta HTTP não chega ao emissor. A origem repete a entrega porque não recebeu a confirmação esperada.

A segunda chamada deve reconhecer o evento ou a matrícula já processada. Sem esse tratamento, a tentativa de recuperar a comunicação pode criar outro cadastro para a mesma inscrição.

## Como testar a integração Além da chamada válida, teste uma assinatura inválida, uma segunda entrega da mesma ocorrência e uma falha no serviço usado pelo workflow. Confira a resposta ao emissor e o resultado no destino, pois cada lado mostra uma parte diferente do processamento. No n8n, também confira se a origem usa a URL de produção e se a versão pretendida do workflow está publicada. O sucesso de uma chamada na URL de teste demonstra aquele recebimento, mas não comprova que os eventos futuros chegarão pelo endereço usado em produção. ### Worker: processo que executa as tarefas - URL: https://promovaweb.com/glossario/worker - Descrição: Worker executa tarefas em segundo plano. Veja sua relação com jobs e filas, os limites de concorrência e o que acontece quando o processamento para. ## O que é um worker Worker é um processo ou componente de execução que realiza tarefas, frequentemente em segundo plano. Em um sistema com [fila](/glossario/fila/), ele recebe um [job](/glossario/job/), executa o trabalho correspondente e registra seu resultado conforme o mecanismo da ferramenta. Uma aplicação pode receber a solicitação de uma planilha e deixá-la aguardando enquanto um worker faz a consulta e gera o arquivo. Essa separação permite que o atendimento HTTP termine antes do processamento demorado, desde que exista uma forma de acompanhar e recuperar o resultado depois. ## O trabalho recebido precisa de recursos para executar O worker precisa acessar a fila e os serviços usados pela tarefa. Para gerar uma planilha, isso pode incluir permissão de consulta ao banco e acesso ao local que armazenará o arquivo, além de memória suficiente para o volume processado. Estar ativo como processo não comprova que ele consegue concluir jobs. Um worker pode continuar funcionando enquanto todas as tarefas falham por credencial expirada ou enquanto tenta se conectar a uma fila cujo endereço foi alterado.

A aplicação registra a exportação na fila de relatórios. Um worker configurado para essa fila assume o job, consulta as inscrições e grava o arquivo no armazenamento.

Se o processo estiver consumindo apenas a fila de mensagens, ele pode permanecer ativo sem iniciar a exportação. A configuração da fila consumida precisa corresponder ao destino usado quando o job foi criado.

## Quantidade de workers e concorrência A quantidade de processos e a quantidade de tarefas simultâneas por processo são configurações diferentes. Um worker pode executar vários jobs ao mesmo tempo se a ferramenta oferecer essa capacidade, enquanto vários workers podem compartilhar o trabalho disponível na mesma fila. A [concorrência](/glossario/concorrencia/) adequada depende da tarefa. Quando os jobs passam boa parte do tempo esperando uma API, pode haver espaço para atender outras tarefas durante a espera, mas um processamento intenso de CPU continua limitado pelos recursos disponíveis. Mais workers podem produzir mais chamadas simultâneas aos serviços acessados, conforme as tarefas disponíveis. Se todos consultam o mesmo banco ou a mesma API, você precisa observar as conexões e os limites do destino, pois o aumento pode produzir mais recusas e novas tentativas em vez de reduzir a espera. ## O que acontece quando o processo para Uma tarefa pode ser interrompida por encerramento do processo, perda de conexão ou indisponibilidade da máquina. Algumas filas exigem que o worker sinalize periodicamente que continua processando o job. A ausência desse sinal permite identificar tarefas que precisam de tratamento, conforme o mecanismo e a configuração da ferramenta. No BullMQ, a falta dessa atualização pode levar o job de volta à espera ou encerrá-lo como falho, conforme o limite configurado para ocorrências do evento `stalled`. Isso também pode acontecer quando um processamento intenso ocupa o event loop e impede a atualização, mesmo com o processo ainda ativo. Investigue o motivo da interrupção do acompanhamento antes de atribuí-la ao encerramento do worker. A recuperação também precisa considerar o que já aconteceu no destino. Se o worker enviou uma mensagem e parou antes de registrar a conclusão, a próxima tentativa pode repetir o envio, a menos que o processamento trate esse caso. ## Como acompanhar o processamento Observe quantos jobs começam e terminam, quanto tempo demoram e quais erros se repetem. Compare esses registros com a idade das tarefas na fila, porque uma quantidade pequena de jobs antigos também pode representar trabalho que deixou de avançar. Ao substituir ou reiniciar workers, confira como a ferramenta encerra tarefas em andamento e como as retoma. O teste deve acompanhar um job até o resultado final, incluindo a possibilidade de uma nova tentativa, sem presumir que o processo ativo ou a fila vazia comprovam a conclusão de todos os efeitos. ### Workflow: sequência de uma automação - URL: https://promovaweb.com/glossario/workflow - Descrição: Workflow coordena uma inscrição recebida, a consulta de contato e o envio da confirmação no n8n. Entenda as conexões e falhas entre etapas do fluxo. ## O que é um workflow Workflow é a definição das etapas de um processo, das conexões entre elas e das condições para executar cada parte. No n8n, você monta essa definição com [Nodes](/glossario/node/), que podem receber uma chamada, consultar um serviço, transformar campos ou escolher por qual caminho a automação vai continuar. Imagine um formulário de inscrição que precisa cadastrar um contato e enviar uma confirmação. O workflow descreve como essas tarefas se relacionam, enquanto cada envio do formulário pode iniciar uma [execution](/glossario/execution/) com informações próprias. O desenho permanece disponível para novos envios, mas o resultado de cada execução depende da entrada e dos serviços acessados naquele momento. ## As conexões também representam caminhos alternativos Um workflow pode ultrapassar a sequência linear de receber, processar e enviar. Você pode separar inscrições válidas de formulários incompletos, aguardar uma resposta ou chamar outro workflow que cuida de uma tarefa compartilhada por várias automações. Esses caminhos precisam ter uma finalidade explícita. Se o email estiver ausente, por exemplo, encaminhar a inscrição para correção pode ser o comportamento esperado, enquanto tentar enviar a confirmação com um destinatário vazio apenas transfere a falha para outra etapa.

O formulário envia o nome e o email. Uma etapa verifica os campos e encaminha a inscrição válida para o cadastro, que devolve o identificador do contato criado.

Se faltar o email, outro caminho registra a inscrição incompleta para correção e encerra esse processamento. Esse comportamento depende das condições configuradas, não surge automaticamente porque existe um Node de formulário.

## O formato entre as etapas faz parte do workflow As linhas do editor mostram as conexões, mas a compatibilidade também depende do conteúdo transmitido. Se o cadastro devolve o identificador em `contato.id` e a etapa seguinte procura `id`, a ligação visual pode estar correta enquanto o valor necessário permanece ausente. Você consegue localizar essa diferença comparando a saída de uma etapa com a entrada esperada pela próxima. Faça essa leitura também quando uma consulta não encontrar nenhum registro ou quando uma integração devolver vários resultados, pois essas situações podem mudar quais etapas recebem conteúdo para processar. ## Uma falha posterior não desfaz o que já foi enviado Considere uma execução que criou o contato, mas falhou ao enviar a confirmação. O cadastro continua existindo no serviço externo, e repetir o workflow desde o início pode criar outro contato se a integração não reconhecer a inscrição já processada. A recuperação deve considerar os efeitos concluídos, a possibilidade de repetição e o ponto adequado para retomar. O [tratamento de erros do n8n](https://docs.n8n.io/build/flow-logic/handle-errors-gracefully) permite configurar uma reação à falha, mas essa reação precisa ser planejada junto com o processo que você está automatizando. ## Como conferir o resultado Teste uma inscrição válida, outra incompleta e uma situação na qual o serviço de cadastro esteja indisponível. Em cada execução, confira o caminho percorrido e consulte o destino para saber se o contato foi criado e se a confirmação foi enviada. O status de conclusão informa como a plataforma terminou o fluxo, mas não substitui essa comparação. Uma inscrição encaminhada corretamente para correção pode concluir sua execução sem produzir o mesmo resultado de uma inscrição válida. --- ## Ebooks ### Markdown na Prática - URL: https://promovaweb.com/ebooks - Descrição: Markdown legível para pessoas, revisores e agentes. ## Prefácio A maioria encontra Markdown pela superfície. Aprende a fazer um título com `#`, uma lista com hífens, um link com colchetes e parênteses, e segue achando que já entendeu o assunto. Isso atende ao básico, mas não explica por que essa linguagem continua sendo uma das peças mais úteis da escrita digital. Markdown ganhou espaço porque organiza texto com pouco esforço e preserva o sentido mesmo quando o conteúdo circula entre editores, repositórios, plataformas, áreas técnicas e ferramentas de IA. Essa diferença importa. Quando alguém trata Markdown como truque de formatação, tende a produzir arquivos cheios de marcações corretas e raciocínio confuso. Quando entende Markdown como linguagem de estrutura, escreve documentos mais claros, mais reaproveitáveis e menos presos ao editor da vez. O arquivo sai da condição de bloco de texto decorado e funciona como ponte entre o autor, o leitor e o sistema que processa aquele conteúdo depois. Um bom documento em Markdown costuma durar melhor que um documento bonito preso a um software específico. Ele viaja bem, versiona bem, responde bem à revisão, conversa bem com automação e continua legível mesmo fora do editor original. Em um mundo que depende cada vez mais de documentação viva, base de conhecimento, repositório, conteúdo indexável e instrução para agentes, isso pesa muito. Este ebook foi escrito para você ganhar essa base sem transformar a leitura em manual seco de símbolos. A proposta é mostrar a lógica do Markdown, a anatomia de um documento bem montado e o que separa um arquivo útil de um arquivo apenas formatado. Sair desta leitura enxergando texto técnico como parte da execução cumpre o objetivo. Também há um ponto de fundo: IA lê melhor quando a informação vem estruturada. Agentes conseguem interpretar um documento com headings coerentes, exemplos delimitados, listas bem usadas e links claros com menos ambiguidade do que um texto colado sem forma. Markdown virou uma ponte prática entre escrita humana e processamento por software. ## Introdução Todo sistema sério depende de texto em algum ponto: para explicar arquitetura, registrar escolhas, escrever README, montar onboarding, detalhar requisito e publicar changelog, além de manter handbook e transferir histórico para o próximo mantenedor do projeto. O problema é que boa parte desses textos é escrita em ferramentas que ajudam a editar, mas não ajudam a manter. Quando o conteúdo fica preso demais ao formato visual, ele perde mobilidade. Copiar, revisar, versionar, comparar, automatizar e republicar dá mais trabalho do que deveria. Markdown entrou nesse espaço porque oferece um equilíbrio raro. Ele é leve o suficiente para não atrapalhar a escrita e estruturado o suficiente para organizar leitura, publicação e processamento automático. Um arquivo simples pode virar página web, documentação renderizada, post de blog, base de conhecimento, anotação pessoal, instrução para IA ou material de apoio em produto digital sem exigir uma reconstrução completa a cada mudança de ambiente. Essa versatilidade aparece de verdade quando você entende o papel de cada peça do documento. O título define hierarquia, a lista organiza itens equivalentes e o bloco de código delimita exemplo técnico, cada um cumprindo uma função estrutural que ultrapassa o efeito visual. Ele diz ao leitor e aos sistemas o que aquele trecho é, como participa do conjunto e qual ritmo de leitura precisa apoiar. Quando essa lógica está ausente, o documento degrada com facilidade: surgem headings sem hierarquia, listas usadas por preguiça de desenvolver argumento, links sem explicação, blocos de código jogados no meio da página e arquivos que até parecem organizados, mas não ajudam ninguém a decidir ou entender nada melhor. O problema, nesse caso, está na falta de método ao usar a linguagem. Ao longo deste ebook, vou tratar Markdown como instrumento de clareza. Você vai entender a estrutura de um documento, a função editorial de cada parte e os erros mais comuns que deixam arquivos técnicos piores do que poderiam ser. O ponto é aprender a pensar em estrutura, com a sintaxe ficando em segundo plano. ## O que você vai aprender Ao final desta leitura, você deve conseguir enxergar Markdown como uma linguagem de organização do texto, além de um conjunto de recursos visuais. Esse entendimento eleva a qualidade do que você escreve porque desloca o foco da aparência para a função do documento. Você também vai entender como um arquivo em Markdown se organiza por camadas: frontmatter quando houver, hierarquia de headings, blocos de desenvolvimento, recursos de apoio como listas e tabelas, além de apêndices ou referências de consulta quando a leitura exigir esse suporte. Outra parte importante deste ebook é mostrar quando vale usar cada recurso: nem toda informação merece virar lista, nem todo termo precisa de negrito e nem todo documento precisa de tabela. O bom uso do Markdown depende menos do número de marcações disponíveis e mais da capacidade de escolher a marcação certa para o trabalho certo. Por fim, também vou tratar do papel do Markdown em repositórios, documentação, trabalho distribuído, SEO, GEO e fluxos com IA. Isso importa porque hoje o arquivo não existe apenas para leitura na tela. Ele serve também para sistemas que indexam, renderizam, interpretam e reutilizam esse conteúdo em várias camadas da execução. ## Capítulo 1: o que o Markdown organiza de verdade Markdown costuma ser apresentado como uma linguagem de marcação leve. A definição está correta, mas ainda é curta demais para explicar por que ele segue relevante. A tese é que Markdown encurta a distância entre escrita e estrutura. Você não precisa escolher entre texto legível em modo cru e texto publicável. Consegue os dois ao mesmo tempo. Esse equilíbrio torna a linguagem útil para documentação, software, conteúdo e gestão de conhecimento. Antes do Markdown, muita produção digital dependia de formatos mais pesados, nos quais escrever e formatar eram praticamente a mesma atividade, o que cria uma armadilha: você gasta energia demais na aparência e pouca na organização do pensamento. Quando o texto precisa ser movido para outro ambiente, a dependência do formato original cobra juros. A exportação quebra, a revisão fica ruim, a comparação entre versões perde clareza e a manutenção do conteúdo fica mais cara do que ele merecia. O Markdown separa o essencial do acessório, sem competir com diagramação avançada nem tentar ser suíte editorial completa. Ele oferece uma gramática pequena para estruturar o que mais importa em um documento digital comum: títulos, parágrafos, listas, links, ênfases, citações, imagens, blocos de código e tabelas simples. Em vez de tornar o arquivo dependente de um editor específico, ele cria uma base portátil. ### Portabilidade muda o custo de manutenção A portabilidade muda bastante o custo de manutenção. Um `README.md` continua legível no terminal, no editor, no GitHub e em um site estático. Uma documentação interna pode ser versionada no repositório, revisada em pull request, processada por geradores e usada como referência por agentes. Um artigo pode ser escrito em Markdown e renderizado no blog sem obrigar a área editorial a reescrever tudo em HTML bruto. Esse ganho ultrapassa o conforto de escrita, porque representa redução do custo de circulação. Também existe um ganho cognitivo importante: como o Markdown usa marcações discretas, o autor tende a focar mais na progressão do raciocínio, o que acontece simplesmente porque a linguagem não oferece muita distração. Em vez de pensar em menu, fonte, bloco visual, peso de parágrafo e alinhamento o tempo todo, você pensa em hierarquia, sequência e apoio semântico. A escrita fica mais próxima da ideia. O Markdown combina tão bem com documentação séria porque a documentação boa precisa envelhecer bem: continuar legível depois de vários ciclos de edição e aceitar comparação entre versões, revisão incremental, reorganização e reaproveitamento. Um formato que concentra esforço em estrutura, e não em decoração, tende a resistir melhor a esse tipo de uso. O Markdown estrutura o texto para que ele continue útil em movimento. ### Markdown não é pobreza visual Existe um preconceito recorrente de que Markdown é simples demais para trabalho sério. Essa leitura confunde simplicidade com pobreza. Markdown é simples porque escolhe bem o que não tenta resolver. Ele não quer controlar cada pixel. Ele quer declarar estrutura suficiente para que diferentes sistemas renderizem o conteúdo de forma consistente. Ao abrir mão de controle visual total, o autor ganha mobilidade. Um mesmo arquivo pode ser lido em um terminal, publicado em um site, convertido em PDF, revisado em Git, interpretado por um agente e arquivado em uma base de conhecimento. Quanto mais o documento precisa circular, mais essa mobilidade importa. A aparência pode ser aplicada depois. Um site, um tema ou um componente pode transformar Markdown em uma experiência visual rica. O ponto é que o conteúdo permanece limpo por baixo. Essa separação entre estrutura e apresentação é uma das razões pelas quais Markdown continua relevante para organizações que precisam manter conhecimento vivo. ### O documento precisa servir a alguém Markdown bom começa por utilidade. Você precisa saber para qual leitor o documento será escrito e o que essa pessoa precisa entender. O arquivo será usado para aprender, escolher, executar, revisar ou consultar. Essas respostas orientam a estrutura muito além da lista de marcações disponíveis. Um README precisa ajudar alguém a entender o projeto e começar com segurança, uma especificação precisa registrar a escolha e o limite, um changelog precisa mostrar o que mudou e qual impacto isso tem, um guideline precisa orientar comportamento recorrente e um ebook precisa apoiar leitura contínua. O mesmo Markdown pode servir a todos esses formatos, mas a arquitetura de cada documento muda. Esse é o ponto que muitos iniciantes pulam: eles perguntam qual sintaxe usar sem perguntar qual função o documento precisa cumprir, e a sintaxe vem depois da função. Quando essa ordem fica clara, o Markdown sai da categoria de truque de formatação e entra na categoria de ferramenta de pensamento. ## Capítulo 2: a anatomia de um documento em Markdown Entender a estrutura de um documento vale mais que decorar todos os símbolos da linguagem. Um arquivo bom em Markdown se comporta como arquitetura textual clara, com o documento sabendo onde começa, como se apresenta, como desenvolve a ideia principal e como oferece apoio sem fragmentar a leitura. Muitos projetos começam o documento com frontmatter. Esse bloco aparece entre linhas com `---` e costuma carregar metadados como título, descrição, data, autor, tags, status ou slug. Ele não faz parte do corpo narrativo, mas cumpre uma função operacional forte. Blogs, ebooks, changelogs e coleções de conteúdo usam frontmatter para que o sistema organize publicação, rota, tema, filtros e componentes de interface. Quando existe, ele atua como camada de referência para a plataforma que vai renderizar ou indexar o arquivo. Depois do frontmatter, vem o corpo do documento, e é aqui que a maioria dos erros de estrutura aparece. O autor abre um heading porque quer quebrar visualmente o texto, não porque iniciou uma nova unidade de ideia, ou cria uma lista porque ficou cansado de escrever em prosa, ou espalha subtítulos demais e transforma a leitura em zigue-zague. Em Markdown, a organização precisa responder ao raciocínio, com a sintaxe servindo ao conteúdo em vez do contrário. ### Abertura, desenvolvimento e fechamento Um documento saudável costuma ter uma abertura nítida, um desenvolvimento progressivo e um fechamento coerente: a abertura enquadra o assunto e explica a proposta da leitura, o desenvolvimento distribui o tema em blocos que realmente avançam a compreensão do leitor e o fechamento amarra o que foi discutido, sintetiza implicações ou orienta um próximo passo. Essa lógica vale para ebook, post, README, guideline, especificação e nota técnica, com o formato mudando enquanto a necessidade de progressão permanece. Outro ponto importante é entender a diferença entre estrutura editorial e estrutura operacional. A estrutura editorial organiza a experiência de leitura: introdução, capítulos, seções, exemplos, apêndices. A estrutura operacional organiza o processamento do arquivo: frontmatter, blocos de código, links, tabelas, listas, callouts e outros elementos que a renderização ou a automação interpretam de forma especial. Um documento maduro sabe equilibrar as duas. Pensar no arquivo apenas como texto puro faz você perder a oportunidade de torná-lo mais útil para o sistema. Pensar nele apenas como conteúdo para renderização faz você perder qualidade de leitura. Markdown funciona melhor quando essas duas camadas convivem bem, com o documento legível para humanos e previsível para máquinas. Essa dupla exigência não enfraquece a escrita, e costuma deixá-la mais limpa. ### Frontmatter não deve virar gaveta de qualquer coisa Frontmatter é útil, mas pode virar bagunça quando cada autor adiciona campos sem padrão. Em coleções de conteúdo, isso quebra consistência: um post usa `description`, outro usa `summary`, outro usa `excerpt`, e um ebook registra capa em `cover`, outro em `image`, outro em `thumbnail`. O arquivo ainda abre, mas a plataforma começa a depender de exceções. Por isso, frontmatter precisa de contrato: cada coleção deve declarar quais campos existem, a ordem de cada um, quais são obrigatórios e que tipo de conteúdo aceitam. Esse contrato ajuda humanos e sistemas, porque o autor sabe o que preencher, o validador consegue identificar o erro e a renderização fica mais previsível. Esse cuidado vale muito em projetos com IA: se o agente recebe exemplos inconsistentes, tende a repetir inconsistência, e se o repositório mantém um contrato claro, o agente tem menos espaço para inventar campos. Markdown, nesse caso, funciona como superfície de governança editorial. ### O corpo do documento carrega leitura, não só conteúdo O corpo do documento é onde a escolha editorial aparece: mesmo em documentos técnicos, o leitor precisa de progressão, e juntar blocos corretos ainda é pouco, porque é preciso mostrar como eles se conectam. Um documento sobre instalação, por exemplo, precisa dizer o que será instalado, em qual ambiente, quais pré-requisitos existem, qual comando executa a ação e como verificar se deu certo. Um documento de escolha técnica precisa explicar o problema, as alternativas, a escolha e a consequência. Um README precisa mostrar o que o projeto faz sem despejar instruções na abertura. Essa progressão evita que o leitor fique caçando sentido. Markdown facilita a estrutura, mas a responsabilidade pela ordem continua humana: você precisa pensar no caminho de leitura. ### Modelo não substitui julgamento Modelos ajudam muito quando um projeto precisa publicar vários documentos do mesmo tipo. Um template de README, um roteiro de especificação, um padrão de changelog ou um guia de artigo reduz dúvida inicial e evita que cada autor reinvente a arquitetura do arquivo. Esse ganho é real, e o problema aparece quando o modelo começa a substituir julgamento. Um template deve oferecer pontos de partida, não uma prisão. Se o documento precisa explicar uma escolha complexa, talvez a seção de pontos de atenção tenha que crescer. Se o material é curto, talvez uma tabela prevista no modelo não faça sentido. Se o arquivo serve para agente de IA, talvez precise de comandos, limites e regras de validação mais explícitos do que um texto para leitura humana simples. O bom uso do Markdown combina padrão e leitura crítica: o padrão mantém consistência entre arquivos, e a leitura crítica define o que aquele caso específico exige. Essa combinação é especialmente importante em coleções de conteúdo, porque quando todos os posts, ebooks ou documentos técnicos seguem um contrato mínimo, a plataforma trabalha melhor, e quando cada peça também recebe atenção editorial, o leitor não sente que está diante de material fabricado por molde. Isso vale para empresas pequenas e grandes: em uma estrutura reduzida, o padrão reduz retrabalho, e em uma estrutura maior, reduz divergência entre autores, fornecedores e agentes. O arquivo fica previsível sem perder precisão, e essa previsibilidade favorece a manutenção enquanto a precisão favorece o leitor. Por isso, na hora de adotar qualquer template, vale perguntar que função ele cumpre: ajuda a abrir o documento, organiza metadados, garante campos obrigatórios, protege acessibilidade, facilita publicação ou melhora revisão. Se a resposta for clara, o modelo cumpre função. Se for apenas a repetição de um costume, talvez ele esteja carregando hábito em vez de padrão. ## Capítulo 3: headings, parágrafos e ritmo de leitura Depois de entender a anatomia do documento, entram as duas camadas que mais afetam a leitura no dia a dia: a hierarquia de headings, que dá o esqueleto, e o ritmo da prosa, que define se o texto respira ou cansa. ### Headings são o esqueleto do documento Se eu tivesse que escolher um único ponto de atenção para você que está começando a usar Markdown com mais seriedade, seria a hierarquia de headings. Títulos e subtítulos existem para declarar relações entre blocos de conteúdo, em vez de ajustar o tamanho da letra. Quando essa hierarquia está errada, o leitor sente confusão mesmo sem conseguir nomeá-la. Quando está certa, o texto respira melhor. O `#` indica heading de primeiro nível, o `##` indica o segundo, o `###` indica o terceiro e assim por diante. Em muita implementação, o nível um já é ocupado pelo título do documento ou da página. Por isso, coleções de conteúdo costumam começar o corpo com `##`. O detalhe técnico varia conforme a plataforma, mas a lógica estrutural permanece: cada nível representa uma camada da organização do texto. Não faz sentido pular níveis para ajustar aparência visual. Quando você sai de um `##` para um `####` sem passar pelo `###`, transmite uma estrutura quebrada. O documento pode até renderizar sem falha, mas a leitura fica desalinhada. Ferramentas de acessibilidade, indexação e parsing também tendem a interpretar pior esse tipo de salto. O heading participa da semântica do arquivo, em vez de funcionar como acessório de estilo. ### Headings não são muletas de ritmo Existe ainda um erro mais sutil: usar heading para compensar falta de desenvolvimento. Você escreve um subtítulo para cada microideia e acaba transformando um argumento contínuo em vinte ilhas pequenas, fazendo o leitor sentir fragmentação em vez de progressão. Um bom heading abre uma seção que merece existir como unidade. Se a próxima ideia cabe naturalmente no mesmo fluxo, muitas vezes o certo é seguir em prosa. No caso de documentos longos, os headings também ajudam o leitor a se localizar, funcionando como marcos mentais que permitem escaneabilidade sem sacrificar profundidade. Em um ebook, isso significa dividir o conteúdo em capítulos e subseções que realmente carreguem ângulo. Em um README, significa separar visão geral, instalação, uso, contribuição e licença. Em uma especificação, significa distinguir o histórico inicial, o objetivo, o escopo, os fluxos, as regras e os pontos de atenção. Um bom teste é simples: ler apenas os headings do documento e conferir se a espinha dorsal do raciocínio continua compreensível. Quando a resposta é não, há um problema de arquitetura textual. Headings fortes não substituem o desenvolvimento, mas tornam visível o desenho da leitura. Eles funcionam como esqueleto porque nomeiam as partes do raciocínio. ### Headings também orientam agentes Nos fluxos com IA, headings fortes têm outro efeito: eles orientam a leitura da máquina. Um agente que recebe um documento com seções bem nomeadas consegue localizar regras, exemplos, escolhas e limites com mais precisão. Um agente que recebe texto sem estrutura precisa inferir divisões. Isso não significa escrever apenas para IA. Significa reconhecer que uma boa estrutura serve aos dois lados: o humano escaneia melhor, o agente parseia melhor, o revisor encontra trecho específico e a busca interna indexa com mais precisão. Um único recurso melhora várias camadas do trabalho. Por isso, headings precisam ser específicos: `## Configuração` pode ser suficiente em um README pequeno, mas em um guia maior talvez seja fraco, enquanto `## Configuração do ambiente local` orienta melhor e `## Regras de aceite da nova automação` supera `## Regras`. O heading deve reduzir dúvida, em vez de servir somente para dividir espaço. ### Sumário implícito e manutenção Mesmo quando o documento não tem sumário formal, os headings funcionam como sumário implícito. Eles ajudam o próximo responsável a entender a arquitetura do arquivo. Isso é importante em repositórios, bases de conhecimento e handbooks que serão editados por vários autores. Quando a hierarquia é coerente, a manutenção fica mais fácil: uma nova seção entra no nível certo, um capítulo pode ser movido sem quebrar tudo, um link de âncora fica mais previsível e uma revisão de Markdown consegue apontar problema estrutural com clareza. Já um documento com headings bagunçados costuma piorar a cada edição. Um autor adiciona subtítulo para resolver um problema local, outro cria novo nível para destacar algo, outro pula uma camada para imitar tamanho visual. Em pouco tempo, a estrutura deixa de representar o raciocínio. Corrigir isso depois dá mais trabalho do que escrever bem desde o começo. ### Ritmo: parágrafos, ênfase e transições Depois da hierarquia, entra um aspecto que muita gente subestima: o ritmo. Markdown não escreve por você, e oferece apenas um conjunto de recursos. O modo como você arruma parágrafos, ênfases e transições continua sendo decisivo. Um documento tecnicamente correto pode ser cansativo, duro ou confuso se o autor não souber distribuir o raciocínio. Parágrafo, em Markdown, ainda é parágrafo, o que parece óbvio, mas não é: em textos técnicos, existe a tentação constante de quebrar tudo em blocos minúsculos para parecer escaneável. O problema é que escaneabilidade sem continuidade vira leitura serrilhada, com o leitor pulando de frase em frase sem sentir encadeamento. A boa cadência costuma morar no meio-termo: blocos que respiram, mas mantêm a ideia conectada. O mesmo vale para negrito e itálico: esses recursos servem para sinalizar ênfase, contraste ou vocabulário específico, e quando usados com parcimônia ajudam bastante, enquanto em excesso viram ruído visual. Um arquivo cheio de palavras destacadas comunica insegurança editorial, porque parece que o texto depende de marcação para parecer importante. A ênfase tem função clara ao destacar o que realmente muda a leitura do trecho. ### Sintaxe não corrige parágrafo fraco Markdown não compensa falta de clareza verbal. Se o parágrafo está mal escrito, colocar um termo em negrito não resolve. Se a transição entre duas seções está fraca, abrir um subtítulo novo não corrige a fragilidade. O formato pode apoiar a compreensão, mas não substitui raciocínio bem ordenado. Isso vale para você que escreve documentação, artigo ou livro técnico. A linguagem de marcação é uma moldura, e o argumento ainda precisa se apoiar em conteúdo próprio. Há ainda um benefício importante do Markdown para ritmo de escrita: a simplicidade do arquivo torna revisão mais honesta. Você enxerga melhor quando uma frase está sobrando, quando um bloco está inchado ou quando um parágrafo foi quebrado cedo demais. Em formatos mais visuais, a diagramação às vezes esconde a fraqueza do texto. Em Markdown, o texto aparece mais cru, favorecendo o revisor disposto a trabalhar com rigor. Para construir documentos mais fortes, vale tratar o corpo do arquivo com o mesmo cuidado que normalmente se dá para o conteúdo em si, porque estrutura e prosa cooperam em vez de competir. Quanto melhor o ritmo do documento, menos a sintaxe chama atenção e mais o leitor percebe apenas a clareza do caminho. ### Parágrafo médio é ferramenta de leitura Para ebook, artigo técnico ou documentação explicativa, parágrafos médios costumam funcionar melhor que extremos: blocos longos cansam, e blocos de uma frase repetidos em sequência deixam a leitura picada. O meio-termo desenvolve a ideia sem esmagar o leitor. Isso não segue regra matemática: há momentos de frase isolada e momentos de parágrafo mais longo que apoia uma explicação, e o problema está na repetição automática de um padrão. Documento bem escrito varia ritmo conforme a ideia exige. Markdown facilita esse ajuste porque deixa a estrutura visível. Ao olhar o arquivo cru, você percebe se há listas demais, parágrafos serrilhados ou blocos pesados. Essa leitura prévia à publicação costuma revelar problemas que a renderização bonita esconderia. ### Ênfase deve carregar função Negrito e itálico precisam ter função clara: negrito pode destacar termo central, aviso ou contraste importante, itálico pode indicar palavra estrangeira, nuance ou expressão, e quando tudo parece importante, o leitor não sabe o que é essencial. Um erro comum é destacar o começo de cada parágrafo para simular organização, criando um documento visualmente barulhento. Outro erro é usar negrito para compensar frase fraca, porque a marcação não corrige a frase, e escrever melhor resolve o que o destaque esconde. Documentos usados por IA também perdem qualidade quando há excesso de destaque. A marcação vira ruído quando não representa hierarquia real. O agente pode não se confundir como um humano, mas recebe sinal desnecessário. A estrutura limpa preserva o sinal útil e evita o ruído. ## Capítulo 4: recursos de apoio com função clara Listas, tabelas, citações, links, imagens e blocos de código existem para reforçar a compreensão. Usados sem padrão, viram muleta e enfraquecem o texto. Este capítulo trata de quando cada um ajuda e quando atrapalha. ### Listas, tabelas e blocos de citação Uma das maiores vantagens do Markdown é permitir recursos de apoio com sintaxe leve, e a armadilha é começar a usá-los como muleta. Lista boa organiza informação paralela, lista ruim substitui desenvolvimento que o autor não quis escrever, tabela boa compara elementos que ficariam espalhados em prosa, tabela ruim engessa algo que seria mais claro em texto corrido, bloco de citação bom destaca uma ideia-chave e bloco ruim vira enfeite. As listas funcionam muito bem quando você precisa enxergar itens equivalentes, passos limitados, elementos comparáveis ou agrupamentos claros. Um conjunto de requisitos, uma sequência curta de checagens ou um resumo de itens finais pode ficar melhor em lista do que em parágrafo. O problema aparece quando tudo vira marcador. A leitura perde continuidade e o documento começa a soar como registro de frases soltas. Documentos estratégicos exigem listas usadas com padrão mais rígido. Se a ideia central depende de cenário, implicação e nuance, a prosa costuma ser mais adequada. A lista pode entrar depois, como reforço ou síntese, preservando a densidade do raciocínio. Você entende primeiro e, em seguida, consulta a organização resumida. Essa ordem faz diferença em materiais longos e em conteúdo que precisa ensinar, em vez de apenas enumerar. ### Lista é para equivalência Lista faz sentido quando os itens têm o mesmo peso ou pertencem ao mesmo conjunto. Para listar pré-requisitos, parâmetros, arquivos, campos ou etapas curtas, ela atende bem, mas para desenvolver uma tese, provavelmente a prosa é melhor. Um teste simples é perguntar se os itens poderiam trocar de ordem sem destruir o sentido. Se sim, talvez a lista faça sentido. Se cada item depende do anterior para formar argumento, provavelmente você está quebrando um raciocínio que deveria continuar em parágrafos. Outro cuidado é nomear bem os itens. Lista cheia de termos genéricos obriga o leitor a fazer esforço extra. Quando a lista tem rótulos claros, ela funciona como referência rápida. Quando vira sequência de frases soltas, ela parece rascunho. ### Tabela é para comparação equivalente As tabelas cumprem outro papel. Elas brilham quando há comparação objetiva entre colunas com o mesmo tipo de informação. Sintaxe, elemento, função, erro comum e observação prática, por exemplo, combinam bem com uma tabela. Já temas que dependem de narrativa, julgamento ou gradação sutil costumam ficar duros demais quando comprimidos nesse formato. Em Markdown, a tabela precisa trabalhar a favor da leitura, não contra ela. Tabela ruim é muito comum em documentação. O autor cria colunas demais, textos longos, células que quebram mal e comparação que ninguém consegue escanear. Nesse caso, a tabela perde o motivo de existir. Melhor voltar para prosa ou dividir a informação em blocos menores. Uma boa tabela deve responder rápido: você olha e entende a diferença entre elementos, e se precisa ler cada célula como parágrafo, talvez o formato esteja errado. Markdown facilita tabela simples, mas não faz milagre com comparação mal escolhida. ### Bloco de citação precisa ser raro Blocos de citação também merecem atenção. O símbolo `>` cria uma área destacada que costuma funcionar bem para observações, alertas, princípios ou trechos de forte densidade. Em ebooks e documentações, ele pode ser útil para chamar o leitor de volta ao ponto essencial sem abrir um desvio grande na estrutura. Citação usada como ornamento em todo capítulo perde força, porque o destaque só tem efeito quando é raro. Esses recursos existem para apoiar a compreensão: usá-los para maquiar uma estrutura fraca deixa o documento artificial, e usá-los para tornar visível uma organização que já faz sentido eleva bastante a qualidade do arquivo. Markdown oferece esses instrumentos, e a escolha de quando usá-los continua sendo sua. ### Links, imagens e blocos de código como camadas de referência Pouca coisa mostra tão bem a natureza prática do Markdown quanto os links: um link bem colocado funciona como ponte de referência, indo além de uma simples navegação. Ele diz ao leitor que aquele conceito se liga a outra fonte, que há uma documentação oficial, que existe um aprofundamento ou que aquela escolha se apoia em um documento específico. Em documentação técnica, link bom reduz ambiguidade, em conteúdo público melhora trilha de leitura e em IA ancora a origem. O erro clássico é linkar sem intenção, com a frase recebendo um hiperlink porque talvez seja útil, o que cria ruído. O link deve entrar quando amplia entendimento, apoia afirmação ou orienta continuidade real. Também importa o texto âncora: expressões vagas como clique aqui carregam pouco valor semântico. Um bom texto de link já informa o que existe do outro lado. Com imagens acontece algo parecido. Markdown aceita imagens de forma simples, mas a função delas precisa estar clara. Em documentação, imagem pode mostrar interface, diagrama ou resultado esperado. Em conteúdo editorial, pode servir como pausa visual ou reforço narrativo. O problema aparece quando a imagem entra para compensar falta de explicação. Se a lógica do argumento depende da figura e não do texto, o documento perde autonomia. ### Bloco de código precisa de explicação em volta Blocos de código merecem atenção especial porque são frequentemente mal usados. Em textos técnicos, é muito comum o autor jogar exemplos de comando, JSON, YAML, HTML ou shell sem enquadrar o que aquele trecho faz. Você vê o bloco, mas não entende por que ele está ali, quando usá-lo ou o que observar. Em Markdown, o bloco de código funciona melhor quando entra acompanhado de explicação em volta. Outro detalhe importante é a linguagem informada no fence. Escrever três crases e declarar `bash`, `json`, `yaml`, `ts` ou outra linguagem ajuda renderização, highlight e interpretação da pessoa que consome o conteúdo. Parece detalhe, mas aumenta muito a utilidade prática do trecho. Em documentação viva, esse tipo de cuidado reduz o esforço da pessoa que consulta o arquivo em emergência. No caso de projetos modernos, links, imagens e blocos de código também servem a fluxos automáticos. Um site pode extrair previews, um motor de indexação pode entender melhor a página, uma ferramenta de IA pode usar os exemplos como referência e uma revisão técnica pode avaliar mudanças com mais precisão em pull request. Ou seja, esses elementos ultrapassam a aparência e fortalecem o valor operacional do documento. ### Alt text também é estrutura Imagem em Markdown exige texto alternativo. Muita gente preenche esse campo de qualquer jeito ou deixa vazio. Isso prejudica acessibilidade e enfraquece a leitura por sistemas. O alt text deve descrever a função da imagem, não tentar repetir o arquivo. Um tutorial de interface, por exemplo, pode usar alt text para explicar que a imagem mostra a tela de configuração de integração com o botão de salvar destacado. Um relatório pode dizer que o gráfico compara crescimento de potenciais clientes por canal. Uma capa editorial pode descrever o cenário visual principal. Alt text bom beneficia leitores que usam tecnologia assistiva, melhora interpretação por ferramentas e preserva parte do sentido quando a imagem não carrega. Em documentos que precisam circular, isso é parte da qualidade. ### Links precisam de manutenção Link quebrado envelhece mal. Um documento que aponta para referência inexistente começa a parecer abandonado. Por isso, arquivos importantes precisam de revisão periódica. Links para documentação oficial, páginas internas, imagens, assets e exemplos devem ser testados quando o conteúdo é atualizado. Também vale preferir links específicos. Apontar para a página inicial de uma ferramenta raramente ajuda tanto quanto apontar para a seção exata da documentação. O leitor ganha tempo e o arquivo mostra cuidado. Nos repositórios, links internos devem seguir padrão consistente. Caminho relativo, URL completa, âncora de heading e referência a arquivos precisam ser escolhidos conforme o uso. Essa consistência facilita manutenção, revisão e automação. ### Referência cruzada evita documento isolado Um documento em Markdown raramente deveria viver como ilha: README aponta para guia de contribuição, guia de contribuição aponta para padrão de commit, changelog aponta para release, ebook aponta para próximo passo e especificação aponta para a escolha anterior. Quando esses vínculos são bem feitos, você entende que cada arquivo faz parte de uma arquitetura maior. Referência cruzada cria pontes úteis entre documentos que realmente se completam, em vez de encher o texto de links. Um link para uma política interna faz sentido quando a seção depende daquela regra. Um link para documentação oficial faz sentido quando o leitor pode precisar verificar sintaxe ou comportamento. Um link para outro artigo faz sentido quando amplia a leitura sem interromper a tese principal. Esse cuidado rende muito em bases de conhecimento. Sem referências cruzadas, cada documento precisa repetir explicações básicas para ser compreendido. Com referências bem posicionadas, o arquivo pode manter foco e ainda oferecer caminho para aprofundamento. A leitura fica mais limpa, e a manutenção também. Se uma regra muda, é melhor atualizar uma página canônica e manter links para ela do que espalhar versões parecidas em vários lugares. Também há uma vantagem para agentes. Quando o documento declara onde está a regra principal, onde está o exemplo e onde está a validação, a ferramenta tem mais chance de recuperar o material certo. O Markdown não resolve busca sozinho, mas cria uma rede legível de relações. Essa rede reduz a dependência de conversa informal em todas as pontas: autores, sistemas e revisores. A pergunta útil é se o link reduz ambiguidade: se reduz, ele provavelmente deve entrar, e se o link existe apenas para parecer completo, ele tende a distrair. Referência cruzada deve reforçar confiança, não inflar o documento. ## Capítulo 5: Markdown em repositórios, sites e fluxos com IA Você que olha para Markdown apenas como recurso de anotação pessoal perde a parte mais estratégica da história. Hoje, boa parte da infraestrutura editorial e técnica da internet conversa com arquivos `.md` ou `.mdx` em algum ponto. Isso vale para documentação de produto, coleções de conteúdo, changelog, páginas estáticas, base de conhecimento, prompts estruturados, especificações e materiais usados por agentes. Nos repositórios, Markdown virou quase um idioma padrão. `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `AGENTS.md`, guias internos, RFCs, post-mortems e documentação de arquitetura costumam ser escritos nesse formato porque ele versiona bem. Revisores conseguem analisar linha por linha, comentar mudanças específicas, comparar revisões e manter histórico de escolhas com menos ruído. Esse comportamento é difícil de replicar com a mesma leveza em formatos muito presos a interface gráfica. Sites estáticos e stacks de conteúdo tornam o Markdown ainda mais útil porque separam texto e apresentação. O conteúdo vive como arquivo legível e a camada visual é resolvida pelo framework, pelo tema ou pelo sistema de templates. Isso reduz custo editorial. Você pode reorganizar layout, card, listagem, rota, filtro ou página de detalhe sem reescrever o conteúdo bruto. O texto ganha portabilidade. ### Agentes precisam de documentos parseáveis Quando entram fluxos com IA, esse valor cresce de novo. Agentes trabalham melhor quando a informação é explícita, previsível e parseável. Um arquivo em Markdown com headings fortes, blocos bem delimitados, links claros e estrutura coerente tende a produzir menos ruído do que um texto colado sem forma em um chat ou preso dentro de uma interface fechada. A IA não precisa adivinhar tanto onde começa uma regra, onde termina uma observação ou qual bloco representa exemplo. Isso ajuda inclusive fora da programação: uma área de conteúdo pode usar Markdown para manter bibliotecas de pauta, playbooks e guidelines, uma área comercial pode registrar processos e objeções e uma área operacional pode documentar runbooks. Sempre que o arquivo precisa circular entre autores, sistema, revisão e busca, o Markdown oferece uma base estável. Não porque seja sofisticado, mas porque é simples o suficiente para não atrapalhar. Aprender Markdown hoje ainda faz sentido, menos pela nostalgia do texto cru e mais por ele continuar sendo uma camada de interoperabilidade entre escrita humana, software e automação. Em uma rotina que depende de clareza, isso não é detalhe pequeno. ### README é porta de entrada O `README.md` é um dos documentos mais subestimados em projetos técnicos, porque costuma ser a primeira leitura de um recém-chegado: integrante novo do projeto, cliente técnico, parceiro, agente de IA ou até você mesmo meses depois. Quando o README está fraco, todo mundo começa pior. Um bom README responde rapidamente o que o projeto faz, para qual perfil serve, como rodar, onde estão os arquivos importantes, quais comandos principais existem e quais limites precisam ser conhecidos. Ele abre a porta certa, sem precisar resolver tudo. Também precisa ser mantido, porque README desatualizado é perigoso ao parecer oficial: um comando errado, uma variável antiga ou uma descrição vencida cria perda de tempo. Em projetos com IA, o problema se agrava, já que agentes podem seguir instrução antiga com muita confiança. ### AGENTS e instruções para IA Arquivos de instrução para agentes, como `AGENTS.md`, também se beneficiam de Markdown bem estruturado. Neles, a hierarquia não é apenas conforto de leitura. Ela delimita regras, escopo, prioridades, comandos, proibições e parâmetros de validação. Se esse tipo de documento mistura tudo em parágrafos longos, o agente pode perder instruções importantes. Se usa headings claros, listas específicas e blocos de comando bem delimitados, fica mais fácil para humanos e sistemas seguirem o fluxo. Esse é um bom exemplo de Markdown como interface entre autores e IA. Você escreve a instrução em linguagem humana, mas organiza de forma que a máquina consiga localizar e aplicar. Quando a estrutura melhora, a instrução ganha mais chance de funcionar. ### Instrução para IA precisa de prioridade explícita Um documento para agente de IA não se limita a reunir preferências. Ele precisa declarar prioridade. O que é regra absoluta, o que é convenção do projeto, o que é sugestão e o que depende do tipo de tarefa. Sem essa separação, o agente recebe muitas frases importantes no mesmo nível e pode aplicar uma diretriz secundária com peso central. Markdown ajuda porque permite separar camadas com headings, listas curtas e blocos de comando. Uma seção de regras absolutas pode ficar distante de uma seção de preferências de estilo. Um bloco de validação pode reunir comandos que precisam rodar na hora da entrega. Um trecho de proibição pode ficar em destaque sem se misturar com exemplos. Essa organização também protege o humano. Quando alguém revisa um documento de agente, consegue ver se as instruções estão competindo entre si. Consegue perceber se uma regra técnica invadiu uma regra editorial, se um comando ficou escondido no meio de um parágrafo ou se uma proibição precisa virar item explícito. Um bom arquivo de instrução deve reduzir interpretação livre onde o custo do erro é alto. Se a regra diz para validar Markdown ao final de toda alteração em `.md`, essa regra precisa aparecer com clareza, perto dos comandos e das regras de aceite. Se a regra diz para preservar sigilo de fontes internas, ela não pode ficar perdida em uma observação genérica. O agente segue melhor quando a arquitetura do documento sinaliza importância. Essa é uma das razões para tratar Markdown como parte da execução com IA, porque o arquivo orienta ação em vez de ser apenas lido, e a qualidade da estrutura influencia a qualidade da ação. ### Bases de conhecimento precisam de consistência Markdown também é muito útil para bases de conhecimento, mas o problema é que bases crescem rápido e ficam inconsistentes: um artigo usa um modelo, outro usa outro, links mudam, tags ficam soltas e headings se repetem. O leitor encontra informação, mas não confia na organização. Para evitar isso, a base precisa de padrões. Frontmatter consistente, headings previsíveis, links internos validados, glossário de termos, exemplos bem delimitados e revisão periódica. Markdown facilita tudo isso, mas não governa sozinho. Essa consistência também favorece busca e IA. Um agente consegue responder melhor quando os documentos seguem arquitetura parecida. Uma busca interna funciona melhor quando títulos, descrições e termos estão organizados. A clareza editorial vira infraestrutura de conhecimento. ## Capítulo 6: erros comuns que enfraquecem um documento Depois que você aprende a sintaxe básica, a armadilha muda de lugar: você começa a acreditar que documento bom é documento bem marcado, mas a marcação é superfície. A maioria dos arquivos enfraquece por falta de padrão, e os erros mais comuns costumam vir de excesso, desalinhamento ou improviso estrutural. O primeiro erro é tratar heading como decoração, o que produz arquivos com muitos títulos e pouca progressão. O segundo é usar listas em excesso, como se qualquer ideia ficasse mais clara quando quebrada em tópicos. Em muitos casos, acontece o oposto. A leitura perde fluidez e o texto parece um checklist expandido, incapaz de carregar nuance. Markdown não exige esse tipo de fragmentação, que é uma escolha ruim do autor. Outro erro frequente é esquecer explicação ao redor de links e blocos de código. O documento até contém as referências e os exemplos, mas o leitor não sabe por que eles importam. A página vira um depósito de elementos corretos sem costura narrativa. Esse problema aparece muito em tutoriais apressados e documentações que foram crescendo por acréscimo, sem revisão de arquitetura textual. ### Inconsistência corrói confiança Há também o erro da inconsistência: um capítulo usa frase longa e prosa contínua, o seguinte vira lista, o terceiro abre subtítulos em excesso e o quarto traz bloco de código sem comentário. O arquivo inteiro parece ter sido escrito em humores diferentes, o que é comum em documentos coletivos e exige revisão estrutural justamente por isso. Markdown facilita edição, mas não substitui governança editorial. Talvez o erro mais caro seja ignorar o leitor real. Um documento não existe para provar que o autor conhece sintaxe. Existe para produzir entendimento. Quando o texto é centrado demais no autor e de menos na pessoa que vai consultar, a estrutura tende a falhar. O remédio costuma ser simples: revisar o arquivo perguntando o que o leitor precisa entender primeiro, o que pode vir depois e o que deveria estar em apêndice em vez de disputar espaço no corpo principal. Erros em Markdown raramente são espetaculares e quase sempre silenciosos: o arquivo abre, renderiza e parece aceitável, mas a leitura cansa, a consulta atrasa e a manutenção piora. Você que escreve com atenção para estrutura aprende a perceber esses sinais cedo, e isso melhora muito a qualidade do trabalho. ### Excesso de apêndice também atrapalha Apêndice é útil quando tira do corpo principal uma informação de consulta. Mas apêndice demais pode virar depósito. O autor joga tudo que não conseguiu encaixar no final e chama de referência. O leitor percebe. Um bom apêndice precisa ter função clara. Pode guardar sintaxe, comandos, glossário, tabela de comparação ou exemplo completo. Se o material é essencial para entender a tese, talvez ele pertença ao corpo principal. Se é detalhe de consulta, o apêndice é bom lugar. A distinção tem efeito prático em ebooks técnicos: o corpo carrega o raciocínio, o apêndice oferece consulta rápida, e quando a ordem se inverte, a leitura vira manual, enquanto quando o equilíbrio funciona, o ebook ensina e continua útil depois. ### Validação mecânica não aprova clareza Markdownlint, scripts e validadores são importantes. Eles pegam erro de hierarquia, espaço, lista, bloco de código, heading e outros problemas objetivos. Mas documento sem erro mecânico ainda pode ser ruim. A revisão humana precisa olhar fluidez, utilidade, progressão, excesso de lista, links soltos e exemplos sem explicação, além de conferir se o documento serve ao leitor certo. Um validador pode dizer que a sintaxe está correta, mas não garante que o texto oriente alguém a agir melhor. O ideal é combinar as duas coisas: use ferramenta para garantir padrão e leitura crítica para garantir clareza. Markdown fica melhor quando disciplina mecânica e padrão editorial caminham juntos. ### Dívida editorial aparece em arquivo pequeno Dívida editorial não começa apenas em grandes bases de conhecimento. Ela pode começar em um README curto, em uma nota de release, em um guia de instalação ou em uma especificação de duas páginas. O arquivo parece pequeno demais para receber atenção, então cada pessoa acrescenta uma frase, um link, uma seção, um aviso ou um bloco de código. Depois de alguns ciclos, ninguém sabe direito qual parte ainda vale, qual trecho foi escrito para uma versão antiga e qual comando deveria ser testado na próxima entrega. Markdown torna esse acúmulo visível quando alguém decide olhar: a comparação entre versões mostra as adições, o histórico mostra quando a seção mudou e o arquivo cru revela listas que cresceram sem padrão e headings criados para resolver problemas locais. Essa visibilidade é uma vantagem, mas só vira qualidade quando existe revisão. Sem revisão, o mesmo formato que facilita manutenção também facilita acúmulo desordenado. O sinal mais claro de dívida editorial é a perda de confiança. Você abre o documento e desconfia de cada trecho. O comando ainda funciona, a imagem ainda representa a interface, o link aponta para a política correta, a seção de requisitos fala da entrega atual ou de uma versão passada. Quando você precisa checar tudo por fora, o documento já falhou em sua função principal. Outro sinal aparece quando integrantes diferentes usam o mesmo arquivo de formas incompatíveis: uma usa como guia de execução, outra como histórico, outra como material de onboarding e outra como base para agente. Nenhuma dessas funções é errada, mas um único documento pode não atender todas com a mesma clareza. Às vezes o melhor ajuste é dividir o material: README para entrada, guia técnico para execução, changelog para histórico e instrução própria para IA. Essa divisão não deve ser feita por gosto de organização, e sim quando reduz ambiguidade: um arquivo longo demais pode esconder a informação importante, e vários arquivos curtos demais podem fragmentar a leitura. O que decide é sempre a função. Se o leitor encontra o que precisa com menos esforço e o mantenedor sabe onde atualizar cada padrão, a estrutura está funcionando. Também existe uma dívida criada por excesso de exemplos: exemplos ajudam quando iluminam uma escolha e atrapalham quando viram catálogo desatualizado. Em documentação técnica, é comum guardar comandos antigos por medo de remover algo útil. O resultado é um arquivo que tenta atender todos os casos e não orienta bem nenhum. Markdown facilita manter exemplos, mas cada exemplo precisa justificar presença. Um exemplo sem data, sem finalidade e sem leitura posterior envelhece rápido. Tratar dívida editorial como parte da manutenção muda a relação com o arquivo. Revisar Markdown sai da categoria de tarefa cosmética e entra no cuidado com o histórico do projeto. Você que corrige um heading, remove um link vencido, atualiza um comando ou separa um apêndice está reduzindo custo futuro. Esse trabalho quase nunca aparece em destaque, mas aparece no tempo preservado depois. A maturidade aparece quando a revisão deixa rastros suficientes para a próxima pessoa confiar no arquivo. Um documento pode informar quando foi revisado, qual parte mudou, quais links precisam ser testados, que comandos são referência e que seções pertencem a uma escolha antiga. Esses sinais não precisam transformar a página em relatório burocrático. Eles precisam dar ao leitor a sensação de que existe responsabilidade por trás do texto. Markdown é bom para isso porque aceita pequenas marcas de governança sem esconder a leitura principal. Esse cuidado também impede que a IA trate todo texto como verdade sem prazo. Se o documento informa estado, limite e data, o agente tem mais elementos para ponderar a resposta. Se o arquivo mistura regra vigente, exemplo antigo e observação solta, a ferramenta tende a reutilizar tudo no mesmo nível. A qualidade da informação de entrada pesa no resultado. Por isso, escrever bem em Markdown também é uma forma de reduzir ambiguidade na automação. ## Capítulo 7: planejar a estrutura e manter o conhecimento As duas pontas do ciclo: pensar a arquitetura do arquivo antes do primeiro heading e, depois de publicado, tratar o conjunto de documentos como infraestrutura que a empresa mantém viva. ### A estrutura começa pela pergunta certa Talvez a melhor maneira de usar Markdown seja não começar pela sintaxe. A primeira pergunta deve ser simples: o que este documento precisa fazer, porque essa resposta define quase toda a arquitetura do arquivo. Orientar onboarding exige uma ordem de blocos, registrar uma escolha exige outra, ensinar um conceito muda a progressão e servir como referência de consulta muda a densidade de apoio. Quando essa intenção está clara, você consegue desenhar o esqueleto do documento. Pensa na abertura, nos blocos principais, nos apoios necessários, no fechamento e nos anexos. Esse pequeno trabalho inicial evita dois extremos comuns: a página que começa crua e vai sendo remendada conforme a escrita avança, e a página que começa excessivamente compartimentada porque o autor tentou planejar cada microseção sem entender o que realmente precisava dizer. ### Corpo principal e apêndice Também vale decidir cedo o que pertence ao corpo principal e o que deve ir para apêndice. Em temas técnicos, essa distinção é especialmente útil. O corpo principal pode carregar cenário, conceito, regra, implicação e estrutura do pensamento. O apêndice fica com sintaxe de referência, exemplos curtos, comandos ou quadros de consulta. Isso protege o fluxo do texto sem impedir que o material continue útil na prática. Outra escolha boa é pensar nos headings como perguntas implícitas. O que este capítulo responde e o que esta subseção organiza. Se o título da seção é vago demais, provavelmente a seção também será. Um heading forte costuma surgir de um ângulo editorial claro. Ele nomeia o assunto e enquadra o ponto com que aquele assunto será tratado. Por fim, vale ter claro que escrever em Markdown não significa ser minimalista por estética. Significa criar arquivos que resistam bem ao uso real. Se o documento precisa viver em repositório, receber revisão, virar página, alimentar busca, servir de base para IA e continuar legível daqui a meses, a estrutura precisa ser pensada desde o começo. Essa é a parte mais madura do Markdown: ele te obriga a respeitar a arquitetura do texto. ### Roteiro mental para o primeiro heading Antes de começar, responda a algumas perguntas úteis: para qual leitor o documento será escrito, o que o leitor precisa fazer depois, se o documento será lido inteiro ou consultado por partes, se o arquivo será publicado, versionado, indexado ou usado por agente e que informação deve ficar no corpo ou virar apêndice. Essas respostas evitam estrutura automática: um documento de escolha técnica não deve parecer tutorial, um README não deve parecer artigo e um guia editorial não deve parecer lista de comandos. Cada tipo de arquivo tem uma missão. Depois disso, desenhe a sequência, com abertura, seções principais, exemplos, pontos de atenção, fechamento e consulta. Esse esboço pode ser simples, mas precisa existir. Markdown é leve o suficiente para mudar durante a escrita, mas um esqueleto inicial evita que o arquivo cresça torto. ### Revisão final por camadas Uma revisão boa passa por camadas. Primeiro, leia apenas os headings para conferir se a estrutura faz sentido. Depois, leia a abertura e o fechamento de cada seção para ver se o raciocínio avança. Em seguida, revise listas, tabelas, links e blocos de código para ver se têm função ou estão ali por costume. Por fim, rode o markdownlint e valide os padrões do projeto. Esse processo parece mais longo do que simplesmente publicar, mas evita retrabalho. Documento bom costuma ser consultado várias vezes. Cada hora investida em clareza reduz muitas pequenas perdas de tempo depois. Projetos com IA também se beneficiam dessa revisão. Quanto mais limpo o documento, melhor a chance de uma ferramenta conseguir usar aquela informação corretamente. O benefício não fica limitado ao leitor humano. ### Markdown como infraestrutura de conhecimento Markdown parece pequeno demais para receber esse nome, mas em muitos projetos ele funciona como infraestrutura de conhecimento: README orienta entrada, changelog preserva mudança, guia interno registra regra, spec delimita o que será entregue, ebook organiza tese e documento de agente orienta execução com IA. Todos esses arquivos formam uma camada invisível de coordenação. Quando essa camada é fraca, a empresa depende de conversa oral, registro disperso e improviso. Quando é forte, os leitores encontram resposta com mais autonomia, os agentes recebem instrução melhor e a revisão consegue trabalhar com prova escrita. ### Conhecimento precisa ser versionável Conhecimento importante precisa de histórico. Por que uma regra mudou, quando um comando foi atualizado, qual seção foi removida e qual revisor analisou a política de contribuição. Markdown em repositório responde bem a essas perguntas porque cada alteração pode ser versionada. Isso é útil para engenharia, mas também para marketing, suporte, produto e conteúdo, porque uma base de conhecimento versionada permite entender a evolução da empresa. Evita que documentos críticos sejam sobrescritos sem rastro. Facilita auditoria e revisão. Ferramentas visuais podem ser ótimas para colaboração, mas muitas escondem o histórico fino de mudanças. Markdown no Git não resolve tudo, mas oferece um nível de rastreabilidade muito forte para escolhas que precisam durar. ### Conhecimento precisa ser reutilizável Outro benefício é reaproveitamento: um trecho de documentação pode virar página pública, um guia interno pode alimentar onboarding, uma spec pode orientar teste, um README pode ser resumido por IA para apresentação e um changelog pode abastecer newsletter técnica. Esse reaproveitamento funciona melhor quando a estrutura está limpa. Se o arquivo mistura escolha, tutorial, comentário solto e referência sem organização, reaproveitar vira trabalho manual. Se os blocos estão bem delimitados, a adaptação fica mais simples. Para negócios digitais, isso pesa de verdade, porque produzir conhecimento custa: se cada conteúdo precisa ser refeito do zero para cada canal, o custo sobe. Markdown ajuda a preservar o núcleo estrutural para que a apresentação varie sem destruir o conteúdo. ### Conhecimento precisa ser confiável Documento confiável é documento que indica estado, data, dono, escopo e limite quando isso importa. Markdown não garante esses campos sozinho, mas facilita criá-los. Frontmatter, seção de status, changelog interno, links para fontes e checklist de validação ajudam a manter confiança. Sem isso, o leitor precisa adivinhar se o arquivo ainda vale. Em sistemas com IA, isso pesa mais. Um agente pode usar documento desatualizado como se fosse referência vigente. Por isso, arquivos críticos devem deixar claro quando foram revisados e a que se aplicam. Essa é uma camada de governança que parece detalhe editorial, mas evita escolhas erradas: documento sem estado pode atrapalhar tanto quanto documento ausente. ### Conhecimento precisa de rotina de revisão Documento importante não deve depender de revisão eventual: se ele orienta processo, suporte, produto, publicação ou IA, precisa ter algum tipo de rotina. Pode ser revisão mensal, revisão a cada release, revisão depois de mudança relevante ou revisão quando uma métrica de suporte aponta dúvida recorrente. A frequência varia, e o princípio é o mesmo: conhecimento vivo precisa ser cuidado. Markdown favorece essa rotina porque torna a revisão pequena e rastreável: um parágrafo pode mudar sem redesenhar a página, um heading pode ser renomeado sem mexer em layout, um comando pode ser atualizado com uma comparação clara entre versões e uma tabela pode receber nova linha. Essa granularidade reduz resistência. Revisar deixa de parecer projeto especial e cabe no trabalho normal. Também vale nomear responsáveis, porque um documento sem dono tende a envelhecer em silêncio. O dono não precisa escrever tudo sozinho, mas precisa garantir que o arquivo continua útil. Em uma base técnica, pode ser o responsável pelo módulo. Em um handbook editorial, pode ser o responsável pela governança de conteúdo. Em uma documentação para IA, pode ser o mantenedor das regras de validação. Outro ponto prático é registrar quando uma revisão foi feita e o que mudou. Nem todo documento precisa de changelog interno, mas materiais críticos se beneficiam disso. Um pequeno histórico evita dúvida sobre validade e permite que o próximo mantenedor entenda por que determinada regra existe. Se a mudança for grande, o próprio pull request pode cumprir essa função. O importante é que a evolução não fique invisível. Quando essa rotina existe, Markdown vira registro confiável, e quando não existe, vira arquivo esquecido com aparência oficial. A diferença entre uma coisa e outra está menos na sintaxe e mais na disciplina de manutenção. ## Conclusão O valor do Markdown não está na sintaxe curta. Está em oferecer uma forma simples de deixar o texto mais organizado, mais portável e mais legível sem prender o autor a uma ferramenta específica. A linguagem funciona porque transforma estrutura em algo leve o bastante para caber na rotina e forte o bastante para manter publicação, revisão, documentação e automação. Quando você entende a anatomia de um documento, usa o Markdown com muito mais intenção. O heading vira o esqueleto, o parágrafo vira progressão, e lista, tabela, link, imagem e bloco de código voltam a ser apoio semântico. O arquivo ganha nitidez porque cada peça cumpre a função certa. Esse aprendizado parece simples, mas produz ganho acumulado. Documentos melhores reduzem retrabalho, encurtam onboarding, fortalecem indexação, melhoram a relação com IA e deixam o conhecimento da rotina menos dependente de conversa oral ou de registro disperso. Você que escreve bem em Markdown estrutura informação de um jeito que outros profissionais e outros sistemas conseguem usar. Uma ideia para levar deste ebook: um documento bem estruturado respeita o tempo de leitura dos leitores e facilita a manutenção posterior, e em ambientes digitais isso vale muito. ## Próximo passo Você que trabalha com documentação, conteúdo técnico, produto, software house ou execução apoiada por IA vale transformar Markdown em disciplina, não em hábito improvisado. O melhor início costuma estar nos arquivos que mais circulam: README, guideline, changelog, especificação, handbook ou base de conhecimento. Revise a hierarquia de headings, reduza listas desnecessárias, enquadre melhor links e blocos de código e trate cada documento como parte da infraestrutura de referência do seu trabalho. Para aprofundar essa visão com foco em documentação, clareza operacional e uso de IA em produção, a formação [IA Makers](/planos/ia-makers) é o caminho mais natural dentro da Promovaweb. Ela conversa bem com este tema porque trata software, agentes, estrutura de projeto e escolha técnica como prática contínua, não como demonstração isolada. Antes de encerrar, deixo um apêndice curto, que não substitui o argumento principal do ebook. Serve apenas como referência de consulta para quando você precisar da sintaxe mais comum sem abrir mão da lógica estrutural que acabamos de construir. ## Apêndice: referência de consulta da estrutura ### Uma tabela para consultar o papel de cada bloco | Elemento | Sintaxe básica | Função principal | Erro comum | | --- | --- | --- | --- | | Heading | `## Título` | Declarar hierarquia e abrir uma seção | Pular níveis ou criar subtítulos em excesso | | Parágrafo | Linha em texto corrido | Desenvolver argumento com continuidade | Quebrar cedo demais e serrilhar a leitura | | Lista | `- Item` | Organizar itens paralelos ou checagens | Substituir raciocínio por enumeração | | Link | `[texto](url)` | Conectar referência e aprofundamento | Usar âncora vaga ou link sem função clara | | Imagem | `![alt](arquivo)` | Apoiar visualmente a compreensão | Depender da imagem para explicar o essencial | | Código | ```` ```bash ```` | Mostrar exemplo técnico delimitado | Soltar bloco sem explicação em volta | | Citação | `> Texto` | Destacar princípio, alerta ou observação | Virar enfeite recorrente | | Tabela | Colunas separadas por barras verticais | Comparar informações equivalentes | Forçar narrativa complexa em grade rígida | ### Um exemplo mínimo de documento bem montado ```md --- title: "Exemplo de Documento" description: "Resumo curto do conteúdo." --- ## Introdução Apresente o histórico inicial, a proposta e a utilidade do texto. ## Desenvolvimento Abra seções claras, com headings coerentes e parágrafos que avancem a ideia. ### Apoio pontual Use listas, links, imagens ou código apenas quando melhorarem a compreensão. ## Conclusão Feche o raciocínio e indique o que o leitor deve levar dali. ``` ### Roteiro de revisão do arquivo - A hierarquia dos headings faz sentido sem pular níveis. - O corpo principal está em prosa na maior parte do documento. - As listas realmente organizam informação paralela. - Os links explicam por que apontam para aquele destino. - Os blocos de código têm explicação em volta. - O texto continua legível mesmo fora da renderização final. ## Sobre o autor: Luiz Eduardo Oliveira Fonseca [Luiz Eduardo Oliveira Fonseca](/luizeof), também conhecido como luizeof, é fundador da Promovaweb e da Powertic. Trabalha há mais de 20 anos com desenvolvimento de software e automação de marketing, colabora com o product team do Mautic e atua como embaixador do n8n. Sua atuação combina produto, arquitetura, automação e visão de negócio para ajudar profissionais e empresas a construir sistemas mais claros, úteis e viáveis na prática. --- ## Documentação --- ## Documentação de projetos open source ### Uso da marca por agentes - URL: https://promovaweb.com/docs/brandfy/agentes - Descrição: O setup inclui no `AGENTS.md` um bloco que orienta o uso de `.brandfy/` e `brand/`. Preserve os marcadores porque uma execução posterior atualiza somente esse trecho. Instruções específicas do projeto continuam fora do bloco. ## Dê ao agente uma fonte única O setup inclui no `AGENTS.md` um bloco que orienta o uso de `.brandfy/` e `brand/`. Preserve os marcadores porque uma execução posterior atualiza somente esse trecho. Instruções específicas do projeto continuam fora do bloco. Antes de criar uma peça, o agente deve ler `.brandfy/config.yaml`, `BRAND.md`, o índice e os arquivos ligados ao canal. Para uma arte social, isso inclui os tokens, o logo apropriado e o guia do template. Para um texto, inclui a estratégia, a voz e os exemplos do canal. ## Escreva instruções verificáveis Uma solicitação útil nomeia a entrada, o canal e a saída. A porta de entrada continua sendo `$brandfy`, os nomes abaixo ajudam a explicar qual especialista será acionada internamente: ```text Use $brandfy para preparar um carrossel de Instagram a partir do template aprovado. Leia BRAND.md, brand/README.md e brand/templates/README.md, preserve a zona segura, salve o SVG editável e abra o PNG final em 1080 × 1350. ``` O agente precisa relatar quais arquivos leu, quais arquivos criou, que conferências executou e o que permaneceu pendente. Uma resposta que apenas afirma fidelidade à marca sem apontar o manual e o arquivo resultante não oferece evidência suficiente. ## Preserve ativos aprovados Uma nova execução não deve redesenhar o logo, trocar fontes ou substituir um template aprovado para atender uma peça isolada. Quando a aplicação revela uma limitação do sistema, registre o achado e encaminhe a revisão à skill especialista. Fotografias institucionais dependem de arquivo autorizado. Uma imagem gerada não substitui o retrato oficial de uma pessoa. Toda fonte, ilustração ou elemento externo precisa manter autoria, licença e procedência. ## Confira a exportação O arquivo editável e a exportação cumprem funções diferentes. O SVG permite revisão futura, o PNG mostra como a peça chega ao canal. Peça ao agente para abrir a exportação no tamanho final, testar contraste e confirmar que guias, placeholders e conteúdo reservado foram removidos. ### Assets digitais - URL: https://promovaweb.com/docs/brandfy/ativos-digitais - Descrição: Depois da aprovação da estratégia e da direção visual, `$brandfy` chama as especialistas de produção na ordem necessária. A usuária não precisa executar exportadores ou recompiladores individualmente. ## Produção coordenada Depois da aprovação da estratégia e da direção visual, `$brandfy` chama as especialistas de produção na ordem necessária. A usuária não precisa executar exportadores ou recompiladores individualmente. ## Tipografia `brandfy-tipografia-web` seleciona webfontes licenciadas, registra pesos, fallbacks, hierarquia e CSS. O resultado deve apontar para os arquivos de fonte, a licença e o uso esperado em `BRAND.md`. ## Logo `brandfy-logo` define conceito, símbolo, assinatura, variantes, área livre, tamanho mínimo e usos inadequados. `brandfy-ativos-logo` transforma a versão aprovada em SVG, PNG, favicon, avatar e manifesto, preservando a fonte editável. O agente deve abrir os arquivos exportados e conferir proporção, bordas, transparência, fundo, tamanho mínimo e legibilidade antes da auditoria. ## Tokens e círculo cromático `brandfy-design-tokens` transforma as escolhas visuais em tokens reutilizáveis. Ele produz CSS, JSON e tema Tailwind, além de registrar estados e combinações de contraste. Componentes devem consumir tokens sem copiar valores isolados. A cor de origem não é escolhida por gosto do agente. Ela vem de pesquisa de referência ou de preferência declarada pela responsável pela marca, e é ajustada tecnicamente pelo círculo cromático: um esquema de harmonia (monocromático, análogo, complementar, split-complementar, tríade ou tetrádico) relaciona `primary` e `accent` por distância angular de matiz, não por combinação arbitrária. `CHROMATIC.md`, na raiz do projeto, registra essa origem, o esquema escolhido e a decisão final. ## Templates e aplicações `brandfy-aplicacoes` define quais peças precisam existir, para qual canal, formato e situação. `brandfy-templates-canais` instala modelos editáveis para Instagram, LinkedIn, email e YouTube, com zona segura, campos variáveis, dimensões e exemplos. O manual registra a relação entre cada aplicação, o template, a variante do logo, os tokens e a saída exportada. Isso permite que outro agente retome a produção sem reconstruir a intenção visual. ## Arquivos e fontes O arquivo-fonte é preservado junto das exportações. Assets gerados recebem manifesto, dimensão, formato, licença e origem. A auditoria reprova um pacote quando só existe o PNG final, quando a fonte editável desapareceu ou quando `BRAND.md` aponta para um caminho que não existe. ### Auditoria da marca - URL: https://promovaweb.com/docs/brandfy/auditoria - Descrição: Depois de compilar o manual e gerar os assets, peça ao agente: ## Execute a conferência automatizada Depois de compilar o manual e gerar os assets, peça ao agente: ```text Use $brandfy para auditar a marca, os assets, o manual e as aplicações do projeto. ``` Durante o fluxo, `$brandfy` chama `brandfy-auditoria` e grava o relatório no caminho configurado. O usuário não precisa executar o script interno da especialista. O relatório padrão fica em `.brandfy/audit.md`. Ele separa reprovações, avisos, evidências encontradas e itens que dependem de inspeção humana. A skill não corrige silenciosamente um arquivo aprovado. ## Confronte definição, fonte e aplicação A auditoria compara o que o manual afirma com o arquivo fonte, a exportação e a aplicação observada. Uma paleta pode estar documentada corretamente e ainda falhar quando o template usa um valor antigo. Um PNG pode ter a dimensão prevista e ainda apresentar margem desigual ou transparência incorreta. Abra pelo menos: - as variantes light e dark do logo, - o ícone no tamanho mínimo, - uma peça de cada canal prioritário, - uma página de interface nos dois temas, - o manual em PDF, - um texto produzido com o guia de voz. Também confira a licença das fontes, a procedência de fotografias, o consentimento de imagem e o registro das pesquisas de naming. A busca de nome e domínio continua sendo indicativa. ## Interprete o relatório Uma reprovação impede a publicação do conjunto afetado. Um aviso registra uma correção necessária ou uma melhoria cuja consequência precisa ser avaliada. A inspeção humana deve acrescentar evidência ao relatório em vez de apenas marcar um item como concluído. Depois de corrigir um arquivo, atualize o manifesto quando necessário, recompile o PDF e execute a auditoria outra vez. O resultado está pronto quando o manual, os ativos e as aplicações concordam e as pendências aceitas possuem responsável e motivo. ### BRAND.md em detalhe - URL: https://promovaweb.com/docs/brandfy/brand - Descrição: `BRAND.md` é o guia canônico da marca no projeto consumidor. Ele fica na raiz para ser encontrado por pessoas, agentes, ferramentas de revisão e integrações separadamente do diretório de assets. O arquivo explica o que a marca significa, como deve aparecer, quais escolhas já foram confirmadas e onde estão os arquivos que materializam cada regra. ## Função do arquivo `BRAND.md` é o guia canônico da marca no projeto consumidor. Ele fica na raiz para ser encontrado por pessoas, agentes, ferramentas de revisão e integrações separadamente do diretório de assets. O arquivo explica o que a marca significa, como deve aparecer, quais escolhas já foram confirmadas e onde estão os arquivos que materializam cada regra. `brand/README.md` não substitui `BRAND.md`. Ele é um índice curto para navegar pelos arquivos. Quando uma regra do manual e uma descrição do índice parecerem divergentes, a orquestradora deve corrigir o índice e preservar `BRAND.md` como fonte editorial. ## Como o arquivo é construído `brandfy-setup` cria a estrutura inicial. `brandfy-mvp` preenche o que já está documentado em `MVP.md`. `brandfy-entrevista`, `brandfy-estrategia`, `brandfy-voz`, `brandfy-identidade-visual` e `brandfy-manual` consolidam as respostas confirmadas. As demais especialistas adicionam os links para assets, tokens, templates, licenças e aplicações. Uma nova execução atualiza somente os blocos administrados pelo Brandfy e preserva notas humanas fora deles. O arquivo não deve receber promessas, preferências ou exemplos que não tenham fonte, aprovação ou indicação explícita de hipótese. ## Conteúdo esperado ### Identificação e resumo Registra o nome, o estado da marca, a categoria, a descrição curta, a promessa central e o resumo que permite entender o projeto sem abrir todos os arquivos. ### Estratégia e posicionamento Explica propósito, missão, visão, valores, princípios, público, problema, alternativas, diferenciais, razões para acreditar, posicionamento e critérios usados para comparar escolhas. Quando algo ainda for hipótese, o manual aponta essa condição e liga o item a uma pergunta em `.brandfy/`. ### Personalidade e voz Descreve atributos de personalidade, voz, tons por contexto, vocabulário, mensagens, exemplos de formulações adequadas e limites que devem ser evitados. O texto precisa permitir que outra pessoa produza uma mensagem coerente sem adivinhar a intenção da marca. ### Direção visual Registra conceito, paleta, contraste, tipografia, fotografia, ilustração, iconografia, composição, motion, área livre, tamanho mínimo e variantes de logo. Cada regra aponta para o asset, token ou referência correspondente. ### Aplicações e canais Relaciona as superfícies prioritárias, os templates instalados, as dimensões, as zonas seguras, os formatos de exportação e os usos permitidos. Uma aplicação deve informar qual variante do logo e quais tokens deve usar. ### Governança e manutenção Define responsáveis por aprovação, fontes de verdade, licenças, periodicidade de revisão, forma de propor mudanças e relação entre arquivo-fonte, exportações, manifesto e arquivo arquivado. ### Lacunas e mapa de arquivos Lista perguntas abertas, responsável, próximo passo e impacto da ausência. O mapa de arquivos relaciona cada caminho de `brand/` com sua função, formato, fonte editável e skill responsável pela atualização. ## Como ler o mapa de arquivos O mapa evita que um agente trate uma exportação como fonte. Em geral: | Caminho | Papel | Fonte de atualização | | --- | --- | --- | | `BRAND.md` | Guia completo da marca | `brandfy-manual` e escolhas confirmadas | | `CHROMATIC.md` | Guia de cores: origem, esquema do círculo cromático e decisão | `brandfy-identidade-visual` | | `brand/README.md` | Índice dos assets | `brandfy-manual` | | `brand/strategy.md` | Estratégia detalhada | `brandfy-estrategia` | | `brand/voice.md` | Voz, tons e exemplos | `brandfy-voz` | | `brand/tokens.json` e `brand/global.css` | Tokens de interface | `brandfy-design-tokens` | | `brand/logo/` | Fontes e exportações do logo | `brandfy-logo` e `brandfy-ativos-logo` | | `brand/templates/` | Modelos de canais | `brandfy-templates-canais` | | `brand/brand-guide.pdf` | Manual compilado para leitura | `brandfy-guia-pdf` | | `.brandfy/audit.md` | Relatório da auditoria | `brandfy-auditoria` | O mapa real do projeto pode incluir caminhos adicionais. A orquestradora deve atualizá-lo quando criar um novo asset, registrar a origem e indicar se o arquivo é editável, gerado, arquivado ou apenas uma referência. ## Regras de uso Antes de criar uma peça, leia `BRAND.md`, depois `brand/README.md` e os arquivos ligados ao canal. Use tokens em vez de copiar valores isolados, escolha a variante correta do logo e respeite as licenças. Não altere uma regra aprovada para resolver uma peça específica sem registrar a revisão no manual. Depois de alterar a marca, atualize `BRAND.md`, o índice e o asset relacionado, recompile o manual e deixe a auditoria registrar o novo estado. ### Como o Brandfy organiza uma marca - URL: https://promovaweb.com/docs/brandfy/conceitos - Descrição: O Brandfy separa o material de pesquisa dos arquivos aprovados. Essa separação permite que uma entrevista registre uma hipótese sem apresentá-la no manual como definição final. ## O papel de cada diretório O Brandfy separa o material de pesquisa dos arquivos aprovados. Essa separação permite que uma entrevista registre uma hipótese sem apresentá-la no manual como definição final. | Caminho | Conteúdo | Pode ser publicado | | --- | --- | --- | | `.brandfy/` | Configuração, briefing, entrevistas, evidências, relatórios e trabalho em andamento | Não, salvo escolha explícita do responsável | | `brand/` | Manual, logos, fontes, tokens, templates e arquivos finais | Sim, depois da auditoria | | `.agents/skills/brandfy-*/` | Método, referências, scripts e arquivos-base instalados | Não como parte da marca | O caminho de saída é configurável em `.brandfy/config.yaml`, embora `brand/` seja o padrão e o formato esperado pelas skills. Uma mudança de diretório precisa ser refletida nos comandos, links e relatórios. ## As camadas da informação Uma entrevista de marca mistura lembranças, preferências e afirmações comprovadas. O Brandfy registra cada uma na camada adequada: - **Fato:** afirmação confirmada por uma fonte identificada. - **Evidência:** arquivo, pesquisa, relato ou comportamento que fundamenta uma afirmação. - **Interpretação:** leitura construída a partir de fatos informados. - **Hipótese:** explicação que ainda precisa de teste. - **Preferência:** gosto ou direção desejada, com seu motivo. - **Escolha aprovada:** definição aceita por um responsável identificado. - **Pendência:** pergunta ou trabalho que continua aberto. Essa classificação aparece no JSON da entrevista, nos relatórios e no raciocínio das skills. Uma preferência visual pode orientar as rotas apresentadas, mas não deve ser descrita como preferência comprovada do público sem pesquisa. ## As quatro fases O fluxo completo percorre descoberta, definição, desenvolvimento e publicação. Cada fase produz uma fonte que a próxima consegue ler. Na descoberta, a entrevista e o diagnóstico registram o que existe, o que foi dito e onde há conflito. Na definição, estratégia, naming, slogan e voz explicam a marca em linguagem verificável. O desenvolvimento transforma essas definições em sistema visual e ativos. A publicação compila o manual e confere os arquivos com a auditoria. ## As skills como especialistas `$brandfy` é a única skill que o usuário precisa chamar. Ela coordena o percurso, escolhe as especialistas internas conforme o estado do projeto e retoma o trabalho depois que cada etapa produz os arquivos esperados. Entre essas especialistas estão `brandfy-setup`, `brandfy-mvp`, `brandfy-entrevista`, `brandfy-estrategia`, `brandfy-identidade-visual`, `brandfy-design-tokens`, `brandfy-manual` e `brandfy-auditoria`. As demais skills não formam uma segunda interface pública. Elas são partes do fluxo orquestrado e podem ser atualizadas pelo CLI sem exigir que o usuário conheça seus scripts ou seus caminhos internos. Cada skill precisa informar a fonte consultada, o arquivo alterado, a conferência executada e o que permaneceu aberto. O relatório final deve permitir que outro agente retome o trabalho sem inferir o estado anterior. ### Descoberta e contexto - URL: https://promovaweb.com/docs/brandfy/descoberta - Descrição: Ao iniciar o percurso, `$brandfy` lê a configuração, `BRAND.md`, o índice, os assets existentes e o estado em `.brandfy/`. Se houver `MVP.md` na raiz, `brandfy-mvp` transforma o conteúdo em contexto estruturado antes de abrir qualquer nova pergunta. ## O Brandfy começa pelo que já existe Ao iniciar o percurso, `$brandfy` lê a configuração, `BRAND.md`, o índice, os assets existentes e o estado em `.brandfy/`. Se houver `MVP.md` na raiz, `brandfy-mvp` transforma o conteúdo em contexto estruturado antes de abrir qualquer nova pergunta. Essa ordem evita repetir respostas e permite que a entrevista seja usada para completar somente o que o MVP não registrou. O documento do MVP não é editado, as conclusões para a marca ficam em `.brandfy/mvp-context.json`, no briefing e nos briefs de assets. ## O que a entrevista cobre `brandfy-entrevista` conduz a conversa complementar sobre: - nome, estado da marca e categoria, - público, personas, problema, alternativas e resultado desejado, - oferta, modelo de negócio, jornada, canais e operação, - posicionamento, promessa, diferenças, provas e objeções, - personalidade, voz, tom, vocabulário e exemplos, - direção visual, aplicações, logo, tipografia, imagens e acessibilidade, - licenças, responsáveis, aprovação, prazo e revisão. Cada resposta recebe fonte, participante, estado e confirmação. O resumo da entrevista permite retomar o trabalho sem transformar uma hipótese em regra. ## O diagnóstico Depois da descoberta, `brandfy-diagnostico` compara o relato com os arquivos reais. Ele identifica logos duplicados, tokens sem fonte, fontes sem licença, aplicações incompatíveis, links quebrados, documentos desatualizados e assets que o manual promete mas não entrega. O relatório não substitui a conversa. Ele organiza as perguntas e mostra qual arquivo ou uso motivou cada recomendação. ## Passagem para a estratégia Quando o contexto estiver confirmado, `brandfy-estrategia` organiza propósito, posicionamento, promessa, diferenciais, princípios e personalidade. A partir daí, a orquestradora chama naming, slogan, voz e identidade visual conforme as lacunas e o escopo aprovados. ### Instalação do Brandfy - URL: https://promovaweb.com/docs/brandfy/instalacao - Descrição: O projeto consumidor precisa ter uma raiz definida, permissão para criar ou atualizar arquivos e um `AGENTS.md` que possa receber o bloco gerenciado do Brandfy. O CLI e as skills usam Node.js 22.20 ou posterior. ## Requisitos O projeto consumidor precisa ter uma raiz definida, permissão para criar ou atualizar arquivos e um `AGENTS.md` que possa receber o bloco gerenciado do Brandfy. O CLI e as skills usam Node.js 22.20 ou posterior. ImageMagick, Pandoc e WeasyPrint são necessários somente quando o percurso chegar a exportações raster, ao manual em PDF ou a algum asset que dependa deles. O diagnóstico informa a dependência ausente quando ela for necessária. ## Os três comandos públicos Instale o CLI uma vez: ```bash npm install --global @promovaweb/brandfy ``` Depois, na raiz do projeto que receberá a marca: ```bash brandfy install . ``` O `install` instala todas as 19 skills, prepara `.brandfy/`, cria ou confere `BRAND.md`, deixa `brand/README.md` como índice, cria os diretórios esperados e atualiza o bloco do `AGENTS.md`. A conversa de marca começa depois disso com a skill `$brandfy`. Quando uma nova versão do Brandfy for publicada, use: ```bash brandfy update ``` O `update` atualiza as skills, reaplica a estrutura gerenciada sem substituir conteúdo autoral e executa a verificação do setup. Para conferir a instalação e os arquivos: ```bash brandfy doctor ``` O diagnóstico confere Node.js, as 19 skills, `skills-lock.json`, `.brandfy/config.yaml`, `BRAND.md`, `brand/README.md` e o bloco do `AGENTS.md`. Ele também informa se `MVP.md` foi encontrado na raiz. A ausência do MVP é aceita porque a entrada é opcional. ## Depois da instalação Não execute scripts das skills e não use o gerenciador `skills` diretamente. A skill `$brandfy` lê o estado, conversa sobre as lacunas e chama `brandfy-setup`, `brandfy-mvp` e todas as especialistas necessárias. O capítulo [Skills do Brandfy](/docs/brandfy/skills) explica cada especialista. O capítulo [BRAND.md em detalhe](/docs/brandfy/brand) explica o manual e o mapa de arquivos que a orquestradora mantém. ### Guia completo do usuário - URL: https://promovaweb.com/docs/brandfy/introducao - Descrição: Uma marca costuma começar com material espalhado: um logo usado no site, cores copiadas de apresentações, fontes escolhidas por hábito e explicações que somente uma parte da empresa conhece. O Brandfy reúne esse material, conduz as definições que ainda faltam e grava um sistema que pessoas e agentes conseguem consultar antes de criar uma nova peça. Uma marca costuma começar com material espalhado: um logo usado no site, cores copiadas de apresentações, fontes escolhidas por hábito e explicações que somente uma parte da empresa conhece. O Brandfy reúne esse material, conduz as definições que ainda faltam e grava um sistema que pessoas e agentes conseguem consultar antes de criar uma nova peça. O Brandfy é uma biblioteca de skills para agentes. Ele não substitui a conversa com os responsáveis pela marca, a pesquisa jurídica nem a revisão de um designer. As skills ajudam a registrar evidências, comparar alternativas, produzir arquivos repetíveis e mostrar o que ainda precisa de aprovação humana. ## Leia online ou como parte do guia portátil Este percurso forma o PDF e o EPUB do Brandfy. Os arquivos Markdown em `docs/user/` são a fonte editorial, por isso uma correção feita aqui entra nas duas edições no próximo build. A referência técnica permanece disponível online em `docs/develop/` e não entra nesses artefatos. - O PDF preserva a diagramação e funciona bem para leitura, compartilhamento e impressão. - O EPUB permite ajustar a fonte e o tamanho em leitores digitais. Baixe o [PDF do guia do usuário](https://github.com/promovaweb/brandfy/blob/main/ebooks/Brandfy-Guia-do-Usuario-v1.3.1.pdf) ou o [EPUB do guia do usuário](https://github.com/promovaweb/brandfy/blob/main/ebooks/Brandfy-Guia-do-Usuario-v1.3.1.epub). A [pasta dos ebooks](https://github.com/promovaweb/brandfy/blob/main/ebooks/README.md) registra a edição vigente e os hashes dos artefatos. ## Percurso recomendado Comece pela [instalação](/docs/brandfy/instalacao) e confirme o estado com `brandfy doctor`. Depois, leia [como o Brandfy organiza os arquivos](/docs/brandfy/conceitos), [o guia de `BRAND.md`](/docs/brandfy/brand) e [o papel de cada skill](/docs/brandfy/skills). Essa ordem ajuda a separar `.brandfy/`, `BRAND.md` e a pasta pública `brand/`. O trabalho completo segue esta sequência: 1. [Instale e confira o CLI](/docs/brandfy/instalacao). 2. [Entenda os arquivos e as camadas de informação](/docs/brandfy/conceitos). 3. [Leia o guia de `BRAND.md`](/docs/brandfy/brand) e [o papel de cada skill](/docs/brandfy/skills). 4. [Prepare o projeto consumidor](/docs/brandfy/primeira-marca). 5. [Conduza a entrevista e o diagnóstico](/docs/brandfy/descoberta). 6. [Construa ou revise o sistema de marca](/docs/brandfy/sistema-de-marca). 7. [Gere logos, tokens, webfontes e templates](/docs/brandfy/ativos-digitais). 8. [Compile o manual e o PDF da marca](/docs/brandfy/manual-e-pdf). 9. [Audite os arquivos antes de publicar](/docs/brandfy/auditoria). 10. [Oriente outros agentes a usar a marca](/docs/brandfy/agentes). 11. [Investigue falhas conhecidas](/docs/brandfy/solucao-de-problemas). Uma marca existente pode começar pelo diagnóstico e preservar tudo o que já possui evidência de uso e aprovação. Uma marca nova precisa de entrevista antes da direção verbal e visual, pois o agente não deve completar uma lacuna com uma resposta apenas plausível. ## O resultado no repositório Ao final, o projeto consumidor mantém a origem do trabalho em `.brandfy/` e os arquivos utilizáveis em `brand/`. Um conjunto completo pode conter estratégia, voz, logos vetoriais e raster, favicons, paleta, tokens CSS e JSON, tema Tailwind, webfontes, templates, regras de acessibilidade, licenças, manifesto e manual em PDF. O relatório `.brandfy/audit.md` fecha o percurso ao confrontar o manual com os arquivos produzidos. A aprovação automática não dispensa a abertura do PDF, dos logos e de pelo menos uma aplicação de cada canal no tamanho final. ### Manual e PDF da marca - URL: https://promovaweb.com/docs/brandfy/manual-e-pdf - Descrição: `brandfy-manual` consolida as definições confirmadas em `BRAND.md` e atualiza `brand/README.md` como índice. O manual reúne estratégia, posicionamento, voz, direção visual, aplicações, governança, lacunas e mapa dos arquivos. ## O manual editável `brandfy-manual` consolida as definições confirmadas em `BRAND.md` e atualiza `brand/README.md` como índice. O manual reúne estratégia, posicionamento, voz, direção visual, aplicações, governança, lacunas e mapa dos arquivos. `BRAND.md` é a fonte editorial. O PDF não deve ser corrigido diretamente, e o índice não deve repetir o manual inteiro. ## O PDF do projeto consumidor Quando o manual e os assets estiverem prontos, `$brandfy` chama `brandfy-guia-pdf`. A especialista instala ou confere o kit de PDF em `brand/pdf/`, sem substituir personalizações existentes, e compila `brand/brand-guide.pdf` a partir de `BRAND.md`. O PDF usa A4, capa clara, Manrope nos títulos, Inter no corpo, sumário, tabelas, blocos de código, paginação e links internos. O design system global fica em `brand/pdf/` e inclui as licenças das fontes. ## O que conferir na leitura Abra o PDF depois da compilação e confira: - capa, nome, descrição, logo e edição, - sumário e hierarquia dos capítulos, - quebras de página, tabelas, imagens e blocos de código, - variantes do logo, contraste, fontes e licenças, - URLs, rodapé, cabeçalho e propriedades do documento, - correspondência entre o texto do PDF e `BRAND.md`. O PDF do Brandfy em `ebooks/` é outro produto: ele contém somente o guia do usuário do framework. `brand/brand-guide.pdf` é o manual da marca do projeto consumidor. ### Primeira marca com o Brandfy - URL: https://promovaweb.com/docs/brandfy/primeira-marca - Descrição: Depois de executar `brandfy install .`, abra o projeto no agente escolhido e converse com `$brandfy`. A orquestradora chama `brandfy-setup` antes de qualquer definição e confere a raiz, o `AGENTS.md`, `.brandfy/`, `BRAND.md`, `brand/README.md` e a estrutura de assets. ## Prepare o projeto Depois de executar `brandfy install .`, abra o projeto no agente escolhido e converse com `$brandfy`. A orquestradora chama `brandfy-setup` antes de qualquer definição e confere a raiz, o `AGENTS.md`, `.brandfy/`, `BRAND.md`, `brand/README.md` e a estrutura de assets. O setup preserva instruções fora do bloco gerenciado. Em um projeto antigo, migra o conteúdo que ainda estiver em `brand/README.md` para `BRAND.md` e mantém uma cópia no arquivo de arquivo quando necessário. ## A entrada do projeto Se `MVP.md` existir na raiz, `$brandfy` chama `brandfy-mvp` antes da entrevista. Essa especialista lê o documento gerado pelo MVPFy, mantém o arquivo intacto, responde as perguntas já cobertas e registra as lacunas que ainda dependem de uma pessoa. Se `MVP.md` não existir, a orquestradora chama `brandfy-entrevista` para descobrir o negócio, o público, a oferta, o problema, a diferença pretendida, as provas, a personalidade, as aplicações e as restrições de uso. Uma marca existente passa primeiro por `brandfy-diagnostico`. Ele confronta o manual e os assets atuais com o contexto confirmado e indica o que deve ser preservado, corrigido ou criado. ## O que precisa de confirmação A usuária confirma nome, público, promessa, posicionamento, alternativas, personalidade, voz, direção visual, aplicações prioritárias, licenças e responsáveis por aprovação. O Brandfy não completa uma lacuna com uma resposta apenas plausível. Quando uma resposta ainda estiver aberta, `$brandfy` registra a pergunta, mostra três caminhos quando a escolha for editorial e aguarda a confirmação antes de avançar para a próxima especialista. ## O primeiro resultado O primeiro percurso não entrega apenas uma pasta vazia. Ele deixa uma base consultável em `.brandfy/`, um `BRAND.md` com as definições confirmadas e um `brand/README.md` que aponta para os assets e documentos. As especialistas seguintes completam estratégia, voz, direção visual, logos, tokens, templates, manual e auditoria conforme o escopo. ### Construção do sistema de marca - URL: https://promovaweb.com/docs/brandfy/sistema-de-marca - Descrição: Peça a coordenação das etapas quando a marca ainda precisa de base verbal, direção visual e arquivos: ## Use o fluxo completo Peça a coordenação das etapas quando a marca ainda precisa de base verbal, direção visual e arquivos: ```text Use $brandfy para construir ou revisar a marca completa a partir do contexto disponível no projeto. ``` `$brandfy` começa pelo setup. Se encontrar `MVP.md` na raiz, importa esse arquivo antes da entrevista. Depois, encaminha a estratégia, o naming quando necessário, o slogan, a voz, a identidade visual, a tipografia, o logo, os ativos, os tokens, as aplicações, o manual, o PDF e a auditoria. Uma marca existente pode saltar uma etapa quando o diagnóstico aponta a fonte aprovada e o uso atual. O arquivo preservado continua sujeito à conferência de licença, acessibilidade e coerência com o restante do sistema. ## Estratégia, naming e slogan `brandfy-estrategia` conecta público, necessidade, alternativas, promessa, diferença, provas e comportamento. Missão e promessa precisam refletir a capacidade atual. A visão pode apontar uma ambição futura, desde que não seja apresentada como estado já alcançado. `brandfy-naming` explora territórios diferentes e registra buscas indicativas de grafia, fonética, domínio, perfis sociais e marcas relacionadas. Essa pesquisa não substitui um parecer de propriedade intelectual nem permite prever o exame do INPI. O trabalho com uma opção que apresente conflito deve parar até a análise adequada. `brandfy-slogan` testa entendimento, verdade, pronúncia, uso junto ao logo e vida útil. A ausência de uma frase adequada é um resultado aceitável, um slogan fraco não deve ser mantido apenas para preencher o lockup. ## Voz e tom `brandfy-voz` documenta como a marca explica, orienta, vende, cobra e reage a uma falha. Cada princípio registra intenção, mecanismo, limite, exemplo, contraexemplo e evidência. O tom muda conforme a situação, mas a relação com o leitor e a promessa permanecem reconhecíveis. O arquivo `brand/voice.md` precisa ser específico o bastante para orientar uma página, um email, uma mensagem de suporte e um texto de interface. Quando dois redatores aplicam a regra de formas incompatíveis, faltam mecanismos ou exemplos. ## Identidade visual e logo `brandfy-identidade-visual` traduz atributos em princípios de composição, cor, tipografia, fotografia, iconografia e motion. As rotas precisam diferir em estrutura, trazer vantagens e limitações e aparecer em mais de uma aplicação. `brandfy-logo` desenvolve o sistema aprovado, com símbolo, wordmark e lockups necessários. O SVG mestre deve usar formas vetoriais, `viewBox` e nomes previsíveis, a partir de arquivos vetoriais e fontes licenciadas. A seleção considera redução, uma cor, impressão, avatar, favicon, fundos claros e escuros. ## Gates de aprovação O fluxo interrompe a passagem para o visual quando nome, público, promessa ou restrições de uso continuam contraditórios. Em cada marco, o responsável deve conseguir explicar a alternativa escolhida, a evidência usada, a limitação aceita e o arquivo que registra a aprovação. ### Skills do Brandfy - URL: https://promovaweb.com/docs/brandfy/skills - Descrição: A usuária conversa somente com `$brandfy`. Essa skill lê o estado do projeto, identifica a próxima etapa e chama as especialistas instaladas sem expor scripts, argumentos ou uma sequência manual de comandos. ## Uma única conversa A usuária conversa somente com `$brandfy`. Essa skill lê o estado do projeto, identifica a próxima etapa e chama as especialistas instaladas sem expor scripts, argumentos ou uma sequência manual de comandos. As 19 skills formam um sistema coordenado. Cada uma possui uma responsabilidade própria, mas a usuária não precisa escolher entre elas. O resultado de uma etapa alimenta a próxima em `.brandfy/`, `BRAND.md` e `brand/`. ## Orquestração e preparação ### `brandfy` É a porta de entrada do produto. Coordena leitura do projeto, importação do MVP, perguntas complementares, estratégia, voz, identidade visual, produção de assets, manual, PDF e auditoria. Retoma o estado existente e não repete uma etapa já confirmada sem motivo registrado. ### `brandfy-setup` Confere a consistência da raiz do projeto antes do trabalho. Cria ou atualiza `.brandfy/config.yaml`, prepara diretórios, cria `BRAND.md`, deixa `brand/README.md` como índice e mantém o bloco gerenciado no `AGENTS.md`. Também migra um manual legado de `brand/README.md` para `BRAND.md` sem apagar o conteúdo aprovado. ### `brandfy-mvp` Lê `MVP.md` somente quando ele existe na raiz. Preserva o arquivo, extrai fatos do produto, público, problema, mercado, operação, canais, validação e modelo de negócio, e registra as lacunas que ainda exigem resposta. O resultado fica em `.brandfy/mvp-context.json`, no briefing e nos briefs usados para criar assets. ## Descoberta e estratégia ### `brandfy-entrevista` Faz as perguntas complementares que o MVP e os arquivos existentes não respondem. Registra fatos, hipóteses, preferências, fontes, responsáveis e confirmações em `.brandfy/interview.json` e no resumo da entrevista. ### `brandfy-diagnostico` Confronta o relato e o contexto importado com arquivos, usos, logos, fontes, licenças, canais e aplicações já existentes. Produz um diagnóstico do que pode ser preservado, corrigido ou criado. ### `brandfy-estrategia` Transforma contexto confirmado em propósito, missão, visão, valores, posicionamento, promessa, diferenciais, princípios e personalidade. Liga cada definição à fonte ou à escolha confirmada. ### `brandfy-naming` Organiza a definição ou a revisão do nome. Compara opções por significado, sonoridade, distinção, uso e disponibilidade indicativa, sem substituir análise jurídica ou consulta oficial. ### `brandfy-slogan` Desenvolve a assinatura verbal da marca a partir do posicionamento e da promessa. Testa entendimento, ritmo, memorabilidade, contexto de uso e limites da frase escolhida. ### `brandfy-voz` Documenta a voz, os tons por situação, o vocabulário, as mensagens principais, os limites e exemplos aprovados. O resultado orienta textos produzidos por pessoas e agentes. ## Identidade visual ### `brandfy-identidade-visual` Converte estratégia em direção visual. Define paleta, tipografia, fotografia, ilustração, iconografia, composição, motion, acessibilidade e referências que podem orientar a criação sem copiar outra marca. ### `brandfy-tipografia-web` Seleciona webfontes compatíveis com a licença e com a direção visual. Registra hierarquia, pesos, fallback, carregamento e CSS para que o produto mantenha a mesma leitura em telas diferentes. ### `brandfy-logo` Conduz o conceito e o sistema de logo. Define símbolo, assinatura, variantes, área livre, tamanho mínimo, fundos permitidos e usos inadequados antes das exportações finais. ### `brandfy-ativos-logo` Exporta o sistema aprovado em SVG e PNG, cria favicons, avatares e manifestos, confere dimensões e preserva o arquivo-fonte para futuras revisões. ### `brandfy-design-tokens` Transforma paleta, tipografia, espaçamento e estados em tokens reutilizáveis. Gera CSS, JSON e tema Tailwind e registra combinações de contraste que podem ser usadas por componentes e aplicações. ## Aplicações e entrega ### `brandfy-aplicacoes` Planeja as aplicações prioritárias da marca em superfícies digitais, sociais, impressas e institucionais. Define formato, conteúdo, composição, zona segura, variante do logo e arquivos que devem ser entregues. ### `brandfy-templates-canais` Instala modelos editáveis para Instagram, LinkedIn, email e YouTube. Cada template registra dimensões, campos variáveis, limites de texto, áreas seguras e arquivos de exemplo. ### `brandfy-manual` Consolida o conteúdo verbal, estratégico, visual, técnico e de governança em `BRAND.md`. Também atualiza `brand/README.md` como índice, sem transformá-lo em uma segunda fonte do manual. ### `brandfy-guia-pdf` Compila `BRAND.md` do projeto consumidor em `brand/brand-guide.pdf`. Instala o design system de PDF quando necessário, preserva personalizações e verifica capa, sumário, fontes, imagens, links, tabelas e paginação. ### `brandfy-auditoria` Confere a estrutura, a consistência entre `BRAND.md` e `brand/`, os arquivos prometidos, dimensões, contraste, licenças, links e saídas compiladas. Registra reprovações, avisos, comprovações e próximos passos em `.brandfy/audit.md`. ## O que a pessoa precisa fazer A usuária instala o sistema com o CLI e conversa com `$brandfy`. Ela confirma respostas, aprova direções e informa arquivos ou restrições que o agente não pode descobrir sozinho. A orquestradora chama as especialistas, explica os resultados e interrompe o percurso quando uma confirmação essencial estiver faltando. ### Solução de problemas - URL: https://promovaweb.com/docs/brandfy/solucao-de-problemas - Descrição: Na raiz do projeto, atualize a instalação e confira o diagnóstico: ## A skill não aparece Na raiz do projeto, atualize a instalação e confira o diagnóstico: ```bash brandfy update brandfy doctor ``` O diagnóstico mostra as skills esperadas, os arquivos de configuração, o estado de `BRAND.md`, o índice `brand/README.md` e a presença de `MVP.md`. ## O setup alteraria arquivos Execute `brandfy doctor` e peça ao agente para revisar o setup. Abra o `AGENTS.md` e procure os dois marcadores do Brandfy. Um bloco incompleto ou duplicado precisa ser corrigido antes de outra execução. Preserve todo conteúdo autoral fora dos marcadores. ## A entrevista não passa no check Abra `.brandfy/interview.json` e leia as mensagens do compilador. Uma entrevista pronta exige confirmação, data, participantes, etapas concluídas e campos mínimos. Uma resposta ainda desconhecida deve aparecer na coleção de pendências com pergunta e responsável. Não altere `status` para `ready` apenas para satisfazer o validador. Complete a conversa ou registre honestamente o que falta. ## O PNG não foi gerado Confirme o ImageMagick e a presença dos SVGs mestres: ```bash magick -version || convert -version find brand/logo/svg -type f -name '*.svg' -print ``` Abra o SVG que falhou e confira `viewBox`, formas vetoriais e referências externas. Uma fonte ausente ou uma imagem vinculada pode funcionar no editor e falhar no ambiente do gerador. ## A webfont não carrega Confira a URL registrada em `brand/fonts/fonts.css`, o nome do arquivo e o MIME type servido pelo website. Abra a página com a rede desabilitada para testar o fallback. Quando o arquivo não pode ser redistribuído, use o serviço licenciado em vez de copiá-lo para o repositório. ## O contraste foi reprovado Leia `brand/accessibility.md` e identifique a função semântica, o tema e a combinação exata. Uma cor aceita no logo pode ser inadequada para texto, controle ou indicador de foco. Corrija a paleta editável e gere novamente os tokens, em vez de aplicar um valor isolado no componente. ## O PDF ficou sem imagens ou fontes Execute o build na raiz do projeto e confira caminhos relativos ao Markdown. Verifique também Pandoc e WeasyPrint: ```bash pandoc --version weasyprint --version ``` Depois da correção, apague somente arquivos temporários declarados pelo compilador e gere o PDF outra vez. Nunca edite o PDF como fonte. ## A auditoria ainda apresenta avisos Abra `.brandfy/audit.md` e relacione cada aviso ao arquivo observado. Alguns itens exigem inspeção humana, como legibilidade no feed, procedência de uma foto ou coerência do tom. Registre a evidência da conferência e execute a auditoria novamente quando houver alteração técnica. ## Dados para um relato de falha Inclua a versão do Node.js, o sistema operacional, o caminho da skill, o comando executado, a mensagem completa e a lista dos arquivos esperados. Remova tokens, informações pessoais, entrevistas reservadas e ativos que não podem ser compartilhados. ### Skills do ClickUpfy para criar, implementar e lançar - URL: https://promovaweb.com/docs/clickupfy/agentes - Descrição: Instale e use quatro skills para trabalho diário, criação de issues, implementação acompanhada, validação técnica e preparação de releases do CLI. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | instalação e responsabilidades das skills distribuídas | | Autoridade | assets empacotados e contrato de agent install | ## O catálogo incluído O pacote distribui cinco skills: | Skill | Responsabilidade | | --- | --- | | `clickupfy-setup` | Configuração de perfil, skills e MCP do projeto. | | `clickupfy-dev` | Consulta e atualização do trabalho diário de software. | | `clickup-issue-create` | Criação de tarefa, subtarefas e checklists sem executar a implementação. | | `clickup-issue-implement` | Execução acompanhada por plano, comentários, tempo, testes e status. | | `clickupfy-release` | Preparação e acompanhamento de versões e artefatos. | As skills são instruções. Elas usam o CLI ou o MCP disponível, mas não contêm credenciais. ## Inspecione antes de instalar ```bash clickupfy agent skill list clickupfy agent skill show clickupfy-dev ``` `list` apresenta o catálogo. `show` imprime a fonte empacotada da skill, útil para revisar permissões e fluxo antes da instalação. As cinco skills são mantidas em português do Brasil. ## Configure o projeto Use `$clickupfy-setup` para preparar um repositório novo ou revisar uma integração existente. A skill executa `clickupfy doctor`, orienta o perfil com `clickupfy auth add` quando necessário, instala as skills por `npx skills add` e cria o MCP somente depois de confirmar os IDs do ClickUp. ## Instale no projeto Na raiz do repositório, o ClickUpfy delega a instalação ao gerenciador `skills`: ```bash clickupfy agent skill install ``` As skills entram em `.agents/skills/` e o gerenciador registra a origem em `skills-lock.json`. Esse modo mantém a configuração próxima ao projeto e permite versionar as instruções. Para instalar no catálogo global do usuário, em `~/.codex/skills/`: ```bash clickupfy agent skill install --global ``` Prefira a instalação local quando projetos usam versões ou regras diferentes. Consulte a instalação efetiva com: ```bash npx skills list npx skills list --global ``` `--force` é aceito por compatibilidade. A atualização passa pelo próprio `npx skills add`, que mantém o lockfile e os caminhos canônicos: ```bash clickupfy agent skill install --force ``` ## Crie uma issue sem implementá-la Peça explicitamente a skill de criação: ```text Use $clickup-issue-create para transformar esta solicitação em uma tarefa no ClickUp. Crie subtarefas e checklists de teste, mas não implemente o trabalho. ``` A skill deve obter os status da List, redigir a descrição em Markdown, criar a tarefa principal e materializar subtarefas e checklists recursivos. A criação não autoriza editar código nem marcar validações como concluídas. ## Implemente uma issue existente ```text Use $clickup-issue-implement para executar a tarefa até a validação final. ``` O fluxo lê a tarefa inteira, monta um plano visível, registra início, datas e time tracking quando aplicável, percorre subtarefas e checklist items e publica checkpoints. Um item de teste só é resolvido depois do comando correspondente passar. A conclusão exige releitura do estado remoto, regressão aplicável e um status terminal existente na List. ## Use a skill diária `clickupfy-dev` é adequada para consultas e mutações pontuais: ```text Use $clickupfy-dev para ler a tarefa , publicar o resultado dos testes e marcar apenas o checklist correspondente. ``` Escopo e autorização continuam limitados pelo pedido. A skill não transforma uma consulta em implementação completa. ## Prepare uma release `clickupfy-release` lê a documentação de release do próprio repositório e acompanha versão, changelog, validações e artefatos. Ela não deve ser instalada como regra genérica em projetos que apenas consomem o CLI. Agora veja como essas skills acessam o ClickUp pelo [servidor MCP](/docs/clickupfy/mcp). ### Referência do CLI ClickUpfy: comandos e formatos de saída - URL: https://promovaweb.com/docs/clickupfy/cli - Descrição: Consulte comandos, opções globais e formatos de saída para configurar perfis, navegar pela hierarquia, trabalhar com tarefas, tempo, skills e MCP. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | grupos públicos, opções globais e formatos de saída | | Autoridade | definições Commander em src/cli.ts | ## Sintaxe global ```text clickupfy [options] [command] ``` O comando de manutenção da instalação npm usa esta forma: ```text clickupfy upgrade [alvo] ``` As opções globais selecionam o account e o formato da resposta antes que o CLI interprete o grupo e a ação: | Opção | Efeito | | -------------------- | ----------------------------------------- | | `-V`, `--version` | Mostra a versão. | | `--account ` | Usa outro account somente nessa execução. | | `--json` | Imprime a resposta completa em JSON. | | `-h`, `--help` | Mostra ajuda. | Coloque as opções globais antes do grupo. No exemplo abaixo, a resposta de `task get` usa o account `cliente-a` e sai em JSON: ```bash clickupfy --account cliente-a --json task get 86abc123 ``` ## Configuração e identidade ```bash clickupfy install [options] clickupfy doctor clickupfy status clickupfy whoami clickupfy account list clickupfy account show [perfil] clickupfy account use clickupfy account remove clickupfy workspace list clickupfy workspace use ``` Para atualizar uma instalação global feita pelo npm, use `clickupfy upgrade`. Consulte a [referência de perfis e hierarquia](/docs/clickupfy/referencia/cli-perfis-hierarquia) para parâmetros, canais aceitos, confirmação da versão e limites do comando. O setup recebe a credencial, identifica o account local e associa o workspace. Estes parâmetros permitem executar o mesmo processo com ou sem prompts: | Opção | Efeito | | ------------------- | ------------------------------------------------------------------- | | `--api-key ` | Informa a API key pessoal do ClickUp. | | `--token ` | Mantém compatibilidade como alias de `--api-key`. | | `--name ` | Define o nome local do account. | | `--workspace ` | Associa o account ao workspace indicado. | | `--non-interactive` | Executa sem abrir prompts e exige os valores necessários por opção. | `account remove ` aceita `--yes` para confirmar a remoção sem prompt. As outras ações desse grupo não possuem opções próprias. `clickupfy doctor` verifica localmente o JSON em `~/clickupfy/config.json`, as permissões, o schema, os accounts, o gerenciador `skills`, as skills do ClickUpfy e os arquivos `.mcp.json` e `.codex/config.toml` do projeto quando existirem. Use `--json` para automação. O comando não faz chamada ao ClickUp. Use `clickupfy whoami` para validar a API key remotamente. ## Hierarquia ```bash clickupfy space list [--archived] clickupfy folder list --space [--archived] clickupfy list list --folder [--archived] clickupfy list list --space [--archived] clickupfy list get ``` `space list`, `folder list` e `list list` aceitam `--archived`. O comando `folder list` exige `--space `. Em `list list`, informe `--folder ` ou `--space `, pois os dois destinos são mutuamente exclusivos e a resposta precisa pertencer a um único nível da hierarquia. ## Tarefas ```bash clickupfy task list --list clickupfy task search --query clickupfy task get clickupfy task get --markdown clickupfy task get --raw clickupfy task create [options] clickupfy task update [options] clickupfy task delete [--yes] ``` ### Filtros de leitura | Comando | Opção | Efeito | | ------------- | ---------------------- | ------------------------------------------------------ | | `task list` | `--list ` | Define a List consultada e é obrigatório. | | `task list` | `--status ` | Restringe a resposta aos status informados. | | `task list` | `--assignee ` | Restringe a resposta aos responsáveis informados. | | `task list` | `--include-closed` | Inclui tarefas concluídas. | | `task list` | `--page ` | Consulta uma página, começando em zero. | | `task search` | `--query ` | Procura no nome, na descrição ou no ID. | | `task search` | `--status ` | Restringe a busca aos status informados. | | `task search` | `--assignee ` | Restringe a busca aos responsáveis informados. | | `task search` | `--include-closed` | Inclui tarefas concluídas. | | `task search` | `--max-pages ` | Limita a paginação consultada entre uma e 100 páginas. | | `task get` | `--raw` | Retorna a resposta original do ClickUp. | | `task get` | `--markdown` | Concatena tarefa, subtarefas e checklists em Markdown. | `--raw` e `--markdown` não podem ser usados juntos. A opção global `--json` também é incompatível com esses dois formatos, e o CLI encerra a execução com uma mensagem de uso quando encontra a combinação. ### Campos de criação | Opção | Efeito | | ------------------------------- | -------------------------------------------------------- | | `--list ` | Define a List de destino e é obrigatório. | | `--name ` | Define o nome e é obrigatório. | | `--description ` | Envia uma descrição em texto. | | `--markdown-content ` | Envia uma descrição preservada como Markdown. | | `--status ` | Define o status inicial. | | `--priority ` | Define prioridade de `1` a `4`. | | `--assignee ` | Informa IDs numéricos dos responsáveis. | | `--parent ` | Cria uma subtarefa ligada ao item informado. | | `--start-date ` | Define a data de início. | | `--due-date ` | Define a data de entrega. | | `--points ` | Define Sprint Points com número igual ou maior que zero. | Escolha `--description` para texto ou `--markdown-content` para Markdown. Evite enviar os dois campos na mesma criação para não deixar a representação da descrição ambígua. ### Campos de atualização | Opção | Efeito | | ------------------------------- | ----------------------------------- | | `--name ` | Altera o nome. | | `--description ` | Substitui a descrição por texto. | | `--markdown-content ` | Substitui a descrição por Markdown. | | `--status ` | Altera o status. | | `--priority ` | Altera a prioridade de `1` a `4`. | | `--start-date ` | Altera a data de início. | | `--clear-start-date` | Remove a data de início. | | `--due-date ` | Altera a data de entrega. | | `--clear-due-date` | Remove a data de entrega. | | `--points ` | Altera os Sprint Points. | O comando exige pelo menos um campo. Quando uma data e sua opção `--clear-*` aparecem na mesma execução, a remoção prevalece. `task delete` usa `--yes` para confirmar a exclusão sem prompt. Depois de escolher os campos, consulte a ajuda da versão instalada para comparar a referência com o contrato executável: ```bash clickupfy task create --help clickupfy task update --help ``` ## Checklists e comentários ```bash clickupfy checklist create --name clickupfy checklist item-create --name clickupfy checklist set \ \ --resolved clickupfy checklist set \ \ --open clickupfy comment list --task clickupfy comment create --task --text ``` `checklist item-create` aceita `--assignee ` para associar o item a um responsável. Em `checklist set`, escolha exatamente `--resolved` ou `--open` para que a releitura confirme o estado pretendido. `comment create` aceita `--notify-all` quando a atualização precisa notificar os participantes da tarefa. ## Sprints ```bash clickupfy sprint list --folder clickupfy sprint current --folder clickupfy sprint get clickupfy sprint tasks [--open-only] clickupfy sprint add-task clickupfy sprint remove-task clickupfy sprint set-points ``` Os comandos de Sprint aceitam opções de calendário, inclusão e estado para separar uma List comum do ciclo que será analisado: | Comando | Opção | Efeito | | ---------------- | ------------------- | -------------------------------------------- | | `sprint list` | `--archived` | Inclui Lists arquivadas. | | `sprint list` | `--include-regular` | Inclui Lists sem período do Sprint Folder. | | `sprint list` | `--at ` | Calcula o estado do ciclo na data informada. | | `sprint current` | `--at ` | Procura a Sprint ativa na data informada. | | `sprint get` | `--at ` | Calcula o relatório na data informada. | | `sprint tasks` | `--open-only` | Omite tarefas concluídas. | `sprint list` e `sprint current` exigem `--folder ` para limitar a busca ao Sprint Folder selecionado. ## Time tracking ```bash clickupfy time current clickupfy time start --task [--description ] clickupfy time stop ``` ## Docs ```bash clickupfy doc list [--query ] [options] clickupfy doc get clickupfy doc create --name [options] clickupfy doc page tree clickupfy doc page list [options] clickupfy doc page get [--content-format ] clickupfy doc page create --name [options] clickupfy doc page update [options] ``` Docs usam a API v3 do ClickUp e sempre operam no workspace do account ativo, fora da hierarquia de Space, Folder ou List. | Comando | Opção | Efeito | | -------------------------------- | ---------------------------- | ---------------------------------------------------------------------------- | | `doc list` | `--query ` | Filtra pelo nome ou ID localmente. | | `doc list` | `--parent-id ` | Restringe aos Docs criados sob este local. | | `doc list` | `--parent-type ` | Tipo do local: `4` Space, `5` Folder, `6` List, `7` Everything, `12` tarefa. | | `doc list` | `--deleted` | Inclui Docs excluídos. | | `doc list` | `--archived` | Inclui Docs arquivados. | | `doc list` | `--creator ` | Restringe ao ID numérico do criador. | | `doc list` | `--max-pages ` | Limita a paginação por cursor, entre uma e 50 páginas. | | `doc create` | `--parent-id ` | Local onde o Doc nasce, exige `--parent-type`. | | `doc create` | `--parent-type ` | Tipo do local, exige `--parent-id`. | | `doc create` | `--visibility ` | `PRIVATE` ou `PUBLIC`. | | `doc create` | `--create-page` | Cria também a primeira página em branco. | | `doc page list` | `--max-page-depth ` | Limita a profundidade de sub-páginas retornadas. | | `doc page list` / `doc page get` | `--content-format ` | `text/md` (padrão) ou `text/plain`. | | `doc page create` | `--content ` | Conteúdo inicial da página. | | `doc page create` | `--sub-title ` | Subtítulo da página. | | `doc page create` | `--parent-page ` | Cria como sub-página deste ID. | | `doc page create` | `--orderindex ` | Posição entre as páginas irmãs. | | `doc page update` | `--content-edit-mode ` | `replace` (padrão), `append` ou `prepend`. | `doc page tree` mostra a hierarquia de páginas sem conteúdo, o caminho mais rápido para localizar um `page-id`. `doc page update` exige pelo menos um campo entre `--name`, `--sub-title` e `--content`. A API pública do ClickUp não oferece endpoints para excluir Docs ou páginas, reordenar páginas na árvore, nem gerenciar permissões de compartilhamento. ## Agentes e MCP ```bash clickupfy agent skill list clickupfy agent skill show clickupfy agent skill install [--global] [--force] clickupfy agent install [options] clickupfy mcp serve --list [options] ``` `agent skill install` aceita uma lista opcional de skills e chama `npx skills add promovaweb/clickupfy --agent codex --copy --yes`. Sem `--global`, o gerenciador usa `.agents/skills/` e cria ou atualiza `skills-lock.json` no projeto. Com `--global`, usa `~/.codex/skills/`. Para consultar o estado real, use `npx skills list` ou `npx skills list --global`, `clickupfy agent skill list` exibe somente o catálogo distribuído pelo ClickUpfy. O comando não oferece `--target`: o gerenciador de skills controla os caminhos canônicos. `--force` permanece aceito por compatibilidade, mas a sincronização é feita pelo próprio `npx skills add`. `agent install` exige `--space ` e `--list `. Ele também aceita `--global`, `--workspace `, `--folder `, `--sprint-folder ` e `--force`. O comando atualiza o servidor `promovaweb-clickupfy` no `.mcp.json` e no `.codex/config.toml`, preservando as outras entradas de cada arquivo. `mcp serve` exige `--list ` e aceita `--account `, `--workspace `, `--space `, `--folder `, `--sprint-folder ` e `--read-only`. ## Escolha o formato de saída A tabela compacta é adequada para leitura humana. Use `--json` quando um script precisar de campos completos ou quando a tabela não mostrar um detalhe da API. Use `task get --markdown` para contexto textual. Use `--raw` apenas quando precisar comparar a resposta original do ClickUp com a projeção do ClickUpfy. ## Ajuda é a referência da versão instalada Esta documentação explica o contrato estável. Para flags exatas da versão presente na máquina: ```bash clickupfy --help clickupfy --help clickupfy --help ``` Quando a ajuda estiver correta, mas a execução falhar, continue no guia de [solução de problemas](/docs/clickupfy/solucao-de-problemas) para conferir instalação, credencial, escopo e resposta da API. ### Como o ClickUpfy organiza CLI, MCP, perfis e projetos - URL: https://promovaweb.com/docs/clickupfy/conceitos - Descrição: Conheça as responsabilidades do ClickUp, do CLI, do servidor MCP e das skills e entenda a diferença entre um account local e o escopo de um projeto. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | conceitos, responsabilidades e limites do produto | | Autoridade | README, CLI, servidor MCP e cliente HTTP do ClickUpfy | ## O problema que a ferramenta resolve O ClickUp continua sendo a fonte do trabalho: tarefa, descrição, status, checklist, comentário, Sprint e registro de tempo permanecem no workspace. O ClickUpfy não cria um gerenciador paralelo. Ele oferece uma interface previsível para consultar e alterar essa fonte pelo terminal ou por um agente. Sem essa camada, cada agente precisa descobrir como autenticar, quais endpoints usar, em qual List trabalhar e como representar uma tarefa grande. O ClickUpfy centraliza essas decisões em três contratos: - o perfil local associa uma API key a um workspace - o projeto fixa o perfil e a hierarquia autorizada no `.mcp.json` ou no `.codex/config.toml` - as skills descrevem quando ler, planejar, comentar, medir tempo e concluir. ## As quatro camadas ### ClickUp É o sistema remoto e a fonte de verdade. O ClickUpfy usa a API pública para ler workspaces, Spaces, Folders, Lists, tarefas, checklists, comentários, Sprints e time entries. Permissões e ClickApps continuam sendo administrados no ClickUp. ### CLI É a interface humana e automatizável. A sintaxe segue `recurso ação`, como `task get`, `sprint current` e `comment create`. Sem `--json`, a saída é compacta. Com `--json`, o CLI preserva a resposta completa necessária para scripts e diagnóstico. ### Servidor MCP É a interface para agentes. Ele usa transporte stdio e expõe ferramentas com schemas explícitos. Uma configuração por projeto pode fixar account, workspace, Space, Folder, List e Sprint Folder. A List é obrigatória porque define o destino das consultas, buscas e criações de tarefa. ### Skills São instruções operacionais entregues junto ao pacote. Elas não substituem o MCP: orientam o agente a usar as ferramentas na ordem adequada, preservar contexto, registrar progresso e comprovar a conclusão. ## Perfis e projetos são coisas diferentes Um **account** do ClickUpfy é um perfil local. Ele contém um nome, a API key, o usuário autenticado e o workspace associado. O arquivo vive fora dos repositórios, em `~/clickupfy/config.json`. Um **projeto** é uma raiz de código que pode conter `.mcp.json` e `.codex/config.toml`. Esses arquivos selecionam um account e fixam IDs da hierarquia no formato esperado por cada cliente. Eles podem ser versionados quando os IDs não forem considerados sensíveis pela equipe, pois nunca contêm a API key. O mesmo account pode servir mais de um projeto. Ambientes de clientes ou workspaces diferentes devem receber perfis separados. ## Leitura compacta e leitura executável `task get` não retorna apenas a tarefa original. O ClickUpfy monta uma propriedade `execution` que achata a tarefa principal, subtarefas de qualquer nível e checklist items em uma fila ordenada. Cada item informa: - uma `key` estável para a leitura atual - o tipo do item - a relação com o pai - a profundidade na árvore - o estado aberto ou concluído - a ação equivalente no CLI e no MCP. Essa fila ajuda o agente a selecionar um item pendente sem perder a hierarquia. Quando o contexto precisa ser lido como documento, `task get --markdown` produz metadados, descrição, resumo e checkboxes em um único texto. ## Limites importantes O ClickUpfy não cria uma Sprint nem habilita o Sprint ClickApp, porque a API pública não oferece um endpoint próprio para essas operações. Crie o Sprint Folder e as Sprints na interface do ClickUp e use o CLI para consulta, associação de tarefas e Sprint Points. O CLI também não decide sozinho qual status representa conclusão. Use `list get ` para ler os status configurados na List. Skills de implementação devem escolher um status terminal existente, não inventar uma grafia. Agora siga para a [instalação](/docs/clickupfy/instalacao). ### Configuração segura de API keys e accounts no ClickUpfy - URL: https://promovaweb.com/docs/clickupfy/configuracao - Descrição: Associe uma API key a um workspace, organize vários accounts e entenda permissões, variáveis de ambiente e cuidados com o arquivo local de credenciais. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | autenticação, accounts e armazenamento local | | Autoridade | setup, schema de configuração e resolução de accounts | ## Crie a API key Use uma API key pessoal criada nas configurações do ClickUp. O ClickUpfy valida a chave antes de salvar, consulta o usuário autenticado e lista os workspaces permitidos. Não cole a chave em issue, comentário, arquivo `.env` versionado, `.mcp.json`, `.codex/config.toml` ou comando compartilhado no histórico da equipe. Em um terminal interativo, prefira o setup com prompt oculto: ```bash clickupfy install ``` Escolha um nome local para o perfil e selecione o workspace. O nome vira um identificador normalizado, como `promovaweb` ou `cliente-a`. ## Automatize o setup quando necessário Em uma automação isolada, o setup aceita parâmetros: ```bash clickupfy install \ --api-key "pk_..." \ --name "Promovaweb" \ --workspace "123456" \ --non-interactive ``` Evite colocar a chave diretamente em um script. Leia o valor de um secret manager ou de uma variável protegida e apague o ambiente temporário depois da execução. ## Entenda o arquivo local Por padrão, a configuração fica em: ```text ~/clickupfy/config.json ``` O diretório recebe permissão `0700` e o arquivo `0600`. A API key precisa estar no JSON porque o CLI autentica chamadas futuras. Essa proteção limita a leitura ao usuário local, mas não substitui os cuidados com backup, malware ou pastas sincronizadas. O schema permite vários accounts: ```json { "version": 1, "activeAccount": "promovaweb", "accounts": { "promovaweb": { "name": "Promovaweb", "apiKey": "pk_...", "user": { "id": 123, "username": "Desenvolvedor" }, "workspace": { "id": "456", "name": "Engenharia" }, "createdAt": "2026-07-29T12:00:00.000Z", "updatedAt": "2026-07-29T12:00:00.000Z" } } } ``` ## Gerencie accounts Use comandos que mascaram a API key: ```bash clickupfy account list clickupfy account show clickupfy status clickupfy whoami ``` `status` mostra o caminho da configuração, o account resolvido e o workspace. `whoami` faz uma chamada autenticada e confirma se a chave ainda é válida. Para conferir o setup local, as permissões do arquivo, o schema e os arquivos de integração do projeto, execute: ```bash clickupfy doctor ``` Esse diagnóstico não faz uma chamada ao ClickUp. Use `clickupfy whoami` quando precisar validar a API key remotamente. Para trocar o perfil ativo: ```bash clickupfy account use cliente-a ``` Para usar outro account em um único comando, sem alterar o ativo: ```bash clickupfy --account cliente-a task get 86abc123 ``` A variável `PROMOVAWEB_CLICKUPFY_ACCOUNT` oferece a mesma seleção em automações. A variável `PROMOVAWEB_CLICKUPFY_CONFIG` aponta para outro JSON e é útil em testes ou ambientes efêmeros. ## Troque o workspace associado Liste os workspaces autorizados e escolha um deles: ```bash clickupfy workspace list clickupfy workspace use 123456 ``` Essa ação altera o workspace do account atual. Configurações de projeto que fixam `--workspace` precisam continuar correspondendo ao perfil. ## Remova um perfil ```bash clickupfy account remove cliente-antigo ``` O CLI pede confirmação. Em automação, `--yes` confirma sem prompt. A remoção apaga o perfil local, não revoga a API key no ClickUp. Revogue a chave no ClickUp quando ela não for mais necessária. Com o perfil validado, prepare o [primeiro projeto](/docs/clickupfy/primeiro-projeto). ### Hierarquia do ClickUpfy: workspace, Space, Folder e List - URL: https://promovaweb.com/docs/clickupfy/hierarquia - Descrição: Encontre IDs de workspace, Space, Folder e List, consulte os status válidos e defina o escopo adequado para o MCP trabalhar em cada projeto local. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | descoberta de IDs e navegação entre recursos do ClickUp | | Autoridade | comandos workspace, space, folder, list e task | ## A ordem dos recursos O ClickUp organiza o trabalho nesta cadeia: ```text Workspace └── Space ├── List sem Folder └── Folder └── List ``` Sprints também são Lists, mas vivem normalmente dentro de um Sprint Folder e possuem `start_date` e `due_date`. O account já conhece um workspace. Por isso, `space list` não exige esse ID. A partir do Space, os comandos precisam do pai para evitar uma busca ambígua. ## Liste workspaces e Spaces ```bash clickupfy workspace list clickupfy space list clickupfy space list --archived ``` O asterisco na saída compacta indica o workspace associado ao account. Use `--archived` somente quando precisar localizar uma estrutura antiga. ## Liste Folders e Lists ```bash clickupfy folder list --space clickupfy list list --folder ``` Para Lists que pertencem diretamente ao Space: ```bash clickupfy list list --space ``` Folder e Space são alternativas no comando de Lists. Não informe os dois ao mesmo tempo. ## Confira os status da List ```bash clickupfy list get ``` Essa leitura é importante antes de atualizar uma tarefa. Os nomes e tipos de status são configuráveis no ClickUp. Uma equipe pode usar `feito`, outra `concluído`, e uma terceira pode manter mais de um estado terminal. Registre o ID da List e escolha um status terminal existente. Não assuma que `done` ou `complete` será aceito. ## Liste e busque tarefas ```bash clickupfy task list --list clickupfy task search --query "autenticação" ``` `task list` consulta uma List conhecida. `task search` procura no workspace, mas o MCP de projeto restringe a busca à List fixada para impedir vazamento de contexto entre projetos. Use `--json` quando precisar inspecionar campos não exibidos na tabela: ```bash clickupfy --json task list --list ``` A opção global vem antes do grupo do comando. ## Escolha o menor escopo suficiente Um MCP de projeto sempre exige List. Space e Folder ajudam as ferramentas de navegação, mas não ampliam o destino de criação. Sprint Folder só deve ser configurado quando as Sprints do projeto estiverem dentro dele. Para um projeto com List diretamente no Space: ```bash clickupfy --account produto agent install \ --space 10 \ --list 30 ``` Para um projeto com Folder e Sprints: ```bash clickupfy --account produto agent install \ --space 10 \ --folder 20 \ --list 30 \ --sprint-folder 40 ``` Continue em [tarefas e checklists](/docs/clickupfy/tarefas). ### Instalação do ClickUpfy pelo npm ou executável standalone - URL: https://promovaweb.com/docs/clickupfy/instalacao - Descrição: Instale o ClickUpfy pelo pacote npm, por um executável de GitHub Release ou em modo de desenvolvimento e confira CLI, versão e skills empacotadas. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | instalação do CLI para uso e desenvolvimento | | Autoridade | package.json, launcher npm e pipeline de executáveis | ## Requisitos Para instalar pelo npm ou desenvolver, use Node.js `22.12.0` ou superior. Para usar um executável standalone, o Node.js não é necessário porque o runtime já está incorporado. Você também precisa de uma API key pessoal do ClickUp com acesso a pelo menos um workspace. A chave só será usada na etapa de [configuração](/docs/clickupfy/configuracao). ## Instale pelo npm O pacote oficial instala o comando global: ```bash npm install --global @promovaweb/clickupfy clickupfy --version clickupfy --help ``` O launcher seleciona o executável compilado em Linux x64, macOS Intel e macOS Apple Silicon. Em outras plataformas, inclusive Windows, usa o build JavaScript incluído no pacote. Uma versão válida na primeira linha confirma que o pacote e o launcher foram encontrados. Se o terminal não localizar `clickupfy`, confira o diretório global do npm: ```bash npm prefix --global npm bin --global ``` O segundo comando pode não existir em versões novas do npm. Nesse caso, o diretório de executáveis costuma ser `bin` dentro do prefixo em Linux e macOS. ## Atualize a instalação npm Quando o ClickUpfy foi instalado globalmente pelo npm, o próprio comando inicia a instalação da versão nova e confirma o launcher que ficará disponível no terminal: ```bash clickupfy upgrade ``` O alvo padrão é `latest`. Para testar um canal ou fixar uma versão, use `clickupfy upgrade next` ou `clickupfy upgrade 0.5.0`. O comando não substitui um executável standalone, nesse caso, baixe o archive correspondente na GitHub Release, confira `SHA256SUMS` e substitua o arquivo no `PATH`. ## Instale um executável standalone Cada GitHub Release distribui archives para Linux x64, macOS Intel, macOS Apple Silicon e Windows x64. Baixe o archive da plataforma, extraia `clickupfy` ou `clickupfy.exe` e mova o arquivo para uma pasta presente no `PATH`. No Linux ou macOS: ```bash chmod +x clickupfy ./clickupfy --version ``` Antes de usar um binário baixado, confira o arquivo `SHA256SUMS` da mesma release. O nome e a versão do archive precisam corresponder à plataforma escolhida. No macOS, o Gatekeeper pode impedir a abertura de um executável sem notarização. Confirme a origem no repositório oficial e siga a política de segurança da máquina. Não desative proteções globais para contornar o aviso. ## Instale para desenvolvimento Clone o repositório independente do ClickUpfy e execute: ```bash npm install npm run build npm link clickupfy --version ``` `npm link` aponta o comando global para o checkout atual. Use esse modo apenas quando precisar desenvolver ou validar uma mudança local. Para voltar ao pacote publicado, remova o link e reinstale a versão do npm. ## Confirme a instalação Execute três leituras sem credenciais: ```bash clickupfy --version clickupfy --help clickupfy agent skill list ``` O catálogo deve listar `clickupfy-dev`, `clickup-issue-create`, `clickup-issue-implement` e `clickupfy-release`. A presença das skills confirma que os assets foram empacotados junto ao CLI. Ainda não execute comandos remotos. Primeiro [configure um perfil](/docs/clickupfy/configuracao). ### Guia completo do ClickUpfy: visão geral e percurso de uso - URL: https://promovaweb.com/docs/clickupfy/introducao - Descrição: Entenda como o ClickUpfy conecta terminal, tarefas, Sprints, skills e agentes ao ClickUp com credenciais locais e um escopo seguro para cada projeto. O ClickUpfy conecta o trabalho mantido no ClickUp ao terminal e aos agentes de código. Um único executável configura vários perfis, percorre a hierarquia do ClickUp, administra tarefas, checklists, Sprints, comentários e time tracking, instala skills no projeto e oferece as mesmas operações por MCP. Este guia ensina essa jornada em sequência. Você começa instalando o CLI e associando uma API key a um workspace. Depois encontra os IDs do projeto, executa uma tarefa completa pelo terminal e prepara um MCP restrito para que o agente trabalhe somente na List autorizada. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | percurso completo do usuário do ClickUpfy | | Autoridade | interfaces públicas do CLI, servidor MCP e skills distribuídas | ## Leia online ou como ebook Estas páginas também formam o **ClickUpfy — Guia completo do usuário**. A [pasta do ebook](https://github.com/promovaweb/clickupfy/blob/main/ebook/README.md) publica a versão vigente em PDF e EPUB e registra os hashes que comprovam a origem comum dos formatos. O PDF favorece leitura, compartilhamento e impressão. O EPUB se adapta ao tamanho de fonte e ao leitor digital. Os dois são reconstruídos sempre que uma página desta documentação muda. ## Percurso pedagógico Siga esta ordem na primeira leitura: 1. [Entenda o ClickUpfy](/docs/clickupfy/conceitos) e os limites entre ClickUp, CLI, MCP e skills. 2. [Instale o CLI](/docs/clickupfy/instalacao) pelo npm ou por um executável standalone. 3. [Configure perfis e credenciais](/docs/clickupfy/configuracao) sem colocar a API key no repositório. 4. Consulte a [referência de perfis e hierarquia](/docs/clickupfy/referencia/cli-perfis-hierarquia) sempre que precisar de parâmetro, efeito persistente ou variação de comando. 5. [Prepare o primeiro projeto](/docs/clickupfy/primeiro-projeto) e confira o escopo antes de permitir escrita. 6. [Navegue pela hierarquia](/docs/clickupfy/hierarquia) até encontrar Space, Folder, List e Sprint Folder. 7. [Trabalhe com tarefas e checklists](/docs/clickupfy/tarefas), incluindo subtarefas, Markdown, datas e comentários. 8. Consulte a [referência de tarefas, checklists, comentários e tempo](/docs/clickupfy/referencia/cli-tarefas) para parâmetros, formatos e confirmações de escrita. 9. [Planeje Sprints](/docs/clickupfy/sprints) e acompanhe avanço por tarefas e Sprint Points. 10. Consulte a [referência de Sprints](/docs/clickupfy/referencia/cli-sprints) para os parâmetros de relatório, associação e Sprint Points. 11. [Registre tempo](/docs/clickupfy/time-tracking) no item em execução. 12. [Instale e use as skills](/docs/clickupfy/agentes) que acompanham criação, implementação e release. 13. [Conecte um agente por MCP](/docs/clickupfy/mcp) com IDs fixos e opção read-only. 14. Consulte a [referência de Docs, skills e servidor MCP](/docs/clickupfy/referencia/cli-docs-agentes) para os recursos de documentação dentro do ClickUp e a integração no projeto. 15. Use a [referência MCP de contexto e hierarquia](/docs/clickupfy/referencia/mcp-contexto-hierarquia) para conhecer cada argumento aceito pelas ferramentas de navegação. 16. Consulte a [referência MCP de Docs e administração](/docs/clickupfy/referencia/mcp-docs-administracao) para o workspace, Docs, páginas e ferramentas condicionais do servidor. 17. Consulte a [referência MCP de trabalho](/docs/clickupfy/referencia/mcp-trabalho) para operações de tarefas, Sprints, checklists, comentários e tempo. 18. [Consulte a referência do CLI](/docs/clickupfy/cli) para comandos, argumentos e formatos de saída. 19. [Resolva falhas comuns](/docs/clickupfy/solucao-de-problemas) de autenticação, escopo, status e integração. ## O modelo mental em uma frase O arquivo global guarda credenciais. Os arquivos do projeto guardam somente o perfil e os IDs autorizados. O `.mcp.json` atende clientes que usam JSON, o `.codex/config.toml` atende o Codex. Essa divisão permite usar o mesmo ClickUpfy em vários projetos sem duplicar a API key. Um projeto pode apontar para a List de um produto, enquanto outro aponta para a List de um cliente. O MCP de cada raiz recusa IDs diferentes dos que foram fixados. Comece por [entender o papel de cada camada](/docs/clickupfy/conceitos). ### Servidor MCP do ClickUpfy: ferramentas, escopo e read-only - URL: https://promovaweb.com/docs/clickupfy/mcp - Descrição: Configure o transporte stdio, fixe a hierarquia do projeto, use read-only e conheça as ferramentas de contexto, tarefas, Sprints e time tracking. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | configuração, isolamento e uso do servidor MCP | | Autoridade | implementação do servidor MCP e schemas das ferramentas | ## Inicie manualmente O servidor usa transporte stdio e reserva a saída padrão para as mensagens JSON-RPC trocadas com o cliente MCP: ```bash clickupfy mcp serve --list 30 ``` A List é obrigatória porque limita consultas e mutações ao destino do projeto. O comando abaixo também fixa os níveis superiores e o Sprint Folder: ```bash clickupfy mcp serve \ --account promovaweb \ --workspace 123 \ --space 10 \ --folder 20 \ --list 30 \ --sprint-folder 40 ``` Na prática, deixe o cliente MCP iniciar esse processo pelo `.mcp.json` ou pelo `.codex/config.toml` quando o cliente for o Codex. O comando `agent install` gera e atualiza os dois formatos. ## Ative read-only ```bash clickupfy mcp serve --list 30 --read-only ``` O modo read-only não registra ferramentas de escrita. Elas deixam de aparecer em `tools/list`, portanto a restrição é aplicada na superfície do servidor e não depende apenas da obediência do agente. Use esse modo para descoberta, auditoria, demonstração ou qualquer conversa que não autorize alterações. Confira `tools/list` no cliente para confirmar que as ferramentas de escrita não foram registradas. ## Entenda o isolamento O MCP recebe IDs no processo. Quando uma ferramenta omite um ID, o servidor usa o valor fixado. Quando recebe um valor diferente, recusa a operação. Essa comparação protege estes níveis: - account - workspace - Space - Folder - List - Sprint Folder. A busca de tarefas também permanece dentro da List do projeto. Assim, dois clientes MCP podem operar em paralelo sem compartilhar destino. ## Ferramentas de contexto e navegação `clickupfy_mcp_context` mostra perfil e hierarquia sem expor a API key. `clickupfy_list_get` retorna os status válidos da List. ### Catálogo disponível em read-only | Ferramenta | Função | | --------------------------- | ------------------------------------------------------------------- | | `clickupfy_mcp_context` | Mostra o account e os IDs fixados pelo projeto. | | `clickupfy_accounts_list` | Lista accounts locais sem revelar API keys. | | `clickupfy_whoami` | Valida o account e retorna o usuário autenticado. | | `clickupfy_workspaces_list` | Lista workspaces autorizados. | | `clickupfy_spaces_list` | Lista Spaces do workspace do account. | | `clickupfy_folders_list` | Lista Folders do Space fixado ou informado. | | `clickupfy_lists_list` | Lista Lists de um Folder ou diretamente de um Space. | | `clickupfy_list_get` | Lê a List do projeto e seus status. | | `clickupfy_tasks_list` | Lista tarefas da List autorizada. | | `clickupfy_tasks_search` | Busca tarefas dentro da List autorizada. | | `clickupfy_task_get` | Lê uma tarefa como resposta original, fila `execution` ou Markdown. | | `clickupfy_comments_list` | Lê os comentários de uma tarefa. | | `clickupfy_sprints_list` | Lista Sprints do Sprint Folder. | | `clickupfy_sprint_current` | Obtém a Sprint ativa na data de referência. | | `clickupfy_sprint_get` | Produz o relatório de uma Sprint. | | `clickupfy_sprint_tasks` | Lista tarefas associadas à Sprint. | | `clickupfy_time_current` | Consulta o time entry em execução. | | `clickupfy_docs_list` | Busca Docs do workspace do account. | | `clickupfy_doc_get` | Lê metadados de um Doc. | | `clickupfy_doc_page_tree` | Lê a hierarquia de páginas do Doc, sem conteúdo. | | `clickupfy_doc_pages_list` | Lê as páginas do Doc com conteúdo em Markdown. | | `clickupfy_doc_page_get` | Lê uma página específica com conteúdo. | ### Catálogo acrescentado no modo com escrita | Ferramenta | Função | | --------------------------------- | ---------------------------------------------------------------- | | `clickupfy_account_use` | Altera o account ativo quando o servidor não fixa um account. | | `clickupfy_workspace_use` | Altera o workspace quando account e workspace não estão fixados. | | `clickupfy_task_create` | Cria tarefa ou subtarefa na List autorizada. | | `clickupfy_task_update` | Atualiza campos de uma tarefa. | | `clickupfy_checklist_create` | Cria um checklist em uma tarefa. | | `clickupfy_checklist_item_create` | Acrescenta um item ao checklist. | | `clickupfy_checklist_item_set` | Marca ou reabre um item e confirma o novo estado. | | `clickupfy_sprint_add_task` | Associa uma tarefa à Sprint. | | `clickupfy_sprint_remove_task` | Remove a associação sem excluir a tarefa. | | `clickupfy_sprint_set_points` | Define Sprint Points. | | `clickupfy_task_delete` | Exclui uma tarefa mediante `confirm: true`. | | `clickupfy_comment_create` | Publica um comentário na tarefa. | | `clickupfy_time_start` | Inicia um time entry associado à tarefa. | | `clickupfy_time_stop` | Encerra o time entry atual. | | `clickupfy_doc_create` | Cria um Doc no workspace, opcionalmente vinculado a um local. | | `clickupfy_doc_page_create` | Cria uma página, ou sub-página, em um Doc. | | `clickupfy_doc_page_update` | Atualiza título, subtítulo e/ou conteúdo de uma página. | Na criação e na atualização, informe apenas os campos que devem ser enviados. O servidor recusa IDs que não correspondem ao escopo fixado. A skill de implementação consulta `clickupfy_time_current` antes de iniciar outro registro. As ferramentas de Docs não seguem o isolamento por Space, Folder ou List: elas sempre operam no workspace do account resolvido, porque Docs não pertencem a uma List. `clickupfy_doc_create` exige `parentType` sempre que `parentId` for informado, seguindo os mesmos tipos de local da API do ClickUp (`4` Space, `5` Folder, `6` List, `7` Everything, `12` tarefa). ## Use Markdown para contexto longo `clickupfy_task_get` aceita `markdown: true`. Nesse modo, a ferramenta retorna um texto único, sem envolver o documento em uma string JSON escapada. Essa forma reduz ruído para agentes e preserva checkboxes hierárquicos. Esta solicitação usa a leitura em Markdown e informa ao agente que nenhuma mutação está autorizada: ```text Leia a tarefa 86abc123 com clickupfy_task_get e markdown: true. Resuma o objetivo, liste os itens pendentes e não faça mutações. ``` ## Diagnostique a conexão Se o cliente não listar ferramentas, siga a conexão desde o comando local até o recarregamento do processo: 1. execute o comando de `args` manualmente no terminal 2. confira se o account existe 3. confirme que `--list` possui valor 4. valide o JSON 5. reinicie o cliente MCP 6. leia os logs sem imprimir a API key. A [referência do CLI](/docs/clickupfy/cli) reúne os comandos e as flags usados para reproduzir o servidor manualmente quando o diagnóstico exigir uma comparação. ### Primeiro projeto com ClickUpfy e MCP, passo a passo - URL: https://promovaweb.com/docs/clickupfy/primeiro-projeto - Descrição: Valide o perfil, encontre Space, Folder e List, instale as skills, configure o MCP do repositório e confira o destino com acesso somente leitura. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | primeira integração de um repositório com ClickUpfy e MCP | | Autoridade | agent install, escopo MCP e ferramentas públicas | ## O que você vai preparar Neste percurso, um repositório será ligado a uma List do ClickUp. O resultado são `.mcp.json` e `.codex/config.toml`, cada um no formato do cliente que os consome, iniciando o ClickUpfy com um account e IDs fixos, além das quatro skills instaladas no projeto. Antes de escrever qualquer tarefa, você vai: 1. validar o perfil 2. descobrir Space, Folder e List 3. instalar o MCP em read-only para conferir o destino 4. liberar escrita somente depois da revisão. ## Valide o perfil ```bash clickupfy status clickupfy whoami ``` Confirme o nome do account, o usuário e o workspace. Se qualquer dado estiver errado, volte à [configuração](/docs/clickupfy/configuracao). ## Descubra a hierarquia ```bash clickupfy workspace list clickupfy space list clickupfy folder list --space clickupfy list list --folder ``` Uma List pode pertencer diretamente ao Space. Nesse caso: ```bash clickupfy list list --space ``` Guarde os IDs confirmados. Se o projeto usa Sprints, localize também o Sprint Folder que contém as Lists temporais. ## Inicialize o agente Na raiz do repositório: ```bash clickupfy --account promovaweb agent install \ --workspace 123 \ --space 10 \ --folder 20 \ --list 30 ``` `space` e `list` são obrigatórios. Workspace e Folder podem ser omitidos quando não forem necessários ao escopo. Acrescente `--sprint-folder ` se o projeto usa Sprints. O comando instala as skills e mescla o servidor no `.mcp.json` e no `.codex/config.toml` existentes sem remover outros servidores ou configurações. No JSON, a entrada fica assim: ```json { "mcpServers": { "promovaweb-clickupfy": { "command": "clickupfy", "args": [ "mcp", "serve", "--account", "promovaweb", "--workspace", "123", "--space", "10", "--folder", "20", "--list", "30" ] } } } ``` No Codex, a entrada equivalente fica na tabela `mcp_servers`: ```toml [mcp_servers."promovaweb-clickupfy"] command = "clickupfy" args = ["mcp", "serve", "--account", "promovaweb", "--workspace", "123", "--space", "10", "--folder", "20", "--list", "30"] ``` Antes de abrir o cliente MCP pela primeira vez, acrescente `--read-only` ao fim de `args`. O `agent install` prepara o servidor completo. Essa edição consciente reduz a superfície durante a conferência inicial. ## Confira no agente Reinicie ou recarregue o cliente MCP para que ele leia a nova configuração. Peça uma consulta ao contexto: ```text Use clickupfy_mcp_context e mostre o perfil, o workspace e a hierarquia deste projeto. ``` Compare o resultado com os IDs anotados. Depois liste as tarefas: ```text Use clickupfy_tasks_list sem informar listId. ``` O servidor deve aplicar a List configurada. Uma tentativa de consultar outra List deve ser recusada. ## Libere escrita Quando o destino estiver correto, remova apenas `--read-only` da entrada gerenciada. Reabra o cliente MCP e confirme que as ferramentas de escrita aparecem em `tools/list`. Crie uma tarefa de teste somente se o projeto e a equipe autorizarem a mutação. Caso contrário, use uma tarefa real já existente para validar leitura, comentários e checklists. ## Primeira leitura de uma tarefa No terminal: ```bash clickupfy task get --markdown ``` No agente: ```text Leia com clickupfy_task_get usando markdown: true. Não altere a tarefa. ``` Confira descrição, subtarefas, checklists e fila executável. Agora você já pode aprofundar a [hierarquia](/docs/clickupfy/hierarquia) ou começar a [trabalhar com tarefas](/docs/clickupfy/tarefas). ### Referência do CLI ClickUpfy: Docs, skills e servidor MCP - URL: https://promovaweb.com/docs/clickupfy/referencia/cli-docs-agentes - Descrição: Consulte Docs, páginas, skills, inicialização de projetos e servidor MCP no CLI ClickUpfy, com parâmetros, efeitos, permissões, limites e exemplos de uso. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | comandos de Docs do ClickUp, skills distribuídas, inicialização de projeto e servidor MCP | | Autoridade | `src/cli.ts`, `src/agent-assets.ts`, `src/mcp.ts` e ajuda da versão instalada | Os Docs do ClickUp pertencem ao workspace do perfil. Eles não usam a List, Space ou Folder fixados pelo MCP, porque a API de Docs trabalha em outro ramo da plataforma. Os IDs abaixo são fictícios. Use `doc list`, `doc get` e `doc page tree` para descobrir IDs reais antes de criar ou alterar conteúdo. ## Docs ### `clickupfy doc list` Busca Docs no workspace associado ao perfil. `--max-pages` controla o número de páginas de cursor consultadas e aceita inteiros de `1` a `50`, o padrão é `50`. `--parent-id` deve ser usado junto de `--parent-type` para identificar o local. | Parâmetro | Obrigatório | Uso | | ------------------- | ----------- | ------------------------------------------------------------- | | `--query ` | não | Filtro pelo nome ou ID do Doc. | | `--parent-id ` | não | Local pai do Doc. | | `--parent-type ` | não | `4` Space, `5` Folder, `6` List, `7` Everything, `12` tarefa. | | `--deleted` | não | Inclui Docs excluídos. | | `--archived` | não | Inclui Docs arquivados. | | `--creator ` | não | ID numérico da pessoa criadora. | | `--max-pages ` | não | Cursor de `1` a `50`, padrão `50`. | Exemplos: ```bash clickupfy doc list ``` ```bash clickupfy doc list --query "API" ``` ```bash clickupfy doc list --parent-id 3001 --parent-type 6 ``` ```bash clickupfy doc list --archived --deleted --creator 42 --max-pages 10 ``` ```bash clickupfy --account produto --json doc list --query "Manual" --max-pages 5 ``` `--parent-type` sem `--parent-id` não cria uma consulta útil, pois não há local para classificar. A saída inclui os metadados necessários para chamar `doc get` ou navegar pelas páginas. ### `clickupfy doc get ` Obtém metadados de um Doc no workspace atual. Ele não devolve automaticamente o conteúdo das páginas, use `doc page list` para conteúdo completo ou `doc page get` para uma página determinada. Exemplos: ```bash clickupfy doc get doc-1 ``` ```bash clickupfy --json doc get doc-1 ``` ```bash clickupfy --account produto doc get doc-1 ``` ```bash clickupfy --account cliente-a --json doc get doc-22 ``` ```bash clickupfy doc get doc-1 > /tmp/doc-1.txt ``` O último exemplo guarda a tabela compacta. Para processamento por outro programa, acrescente `--json` e preserve os dados do workspace como informação interna da equipe. ### `clickupfy doc create --name ` Cria um Doc no workspace. Quando `--parent-id` é informado, `--parent-type` é obrigatório. Os tipos são `4` Space, `5` Folder, `6` List, `7` Everything e `12` tarefa. `--visibility` aceita o valor definido pela API, normalmente `PRIVATE` ou `PUBLIC`, `--create-page` cria a primeira página em branco. | Parâmetro | Obrigatório | Uso | | ---------------------- | ----------- | ----------------------------------------- | | `--name ` | sim | Nome do Doc. | | `--parent-id ` | não | Local onde o Doc será criado. | | `--parent-type ` | condicional | Tipo do local quando há `parent-id`. | | `--visibility ` | não | Visibilidade, como `PRIVATE` ou `PUBLIC`. | | `--create-page` | não | Cria uma primeira página vazia. | Exemplos: ```bash clickupfy doc create --name "Manual da API" ``` ```bash clickupfy doc create --name "Guia do produto" --create-page ``` ```bash clickupfy doc create --name "Notas da List" --parent-id 3001 --parent-type 6 ``` ```bash clickupfy doc create --name "Documento interno" --parent-id 2001 --parent-type 5 --visibility PRIVATE ``` ```bash clickupfy --account produto --json doc create --name "Plano de release" --parent-id 86abc123 --parent-type 12 --create-page ``` Uma criação bem-sucedida devolve o ID do Doc. Releia seus metadados e crie as páginas pelo grupo `doc page`. A API pública usada pelo ClickUpfy não expõe exclusão de Docs, mudança de permissões ou reordenação da árvore. ### `clickupfy doc page tree ` Mostra somente a árvore de páginas, sem o corpo. É a leitura mais econômica para descobrir um `page-id` e a relação pai-filho antes de criar uma subpágina ou atualizar conteúdo. Exemplos: ```bash clickupfy doc page tree doc-1 ``` ```bash clickupfy --json doc page tree doc-1 ``` ```bash clickupfy --account produto doc page tree doc-1 ``` ```bash clickupfy --account cliente-a --json doc page tree doc-22 ``` ```bash clickupfy doc page tree doc-1 > /tmp/doc-1-tree.txt ``` O retorno não é cópia de segurança do conteúdo. Use `doc page list` quando o objetivo for ler todas as páginas em Markdown. ### `clickupfy doc page list ` Lista páginas com conteúdo. `--max-page-depth` limita a profundidade de subpáginas retornada. `--content-format` aceita `text/md`, o padrão, ou `text/plain` para texto sem a representação Markdown da API. | Parâmetro | Obrigatório | Uso | | -------------------------- | ----------- | ---------------------------------- | | `` | sim | Doc cujas páginas serão lidas. | | `--max-page-depth ` | não | Profundidade máxima de subpáginas. | | `--content-format ` | não | `text/md` ou `text/plain`. | Exemplos: ```bash clickupfy doc page list doc-1 ``` ```bash clickupfy doc page ls doc-1 --max-page-depth 1 ``` ```bash clickupfy doc page list doc-1 --max-page-depth 3 ``` ```bash clickupfy doc page list doc-1 --content-format text/plain ``` ```bash clickupfy --account produto --json doc page list doc-1 --content-format text/md ``` Use uma profundidade pequena quando só precisa dos capítulos principais. Para uma página conhecida, `doc page get` reduz a resposta e evita transmitir o conteúdo de outras páginas a um agente. ### `clickupfy doc page get ` Obtém uma página específica e seu conteúdo. `--content-format` tem os mesmos valores de `doc page list`: `text/md` por padrão e `text/plain` como opção. Exemplos: ```bash clickupfy doc page get doc-1 page-1 ``` ```bash clickupfy doc page get doc-1 page-1 --content-format text/plain ``` ```bash clickupfy --json doc page get doc-1 page-1 ``` ```bash clickupfy --account produto doc page get doc-1 page-2 --content-format text/md ``` ```bash clickupfy --account cliente-a --json doc page get doc-22 page-8 ``` O ID da página deve pertencer ao Doc informado. Localize-o com `doc page tree` ou `doc page list`, não com tentativa e erro. ### `clickupfy doc page create --name ` Cria página ou subpágina em um Doc. `--parent-page` indica uma página pai, `--orderindex` escolhe a posição entre páginas irmãs. O conteúdo inicial e o subtítulo são opcionais. Não use `orderindex` como substituto de uma revisão da árvore existente: leia a árvore antes de inserir conteúdo. | Parâmetro | Obrigatório | Uso | | -------------------------- | ----------- | ---------------------------- | | `` | sim | Doc proprietário. | | `--name ` | sim | Título da página. | | `--content ` | não | Conteúdo inicial. | | `--sub-title ` | não | Subtítulo. | | `--parent-page ` | não | Página pai de uma subpágina. | | `--orderindex ` | não | Posição entre páginas irmãs. | | `--content-format ` | não | `text/md` ou `text/plain`. | Exemplos: ```bash clickupfy doc page create doc-1 --name "Introdução" ``` ```bash clickupfy doc page create doc-1 --name "Autenticação" --content "Use uma API key pessoal." ``` ```bash clickupfy doc page create doc-1 --name "Detalhes" --sub-title "Campos e respostas" --content "## Parâmetros" ``` ```bash clickupfy doc page create doc-1 --name "Erros" --parent-page page-1 --orderindex 2 ``` ```bash clickupfy --account produto --json doc page create doc-1 --name "Integração" --content "# MCP" --content-format text/md ``` Leia a página criada com `doc page get` e a árvore com `doc page tree` para confirmar conteúdo e posição. A criação não atualiza outras páginas nem cria um Doc novo. ### `clickupfy doc page update ` Atualiza título, subtítulo e/ou conteúdo de uma página. Pelo menos um campo é necessário. `--content-edit-mode` controla o conteúdo: `replace` substitui, `append` acrescenta ao fim e `prepend` insere no começo. Sem a flag, o modo é `replace`. | Parâmetro | Obrigatório | Uso | | ---------------------------- | ----------- | --------------------------------- | | ``, `` | sim | Doc e página a atualizar. | | `--name ` | não | Novo título. | | `--sub-title ` | não | Novo subtítulo. | | `--content ` | não | Conteúdo enviado à API. | | `--content-edit-mode ` | não | `replace`, `append` ou `prepend`. | | `--content-format ` | não | `text/md` ou `text/plain`. | Exemplos: ```bash clickupfy doc page update doc-1 page-1 --name "Visão geral" ``` ```bash clickupfy doc page update doc-1 page-1 --sub-title "Instalação e configuração" ``` ```bash clickupfy doc page update doc-1 page-1 --content "# Novo conteúdo" ``` ```bash clickupfy doc page update doc-1 page-1 --content "\n## Changelog" --content-edit-mode append ``` ```bash clickupfy --account produto --json doc page update doc-1 page-2 --content "# Aviso\n\n" --content-edit-mode prepend --content-format text/md ``` Leia a página depois da escrita para confirmar o modo aplicado. A API pública usada pelo ClickUpfy não oferece exclusão de página nem movimentação na árvore. ## Skills e projeto de agente ### `clickupfy agent skill list` Lista as skills embaladas: `clickupfy-dev`, `clickup-issue-create`, `clickup-issue-implement` e `clickupfy-release`. Não instala nada e não precisa de perfil configurado. O estado da instalação é responsabilidade do gerenciador `npx skills`, use `npx skills list` no projeto ou `npx skills list --global`. Exemplos: ```bash clickupfy agent skill list ``` ```bash clickupfy agent skill list | sort ``` ```bash clickupfy agent skill list > /tmp/clickupfy-skills.txt ``` ```bash clickupfy agent skill list | wc -l ``` ```bash clickupfy agent skill list && clickupfy agent skill show clickupfy-dev ``` O catálogo é incorporado ao pacote ou executável. `list` não verifica se uma skill já está instalada no projeto, ele apenas mostra o que a versão instalada do ClickUpfy pode distribuir. As instruções e os metadados distribuídos estão em português do Brasil. ### `clickupfy agent skill show ` Imprime a fonte da skill embarcada. Use-o para revisar instruções e permissões antes da instalação. O argumento precisa ser um dos quatro nomes do catálogo. Exemplos: ```bash clickupfy agent skill show clickupfy-dev ``` ```bash clickupfy agent skill show clickup-issue-create ``` ```bash clickupfy agent skill show clickup-issue-implement ``` ```bash clickupfy agent skill show clickupfy-release ``` ```bash clickupfy agent skill show clickupfy-dev > /tmp/clickupfy-dev-skill.md ``` Uma skill inexistente é recusada. O comando só lê o asset distribuído, ele não abre uma cópia local já instalada, que pode ter sido alterada pelo projeto. ### `clickupfy agent skill install [skills...]` Instala todas as skills quando nenhum nome é informado, ou somente as skills posicionais escolhidas, chamando `npx skills add promovaweb/clickupfy`. Sem `--global`, o destino é `.agents/skills/` da pasta atual e o gerenciador atualiza `skills-lock.json`. `--global` usa `~/.codex/skills`. A instalação sempre usa `--agent codex`, `--copy` e `--yes`. | Parâmetro | Obrigatório | Uso | | ------------- | ----------- | -------------------------------------- | | `[skills...]` | não | Uma ou mais skills do catálogo. | | `--global` | não | Instala no catálogo global do usuário. | | `--force` | não | Permite repetir a instalação. | Exemplos: ```bash clickupfy agent skill install ``` ```bash clickupfy agent skill install clickupfy-dev ``` ```bash clickupfy agent skill install clickup-issue-create clickup-issue-implement ``` ```bash clickupfy agent skill install --global clickupfy-dev ``` ```bash clickupfy agent skill install clickupfy-release --force ``` `--target` não é aceito porque os caminhos canônicos pertencem ao gerenciador `npx skills`. Revise a fonte com `agent skill show` e consulte `npx skills list` antes de atualizar regras de um projeto. ### `clickupfy agent install` Instala as skills e mescla um servidor `promovaweb-clickupfy` no `.mcp.json` e no `.codex/config.toml` do projeto. `--space` e `--list` são obrigatórios. Os arquivos gerados guardam perfil e IDs, mas nunca a API key. O JSON usa `mcpServers`, o Codex usa `[mcp_servers."promovaweb-clickupfy"]`. Acrescente `--read-only` manualmente aos argumentos das entradas quando o primeiro uso só pode consultar dados. | Parâmetro | Obrigatório | Uso | | ---------------------- | ----------- | ---------------------------- | | `--global` | não | Instala skills globalmente. | | `--workspace ` | não | Workspace esperado pelo MCP. | | `--space ` | sim | Space fixado para o projeto. | | `--folder ` | não | Folder fixado. | | `--list ` | sim | List fixa e obrigatória. | | `--sprint-folder ` | não | Sprint Folder do projeto. | | `--force` | não | Atualiza skills existentes. | Exemplos: ```bash clickupfy agent install --space 1001 --list 3001 ``` ```bash clickupfy --account produto agent install --workspace 123456 --space 1001 --folder 2001 --list 3001 ``` ```bash clickupfy agent install --space 1001 --list 3001 --sprint-folder 4001 ``` ```bash clickupfy agent install --global --space 1001 --list 3001 --force ``` ```bash clickupfy --account cliente-a agent install --workspace 987654 --space 5001 --list 7001 --sprint-folder 8001 --force ``` O comando preserva outros servidores e configurações nos dois arquivos. Reabra o cliente MCP e chame `clickupfy_mcp_context` para conferir o destino. O CLI não lê esses arquivos em chamadas normais: eles só são usados pelo cliente para iniciar `mcp serve`. ### `clickupfy mcp serve --list ` Inicia o servidor MCP em stdio. A saída padrão é reservada ao protocolo JSON-RPC, mensagens operacionais são escritas em stderr. `--list` é obrigatório. Os outros IDs fixam os níveis superiores, `--read-only` remove ferramentas de escrita de `tools/list`. | Parâmetro | Obrigatório | Uso | | ---------------------- | ----------- | ------------------------------------- | | `--account ` | não | Perfil fixado. | | `--workspace ` | não | Workspace esperado. | | `--space ` | não | Space fixado. | | `--folder ` | não | Folder fixado. | | `--list ` | sim | List fixa. | | `--sprint-folder ` | não | Sprint Folder fixado. | | `--read-only` | não | Expõe somente ferramentas de leitura. | Exemplos: ```bash clickupfy mcp serve --list 3001 ``` ```bash clickupfy mcp serve --account produto --list 3001 ``` ```bash clickupfy mcp serve --workspace 123456 --space 1001 --folder 2001 --list 3001 ``` ```bash clickupfy mcp serve --list 3001 --sprint-folder 4001 --read-only ``` ```bash clickupfy mcp serve --account cliente-a --workspace 987654 --space 5001 --list 7001 --sprint-folder 8001 ``` Normalmente o cliente MCP executa esse comando a partir do `.mcp.json` ou do `.codex/config.toml`, não o inicie em um terminal que também precise de saída humana. A referência MCP detalha cada ferramenta exposta pelo servidor e as diferenças entre leitura e escrita. ### Referência do CLI ClickUpfy: perfis e hierarquia no ClickUp - URL: https://promovaweb.com/docs/clickupfy/referencia/cli-perfis-hierarquia - Descrição: Consulte opções globais, setup, accounts, autenticação e a hierarquia do ClickUp no CLI ClickUpfy, com parâmetros, saídas, limites e exemplos práticos. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | comandos globais, perfis locais, autenticação e descoberta da hierarquia do ClickUp | | Autoridade | `src/cli.ts`, `src/config.ts`, `src/context.ts` e ajuda da versão instalada | Este capítulo descreve cada comando que prepara uma sessão de trabalho e localiza os IDs usados pelos demais capítulos. Os exemplos usam IDs fictícios. Substitua somente os valores entre colchetes ou os números de exemplo. Nunca cole uma API key em arquivo versionado, conversa pública, comentário de tarefa ou captura de tela. ## Opções globais Todas as ações, exceto a configuração inicial, podem receber estas opções imediatamente depois de `clickupfy`: | Opção | Tipo | Efeito | | -------------------- | -------- | ----------------------------------------------------------------------- | | `--account ` | texto | Seleciona um perfil para esta execução sem trocar o perfil ativo. | | `--json` | booleano | Imprime o payload completo em JSON, adequado para automação e inspeção. | O perfil ativo só muda com `account use`. A ordem importa: escreva `clickupfy --account cliente-a task list`, e não coloque `--account` depois do subcomando. ### `clickupfy upgrade` Atualiza a instalação global do ClickUpfy pelo npm e relê o launcher global depois da instalação. Sem alvo, instala `@promovaweb/clickupfy@latest`. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `[alvo]` | não | `latest`, `next` ou uma versão SemVer, como `0.5.0`. `latest` é o padrão. | O comando instala a nova versão com `npm install --global`, sem alterar a configuração de accounts, e confirma a versão retornada pelo launcher global. Ele exige o npm disponível no `PATH` e permissões para alterar o prefixo global. Não substitui executáveis standalone baixados da GitHub Release. Exemplos: ```bash clickupfy upgrade ``` ```bash clickupfy upgrade latest ``` ```bash clickupfy upgrade next ``` ```bash clickupfy upgrade 0.5.0 ``` ```bash clickupfy upgrade v0.5.0 ``` O quinto exemplo normaliza o prefixo `v` antes de chamar o npm. Se o npm falhar ou o launcher não retornar uma versão SemVer, o comando encerra com erro e não declara a atualização como concluída. ### `clickupfy doctor` Verifica o setup local sem fazer chamadas à API do ClickUp. O diagnóstico confere o caminho `~/clickupfy/config.json` ou o caminho definido por `PROMOVAWEB_CLICKUPFY_CONFIG`, as permissões `0700` do diretório e `0600` do arquivo, o JSON, o schema, os accounts e o account ativo. Quando executado na raiz de um projeto, também verifica o gerenciador `skills`, as quatro skills do ClickUpfy, o idioma dos arquivos instalados e lê `.mcp.json` e `.codex/config.toml` se existirem. API keys nunca aparecem na saída. Os arquivos de projeto são opcionais. A ausência deles gera `skipped` porque o MCP só é necessário quando o projeto usa agentes. Um arquivo presente, mas inválido, gera `error`. O comando retorna código `1` quando existe uma verificação com erro. `warning` e `skipped` não reprovam o diagnóstico. Se o gerenciador `skills` não estiver instalado, ou se uma skill instalada estiver fora do padrão de português do Brasil, o diagnóstico registra essa situação para correção. Exemplos: ```bash clickupfy doctor ``` ```bash clickupfy --json doctor ``` ```bash PROMOVAWEB_CLICKUPFY_CONFIG=/tmp/clickupfy-config.json clickupfy doctor ``` ```bash cd ~/projetos/produto && clickupfy doctor ``` ```bash clickupfy --json doctor | jq '.checks[] | select(.estado == "error")' ``` O diagnóstico confirma a configuração local e os arquivos usados pelos agentes, mas não testa se a API key continua válida no ClickUp. Para essa verificação remota, use `clickupfy whoami`. ### `clickupfy install` Cria ou atualiza um perfil local e associa a API key a um workspace autorizado. Sem `--non-interactive`, o comando pergunta pelos valores ausentes. A API key fica no arquivo de configuração do usuário, cujo caminho aparece em `status`, ela não vai para o `.mcp.json` nem para o `.codex/config.toml` do projeto. | Parâmetro | Obrigatório | Uso | | ------------------- | ----------- | --------------------------------------------------------------- | | `--api-key ` | não | API key pessoal do ClickUp. `--token` é um alias compatível. | | `--name ` | não | Nome legível do perfil local. | | `--workspace ` | não | Workspace que será associado ao perfil. | | `--non-interactive` | não | Recusa prompts, use junto dos dados necessários para automação. | Exemplos: ```bash clickupfy install ``` ```bash clickupfy install --name "Produto" ``` ```bash clickupfy install --name "Cliente A" --workspace 123456 ``` ```bash clickupfy install --api-key "$CLICKUP_API_KEY" --name "Automação" ``` ```bash clickupfy install \ --api-key "$CLICKUP_API_KEY" \ --name "Produto" \ --workspace 123456 \ --non-interactive ``` Quando a API key for inválida, execute `whoami` para conferir a autenticação. Quando o workspace informado não pertencer à chave, selecione um workspace da lista devolvida pelo ClickUp. O comando nunca deve aparecer em histórico de shell com uma chave escrita diretamente, prefira uma variável de ambiente temporária ou a entrada interativa. ### `clickupfy status` Mostra o caminho de configuração, o perfil resolvido, se ele está ativo, o usuário e o workspace associado. A chave aparece mascarada. Use este comando como inspeção local, não como teste definitivo de uma chave recém-revogada. Exemplos: ```bash clickupfy status ``` ```bash clickupfy --json status ``` ```bash clickupfy --account produto status ``` ```bash clickupfy --account cliente-a --json status ``` ```bash clickupfy status > /tmp/clickupfy-status.txt ``` O quarto exemplo consulta o perfil `cliente-a` sem alterar o perfil que será usado pela próxima chamada sem `--account`. A redireção do último exemplo é segura porque a saída mascara a chave, mas ainda pode conter nomes de pessoas e workspaces. ## Perfis locais Um perfil é um conjunto local de API key, identidade autenticada e workspace selecionado. Cada perfil tem um identificador, como `produto` ou `cliente-a`. O identificador é usado com `--account` e pelo `--account` do servidor MCP. ### `clickupfy account list` Lista todos os perfis e marca o perfil ativo com `*`. Não revela API keys. `clickupfy account ls` é o alias equivalente. Exemplos: ```bash clickupfy account list ``` ```bash clickupfy account ls ``` ```bash clickupfy --json account list ``` ```bash clickupfy --account produto account list ``` ```bash clickupfy account list | less ``` Mesmo com `--account`, a lista continua mostrando todos os perfis, a opção só tem efeito quando uma ação precisa resolver uma conta. Use a tabela para conferir o identificador exato antes de chamar `account show`, `account use` ou um comando de trabalho. ### `clickupfy account show [perfil]` Exibe metadados seguros de um perfil. Sem argumento, resolve o perfil ativo ou o que foi indicado pela opção global `--account`. O argumento posicional tem precedência sobre a opção global quando os dois aparecem. | Parâmetro | Obrigatório | Uso | | ---------- | ----------- | ------------------------------ | | `[perfil]` | não | Identificador local do perfil. | Exemplos: ```bash clickupfy account show ``` ```bash clickupfy account show produto ``` ```bash clickupfy --account cliente-a account show ``` ```bash clickupfy --json account show produto ``` ```bash clickupfy --account cliente-a account show produto ``` No último caso, a saída é do perfil `produto`, pois o argumento posicional foi informado. Se o perfil não existir, o CLI interrompe a chamada sem iniciar uma requisição ao ClickUp. ### `clickupfy account use ` Define o perfil ativo no arquivo de configuração. É uma alteração local e não muda nada no ClickUp. Evite usar este comando em automações ou quando dois projetos usam contas diferentes ao mesmo tempo, nesses casos, informe `--account` em cada chamada ou fixe o perfil no MCP de cada projeto. | Parâmetro | Obrigatório | Uso | | ---------- | ----------- | ----------------------------------- | | `` | sim | Identificador local já configurado. | Exemplos: ```bash clickupfy account use produto ``` ```bash clickupfy account use cliente-a ``` ```bash clickupfy account use homologacao ``` ```bash clickupfy account use suporte ``` ```bash clickupfy account use produto && clickupfy status ``` O último exemplo confirma a mudança persistida. Quando o comando faz parte de um script, prefira não depender do perfil ativo: `clickupfy --account produto ...` deixa o destino explícito e não interfere no restante da máquina. ### `clickupfy account remove ` Remove somente o perfil local. Não revoga a API key no ClickUp, não remove usuários e não exclui tarefas. Em terminal interativo, pede confirmação. Em automação, `--yes` confirma a remoção sem prompt. | Parâmetro | Obrigatório | Uso | | ---------- | ----------- | ------------------------------ | | `` | sim | Identificador local a remover. | | `--yes` | não | Confirma sem interação. | Exemplos: ```bash clickupfy account remove conta-antiga ``` ```bash clickupfy account remove sandbox --yes ``` ```bash clickupfy account remove cliente-encerrado ``` ```bash clickupfy account remove homologacao --yes ``` ```bash clickupfy account remove temporario --yes && clickupfy account list ``` Se você remover o perfil ativo, o ClickUpfy torna ativo o primeiro perfil que sobrar ou deixa a configuração sem perfil ativo quando não houver outro. Leia `account list` após a remoção, especialmente em uma máquina compartilhada. ## Workspace e identidade autenticada O perfil tem um workspace associado, mas uma API key pode ter permissão para mais de um workspace. `workspace list` descobre as opções, `workspace use` persiste a escolha no perfil, `whoami` consulta a API e confirma o usuário. ### `clickupfy workspace list` Lista os workspaces que a API key do perfil consegue acessar. O marcador `*` indica o workspace atualmente associado ao perfil. `workspace ls` é um alias. Exemplos: ```bash clickupfy workspace list ``` ```bash clickupfy workspace ls ``` ```bash clickupfy --account produto workspace list ``` ```bash clickupfy --account cliente-a --json workspace list ``` ```bash clickupfy workspace list | tee /tmp/workspaces.txt ``` O resultado autoritativo vem da API. Caso o workspace esperado não apareça, verifique a permissão da API key no ClickUp em vez de tentar adivinhar um ID. ### `clickupfy workspace use ` Associa um workspace autorizado ao perfil resolvido. O CLI consulta a API e só salva o ID quando ele aparece na lista permitida, portanto um número copiado de outro perfil é recusado. | Parâmetro | Obrigatório | Uso | | ---------------- | ----------- | ---------------------------------- | | `` | sim | ID devolvido por `workspace list`. | Exemplos: ```bash clickupfy workspace use 123456 ``` ```bash clickupfy --account cliente-a workspace use 987654 ``` ```bash clickupfy --account produto workspace use 123456 ``` ```bash clickupfy workspace use 654321 && clickupfy status ``` ```bash clickupfy --account suporte workspace use 246810 ``` A alteração afeta o perfil indicado, não todos os perfis. Um servidor MCP com `--workspace` fixo ainda recusará um workspace diferente, mesmo que o perfil local seja alterado depois. ### `clickupfy whoami` Valida a API key em uma chamada ao ClickUp e devolve o usuário autenticado junto do perfil e do workspace resolvidos. Use-o depois de `setup`, após uma troca de chave ou ao investigar erro de autorização. Exemplos: ```bash clickupfy whoami ``` ```bash clickupfy --json whoami ``` ```bash clickupfy --account produto whoami ``` ```bash clickupfy --account cliente-a --json whoami ``` ```bash clickupfy whoami && clickupfy workspace list ``` Uma resposta de `status` não substitui este teste: ela lê a configuração local. `whoami` é a chamada que confirma se a chave ainda funciona no serviço remoto. ## Descoberta da hierarquia O ClickUp organiza trabalho em workspace, Space, Folder e List. Uma List pode existir diretamente dentro de um Space, sem Folder. IDs não são intercambiáveis: um `space-id` não serve no lugar de `folder-id`, por exemplo. Comece no workspace selecionado e preserve os IDs retornados em um local seguro. ### `clickupfy space list` Lista Spaces do workspace associado ao perfil. `--archived` acrescenta Spaces arquivados, sem a opção, o resultado contém apenas os ativos. | Parâmetro | Obrigatório | Uso | | ------------ | ----------- | ------------------------- | | `--archived` | não | Inclui Spaces arquivados. | Exemplos: ```bash clickupfy space list ``` ```bash clickupfy space ls ``` ```bash clickupfy space list --archived ``` ```bash clickupfy --account produto --json space list ``` ```bash clickupfy --account cliente-a space list --archived ``` Escolha o Space pelo ID e pelo nome retornados, não pela posição da linha. Spaces arquivados podem ser úteis em migração ou consulta histórica, mas não devem ser usados como destino de novas tarefas sem autorização explícita. ### `clickupfy folder list --space ` Lista Folders de um Space. O parâmetro `--space` é obrigatório, o CLI não usa um Space implícito porque um perfil pode operar em vários projetos. | Parâmetro | Obrigatório | Uso | | -------------- | ----------- | --------------------------------------- | | `--space ` | sim | ID do Space retornado por `space list`. | | `--archived` | não | Inclui Folders arquivados. | Exemplos: ```bash clickupfy folder list --space 1001 ``` ```bash clickupfy folder ls --space 1001 ``` ```bash clickupfy folder list --space 1001 --archived ``` ```bash clickupfy --account produto --json folder list --space 1001 ``` ```bash clickupfy --account cliente-a folder list --space 2001 --archived ``` Uma resposta vazia não significa necessariamente falta de acesso: o Space pode guardar Lists diretamente. Execute `list list --space ` para cobrir esse ramo da hierarquia. ### `clickupfy list list --folder | --space ` Lista Lists dentro de um Folder ou Lists que pertencem diretamente a um Space. Informe uma das duas opções. O CLI exige pelo menos uma, quando ambas forem fornecidas, a chamada deve apontar para o nível real que você pretende ler, mantendo um único destino por consulta. | Parâmetro | Obrigatório | Uso | | --------------- | ----------- | ---------------------------------- | | `--folder ` | condicional | ID do Folder que contém as Lists. | | `--space ` | condicional | ID do Space para Lists sem Folder. | | `--archived` | não | Inclui Lists arquivadas. | Exemplos: ```bash clickupfy list list --folder 2001 ``` ```bash clickupfy list ls --folder 2001 ``` ```bash clickupfy list list --folder 2001 --archived ``` ```bash clickupfy list list --space 1001 ``` ```bash clickupfy --account produto --json list list --space 1001 --archived ``` Consulte cada List pelo comando seguinte para obter os status configurados. Em projetos com MCP, o ID da List escolhido aqui será o valor obrigatório de `agent install --list` ou de `mcp serve --list`. ### `clickupfy list get ` Obtém a List e os status aceitos pelas tarefas dela. A grafia retornada para um status é a mesma que deve aparecer em `task create --status` e `task update --status`, não use uma tradução ou suposição local. | Parâmetro | Obrigatório | Uso | | ----------- | ----------- | ------------------------------------- | | `` | sim | ID da List retornado por `list list`. | Exemplos: ```bash clickupfy list get 3001 ``` ```bash clickupfy --json list get 3001 ``` ```bash clickupfy --account produto list get 3001 ``` ```bash clickupfy --account cliente-a --json list get 4001 ``` ```bash clickupfy list get 3001 > /tmp/list-3001.json ``` O último exemplo deve incluir `--json` quando o arquivo for consumido por outro programa. A tabela compacta é adequada para leitura, mas não é uma API estável de máquina. Continue em [tarefas e checklists](/docs/clickupfy/tarefas) para usar os status e IDs encontrados aqui. ### Referência CLI ClickUpfy: Sprints, tarefas e Sprint Points - URL: https://promovaweb.com/docs/clickupfy/referencia/cli-sprints - Descrição: Consulte os comandos do CLI ClickUpfy para Sprints e Sprint Points, com filtros de período, associação de tarefas, relatórios, limites e exemplos. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | consulta, relatório, associação de tarefas e Sprint Points no terminal | | Autoridade | `src/cli.ts`, `src/sprints.ts` e endpoints públicos do ClickUp usados pelo ClickUpfy | No ClickUpfy, uma Sprint é uma List dentro de um Sprint Folder que possui `start_date` e `due_date`. Uma List comum do mesmo Folder não entra no resultado por padrão. O CLI não cria Sprints, não habilita o ClickApp de Sprints e não altera datas de um ciclo: essas operações continuam na interface do ClickUp. ## Consulta de ciclos ### `clickupfy sprint list --folder ` Lista Sprints identificadas pelo período. `--folder` é obrigatório. Use `--include-regular` para diagnosticar um Folder misto e `--archived` para incluir Lists arquivadas. `--at` recebe uma data `AAAA-MM-DD` para calcular o estado do ciclo naquela data. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--folder ` | sim | Sprint Folder consultado. | | `--archived` | não | Inclui Lists arquivadas. | | `--include-regular` | não | Inclui Lists sem período configurado. | | `--at ` | não | Data usada no cálculo do estado. | Exemplos: ```bash clickupfy sprint list --folder 4001 ``` ```bash clickupfy sprint list --folder 4001 --at 2026-08-10 ``` ```bash clickupfy sprint list --folder 4001 --include-regular ``` ```bash clickupfy sprint list --folder 4001 --archived --include-regular ``` ```bash clickupfy --account produto --json sprint list --folder 4001 --at 2026-09-01 ``` Uma List sem início ou término aparece somente com `--include-regular`, ela não deve ser tratada como Sprint. Guarde o ID de uma Sprint retornada para os comandos de relatório e associação. ### `clickupfy sprint current --folder ` Encontra a única Sprint cujo período inclui a data atual ou a data indicada por `--at`. A consulta falha quando não existe ciclo ativo ou quando dois ciclos se sobrepõem, essa falha protege o planejamento contra uma seleção arbitrária. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--folder ` | sim | Sprint Folder consultado. | | `--at ` | não | Data usada para localizar a Sprint. | Exemplos: ```bash clickupfy sprint current --folder 4001 ``` ```bash clickupfy sprint current --folder 4001 --at 2026-08-10 ``` ```bash clickupfy sprint current --folder 4001 --at 2026-09-01 ``` ```bash clickupfy --account produto sprint current --folder 4001 ``` ```bash clickupfy --account cliente-a --json sprint current --folder 5001 --at 2026-10-15 ``` Corrija datas sobrepostas no ClickUp quando o comando falhar. Não passe uma List comum para `sprint get` como alternativa: o relatório depende do período da Sprint. ### `clickupfy sprint get ` Mostra período, estado temporal, total de tarefas, distribuição de status e progresso por quantidade e por Sprint Points. `--at` muda a leitura temporal, sem alterar a Sprint nem suas tarefas. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Sprint a analisar. | | `--at ` | não | Data usada no cálculo do estado. | Exemplos: ```bash clickupfy sprint get sprint-10 ``` ```bash clickupfy sprint get sprint-10 --at 2026-08-10 ``` ```bash clickupfy sprint get sprint-11 ``` ```bash clickupfy --account produto sprint get sprint-10 ``` ```bash clickupfy --account cliente-a --json sprint get sprint-22 --at 2026-09-01 ``` Uma tarefa sem Points entra no total de tarefas, mas não adiciona peso ao progresso por pontos. Consulte `sprint tasks` para inspecionar as tarefas que compõem esses números. ### `clickupfy sprint tasks ` Lista tarefas associadas à Sprint. Por padrão, inclui tarefas concluídas. `--open-only` omite itens fechados e serve para a fila de trabalho atual, não para conferir o resultado final do ciclo. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Sprint consultada. | | `--open-only` | não | Omite tarefas concluídas. | Exemplos: ```bash clickupfy sprint tasks sprint-10 ``` ```bash clickupfy sprint tasks sprint-10 --open-only ``` ```bash clickupfy sprint tasks sprint-11 ``` ```bash clickupfy --account produto sprint tasks sprint-10 --open-only ``` ```bash clickupfy --account cliente-a --json sprint tasks sprint-22 ``` O retorno é um resumo de tarefas. Para obter descrição, subtarefas e checklist items de uma tarefa, execute `clickupfy task get `. ## Alterações no planejamento ### `clickupfy sprint add-task ` Associa uma tarefa existente a uma Sprint sem trocar sua List principal. Isso permite manter a tarefa no backlog e no ciclo atual ao mesmo tempo. A operação não cria cópia, não move a tarefa e não modifica status. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Sprint de destino. | | `` | sim | Tarefa que será associada. | Exemplos: ```bash clickupfy sprint add-task sprint-10 86abc123 ``` ```bash clickupfy sprint add-task sprint-10 77def456 ``` ```bash clickupfy --account produto sprint add-task sprint-10 86abc123 ``` ```bash clickupfy --account cliente-a sprint add-task sprint-22 55ghi789 ``` ```bash clickupfy --json sprint add-task sprint-10 99jkl012 ``` Reler `sprint tasks ` confirma a associação. Só execute essa ação quando o planejamento da Sprint estiver no escopo autorizado. ### `clickupfy sprint remove-task ` Remove a associação entre tarefa e Sprint. A tarefa continua existindo na List principal e não perde seus comentários, checklist, tempo ou histórico. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Sprint cuja associação será removida. | | `` | sim | Tarefa associada. | Exemplos: ```bash clickupfy sprint remove-task sprint-10 86abc123 ``` ```bash clickupfy sprint remove-task sprint-10 77def456 ``` ```bash clickupfy --account produto sprint remove-task sprint-10 86abc123 ``` ```bash clickupfy --account cliente-a sprint remove-task sprint-22 55ghi789 ``` ```bash clickupfy --json sprint remove-task sprint-10 99jkl012 ``` Para excluir uma tarefa, use `task delete` apenas com autorização explícita. Para confirmar que a associação saiu, releia a Sprint e a tarefa depois desta operação. ### `clickupfy sprint set-points ` Define Sprint Points de uma tarefa. O número deve ser igual ou maior que zero. O ClickUpfy não interpreta a escala: a equipe define se `1`, `2`, `3`, `5` ou outros valores representam tamanho, esforço ou complexidade. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa que receberá pontos. | | `` | sim | Número não negativo. | Exemplos: ```bash clickupfy sprint set-points 86abc123 0 ``` ```bash clickupfy sprint set-points 86abc123 1 ``` ```bash clickupfy sprint set-points 86abc123 3 ``` ```bash clickupfy --account produto sprint set-points 86abc123 5 ``` ```bash clickupfy --account cliente-a --json sprint set-points 77def456 8 ``` `task update --points ` atualiza o mesmo campo. Use apenas uma das interfaces por alteração e releia a tarefa para confirmar o valor salvo. ### CLI ClickUpfy: tarefas, checklists, comentários e tempo - URL: https://promovaweb.com/docs/clickupfy/referencia/cli-tarefas - Descrição: Consulte comandos do CLI ClickUpfy para tarefas, checklists, comentários e tempo, com filtros, parâmetros, confirmações, saídas e exemplos no terminal. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | comandos de consulta e alteração de tarefas, checklists, comentários e time tracking | | Autoridade | `src/cli.ts`, `src/work-items.ts`, `src/clickup.ts` e ajuda da versão instalada | Os IDs deste capítulo são fictícios. Use `list get` para obter a grafia dos status e `task get --json` para encontrar IDs de checklist items. Uma chamada de escrita deve ser seguida por uma nova leitura do recurso alterado, a ausência de erro não confirma que o ClickUp persistiu o valor esperado. ## Leitura de tarefas ### `clickupfy task list --list ` Lista tarefas de uma List em uma página. `--list` é obrigatório porque o CLI não lê o `.mcp.json` do projeto. `--status` aceita um ou mais nomes de status, `--assignee` recebe um ou mais IDs de responsáveis, `--page` começa em zero. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--list ` | sim | List consultada. | | `--status ` | não | Restringe aos status informados. | | `--assignee ` | não | Restringe aos responsáveis. | | `--include-closed` | não | Inclui tarefas concluídas. | | `--page ` | não | Página, iniciando em `0`. | Exemplos: ```bash clickupfy task list --list 3001 ``` ```bash clickupfy task list --list 3001 --status "em andamento" ``` ```bash clickupfy task list --list 3001 --status aberta "em andamento" --assignee 42 ``` ```bash clickupfy task list --list 3001 --include-closed --page 0 ``` ```bash clickupfy --account produto --json task list --list 3001 --page 2 ``` A saída comum é uma tabela com ID, nome, status, prioridade, pontos, pessoas e link. Use `--json` quando um script precisar de todos os campos retornados pela API. Para encontrar uma tarefa fora de uma List conhecida, use `task search`. ### `clickupfy task get ` Obtém uma tarefa e prepara uma fila chamada `execution`, que inclui tarefa, subtarefas e checklist items em uma ordem estável. Sem opção de formato, imprime uma tabela compacta da fila. `--json` mostra a estrutura, `--markdown` junta metadados, descrição e itens em um documento, `--raw` mostra apenas a resposta original da API. Escolha exatamente um desses formatos. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa raiz a consultar. | | `--raw` | não | Retorna somente a resposta original do ClickUp. | | `--markdown` | não | Renderiza descrição e fila em Markdown. | | `--json` | não | Opção global que devolve tarefa e fila estruturada. | Exemplos: ```bash clickupfy task get 86abc123 ``` ```bash clickupfy task get 86abc123 --markdown ``` ```bash clickupfy task get 86abc123 --raw ``` ```bash clickupfy --json task get 86abc123 ``` ```bash clickupfy --account produto task get 86abc123 --markdown ``` `execution.items` usa `task:` para tarefas e subtarefas e `checklist::` para itens de checklist. `parentKey` e `depth` preservam a relação de parentesco. Não tente combinar `--raw`, `--markdown` e `--json`: o CLI recusa a ambiguidade de formato. ### `clickupfy task search` Busca tarefas em todo o workspace associado ao perfil. É uma consulta paginada, limitada por `--max-pages`, que começa em uma e aceita no máximo cem páginas. O texto de `--query` procura nome, descrição ou ID. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--query ` | não | Termo de busca no nome, descrição ou ID. | | `--status ` | não | Filtra por status. | | `--assignee ` | não | Filtra por responsáveis. | | `--include-closed` | não | Inclui tarefas concluídas. | | `--max-pages ` | não | Limite entre `1` e `100`, o padrão é `100`. | Exemplos: ```bash clickupfy task search --query "autenticação" ``` ```bash clickupfy task search --query 86abc123 ``` ```bash clickupfy task search --query "API" --status "em andamento" ``` ```bash clickupfy task search --assignee 42 --include-closed --max-pages 5 ``` ```bash clickupfy --account cliente-a --json task search --query "checkout" --max-pages 10 ``` Se mais de uma tarefa corresponder ao pedido, apresente os IDs e nomes para a pessoa escolher a correta antes de executar uma escrita. Em MCP de projeto, use `clickupfy_tasks_search`: essa ferramenta é limitada à List fixa, enquanto este comando percorre o workspace inteiro. ## Criação e atualização de tarefas ### `clickupfy task create` Cria tarefa ou subtarefa na List indicada. `--list` e `--name` são obrigatórios. Use `--description` para texto simples ou `--markdown-content` quando a descrição precisa preservar Markdown. O CLI não impõe uma regra de prioridade, status ou pontos do seu time, ele transmite valores válidos para a API. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--list ` | sim | List de destino. | | `--name ` | sim | Nome da tarefa. | | `--description ` | não | Descrição em texto. | | `--markdown-content ` | não | Descrição em Markdown. | | `--status ` | não | Status inicial existente na List. | | `--priority ` | não | `1` urgente, `2` alta, `3` normal, `4` baixa. | | `--assignee ` | não | IDs numéricos das pessoas responsáveis. | | `--parent ` | não | Cria como subtarefa da tarefa informada. | | `--start-date ` | não | Data de início. | | `--due-date ` | não | Data de entrega. | | `--points ` | não | Sprint Points iguais ou maiores que zero. | Exemplos: ```bash clickupfy task create --list 3001 --name "Corrigir retorno da API" ``` ```bash clickupfy task create \ --list 3001 \ --name "Documentar autenticação" \ --description "Explicar o fluxo de login." ``` ```bash clickupfy task create \ --list 3001 \ --name "Criar testes" \ --markdown-content "## Casos\n\n- Login válido\n- Senha inválida" ``` ```bash clickupfy task create \ --list 3001 \ --name "Implementar refresh token" \ --status "em andamento" \ --priority 2 \ --assignee 42 57 \ --start-date 2026-08-10 \ --due-date 2026-08-14 \ --points 5 ``` ```bash clickupfy --account produto task create \ --list 3001 \ --parent 86abc123 \ --name "Cobrir expiração de sessão" \ --markdown-content "Adicionar casos de teste para sessão expirada." ``` Consulte `clickupfy list get ` para copiar o status exato. Depois da criação, guarde o ID devolvido e chame `task get` para confirmar pai, datas, responsáveis e conteúdo. Não use `--parent` para mover uma tarefa existente, ele só define o pai na criação. ### `clickupfy task update ` Atualiza campos de uma tarefa existente. Pelo menos um campo é obrigatório. `--clear-start-date` e `--clear-due-date` removem as respectivas datas, quando uma flag de remoção e uma nova data aparecem juntas, a remoção prevalece. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa a alterar. | | `--name ` | não | Novo nome. | | `--description ` | não | Nova descrição textual. | | `--markdown-content ` | não | Nova descrição em Markdown. | | `--status ` | não | Status existente na List. | | `--priority ` | não | Prioridade de `1` a `4`. | | `--start-date ` | não | Nova data de início. | | `--clear-start-date` | não | Remove a data de início. | | `--due-date ` | não | Nova data de entrega. | | `--clear-due-date` | não | Remove a data de entrega. | | `--points ` | não | Sprint Points não negativos. | Exemplos: ```bash clickupfy task update 86abc123 --status "em andamento" ``` ```bash clickupfy task update 86abc123 --name "Corrigir autenticação por token" ``` ```bash clickupfy task update 86abc123 --priority 1 --points 8 ``` ```bash clickupfy task update 86abc123 --start-date 2026-08-10 --due-date 2026-08-14 ``` ```bash clickupfy --account produto task update 86abc123 --markdown-content "## Entrega\n\nPublicar a documentação atualizada." --clear-due-date ``` `--description` e `--markdown-content` representam alternativas de conteúdo, envie apenas a forma que você quer persistir. Uma atualização de status precisa usar a grafia devolvida por `list get`. Releia a tarefa depois da escrita e compare cada campo solicitado com o estado devolvido. ### `clickupfy task delete ` Exclui permanentemente uma tarefa. Em terminal interativo, pede confirmação, em automação, exige `--yes`. Leia nome, List e relação com Sprint antes de executar. A exclusão não é uma forma de retirar a tarefa de uma Sprint: use `sprint remove-task` para remover apenas a associação. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa a excluir. | | `--yes` | não | Confirma a exclusão sem prompt. | Exemplos: ```bash clickupfy task delete 86abc123 ``` ```bash clickupfy task delete 86abc123 --yes ``` ```bash clickupfy --account produto task delete 86abc123 ``` ```bash clickupfy --account cliente-a task delete 77def456 --yes ``` ```bash clickupfy task get 86abc123 && clickupfy task delete 86abc123 --yes ``` O último exemplo lê a tarefa no mesmo terminal, mas ainda exige que você compare o resultado e tenha autorização explícita. No MCP, a ferramenta equivalente exige o campo literal `confirm: true`. ## Checklists e comentários ### `clickupfy checklist create --name ` Cria um checklist vazio em uma tarefa. Os itens são criados pelo comando seguinte. Use um nome que indique a finalidade, como `Testes`, `Publicação` ou `Revisão manual`. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa proprietária. | | `--name ` | sim | Nome do checklist. | Exemplos: ```bash clickupfy checklist create 86abc123 --name "Testes" ``` ```bash clickupfy checklist create 86abc123 --name "Revisão de segurança" ``` ```bash clickupfy checklist create 77def456 --name "Publicação" ``` ```bash clickupfy --account produto checklist create 86abc123 --name "Aceite" ``` ```bash clickupfy --json checklist create 86abc123 --name "Regressão" ``` Guarde o ID retornado: `item-create` usa o ID do checklist, não o ID da tarefa. Crie o checklist na tarefa que realmente possui os itens, uma subtarefa pode ter checklist próprio e não deve receber os itens da tarefa pai por acidente. ### `clickupfy checklist item-create --name ` Acrescenta um item aberto a um checklist. `--assignee` é opcional e recebe um ID numérico. O comando não aceita o ID da tarefa porque o checklist já define seu proprietário. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Checklist que receberá o item. | | `--name ` | sim | Texto do item. | | `--assignee ` | não | ID do responsável pelo item. | Exemplos: ```bash clickupfy checklist item-create check-1 --name "Executar testes unitários" ``` ```bash clickupfy checklist item-create check-1 --name "Executar build" ``` ```bash clickupfy checklist item-create check-1 --name "Revisar documentação" --assignee 42 ``` ```bash clickupfy --account produto checklist item-create check-2 --name "Conferir changelog" ``` ```bash clickupfy --json checklist item-create check-3 --name "Validar publicação" --assignee 57 ``` Um item deve descrever uma verificação observável, não uma promessa genérica. Depois de criar itens, execute `task get --json` para localizar o `item-id` e confirmar que todos começam abertos. ### `clickupfy checklist set ` Marca um item como concluído com `--resolved` ou o reabre com `--open`. Escolha exatamente uma flag. O ClickUpfy primeiro confirma que o item pertence à tarefa raiz informada, grava o estado e relê a tarefa para confirmar o resultado. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `` | sim | Tarefa raiz usada para validar a associação. | | `` | sim | Checklist proprietário. | | `` | sim | Item a alterar. | | `--resolved` | condicional | Marca como concluído. | | `--open` | condicional | Reabre o item. | Exemplos: ```bash clickupfy checklist set 86abc123 check-1 item-1 --resolved ``` ```bash clickupfy checklist set 86abc123 check-1 item-1 --open ``` ```bash clickupfy --account produto checklist set 86abc123 check-2 item-4 --resolved ``` ```bash clickupfy --json checklist set 77def456 check-3 item-2 --resolved ``` ```bash clickupfy checklist set 77def456 check-3 item-2 --open ``` Não use `--resolved --open` nem omita ambas: o CLI recusa as duas situações. Um `item-id` de outro checklist também é recusado pela releitura. Marque o item somente depois da validação correspondente. ### `clickupfy comment list --task ` Lista os comentários de uma tarefa com autoria, data e texto. A API pode representar o conteúdo em formatos diferentes, o ClickUpfy o normaliza para a coluna `text` na tabela compacta. Exemplos: ```bash clickupfy comment list --task 86abc123 ``` ```bash clickupfy comment ls --task 86abc123 ``` ```bash clickupfy --json comment list --task 86abc123 ``` ```bash clickupfy --account produto comment list --task 86abc123 ``` ```bash clickupfy --account cliente-a --json comment list --task 77def456 ``` Leia os comentários antes de atualizar status ou publicar outro progresso, pois podem conter uma orientação nova. Nunca publique credenciais, dados pessoais, URLs assinadas ou logs extensos em um comentário. ### `clickupfy comment create --task --text ` Publica um comentário em uma tarefa. `--notify-all` pede ao ClickUp que notifique todos os participantes. Use o comando para registrar início, resultado de teste, mudança de escopo ou conclusão, sempre com informação verificável. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--task ` | sim | Tarefa que receberá o comentário. | | `--text ` | sim | Conteúdo do comentário. | | `--notify-all` | não | Notifica participantes da tarefa. | Exemplos: ```bash clickupfy comment create --task 86abc123 --text "Iniciei a análise da tarefa." ``` ```bash clickupfy comment create --task 86abc123 --text "Os testes unitários passaram." ``` ```bash clickupfy comment create --task 86abc123 --text "Aguardando acesso ao ambiente de homologação." --notify-all ``` ```bash clickupfy --account produto comment create --task 86abc123 --text "Documentação e ebook foram atualizados." ``` ```bash clickupfy --json comment create --task 77def456 --text "Validação final concluída." --notify-all ``` Reler `comment list` confirma que o comentário ficou na tarefa pretendida e que o texto chegou completo. O comando não modifica status, timer ou checklist. ## Time tracking ### `clickupfy time current` Consulta o time entry em execução no workspace associado ao perfil. Chame este comando antes de `time start` para não iniciar outro registro sem saber qual tarefa já está em andamento. Exemplos: ```bash clickupfy time current ``` ```bash clickupfy --json time current ``` ```bash clickupfy --account produto time current ``` ```bash clickupfy --account cliente-a --json time current ``` ```bash clickupfy time current && clickupfy task get 86abc123 ``` Se houver entrada ativa para outra tarefa, pare e peça orientação antes de usar `time stop`. O comando é somente leitura e não altera status ou comentários. ### `clickupfy time start --task ` Inicia um time entry associado à tarefa. A descrição é opcional e deve dizer o trabalho em curso. O registro pertence ao usuário autenticado pelo perfil e ao workspace desse perfil. | Parâmetro | Obrigatório | Uso | | --- | --- | --- | | `--task ` | sim | Tarefa associada ao tempo. | | `--description ` | não | Descrição curta do trabalho. | Exemplos: ```bash clickupfy time start --task 86abc123 ``` ```bash clickupfy time start --task 86abc123 --description "Implementação" ``` ```bash clickupfy time start --task 86abc123 --description "Testes de regressão" ``` ```bash clickupfy --account produto time start --task 86abc123 --description "Revisão de documentação" ``` ```bash clickupfy --account cliente-a time start --task 77def456 --description "Correção da integração" ``` Depois da chamada, execute `time current` para confirmar o item ativo. Iniciar um timer não muda o status da tarefa nem avisa participantes, essas ações usam `task update` e `comment create` separadamente. ### `clickupfy time stop` Encerra o time entry em execução no workspace do perfil. Não recebe argumento de tarefa: ele para o registro atual. Por isso a consulta anterior é necessária em trabalhos paralelos ou quando mais de uma pessoa usa o mesmo perfil local. Exemplos: ```bash clickupfy time stop ``` ```bash clickupfy --account produto time stop ``` ```bash clickupfy --account cliente-a time stop ``` ```bash clickupfy time stop && clickupfy time current ``` ```bash clickupfy --json time stop ``` O quarto exemplo verifica que não há entrada em execução após o encerramento. Parar o tempo não fecha tarefa, não altera seus pontos e não resolve checklist items. Registre a conclusão do trabalho nas interfaces próprias se elas também forem autorizadas. ### Referência MCP do ClickUpfy: contexto, perfis e hierarquia - URL: https://promovaweb.com/docs/clickupfy/referencia/mcp-contexto-hierarquia - Descrição: Consulte as ferramentas MCP do ClickUpfy para perfil, workspace e hierarquia, com IDs fixos, escopo por projeto, recusas e exemplos de chamadas úteis. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | ferramentas MCP de identificação do projeto, perfis e navegação na hierarquia do ClickUp | | Autoridade | schemas e handlers de `src/mcp.ts` | Este capítulo registra as ferramentas de leitura que permitem descobrir o destino do servidor MCP sem alterar o ClickUp. Cada exemplo representa os argumentos enviados em uma chamada de ferramenta. O cliente MCP é responsável por transportar esse objeto, não execute esses blocos diretamente no shell. O servidor pode fixar `account`, `workspaceId`, `spaceId`, `folderId` e `listId` quando é iniciado. Quando um ID fixado recebe um valor diferente, a chamada é recusada. O campo `account` é opcional nas ferramentas que o aceitam, mas também será recusado se divergir do perfil fixado. Nenhuma ferramenta deste capítulo devolve a API key. ## Ferramentas de identificação ### `clickupfy_mcp_context` Mostra o perfil resolvido, o workspace associado e a hierarquia fixada pelo processo MCP. Execute-a como primeira chamada de um agente: ela informa quais IDs podem ser omitidos nas ferramentas seguintes e se o projeto tem `sprintFolderId`. O único argumento aceito é `account`, opcional. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver quando o processo não o fixou. | Exemplos: ```json {} ``` ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` Uma chamada sem argumento não seleciona outro perfil: ela usa o perfil fixado ou o perfil ativo do arquivo local. Guarde os valores de `scope` durante a sessão. O campo `listId` sempre existe porque `mcp serve --list` é obrigatório. ### `clickupfy_accounts_list` Lista todos os perfis configurados na máquina, com nome, usuário, workspace e marca do perfil ativo. Ela não recebe argumentos e não faz requisição à API do ClickUp. Use-a para localizar o identificador de um perfil, nunca para obter uma credencial. Exemplos: ```json {} ``` ```json {} ``` ```json {} ``` ```json {} ``` ```json {} ``` Os cinco exemplos são idênticos porque a ferramenta não possui parâmetro. Em um cliente com chamada nomeada, a variação fica no nome da ferramenta, não nos argumentos: `clickupfy_accounts_list` sempre recebe o objeto vazio. Esse fato é importante para agentes: não invente filtros como `workspace`, `query` ou `includeArchived`, pois o schema os rejeita. ### `clickupfy_whoami` Valida o perfil escolhido na API do ClickUp e retorna o usuário autenticado, além do workspace associado ao perfil. É a confirmação remota para uma chave que pode ter sido revogada ou cujas permissões acabaram de mudar. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil que será autenticado. | Exemplos: ```json {} ``` ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` Quando `account` for omitido, o mesmo resolvedor usado por `clickupfy_mcp_context` escolhe o perfil. Uma resposta bem-sucedida prova que a chave funciona naquele momento, não prova permissão para uma List específica. Consulte `clickupfy_mcp_context` e `clickupfy_list_get` para conferir o destino do projeto e os status permitidos. ### `clickupfy_workspaces_list` Lista os workspaces autorizados pela API key do perfil. Ela não recebe ID de workspace porque consulta todos os workspaces acessíveis e o servidor usa o perfil para autenticar a chamada. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil cuja chave será usada na consulta. | Exemplos: ```json {} ``` ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` Essa ferramenta apenas lê os workspaces. Para alterar a associação do perfil, `clickupfy_workspace_use` só fica disponível quando o servidor tem escrita e não foi iniciado com `--account` nem `--workspace`. O valor retornado aqui deve ser usado literalmente nessa ferramenta de escrita ou no CLI. ## Ferramentas de navegação ### `clickupfy_spaces_list` Lista Spaces do workspace associado ao perfil. A ferramenta usa o workspace do perfil ou o que foi fixado no processo. `archived` é opcional e, quando verdadeiro, acrescenta Spaces arquivados. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil usado para a consulta. | | `archived` | booleano | não | Inclui Spaces arquivados quando vale `true`. | Exemplos: ```json {} ``` ```json {"archived":true} ``` ```json {"account":"produto"} ``` ```json {"account":"produto","archived":true} ``` ```json {"account":"cliente-a","archived":false} ``` O valor `false` é diferente de omitir o campo apenas para deixar a intenção explícita no registro do agente, os dois retornam somente recursos ativos. Escolha um `id` da resposta para chamar `clickupfy_folders_list` ou `clickupfy_lists_list`. ### `clickupfy_folders_list` Lista Folders de um Space. Quando o servidor foi iniciado com `--space`, omita `spaceId` para usar o valor fixado. Quando não há Space fixo, o campo é necessário. Um ID diferente do fixado é recusado para preservar o isolamento do projeto. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil usado para a consulta. | | `spaceId` | string | condicional | Space a consultar, obrigatório sem Space fixo. | | `archived` | booleano | não | Inclui Folders arquivados. | Exemplos: ```json {} ``` ```json {"spaceId":"1001"} ``` ```json {"spaceId":"1001","archived":true} ``` ```json {"account":"produto","spaceId":"1001"} ``` ```json {"account":"cliente-a","spaceId":"2001","archived":false} ``` O primeiro exemplo só funciona quando o processo MCP já recebeu `--space`. Uma resposta vazia pode significar que o Space guarda Lists diretamente, ela não autoriza assumir que o projeto não tem Lists. Nesse caso, consulte `clickupfy_lists_list` com `spaceId`. ### `clickupfy_lists_list` Lista Lists de um Folder ou Lists criadas diretamente em um Space. O servidor resolve `folderId` e `spaceId` contra os IDs fixados. Quando um Folder é resolvido, ele tem precedência e o Space não é enviado à API. Sem Folder e sem Space, a ferramenta recusa a chamada porque não há nível da hierarquia para consultar. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil usado para a consulta. | | `folderId` | string | condicional | Folder que contém as Lists. | | `spaceId` | string | condicional | Space usado quando as Lists não pertencem a Folder. | | `archived` | booleano | não | Inclui Lists arquivadas. | Exemplos: ```json {} ``` ```json {"folderId":"2001"} ``` ```json {"folderId":"2001","archived":true} ``` ```json {"spaceId":"1001"} ``` ```json {"account":"produto","spaceId":"1001","archived":false} ``` A primeira chamada exige que o processo tenha iniciado com `--folder` ou `--space`. Não passe IDs de ambos os níveis para tentar ampliar a resposta. A separação permite que o agente descubra a hierarquia sem atravessar o destino do projeto. ### `clickupfy_list_get` Obtém os metadados de uma List e os status aceitos por suas tarefas. A List fixada no processo é a escolha normal: omita `listId` para usá-la. Só informe o campo em um MCP sem List fixa, situação que não ocorre no comando público `mcp serve`, ou para repetir exatamente o ID fixado. | Campo | Tipo | Obrigatório | Efeito | | --- | --- | --- | --- | | `account` | string | não | Perfil usado para a consulta. | | `listId` | string | não no MCP do projeto | List a obter, omita para usar a List fixada. | Exemplos: ```json {} ``` ```json {"listId":"3001"} ``` ```json {"account":"produto"} ``` ```json {"account":"produto","listId":"3001"} ``` ```json {"account":"cliente-a","listId":"4001"} ``` Leia os nomes dos status retornados antes de chamar uma ferramenta que crie ou atualize tarefa. `status` não é um conjunto global do ClickUp: uma grafia como `em revisão` pode existir em uma List e ser recusada em outra. Esta ferramenta não altera o status de nenhuma tarefa. ### Referência MCP do ClickUpfy: Docs e administração de perfil - URL: https://promovaweb.com/docs/clickupfy/referencia/mcp-docs-administracao - Descrição: Consulte as ferramentas MCP do ClickUpfy para Docs, páginas, perfis e workspaces, com permissões, limites de escrita e exemplos de chamadas JSON. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | ferramentas MCP de Docs do ClickUp, seleção de perfil e seleção de workspace | | Autoridade | schemas e handlers de `src/mcp.ts` e cliente de Docs em `src/clickup.ts` | As ferramentas de Docs sempre usam o workspace resolvido pelo perfil, sem aplicar o isolamento de Space, Folder ou List do projeto. As ferramentas de seleção de perfil e workspace só são registradas quando o servidor tem escrita e não recebeu os respectivos valores fixos. Objetos JSON a seguir representam os argumentos de uma chamada MCP, IDs são fictícios. ## Leitura de Docs ### `clickupfy_docs_list` Busca Docs do workspace do perfil. `maxPages` aceita inteiros de `1` a `50`. Quando `parentId` for informado, `parentType` informa o tipo do local: `4` Space, `5` Folder, `6` List, `7` Everything ou `12` tarefa. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `query` | string | não | Nome ou ID do Doc. | | `parentId` | string | não | Local pai do Doc. | | `parentType` | inteiro | não | Tipo de `parentId`. | | `deleted`, `archived` | booleano | não | Inclui Docs excluídos ou arquivados. | | `creator` | inteiro | não | Pessoa criadora. | | `maxPages` | inteiro | não | Cursor de `1` a `50`. | Exemplos: ```json {} ``` ```json {"query":"API"} ``` ```json {"parentId":"3001","parentType":6} ``` ```json {"archived":true,"deleted":true,"creator":42,"maxPages":10} ``` ```json {"account":"produto","query":"Manual","maxPages":5} ``` Use o ID retornado em `clickupfy_doc_get`, `clickupfy_doc_page_tree` ou uma ferramenta de página. A busca não devolve automaticamente todo conteúdo das páginas e não se limita à List fixada pelo MCP. ### `clickupfy_doc_get` Obtém metadados de um Doc. O corpo pertence às páginas, por isso esta ferramenta é indicada para confirmar nome, local e estado do Doc antes de consultar ou alterar uma página. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `docId` | string | sim | Doc a obter. | Exemplos: ```json {"docId":"doc-1"} ``` ```json {"docId":"doc-22"} ``` ```json {"account":"produto","docId":"doc-1"} ``` ```json {"account":"cliente-a","docId":"doc-22"} ``` ```json {"account":"homologacao","docId":"doc-33"} ``` Se o Doc não pertencer ao workspace do perfil, a API recusa a chamada. Não substitua `docId` por `pageId`: os dois identificadores pertencem a recursos distintos. ### `clickupfy_doc_page_tree` Retorna a hierarquia de páginas de um Doc sem trazer seus conteúdos. É a escolha adequada para localizar `pageId`, parentesco e profundidade antes de criar uma subpágina ou atualizar uma página existente. Exemplos: ```json {"docId":"doc-1"} ``` ```json {"docId":"doc-22"} ``` ```json {"account":"produto","docId":"doc-1"} ``` ```json {"account":"cliente-a","docId":"doc-22"} ``` ```json {"account":"homologacao","docId":"doc-33"} ``` Essa ferramenta não é uma cópia de segurança do texto. Use `clickupfy_doc_pages_list` para ler muitas páginas ou `clickupfy_doc_page_get` para ler uma página conhecida. ### `clickupfy_doc_pages_list` Lista páginas de um Doc com conteúdo. `maxPageDepth` limita o retorno de subpáginas. `contentFormat` aceita a forma usada pela API, normalmente `text/md` ou `text/plain`, quando omitido, a API usa `text/md`. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `docId` | string | sim | Doc cujas páginas serão lidas. | | `maxPageDepth` | inteiro | não | Profundidade máxima de subpáginas. | | `contentFormat` | string | não | Forma do conteúdo, como `text/md`. | Exemplos: ```json {"docId":"doc-1"} ``` ```json {"docId":"doc-1","maxPageDepth":1} ``` ```json {"docId":"doc-1","maxPageDepth":3} ``` ```json {"docId":"doc-1","contentFormat":"text/plain"} ``` ```json {"account":"produto","docId":"doc-1","contentFormat":"text/md"} ``` Leia somente a profundidade necessária para reduzir conteúdo irrelevante na conversa do agente. A ferramenta não modifica o Doc nem a árvore. ### `clickupfy_doc_page_get` Obtém uma página específica e seu conteúdo. O `pageId` deve pertencer ao Doc informado, localize-o pela árvore ou pela listagem de páginas. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `docId` | string | sim | Doc proprietário. | | `pageId` | string | sim | Página a obter. | | `contentFormat` | string | não | Forma do conteúdo. | Exemplos: ```json {"docId":"doc-1","pageId":"page-1"} ``` ```json {"docId":"doc-1","pageId":"page-1","contentFormat":"text/plain"} ``` ```json {"docId":"doc-1","pageId":"page-2","contentFormat":"text/md"} ``` ```json {"account":"produto","docId":"doc-1","pageId":"page-1"} ``` ```json {"account":"cliente-a","docId":"doc-22","pageId":"page-8"} ``` ## Escrita de Docs As três ferramentas seguintes não aparecem em read-only. A API pública usada pelo ClickUpfy não expõe ferramentas para excluir Docs ou páginas, mudar permissões de um Doc existente ou reordenar a árvore depois da criação. ### `clickupfy_doc_create` Cria Doc no workspace. `name` é obrigatório. Quando `parentId` é informado, `parentType` também é obrigatório. `visibility` pode ser `PRIVATE` ou `PUBLIC`, `createPage` cria uma página em branco junto do Doc. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `name` | string | sim | Nome do Doc. | | `parentId` | string | não | Local pai. | | `parentType` | inteiro | condicional | Tipo do local pai. | | `visibility` | string | não | Visibilidade do novo Doc. | | `createPage` | booleano | não | Cria a primeira página vazia. | Exemplos: ```json {"name":"Manual da API"} ``` ```json {"name":"Guia do produto","createPage":true} ``` ```json {"name":"Notas da List","parentId":"3001","parentType":6} ``` ```json {"name":"Documento interno","parentId":"2001","parentType":5,"visibility":"PRIVATE"} ``` ```json {"account":"produto","name":"Plano de release","parentId":"86abc123","parentType":12,"createPage":true} ``` Chame `clickupfy_doc_get` depois da criação e use o ID devolvido para criar as páginas. Quando houver `parentId` sem `parentType`, o servidor recusa a chamada antes de tocar na API. ### `clickupfy_doc_page_create` Cria página ou subpágina em um Doc. `name` é obrigatório. `parentPageId` define o pai, `orderindex` indica a posição entre páginas irmãs. O conteúdo e o subtítulo são opcionais. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account`, `docId` | string | `docId` sim | Perfil e Doc proprietário. | | `name` | string | sim | Título. | | `content`, `subTitle` | string | não | Corpo e subtítulo iniciais. | | `parentPageId` | string | não | Página pai. | | `orderindex` | número | não | Posição entre páginas irmãs. | | `contentFormat` | string | não | Forma do conteúdo. | Exemplos: ```json {"docId":"doc-1","name":"Introdução"} ``` ```json {"docId":"doc-1","name":"Autenticação","content":"Use uma API key pessoal."} ``` ```json {"docId":"doc-1","name":"Detalhes","subTitle":"Campos e respostas","content":"## Parâmetros"} ``` ```json {"docId":"doc-1","name":"Erros","parentPageId":"page-1","orderindex":2} ``` ```json {"account":"produto","docId":"doc-1","name":"Integração","content":"# MCP","contentFormat":"text/md"} ``` ### `clickupfy_doc_page_update` Atualiza título, subtítulo e/ou conteúdo. O schema recusa chamada sem campo de alteração. `contentEditMode` aceita `replace`, `append` ou `prepend`, o padrão é `replace`. O modo afeta somente `content` e não o título ou subtítulo. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account`, `docId`, `pageId` | string | Doc e página sim | Recurso a alterar. | | `name`, `subTitle`, `content` | string | ao menos um | Campos a persistir. | | `contentEditMode` | enum | não | `replace`, `append` ou `prepend`. | | `contentFormat` | string | não | Forma do conteúdo. | Exemplos: ```json {"docId":"doc-1","pageId":"page-1","name":"Visão geral"} ``` ```json {"docId":"doc-1","pageId":"page-1","subTitle":"Instalação e configuração"} ``` ```json {"docId":"doc-1","pageId":"page-1","content":"# Novo conteúdo"} ``` ```json {"docId":"doc-1","pageId":"page-1","content":"\n## Changelog","contentEditMode":"append"} ``` ```json {"account":"produto","docId":"doc-1","pageId":"page-2","content":"# Aviso\n\n","contentEditMode":"prepend","contentFormat":"text/md"} ``` Leia a página com `clickupfy_doc_page_get` após atualizar. Não envie um objeto vazio para testar a conexão: use uma das ferramentas de leitura, pois uma atualização sem conteúdo é recusada. ## Administração condicionada ao servidor ### `clickupfy_account_use` Define o perfil ativo local. Só aparece quando `mcp serve` não recebeu `--account` e o servidor não está em read-only. É a equivalência MCP de `clickupfy account use`, em projetos isolados, prefira fixar o perfil na configuração do processo para evitar troca global durante o trabalho. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | sim | Perfil local já configurado. | Exemplos: ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` ```json {"account":"desenvolvimento"} ``` O retorno informa `activeAccount`. Esta ação muda a configuração da máquina, logo não deve ser usada para uma consulta pontual de outro perfil. ### `clickupfy_workspace_use` Associa workspace autorizado ao perfil. Só aparece quando o processo não fixou `--account` nem `--workspace` e tem escrita. O servidor confere a autorização contra a API antes de salvar a associação no perfil local. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a alterar quando omitido usa o ativo. | | `workspaceId` | string | sim | Workspace autorizado para o perfil. | Exemplos: ```json {"workspaceId":"123456"} ``` ```json {"account":"produto","workspaceId":"123456"} ``` ```json {"account":"cliente-a","workspaceId":"987654"} ``` ```json {"account":"homologacao","workspaceId":"246810"} ``` ```json {"account":"suporte","workspaceId":"135791"} ``` Use `clickupfy_workspaces_list` para descobrir um ID autorizado. Uma tentativa com workspace ausente da lista é recusada e não altera a associação existente. ### MCP ClickUpfy: tarefas, Sprints, checklists e tempo - URL: https://promovaweb.com/docs/clickupfy/referencia/mcp-trabalho - Descrição: Consulte as ferramentas MCP do ClickUpfy para tarefas, Sprints, checklists, comentários e tempo, com escopo por List, recusas e exemplos de chamadas. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | ferramentas MCP de trabalho em tarefas, Sprints, checklists, comentários e time tracking | | Autoridade | schemas e handlers de `src/mcp.ts`, `src/work-items.ts` e `src/sprints.ts` | As chamadas deste capítulo usam objetos JSON de argumentos. Valores como `3001`, `86abc123` e `sprint-10` são apenas exemplos. Ferramentas de escrita somem de `tools/list` quando o servidor é iniciado com `--read-only`, não há parâmetro que contorne essa ausência. Depois de cada escrita, faça uma leitura do recurso alterado para comparar o estado persistido. ## Tarefas: leitura e busca ### `clickupfy_tasks_list` Lista tarefas da List autorizada. Omitir `listId` usa a List fixada. Os filtros aceitam arrays: `status` é uma lista de nomes configurados na List e `assignees` contém IDs de pessoas. `page` deve ser inteiro maior ou igual a zero. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `listId` | string | não | List fixa do projeto quando omitido. | | `status` | string[] | não | Filtra por um ou mais status. | | `assignees` | string[] | não | Filtra por responsáveis. | | `includeClosed` | booleano | não | Inclui tarefas concluídas. | | `page` | inteiro | não | Página, iniciando em zero. | Exemplos: ```json {} ``` ```json {"status":["em andamento"]} ``` ```json {"assignees":["42","57"],"includeClosed":false} ``` ```json {"includeClosed":true,"page":1} ``` ```json {"account":"produto","listId":"3001","status":["aberta","em andamento"]} ``` O retorno é compacto, com os campos usados para localizar trabalho. Para obter descrição, subtarefas e checklist items de uma tarefa, chame `clickupfy_task_get` com o `id` devolvido. Nunca use um `listId` diferente do fixado pelo projeto. ### `clickupfy_task_get` Obtém a tarefa e acrescenta `execution`, uma fila endereçável que preserva subtarefas e checklist items. `raw` devolve somente a resposta original da API. `markdown` devolve um texto único com descrição e itens, os dois formatos são mutuamente exclusivos. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa raiz. | | `raw` | booleano | não | Retorna somente o payload do ClickUp. | | `markdown` | booleano | não | Renderiza tarefa e fila em Markdown. | Exemplos: ```json {"taskId":"86abc123"} ``` ```json {"taskId":"86abc123","markdown":true} ``` ```json {"taskId":"86abc123","raw":true} ``` ```json {"account":"produto","taskId":"86abc123"} ``` ```json {"account":"cliente-a","taskId":"77def456","markdown":true} ``` Os itens usam chaves como `task:86abc123` e `checklist:check-1:item-1`. `parentKey` e `depth` preservam a árvore. A ação `complete` de cada item mostra o comando CLI e a chamada MCP adequados, mas a autorização para executar essa ação continua vindo do pedido recebido pelo agente. ### `clickupfy_tasks_search` Busca somente dentro da List fixada, diferentemente do comando CLI `task search`, que percorre o workspace. `maxPages` aceita inteiro entre `1` e `100`. Omitir `query` lista de acordo com os outros filtros, portanto inclua um termo quando a intenção for uma busca nominal. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `query` | string | não | Texto no nome, descrição ou ID. | | `status` | string[] | não | Filtra por status. | | `assignees` | string[] | não | Filtra por responsáveis. | | `includeClosed` | booleano | não | Inclui tarefas concluídas. | | `maxPages` | inteiro | não | Paginação, de `1` a `100`. | Exemplos: ```json {"query":"autenticação"} ``` ```json {"query":"86abc123"} ``` ```json {"query":"API","status":["em andamento"]} ``` ```json {"assignees":["42"],"includeClosed":true,"maxPages":5} ``` ```json {"account":"produto","query":"checkout","maxPages":10} ``` Se duas tarefas forem plausíveis, apresente ID e nome e aguarde a escolha da pessoa que solicitou o trabalho. A ferramenta não altera tarefa e não expande a busca para uma List não autorizada. ### `clickupfy_comments_list` Lê comentários de uma tarefa. O retorno normaliza usuário, data e texto para facilitar a leitura pelo agente. A ferramenta não aceita paginação nem filtro de autor, leia a lista completa retornada e não trate um comentário antigo como instrução mais recente sem conferir as datas. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa cujos comentários serão lidos. | Exemplos: ```json {"taskId":"86abc123"} ``` ```json {"taskId":"77def456"} ``` ```json {"account":"produto","taskId":"86abc123"} ``` ```json {"account":"cliente-a","taskId":"77def456"} ``` ```json {"account":"homologacao","taskId":"55ghi789"} ``` Leia essa ferramenta antes de publicar mudança de status ou comentário de progresso. Ela não expõe anexos como conteúdo, não publica respostas e não altera o campo de status. ## Sprints ### `clickupfy_sprints_list` Lista Sprints dentro do Sprint Folder fixado. Uma Sprint é uma List que possui `start_date` e `due_date`, `includeRegular` acrescenta Lists comuns ao retorno de diagnóstico. `at` recebe uma data `AAAA-MM-DD` usada para classificar o estado do ciclo. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `folderId` | string | não | Sprint Folder fixado quando omitido. | | `archived` | booleano | não | Inclui Lists arquivadas. | | `includeRegular` | booleano | não | Inclui Lists que não são Sprints. | | `at` | string | não | Data de referência em `AAAA-MM-DD`. | Exemplos: ```json {} ``` ```json {"at":"2026-08-10"} ``` ```json {"archived":true,"includeRegular":true} ``` ```json {"folderId":"4001","at":"2026-09-01"} ``` ```json {"account":"produto","folderId":"4001","includeRegular":false} ``` O objeto vazio funciona somente se o servidor recebeu `--sprint-folder`. A ferramenta não cria Sprint nem altera datas: a API pública do ClickUp não oferece criação de Sprint por esse fluxo. ### `clickupfy_sprint_current` Obtém a única Sprint cujo período contém a data informada ou a data atual. Se não houver Sprint ativa, ou se dois períodos se sobrepuserem, a ferramenta retorna erro em vez de escolher uma List arbitrariamente. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `folderId` | string | não | Sprint Folder fixado quando omitido. | | `at` | string | não | Data de referência em `AAAA-MM-DD`. | Exemplos: ```json {} ``` ```json {"at":"2026-08-10"} ``` ```json {"folderId":"4001"} ``` ```json {"folderId":"4001","at":"2026-09-01"} ``` ```json {"account":"produto","folderId":"4001","at":"2026-10-15"} ``` Não use a falha como motivo para anexar tarefa a qualquer List do Folder. Corrija datas e sobreposição no ClickUp, depois leia novamente a Sprint atual. ### `clickupfy_sprint_get` Produz relatório de uma Sprint informada. Inclui período, progresso por quantidade de tarefas, progresso por Sprint Points e distribuição de status. `at` muda somente o cálculo temporal da situação da Sprint. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `sprintId` | string | sim | Sprint a analisar. | | `at` | string | não | Data de referência em `AAAA-MM-DD`. | Exemplos: ```json {"sprintId":"sprint-10"} ``` ```json {"sprintId":"sprint-10","at":"2026-08-10"} ``` ```json {"sprintId":"sprint-11"} ``` ```json {"account":"produto","sprintId":"sprint-10"} ``` ```json {"account":"cliente-a","sprintId":"sprint-22","at":"2026-09-01"} ``` Uma tarefa sem Points participa do total de tarefas, mas não adiciona peso ao cálculo por pontos. Leia `clickupfy_sprint_tasks` para obter os itens do relatório, não tente inferi-los apenas pelas porcentagens. ### `clickupfy_sprint_tasks` Lista tarefas associadas a uma Sprint, incluindo concluídas por padrão. `openOnly: true` remove tarefas já concluídas e é útil para a fila presente, mas não substitui a lista integral usada na revisão final do ciclo. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `sprintId` | string | sim | Sprint consultada. | | `openOnly` | booleano | não | Omite tarefas concluídas quando vale `true`. | Exemplos: ```json {"sprintId":"sprint-10"} ``` ```json {"sprintId":"sprint-10","openOnly":true} ``` ```json {"sprintId":"sprint-11"} ``` ```json {"account":"produto","sprintId":"sprint-10","openOnly":false} ``` ```json {"account":"cliente-a","sprintId":"sprint-22","openOnly":true} ``` A ferramenta retorna resumos de tarefa. Para descrição, subtarefas e checklist items de um item específico, chame `clickupfy_task_get` com o ID da tarefa. ## Ferramentas de escrita de trabalho As ferramentas seguintes só aparecem fora de read-only. Informe apenas campos que devem mudar. Elas usam o mesmo perfil e regras de isolamento das consultas. ### `clickupfy_task_create` Cria tarefa ou subtarefa na List fixa. `name` é obrigatório. Datas devem ser timestamps inteiros em milissegundos, diferentemente do CLI, que aceita datas `AAAA-MM-DD`. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account`, `listId` | string | não | Perfil e List fixa quando omitida. | | `name` | string | sim | Nome da tarefa. | | `description`, `markdownContent`, `status`, `parent` | string | não | Conteúdo, status e pai. | | `priority` | inteiro | não | De `1` a `4`. | | `assignees` | número[] | não | Responsáveis. | | `startDate`, `dueDate` | inteiro | não | Timestamp em milissegundos. | | `points` | número | não | Sprint Points não negativos. | Exemplos: ```json {"name":"Corrigir retorno da API"} ``` ```json {"name":"Documentar login","description":"Explicar a sessão."} ``` ```json {"name":"Criar testes","markdownContent":"## Casos\n\n- Login válido"} ``` ```json {"name":"Implementar token","status":"em andamento","priority":2,"assignees":[42,57],"startDate":1786320000000,"dueDate":1786665600000,"points":5} ``` ```json {"account":"produto","listId":"3001","name":"Cobrir expiração","parent":"86abc123","markdownContent":"Adicionar testes de sessão expirada."} ``` Leia a tarefa criada com `clickupfy_task_get`. Para `listId`, omitir é o caminho normal no MCP do projeto, um valor diferente do valor fixo é recusado. ### `clickupfy_task_update` Atualiza campos de uma tarefa. `taskId` é obrigatório e pelo menos um campo de alteração deve estar presente. Para remover data, use `null` em `startDate` ou `dueDate`, não envie texto vazio. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account`, `taskId` | string | `taskId` sim | Perfil e tarefa. | | `name`, `description`, `markdownContent`, `status` | string | não | Campos textuais. | | `priority` | inteiro | não | De `1` a `4`. | | `startDate`, `dueDate` | inteiro ou `null` | não | Nova data ou remoção. | | `points` | número | não | Sprint Points não negativos. | Exemplos: ```json {"taskId":"86abc123","status":"em andamento"} ``` ```json {"taskId":"86abc123","name":"Corrigir autenticação por token"} ``` ```json {"taskId":"86abc123","priority":1,"points":8} ``` ```json {"taskId":"86abc123","startDate":1786320000000,"dueDate":1786665600000} ``` ```json {"account":"produto","taskId":"86abc123","markdownContent":"## Entrega\n\nPublicar manual atualizado.","dueDate":null} ``` Depois da escrita, use `clickupfy_task_get`. A ferramenta devolve a tarefa atualizada, mas a releitura é importante quando outras alterações concorrem na mesma tarefa. ### `clickupfy_checklist_create` Cria checklist em uma tarefa. O retorno fornece o ID necessário em `clickupfy_checklist_item_create`. Itens não são criados automaticamente. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa proprietária. | | `name` | string | sim | Nome do checklist. | Exemplos: ```json {"taskId":"86abc123","name":"Testes"} ``` ```json {"taskId":"86abc123","name":"Revisão de segurança"} ``` ```json {"taskId":"77def456","name":"Publicação"} ``` ```json {"account":"produto","taskId":"86abc123","name":"Aceite"} ``` ```json {"account":"cliente-a","taskId":"77def456","name":"Regressão"} ``` ### `clickupfy_checklist_item_create` Acrescenta item aberto a um checklist. `assignee`, quando informado, é um ID numérico. A ferramenta não recebe `taskId` porque o checklist já define a tarefa proprietária. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `checklistId` | string | sim | Checklist que receberá o item. | | `name` | string | sim | Texto do item. | | `assignee` | inteiro | não | ID do responsável pelo item. | Exemplos: ```json {"checklistId":"check-1","name":"Executar testes unitários"} ``` ```json {"checklistId":"check-1","name":"Executar build"} ``` ```json {"checklistId":"check-1","name":"Revisar documentação","assignee":42} ``` ```json {"account":"produto","checklistId":"check-2","name":"Conferir changelog"} ``` ```json {"account":"cliente-a","checklistId":"check-3","name":"Validar publicação","assignee":57} ``` ### `clickupfy_checklist_item_set` Marca ou reabre um item e confirma o estado por uma nova leitura da tarefa. `taskId` deve ser a tarefa raiz devolvida por `clickupfy_task_get`, `resolved: true` conclui e `resolved: false` reabre. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa raiz usada na conferência. | | `checklistId` | string | sim | Checklist proprietário. | | `itemId` | string | sim | Item a atualizar. | | `resolved` | booleano | sim | `true` conclui, `false` reabre. | Exemplos: ```json {"taskId":"86abc123","checklistId":"check-1","itemId":"item-1","resolved":true} ``` ```json {"taskId":"86abc123","checklistId":"check-1","itemId":"item-1","resolved":false} ``` ```json {"account":"produto","taskId":"86abc123","checklistId":"check-2","itemId":"item-4","resolved":true} ``` ```json {"account":"cliente-a","taskId":"77def456","checklistId":"check-3","itemId":"item-2","resolved":true} ``` ```json {"taskId":"77def456","checklistId":"check-3","itemId":"item-2","resolved":false} ``` Não passe um item de outra tarefa. A ferramenta faz essa conferência e recusa a escrita quando a relação não corresponde à árvore lida. ### `clickupfy_sprint_add_task` Associa tarefa a Sprint sem trocar sua List principal. Ela não cria tarefa e não muda seu status. A ferramenta só aparece em servidor com escrita. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `sprintId` | string | sim | Sprint de destino. | | `taskId` | string | sim | Tarefa a associar. | Exemplos: ```json {"sprintId":"sprint-10","taskId":"86abc123"} ``` ```json {"sprintId":"sprint-10","taskId":"77def456"} ``` ```json {"account":"produto","sprintId":"sprint-10","taskId":"86abc123"} ``` ```json {"account":"cliente-a","sprintId":"sprint-22","taskId":"55ghi789"} ``` ```json {"account":"homologacao","sprintId":"sprint-33","taskId":"99jkl012"} ``` Leia `clickupfy_sprint_tasks` depois da escrita. Só associe a tarefa quando o planejamento da Sprint estiver incluído no pedido. ### `clickupfy_sprint_remove_task` Remove uma associação com Sprint sem excluir a tarefa. Comentários, checklist, tempo e List principal permanecem na tarefa. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `sprintId` | string | sim | Sprint cuja associação será removida. | | `taskId` | string | sim | Tarefa associada. | Exemplos: ```json {"sprintId":"sprint-10","taskId":"86abc123"} ``` ```json {"sprintId":"sprint-10","taskId":"77def456"} ``` ```json {"account":"produto","sprintId":"sprint-10","taskId":"86abc123"} ``` ```json {"account":"cliente-a","sprintId":"sprint-22","taskId":"55ghi789"} ``` ```json {"account":"homologacao","sprintId":"sprint-33","taskId":"99jkl012"} ``` Use `clickupfy_task_delete` somente quando a exclusão inteira estiver explicitamente autorizada. ### `clickupfy_sprint_set_points` Define Sprint Points de uma tarefa. `points` é um número maior ou igual a zero. O ClickUpfy transmite o valor, a escala pertence ao time. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa que receberá pontos. | | `points` | número | sim | Valor não negativo. | Exemplos: ```json {"taskId":"86abc123","points":0} ``` ```json {"taskId":"86abc123","points":1} ``` ```json {"taskId":"86abc123","points":3} ``` ```json {"account":"produto","taskId":"86abc123","points":5} ``` ```json {"account":"cliente-a","taskId":"77def456","points":8} ``` Leia a tarefa com `clickupfy_task_get` para confirmar o número persistido. ### `clickupfy_task_delete` Exclui permanentemente uma tarefa. O campo `confirm` só aceita o literal `true`, essa exigência impede uma exclusão causada por objeto incompleto ou ambíguo. A ferramenta não está disponível em read-only. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa a excluir. | | `confirm` | `true` | sim | Confirmação literal obrigatória. | Exemplos: ```json {"taskId":"86abc123","confirm":true} ``` ```json {"taskId":"77def456","confirm":true} ``` ```json {"account":"produto","taskId":"86abc123","confirm":true} ``` ```json {"account":"cliente-a","taskId":"77def456","confirm":true} ``` ```json {"account":"homologacao","taskId":"55ghi789","confirm":true} ``` Leia tarefa, nome e List e obtenha autorização explícita para exclusão antes de qualquer exemplo deste tipo. Para somente retirar a tarefa do ciclo, use `clickupfy_sprint_remove_task`. ### `clickupfy_comment_create` Publica comentário em uma tarefa. `notifyAll` é opcional, ele pede ao ClickUp para notificar participantes. A ferramenta não modifica status, timer ou checklist. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa que receberá o comentário. | | `text` | string | sim | Conteúdo do comentário. | | `notifyAll` | booleano | não | Pede notificação aos participantes. | Exemplos: ```json {"taskId":"86abc123","text":"Iniciei a análise da tarefa."} ``` ```json {"taskId":"86abc123","text":"Os testes unitários passaram."} ``` ```json {"taskId":"86abc123","text":"Aguardando acesso ao ambiente de homologação.","notifyAll":true} ``` ```json {"account":"produto","taskId":"86abc123","text":"Documentação e ebook foram atualizados."} ``` ```json {"account":"cliente-a","taskId":"77def456","text":"Validação final concluída.","notifyAll":true} ``` ### `clickupfy_time_current` Consulta o time entry que está em execução no workspace. Não recebe filtros, omitir `account` usa o perfil fixado ou ativo. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil cujo workspace será consultado. | Exemplos: ```json {} ``` ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` ### `clickupfy_time_start` Inicia um time entry para uma tarefa. Consulte `clickupfy_time_current` antes, pois a ferramenta não encerra automaticamente um registro que já esteja ativo. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil a resolver. | | `taskId` | string | sim | Tarefa associada ao tempo. | | `description` | string | não | Descrição curta do trabalho. | Exemplos: ```json {"taskId":"86abc123"} ``` ```json {"taskId":"86abc123","description":"Implementação"} ``` ```json {"taskId":"86abc123","description":"Testes de regressão"} ``` ```json {"account":"produto","taskId":"86abc123","description":"Revisão de documentação"} ``` ```json {"account":"cliente-a","taskId":"77def456","description":"Correção da integração"} ``` ### `clickupfy_time_stop` Encerra o time entry atual do workspace. Ela não recebe `taskId` e não modifica status nem comentários. Relê `clickupfy_time_current` depois da chamada quando o encerramento precisa ser confirmado. | Campo | Tipo | Obrigatório | Uso | | --- | --- | --- | --- | | `account` | string | não | Perfil cujo registro atual será encerrado. | Exemplos: ```json {} ``` ```json {"account":"produto"} ``` ```json {"account":"cliente-a"} ``` ```json {"account":"homologacao"} ``` ```json {"account":"suporte"} ``` ### Solução de problemas no ClickUpfy: diagnóstico e correção - URL: https://promovaweb.com/docs/clickupfy/solucao-de-problemas - Descrição: Diagnostique instalação, API key, workspace, hierarquia, status, MCP, Sprints, checklists, time tracking e saída sem expor suas credenciais do ClickUp. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | diagnóstico de instalação, autenticação, escopo e API | | Autoridade | mensagens de erro e contratos públicos do ClickUpfy | ## O comando não foi encontrado Execute: ```bash npm prefix --global ``` Confirme se a pasta de executáveis globais está no `PATH`. Em instalação standalone, confira permissão de execução e o nome do arquivo. ## A API key foi recusada Use: ```bash clickupfy whoami ``` Se falhar, gere ou confira a chave no ClickUp e execute `clickupfy install` novamente. Uma chave revogada não pode ser recuperada pelo ClickUpfy. Nunca publique a chave para pedir suporte. Informe apenas o account, o workspace mascarado quando necessário e a mensagem de erro sem headers. ## O workspace está incorreto ```bash clickupfy workspace list clickupfy workspace use clickupfy status ``` Se o MCP fixa `--workspace`, atualize a configuração do projeto para o mesmo ID ou selecione o account correto. ## Folder ou List não aparece Confirme o Space e tente incluir arquivados: ```bash clickupfy folder list --space --archived clickupfy list list --folder --archived ``` Para List sem Folder, use `--space`. Permissões da API key também podem ocultar recursos. ## O status foi rejeitado ```bash clickupfy list get ``` Copie a grafia de um status retornado. Status são configuráveis por List. ## O MCP não inicia Execute manualmente o comando registrado no `.mcp.json` ou no `.codex/config.toml`. Os motivos mais comuns são: - `clickupfy` ausente no `PATH` do cliente - JSON inválido - account inexistente - `--list` sem valor - workspace fixado diferente do perfil - cliente não reiniciado depois da edição. ## O MCP recusou um ID Essa recusa é esperada quando a ferramenta recebe um ID diferente do escopo do projeto. Consulte: ```text clickupfy_mcp_context ``` Use o destino fixado ou altere o arquivo do cliente conscientemente. Não contorne a proteção repetindo a chamada com outro recurso. ## Uma ferramenta de escrita não aparece O servidor pode estar em read-only. Confira os argumentos. Remover `--read-only` amplia as permissões do cliente e deve ser uma decisão explícita. ## A Sprint atual não foi encontrada Liste o Folder com períodos: ```bash clickupfy sprint list --folder --include-regular ``` Confirme se existe exatamente uma Sprint cujo período inclui a data atual. Corrija datas ou sobreposição na interface do ClickUp. ## O item de checklist não mudou Releia a tarefa: ```bash clickupfy task get --json ``` Confirme task ID, checklist ID e item ID. O comando `checklist set` rejeita um item que não pertença à tarefa informada. ## O time entry já está em execução ```bash clickupfy time current clickupfy time stop ``` Confira o item antes de encerrar. Depois inicie o registro correto. ## A saída compacta não mostra um campo Repita com `--json`: ```bash clickupfy --json task get ``` Para uma tarefa longa consumida por agente, prefira `--markdown`. ## Diagnóstico seguro Ao relatar um problema, inclua: - versão de `clickupfy --version` - plataforma e forma de instalação - grupo e ação executados - mensagem de erro - se o modo era CLI ou MCP - escopo sem credenciais. Remova API keys, tokens, headers, conteúdo de clientes e dados pessoais. Volte ao [início do guia](/docs/clickupfy/introducao) ou consulte a [referência do CLI](/docs/clickupfy/cli). ### Sprints no ClickUpfy: ciclos, tarefas e Sprint Points - URL: https://promovaweb.com/docs/clickupfy/sprints - Descrição: Liste Sprints, encontre o ciclo atual, acompanhe tarefas e Points e associe uma tarefa ao ciclo sem removê-la da List principal onde ela foi criada. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | consulta e planejamento de Sprints existentes | | Autoridade | módulo de Sprints e endpoints públicos do ClickUp | ## Como o ClickUpfy reconhece uma Sprint No ClickUp, uma Sprint é uma List dentro de um Sprint Folder. O ClickUpfy considera Sprint uma List que possua `start_date` e `due_date`. Lists comuns do mesmo Folder ficam fora do resultado, salvo quando `--include-regular` for usado. O CLI não cria Sprints nem habilita o Sprint ClickApp. Essas operações continuam na interface do ClickUp. ## Liste os ciclos ```bash clickupfy sprint list --folder ``` Para diagnóstico de um Folder misto: ```bash clickupfy sprint list \ --folder \ --include-regular ``` Confira nome, ID, início e término. Um período ausente indica uma List comum ou uma Sprint ainda não configurada corretamente. ## Encontre a Sprint atual ```bash clickupfy sprint current --folder ``` O comando espera uma única Sprint ativa na data atual. Nenhuma Sprint ativa ou mais de uma sobreposta produz uma falha explícita. Corrija o calendário no ClickUp antes de automatizar a seleção. ## Leia o relatório ```bash clickupfy sprint get clickupfy sprint tasks clickupfy sprint tasks --open-only ``` O relatório percorre todas as páginas e inclui tarefas concluídas. O avanço é calculado por quantidade de tarefas e por Sprint Points. Uma tarefa sem Points participa da quantidade de itens, mas não acrescenta peso ao cálculo por pontos. Use `--open-only` para a fila de trabalho corrente, não para o relatório final da Sprint. ## Associe uma tarefa sem mover a List principal ```bash clickupfy sprint add-task ``` A API associa a tarefa à Sprint e preserva sua List principal. Isso permite manter backlog e ciclo como dimensões diferentes. Para remover a associação: ```bash clickupfy sprint remove-task ``` Essa ação não exclui a tarefa. ## Defina Sprint Points ```bash clickupfy sprint set-points 5 ``` O mesmo campo pode ser atualizado pelo grupo de tarefas: ```bash clickupfy task update --points 8 ``` Use a escala adotada pela equipe. O ClickUpfy transmite o número, mas não define se ele representa complexidade, esforço ou tamanho relativo. ## Configure o MCP para Sprints Acrescente o Folder ao projeto: ```bash clickupfy --account produto agent install \ --space 10 \ --folder 20 \ --list 30 \ --sprint-folder 40 ``` As ferramentas de Sprint podem omitir `folderId` quando esse valor está fixado. Um ID diferente é recusado. Consultas permanecem disponíveis em read-only. Associação e Points aparecem apenas no servidor com escrita. Depois do planejamento, aprenda a [registrar o tempo](/docs/clickupfy/time-tracking). ### Tarefas, subtarefas, checklists e comentários no ClickUpfy - URL: https://promovaweb.com/docs/clickupfy/tarefas - Descrição: Leia a fila executável, crie tarefas e subtarefas em Markdown, administre datas, prioridades e checklists e registre o progresso nos comentários. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | ciclo de leitura, criação, atualização e conclusão do trabalho | | Autoridade | comandos task, checklist e comment e fila execution | ## Leia antes de alterar Comece pela tarefa completa: ```bash clickupfy task get --markdown ``` Esse formato reúne metadados, descrição, subtarefas e checklist items em um documento. Para automação estruturada, use: ```bash clickupfy task get --json ``` Para obter somente a resposta original da API, sem a fila `execution`: ```bash clickupfy task get --raw ``` `--markdown`, `--json` e `--raw` são mutuamente exclusivos. ## Entenda a fila executável O objeto `execution` transforma a árvore em itens ordenados. Uma chave como `task:86abc123` identifica uma tarefa ou subtarefa. Uma chave como `checklist:check-1:item-1` identifica um item de checklist. O resumo informa totais abertos e concluídos. Cada item inclui `parentKey` e `depth`, por isso um agente consegue trabalhar em uma subtarefa aninhada sem tratá-la como item independente. A fila é uma projeção da leitura atual, não um segundo estado. Sempre releia a tarefa depois de uma mutação. ## Crie uma tarefa Use Markdown na descrição quando o ClickUp ClickApp correspondente estiver disponível: ```bash clickupfy task create \ --list \ --name "Implementar autenticação" \ --markdown-content "Adicionar o fluxo de login e os testes." \ --start-date 2026-08-01 \ --due-date 2026-08-05 ``` Datas aceitam o formato `AAAA-MM-DD`. Antes de criar, confira o fuso e a política de datas da equipe. Para criar uma subtarefa, informe o pai: ```bash clickupfy task create \ --list \ --name "Criar testes de autenticação" \ --parent \ --markdown-content "Cobrir sucesso, credencial inválida e limite." ``` Subtarefas podem receber novas subtarefas. A leitura executável preserva todos os níveis. ## Monte checklists verificáveis Crie o checklist na tarefa e depois os itens: ```bash clickupfy checklist create --name "Validação" clickupfy checklist item-create --name "Executar testes unitários" clickupfy checklist item-create --name "Executar build" ``` Os itens são criados abertos. Marque um item somente depois de executar sua verificação: ```bash clickupfy checklist set \ \ --resolved ``` Para reabrir: ```bash clickupfy checklist set \ \ --open ``` O ClickUpfy confirma primeiro que o item pertence à tarefa, grava o novo estado e relê a tarefa. O comando só comunica sucesso quando a API devolve o valor esperado. ## Atualize campos ```bash clickupfy task update --status "em andamento" clickupfy task update --priority 2 clickupfy task update --start-date 2026-08-01 clickupfy task update --due-date 2026-08-05 clickupfy task update --points 5 ``` As prioridades seguem a API do ClickUp: | Valor | Prioridade | | --- | --- | | `1` | urgente | | `2` | alta | | `3` | normal | | `4` | baixa | Consulte `list get` antes de definir status. Para remover datas: ```bash clickupfy task update --clear-start-date clickupfy task update --clear-due-date ``` ## Registre progresso em comentários ```bash clickupfy comment list --task clickupfy comment create \ --task \ --text "Testes focais passaram. Iniciando a regressão." ``` Um comentário útil registra um evento verificável: início, impedimento, checkpoint de teste ou conclusão. Evite publicar raciocínio interno, secrets, logs extensos ou promessas sem evidência. ## Exclua apenas com alvo confirmado ```bash clickupfy task delete --yes ``` A exclusão é permanente na interface do CLI e exige confirmação. Leia a tarefa, confira List e nome e confirme se a solicitação autoriza exclusão antes de usar `--yes`. Quando a equipe trabalha por ciclos, continue em [Sprints e Sprint Points](/docs/clickupfy/sprints). ### Time tracking no ClickUpfy: consultar, iniciar e encerrar - URL: https://promovaweb.com/docs/clickupfy/time-tracking - Descrição: Consulte o registro atual, inicie um time entry ligado à tarefa e encerre a medição sem misturar tempo trabalhado, status e comentário de progresso. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | início, consulta e encerramento de time entries | | Autoridade | comandos e ferramentas de time tracking | ## Consulte antes de iniciar ```bash clickupfy time current ``` Essa leitura evita iniciar um segundo registro enquanto outro item permanece em execução. Se houver um time entry ativo, confirme a tarefa e decida se ele deve continuar ou ser encerrado. ## Inicie um registro ```bash clickupfy time start \ --task \ --description "Implementação e testes" ``` Use uma descrição curta e observável. O registro pertence ao usuário autenticado pelo account selecionado. Em um fluxo com agente, inicie o tempo somente quando a implementação realmente começar. Leitura inicial, esclarecimento e espera por autorização não devem ser registrados automaticamente sem uma regra explícita da equipe. ## Encerre o registro ```bash clickupfy time stop ``` Depois, consulte novamente: ```bash clickupfy time current ``` A ausência de registro em execução confirma o encerramento. ## Use outro account em uma operação ```bash clickupfy --account cliente-a time current clickupfy --account cliente-a time start \ --task \ --description "Correção e regressão" ``` Essa seleção não altera o account ativo. É útil quando dois projetos usam workspaces diferentes na mesma máquina. ## Relação com comentários e status Time tracking não muda status nem publica comentário. As três ações representam evidências diferentes: - status indica a etapa no fluxo - comentário registra um evento legível pela equipe - time entry mede o período atribuído ao trabalho. A skill de implementação coordena essas ações, mas cada mutação continua explícita e verificável. Continue em [skills para agentes](/docs/clickupfy/agentes). ### Atualização e reparo - URL: https://promovaweb.com/docs/inboundfy/atualizacao-e-reparo - Descrição: Peça ao agente para executar `inboundfy-setup` sempre que: Peça ao agente para executar `inboundfy-setup` sempre que: - a versão-fonte do Inboundfy mudar, - uma skill ou arquivo de apoio desaparecer, - o inventário de fontes ficar desatualizado, - um diretório de saída gerenciado estiver ausente, - nomes legados aparecerem no diretório ativo. ## Passo a passo 1. Preserve alterações locais. 2. Simule a atualização: ```bash npx @promovaweb/inboundfy@latest update --dry-run ``` 3. Aplique a atualização: ```bash npx @promovaweb/inboundfy@latest update --yes ``` 4. Peça à skill `inboundfy-setup` para revisar as fontes e o contexto. 5. Confirme que `.inboundfy/context/` permaneceu intacto. 6. Confira os conflitos atualizados em `.inboundfy/fontes-projeto.md`. 7. Execute `npx @promovaweb/inboundfy@latest doctor --strict`. 8. Preencha qualquer template restaurado com a skill de contexto indicada. Metodologia, templates, documentação e skills gerenciadas acompanham a versão. Dados vivos, instruções externas e fontes descobertas permanecem no lugar. ## O que muda e o que permanece | O setup pode atualizar | O setup preserva | | --- | --- | | skills gerenciadas | dados existentes em `.inboundfy/context/` | | metodologia instalada | instruções fora do bloco do Inboundfy | | documentação instalada | fontes Markdown descobertas | | templates read-only | customizações antes da migração | | inventário de fontes | assets originais em `brand/` | ## Nomes legados Uma atualização não deixa dois gatilhos para a mesma fase. Os antigos nomes estratégicos sem número são movidos para `.inboundfy/migracoes/skills-legadas//`, e os nomes `00–03` permanecem no diretório ativo. ## Como conferir o reparo Primeiro simule e depois aplique: ```bash npx @promovaweb/inboundfy@latest repair --dry-run npx @promovaweb/inboundfy@latest repair --yes npx @promovaweb/inboundfy@latest doctor --strict ``` O reparo termina quando o diagnóstico não encontra erro ou aviso, o contexto vivo foi preservado e o inventário reflete as fontes atuais. ## Uma versão para tudo O número mostrado por `inboundfy --version` é o mesmo do framework instalado, do pacote npm, da tag Git `vX.Y.Z`, da GitHub Release e da edição do ebook. Não existe versão independente para o CLI. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | atualização, reparo, preservação e migração | | Autoridade | modos de reconciliação de `inboundfy-setup` | ### Contexto, fontes e marca - URL: https://promovaweb.com/docs/inboundfy/contexto-e-marca - Descrição: O Inboundfy combina três camadas sem copiá-las para um único arquivo: O Inboundfy combina três camadas sem copiá-las para um único arquivo: 1. `.inboundfy/context/`: dados estruturados do negócio. 2. `.inboundfy/fontes-projeto.md`: inventário das fontes que já existiam. 3. `brand/`: manual, tokens, logos, tipografia e aplicações de marca, quando a pasta existir. O arquivo `.inboundfy/context/aprendizado.md` mantém as orientações dadas durante as revisões. Cada registro informa se vale para uma peça, canal, persona ou todo o projeto. A skill lê esse arquivo antes de produzir e encaminha regras confirmadas de voz, grafia ou proibição para o arquivo normativo correspondente. Durante o setup, arquivos Markdown com nome em maiúsculas, como `PRODUCT.md`, `COPY.md` e `PROHIBITED.md`, são descobertos em todo o projeto. Dentro de `brand/`, todos os Markdown são inventariados, inclusive nomes em minúsculas. O setup registra caminho, assunto e possíveis conflitos, mas não move nem reescreve as fontes. Antes de produzir, cada skill lê o inventário e carrega somente os arquivos relevantes. Fatos confirmados no contexto prevalecem sobre exemplos, conflitos entre fontes são explicitados e não podem ser resolvidos por invenção. ## Proibições são hard gates `context/proibicoes.md` reúne vetos do negócio. `context/estruturas-proibidas.md` reúne padrões genéricos de escrita artificial. A validação faz um passe literal e outro semântico. Uma ocorrência reprova o asset, independentemente de outros aspectos de escrita, estética ou SEO. Detalhes de precedência estão em [CONTEXTO.md](https://github.com/promovaweb/inboundfy/blob/main/CONTEXTO.md). ## Arquivos de contexto | Arquivo | Informação mantida | | --- | --- | | `empresa.md` | identidade, missão e modelo de negócio | | `pessoas.md` | porta-vozes e pessoas citáveis | | `produtos.md` | produtos, recursos e limites | | `servicos.md` | serviços e condições | | `ofertas.md` | preço, validade, garantia e CTA | | `marca-voz.md` | idioma, tom e exemplos de voz | | `publico.md` | públicos, dores e objeções | | `concorrentes.md` | referências e diferenças confirmadas | | `enderecos.md` | Endereço físico, registro legal e contatos oficiais | | `links.md` | URLs oficiais, perfis sociais, páginas e destinos de conversão | | `canais.md` | formatos, caminhos e canais ativos | | `ferramentas.md` | ferramentas que podem ser citadas | | `glossario.md` | termos e grafias preferidas | | `campanhas.md` | campanhas ativas e seus estados | | `proibicoes.md` | vetos específicos do negócio | | `estruturas-proibidas.md` | padrões genéricos de escrita artificial | | `.inboundfy/context/aprendizado.md` | sugestões, correções, alinhamentos e dicas confirmadas | ## Quando um dado estiver faltando Use a skill `inboundfy-contexto-*` ligada ao arquivo. Ela pergunta, registra a origem e atualiza o conteúdo sem mudar o caminho. Quando o próprio arquivo estiver ausente, execute primeiro `inboundfy-setup` para restaurar o template. ## Como conferir a marca Quando `brand/` existir, abra o manual e os ativos usados pela tarefa. Uma peça visual precisa respeitar logo, proporção, paleta, tipografia e aplicação. Uma peça textual também pode depender da voz e das proibições registradas ali. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | contexto, fontes descobertas, marca e proibições | | Autoridade | `CONTEXTO.md` e contrato de descoberta do setup | ### Instalação e preparação - URL: https://promovaweb.com/docs/inboundfy/instalacao - Descrição: Disponibilizar skills ao agente não prepara o projeto. A primeira execução deve ser conduzida por `inboundfy-setup`, que usa o CLI para criar e conferir os arquivos. Disponibilizar skills ao agente não prepara o projeto. A primeira execução deve ser conduzida por `inboundfy-setup`, que usa o CLI para criar e conferir os arquivos. ## Instalação rápida Na raiz do projeto, faça primeiro uma simulação: ```bash npx @promovaweb/inboundfy@latest install --dry-run ``` Depois instale escolhendo o agente e o arquivo de instruções: ```bash npx @promovaweb/inboundfy@latest install \ --agent codex \ --instruction-file AGENTS.md \ --yes ``` O CLI instala as skills no diretório usado pelo agente, copia o método para `.inboundfy/framework/`, cria a configuração viva, os diretórios de acervo, canais e calendário, os índices e o bloco do agente. ## Arquivos canônicos do projeto Preencha os arquivos operacionais em `.inboundfy/` e os dados de empresa e copy em `.inboundfy/context/`: ```text .inboundfy/ ├── estrategia.md ├── pipeline.md ├── context/ │ ├── empresa.md │ ├── marca-voz.md │ ├── publico.md │ ├── glossario.md │ ├── proibicoes.md │ ├── links.md │ └── aprendizado.md └── indices/ ``` O setup pergunta sobre empresa, produtos, serviços, endereços, pessoas, endereço físico, URLs oficiais, redes sociais, oferta, personas, voz, regras, aprendizados prévios, canais, calendário e estados. Antes de liberar produção, exige empresa, site, voz, uma persona completa, objetivo e pelo menos um canal. Depois da entrevista, rode: ```bash inboundfy project sync inboundfy context ready --yes inboundfy doctor --strict ``` ## Primeiro acervo Registre o material sem edição. O texto original nunca é substituído: ```bash inboundfy acervo add "Título do material" --file entrada.md inboundfy acervo process 0001 ``` O diretório numerado contém: ```text acervo/0001-AAAA-MM-DD-slug/ ├── README.md ├── bruto.md ├── processado.md ├── faq.md ├── base-editorial.md ├── pesquisa.md └── estrategia.md auditorias/anti-slop/ ├── 00-entrada.md ├── 01-processado.md ├── 02-base-editorial.md ├── 03-estrategia-brief.md ├── 04-rascunho.md ├── 05-peca.md └── 06-pacote.md ``` As skills completam FAQ, base editorial, pesquisa e possibilidades de uso com o contexto do projeto, outras bases e pesquisa atualizada. ## Primeira peça Apresente as personas com número, ID, nome e detalhes de contexto, problema e resultado. Escolha uma ou mais antes de escrever. Crie a pasta final: ```bash inboundfy content create blog "Título da peça" \ --persona persona-01 --acervo 0001 ``` O caminho segue `canais//--/README.md`. O frontmatter registra canal, persona, acervo, estado, datas e vínculos editoriais. Use o pipeline e o calendário: ```bash inboundfy calendario add 2026-09-20 0001 inboundfy content status 0001 revisao inboundfy content digest 0001 ``` Depois da auditoria final, acrescente ao relatório da validadora o ID, o caminho retornado pelo comando e o SHA-256 atual, neste formato: ```markdown - **ID da peça:** `0001` - **Asset:** `canais/blog/0001-AAAA-MM-DD-titulo/README.md` - **SHA-256 da peça:** `` - **Veredito:** aprovado ``` Use o caminho do relatório ao registrar a aprovação e o agendamento: ```bash inboundfy content status 0001 aprovado \ --audit-report 06-auditoria/assets/blog-0001.md inboundfy content status 0001 agendado ``` O CLI recusa aprovação sem esse relatório, confere se ID, caminho e hash correspondem à peça e invalida a aprovação se o conteúdo mudar. Se houver correção posterior, retorne para `revisao`, repita a auditoria completa e atualize o relatório. Antes de publicar, a peça passa por voz, persona, dicionário, proibições, anti-slop e validador do canal. A publicação exige URL e data: ```bash inboundfy content status 0001 publicado \ --url https://exemplo.test/artigo \ --published-at 2026-09-20 ``` Consulte [a referência do CLI e dos estados](https://github.com/promovaweb/inboundfy/blob/main/docs/method/10-referencia-cli.md) para as passagens permitidas e as respostas completas dos comandos. ## Atualização e reparo Peça ao agente para executar `inboundfy-setup` quando a instalação precisar de atualização ou reparo. O CLI preserva dados preenchidos e registra customizações em `.inboundfy/migracoes/`. ```bash npx @promovaweb/inboundfy@latest update --dry-run npx @promovaweb/inboundfy@latest update --yes npx @promovaweb/inboundfy@latest doctor --strict ``` ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | instalação, configuração e primeira operação | | Autoridade | `inboundfy-setup` e `INSTALACAO.md` | ### Guia do usuário do Inboundfy - URL: https://promovaweb.com/docs/inboundfy/introducao - Descrição: Este guia acompanha uma instalação do Inboundfy e ensina a operar o framework sem exigir conhecimento da implementação das skills. Este guia acompanha uma instalação do Inboundfy e ensina a operar o framework sem exigir conhecimento da implementação das skills. ## Leia online ou como ebook Os capítulos deste diretório também formam o **Inboundfy — Guia completo do usuário**. O PDF preserva a diagramação para leitura, compartilhamento e impressão. O EPUB permite ajustar fonte e tamanho no leitor digital. - [Baixe o PDF](/pdf/ebook-inboundfy.pdf). - [Baixe o EPUB](/pdf/ebook-inboundfy.epub). - [Consulte a edição e os hashes](https://github.com/promovaweb/inboundfy/blob/main/ebook/README.md). ## Percurso completo Leia na ordem: 1. [Visão geral e escolha do fluxo](/docs/inboundfy/visao-geral) 2. [Pré-requisitos](/docs/inboundfy/pre-requisitos) 3. [Instalação e preparação](/docs/inboundfy/instalacao) 4. [Contexto, fontes e marca](/docs/inboundfy/contexto-e-marca) 5. [Primeiro brainstorm](/docs/inboundfy/primeiro-brainstorm) 6. [Primeira campanha](/docs/inboundfy/primeira-campanha) 7. [Primeiro pacote editorial](/docs/inboundfy/primeiro-pacote) 8. [Peça avulsa](/docs/inboundfy/peca-avulsa) 9. [Validação e correções](/docs/inboundfy/validacao-e-correcoes) 10. [Atualização e reparo](/docs/inboundfy/atualizacao-e-reparo) 11. [Solução de problemas](/docs/inboundfy/solucao-de-problemas) Os [exemplos executáveis](https://github.com/promovaweb/inboundfy/blob/main/examples/README.md) mostram relatórios, reprovações, correções e aprovações preenchidos com dados fictícios. ## Skills principais - `inboundfy-setup`: instala, atualiza ou repara o ambiente. - `$inboundfy`: entrada padrão, interpreta o pedido e escolhe o fluxo. - `inboundfy-brainstorm`, `inboundfy-acervo` e `inboundfy-estrategia`: componentes acionados pela orquestradora ou disponíveis para pedido direto. - `inboundfy-iniciar`: alias compatível que encaminha para `$inboundfy`. Uma skill especialista pode ser chamada diretamente quando já existe um brief claro para uma única peça. ## Um exemplo de ponta a ponta Imagine que você quer transformar uma anotação sobre manutenção preventiva em um artigo e um post. Depois do setup, o percurso fica assim: 1. Você entrega a anotação a `$inboundfy`. 2. A skill preserva o original, processa o texto, pesquisa o tema e registra FAQ, base editorial e possibilidades. 3. Você escolhe canais, personas e direção editorial. 4. As especialistas produzem o artigo e o post. 5. Cada validadora confronta sua peça com o brief, o contexto e a marca. 6. Uma reprovação volta à especialista com a correção necessária. 7. O fluxo registra somente as versões aprovadas no calendário e no catálogo. Você acompanha esse trabalho pelos arquivos criados. A resposta do agente resume o resultado, mas os artefatos do projeto são a evidência que permite retomar, revisar e auditar a execução. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | percurso completo do usuário do Inboundfy | | Autoridade | interfaces públicas das skills e metodologia instalada | ### Peça avulsa - URL: https://promovaweb.com/docs/inboundfy/peca-avulsa - Descrição: Envie o pedido a `$inboundfy`. Quando já houver um brief mínimo claro, a orquestradora encaminha a peça avulsa ao especialista: canal, objetivo, público, mensagem, CTA, formato e restrições. Envie o pedido a `$inboundfy`. Quando já houver um brief mínimo claro, a orquestradora encaminha a peça avulsa ao especialista: canal, objetivo, público, mensagem, CTA, formato e restrições. ## Passo a passo 1. Escolha `inboundfy-especialista-` ou `inboundfy-especialista--imagem`. 2. A especialista verifica setup, contexto, fontes, marca e brief. 3. Se faltar decisão estratégica, retorne ao briefing, não a invente dentro da produção. 4. A especialista produz o asset e registra sua relação com o brief. 5. A validadora de mesmo sufixo executa os vetos e as regras do canal. 6. Em reprovação, a especialista corrige em nova versão e reenvia. 7. Entregue apenas a versão aprovada e seu relatório. Para texto comercial, o brief também define a estrutura persuasiva adequada. Consulte [ESTRUTURAS-PERSUASIVAS.md](https://github.com/promovaweb/inboundfy/blob/main/ESTRUTURAS-PERSUASIVAS.md). Se o pedido puder originar várias peças ou exigir pesquisa e seleção de oportunidades, use o [pacote completo](/docs/inboundfy/primeiro-pacote). ## Brief mínimo Use este modelo para preparar o pedido: ```markdown # Brief - Canal: - Formato: - Público: - Objetivo: - Mensagem principal: - Chamada para a próxima ação: - Fonte factual: - Restrições: - Condições de aprovação: ``` Preço, prazo, promessa, URL, pessoa citada e dimensão visual precisam vir de uma fonte confirmada quando forem relevantes. A especialista não completa esses campos por inferência. ## Exemplo de pedido > Use `inboundfy-especialista-email` para produzir um email de convite a partir > deste brief. Salve a primeira versão, envie à validadora pareada e me mostre > apenas a versão aprovada e o relatório final. ## Quando usar o pacote completo Use o fluxo completo de `$inboundfy` quando ainda for necessário pesquisar, comparar canais, extrair oportunidades ou criar mais de uma peça. Especialistas diretos permanecem disponíveis para pedidos explícitos e briefs completos. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | produção direta de uma peça com brief aprovado | | Autoridade | especialistas, briefing e validadoras pareadas | ### Pré-requisitos - URL: https://promovaweb.com/docs/inboundfy/pre-requisitos - Descrição: Antes de instalar, confirme: Antes de instalar, confirme: - Node.js 22.14.0 ou superior está disponível (`node --version`), - o projeto possui acesso ao registro público do npm, - o agente consegue carregar skills no formato `SKILL.md`, - o projeto possui uma raiz bem definida, - existe um diretório de skills ativo ou o usuário pode indicar um, - o projeto permite criar `.inboundfy/`, `acervo/`, `canais/` e `calendario/`, - as instruções existentes em `AGENTS.md` ou `CLAUDE.md` podem ser preservadas e complementadas por um bloco delimitado. Não é necessário instalar servidor ou banco de dados. O comando `npx` baixa o CLI no momento do uso. Serviços de imagem e pesquisa podem exigir credenciais apenas quando uma skill específica os usar. ## Antes de executar o setup 1. Abra o agente na raiz do projeto consumidor. 2. Confira o CLI com `npx @promovaweb/inboundfy@latest --version`. 3. Preserve mudanças locais do projeto. 4. Peça ao agente para usar `inboundfy-setup`, ela conduzirá o CLI. Se `.claude/skills/` e `.codex/skills/` existirem ao mesmo tempo, o setup deve perguntar qual diretório está ativo. Ele não instala em ambos por suposição. ## O que ter em mãos O setup consegue começar com poucas informações. Separe: - uma frase que explique o que a empresa ou a pessoa faz, - três palavras para descrever a voz, - um texto curto que já represente essa voz, quando existir, - o primeiro produto ou serviço que será usado, - o primeiro canal no qual você quer produzir. Documentos existentes como `README.md`, `PRODUCT.md`, `BRAND.md` e `COPY.md` podem fornecer parte dessas respostas. O setup cataloga os arquivos e pede confirmação antes de gravar fatos no contexto. ## Como saber se pode continuar Continue quando estiver na raiz correta, souber qual diretório de skills está ativo e puder identificar o negócio, a voz, um produto ou serviço e um canal. Se uma dessas decisões ainda não existir, você pode iniciar o setup, mas a produção ficará suspensa até o contexto mínimo ser confirmado. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | condições necessárias antes da instalação | | Autoridade | contrato executável de `inboundfy-setup` | ### Primeira campanha - URL: https://promovaweb.com/docs/inboundfy/primeira-campanha - Descrição: Use a sequência estratégica quando ainda for necessário decidir objetivo, público, KPI, canais, fases e calendário. Use a sequência estratégica quando ainda for necessário decidir objetivo, público, KPI, canais, fases e calendário. ## Passo a passo 1. Envie o pedido a `$inboundfy`, ele aciona `inboundfy-estrategia`, que executa `00-briefing-cliente` e registra objetivo de negócio, público, oferta, orçamento, prazo, restrições e indicadores. 2. A etapa `01-pesquisa-mercado` reúne comprovações de mercado, categoria, concorrência e comportamento. 3. A etapa `02-campanha` transforma briefing e pesquisa em tese, fases, mensagens, mix de canais e volume de peças. 4. A etapa `03-calendario` distribui campanha e cadência orgânica no tempo, com dependências e responsáveis. 5. Cada item aprovado do calendário entra no planejamento editorial ou numa especialista, conforme sua complexidade. As fases estratégicas não escrevem copy final. Elas produzem decisões e briefs que orientam a execução. Quando a campanha já tiver todos esses elementos confirmados, retome a fase correspondente em vez de reiniciar o kickoff. Veja os campos e condições de passagem em [ESTRATEGIA.md](https://github.com/promovaweb/inboundfy/blob/main/ESTRATEGIA.md). ## O que informar no kickoff Prepare o objetivo de negócio, o público, a oferta, o período, o orçamento, as restrições e a forma de medir resultado. Quando um item ainda for desconhecido, registre a pendência em vez de usar um valor plausível. ## Artefatos esperados | Fase | Arquivo | | --- | --- | | `00` | `/00-briefing/brief-cliente.md` | | `01` | `/00-briefing/pesquisa-mercado.md` | | `02` | `/01-plano/plano-de-campanha.md` | | `03` | `calendario/.md` | O plano descreve as fases, as mensagens, os canais e o volume aproximado. O calendário transforma essas decisões em itens que podem entrar no pipeline. ## Como conferir Verifique se cada item do calendário aponta para uma campanha, um objetivo e um próximo fluxo. Um item sem material suficiente segue para planejamento. Uma peça simples, com brief completo, pode seguir diretamente para a especialista do canal. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | planejamento de campanha e calendário | | Autoridade | `ESTRATEGIA.md`, `inboundfy-estrategia` e `references/etapas/` | ### Primeiro brainstorm - URL: https://promovaweb.com/docs/inboundfy/primeiro-brainstorm - Descrição: Use este fluxo quando houver apenas uma ideia, pergunta ou anotação, ainda sem tese, evidência ou brief. Use este fluxo quando houver apenas uma ideia, pergunta ou anotação, ainda sem tese, evidência ou brief. ## Passo a passo 1. Envie a ideia a `$inboundfy` sem tentar estruturá-la, ele encaminha para `inboundfy-brainstorm`. 2. A fase `00-triagem` preserva a entrada original e abre um diretório datado. 3. A fase `01-entrevista` identifica lacunas. Perguntas só são feitas quando uma resposta muda materialmente o resultado. 4. A fase `02-pesquisa` consulta fontes do projeto e fontes externas necessárias, separando fatos, opiniões e hipóteses. 5. A fase `03-sintese` forma tese, recorte, argumentos, ativos e oportunidades por canal. 6. A fase `04-validacao` aplica escrita, fontes, contexto e proibições. 7. Uma reprovação retorna somente à fase responsável. ## Resultado esperado O arquivo `brainstorms/-/brainstorm.md` termina com status aprovado, ideia original intacta, fontes identificadas e suposições explícitas. Se o pedido já mencionar uma peça, o brainstorm aprovado segue para briefing. Se houver várias oportunidades, `$inboundfy` encaminha para o acervo e para o planejamento do pacote. O contrato de campos está em [BRAINSTORM.md](https://github.com/promovaweb/inboundfy/blob/main/BRAINSTORM.md). ## O que informar Envie a ideia original e, quando souber, diga qual público ou canal motivou a anotação. Não transforme a ideia em um brief artificial apenas para iniciar. A fase de triagem precisa preservar o material como ele chegou. Exemplo: > Quero explicar por que uma revisão de bicicleta antes do trajeto diário > evita falhas que parecem surgir de repente. ## Como acompanhar Abra o `brainstorm.md` depois de cada fase. A ideia original não muda. As perguntas e respostas, as fontes, as suposições, a tese e as oportunidades ganham seções próprias. A validação final informa o status e qualquer fase que precise ser refeita. ## Quando interromper Interrompa quando uma afirmação depender de dado ausente, uma fonte relevante estiver em conflito ou a marca ainda não tiver público e canal mínimos. O brainstorm pode preservar uma hipótese, mas não apresentá-la como fato. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | desenvolvimento sequencial de uma ideia | | Autoridade | `BRAINSTORM.md`, `inboundfy-brainstorm` e `references/etapas/` | ### Primeiro pacote editorial - URL: https://promovaweb.com/docs/inboundfy/primeiro-pacote - Descrição: Envie material bruto, peça-base, brainstorm aprovado ou item de calendário a `$inboundfy`. A orquestradora aciona `inboundfy-acervo` e conduz o ciclo completo. `inboundfy-iniciar` é um alias compatível para a mesma entrada. Envie material bruto, peça-base, brainstorm aprovado ou item de calendário a `$inboundfy`. A orquestradora aciona `inboundfy-acervo` e conduz o ciclo completo. `inboundfy-iniciar` é um alias compatível para a mesma entrada. ## Passo a passo 1. A instalação e os arquivos de contexto são conferidos. 2. A entrada é preservada em `bruto.md` com um ID único. 3. O material é processado com voz, personas, dicionário e proibições. O anti-slop faz a primeira leitura da entrada e uma segunda leitura do processado. 4. As perguntas frequentes, a pesquisa e as fontes são registradas. 5. A base editorial passa por nova auditoria para conferir resumos, relações, fontes e lacunas. 6. As possibilidades de canais, formatos, recortes e reaproveitamentos são mapeadas e auditadas antes do brief. 7. Você escolhe canais, uma ou mais personas e a direção editorial quando esses dados ainda não estiverem definidos. 8. A especialista de cada canal produz a peça com seus metadados e vínculos. 9. O outline e a abertura passam pelo anti-slop antes da expansão. A peça completa passa por outro ciclo antes da validadora. 10. O pacote aprovado passa por uma última comparação anti-slop antes de o pipeline, o calendário e os índices receberem os caminhos e estados finais. ## Como acompanhar Cada diretório do pacote representa um estado. Não edite o original para simular avanço, preserve a entrada e gere a próxima versão. Um asset só é pronto quando houver relatório individual aprovado e a auditoria do pacote estiver consistente. O detalhamento de diretórios está em [METODOLOGIA.md](https://github.com/promovaweb/inboundfy/blob/main/METODOLOGIA.md). ## Estrutura completa ```text acervo/--/ ├── bruto.md ├── processado.md ├── faq.md ├── base-editorial.md ├── pesquisa.md ├── estrategia.md └── auditorias/anti-slop/ ├── 00-entrada.md ├── 01-processado.md ├── 02-base-editorial.md ├── 03-estrategia-brief.md ├── 04-rascunho.md ├── 05-peca.md └── 06-pacote.md canais//--/README.md calendario/AAAA-MM.md ``` Não existe uma pasta obrigatória `05-producao/`. O número identifica a etapa interna de `inboundfy-planejamento/references/etapas/` que encaminha o brief para a especialista. As versões candidatas e os relatórios permanecem ligados ao item auditado. ## O que conferir em cada fase - `bruto.md`: o original foi preservado sem edição, - `processado.md`: ruído, dicionário, proibições, voz e o ciclo A1 do anti-slop foram tratados, - `faq.md`: perguntas e lacunas foram extraídas por parágrafo, - `base-editorial.md`: núcleo, atores, frases, fontes e usos estão descritos, - `pesquisa.md`: fontes externas e data de consulta estão registradas, - `estrategia.md`: canais, formatos, ângulos e reaproveitamentos estão listados, - `auditorias/anti-slop/`: os ciclos aplicáveis estão registrados por código, - `canais/`: cada peça tem persona, acervo, voz, estado e validação, - `calendario/`: cada data aponta para o caminho da peça. ## Retomar um pacote Informe o caminho do pacote existente. O agente lê o último estado válido e continua dali. Enviar novamente o material bruto sem indicar o pacote cria uma nova execução e não deve ser usado como forma de retomar. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | pipeline editorial completo e seus artefatos | | Autoridade | `METODOLOGIA.md`, `inboundfy-planejamento` e `references/etapas/` | ### Solução de problemas - URL: https://promovaweb.com/docs/inboundfy/solucao-de-problemas - Descrição: Execute `npx @promovaweb/inboundfy@latest doctor`. A presença das skills no agente não substitui uma instalação válida. Depois, peça ao agente para usar `inboundfy-setup`. ## A skill pede setup Execute `npx @promovaweb/inboundfy@latest doctor`. A presença das skills no agente não substitui uma instalação válida. Depois, peça ao agente para usar `inboundfy-setup`. ## Um arquivo de contexto sumiu Execute `inboundfy repair --yes` por meio de `inboundfy-setup` para restaurar o template. Depois, use a skill `inboundfy-contexto-*` correspondente para preencher o dado. O setup não inventa nem sobrescreve informação do negócio. ## Duas fontes discordam Consulte a seção de conflitos em `.inboundfy/fontes-projeto.md`. A execução deve impedir a afirmação afetada ou pedir uma decisão, nunca escolher uma versão silenciosamente. ## Uma peça continua reprovada Leia o relatório da validadora pareada e corrija na produtora indicada. Proibições exigem novo passe literal e semântico sobre o asset inteiro. ## A marca não aparece no inventário Rode `inboundfy context scan` e peça ao setup para reconciliar a classificação. Todo Markdown sob `brand/` deve aparecer, mesmo com nome em minúsculas. Ativos binários não entram no inventário, mas permanecem disponíveis no caminho original. ## Uma fase parece ter sido pulada Confira o estado do pacote e a [sequência documentada](/docs/inboundfy/visao-geral). Só peça avulsa com brief claro ou retomada explícita pode evitar etapas do pipeline completo. ## Consulta rápida | Sintoma | Próxima ação | | --- | --- | | Aviso de setup | Rode `inboundfy doctor` e execute `inboundfy-setup` | | Contexto ausente | Repare o template e preencha com a skill de contexto | | Fonte conflitante | Resolva o conflito no inventário | | Asset reprovado | Volte à especialista indicada | | Marca divergente | Confira `brand/` e refaça a validação | | Fase fora de ordem | Retome o último estado válido | | Saída em caminho inesperado | Confira `context/canais.md` | ## O agente não encontra uma skill Execute `inboundfy repair --yes` por meio do setup e confira o diretório de skills ativo. Se o projeto usa mais de uma convenção, indique explicitamente qual agente está em uso. Não copie uma skill isolada para um segundo diretório, pois isso pode criar versões divergentes. ## O conteúdo foi salvo, mas não está aprovado Procure o relatório individual em `06-auditoria/assets/`. Confira se ele tem o ID, o caminho, o SHA-256 atual da peça e `Veredito: aprovado`. Use `inboundfy content digest ` para comparar o hash e passe o caminho do relatório em `inboundfy content status aprovado --audit-report `. Se o arquivo mudou depois da auditoria, retorne para `revisao` e repita a validação completa antes de agendar ou publicar. ## Ainda não resolveu Gere um diagnóstico estruturado: ```bash npx @promovaweb/inboundfy@latest --json doctor ``` Reúna esse resultado, o caminho do pacote e a fase atual. Com esses elementos, o agente consegue retomar o estado real sem repetir o trabalho desde o começo. ## Classificação | Campo | Valor | | --- | --- | | Natureza | referência | | Escopo | diagnóstico de setup, contexto, fontes e fases | | Autoridade | mensagens e condições de interrupção das skills | ### Validação e correções - URL: https://promovaweb.com/docs/inboundfy/validacao-e-correcoes - Descrição: Toda especialista possui uma validadora de mesmo sufixo: Toda especialista possui uma validadora de mesmo sufixo: ```text inboundfy-especialista-linkedin ↓ inboundfy-validador-linkedin ``` A validadora lê o brief, o contexto completo, as fontes relevantes, as proibições e `brand/` quando existir. Ela não corrige o asset. Em caso de reprovação, registra: - localização do problema, - evidência observada, - regra violada, - correção verificável, - skill produtora à qual o trabalho deve voltar. A produtora cria nova versão e a validadora repete todos os passes. Só uma ciclo aprovado permite que o asset entre em `97-ativos-finais/`. Em pacotes, `inboundfy-planejamento` consolida as aprovações e verifica a coerência do conjunto. O anti-slop acompanha o trabalho antes da validadora. Use os marcos A0 a A6 descritos em `skills/inboundfy-anti-slop/ETAPAS.md`: entrada, processado, base, estratégia e brief, rascunho, peça completa e pacote final. Cada ciclo tem registro próprio e uma alteração invalida os ciclos posteriores ao ponto alterado. Os casos em [examples/validacao-assets](https://github.com/promovaweb/inboundfy/blob/main/examples/validacao-assets/README.md) demonstram reprovação literal, problema semântico, divergência factual e violação de marca visual. ## Como ler um relatório Um relatório reprovado precisa responder: | Campo | Pergunta respondida | | --- | --- | | Localização | Onde o problema aparece? | | Evidência | O que foi encontrado no asset? | | Regra | Qual contrato foi violado? | | Correção | O que precisa mudar para ser verificável? | | Retorno | Qual especialista recebe o trabalho? | Uma ocorrência de proibição, fato incorreto ou divergência material de marca mantém o status reprovado, mesmo quando outros aspectos do asset estão corretos. O relatório aponta o trecho, a regra e a correção necessária. Para aprovar uma peça no pipeline, o relatório final precisa identificar o ID, o caminho do `README.md`, o SHA-256 atual e o veredito `aprovado`. Consulte o hash com `inboundfy content digest ` e passe o caminho do relatório a: ```bash inboundfy content status aprovado --audit-report ``` O CLI também confere esse vínculo ao agendar ou publicar. Alteração na peça invalida a aprovação e exige retorno para `revisao`, nova leitura integral e novo relatório. ## Exemplo do ciclo ```text especialista produz v1 ↓ validadora reprova com evidência ↓ especialista produz v2 ↓ validadora repete todos os passes ↓ relatório aprovado ``` Não corrija apenas a frase citada e presuma que o restante continua aprovado. Depois de uma alteração, a validadora relê o asset inteiro. ## Aprendizado com suas orientações Sugestões, correções, alinhamentos e dicas entram em `.inboundfy/context/aprendizado.md` com um ID, a mensagem original, a aplicação e o alcance. Se o alcance não for claro, a skill pergunta se a orientação vale para esta peça, para um canal ou persona, ou para todo o projeto. Uma correção local afeta somente a peça relacionada. Uma regra confirmada para todo o projeto também atualiza `context/marca-voz.md`, `context/glossario.md` ou `context/proibicoes.md`, quando aplicável. O registro permanece como memória para as próximas peças. ## Falta de confirmação factual Quando a correção depende de preço, URL, data, permissão ou decisão que não está disponível, o relatório registra a pendência e pede informação. O asset não avança com um placeholder apresentado como definitivo. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | aprovação individual, reprovação e retorno à produtora | | Autoridade | `inboundfy-base-validador` e validadoras de asset | ### Visão geral - URL: https://promovaweb.com/docs/inboundfy/visao-geral - Descrição: Use `$inboundfy` para qualquer pedido. Conte o que você tem e o que pretende produzir, a orquestradora verifica o setup e escolhe o fluxo. Você não precisa memorizar nomes de skills. Especialistas continuam disponíveis para tarefas isoladas quando você pedir esse caminho diretamente. ## Um ponto de entrada Use `$inboundfy` para qualquer pedido. Conte o que você tem e o que pretende produzir, a orquestradora verifica o setup e escolhe o fluxo. Você não precisa memorizar nomes de skills. Especialistas continuam disponíveis para tarefas isoladas quando você pedir esse caminho diretamente. ## Roteamento interno | O que já existe | Fluxo interno | Resultado | | --- | --- | --- | | Uma ideia curta | `inboundfy-brainstorm` | Brainstorm validado | | Uma campanha a definir | Estratégia `00` | Plano e calendário | | Material bruto ou peça-base | `inboundfy-acervo` | Pacote auditado e saídas por canal | | Brief de uma peça | Especialista do canal | Peça avulsa validada | | Instalação ausente ou parcial | `inboundfy-setup` | Ambiente reconciliado | ## Sequências automáticas `inboundfy` encaminha ideias a `inboundfy-brainstorm`, campanhas a `inboundfy-estrategia` e material bruto a `inboundfy-acervo`. `inboundfy-brainstorm` executa `00` a `04`. `inboundfy-acervo` conduz o ciclo completo de um material: registro, processamento, FAQ, pesquisa, base editorial, possibilidades, escolha de canais e personas, produção, revisão, calendário e catálogo. `inboundfy-iniciar` permanece como alias compatível. Cada asset produzido passa pela validadora do canal antes da auditoria final. Não chame uma fase numerada fora de ordem, exceto para retomar um pacote no estado registrado. Skills base, de contexto, especialistas e validadoras não têm numeração porque são escolhidas por responsabilidade, não por cronologia. ## Saídas - Ideias desenvolvidas: `brainstorms/-/brainstorm.md`. - Itens de conhecimento: `acervo/--/`. - Peças finais: `canais//--/README.md`. - Agenda mensal: `calendario/AAAA-MM.md`. Os caminhos podem ser alterados em `.inboundfy/context/canais.md`. ## O que você informa Não é necessário conhecer o nome de todas as skills. Descreva o material que já possui, o resultado desejado e qualquer restrição que não possa ser decidida automaticamente. Exemplo: > Tenho a transcrição de uma conversa com um cliente. Quero encontrar ideias > para blog e LinkedIn, sem publicar nada automaticamente. `$inboundfy` identifica o material bruto, inicia o acervo e respeita os canais informados. Especialistas e etapas podem ser chamados diretamente para uma operação isolada, mas o fluxo padrão começa na orquestradora. ## O que o Inboundfy não faz sozinho O framework não publica em CMS ou rede social, não escolhe uma versão quando duas fontes factuais discordam e não inventa preço, promessa, pessoa, produto ou regra de marca. Essas situações geram uma pendência explícita. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | escolha do fluxo e pontos de entrada | | Autoridade | wrappers, catálogo e contratos das sequências | ### A entrevista, uma pergunta por vez - URL: https://promovaweb.com/docs/mvpfy/entrevista - Descrição: A entrevista é o lugar onde a ideia ganha forma. Você escreve como falaria com uma pessoa da equipe, e a orquestradora escolhe o próximo ponto que mais ajuda a montar o plano. A entrevista é o lugar onde a ideia ganha forma. Você escreve como falaria com uma pessoa da equipe, e a orquestradora escolhe o próximo ponto que mais ajuda a montar o plano. ## Primeiro, conte a ideia inteira Antes da primeira pergunta com opções, descreva livremente a ideia do SaaS e do MVP. Conte o que o produto pode fazer, qual público ele atenderia e quais módulos, recursos ou integrações já apareceram na sua cabeça. O MVPFy salva esse relato e separa os itens citados para examiná-los depois. Depois, começa a entrevista fechada. Cada turno tem uma única pergunta e cinco opções. Um item citado não entra automaticamente na versão 1.0. A conversa vai mostrar se ele apoia a jornada principal, se deve esperar ou se não serve ao recorte escolhido. Você também pode enviar tudo em uma mensagem. Por exemplo: ```text Quero um SaaS para pequenas agências acompanharem leads de seus clientes. Hoje elas usam planilhas e WhatsApp. A agência paga, cada cliente vê apenas seus próprios leads e o MVP precisa cadastrar o lead, atribuí-lo a alguém e mostrar um resumo. Quero começar com Laravel em uma VPS e cobrar mensalidade. ``` Nesse caso, o MVPFy já pode registrar problema, público, cliente pagador, permissões, jornada, tecnologia e cobrança. Ele não precisa perguntar de novo qual empresa ou pessoa fará o pagamento ou repetir etapas que você descreveu. A próxima pergunta trata apenas do ponto importante que ainda falta. Se quiser acrescentar informações, envie outra mensagem. Todas são acolhidas e salvas. Quando terminar, escolha `4. Avançar`. O encerramento da entrada inicial pode aparecer assim: ```text MVPFy: Entendi a ideia e já registrei o problema, o público, a jornada e os itens candidatos. Você quer acrescentar algo antes de começar? 1. Acrescentar outro módulo ou recurso. 2. Explicar melhor o público ou o problema. 3. Informar tecnologia, preço ou canal de venda. 4. Continuar para as perguntas. 5. Conversar mais sobre este tema. ``` As opções 1, 2, 3 e 5 permitem continuar enviando conteúdo. A opção 4 salva o estado da entrada e libera a próxima pergunta fechada. ## A primeira pergunta fechada Depois de salvar a ideia inicial, o MVPFy confirma o modelo de atendimento antes de investigar problema, preço ou tecnologia: ```text O sistema atenderá várias empresas ou equipes separadas dentro da mesma aplicação? 1. Sim. Vários clientes usarão a mesma aplicação, com dados separados. 2. Não. Cada cliente terá uma instalação ou ambiente próprio. 3. Ainda não sei. Quero comparar os dois modelos. 4. Avançar 5. Conversar mais sobre este tema ``` Se você escolher a primeira opção, a conversa pode fazer uma única pergunta curta sobre a unidade do tenant e a pessoa administradora. Os detalhes de membros, papéis, acesso entre espaços, separação de dados, banco e criação de novos tenants viram recomendações técnicas. Assim, o MVP não vira um cadastro interminável de regras de acesso. Se ainda não souber, a opção 5 permite conversar sobre a diferença antes de registrar a escolha. A pergunta continua sendo uma por vez. ## Quantas perguntas serão feitas A entrevista fechada tem no máximo oito perguntas. Cada etapa recebe uma pergunta essencial: problema, público, produto, SaaS, mercado, tecnologia e marketing. A etapa SaaS pode receber uma segunda pergunta curta. Se a ideia inicial já respondeu uma etapa, ela é pulada. O que permanecer será registrado como recomendação ou hipótese no `MVP.md`. Depois da oitava resposta, o MVPFy encerra a entrevista normal e monta o documento. Você pode pedir uma revisão específica depois, mas o fluxo inicial não continua perguntando sem fim. ## O que acontece depois da sua resposta 1. Você responde com número, texto, combinação de opções ou “não sei”. 2. O MVPFy guarda sua mensagem original. 3. A resposta recebe uma leitura organizada, sem mudança de sentido. 4. O sistema registra escolhas, hipóteses e áreas já cobertas. 5. `state.json` e `MVP.md` são atualizados quando fizer sentido. 6. A orquestradora revê o que ainda falta. 7. Uma única pergunta seguinte aparece. Se a gravação falhar, o fluxo não avança. A mesma pergunta volta para que você possa tentar novamente. ## O formato de cada turno Cada pergunta aparece com cinco opções: ```text Qual situação descreve melhor o problema? 1. A equipe perde o acompanhamento. 2. A equipe demora para responder. 3. A equipe não consegue mostrar o resultado. 4. Avançar 5. Conversar mais sobre este tema ``` As três primeiras opções respondem à mesma pergunta. A opção 4 aceita o entendimento atual e leva à próxima etapa. A opção 5 abre uma conversa sobre o mesmo tema. Você pode explicar um caso, tirar uma dúvida ou enviar uma resposta complexa. O MVPFy pode continuar essa conversa por mais de um turno, sempre salvando cada mensagem e mostrando no máximo uma pergunta principal. Nunca aparecem duas perguntas principais no mesmo turno. ## Você pode responder do seu jeito Você pode responder: - `1`, `2` ou `3`. - `4` para avançar. - `5` para conversar mais sobre a pergunta atual. - “2, mas também atendo consultores”. - uma explicação livre. - “ainda não sei”. - uma correção de resposta anterior. - “pausar”, “continuar”, “revisar preço” ou “gerar documento”. “Ainda não sei” também ajuda. O MVPFy registra a lacuna e pode sugerir uma hipótese provisória, deixando claro que ela ainda precisa de comprovação. ## Peça uma ação quando precisar | Pedido | Resultado | | --- | --- | | “Começar” | Cria ou abre um projeto e faz a primeira pergunta útil. | | “Continuar” | Lê o estado e retoma pela pendência prioritária. | | “Pausar” | Salva o ponto atual sem apagar respostas. | | “Revisar preço” | Trabalha somente em modelo, faixa e premissas de preço. | | “Mudar o público” | Registra a correção e revisa áreas dependentes. | | “O que falta?” | Mostra um resumo das pendências sem abrir formulário. | | “Gerar documento” | Consolida a melhor versão, mesmo que preliminar. | ## Como o fluxo aproveita o que você já disse Cada resposta recebe uma lista de áreas cobertas. Uma mensagem como “a agência paga e o cliente acompanha” já descreve papéis comerciais e de produto. A orquestradora usa essa informação para não colocar perguntas repetidas na fila. Ela também confere mudanças de direção. Se antes você disser que o cliente pagador é uma clínica e depois informar que venderá para agências, a nova mensagem fica registrada como correção. Personas, preço, jornada e canais ligados ao público anterior voltam para revisão. ## Quando a ideia ficou grande demais Quando aparecem várias jornadas, muitos públicos ou módulos que parecem produtos separados, o MVPFy pede um recorte. A pergunta passa a ser: ```text Qual resultado precisa funcionar do começo ao fim na primeira versão? 1. Registrar e acompanhar o lead. 2. Gerar o relatório para o cliente. 3. Automatizar a distribuição do lead. ``` As outras ideias são preservadas em “Fora do MVP e evolução futura”. ### Instalação do MVPFy - URL: https://promovaweb.com/docs/mvpfy/instalacao - Descrição: Para usar o MVPFy, tenha Node.js 22 ou superior instalado. Para usar o MVPFy, tenha Node.js 22 ou superior instalado. ## Prepare o projeto Na raiz do projeto consumidor, execute um único comando. Ele instala as skills e prepara os arquivos locais: ```bash npx --yes @promovaweb/mvpfy install --project . ``` O comando cria `MVP.md` e `.mvpfy/` para guardar o plano e o estado necessário para retomar a entrevista, sem alterar o código da aplicação ou os arquivos do Specsfy. Confira o resultado com os dois comandos abaixo. Eles mostram se o projeto e o planejamento já estão prontos: ```bash mvpfy doctor --project . mvpfy progress --project . ``` Com o projeto preparado, carregue `$mvpfy` no agente e peça para começar. A primeira mensagem livre será registrada antes da primeira pergunta fechada. ## Atualize as skills Na mesma raiz do projeto, execute o comando de atualização. Ele mantém as skills disponíveis para a próxima sessão: ```bash mvpfy update --project . ``` Quando já existir um `MVP.md` de uma versão anterior, a atualização compara o template e chama `mvpfy-migrate` antes de continuar. As respostas registradas permanecem disponíveis para a próxima lacuna da entrevista. Se algo não aparecer no projeto, consulte [Solução de problemas](/docs/mvpfy/solucao-de-problemas). Essa página reúne as verificações para corrigir a instalação. ### Guia do usuário do MVPFy - URL: https://promovaweb.com/docs/mvpfy/introducao - Descrição: Você não precisa chegar com um plano pronto. Basta descrever o que imagina criar, mesmo que a ideia ainda misture público, funcionalidades, preço e tecnologia. O MVPFy lê esse primeiro relato, aproveita o que já está claro e conduz a conversa até uma versão inicial que possa ser construída e testada. Você não precisa chegar com um plano pronto. Basta descrever o que imagina criar, mesmo que a ideia ainda misture público, funcionalidades, preço e tecnologia. O MVPFy lê esse primeiro relato, aproveita o que já está claro e conduz a conversa até uma versão inicial que possa ser construída e testada. Durante a entrevista, você conversa com a skill `mvpfy`. Ela faz uma pergunta por vez, salva a resposta antes de seguir e chama especialistas para tratar do problema, do público, do produto, do preço, da tecnologia e da entrada no mercado. No fim, você recebe um arquivo `MVP.md`. Ele dá às equipes uma base comum para criar o website, orientar a marca, construir a versão 1.0, vender o serviço e acompanhar os primeiros clientes. O MVPFy não cria `spec.md`, não executa o método do Specsfy e não altera o repositório `specsfy`. A semelhança entre os guias existe apenas na organização da documentação e no padrão visual do ebook. ## Escolha como começar Você pode ler este percurso online ou levar o conteúdo para um leitor digital. Esta edição portátil é a **v0.4.7**: - [PDF](/pdf/ebook-mvpfy.pdf), para leitura e impressão. - [EPUB](/pdf/ebook-mvpfy.epub), para leitores digitais. - [manifesto](/docs/mvpfy/downloads/build.json), com a versão e os hashes do build. O ebook contém somente o guia do usuário. A ordem de compilação está em ordem de leitura canônica. A documentação técnica continua disponível online para instalação, manutenção e contribuição com o framework. ## Para qual situação o MVPFy serve No começo de uma empresa, é comum pensar no painel antes de entender o problema, escolher a tecnologia antes de conhecer o volume e imaginar o preço sem saber qual empresa ou pessoa fará o pagamento. O MVPFy organiza essas escolhas em uma conversa simples. O guia foi feito para este cenário: - uma empresa nova ou uma operação ainda em formação. - um primeiro produto de software. - uma oferta contínua de software como serviço. - uma versão 1.0 para aprender com os primeiros clientes. Se a ideia for uma agência que cria sites sob encomenda, o MVPFy verifica se existe também um produto SaaS repetível. Sem esse produto, a proposta não se encaixa no percurso principal. ## Um percurso curto e progressivo 1. Leia [A proposta](/docs/mvpfy/proposta) para saber o que o MVPFy prepara. 2. Siga [Instalação](/docs/mvpfy/instalacao) para preparar o projeto que receberá o plano. 3. Acompanhe [Primeiro MVP](/docs/mvpfy/primeiro-mvp) com um exemplo do início ao fim. 4. Consulte [Entrevista](/docs/mvpfy/entrevista) para entender a conversa e a retomada. 5. Abra [MVP.md](/docs/mvpfy/mvp) para conhecer o documento entregue. 6. Use [Pesquisa e preço](/docs/mvpfy/pesquisa-e-preco) e [Tecnologia e operação](/docs/mvpfy/tecnologia-e-operacao) quando essas partes fizerem sentido para sua ideia. 7. Consulte [Progresso](/docs/mvpfy/progresso) para acompanhar as áreas do MVP pela CLI ou TUI. 8. Consulte o [catálogo de skills](/docs/mvpfy/skills) se quiser saber qual especialista trata cada assunto. ## Você pode continuar depois Você pode parar quando quiser. O MVPFy salva as respostas no projeto que você preparou e retoma a conversa depois. Ao dizer “continuar”, ele lê o que já foi registrado, encontra o próximo ponto relevante e mostra somente uma pergunta. Uma mensagem longa também é bem-vinda. Se você explicar que agências pequenas perdem leads recebidos por WhatsApp, formulário e Instagram, o MVPFy pode usar essa informação para descrever o problema, o público, os canais e a alternativa atual. Você não precisa repetir a mesma resposta em perguntas diferentes. ## Próximo passo Para acompanhar um exemplo concreto, abra [Primeiro MVP](/docs/mvpfy/primeiro-mvp). Se você já instalou o framework e precisa consultar uma regra, use o índice de [skills](/docs/mvpfy/skills). O guia de desenvolvimento fica separado para instalação e manutenção da implementação. ### O plano que você recebe: `MVP.md` - URL: https://promovaweb.com/docs/mvpfy/mvp - Descrição: `MVP.md` é a entrega central do MVPFy. Ele transforma a conversa em um plano que pode circular entre produto, desenvolvimento, marketing, vendas e operação a partir dos registros reunidos no documento. `MVP.md` é a entrega central do MVPFy. Ele transforma a conversa em um plano que pode circular entre produto, desenvolvimento, marketing, vendas e operação a partir dos registros reunidos no documento. ## Como ler o estado do plano | Estado | Significado | | --- | --- | | `preliminary` | Há conteúdo aproveitável, mas faltam escolhas importantes. | | `ready` | Os campos mínimos do primeiro SaaS estão descritos e coerentes. | | `validated` | As hipóteses principais já foram conferidas fora da entrevista. | O estado não funciona como uma nota. Ele mostra quanto do plano já tem base suficiente para orientar o próximo trabalho. ## O que o plano reúne O template atual reúne 37 áreas. Antes das áreas de planejamento, a seção **Analise de Requisitos** reúne toda a entrada recebida e organiza módulos, recursos, telas, ferramentas, pessoas, dados, fluxos e requisitos operacionais. O texto original de cada resposta permanece disponível para consulta. Em seguida, **Especificação funcional detalhada** oferece uma estrutura para consolidar princípios, papéis, entidades, jornadas, páginas, integrações, operações, restrições, questões abertas e próxima etapa. As demais áreas acompanham o caminho natural de uma empresa que sai da ideia e chega à primeira operação SaaS. Primeiro, o plano explica o ponto de partida: - resumo executivo. - empresa e contexto. - modelo da empresa SaaS. - problema. - comprovação, alternativas e hipóteses. - público-alvo. - usuária, cliente pagador e pagador. - personas. - proposta de valor e posicionamento. - nome, marca e slogan. Depois, ele descreve o produto e a relação com cada cliente: - jornada principal. - modelo multitenante, espaço, acesso e separação de dados. - onboarding e primeiro valor. - escopo funcional da versão 1.0. - módulos e funcionalidades. - perfis e permissões. - assinatura e cobrança. - suporte, retenção e cancelamento. - processos manuais. - itens fora do MVP. Por fim, o plano mostra como a empresa pode chegar ao mercado e operar: - concorrentes e alternativas. - modelo comercial e preço. - custos e economia unitária. - tecnologia e arquitetura. - infraestrutura e operação. - uso de IA. - website. - marketing. - vendas e lançamento. - métricas. - validações e dependências. - execução. - escolhas confirmadas. - hipóteses e pendências. - fontes. Cada seção possui um comentário estável, como ``. Se o nome visível mudar, o renderer ainda encontra o conteúdo pelo identificador. ## O que está confirmado e o que ainda falta O documento usa quatro rótulos para que uma sugestão não pareça uma certeza: - **Confirmado:** informação declarada por você ou respaldada por uma fonte. - **Recomendado:** sugestão de uma especialista, baseada no contexto disponível. - **Hipótese:** afirmação ainda não conferida com pessoas, mercado ou uso. - **Pendente:** informação necessária que ainda não foi fornecida. Essa separação impede que uma estimativa de preço pareça uma pesquisa concluída ou que uma sugestão de Laravel pareça uma exigência do produto. ## Como o plano evolui Quando o template evolui, `mvpfy-migrate` insere as seções novas, conserva o texto existente e marca os campos que precisam de resposta. Depois da atualização, a orquestradora continua pela primeira pergunta relevante, sempre uma por vez. ### Mercado, preço e custo - URL: https://promovaweb.com/docs/mvpfy/pesquisa-e-preco - Descrição: O MVPFy pesquisa o mercado quando você informa concorrentes, envia URLs ou solicita uma referência atual. A pesquisa ajuda a montar uma hipótese de preço, mas não substitui a conversa com potenciais clientes. O MVPFy pesquisa o mercado quando você informa concorrentes, envia URLs ou solicita uma referência atual. A pesquisa ajuda a montar uma hipótese de preço, mas não substitui a conversa com potenciais clientes. ## Quando você tem concorrentes para comparar Informe uma URL ou um nome. A skill `mvpfy-market` procura, quando os dados estão publicados: - o público e a promessa. - os recursos úteis para a comparação. - o preço mensal, anual ou sob consulta. - a moeda, os limites e as condições do plano. - a diferença entre concorrente direto, indireto e alternativa manual. O `MVP.md` registra fonte e data. Se o preço não estiver publicado, o plano escreve “não publicado”. O MVPFy não inventa uma faixa nem apresenta uma promoção como preço permanente. ## Quando não há concorrente direto Nesse caso, a conversa olha para o trabalho feito hoje. As perguntas continuam aparecendo uma por vez, com três respostas prontas, `Avançar` e `Conversar mais sobre este tema`. A investigação pode tratar de: - tempo gasto por mês. - ferramentas combinadas. - erros, perdas ou atrasos. - resultado que traria benefício suficiente para justificar o pagamento. Essas respostas ajudam a aproximar o valor percebido e escolher uma unidade de cobrança que seja fácil de explicar. ## Como surge a faixa de preço `mvpfy-pricing` considera cliente pagador, unidade de valor, frequência de uso, benefício, esforço comercial, custo variável, suporte e estágio da validação. Com esses dados, pode recomendar cobrança por espaço, por pessoa, por volume, por uso ou um modelo combinado. Quando houver dados suficientes, o plano compara três cenários: | Cenário | Uso | | --- | --- | | Mínimo | Poucos clientes, infraestrutura mínima e operação acompanhada de perto. | | Base | Volume inicial esperado e custos recorrentes conhecidos. | | Crescimento | Aumento de uso sem acrescentar complexidade antes de existir necessidade. | As espaços conceituais são: ```text custo mensal = fixos + variáveis + IA + comunicação + suporte + taxas margem por cliente = receita líquida - custo variável por cliente clientes para equilíbrio = custos fixos / margem por cliente MRR = soma da receita recorrente mensal dos clientes ativos ARPA = MRR / espaços pagantes ``` O resultado é uma faixa acompanhada das suas premissas. Não é previsão contábil e não garante receita. ### Primeiro MVP: do relato ao plano - URL: https://promovaweb.com/docs/mvpfy/primeiro-mvp - Descrição: Este exemplo acompanha uma ideia fictícia. Ele não descreve um produto real do MVPFy. A proposta é uma ferramenta para pequenas agências acompanharem leads recebidos por WhatsApp, formulário e Instagram. Este exemplo acompanha uma ideia fictícia. Ele não descreve um produto real do MVPFy. A proposta é uma ferramenta para pequenas agências acompanharem leads recebidos por WhatsApp, formulário e Instagram. ## Conte a ideia do jeito que ela vier Você pode começar com uma frase curta: ```text Quero criar um sistema para pequenas agências que perdem leads dos clientes. ``` Também pode enviar tudo o que já imaginou em uma única mensagem: ```text Quero um SaaS para pequenas agências acompanharem leads dos clientes. A agência paga, o cliente acompanha apenas os próprios contatos e o MVP deve receber o lead, atribuí-lo a alguém e mostrar um resumo. Já imagino CRM, integração com WhatsApp e um painel. Quero usar Laravel em uma VPS e cobrar mensalidade. ``` O agente lê a mensagem inteira antes de perguntar. CRM, WhatsApp e painel entram como ideias para examinar. Problema, público, jornada, tecnologia e cobrança podem receber informações desde o primeiro relato. Você também pode mandar outra mensagem antes de escolher `4. Avançar`. O MVPFy acolhe esse complemento e só começa a entrevista fechada depois que você indicar que terminou de apresentar a ideia. O ponto de partida não é transformar cada recurso citado em módulo. Primeiro, o MVPFy tenta entender a situação que faz alguém procurar o produto. ## Veja como uma pergunta aparece Uma conversa possível: ```text MVPFy: Em qual situação o problema aparece com mais frequência? 1. A equipe recebe contatos em vários canais e perde o acompanhamento. 2. A equipe demora para responder ao primeiro contato. 3. A equipe não consegue mostrar resultados para o cliente. 4. Avançar 5. Conversar mais sobre este tema Você: 1 MVPFy: resposta salva. Qual pessoa usaria o produto no trabalho diário? 1. A equipe da agência. 2. O cliente da agência. 3. A equipe e o cliente, com acessos diferentes. 4. Avançar 5. Conversar mais sobre este tema ``` O texto “resposta salva” representa uma etapa interna obrigatória. A próxima pergunta só aparece depois do registro no `answers.jsonl` e da atualização do estado do projeto. Se você escolher 5, pode explicar um caso, perguntar o significado de uma opção ou enviar uma resposta complexa. O MVPFy continua conversando sobre o mesmo assunto, salva cada turno e mostra no máximo uma pergunta principal. ## Envie mais contexto quando precisar Você não precisa escolher apenas um número. Esta resposta também é válida: ```text A agência paga. Cada cliente deve acompanhar somente os próprios leads, e a equipe da agência precisa administrar tudo em um espaço. ``` Essa frase já informa a empresa cliente, a responsável pelo pagamento, o titular do espaço e as pessoas usuárias, permissões e separação entre clientes. O MVPFy aproveita essas informações e não pergunta novamente qual empresa fará o pagamento. ## Transforme a ideia em uma jornada Depois de entender o problema, a conversa procura um caminho completo para o primeiro valor. No exemplo, o fluxo poderia ser: 1. A agência cria um espaço. 2. A equipe cadastra um cliente. 3. O sistema recebe ou registra um lead. 4. A equipe atribui o lead a alguém. 5. O cliente acompanha o andamento. 6. A agência mostra o resultado em um resumo simples. O MVPFy pergunta quais dessas etapas precisam funcionar na primeira versão. Um aplicativo móvel, um marketplace e automações avançadas podem ficar para depois se não ajudarem a provar esse caminho. ## Explique como o serviço começa O plano registra a agência como espaço pagadora e limita o acesso de cada cliente aos próprios leads. Também descreve o primeiro valor: registrar um lead, atribuí-lo e acompanhar seu andamento. A conversa ainda trata do teste, da implantação assistida e do sinal que confirma a ativação. ## Compare alternativas e monte uma faixa de preço Se você fornecer URLs de concorrentes, a especialista de mercado consulta os planos, limites e preços publicados e registra a fonte e a data. Sem uma referência direta, a conversa olha para o que a agência gasta hoje com planilhas, horas de acompanhamento e leads perdidos. A especialista de preço transforma esses dados em uma faixa inicial. Isso é uma hipótese comercial, não uma promessa. O documento pode comparar um cenário mínimo, um cenário base e um cenário de crescimento. ## Gere o `MVP.md` Quando você pedir “gerar o documento”, o MVPFy reúne as áreas já trabalhadas. Uma primeira versão pode ter estado `preliminary` e indicar `Pendente` onde faltarem informações. Depois, com problema, público, jornada, escopo, modelo SaaS, preço, tecnologia, aquisição, métricas e comprovações suficientes, o documento pode receber o estado `ready`. ## Use o plano com as equipes O `MVP.md` permite que as equipes partam do mesmo entendimento: - produto encontra o escopo e as condições de aceite. - desenvolvimento encontra arquitetura, espaços e integrações. - website encontra público, promessa e oferta. - marca encontra posicionamento, nomes e tom. - marketing encontra canais, conteúdo e captação. - vendas encontra preço, processo e objeções. - operação encontra onboarding, suporte e métricas. ### Acompanhe o progresso do MVP - URL: https://promovaweb.com/docs/mvpfy/progresso - Descrição: O arquivo `MVP.md` cresce enquanto a entrevista registra respostas e recomendações. A skill `mvpfy-progress` apresenta esse estado sem abrir uma pergunta nova. Ela pode ser usada quando você quiser saber o que já está claro e qual assunto ainda precisa de atenção. O arquivo `MVP.md` cresce enquanto a entrevista registra respostas e recomendações. A skill `mvpfy-progress` apresenta esse estado sem abrir uma pergunta nova. Ela pode ser usada quando você quiser saber o que já está claro e qual assunto ainda precisa de atenção. ## Pelo terminal Na raiz do projeto consumidor: ```bash mvpfy progress --project . ``` O resultado agrupa o plano em Problema, Público, Produto, SaaS, Mercado e preço, Tecnologia, Marketing e Validação. O percentual é uma indicação de preenchimento das seções encontradas no `MVP.md`, ele não substitui a leitura das hipóteses e dos pontos ainda abertos. Para abrir o painel: ```bash mvpfy --project . ``` Na aba **Home**, você vê o resumo geral, as áreas e o próximo ponto. Na aba **Áreas**, pode navegar por cada grupo e ver quais seções estão completas. Na aba **MVP.md**, o documento é renderizado com cores e pode ser percorrido com as setas do terminal. Essa leitura não altera o arquivo. ## Instalação e atualização no painel A aba **Skills** oferece duas ações: - `I` instala ou reconcilia as skills do MVPFy, - `R` atualiza as skills já instaladas. As ações executam `npx skills add promovaweb/mvpfy --skill '*' --agent claude-code codex --copy --yes` e `npx skills update --project --yes`. A instalação é feita somente para Claude Code e Codex. O MVPFy não substitui o CLI oficial nem cria uma cópia paralela da instalação. ## Como interpretar o resumo ```text Progresso do MVP: 48% ✓ Problema: 100% (2/2) ◐ Produto: 60% (3/5) ○ Marketing: 0% (0/3) Próximo ponto: Preencher a seção marketing ``` Uma área concluída tem todas as seções encontradas preenchidas. Uma área em andamento possui parte do conteúdo definido. Uma área pendente ainda não tem informação suficiente no documento. O modelo de atendimento SaaS aparece à parte porque a escolha entre multitenante compartilhado e instalação separada afeta várias áreas. ## Sem TUI Para agentes e automações, use JSON: ```bash mvpfy progress --project . --json ``` Esse formato inclui as áreas, seções pendentes, estado da entrevista, modelo SaaS e próximo ponto. O comando é somente de leitura. ### O que o MVPFy prepara - URL: https://promovaweb.com/docs/mvpfy/proposta - Descrição: O MVPFy foi criado para o primeiro momento de uma empresa. Você tem uma ideia de software, ainda precisa descobrir o recorte comercial e quer chegar a uma versão que possa ser construída, vendida e aprendida com clientes reais. O MVPFy foi criado para o primeiro momento de uma empresa. Você tem uma ideia de software, ainda precisa descobrir o recorte comercial e quer chegar a uma versão que possa ser construída, vendida e aprendida com clientes reais. ## O plano que sai da conversa Ao terminar a entrevista, o MVPFy reúne o trabalho em um único arquivo chamado `MVP.md`. O arquivo serve como ponto de encontro para produto, desenvolvimento, website, marca, marketing, vendas e operação. Você não recebe uma cópia bruta da conversa. O plano separa o que você descreveu, o que uma especialista recomendou, o que ainda precisa ser testado e o que continua sem resposta. Assim, uma equipe consegue ler o contexto a partir dos registros reunidos no documento. O plano cobre as perguntas que mais afetam a primeira versão: - a empresa, o contexto e a forma de oferecer o SaaS. - o problema, a alternativa usada hoje e a hipótese de valor. - o público, o cliente pagador, o pagador, as pessoas usuárias e as personas. - a promessa, a jornada central e o limite da versão 1.0. - o espaço, o onboarding, a ativação, a assinatura, o suporte e o cancelamento. - o posicionamento inicial, o nome, a marca e o slogan. - concorrentes, preços observados e alternativas manuais. - preço, custo operacional, receita recorrente e margem estimada. - Laravel, VPS, banco, arquivos, e-mail, IA e rotina de operação. - website, conteúdo, captação, vendas, lançamento, métricas e próximos passos. ## O que fica fora deste trabalho O MVPFy não constrói o software, publica o website ou entrega um logo final. Ele prepara o contexto para que outros agentes e equipes executem essas atividades com menos suposições. O framework também não cria `spec.md`, não altera o Specsfy e não converte o `MVP.md` em uma especificação do Specsfy. O MVPFy possui seu próprio arquivo, seu próprio estado e seus próprios scripts. ## Por que o plano trata o serviço inteiro Uma lista de funcionalidades não explica como um SaaS funciona. O plano precisa mostrar qual pessoa cria o espaço, qual pessoa usa, qual pessoa paga, como a primeira pessoa chega ao valor e o que acontece com o acesso depois. Durante a validação, algumas tarefas podem continuar manuais. Uma pessoa pode liberar um espaço, acompanhar a implantação e conferir um pagamento enquanto a equipe aprende com os primeiros clientes. O `MVP.md` registra essa rotina, seu responsável e o momento previsto para automatizá-la. ## O limite da versão 1.0 O plano procura manter quatro pontos ligados: um público prioritário, um problema principal, uma promessa central e uma jornada capaz de entregar essa promessa do começo ao fim. Um recurso pode ser útil e ainda assim ficar para depois se não for necessário para testar essa combinação. ## Recomendação não é obrigação O MVPFy pode sugerir Laravel, VPS, Supabase, armazenamento de objetos e um provedor de IA. Essas escolhas partem do padrão da Promovaweb e do contexto fornecido por você. O plano também registra a razão da recomendação e o sinal que justificaria uma revisão. ### As especialistas que trabalham no MVPFy - URL: https://promovaweb.com/docs/mvpfy/skills - Descrição: Você conversa apenas com `$mvpfy`. A orquestradora lê o que já foi registrado, escolhe a especialista adequada e incorpora o retorno ao plano. Você não precisa chamar cada skill manualmente. Conhecer o papel de cada uma ajuda a entender por que determinada pergunta apareceu. Você conversa apenas com `$mvpfy`. A orquestradora lê o que já foi registrado, escolhe a especialista adequada e incorpora o retorno ao plano. Você não precisa chamar cada skill manualmente. Conhecer o papel de cada uma ajuda a entender por que determinada pergunta apareceu. ## Ordem típica ```text contexto existente ↓ problema → público → produto → SaaS ↓ ↓ ↓ ↓ mercado → preço → tecnologia → marketing ↓ marca → MVP.md → migração quando o template mudar ``` Essa ordem é apenas um caminho comum. Um documento já existente pode preencher uma área inteira, e uma resposta nova pode levar a conversa de volta para um assunto anterior. A orquestradora acompanha o conteúdo disponível, não uma lista fixa de perguntas. ## Skills | Skill | Quando entra | O que acrescenta ao plano | | --- | --- | --- | | [`mvpfy`](/docs/mvpfy/skills/mvpfy) | Sempre que você inicia ou retoma | Próxima pergunta e estado integrado | | [`mvpfy-context`](/docs/mvpfy/skills/mvpfy-context) | Setup e início de cada conversa | Specs, código, stack e lacunas disponíveis | | [`mvpfy-problem`](/docs/mvpfy/skills/mvpfy-problem) | O problema ainda está genérico | Declaração do problema e hipótese | | [`mvpfy-audience`](/docs/mvpfy/skills/mvpfy-audience) | Público ou papéis estão misturados | Segmento, ICP e personas | | [`mvpfy-product`](/docs/mvpfy/skills/mvpfy-product) | A solução precisa virar escopo | Jornada, módulos e versão 1.0 | | [`mvpfy-saas`](/docs/mvpfy/skills/mvpfy-saas) | É preciso explicar o serviço recorrente | Espaço do cliente, onboarding e ciclo do cliente | | [`mvpfy-brand`](/docs/mvpfy/skills/mvpfy-brand) | Produto e público já têm direção | Nome, posicionamento e slogan | | [`mvpfy-market`](/docs/mvpfy/skills/mvpfy-market) | Há concorrentes ou URLs | Comparação de mercado e fontes | | [`mvpfy-pricing`](/docs/mvpfy/skills/mvpfy-pricing) | Valor e cobrança precisam de hipótese | Faixas, planos e cenários | | [`mvpfy-technology`](/docs/mvpfy/skills/mvpfy-technology) | A jornada permite desenhar a base técnica | Arquitetura Laravel e custos | | [`mvpfy-marketing`](/docs/mvpfy/skills/mvpfy-marketing) | Oferta e público precisam chegar ao mercado | Aquisição, conteúdo e venda | | [`mvpfy-document`](/docs/mvpfy/skills/mvpfy-document) | Você pede o plano ou há dados suficientes | `MVP.md` renderizado e validado | | [`mvpfy-migrate`](/docs/mvpfy/skills/mvpfy-migrate) | O template mudou | Documento atualizado sem perda | | [`mvpfy-progress`](/docs/mvpfy/skills/mvpfy-progress) | Você quer ver o andamento sem abrir uma pergunta | Resumo por áreas e próxima lacuna | Cada página explica o que a especialista recebe, como trabalha, o que entrega e onde termina sua responsabilidade. Os exemplos usam uma ideia de SaaS para mostrar a passagem de uma etapa para outra. O catálogo descreve o MVPFy. Ele não altera a biblioteca Specsfy. ### A orquestradora: `mvpfy` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy - Descrição: `mvpfy` é a orquestradora e o único ponto de conversa. Antes de escolher a primeira pergunta, ela chama `mvpfy-context` para verificar se o projeto já tem material aproveitável. Depois ela não tenta saber tudo sobre produto, preço ou tecnologia. Em vez disso, lê o contexto existente, chama a especialista certa, controla a entrevista e reúne o resultado no `MVP.md`. `mvpfy` é a orquestradora e o único ponto de conversa. Antes de escolher a primeira pergunta, ela chama `mvpfy-context` para verificar se o projeto já tem material aproveitável. Depois ela não tenta saber tudo sobre produto, preço ou tecnologia. Em vez disso, lê o contexto existente, chama a especialista certa, controla a entrevista e reúne o resultado no `MVP.md`. ## Quando usar Use `$mvpfy` para começar, continuar, pausar, corrigir uma escolha, revisar uma área ou gerar o `MVP.md`. ## De onde ela parte - `.mvpfy/existing-project.json`, renovado no setup e no início da conversa. - `.mvpfy/config.yaml`. - `.mvpfy/state.json`. - `.mvpfy/answers.jsonl`. - `MVP.md`. - template atual. - specs, backlogs, briefs, docs, tickets e planos já existentes no projeto consumidor, sempre em modo somente leitura, resumidos pela `mvpfy-context` e consultados quando necessário. Esses arquivos servem como referência. A orquestradora pode usar uma informação já registrada para evitar uma pergunta, mas não escreve nem corrige esses documentos. Quando o relatório encontra manifestos e código, ele pode sugerir a stack e confirmar que existe uma base técnica. Quando encontra uma spec, ele aponta o arquivo e um trecho curto para orientar a leitura. O código sozinho não define o problema, o público, o pagador ou o recorte do MVP. ## Como ela conduz a conversa 1. Confere se o projeto é um primeiro SaaS. 2. Reaproveita o material já disponível. 3. Verifica se o template precisa de atualização. 4. Escolhe o ponto que mais afeta o plano. 5. Exibe exatamente uma pergunta principal. 6. Registra a resposta antes de prosseguir. 7. Recalcula as áreas cobertas e as mudanças de direção. 8. Chama a especialista adequada. ## Regra rígida de saída Uma resposta pode conter confirmação, contexto curto e opções, mas somente uma pergunta que pede resposta. Ela sempre termina com três opções prontas, `4. Avançar` e `5. Conversar mais sobre este tema`. Nunca apresente um formulário, duas perguntas encadeadas ou “responda A e B”. Se duas áreas estiverem pendentes, escolha a mais importante e deixe a outra para o próximo turno. `Avançar` encerra a etapa com o entendimento atual. `Conversar mais sobre este tema` abre texto livre sobre a mesma pergunta. A conversa pode continuar por mais de uma mensagem, mas nunca apresenta uma segunda pergunta principal no mesmo turno. ## Limite sobre fontes externas ao MVPFy Specs, backlogs e documentos do projeto podem ser lidos como contexto. O MVPFy não cria, altera, renomeia, remove ou migra esses arquivos. O único documento final que ele escreve é `MVP.md`, além do estado em `.mvpfy/`. ## Regra para a documentação e o ebook O guia do usuário e a referência técnica são percursos diferentes. A orquestradora pode consultar a documentação técnica para entender o produto, mas o ebook do usuário usa somente as páginas listadas em `docs/user/reading-order.txt`. Antes de publicar uma nova edição, leia as páginas completas. Confirme que os exemplos ajudam uma pessoa leiga, que a prosa explica a razão das orientações e que listas e tabelas não substituem o raciocínio. O padrão visual dos projetos do Hub serve como referência de organização, não como texto para copiar. ### O público: `mvpfy-audience` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-audience - Descrição: Esta especialista separa o mercado amplo do primeiro grupo que vale atender. Também diferencia a pessoa que usa o produto, a pessoa que compra, a responsável pelo pagamento, o contato que influencia a compra e o grupo que recebe o benefício. Essa distinção evita que “qualquer empresa” vire o público inteiro do MVP. Esta especialista separa o mercado amplo do primeiro grupo que vale atender. Também diferencia a pessoa que usa o produto, a pessoa que compra, a responsável pelo pagamento, o contato que influencia a compra e o grupo que recebe o benefício. Essa distinção evita que “qualquer empresa” vire o público inteiro do MVP. ## O que ela procura - frequência e intensidade do problema por segmento. - acesso ao público. - capacidade de pagar. - comportamento atual. - objeções e gatilhos. - canais de comunicação. - diferenças entre uso e compra. ## O que entra no `MVP.md` O `MVP.md` recebe um segmento prioritário e, no máximo, três personas úteis: produto, compra e marketing quando forem diferentes. Cada uma descreve contexto, objetivo, dor, alternativa, objeção, gatilho e canal. A intenção não é criar biografias, e sim dar à equipe elementos para construir e vender. ## Exemplo Na ferramenta para agências, a agência pode ser compradora e pagadora, a pessoa de atendimento pode ser usuária diária e o cliente da agência pode ser um usuário com permissão limitada. Essa distinção afeta produto, SaaS, preço e marketing. ## Onde termina este trabalho Esta especialista não inventa biografias para preencher espaço nem mantém três públicos prioritários ao mesmo tempo. Quando houver um segmento e um resultado central, ela entrega o contexto para `mvpfy-product`. ### A marca: `mvpfy-brand` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-brand - Descrição: Esta especialista prepara a direção da marca depois que problema, público e promessa já têm uma base. O trabalho ajuda a escolher uma linguagem para o produto e orientar naming e comunicação. Disponibilidade de domínio ou registro de marca só entra como fato depois de uma pesquisa própria. Esta especialista prepara a direção da marca depois que problema, público e promessa já têm uma base. O trabalho ajuda a escolher uma linguagem para o produto e orientar naming e comunicação. Disponibilidade de domínio ou registro de marca só entra como fato depois de uma pesquisa própria. ## O que entra no plano - categoria. - posicionamento em uma frase. - benefício central. - diferenciais. - personalidade e tom. - palavras a usar e evitar. - regras para o nome. - sugestões de nome quando solicitadas. - slogans curtos. - direção visual conceitual. ## Um exemplo Se o valor for dar visibilidade aos leads para agências pequenas, o posicionamento deve falar de acompanhamento e resultado. A marca não precisa depender de uma promessa genérica de inteligência artificial. ## Onde termina este trabalho Esta especialista não cria o logo final, não confirma disponibilidade sem pesquisa e não usa o nome para encobrir um problema ainda indefinido. ### O contexto existente: `mvpfy-context` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-context - Descrição: `mvpfy-context` procura material que já existe no projeto antes de a conversa começar. Assim, um projeto vazio segue pelo relato livre da ideia, enquanto uma aplicação com specs e código oferece um ponto de partida concreto. `mvpfy-context` procura material que já existe no projeto antes de a conversa começar. Assim, um projeto vazio segue pelo relato livre da ideia, enquanto uma aplicação com specs e código oferece um ponto de partida concreto. ## Quando ela entra A análise acontece em dois momentos: - durante `mvpfy install` ou `setup-project.mjs`, - no início de cada conversa iniciada ou retomada com `$mvpfy`. Para executar a leitura manualmente, use: ```bash node skills/mvpfy-context/scripts/analyze-existing-project.mjs --project . ``` O arquivo `.mvpfy/existing-project.json` recebe o relatório atual. O `state.json` guarda apenas o resumo necessário para a orquestradora localizar o relatório sem aumentar o histórico da conversa. ## O que ela procura O scanner percorre documentos com nomes e pastas usados com frequência em projetos, como `spec.md`, `specs/`, `backlog/`, `briefs/`, `plans/`, `docs/`, `product/` e `decisions/`. Também lê manifestos como `package.json`, `composer.json`, `pyproject.toml`, `go.mod` e `Cargo.toml`. Os arquivos de programação entram no relatório com caminho, linguagem e número de linhas. Dependências e scripts dos manifestos ajudam a reconhecer a stack. Pastas geradas, dependências instaladas, caches, cobertura, builds e o repositório Git ficam fora da leitura. ## Como a conversa aproveita o resultado Imagine um projeto que já tem `specs/checkout.md`, `composer.json` com Laravel e uma pasta `app/`. A análise pode sugerir que existe uma base Laravel e apontar a spec do checkout. A orquestradora usa esse material para evitar uma pergunta repetida sobre a stack e começa a conversa perguntando pelo problema, pelo público ou pelo recorte que ainda não aparece nos arquivos. O relatório separa sugestão técnica de escolha confirmada. Uma rota chamada `/customers` mostra que existe uma implementação relacionada a clientes, mas não confirma quem paga, qual dor levou ao projeto nem quais recursos entram na versão 1.0. Esses pontos continuam na conversa e aparecem como pendências até que a pessoa os confirme. ## Proteção do projeto analisado O MVPFy não altera as specs, o código, os arquivos do Specsfy nem os documentos encontrados. A única escrita acontece em `.mvpfy/`, para guardar o relatório e seu resumo. O conteúdo do relatório fica local ao projeto e não é enviado para um serviço externo pelo script. ### O documento final: `mvpfy-document` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-document - Descrição: Esta skill monta e confere o arquivo final. Ela não cria o conteúdo dos domínios. Recebe fatos, escolhas, recomendações, hipóteses e pendências da orquestradora e os organiza no template do `MVP.md`. Esta skill monta e confere o arquivo final. Ela não cria o conteúdo dos domínios. Recebe fatos, escolhas, recomendações, hipóteses e pendências da orquestradora e os organiza no template do `MVP.md`. ## Arquivos que ela usa - `assets/MVP.template.md`. - `scripts/render-company.mjs`. - `scripts/validate-company.mjs`. - `references/document-rules.md`. ## Como ela é executada ```bash node skills/mvpfy-document/scripts/render-company.mjs --project . node skills/mvpfy-document/scripts/validate-company.mjs --project . ``` O renderer localiza os identificadores estáveis, mantém o conteúdo existente e usa “Pendente” quando ainda não há informação. O validator confere se as áreas necessárias para um primeiro SaaS aparecem no arquivo. Durante a renderização, a skill também monta `Analise de Requisitos`. Ela lê a ideia inicial, cada resposta original, a interpretação salva, os campos cobertos e o relatório do projeto existente. O resultado lista os elementos citados por tipo e mantém uma tabela de rastreabilidade para que uma descrição ampla do sistema não seja reduzida às oito perguntas fechadas. Quando o `MVP.md` alimentar um ebook, a ordem deve incluir somente o guia do usuário. A especificação e a referência de desenvolvimento ficam fora do PDF e do EPUB. Depois do build, leia o resultado completo para conferir voz, exemplos, ritmo e separação de públicos. Os validadores confirmam estrutura e integridade do arquivo, mas não substituem a leitura editorial. O PDF, o EPUB e o manifesto usam a mesma versão do framework. `VERSION` é a fonte canônica e `ebooks/VERSION` funciona apenas como espelho de conferência. ## Onde termina este trabalho Esta skill não cria `spec.md`, não edita backlog e não apaga uma resposta para colocar um texto genérico no lugar. ### O mercado: `mvpfy-market` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-market - Descrição: Esta especialista pesquisa concorrentes e alternativas quando você fornece referências ou pede dados atuais. Ela registra o que encontrou com fonte e data, separando informação publicada de interpretação. Esta especialista pesquisa concorrentes e alternativas quando você fornece referências ou pede dados atuais. Ela registra o que encontrou com fonte e data, separando informação publicada de interpretação. ## O que ela compara - concorrente direto, indireto e alternativa manual. - público e promessa. - recursos comparáveis. - preço, moeda, periodicidade e limites. - lacuna percebida. - condições promocionais ou preço sob consulta. ## O que entra no `MVP.md` Uma tabela no `MVP.md` com referência, tipo, público, promessa, recursos, preço, lacuna, link e data da consulta. ## Um exemplo Se uma página mostra “US$ 49 por mês para cinco usuários”, o plano registra o preço, a moeda e o limite. Se a página só diz “fale com vendas”, o documento registra preço não publicado. A falta do preço também é um dado sobre a forma de venda. ## Onde termina este trabalho Esta especialista não inventa preço, não trata uma página antiga como atual e não coloca um recurso no MVP apenas porque um concorrente o oferece. ### A entrada no mercado: `mvpfy-marketing` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-marketing - Descrição: Esta especialista prepara a chegada do primeiro SaaS ao mercado. Ela conecta promessa, público, oferta, conteúdo, captação e venda em poucos canais que a empresa consiga manter na rotina. Esta especialista prepara a chegada do primeiro SaaS ao mercado. Ela conecta promessa, público, oferta, conteúdo, captação e venda em poucos canais que a empresa consiga manter na rotina. ## O que entra no plano - mensagem principal. - objeções e respostas. - oferta inicial. - website mínimo. - canal prioritário. - conteúdo por etapa. - lead magnet quando fizer sentido. - e-mail marketing. - grupos e redes sociais. - demonstração ou venda assistida. - métricas de aquisição, ativação, conversão e retenção. ## Um exemplo Para agências, o primeiro conteúdo pode mostrar o caminho de um lead desde o contato até o retorno ao cliente. O canal só entra no plano se as agências estiverem presentes nele e a equipe conseguir manter essa rotina. ## Onde termina este trabalho Esta especialista não recomenda todos os canais, não cria uma campanha final e não define a mensagem sem usar o público e a proposta registrados antes. ### A atualização do template: `mvpfy-migrate` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-migrate - Descrição: Esta skill cuida da atualização do `MVP.md` quando o template evolui. Ela usa IDs de seção e a versão do schema para acrescentar o que falta sem apagar o plano que você já construiu. Esta skill cuida da atualização do `MVP.md` quando o template evolui. Ela usa IDs de seção e a versão do schema para acrescentar o que falta sem apagar o plano que você já construiu. ## Como a atualização acontece 1. Ler a versão do documento. 2. Localizar os identificadores existentes. 3. Comparar o arquivo com o template atual. 4. Inserir as seções ausentes. 5. Preservar o conteúdo preenchido. 6. Marcar campos novos como pendentes. 7. Atualizar a versão depois de uma gravação válida. 8. Entregar à orquestradora uma única pergunta nova relevante. ## Um exemplo Se o template ganhar “Plano de onboarding” e o documento já descrever convite e primeiro valor em outra seção, o texto antigo permanece. A nova seção recebe uma síntese segura ou “Pendente”. O MVPFy pergunta somente o detalhe que não puder ser entendido a partir do material existente. ## Onde termina este trabalho Esta skill não remove histórico, não duplica seções, não migra arquivos do Specsfy e não cria uma série de perguntas em lote. ### O preço: `mvpfy-pricing` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-pricing - Descrição: Esta especialista transforma valor, custo e comportamento de compra em uma hipótese comercial que possa ser testada. Ela procura uma cobrança fácil de explicar e ligada ao valor percebido, sem exigir medições que o primeiro produto ainda não precisa fazer. Esta especialista transforma valor, custo e comportamento de compra em uma hipótese comercial que possa ser testada. Ela procura uma cobrança fácil de explicar e ligada ao valor percebido, sem exigir medições que o primeiro produto ainda não precisa fazer. ## O que ela procura - cliente pagador e pagador. - unidade de valor. - ticket imaginado. - preço de alternativas. - benefício financeiro ou operacional. - custo fixo e variável. - suporte e esforço de venda. - implantação, teste e inadimplência. - MRR, ARPA e clientes para equilíbrio. ## O que entra no plano O plano apresenta faixa de preço, premissas, modelo de cobrança e cenários mínimo, base e crescimento. Quando os dados são insuficientes, a especialista marca a faixa como hipótese. ## Um exemplo Se o valor surge da gestão de vários clientes, cobrar por espaço da agência pode ser mais simples do que cobrar por cada lead. Essa é uma sugestão para testar com potenciais clientes, não uma regra universal. ## Onde termina este trabalho Esta especialista não oferece precisão contábil, não promete margem e não fixa o preço sem considerar custo operacional e disposição de pagamento. ### O problema: `mvpfy-problem` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-problem - Descrição: Esta especialista ajuda a tirar a conversa do nome da solução. “Preciso de um aplicativo” pode ser o começo do relato, mas o plano precisa explicar o que acontece hoje, qual grupo enfrenta a situação e qual consequência torna a mudança valiosa. Esta especialista ajuda a tirar a conversa do nome da solução. “Preciso de um aplicativo” pode ser o começo do relato, mas o plano precisa explicar o que acontece hoje, qual grupo enfrenta a situação e qual consequência torna a mudança valiosa. ## O que ela procura - situação e frequência. - pessoa afetada. - tarefa que ela tenta realizar. - impacto atual. - alternativa usada hoje. - motivo da insuficiência. - comprovações já disponíveis. - hipótese que o MVP deve testar. ## O que entra no `MVP.md` ```text Para [público], que precisa [tarefa], o problema é [dificuldade], causando [impacto]. Hoje usa [alternativa], que falha porque [limitação]. O MVP deve testar [hipótese]. ``` ## Um exemplo “Agências perdem leads” ainda não explica a frequência, a consequência nem a alternativa atual. Se o contexto já disser que os contatos chegam por três canais e terminam em planilhas, a especialista aproveita esses dados. Ela pergunta somente o ponto que ainda muda a leitura do problema. ## Onde termina este trabalho Esta especialista não escolhe framework, cria módulos ou define preço. Quando o grupo afetado estiver claro, ela entrega o contexto para `mvpfy-audience`. ### O produto: `mvpfy-product` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-product - Descrição: Esta especialista transforma o problema e o público em uma primeira versão que alguém consegue usar e comprar. Ela começa pela jornada principal. A lista de recursos só entra depois, quando fica claro o trabalho que cada item apoia. Esta especialista transforma o problema e o público em uma primeira versão que alguém consegue usar e comprar. Ela começa pela jornada principal. A lista de recursos só entra depois, quando fica claro o trabalho que cada item apoia. ## O que ela procura - promessa central. - entrada, processamento e saída. - jornada de ponta a ponta. - evento de ativação. - módulos essenciais. - perfis e permissões. - regras de negócio. - integrações indispensáveis. - itens posteriores. ## Como separa o escopo | Classe | Uso | | --- | --- | | Essencial | Sem o item, a promessa não é entregue. | | Necessária | Apoia operação, segurança ou cobrança inicial. | | Posterior | Pode esperar aprendizado. | | Descartada | Não atende ao problema prioritário. | ## Um exemplo No caso dos leads, registrar um contato, atribuí-lo e mostrar seu andamento podem formar a jornada principal. Um aplicativo móvel e um marketplace podem ser úteis no futuro, mas não entram apenas por parecerem interessantes. ## Onde termina este trabalho Esta especialista não define sozinha qual pessoa paga ou como o espaço começa. Ela encaminha essas perguntas para `mvpfy-saas` e depois ajusta o escopo com as restrições recebidas. ### `mvpfy-progress` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-progress - Descrição: Esta skill lê o estado e o `MVP.md` para mostrar o andamento do planejamento. Ela não conduz a entrevista, não salva resposta e não altera arquivos do Specsfy. Esta skill lê o estado e o `MVP.md` para mostrar o andamento do planejamento. Ela não conduz a entrevista, não salva resposta e não altera arquivos do Specsfy. ## O que ela apresenta - percentual geral do plano, - andamento por área, - respostas salvas e último ponto da entrevista, - modelo multitenante ou instalação separada, - primeira seção ainda pendente. O percentual é uma referência de preenchimento. Uma seção pode conter uma recomendação e ainda precisar de confirmação na entrevista. ## Exemplo ```text Progresso do MVP: 48% Concluído: Problema e Público. Em andamento: Produto e SaaS. Pendente: Marketing e Validação. Próximo ponto: definir o primeiro canal de aquisição. ``` Para abrir a visão completa, use `mvpfy progress` ou a aba **Progresso** da TUI. Para ler o documento inteiro com cores, use a aba **MVP.md**. ### O serviço recorrente: `mvpfy-saas` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-saas - Descrição: Esta especialista explica o que acontece ao redor do software. Um SaaS não termina quando a pessoa entra na tela principal. Uma pessoa precisa criar o espaço, usar o serviço, pagar, receber suporte e encerrar o acesso quando necessário. Esta especialista explica o que acontece ao redor do software. Um SaaS não termina quando a pessoa entra na tela principal. Uma pessoa precisa criar o espaço, usar o serviço, pagar, receber suporte e encerrar o acesso quando necessário. Ela começa confirmando se várias empresas ou equipes usarão a mesma aplicação. Essa pergunta vem logo depois da ideia inicial. Se a resposta for multitenante, a especialista faz no máximo uma pergunta curta sobre a unidade do espaço e sua administração antes de tratar preço ou arquitetura. ## O que ela procura - B2B, B2C ou profissionais independentes. - titular do espaço e pessoas usuárias. - separação dos dados entre espaços. - convite, demonstração ou teste. - onboarding e primeiro valor. - ativação. - unidade de valor. - assinatura, limites e excedentes. - cancelamento, inadimplência e suporte. - processos manuais aceitáveis durante a validação. Com essa resposta, ela recomenda: - unidade do tenant. - titularidade e administração. - convites, membros e papéis. - participação de uma pessoa em vários tenants. - limite dos dados e banco. - criação e configuração de novos tenants. Esses itens não abrem uma fila adicional. Eles aparecem como recomendações para o MVP, usando o suporte de Teams do Laravel quando fizer sentido. ## Um exemplo Uma agência pode criar o espaço, adicionar seus clientes e manter a cobrança no próprio contrato. Cada cliente acompanha seus leads, sem acesso aos dados de outros espaços. Esse arranjo muda permissões, preço e onboarding. Quando Laravel for escolhido, o plano avalia o suporte de Teams da solução adotada para equipes, membros, convites e papéis. Teams ajuda na associação de pessoas ao tenant, mas não substitui as regras de isolamento e autorização. ## Ponto de partida técnico Para muitos primeiros produtos, uma aplicação compartilhada com separação lógica segura atende bem. Uma instância dedicada só deve aparecer quando segurança, contrato, desempenho ou posicionamento justificarem esse desenho. ## Onde termina este trabalho Esta especialista não presume que a cobrança precisa ser totalmente automática no primeiro dia. Se uma operação acompanhada ajudar a validar a oferta, o plano pode registrá-la como parte provisória do serviço. ### Setup do MVPFy: `$mvpfy-setup` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-setup - Descrição: Use `$mvpfy-setup` para instalar as skills, criar os arquivos do planejamento e conferir se o projeto pode iniciar ou retomar a entrevista. Use `$mvpfy-setup` para instalar as skills, criar os arquivos do planejamento e conferir se o projeto pode iniciar ou retomar a entrevista. ## Um comando para começar Na raiz do projeto consumidor, execute: ```bash npx --yes @promovaweb/mvpfy install --project . ``` O comando instala as skills e prepara `MVP.md` e `.mvpfy/`. Se esses arquivos já existirem, ele preserva as respostas e a estrutura atual. ## Conferência e atualização Use os comandos abaixo para verificar o resultado ou atualizar as skills: ```bash mvpfy doctor --project . mvpfy progress --project . mvpfy update --project . ``` O setup não cria nem modifica arquivos do Specsfy. O resultado do MVPFy fica somente em `MVP.md` e `.mvpfy/`. ### A tecnologia: `mvpfy-technology` - URL: https://promovaweb.com/docs/mvpfy/skills/mvpfy-technology - Descrição: Esta especialista traduz a jornada do MVP em uma arquitetura pequena, operável e compatível com o momento da empresa. A tecnologia deve apoiar o primeiro aprendizado sem criar uma operação maior do que o produto precisa. Esta especialista traduz a jornada do MVP em uma arquitetura pequena, operável e compatível com o momento da empresa. A tecnologia deve apoiar o primeiro aprendizado sem criar uma operação maior do que o produto precisa. ## Ponto de partida recomendado - Laravel como aplicação principal. - Node.js somente com justificativa concreta. - PostgreSQL, com Supabase quando fizer sentido. - VPS. - armazenamento compatível com S3. - e-mail transacional. - IA externa apenas com função de produto clara. - backups, logs e tarefas agendadas conforme necessidade. ## O que entra no `MVP.md` O `MVP.md` recebe arquitetura, dados conceituais, autenticação, papéis, espaços, isolamento, integrações, filas, arquivos, segurança básica, observabilidade e custo mensal por cenário. ## Um exemplo Para a ferramenta de leads, a arquitetura precisa separar agências e clientes, registrar mudanças de status e enviar notificações. Microsserviços e Kubernetes podem esperar até existir uma necessidade real para esse custo. ## Onde termina este trabalho Esta especialista não implementa o software, não compra a VPS e não transforma a stack padrão em requisito mais importante do que o problema do produto. ### Quando algo não funcionar - URL: https://promovaweb.com/docs/mvpfy/solucao-de-problemas - Descrição: ## O estado não aparece depois da instalação ## O estado não aparece depois da instalação Confirme que o comando foi executado na raiz do projeto que receberá o plano: ```bash npx --yes @promovaweb/mvpfy install --project . ``` Depois, confira se existem `MVP.md` e `.mvpfy/state.json`. O comando deve rodar no projeto consumidor. Executá-lo na raiz do repositório `mvpfy` tenta preparar o próprio pacote, não o projeto da entrevista. ## A pergunta repetiu algo que você já informou Confira se a mensagem anterior foi salva no `answers.jsonl` e se as áreas extraídas chegaram ao `state.json`. Uma resposta livre pode precisar de uma leitura adicional. A ausência de um número não torna a mensagem inválida. ## O documento continua como `preliminary` Abra a seção “Hipóteses e pendências”. Esse estado informa que ainda falta um item necessário para descrever o primeiro SaaS. Peça “continuar” ou “o que falta?” para voltar ao próximo ponto relevante. ## Você mudou uma escolha anterior Diga a alteração com clareza, por exemplo: “o público agora são clínicas, não agências”. O MVPFy conserva a mensagem anterior no histórico, registra a nova e revisa as áreas afetadas. ## O ebook não mostra a versão atual No repositório `mvpfy`, execute: ```bash npm run ebook npm run ebook:verify ``` Se uma página não aparecer, confira o caminho correspondente em `docs/user/reading-order.txt`. Essa lista deve conter apenas o guia do usuário. ### Tecnologia e operação para começar - URL: https://promovaweb.com/docs/mvpfy/tecnologia-e-operacao - Descrição: O ponto de partida da Promovaweb para os projetos atendidos pelo MVPFy é Laravel em uma VPS. Essa combinação mantém a aplicação simples, torna o custo mais previsível e encurta o caminho até a primeira validação. O ponto de partida da Promovaweb para os projetos atendidos pelo MVPFy é Laravel em uma VPS. Essa combinação mantém a aplicação simples, torna o custo mais previsível e encurta o caminho até a primeira validação. ## Componentes de referência | Necessidade | Padrão inicial | | --- | --- | | Aplicação | Laravel. | | Serviço complementar | Node.js apenas quando uma necessidade concreta justificar seu uso. | | Banco | PostgreSQL, com Supabase quando fizer sentido para o projeto. | | Servidor | VPS com ambientes e cópias de segurança definidos. | | Arquivos | Object storage compatível com S3. | | Mensagens | Provedor de e-mail transacional. | | IA | Provedor externo apenas quando houver uma função clara no produto. | | Operação | Logs, cópias de segurança, filas ou tarefas agendadas conforme a jornada. | Outra opção pode fazer sentido quando o contexto exigir. Nesse caso, a especialista explica o motivo e mostra o efeito no custo e na operação. ## O que precisa estar claro na primeira versão O plano não precisa desenhar cada classe do sistema. Ele precisa responder às perguntas que afetam a jornada e a operação: - como o espaço é criado e identificado. - se o produto é multitenante ou usa instalação separada por cliente. - como os dados de clientes ficam separados. - quais pessoas acessam cada parte. - quais integrações são indispensáveis. - quais tarefas podem rodar fora da tela. - onde os arquivos ficam guardados. - como funcionam cópias de segurança, logs e suporte. - qual custo mensal aparece em cada cenário. Para a maioria dos primeiros SaaS, o MVPFy prefere uma aplicação compartilhada com separação lógica segura entre espaços. Uma instância dedicada só entra quando contrato, segurança, desempenho ou posicionamento exigirem esse custo. Quando Laravel for escolhido para um SaaS multitenante, o plano avalia o suporte de Teams da solução adotada para representar equipes, membros, convites e papéis. Essa base organiza a associação das pessoas, mas cada consulta ainda precisa respeitar o tenant ativo e sua separação de dados. ## Comece com operação acompanhada Durante a validação, uma pessoa pode liberar espaços, acompanhar o onboarding e conferir assinaturas manualmente. O `MVP.md` registra essa rotina, seu responsável e o sinal que indicará a hora de automatizar o trabalho. ### SetupVibe Desktop: instalação e ferramentas incluídas - URL: https://promovaweb.com/docs/setupvibe/edicoes/desktop - Descrição: Consulte requisitos, instalação, ferramentas, linguagens e configurações aplicadas pela edição Desktop do SetupVibe em macOS, Linux e WSL, até o uso. > Configuração de ambiente de desenvolvimento multiplataforma — v0.41.11 Instala e configura um stack de desenvolvedor completo em um comando. Suporta macOS e as principais distribuições Linux. ## Requisitos do Sistema | | Suportado | | ---------------- | ------------------------------- | | **macOS** | 12 Monterey ou superior | | **Ubuntu** | 24.04+ | | **Debian** | 12+ | | **Zorin OS** | 18+ | | **Linux Mint** | 21+ | | **Arquiteturas** | x86_64 (amd64), ARM64 (aarch64) | > **Não** execute com `sudo` no macOS — o Homebrew se recusa a instalar como root. Execute normalmente e o script solicitará sua senha quando necessário. ## Instalação ```bash curl -sSL desktop.setupvibe.dev | bash ``` Ou localmente: ```bash bash desktop.sh ``` O script exibe um roteiro interativo e solicita confirmação antes de iniciar. Também solicita a configuração da identidade do Git, caso ainda não esteja definida. ## Skill de setup Use `$setupvibe-setup` quando precisar escolher a edição, repetir a instalação ou conferir o ambiente. Depois que o SetupVibe terminar, instale as skills de cada projeto com `npx skills add `. --- ## O Que é Instalado **14 etapas, totalmente automatizadas.** ### Etapa 1 — Sistema Base e Ferramentas de Build **Linux:** instalação via APT — `build-essential`, `git`, `wget`, `unzip`, `curl`, `tmux`, `ffmpeg`, `imagemagick`, bibliotecas SSL/compressão e o repositório APT do Charmbracelet (para o `glow`). **macOS:** depende do Xcode Command Line Tools (verifica e encerra se não estiver presente). As ferramentas base são instaladas via Homebrew na próxima etapa. ### Etapa 2 — Homebrew - **macOS:** instala o Homebrew se ausente, depois instala ferramentas base (`wget`, `curl`, `tmux`, `ffmpeg`, `imagemagick`, `openssl`, `readline`, etc.) - **Linux:** instala o Linuxbrew em `/home/linuxbrew/.linuxbrew`. Adiciona entradas de PATH ao `~/.bashrc`, `~/.profile`, `~/.zshrc`. Executa `brew upgrade` se já presente ### Etapa 3 — Ecossistema PHP 8.5 | Componente | macOS | Linux | | ----------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- | | PHP 8.5 | via Homebrew | via PPA ondrej/php (Ubuntu) ou sury.org (Debian) | | Extensões | redis, xdebug, imagick via PECL | php8.5-{curl,mbstring,xml,zip,bcmath,intl,mysql,pgsql,sqlite3,gd,imagick,redis,mongodb,yaml,xdebug} | | Composer | via Homebrew | binário em `~/.local/bin/composer` | | Laravel installer | `composer global require laravel/installer` | igual | ### Etapa 4 — Ecossistema Ruby | Componente | macOS | Linux | | --------------- | --------------------------- | ---------------------------------------- | | rbenv | via Homebrew | clonado do GitHub em `~/.rbenv` | | ruby-build | via Homebrew | clonado em `~/.rbenv/plugins/ruby-build` | | Ruby | 3.4.10 compilado via rbenv | igual | | Bundler + Rails | `gem install bundler rails` | igual | ### Etapa 5 — Linguagens | Linguagem | macOS | Linux | | --------- | -------------------------- | -------------------------------------------------- | | Python 3 | `python@3.14` via Homebrew | via APT (`python3`, `python3-pip`, `python3-venv`) | | uv | via script de instalação | igual | | qrcode | `pip --user` com CLI `qr` | igual | | Go | via Homebrew | binário 1.26.5 verificado em `~/.local/go` | | Rust | via rustup | igual | ### Etapa 6 — JavaScript | Ferramenta | macOS | Linux | | ---------- | ------------------------ | ------------------------------ | | Node.js 24 | `node@24` via Homebrew | via repositório APT NodeSource | | PNPM | `npm install -g pnpm` | igual | | PM2 | `npm install -g pm2` | igual | | Bun | via script de instalação | igual | No Linux, os pacotes npm globais usam o prefixo gravável `~/.npm-global` do usuário-alvo, mesmo quando o instalador é executado por `sudo`. PNPM, PM2 e Bun são validados após a instalação. ### Etapa 7 — DevOps | Ferramenta | macOS | Linux | | ----------------- | ------------------------------------ | ---------------------------------------------------------------------------- | | Docker | Docker Desktop via Homebrew Cask | docker-ce + docker-compose-plugin + docker-buildx-plugin via Docker APT repo | | Portainer | via Docker Compose em `~/.setupvibe` | mesmo | | Ansible | via Homebrew | via PPA ansible/ansible (Ubuntu) ou ansible-core (Debian) | | GitHub CLI (`gh`) | via Homebrew | via repositório APT do GitHub | ### Etapa 8 — Ferramentas Unix Modernas Instaladas via Homebrew em ambas as plataformas. | Ferramenta | Descrição | | ------------ | ------------------------------------------- | | `bat` | `cat` com realce de sintaxe | | `eza` | Substituto moderno do `ls` | | `zoxide` | `cd` mais inteligente | | `fzf` | Buscador fuzzy (com atalhos de shell) | | `ripgrep` | Substituto rápido do `grep` | | `fd` | Substituto rápido do `find` | | `lazygit` | Interface terminal para git | | `lazydocker` | Interface terminal para Docker | | `neovim` | Vim moderno | | `glow` | Renderizador de Markdown | | `jq` | Processador JSON | | `tldr` | Páginas simplificadas fornecidas por `tlrc` | | `fastfetch` | Ferramenta de informações do sistema | | `duf` | `df` moderno | | `mise` | Gerenciador de versões de runtime | ### Etapa 9 — Rede, Monitoramento e Tailscale **macOS:** `wget`, `nmap`, `mtr`, `htop`, `btop`, `glances`, `speedtest-cli` via Homebrew. `bandwhich`, `gping`, `trippy`, `rustscan` via Cargo. `ctop` via Homebrew. Tailscale via Cask. **Linux:** mesmas ferramentas via APT + Cargo + binário ctop verificado com SHA-256 em `~/.local/bin`. Tailscale via script oficial de instalação. ### Etapa 10 — Servidor SSH *(somente Linux)* - Instala `openssh-server` - Habilita e inicia o serviço systemd `ssh` - Configura `PermitRootLogin prohibit-password` e `PasswordAuthentication yes` - Faz backup do `sshd_config` original antes de modificar ### Etapa 11 — Shell (ZSH e Starship) - Instala ZSH pelo APT no Linux. O ZSH já é padrão no macOS - Instala Oh My Zsh (sem interação) - Clona os plugins `zsh-autosuggestions` e `zsh-syntax-highlighting` - Instala Nerd Fonts: **FiraCode** e **JetBrains Mono**. Usa Homebrew Cask no macOS e baixa a v3.4.0 em `~/.local/share/fonts` no Linux - Instala o prompt Starship e aplica o preset **Gruvbox Rainbow** - Baixa scripts auxiliares de [`bin/`](https://github.com/promovaweb/setupvibe/tree/main/bin) para `~/.setupvibe/bin`. Veja [Executáveis](/docs/setupvibe/referencia/executaveis) - Baixa o `.zshrc` adequado: - macOS → [`conf/zshrc-macos.zsh`](https://github.com/promovaweb/setupvibe/blob/main/conf/zshrc-macos.zsh) - Linux → [`conf/zshrc-linux.zsh`](https://github.com/promovaweb/setupvibe/blob/main/conf/zshrc-linux.zsh) - Cria `~/.zshrc.local` para aliases e configurações pessoais, as atualizações nunca o sobrescrevem. ### Etapa 12 — Tmux e Plugins - Clona o [TPM](https://github.com/tmux-plugins/tpm) em `~/.tmux/plugins/tpm` - Baixa [`conf/tmux-desktop.conf`](https://github.com/promovaweb/setupvibe/blob/main/conf/tmux-desktop.conf) para `~/.tmux.conf` - Encerra qualquer sessão tmux em execução para aplicar a nova configuração Pressione `prefix + I` dentro do tmux para instalar todos os plugins. Consulte [tmux.md](/docs/setupvibe/ferramentas/tmux) para a referência completa de plugins e atalhos de teclado. ### Passo 13 — Ferramentas de IA (CLI) Instala pacotes npm globalmente, além do Herdr e do Antigravity CLI pelos seus manifestos oficiais de releases: | Ferramenta | Instalação | | ------------------ | ---------------------------- | | Agentlytics | `agentlytics` | | Claude Code | `@anthropic-ai/claude-code` | | OpenAI Codex | `@openai/codex` | | GitHub Copilot CLI | `@github/copilot` | | OpenCode CLI | `opencode-ai` | | Kimi Code | `@moonshot-ai/kimi-code` | | Skills CLI | `skills` | | Herdr | Binário do manifesto oficial | | Antigravity CLI | Binário do manifesto oficial | Cada CLI listado é validado após a instalação. O [Herdr](https://github.com/herdrdev/herdr) é instalado em `~/.local/bin` conforme o sistema operacional e a arquitetura detectados. Consulte o [guia do Herdr](/docs/setupvibe/ferramentas/herdr) para entender sessões, atalhos, atualizações e diagnóstico. O Antigravity CLI é instalado em `~/.local/bin` como `agy`: o manifesto versionado e o checksum SHA-512 do próprio feed de releases do Google são resolvidos e verificados diretamente (o bootstrapper oficial Unix não repassa `--skip-aliases`/`--skip-path` ao seu passo interno `agy install`), e então `agy install --skip-aliases --skip-path` é executado explicitamente para não alterar perfis de shell. O **Spec-Kit** é instalado via `uv tool install specify-cli`. Veja o [SPECKIT.md](/docs/setupvibe/ferramentas/spec-kit) para o guia completo de Spec-Driven Development e aliases. ### Passo 14 — Finalização e Limpeza **macOS:** `brew cleanup --prune=all`, `brew autoremove` e remove somente arquivos temporários do SetupVibe. **Linux:** `apt autoremove`, `apt clean`, remove arquivos temporários e limpa logs do journal. Também limpa `~/.cache/pip`, `~/.cache/composer`, `~/.npm/_npx`, `~/.bundle/cache`. **Ambos:** configura inicialização automática do PM2 (launchd no macOS, systemd no Linux), executa `pm2 save`, define `pm2:autodump true` e baixa `ecosystem.config.js` com tentativas HTTPS limitadas para `~/ecosystem.config.js`. Consulte [pm2.md](/docs/setupvibe/ferramentas/pm2) para a referência completa do PM2. --- ## Configuração do Shell Cada plataforma recebe um `.zshrc` dedicado: | Arquivo | Plataforma | Caminhos principais | | ------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------- | | [`zshrc-macos.zsh`](https://github.com/promovaweb/setupvibe/blob/main/conf/zshrc-macos.zsh) | macOS | Homebrew, Cargo, Composer, Go, Bun | | [`zshrc-linux.zsh`](https://github.com/promovaweb/setupvibe/blob/main/conf/zshrc-linux.zsh) | Linux | Linuxbrew, npm-global, Cargo, Go, Bun, rbenv | ### Aliases | Alias | Comando | | ------------- | ------------------------------------------------------------------------------------- | | `reload` | `source ~/.zshrc` | | `zconfig` | `nano ~/.zshrc` | | `zlocal` | `nano ~/.zshrc.local` | | `ssh_copy_id` | `ssh_copy_id --host HOST --user USUARIO [--pass SENHA]` | | `update` | `brew update && brew upgrade` (macOS) / `sudo apt update && sudo apt upgrade` (Linux) | | `brewup` | `brew update && brew upgrade && brew cleanup` | | `cc` | `claude --permission-mode=auto --dangerously-skip-permissions` | | `skl` | `skills list` | | `skf` | `skills find` | | `ska` | `skills add` | | `sku` | `skills update` | | `d` | `docker` | | `dc` | `docker compose` | | `art` | `php artisan` | | `syslog` | `sudo journalctl -f` *(somente Linux)* | | `ports` | `ss -tulnp` *(somente Linux)* | | `meminfo` | `free -h` *(somente Linux)* | | `diskinfo` | `df -h` *(somente Linux)* | | `cpuinfo` | `lscpu` *(somente Linux)* | ### Plugins Oh My Zsh `git rsync cp extract zoxide fzf zsh-autosuggestions zsh-syntax-highlighting brew gh ansible docker docker-compose laravel composer rails ruby python pip node npm bun golang rust` + `macos` (somente macOS) / `nmap tmux` (somente Linux) ## Contribuição Contribuições de todos os tamanhos são bem-vindas! Por favor, leia nosso [Guia de Contribuição](https://github.com/promovaweb/setupvibe/blob/main/CONTRIBUTING.md) para começar. --- ## Licença Licenciado sob a **GNU General Public License v3.0** — veja [LICENSE](https://github.com/promovaweb/setupvibe/tree/main/LICENSE) para detalhes. Mantido por [promovaweb.com](https://promovaweb.com) · --- ### SetupVibe Server: preparação segura de servidores Linux - URL: https://promovaweb.com/docs/setupvibe/edicoes/server - Descrição: Consulte requisitos, instalação, Docker, rede, shell e ferramentas da edição Server do SetupVibe para distribuições Linux compatíveis, na prática. > Configuração de servidor Linux — v0.41.11 Um script de configuração focado em servidores Linux. Sem Homebrew, ecossistemas de linguagens ou ferramentas de desktop, ele instala Docker, Ansible, recursos de rede, shell, tmux e ferramentas de CLI de IA. ## Requisitos do Sistema | | Suportado | | ---------------- | ------------------------------- | | **Ubuntu** | 24.04+ | | **Debian** | 12+ | | **Zorin OS** | 18+ | | **Arquiteturas** | x86_64 (amd64), ARM64 (aarch64) | > Somente Linux. O script encerra imediatamente se executado no macOS. ## Instalação ```bash curl -sSL server.setupvibe.dev | bash ``` Ou localmente: ```bash bash server.sh ``` Para inicializar o Docker Swarm automaticamente após o setup, passe `--manager`: ```bash curl -sSL server.setupvibe.dev | bash -s -- --manager ``` ```bash bash server.sh --manager ``` Para uma instalação não interativa, adicione `--yes`. Para escolher explicitamente o endereço ou a interface do Swarm, use `--advertise-addr ENDERECO`. Essa opção implica `--manager`. O script valida o sistema operacional, a versão, a arquitetura, o usuário de destino e os argumentos antes de alterar o sistema. Em seguida, exibe um roteiro interativo, solicita confirmação, aguarda por até cinco minutos a liberação dos locks do APT e repete comandos APT que falharem. As etapas param no primeiro erro, o resumo identifica as etapas não executadas e o script retorna um status diferente de zero. Se `--manager` não for informado, instalações interativas perguntam ao final se o Docker Swarm deve ser configurado. ## Skill de setup Use `$setupvibe-setup` para escolher a edição Server, repetir a instalação ou conferir o ambiente. Depois do SetupVibe, instale as skills de cada projeto com `npx skills add `. --- ## O Que é Instalado **9 etapas totalmente automatizadas (Etapas 0–8), mais uma Etapa 9 opcional para configuração do Docker Swarm Manager.** ### Etapa 0 — Pré-requisitos e Verificação de Arquitetura Informa o sistema operacional, a base de repositórios da distribuição, a arquitetura da CPU, o usuário de destino e o diretório inicial validados antes do início da instalação. ### Etapa 1 — Ferramentas do Sistema Base Instala via APT: - Utilitários principais: `curl`, `file`, `figlet`, `fontconfig`, `fzf`, `git`, `gnupg`, `iproute2`, `jq`, `nano`, `procps`, `psmisc`, `sshpass`, `tmux`, `unzip`, `wget` - Serviços do sistema: `cron`, `logrotate`, `rsyslog` - **zoxide** pelo instalador oficial - Habilita o `cron` sem criar tarefas e remove somente as tarefas de demonstração legadas adicionadas pelo SetupVibe v0.41.4-v0.41.6 ### Etapa 2 — Docker, Ansible e GitHub CLI **Docker** — instalado a partir do repositório APT oficial do Docker: - `docker-ce`, `docker-ce-cli`, `containerd.io`, `docker-compose-plugin`, `docker-buildx-plugin` - O usuário é adicionado ao grupo `docker` **Ansible:** - Ubuntu → via PPA `ansible/ansible` - Debian → `ansible-core` via APT **GitHub CLI (`gh`)** — via repositório APT oficial do GitHub **Portainer CE** — usa o canal de imagem `lts` e expõe HTTPS na porta `9443`. A porta HTTP legada `9000` e a porta opcional `8000` para Edge Agent não são abertas ### Etapa 3 — Rede, Monitoramento e Tailscale Pacotes APT: `rsync`, `net-tools`, `dnsutils`, `mtr-tiny`, `nmap`, `tcpdump`, `iftop`, `nload`, `iotop`, `sysstat`, `whois`, `iputils-ping`, `speedtest-cli`, `glances`, `htop`, `btop` - **ctop** — binário baixado em `~/.local/bin/ctop` (v0.7.7, detecta arquitetura, SHA-256 verificado) - **Tailscale** — via script oficial de instalação (`https://tailscale.com/install.sh`) ### Etapa 4 — Servidor SSH - Instala `openssh-server` e `openssh-client` - Habilita e inicia o serviço systemd `ssh` - Valida a configuração efetiva com `sshd -t` - Preserva a política de autenticação existente. Não habilita login de root nem autenticação por senha ### Etapa 5 — Shell (ZSH e Starship) - Instala ZSH via APT - Instala Oh My Zsh (sem interação) - Clona `zsh-autosuggestions` e `zsh-syntax-highlighting` - Instala o prompt Starship em `~/.local/bin` e aplica o preset **Gruvbox Rainbow** - Baixa scripts auxiliares de [`bin/`](https://github.com/promovaweb/setupvibe/tree/main/bin) para `~/.setupvibe/bin`. Veja [Executáveis](/docs/setupvibe/referencia/executaveis) - Baixa [`conf/zshrc-server.zsh`](https://github.com/promovaweb/setupvibe/blob/main/conf/zshrc-server.zsh) para `~/.zshrc` - Cria `~/.zshrc.local` para aliases e configurações pessoais, as atualizações nunca o sobrescrevem. - Preserva uma vez os arquivos `.zshrc`, `.bashrc` e `.tmux.conf` existentes com o sufixo `.pre-setupvibe` antes de substituir ou acrescentar conteúdo - Define o ZSH como shell padrão via `chsh` #### Aliases do Shell | Alias | Comando | | -------------- | -------------------------------------------------------------- | | `reload` | `source ~/.zshrc` | | `zconfig` | `nano ~/.zshrc` | | `zlocal` | `nano ~/.zshrc.local` | | `ssh_copy_id` | `ssh_copy_id --host HOST --user USUARIO [--pass SENHA]` | | `update` | `sudo apt update && sudo apt upgrade` | | `cc` | `claude --permission-mode=auto --dangerously-skip-permissions` | | `skl` | `skills list` | | `skf` | `skills find` | | `ska` | `skills add` | | `sku` | `skills update` | | `skun` | `skills remove` | | `d` | `docker` | | `dc` | `docker compose` | | `syslog` | `sudo journalctl -f` | | `ports` | `ss -tulnp` | | `meminfo` | `free -h` | | `diskinfo` | `df -h` | | `cpuinfo` | `lscpu` | | `wholistening` | `ss -tulnp` | #### Plugins Oh My Zsh `git rsync nmap cp extract zoxide fzf zsh-autosuggestions zsh-syntax-highlighting tmux gh ansible docker docker-compose` ### Etapa 6 — Tmux e Plugins - Clona o [TPM](https://github.com/tmux-plugins/tpm) em `~/.tmux/plugins/tpm` - Baixa [`conf/tmux-server.conf`](https://github.com/promovaweb/setupvibe/blob/main/conf/tmux-server.conf) para `~/.tmux.conf` - Se executado como root com um `REAL_HOME` não-root, também instala em `/root/.tmux.conf` - Preserva as sessões tmux em execução. A nova configuração é aplicada às novas sessões Pressione `prefix + I` dentro do tmux para instalar todos os plugins. Consulte o [Guia do Tmux](/docs/setupvibe/ferramentas/tmux) para a referência completa de plugins e atalhos. ### Passo 7 — Ferramentas de IA CLI Instala o **Node.js 24** pelo repositório APT do NodeSource, instala os pacotes npm globalmente e obtém o Herdr pelo manifesto oficial de releases: | Ferramenta | Instalação | | ------------------ | ---------------------------- | | Claude Code | `@anthropic-ai/claude-code` | | OpenAI Codex | `@openai/codex` | | GitHub Copilot CLI | `@github/copilot` | | OpenCode CLI | `opencode-ai` | | Skills CLI | `skills` | | Herdr | Binário do manifesto oficial | O [Vercel Labs Skills CLI](https://github.com/vercel-labs/skills), o [Herdr](https://github.com/herdrdev/herdr) e cada comando de CLI de IA são validados após a instalação. O Herdr é instalado em `~/.local/bin` conforme a arquitetura detectada. Consulte o [guia do Herdr](/docs/setupvibe/ferramentas/herdr) para entender sessões, atalhos, atualizações e diagnóstico. O pacote descontinuado `@githubnext/github-copilot-cli` é removido. Os pacotes globais do npm são instalados em `~/.npm-global` sempre que o usuário de destino não for root, inclusive quando o instalador for executado por `sudo`. ### Passo 8 — Finalização e Limpeza - Executa `autoclean` e `clean` do APT - Remove as listas de pacotes baixadas pelo APT - Preserva pacotes instalados, logs do sistema e caches do usuário ### Passo 9 — Docker Swarm Manager (opcional) Ativado passando `--manager` ou respondendo **sim** ao prompt interativo exibido ao final do setup. 1. **Detecta o IPv4 roteável principal** pela tabela de rotas local, sem consultar serviços externos de IP. Use `--advertise-addr ENDERECO` para informar um endereço ou uma interface específica. 2. **Inicializa o Docker Swarm** com `docker swarm init --advertise-addr `. Idempotente — ignora a inicialização se a máquina já for manager e falha claramente se ela já for worker. 3. **Cria a rede overlay** `network_swarm_public` com `--driver overlay --attachable`. Idempotente — ignora se a rede já existir. 4. **Exibe os tokens de ingresso** para as roles worker e manager, permitindo adicionar novos nós imediatamente. ## Contribuição Contribuições de todos os tamanhos são bem-vindas! Por favor, leia nosso [Guia de Contribuição](https://github.com/promovaweb/setupvibe/blob/main/CONTRIBUTING.md) para começar. --- ## Licença Licenciado sob a **GNU General Public License v3.0** — veja [LICENSE](https://github.com/promovaweb/setupvibe/tree/main/LICENSE) para detalhes. Mantido por [promovaweb.com](https://promovaweb.com) · --- ### SetupVibe Windows: instalação nativa e ferramentas - URL: https://promovaweb.com/docs/setupvibe/edicoes/windows - Descrição: Consulte requisitos, instalação, recuperação e ferramentas da edição Windows do SetupVibe executada pelo PowerShell com WinGet e Chocolatey, passo a passo. > Configuração de utilitários nativos do Windows — v0.41.11 A Edição Windows (Beta) configura utilitários nativos do Windows, Python, Node.js e CLIs de IA selecionadas, usando o WinGet como fonte principal e o Chocolatey para pacotes indisponíveis no WinGet. ## Requisitos - Windows 11 versão 22H2 (build 22621) ou posterior - Uma edição desktop x64 (AMD64) do Windows. Não há suporte para Windows de 32 bits, Windows em ARM, Windows 10 nem Windows Server - Windows PowerShell 5.1 ou posterior - Um usuário que pertença ao grupo Administradores local. O prompt do UAC deve usar o mesmo usuário conectado - Acesso à internet ## O Que É Instalado - Cliente e Servidor Microsoft Win32-OpenSSH oficiais mais recentes pelo MSI Win64 x64 assinado - WinGet pelo fluxo oficial de reparo `Microsoft.WinGet.Client`, quando ausente - Chocolatey pelo script oficial de bootstrap, quando ausente - Python 3.14 diretamente pelo instalador oficial do `python.org` e Node.js 24 LTS pelo canal oficial `latest-v24.x` do `nodejs.org`, com `python`, `pip`, `node`, `npm` e `npx` no `PATH` da máquina para Claude e Codex - Claude Code pelo instalador nativo recomendado da Anthropic, com seu pacote npm oficial como recuperação, Codex CLI pelo instalador autônomo oficial da OpenAI para Windows e Google Antigravity CLI como `agy` pelo seu instalador nativo oficial - [Vercel Labs Skills CLI](https://github.com/vercel-labs/skills) pelo pacote npm oficial, com o lançador `skills.cmd` compatível com política de execução restrita - Sistema base do WSL sem uma distribuição Linux, com WSL 2 como padrão - Rede espelhada do WSL com acesso por VPN/LAN, tunelamento de DNS, integração com o proxy do Windows, entrada liberada no firewall Hyper-V, recuperação automática de memória e discos virtuais esparsos - Git, 7-Zip, Wget, FFmpeg, ImageMagick e GitHub CLI (`gh`) - bat, eza, zoxide, fzf, ripgrep, fd, lazygit, Neovim, Glow, tldr, Fastfetch, duf e jq - Nmap, Speedtest CLI, Tailscale, gping, btop4win e trippy - PowerShell 7, Windows Terminal, FiraCode Nerd Font e JetBrains Mono Nerd Font O instalador é idempotente: pacotes WinGet instalados são detectados e ignorados, o Chocolatey verifica os pacotes sob sua gestão e os instaladores oficiais do Python e Node.js são reaplicados com segurança. Falhas são registradas por pacote para que as demais instalações continuem. Um log completo é salvo em `C:\ProgramData\SetupVibe\Logs`. Os perfis do Windows PowerShell e PowerShell 7 permanecem originais. Starship e ZSH não são instalados, a política de execução não é alterada e o zoxide permanece somente como utilitário CLI sem inicialização automática. Python e Node.js são os únicos runtimes de programação instalados por este script. Claude Code, Codex CLI e Antigravity CLI são suas únicas CLIs de IA. Ele não instala uma distribuição Linux, frameworks, gerenciadores de runtime, outras CLIs de IA nem outros ecossistemas de linguagens. Depois de instalar uma distribuição separadamente, use o `desktop.sh` dentro dela para configurar um ambiente completo de desenvolvimento. Se `%USERPROFILE%\.wslconfig` já existir, o SetupVibe cria um backup antes de aplicar os padrões de desenvolvimento. O backup e os estados anteriores dos recursos e do firewall do WSL são restaurados por `-Uninstall`. O Docker Desktop foi excluído intencionalmente. O SetupVibe prepara o WSL 2, mas não instala o Docker nem uma distribuição Linux. **Aviso sobre a rede do WSL:** o SetupVibe libera o tráfego de entrada para o WSL em todas as portas pelo firewall Hyper-V, permitindo que serviços futuros sejam acessados pela rede local e por VPNs compatíveis. Restrinja essa política com regras específicas do firewall Hyper-V em redes não confiáveis. Um serviço Linux futuro precisa escutar em `0.0.0.0` ou na interface de rede apropriada para aceitar conexões remotas. ## Instalação Com Um Comando Este é o equivalente no Windows ao comando `curl -sSL desktop.setupvibe.dev | bash`. A URL canônica do instalador Windows é `https://windows.setupvibe.dev`. 1. Abra o menu Iniciar. 2. Procure por **Windows PowerShell** e abra-o. Executar como administrador é opcional, pois o script solicita elevação pelo UAC automaticamente. 3. Revise o [`desktop.ps1`](https://github.com/promovaweb/setupvibe/blob/main/desktop.ps1) do repositório antes de executar código remoto. 4. Cole o comando abaixo e pressione `Enter`: ```powershell [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; irm https://windows.setupvibe.dev | iex ``` 5. Aceite a solicitação do UAC do Windows. 6. Mantenha as janelas do PowerShell abertas até a exibição do resumo. 7. Reinicie o Windows quando solicitado para aplicar alterações pendentes de componentes ou pacotes. O comando baixa o `desktop.ps1` do repositório oficial do SetupVibe e o executa na sessão atual do PowerShell. Quando a elevação é necessária, o instalador baixa uma cópia temporária e continua em uma sessão de administrador. ## Skill de setup Use `$setupvibe-setup` para escolher a edição Windows, repetir a instalação ou conferir o ambiente. Depois do SetupVibe, instale as skills de cada projeto com `npx skills add `. ## Instalação Local Para baixar o script antes de executá-lo: ```powershell $scriptPath = Join-Path $HOME 'Downloads\desktop.ps1' Invoke-WebRequest -UseBasicParsing -Uri https://windows.setupvibe.dev -OutFile $scriptPath powershell.exe -NoProfile -ExecutionPolicy Bypass -File $scriptPath ``` A partir de um clone existente deste repositório: ```powershell Set-Location C:\caminho\para\setupvibe powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\desktop.ps1 ``` ## O Que Esperar Durante a execução, o instalador: 1. Valida o Windows 11 22H2 ou posterior e a arquitetura x64, reiniciando o próprio script pelo Windows PowerShell x64 nativo se ele tiver sido iniciado em um processo de 32 bits, e recusa elevação UAC com credenciais de outro perfil de usuário. 2. Solicita privilégios de administrador pelo UAC. 3. Lista processos de instalação concorrentes e pergunta se deve encerrá-los. Se aceito, tenta normalmente, força os que permanecerem e executa `sfc.exe /scannow`. Se recusado, aguarda ENTER e encerra. 4. Recusa reinicializações pendentes, inicia os serviços necessários, executa `sfc.exe /scannow` caso ainda não tenha sido executado, verifica a política WSUS e valida o armazenamento de componentes do Windows. 5. Resolve o MSI x64 oficial mais recente do Microsoft Win32-OpenSSH sem usar a API de releases do GitHub, valida sua assinatura, instala e repara explicitamente Cliente e Servidor, configura o `PATH` da máquina, valida o código de saída de `ssh.exe -V`, inicia `sshd` automaticamente e libera a entrada TCP/22 salvando o estado anterior da regra de firewall. 6. Copia os scripts auxiliares Windows do SetupVibe para `%USERPROFILE%\.setupvibe\bin` e adiciona esse diretório ao `PATH` do usuário, normalizando e eliminando entradas duplicadas e notificando o Windows sobre a alteração de ambiente. 7. Instala o sistema base do WSL sem uma distribuição Linux e torna o WSL 2 o padrão. 8. Aplica ao WSL rede espelhada, acesso por VPN/LAN, DNS, proxy, firewall, recuperação de memória e discos VHD esparsos. 9. Instala WinGet e Chocolatey quando necessário. 10. Baixa Python 3.14 do `python.org` e resolve o Node.js 24 LTS diretamente pelo canal oficial `latest-v24.x` do `nodejs.org`, sem a API do índice de releases, WinGet ou Chocolatey. Usa o `curl.exe` do Windows com redirecionamentos somente HTTPS e novas tentativas, valida o Authenticode e o SHA-256 oficial do Node.js, repara recursos ausentes do Python ou do MSI do Node.js, remove os shims redundantes `npm.ps1` e `npx.ps1` que falham sob uma política de execução restrita, coloca os diretórios x64 nativos dos runtimes no início do `PATH` da máquina e valida `python`, `pip`, `node`, `npm` e `npx` exatamente como o usuário os executa. 11. Instala cada utilitário restante do Windows de forma independente, executa cada CLI previsível do WinGet e Chocolatey pelo `PATH` atualizado, valida `gh.exe` e o alias `wt.exe` do Windows Terminal e continua após falhas isoladas de pacote ou comando. 12. Instala e valida Skills CLI, Claude Code, Codex CLI e Antigravity CLI por suas fontes oficiais, preservando todos os arquivos de perfil PowerShell do usuário. Skills usa seu pacote npm oficial e um lançador CMD compatível com política de execução restrita. O Claude usa o instalador nativo recomendado independentemente do npm e recorre ao pacote npm oficial da Anthropic somente quando necessário. O Codex usa o instalador autônomo oficial da OpenAI em vez do npm. 13. Remove somente blocos legados reconhecidos do SetupVibe para Starship/zoxide sem recodificar conteúdo não relacionado, preservando os bytes originais dos perfis PowerShell, a configuração Starship do usuário e a política de execução. 14. Exibe um resumo final e o local do log completo. O processo pode demorar porque os gerenciadores de pacotes baixam e instalam cada utilitário separadamente. ## Depois da Instalação 1. Reinicie o Windows quando solicitado para concluir alterações pendentes de componentes ou pacotes. 2. Abra o Windows Terminal ou PowerShell 7 para carregar o novo `PATH`. 3. Conclua as autenticações iniciais exigidas pelo GitHub CLI, Tailscale, Claude Code, Codex CLI ou Antigravity CLI. Os scripts auxiliares do SetupVibe ficam em `%USERPROFILE%\.setupvibe\bin`. O núcleo instalado `ssh_copy_id_core.ps1` e seu lançador mínimo `ssh_copy_id.cmd` podem ser iniciados sem ambiguidade como `ssh_copy_id`. O Codex usa seu `codex.exe` nativo. Nenhum script PowerShell ou lançador do SetupVibe é necessário. Ambos os comandos funcionam em uma nova sessão do PowerShell, Windows Terminal ou Prompt de Comando. Verifique os principais componentes em um novo terminal: ```powershell winget --version choco --version git --version gh --version Get-Command wt rg --version fzf --version pwsh --version python --version pip --version node --version npm --version npx --version skills --version claude --version codex --version Get-Command agy Get-Command ssh_copy_id wsl --status wsl --list --verbose Get-Content $HOME\.wslconfig Get-NetFirewallHyperVVMSetting -PolicyStore ActiveStore -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' ``` `wsl --list --verbose` deve informar que nenhuma distribuição está instalada, a menos que a máquina já tivesse uma. A saída do firewall deve mostrar `DefaultInboundAction` como `Allow`. ## Nova Execução e Logs O instalador foi desenvolvido para ser executado novamente. Os scripts auxiliares do SetupVibe são atualizados, pacotes WinGet já presentes são ignorados e o Chocolatey garante que seus utilitários gerenciados permaneçam instalados. Os logs completos da transcrição e os logs dedicados do DISM são armazenados em: ```text C:\ProgramData\SetupVibe\Logs ``` Se um pacote falhar, revise o resumo final e o log, resolva o problema informado e execute o mesmo comando novamente. ## Segurança Do Windows Servicing Antes de instalar ou remover componentes, o SetupVibe verifica processos ativos do `DISM`, `dismhost`, `TiWorker`, Windows Installer, instaladores do Windows Update, WinGet, Chocolatey e outros processos de instalação conhecidos. Ele lista nomes e PIDs e solicita permissão antes de encerrá-los. Quando aceito, primeiro usa `Stop-Process`, força os processos que permanecerem e depois executa `sfc.exe /scannow`. Quando recusado, aguarda ENTER e encerra sem iniciar outra operação de manutenção. Em seguida, recusa reinicializações pendentes do Component Based Servicing ou Windows Update, inicia os serviços necessários e executa `DISM /Online /Cleanup-Image /CheckHealth`. Os detalhes do Verificador de Arquivos do Sistema são registrados em `C:\Windows\Logs\CBS\CBS.log`. Se um processo permanecer ativo depois das tentativas de encerramento normal e forçado, o SetupVibe conclui a verificação do SFC, aguarda ENTER e encerra recomendando reiniciar o PC. O OpenSSH não usa os Recursos sob Demanda do Windows nem a API de releases do GitHub. O SetupVibe resolve a página oficial `releases/latest` e seus assets expandidos, aceita somente o MSI x64 `OpenSSH-Win64-*.msi`, valida sua assinatura Authenticode e instala e repara explicitamente os recursos Cliente e Servidor em uma única transação MSI com `ADDLOCAL=Client,Server`, `REINSTALL=ALL` e `REINSTALLMODE=amus`. Ele resolve o diretório de instalação pelo diretório Program Files x64 nativo, pelos metadados do MSI e pelo serviço `sshd`, coloca esse diretório no início do `PATH` da máquina, configura `sshd` para inicialização automática, inicia o serviço, habilita a regra de firewall `OpenSSH-Server-In-TCP` para entrada TCP/22, salva o estado anterior da regra para a desinstalação e registra `openssh-msi-*.log` em `C:\ProgramData\SetupVibe\Logs`. ## Opções Reinicie o Windows automaticamente depois de uma instalação totalmente bem-sucedida quando o sistema informar que uma reinicialização é necessária: ```powershell [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; & ([scriptblock]::Create((irm https://windows.setupvibe.dev))) -Restart ``` Sem `-Restart`, o instalador nunca reinicia o Windows automaticamente. ### Desinstalação Remova todos os utilitários e configurações gerenciados pela Edição Windows a partir de um clone local: ```powershell powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\desktop.ps1 -Uninstall ``` Ou execute o desinstalador pela URL canônica do SetupVibe para Windows: ```powershell [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; & ([scriptblock]::Create((irm https://windows.setupvibe.dev))) -Uninstall ``` O modo de desinstalação remove o Cliente e o Servidor OpenSSH, Python e Node.js por seus desinstaladores oficiais, Skills CLI, Claude Code, Codex CLI, Antigravity CLI, os arquivos gerenciados pelo SetupVibe em `%USERPROFILE%\.setupvibe\bin` e as entradas correspondentes do `PATH` do usuário, restaura os estados anteriores dos recursos opcionais do WSL, do firewall do WSL e da regra de firewall do OpenSSH, remove a configuração do WSL aplicada pelo SetupVibe, remove todos os utilitários WinGet e Chocolatey gerenciados pelo SetupVibe e remove as entradas de pacotes e runtimes adicionadas pelo SetupVibe ao `PATH` da máquina e blocos legados reconhecidos do SetupVibe para Starship/zoxide. As skills de agentes instaladas são preservadas. Ele também remove ferramentas de frameworks, caminhos ausentes de gerenciadores de runtime e pacotes npm legados instalados por versões Beta anteriores do Windows. Diretórios ativos gerenciados pelo usuário no `PATH`, configuração Starship, distribuições Linux, configurações e credenciais de usuário das CLIs de IA, WinGet, Chocolatey, logs e arquivos não relacionados dentro de `%USERPROFILE%\.setupvibe` são preservados. **Aviso sobre a desinstalação:** a versão Beta atual não registra se o Cliente e o Servidor OpenSSH ou um pacote gerenciado já existiam antes do SetupVibe. Portanto, `-Uninstall` remove o produto MSI do OpenSSH e todos os pacotes de suas listas gerenciadas, inclusive componentes que possam ter sido instalados separadamente antes do SetupVibe. Combine `-Uninstall` com `-Restart` para reiniciar automaticamente quando o Windows informar que uma reinicialização é necessária. ## Escopo e Limitações - Windows 10, Windows Server, builds do Windows 11 anteriores a 22621, Windows de 32 bits e Windows em ARM são recusados. Somente x64 é compatível. - O WSL é instalado e configurado para WSL 2, rede espelhada por VPN/LAN e otimizações comuns de desenvolvimento, mas nenhuma distribuição Linux é instalada. - Python 3.14 e Node.js 24 LTS são instalados para automações locais. Claude Code, Codex CLI e Antigravity CLI são as únicas CLIs de IA instaladas. Outras linguagens de programação, frameworks, gerenciadores de runtime e CLIs de IA são excluídos. - Starship e ZSH não são instalados no Windows, os perfis do PowerShell não são personalizados e a política de execução persistente não é alterada. - O Docker Desktop e um mecanismo Docker local não são instalados. ### Cronboard no SetupVibe: tarefas cron pelo terminal - URL: https://promovaweb.com/docs/setupvibe/ferramentas/cronboard - Descrição: Consulte como abrir e operar o Cronboard instalado pelo SetupVibe para visualizar, editar, pausar e validar tarefas cron, com exemplos e diagnóstico. > Dashboard de monitoramento Cron TUI — v0.41.11 O SetupVibe instala o [Cronboard](https://github.com/antoniorodr/cronboard) para fornecer uma interface visual (TUI) para gerenciamento de tarefas cron. --- ## O que é o Cronboard? O Cronboard é um dashboard baseado em terminal para gerenciar jobs do cron de forma local e remota. Ele permite visualizar, criar, editar, pausar e excluir tarefas de forma intuitiva, sem a necessidade de editar arquivos de texto manualmente. **Recursos principais:** - **Interface Visual (TUI):** Gerenciamento amigável via teclado. - **Validação:** Feedback em tempo real sobre a validade da expressão cron. - **Linguagem Natural:** Converte expressões cron em descrições legíveis (ex: "Todos os dias às 00:00"). - **Suporte Remoto:** Conexão via SSH para gerenciar crontabs em outros servidores. - **Busca:** Filtro rápido por palavras-chave. --- ## Uso Básico ```bash # Abrir o dashboard do Cronboard cronboard # Ou use o atalho do SetupVibe cronb ``` ### Comandos de Teclado no Dashboard | Tecla | Ação | | ---------------------- | ----------------------------------------------------- | | `j` / `k` ou `↑` / `↓` | Navegar entre as tarefas | | `n` | Criar uma nova tarefa | | `e` | Editar a tarefa selecionada | | `p` | Pausar/Retomar tarefa (comenta/descomenta no crontab) | | `d` | Excluir tarefa | | `s` | Salvar alterações | | `f` | Filtrar tarefas | | `q` | Sair do Cronboard | --- ## Gerenciamento Remoto O Cronboard permite gerenciar servidores via SSH. Você pode configurar conexões no arquivo de configuração do Cronboard. Para mais detalhes sobre configurações avançadas, visite a [documentação oficial](https://antoniorodr.github.io/cronboard/configuration/). --- ### Herdr no SetupVibe: instalação, sessões e atalhos práticos - URL: https://promovaweb.com/docs/setupvibe/ferramentas/herdr - Descrição: Entenda como o SetupVibe instala e atualiza o Herdr e consulte sessões, comandos, atalhos e a relação prática entre agentes e tmux no trabalho diário. > Multiplexador de agentes instalado pelas edições Desktop e Server. O [Herdr](https://github.com/herdrdev/herdr) organiza agentes de código em workspaces persistentes no terminal. Cada workspace pode reunir abas e painéis, enquanto a barra lateral mostra se um agente detectado está trabalhando, aguardando uma resposta, concluído ou ocioso. ## Disponibilidade | Edição | Sistemas | Estado | | -------------- | ------------------------------- | ------------- | | Desktop | macOS, Linux e WSL | Instalado | | Server | Distribuições Linux compatíveis | Instalado | | Windows (Beta) | Windows nativo | Não instalado | A edição Windows do SetupVibe não instala o Herdr porque o suporte nativo do projeto para essa plataforma ainda está em preview. No Windows, a edição Desktop pode ser executada dentro do WSL para usar o binário Linux estável. ## Como o SetupVibe Instala o Herdr Os instaladores Desktop e Server leem o manifesto oficial em `https://herdr.dev/latest.json`, selecionam o binário do sistema operacional e da arquitetura detectados e aceitam somente assets publicados no caminho oficial de releases do projeto original no GitHub. O binário selecionado passa pelas verificações de download do SetupVibe e é instalado em: ```text ~/.local/bin/herdr ``` Depois da instalação, o SetupVibe executa `herdr --version` com o `PATH` do usuário de destino. O passo falha quando o download não termina, a arquitetura não é compatível, o manifesto aponta para uma origem inesperada ou o comando instalado não pode ser executado. Uma nova execução do SetupVibe consulta o manifesto atual e substitui o binário gerenciado pela release estável disponível para a máquina. ## Primeira Sessão Abra o diretório de um projeto e inicie o Herdr: ```bash cd ~/projetos/meu-projeto herdr ``` O Herdr cria ou anexa o cliente à sessão padrão executada em background. Dentro de um painel, abra o agente de código com o comando habitual: ```bash codex ``` Também é possível executar `claude`, `copilot` ou outro agente compatível com o Herdr. A autenticação, as permissões e as instruções do projeto continuam sob responsabilidade de cada CLI e repositório. ## Comandos Essenciais | Comando | Função | | -------------------- | ---------------------------------------------------------------- | | `herdr` | Cria ou anexa o cliente à sessão padrão. | | `herdr --version` | Mostra a versão instalada. | | `herdr --help` | Lista os comandos e as opções disponíveis. | | `herdr config check` | Valida a configuração do Herdr. | | `herdr update` | Atualiza uma instalação gerenciada pelo instalador do Herdr. | | `herdr server stop` | Encerra o servidor padrão e os processos executados nos painéis. | Executar novamente o SetupVibe é a forma recomendada de atualizar o binário gerenciado pelo SetupVibe. Use `herdr update` somente quando quiser que o próprio Herdr assuma suas atualizações. ## Atalhos Iniciais O Herdr usa `Ctrl+B` como prefixo padrão. Pressione o prefixo, solte as teclas e então pressione a tecla da ação. | Ação | Atalho | | ------------------------ | ---------------------------- | | Dividir à direita | `prefix` e depois `v` | | Dividir abaixo | `prefix` e depois `-` | | Criar aba | `prefix` e depois `c` | | Próxima aba ou anterior | `prefix` e depois `n` ou `p` | | Navegar entre workspaces | `prefix` e depois `w` | | Desanexar o cliente | `prefix` e depois `q` | | Mostrar atalhos ativos | `prefix` e depois `?` | Desanexar o cliente ou fechar o terminal mantém o servidor do Herdr e os processos dos painéis em execução. Rode `herdr` novamente para retornar à mesma sessão. ## Herdr e Tmux O SetupVibe continua instalando o tmux nas edições Desktop e Server. O Herdr prioriza workspaces e a visualização do estado dos agentes de código, enquanto o tmux continua adequado para sessões gerais de shell, rotinas remotas já estabelecidas e a configuração de plugins fornecida pelo SetupVibe. Use apenas um multiplexador como sessão externa em cada rotina. Executar o Herdr dentro do tmux, ou o tmux dentro do Herdr, adiciona outra camada de prefixos e captura de input, o que dificulta a leitura de conflitos de teclado e mouse. ## Atualizações e Sessões em Execução Uma atualização que muda o protocolo entre o cliente e o servidor do Herdr pode exigir a reinicialização da sessão. Leia a mensagem de atualização antes de executar: ```bash herdr server stop ``` Esse comando também encerra os processos executados nos painéis. Quando você deseja apenas sair da interface e manter os agentes ativos, use `prefix` e depois `q`. ## Solução de Problemas | Sintoma | Verificação | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | `herdr: command not found` | Abra outro shell e confirme se `~/.local/bin` aparece no `PATH`. | | O SetupVibe não encontra um asset | Confirme se a máquina usa x86_64 ou ARM64 e consegue acessar `herdr.dev` e o GitHub. | | Um agente de código não é detectado | Confirme se o agente roda diretamente dentro de um painel do Herdr e consulte a lista de agentes compatíveis. | | Os atalhos chegam ao programa errado | Procure outro multiplexador aninhado ou atalhos do terminal configurados com o mesmo prefixo. | | O cliente informa incompatibilidade de protocolo | Termine o trabalho atual, encerre o servidor afetado e inicie o Herdr novamente com o binário atualizado. | ## Leitura Complementar - [Repositório do Herdr](https://github.com/herdrdev/herdr) - [Documentação do Herdr](https://herdr.dev/docs/) - [Índice da documentação do SetupVibe](https://github.com/promovaweb/setupvibe/blob/main/docs/README.md) ### PM2 no SetupVibe: processos, logs e inicialização segura - URL: https://promovaweb.com/docs/setupvibe/ferramentas/pm2 - Descrição: Consulte processos, logs, monitoramento, ecosystem files e inicialização automática do PM2 configurado pelo SetupVibe, com persistência no servidor. > Guia de gerenciamento de processos — v0.41.11 O SetupVibe instala o [PM2](https://pm2.keymetrics.io/) globalmente e o configura para inicialização automática na edição Desktop. - **macOS:** inicialização automática via launchd. Baixa e inicia `ecosystem.config.js` do repositório para `~/ecosystem.config.js` - **Linux:** inicialização automática via systemd. Baixa e inicia `ecosystem.config.js` do repositório para `~/ecosystem.config.js` --- ## O que é o PM2? O PM2 é um **gerenciador de processos para Node.js em produção** — mantém seus aplicativos funcionando, reinicia-os em caso de falha, gerencia logs e integra-se com sistemas de init do sistema operacional. **Conceitos principais:** | Conceito | Descrição | | ------------------ | ------------------------------------------------------------------------- | | **App** | Um processo gerenciado pelo PM2 (Node.js, Python, Go ou qualquer binário) | | **Ecosystem file** | `ecosystem.config.js` — configuração declarativa para um ou mais apps | | **Cluster mode** | Cria múltiplas instâncias entre os núcleos da CPU (somente Node.js) | | **Fork mode** | Processo único, funciona com qualquer runtime (padrão) | --- ## Primeiros Passos ```bash # Iniciar um app diretamente pm2 start app.js # Iniciar com nome pm2 start app.js --name meuapp # Iniciar usando ecosystem file pm2 start ecosystem.config.js # Iniciar um app específico do ecosystem file pm2 start ecosystem.config.js --only meuapp # Iniciar com ambiente específico pm2 start ecosystem.config.js --env production # Listar todos os processos gerenciados pm2 list # Mostrar informações detalhadas de um app pm2 show meuapp # Monitorar todos os apps em tempo real pm2 monit ``` --- ## Comandos Comuns ### Controle de Processos ```bash pm2 stop meuapp # Parar (mantém na lista) pm2 restart meuapp # Reiniciar pm2 reload meuapp # Reload sem downtime (cluster mode) pm2 delete meuapp # Parar e remover da lista pm2 stop all # Parar todos os apps pm2 restart all # Reiniciar todos os apps pm2 delete all # Remover todos os apps ``` ### Logs ```bash pm2 logs # Transmitir todos os logs pm2 logs meuapp # Transmitir logs de um app pm2 logs --lines 200 # Mostrar as últimas 200 linhas pm2 flush # Limpar todos os arquivos de log pm2 reloadLogs # Reabrir arquivos de log (útil após rotação) ``` ### Persistência ```bash pm2 save # Salvar lista de processos atual em disco pm2 resurrect # Restaurar lista de processos salva ``` ### Inicialização ```bash # Gerar e configurar integração com sistema de init pm2 startup # Exibe um comando — execute-o com sudo # Remover hook de inicialização pm2 unstartup ``` --- ## Ecosystem File O ecosystem file (`ecosystem.config.js`) é a forma recomendada de gerenciar apps. Um template é gerado em `~/ecosystem.config.js` durante a configuração. ### Template Padrão ```js module.exports = { apps: [ { name: "app", script: "./index.js", instances: 1, exec_mode: "fork", watch: false, ignore_watch: ["node_modules", "logs", ".git"], max_memory_restart: "300M", log_date_format: "YYYY-MM-DD HH:mm:ss", merge_logs: true, time: true, autorestart: true, max_restarts: 10, restart_delay: 1000, kill_timeout: 3000, wait_ready: false, env: { NODE_ENV: "development", }, env_production: { NODE_ENV: "production", }, }, ], }; ``` --- ## Referência de Configuração ### Geral | Opção | Tipo | Padrão | Descrição | | ------------------ | ------- | -------------- | ----------------------------------------------------------------- | | `name` | string | nome do script | Identificador usado em `pm2 list` e comandos | | `script` | string | — | Caminho para o script de entrada (obrigatório) | | `cwd` | string | — | Diretório de trabalho do processo | | `args` | string | — | Argumentos CLI passados ao script | | `interpreter` | string | `node` | Caminho para o interpretador do runtime | | `interpreter_args` | string | — | Flags passadas ao interpretador (ex: `--max-old-space-size=4096`) | | `force` | boolean | `false` | Permite iniciar o mesmo script mais de uma vez | ### Escalabilidade | Opção | Tipo | Padrão | Descrição | | ----------- | ------ | ------ | -------------------------------------------------------- | | `instances` | number | `1` | Número de instâncias. `-1` = todos os núcleos da CPU | | `exec_mode` | string | `fork` | `fork` (qualquer runtime) ou `cluster` (somente Node.js) | ### Estabilidade e Reinicialização | Opção | Tipo | Padrão | Descrição | | ----------------------- | ------------- | ------- | ----------------------------------------------------------------- | | `autorestart` | boolean | `true` | Reiniciar em caso de falha | | `max_restarts` | number | `10` | Máximo de reinicializações instáveis consecutivas antes de parar | | `min_uptime` | string/number | — | Tempo mínimo para ser considerado estável (ms ou `"2s"`) | | `restart_delay` | number | `0` | Milissegundos de espera antes de reiniciar app com falha | | `max_memory_restart` | string | — | Reiniciar se RSS exceder este valor (ex: `"300M"`, `"1G"`) | | `kill_timeout` | number | `1600` | Milissegundos antes de SIGKILL após SIGTERM | | `shutdown_with_message` | boolean | `false` | Usar `process.send('shutdown')` em vez de SIGTERM | | `wait_ready` | boolean | `false` | Aguardar `process.send('ready')` antes de considerar o app online | | `listen_timeout` | number | — | Milissegundos para aguardar sinal `ready` antes de forçar reload | ### Watch | Opção | Tipo | Padrão | Descrição | | -------------- | ------------- | ------- | ------------------------------------------------------------ | | `watch` | boolean/array | `false` | Reiniciar em mudanças de arquivo. Passe um array de caminhos | | `ignore_watch` | array | — | Caminhos ou padrões glob excluídos do watch | ### Logging | Opção | Tipo | Padrão | Descrição | | ----------------------------- | ------- | ------------------------------ | --------------------------------------------------- | | `log_date_format` | string | — | Formato do timestamp (ex: `"YYYY-MM-DD HH:mm:ss"`) | | `out_file` | string | `~/.pm2/logs/-out.log` | Caminho para log de stdout | | `error_file` | string | `~/.pm2/logs/-error.log` | Caminho para log de stderr | | `log_file` | string | — | Caminho para log combinado stdout+stderr | | `merge_logs` / `combine_logs` | boolean | `false` | Desabilitar sufixos de log por instância no cluster | | `time` | boolean | `false` | Prefixar cada linha de log com timestamp | ### Ambiente | Opção | Tipo | Descrição | | ----------------- | ------- | ---------------------------------------------------------------------- | | `env` | object | Variáveis injetadas em todos os modos | | `env_` | object | Variáveis injetadas com `--env ` (ex: `env_production`) | | `filter_env` | array | Remover variáveis de ambiente global com esses prefixos | | `instance_var` | string | Nome da variável com índice da instância (padrão: `NODE_APP_INSTANCE`) | | `appendEnvToName` | boolean | Acrescentar nome do ambiente ao nome do app | ### Source Maps e Diversos | Opção | Tipo | Padrão | Descrição | | -------------------- | ------- | ------ | ------------------------------------------------------------------ | | `source_map_support` | boolean | `true` | Habilitar suporte a source map para stack traces | | `vizion` | boolean | `true` | Rastrear metadados do controle de versão | | `cron_restart` | string | — | Expressão cron para reinicializações agendadas (ex: `"0 3 * * *"`) | | `post_update` | array | — | Comandos a executar após uma atualização `pm2 pull` | --- ## Configurações Globais do PM2 O SetupVibe configura as seguintes durante a instalação: | Configuração | Valor | Descrição | | --------------------- | --------------------- | -------------------------------------------------- | | `pm2:autodump` | `true` | Auto-salvar lista de processos em qualquer mudança | | `pm2:log_date_format` | `YYYY-MM-DD HH:mm:ss` | Formato de timestamp padrão para todos os logs | ```bash pm2 set pm2:autodump true pm2 set pm2:log_date_format "YYYY-MM-DD HH:mm:ss" pm2 get # Listar todas as configurações atuais do módulo PM2 ``` --- ## Cluster Mode (Node.js) ```js { instances: "max", // ou um número, ou -1 exec_mode: "cluster", } ``` ```bash pm2 reload meuapp # Reload rolling sem downtime em cluster mode pm2 scale meuapp 4 # Escalar para 4 instâncias em tempo real pm2 scale meuapp +2 # Adicionar 2 instâncias ``` --- ## Inicialização Automática O SetupVibe configura o PM2 para iniciar automaticamente no boot: - **macOS** — registra um agente launchd (`pm2 startup launchd`) - **Linux** — registra um serviço systemd (`pm2 startup systemd`) Para refazer manualmente: ```bash pm2 startup # Exibe o comando a executar pm2 save # Salva a lista de processos atual ``` Para remover: ```bash pm2 unstartup ``` --- ### Spec-Kit no SetupVibe: instalação e referência completa - URL: https://promovaweb.com/docs/setupvibe/ferramentas/spec-kit - Descrição: Consulte como a edição Desktop instala o Spec-Kit e use seus comandos, fases, opções do CLI e aliases preparados pelo SetupVibe no fluxo de especificação. O SetupVibe instala o [Spec-Kit](https://github.com/github/spec-kit) na edição Desktop (macOS e Linux desktop) via `uv tool install specify-cli`. > Guia de ferramentas — v0.41.11 - **Comando:** `specify` - **Pacote:** `specify-cli` (PyPI) - **Requisitos:** Python 3.11+, `uv`, Git e um agente de IA --- ## O que é o Spec-Kit? O Spec-Kit é um **conjunto de ferramentas de código aberto para o Spec-Driven Development (SDD)** — uma metodologia que inverte a abordagem tradicional de desenvolvimento de software, tornando as especificações executáveis antes que qualquer código seja escrito. Em vez de pular direto para o código ("vibe coding"), o SDD guia você através de três fases: | Fase | Comando | Propósito | | ----------- | ------------------ | ---------------------------------------------------- | | **Specify** | `/speckit.specify` | Define *o que* construir e *por que* | | **Plan** | `/speckit.plan` | Define *como* construir (arquitetura, stack técnica) | | **Tasks** | `/speckit.tasks` | Quebra o plano em partes de implementação acionáveis | --- ## Primeiros Passos ```bash # Verifica se todas as dependências estão instaladas spcheck # Inicializa um novo projeto em uma nova pasta spinit meu-projeto # Inicializa no diretório atual com o Claude spci # Inicializa no diretório atual com o Copilot spkpi ``` --- ## Instalação e Atualização ```bash # Instala o Spec-Kit manualmente (se necessário) uv tool install specify-cli # Atualiza para a versão mais recente spup ``` --- ## Referência da CLI ### `specify init` Prepara um projeto para Spec-Driven Development. ```bash specify init [opções] ``` | Opção | Descrição | | ---------------------- | -------------------------------------------------------------- | | `--ai ` | Agente de IA para usar: `claude`, `copilot`, `codebuddy`, `pi` | | `--script ` | Tipo de script: `sh` (Bash) ou `ps` (PowerShell) | | `--here` | Inicializa no diretório atual em vez de uma nova pasta | | `--offline` | Usa ativos integrados sem buscar na rede | | `--ignore-agent-tools` | Pula a validação de ferramentas do agente de IA | ### `specify check` Verifica se todas as dependências necessárias (Python, uv, Git, agente de IA) estão instaladas e acessíveis. ```bash specify check ``` --- ## Aliases do SetupVibe Estes aliases estão disponíveis após executar o SetupVibe Desktop no macOS ou Linux. | Alias | Comando | Descrição | | --------- | ---------------------------------- | ------------------------------------- | | `sp` | `specify` | Atalho para o comando principal | | `spinit` | `specify init` | Inicializa SDD em novo diretório | | `spcheck` | `specify check` | Verifica dependências instaladas | | `sphere` | `specify init --here` | Inicializa SDD no diretório atual | | `spci` | `specify init --here --ai claude` | Inicia projeto SDD com Claude Code | | `spkpi` | `specify init --here --ai copilot` | Inicia projeto SDD com GitHub Copilot | | `spup` | `uv tool upgrade specify-cli` | Atualiza o Spec-Kit | --- ## Fluxo de Trabalho Típico ### 1. Preparar o projeto ```bash mkdir meu-app && cd meu-app spci ``` Isso cria a estrutura do Spec-Kit com o Claude Code como agente de IA. ### 2. Escrever a especificação Abra seu agente de IA e execute o comando `/speckit.specify`. Responda aos prompts para definir: - Qual problema você está resolvendo? - Qual público usará a solução? - Quais são os cenários principais e os resultados esperados? ### 3. Criar o plano técnico Execute `/speckit.plan` em seu agente de IA para produzir: - Decisões de arquitetura - Escolhas de stack de tecnologia - Pontos de integração e restrições ### 4. Quebrar em tarefas Execute `/speckit.tasks` para gerar uma lista numerada e ordenada de tarefas de implementação a partir do plano. ### 5. Implementar Use `/speckit.implement` ou trabalhe tarefa por tarefa com seu agente de IA, referenciando a especificação e o plano em cada etapa. --- ## Agentes de IA Suportados | Agente | Flag | Notas | | -------------- | ---------------- | ---------------------------------------------- | | Claude Code | `--ai claude` | Recomendação padrão para usuários do SetupVibe | | GitHub Copilot | `--ai copilot` | Requer assinatura do Copilot | | CodeBuddy | `--ai codebuddy` | Assistente de IA da Tencent Cloud | | Pi | `--ai pi` | Assistente de IA da Inflection | --- ## Dicas - Execute `spcheck` antes de iniciar qualquer projeto para confirmar se seu ambiente está pronto. - Use `--offline` em ambientes isolados ou quando a rede não for confiável. - A flag `--here` (alias `sphere`) é útil quando a pasta do projeto já existe. - Faça o commit dos arquivos de especificação gerados junto com seu código — eles servem como documentação viva. - Execute `spup` periodicamente para se manter na versão mais recente do Spec-Kit. --- ### Tmux no SetupVibe: sessões, painéis e atalhos no terminal - URL: https://promovaweb.com/docs/setupvibe/ferramentas/tmux - Descrição: Consulte sessões, janelas, painéis, plugins e atalhos da configuração de tmux distribuída pelas edições Desktop e Server do SetupVibe, com exemplos. > Configuração do multiplexador de terminal — v0.41.11 O SetupVibe instala e configura o tmux com o [TPM](https://github.com/tmux-plugins/tpm) e um conjunto selecionado de plugins. A Edição Desktop usa [`conf/tmux-desktop.conf`](https://github.com/promovaweb/setupvibe/blob/main/conf/tmux-desktop.conf), baixada automaticamente durante a instalação. A Edição Server usa uma [`conf/tmux-server.conf`](https://github.com/promovaweb/setupvibe/blob/main/conf/tmux-server.conf) com menos plugins — mantém os mesmos atalhos, mas sem os plugins `docker`, `mise` e `tmux-open`, e com uma barra de status simplificada (`git · cwd` à esquerda). --- ## O que é o tmux? O tmux é um **multiplexador de terminal** — permite executar múltiplas sessões de terminal em uma única janela, manter sessões ativas após desconexão e dividir a tela em painéis. Essencial para servidores remotos e usuários avançados. **Conceitos principais:** | Conceito | Descrição | | ---------- | --------------------------------------------------------------- | | **Sessão** | Uma coleção de janelas. Sobrevive à desconexão. | | **Janela** | Como uma aba do navegador — uma visão em tela cheia na sessão. | | **Painel** | Uma divisão dentro de uma janela. Múltiplos painéis por janela. | | **Prefix** | `Ctrl + b` — usado antes de todo atalho do tmux. | --- ## Primeiros Passos ```bash # Iniciar uma nova sessão tmux # Iniciar uma sessão com nome tmux new -s meuprojeto # Listar sessões tmux ls # Conectar à última sessão tmux attach # Conectar a uma sessão com nome tmux attach -t meuprojeto # Encerrar uma sessão tmux kill-session -t meuprojeto ``` Após abrir o tmux, pressione `prefix + I` (i maiúsculo) para instalar todos os plugins. --- ## Teclas Estendidas Ambas as configurações ativam `extended-keys on` e adicionam `terminal-features '*:extkeys'`, para que o tmux repasse combinações de modificador+tecla — `Shift+Enter`, `Ctrl+Seta` e semelhantes — para o aplicativo em execução em vez de absorvê-las. Isso beneficia aplicativos que distinguem essas combinações, incluindo Claude Code, Codex, Kimi Code e Neovim. --- ## Atalhos de Teclado Padrão > Em todos os atalhos, use **`Ctrl + b`** primeiro e depois a tecla. ### Sessões | Atalho | Ação | | ------------ | --------------------------------------------- | | `prefix + s` | Listar e alternar sessões (interativo) | | `prefix + $` | Renomear sessão atual | | `prefix + d` | Desconectar da sessão (sessão continua ativa) | | `prefix + (` | Ir para a sessão anterior | | `prefix + )` | Ir para a próxima sessão | | `prefix + L` | Ir para a última sessão utilizada | ### Janelas | Atalho | Ação | | -------------- | -------------------------------------- | | `prefix + c` | Criar nova janela | | `prefix + ,` | Renomear janela atual | | `prefix + &` | Encerrar janela atual | | `prefix + n` | Próxima janela | | `prefix + p` | Janela anterior | | `prefix + l` | Última janela (alternar) | | `prefix + w` | Listar e alternar janelas (interativo) | | `prefix + 0–9` | Ir para janela pelo número | | `prefix + '` | Digitar número da janela para ir | | `prefix + .` | Mover janela para índice diferente | | `prefix + f` | Buscar janela pelo nome | ### Painéis | Atalho | Ação | | ---------------------- | ----------------------------------------------------------------------- | | `prefix + %` | Dividir verticalmente (esquerda/direita) | | `prefix + "` | Dividir horizontalmente (cima/baixo) | | `prefix + o` | Ir para o próximo painel | | `prefix + ;` | Alternar para o último painel ativo | | `prefix + x` | Encerrar painel atual | | `prefix + z` | Zoom/unzoom do painel (alternar tela cheia) | | `prefix + q` | Mostrar números dos painéis (pressione o número para ir) | | `prefix + {` | Trocar painel com o anterior | | `prefix + }` | Trocar painel com o próximo | | `prefix + Alt+1–5` | Mudar para layouts predefinidos (even-h, even-v, main-h, main-v, tiled) | | `prefix + !` | Transformar painel em janela própria | | `prefix + m` | Marcar painel | | `prefix + M` | Limpar marcação do painel | | `↑ ↓ ← →` | Navegar entre painéis por direção | | `prefix + Ctrl + ↑↓←→` | Redimensionar painel (1 célula) | | `prefix + Alt + ↑↓←→` | Redimensionar painel (5 células) | ### Modo de Cópia | Atalho | Ação | | ----------------------- | ----------------------------------- | | `prefix + [` | Entrar no modo de cópia | | `prefix + ]` | Colar último buffer copiado | | `prefix + #` | Listar buffers de colagem | | `prefix + =` | Escolher buffer da lista para colar | | `prefix + -` | Excluir buffer mais recente | | `q` (no modo de cópia) | Sair do modo de cópia | | `Space` (modo de cópia) | Iniciar seleção | | `Enter` (modo de cópia) | Copiar seleção e sair | | `/` (modo de cópia) | Buscar para frente | | `?` (modo de cópia) | Buscar para trás | ### Diversos | Atalho | Ação | | ----------------- | --------------------------------- | | `prefix + :` | Abrir prompt de comando tmux | | `prefix + ?` | Listar todos os atalhos | | `prefix + r` | Recarregar configuração tmux | | `prefix + t` | Mostrar relógio | | `prefix + i` | Mostrar informações da janela | | `prefix + ~` | Mostrar mensagens do tmux | | `prefix + D` | Escolher cliente para desconectar | | `prefix + E` | Distribuir painéis igualmente | | `prefix + Ctrl+z` | Suspender cliente tmux | --- ## Plugins ### Núcleo | Plugin | Descrição | | --------------------------------------------------------------------------- | ---------------------- | | [tmux-plugins/tpm](https://github.com/tmux-plugins/tpm) | Gerenciador de plugins | | [tmux-plugins/tmux-sensible](https://github.com/tmux-plugins/tmux-sensible) | Padrões sensatos | **Atalhos do TPM:** | Atalho | Ação | | ---------------- | -------------------------- | | `prefix + I` | Instalar plugins | | `prefix + U` | Atualizar plugins | | `prefix + Alt+u` | Remover plugins não usados | --- ### Navegação e Controle de Painéis #### [tmux-pain-control](https://github.com/tmux-plugins/tmux-pain-control) Atalhos consistentes e intuitivos para divisão e redimensionamento de painéis. | Atalho | Ação | Substitui padrão | | ------------------ | -------------------------------- | ---------------------------------------------------- | | `prefix + \|` | Dividir verticalmente (esq/dir) | `prefix + %` ainda funciona | | `prefix + -` | Dividir horizontalmente (c/b) | Substitui `delete-buffer` (raramente usado) | | `prefix + \` | Dividir verticalmente completo | — | | `prefix + _` | Dividir horizontalmente completo | — | | `prefix + h` | Selecionar painel à esquerda | — | | `prefix + j` | Selecionar painel abaixo | — | | `prefix + k` | Selecionar painel acima | — | | `prefix + l` | Selecionar painel à direita | `last-window` restaurado após carregamento do plugin | | `prefix + H/J/K/L` | Redimensionar painel (5 células) | — | #### [christoomey/vim-tmux-navigator](https://github.com/christoomey/vim-tmux-navigator) Navegue entre painéis do tmux e splits do vim com as mesmas teclas. | Atalho | Ação | | ---------- | ------------------------- | | `Ctrl + h` | Mover para esquerda | | `Ctrl + j` | Mover para baixo | | `Ctrl + k` | Mover para cima | | `Ctrl + l` | Mover para direita | | `Ctrl + \` | Ir para o painel anterior | > Sem prefix. Funciona de forma transparente dentro do vim/neovim. --- ### Mouse #### [NHDaly/tmux-better-mouse-mode](https://github.com/NHDaly/tmux-better-mouse-mode) | Recurso | Comportamento | | ------------------------------ | ------------------------------------------------------- | | Rolar para baixo no modo cópia | Sai do modo de cópia automaticamente | | Rolar sobre painel | Não muda o painel ativo | | Rolar em vim/less/man | Envia eventos de scroll para o app (buffer alternativo) | --- ### Cópia e Clipboard #### [tmux-plugins/tmux-yank](https://github.com/tmux-plugins/tmux-yank) | Atalho | Contexto | Ação | | ------------ | ---------- | ------------------------------------------ | | `prefix + y` | Normal | Copiar texto da linha de comando | | `prefix + Y` | Normal | Copiar diretório de trabalho atual | | `y` | Modo cópia | Copiar seleção para clipboard | | `Y` | Modo cópia | Copiar seleção e colar na linha de comando | #### [CrispyConductor/tmux-copy-toolkit](https://github.com/CrispyConductor/tmux-copy-toolkit) | Atalho | Ação | | ------------ | ------------------- | | `prefix + e` | Ativar copy toolkit | #### [abhinav/tmux-fastcopy](https://github.com/abhinav/tmux-fastcopy) Cópia baseada em dicas (estilo vimium). Destaca padrões de texto na tela e permite copiá-los digitando letras curtas de dica. | Atalho | Ação | | ------------ | ------------------------ | | `prefix + F` | Ativar dicas do fastcopy | Reconhece: URLs, IPs, hashes Git, caminhos de arquivo, UUIDs, cores hex, números e mais. > Usa `prefix + F` (maiúsculo) — `prefix + f` é preservado para o `find-window` nativo do tmux. --- ### Abertura de URLs e Arquivos #### [tmux-plugins/tmux-open](https://github.com/tmux-plugins/tmux-open) | Atalho | Contexto | Ação | | ----------- | ---------- | ------------------------------ | | `o` | Modo cópia | Abrir com aplicativo padrão | | `Ctrl + o` | Modo cópia | Abrir com `$EDITOR` | | `Shift + s` | Modo cópia | Pesquisar seleção no navegador | #### [wfxr/tmux-fzf-url](https://github.com/wfxr/tmux-fzf-url) | Atalho | Ação | | ------------ | -------------------- | | `prefix + u` | Abrir seletor de URL | --- ### Gerenciamento de Sessões #### [tmux-plugins/tmux-resurrect](https://github.com/tmux-plugins/tmux-resurrect) Salva e restaura todo o ambiente tmux após reinicializações. | Atalho | Ação | | ----------------- | ---------------- | | `prefix + Ctrl+s` | Salvar sessão | | `prefix + Ctrl+r` | Restaurar sessão | Salva: janelas, painéis, diretórios de trabalho, conteúdo dos painéis, programas em execução. #### [tmux-plugins/tmux-continuum](https://github.com/tmux-plugins/tmux-continuum) | Recurso | Valor | | ---------------------------- | ----------------- | | Intervalo de auto-salvamento | A cada 10 minutos | | Auto-restauração ao iniciar | Ativado | Sem atalhos — funciona automaticamente em segundo plano. #### [omerxx/tmux-sessionx](https://github.com/omerxx/tmux-sessionx) Gerenciador de sessões completo com preview via fzf. | Atalho | Ação | | ------------ | ---------------------------- | | `prefix + S` | Abrir gerenciador de sessões | Dentro do sessionx: `Ctrl+d` excluir sessão, `Ctrl+r` renomear, `Tab` alternar preview. > Usa `prefix + S` (maiúsculo) — `prefix + o` é preservado para o `rotate-pane` nativo do tmux. --- ### Buscador Fuzzy #### [sainnhe/tmux-fzf](https://github.com/sainnhe/tmux-fzf) Gerencie sessões, janelas, painéis e execute comandos via fzf. | Atalho | Ação | | ------------------------ | ------------------- | | `prefix + F` (maiúsculo) | Abrir menu tmux-fzf | --- ### Auxiliares de Interface #### [Freed-Wu/tmux-digit](https://github.com/Freed-Wu/tmux-digit) | Atalho | Ação | | -------------- | -------------------------------------- | | `prefix + 0–9` | Ir diretamente para janela pelo índice | #### [anghootys/tmux-ip-address](https://github.com/anghootys/tmux-ip-address) Exibe o endereço IP atual da máquina na barra de status. Sem atalhos. #### [tmux-plugins/tmux-prefix-highlight](https://github.com/tmux-plugins/tmux-prefix-highlight) Destaca a barra de status quando a tecla prefix está ativa, no modo de cópia ou no modo de sincronização. Sem atalhos. #### [alexwforsythe/tmux-which-key](https://github.com/alexwforsythe/tmux-which-key) | Atalho | Ação | | ---------------- | -------------------- | | `prefix + Space` | Abrir menu which-key | > `prefix + Space` é intencionalmente dedicado ao which-key. O next-layout ainda está disponível via `prefix + Alt+1–5`. #### [jaclu/tmux-menus](https://github.com/jaclu/tmux-menus) | Atalho | Ação | | ------------ | ---------------------- | | `prefix + g` | Abrir menu de contexto | --- ### Tema #### [2KAbhishek/tmux2k](https://github.com/2KAbhishek/tmux2k) **Desktop** (`tmux-desktop.conf`): | Posição | Widgets | | -------- | ---------------------------------- | | Esquerda | `git` · `cwd` · `docker` · `mise` | | Direita | `cpu` · `ram` · `network` · `time` | **Server** (`tmux-server.conf`): | Posição | Widgets | | -------- | ---------------------------------- | | Esquerda | `git` · `cwd` | | Direita | `cpu` · `ram` · `network` · `time` | **Tema:** `onedark` com separadores powerline em ambas as edições. --- ## Resolução de Conflitos de Teclas | Tecla | Padrão tmux | Plugin | Resolução | | ---------------- | ----------------------------- | ----------------- | ------------------------------------------------------------------------- | | `prefix + f` | `find-window` | tmux-fastcopy | Fastcopy movido para `prefix + F` — padrão preservado | | `prefix + o` | `rotate-pane` | tmux-sessionx | Sessionx movido para `prefix + S` — padrão preservado | | `prefix + l` | `last-window` | tmux-pain-control | Padrão restaurado com `bind-key l last-window` após carregamento do TPM | | `prefix + -` | `delete-buffer` | tmux-pain-control | Pain-control substitui com split-h — aceito (padrão raramente usado) | | `prefix + \` | *(split do pain-control)* | tmux-menus | Menus movidos para `prefix + g` — split do pain-control preservado | | `prefix + M` | `select-pane -M` (clear mark) | tmux-menus | Menus movidos para `prefix + g` — padrão preservado | | `prefix + Space` | `next-layout` | tmux-which-key | which-key usa Space — next-layout ainda disponível via `prefix + Alt+1–5` | --- ### Como contribuir com o projeto open source SetupVibe - URL: https://promovaweb.com/docs/setupvibe/projeto/contribuir - Descrição: Consulte o fluxo de contribuição do SetupVibe, os padrões dos scripts Bash, as regras de documentação e o processo de versionamento, testes e releases. Bem-vindo ao guia de contribuição do **SetupVibe**! Estamos empolgados com o seu interesse. Este documento descreve os padrões e fluxos de trabalho necessários para contribuir com este projeto. ## 🚀 Como Começar 1. **Faça um Fork** do repositório. 2. **Clone** o seu fork localmente. 3. **Crie uma branch** para sua funcionalidade ou correção (ex: `feat/nova-ferramenta` ou `fix/link-quebrado`). 4. **Implemente** suas mudanças seguindo os padrões abaixo. 5. **Envie um Pull Request** com uma descrição clara das suas alterações. --- ## 🛠 Padrões de Código (Bash) O SetupVibe utiliza dois scripts principais: `desktop.sh` e `server.sh`. Todo o código Shell deve seguir estes padrões: ### 1. Elevação Inteligente de Privilégios Nunca utilize `sudo` diretamente dentro de funções, a menos que seja estritamente necessário por motivos específicos. Utilize nossas funções auxiliares: - **`user_do`**: Executa um comando como o usuário real (mesmo que o script tenha sido iniciado com `sudo`). Use para instalar ferramentas em `$HOME`, configurar o Git ou gerenciar dotfiles do usuário. - **`sys_do`**: Executa um comando com privilégios elevados. Use para gerenciamento de pacotes do sistema (`apt`), modificação de `/etc` ou gerenciamento de serviços do sistema. ### 2. Arquitetura Modular Os scripts são organizados em funções modulares chamadas `step_N`. Se você adicionar uma nova funcionalidade: 1. Adicione o título ao array `STEPS`. 2. Crie uma função `step_N` correspondente. 3. Garanta que a lógica suporte tanto **macOS (`$IS_MACOS`)** quanto **Linux (`$IS_LINUX`)** onde aplicável. ### 3. Idempotência Os scripts devem ser seguros para execução múltipla. Sempre verifique se uma ferramenta já está instalada ou se uma configuração já existe antes de aplicar as alterações. ### 4. Gerenciamento de Chaves (Linux) Não utilize `apt-key` (depreciado). Sempre armazene chaves GPG do APT em `/etc/apt/keyrings/` utilizando os auxiliares `install_key` ou `sys_do`. --- ## 📝 Padrões de Documentação (Markdown) Todos os arquivos `.md` devem seguir estas regras rigorosamente: 1. **Hierarquia**: Use cabeçalhos hierárquicos (H1 → H2 → H3). Nunca pule níveis. 2. **Tabelas**: Alinhe colunas com pipes `|` e inclua uma linha separadora `|---|`. 3. **Blocos de Código**: Sempre especifique a linguagem (ex: ` ```bash `). 4. **Links**: Use o formato `[texto](https://github.com/promovaweb/setupvibe/tree/main/docs/pt-br/url)`. Não use URLs brutas. 5. **Listas**: Use hífens `-` para listas não ordenadas. 6. **Espaçamento**: Uma linha em branco antes e depois de cabeçalhos, blocos de código e tabelas. 7. **Sem HTML**: Evite `
`, ``, `` ou outras tags HTML. --- ## 🔢 Processo de Versionamento Ao atualizar a versão (ex: de `0.41.10` para `0.42.0`), você **deve** atualizar a string de versão em todos os seguintes locais: - `desktop.sh` (variável `VERSION`) - `server.sh` (variável `VERSION`) - `CHANGELOG.md` (adicionar uma nova entrada) - `README.md` (visão geral do projeto na raiz) - `AGENTS.md` (visão geral do projeto para Codex) - `CLAUDE.md` (visão geral do projeto para Claude) - Todos os arquivos `README.md` em `docs/` e seus subdiretórios. --- ## 🤖 Automação & Skills Este projeto utiliza **Agent Skills** (localizadas em `.codex/skills` e `.claude/skills`) para automatizar tarefas. - Se você for um agente de IA, você **deve** ativar as skills relevantes (ex: `markdown-format`, `make-changelog`) antes de realizar tarefas. - As skills de Codex e Claude devem permanecer funcionalmente alinhadas, preservando instruções específicas de cada plataforma. - Se você for um humano, esteja ciente de que essas skills reforçam os padrões mencionados acima. --- ### Referência completa de aliases do SetupVibe no terminal - URL: https://promovaweb.com/docs/setupvibe/referencia/aliases - Descrição: Consulte a lista completa de aliases do SetupVibe, com disponibilidade por edição, comando expandido, descrição e exemplo de uso no terminal local. > Aliases do ambiente shell — v0.41.11 Esta é a lista exaustiva de todos os aliases configurados pelo SetupVibe em todas as plataformas. **Legenda de Disponibilidade:** - 🖥️ **Desktop**: Disponível na edição Desktop (macOS e Linux Desktop). - ☁️ **Server**: Disponível na edição Server (Linux). - 🌐 **Ambos**: Disponível em todas as edições. --- ## SetupVibe - **`setupvibe`** - Disponibilidade: 🌐 Ambos - Comando: `curl -sSL desktop.setupvibe.dev | bash` (Desktop) / `curl -sSL server.setupvibe.dev | bash` (Server) - Descrição: Reinstala ou atualiza o SetupVibe. - Exemplo: `setupvibe` ## AI CLIs - **`cc`** - Disponibilidade: 🌐 Ambos - Comando: `claude --permission-mode=auto --dangerously-skip-permissions` - Descrição: Claude CLI sem confirmações. - Exemplo: `cc` ## Skills CLI - **`skl`** - Disponibilidade: 🌐 Ambos - Comando: `skills list` - Descrição: Lista todas as skills instaladas. - Exemplo: `skl` - **`skf`** - Disponibilidade: 🌐 Ambos - Comando: `skills find` - Descrição: Busca skills no registro. - Exemplo: `skf react` - **`ska`** - Disponibilidade: 🌐 Ambos - Comando: `skills add` - Descrição: Instala uma nova skill. - Exemplo: `ska owner/repo` - **`sku`** - Disponibilidade: 🌐 Ambos - Comando: `skills update` - Descrição: Atualiza todas as skills instaladas. - Exemplo: `sku` - **`skun`** - Disponibilidade: 🌐 Ambos - Comando: `skills remove` - Descrição: Remove uma skill instalada. - Exemplo: `skun nome` - **`skc`** - Disponibilidade: 🌐 Ambos - Comando: `skills check` - Descrição: Verifica atualizações disponíveis. - Exemplo: `skc` ## Shell & Utilitários - **`zconfig`** - Disponibilidade: 🌐 Ambos - Comando: `nano ~/.zshrc` - Descrição: Edita o arquivo de configuração do ZSH. - Exemplo: `zconfig` - **`reload`** - Disponibilidade: 🌐 Ambos - Comando: `source ~/.zshrc` - Descrição: Recarrega as configurações do ZSH e as personalizações locais sem reiniciar o terminal. - Exemplo: `reload` - **`zlocal`** - Disponibilidade: 🌐 Ambos - Comando: `nano ~/.zshrc.local` - Descrição: Edita o arquivo de configurações personalizadas do ZSH (nunca sobrescrito em atualizações). - Exemplo: `zlocal` - **`path`** - Disponibilidade: 🌐 Ambos - Comando: `echo -e ${PATH//:/\\n}` - Descrição: Exibe cada entrada do PATH em uma linha separada. - Exemplo: `path` - **`h`** - Disponibilidade: 🌐 Ambos - Comando: `history | grep` - Descrição: Busca no histórico de comandos. - Exemplo: `h docker` - **`cls`** - Disponibilidade: 🌐 Ambos - Comando: `clear` - Descrição: Limpa o terminal. - Exemplo: `cls` - **`please`** - Disponibilidade: 🌐 Ambos - Comando: `sudo` - Descrição: Atalho amigável para sudo. - Exemplo: `please apt update` - **`week`** - Disponibilidade: 🌐 Ambos - Comando: `date +%V` - Descrição: Exibe o número da semana atual. - Exemplo: `week` ## Navegação & Filesystem - **`..`** - Disponibilidade: 🌐 Ambos - Comando: `cd ..` - Descrição: Sobe um nível de diretório. - Exemplo: `..` - **`...`** - Disponibilidade: 🌐 Ambos - Comando: `cd ../..` - Descrição: Sobe dois níveis de diretório. - Exemplo: `...` - **`....`** - Disponibilidade: 🌐 Ambos - Comando: `cd ../../..` - Descrição: Sobe três níveis de diretório. - Exemplo: `....` - **`ll`** - Disponibilidade: 🌐 Ambos - Comando: `ls -lhA` (macOS) / `ls -lhA --color=auto` (Linux) - Descrição: Lista arquivos com detalhes e tamanho legível. - Exemplo: `ll` - **`la`** - Disponibilidade: 🌐 Ambos - Comando: `ls -A` (macOS) / `ls -A --color=auto` (Linux) - Descrição: Lista todos os arquivos incluindo ocultos. - Exemplo: `la` - **`lsd`** - Disponibilidade: 🌐 Ambos - Comando: `ls -d */ 2>/dev/null` - Descrição: Lista apenas diretórios. - Exemplo: `lsd` - **`md`** - Disponibilidade: 🌐 Ambos - Comando: `mkdir -p` - Descrição: Cria diretório e subdiretórios automaticamente. - Exemplo: `md projeto/src/css` - **`rmf`** - Disponibilidade: 🌐 Ambos - Comando: `rm -rf` - Descrição: Remove arquivos e diretórios recursivamente sem confirmação. - Exemplo: `rmf pasta_velha` - **`du1`** - Disponibilidade: 🌐 Ambos - Comando: `du -h -d 1` (macOS) / `du -h --max-depth=1` (Linux) - Descrição: Uso de disco do diretório atual, um nível de profundidade. - Exemplo: `du1` ## Tmux - **`t`** - Disponibilidade: 🌐 Ambos - Comando: `tmux` - Descrição: Atalho para o tmux. - Exemplo: `t` - **`tn`** - Disponibilidade: 🌐 Ambos - Comando: `tmux new -s` - Descrição: Cria nova sessão tmux. - Exemplo: `tn meu-projeto` - **`ta`** - Disponibilidade: 🌐 Ambos - Comando: `tmux attach -t` - Descrição: Reconecta a uma sessão existente. - Exemplo: `ta meu-projeto` - **`tl`** - Disponibilidade: 🌐 Ambos - Comando: `tmux ls` - Descrição: Lista todas as sessões tmux ativas. - Exemplo: `tl` - **`tk`** - Disponibilidade: 🌐 Ambos - Comando: `tmux kill-session -t` - Descrição: Encerra uma sessão tmux. - Exemplo: `tk meu-projeto` - **`tka`** - Disponibilidade: 🌐 Ambos - Comando: `tmux kill-server` - Descrição: Encerra todas as sessões tmux. - Exemplo: `tka` - **`td`** - Disponibilidade: 🌐 Ambos - Comando: `tmux detach` - Descrição: Desconecta da sessão sem encerrá-la. - Exemplo: `td` - **`tw`** - Disponibilidade: 🌐 Ambos - Comando: `tmux new-window` - Descrição: Cria nova janela na sessão atual. - Exemplo: `tw` - **`ts`** - Disponibilidade: 🌐 Ambos - Comando: `tmux split-window -v` - Descrição: Divide painel horizontalmente (novo painel abaixo). - Exemplo: `ts` - **`tsh`** - Disponibilidade: 🌐 Ambos - Comando: `tmux split-window -h` - Descrição: Divide painel verticalmente (novo painel à direita). - Exemplo: `tsh` - **`trename`** - Disponibilidade: 🌐 Ambos - Comando: `tmux rename-session` - Descrição: Renomeia a sessão atual. - Exemplo: `trename novo-nome` - **`twrename`** - Disponibilidade: 🌐 Ambos - Comando: `tmux rename-window` - Descrição: Renomeia a janela atual. - Exemplo: `twrename editor` - **`treload`** - Disponibilidade: 🌐 Ambos - Comando: `tmux source ~/.tmux.conf` - Descrição: Recarrega as configurações do tmux. - Exemplo: `treload` - **`tconfig`** - Disponibilidade: 🌐 Ambos - Comando: `nano ~/.tmux.conf` - Descrição: Edita o arquivo de configuração do tmux. - Exemplo: `tconfig` ## Git - **`gs`** - Disponibilidade: 🌐 Ambos - Comando: `git status` - Descrição: Exibe o estado atual do repositório. - Exemplo: `gs` - **`ga`** - Disponibilidade: 🌐 Ambos - Comando: `git add` - Descrição: Adiciona arquivos ao stage. - Exemplo: `ga arquivo.txt` - **`gaa`** - Disponibilidade: 🌐 Ambos - Comando: `git add .` - Descrição: Adiciona todos os arquivos modificados ao stage. - Exemplo: `gaa` - **`gc`** - Disponibilidade: 🌐 Ambos - Comando: `git commit` - Descrição: Abre o editor para escrever a mensagem do commit. - Exemplo: `gc` - **`gcm`** - Disponibilidade: 🌐 Ambos - Comando: `git commit -m` - Descrição: Commit com mensagem inline. - Exemplo: `gcm 'fix: typo'` - **`gco`** - Disponibilidade: 🌐 Ambos - Comando: `git checkout` - Descrição: Troca de branch ou restaura arquivos. - Exemplo: `gco main` - **`gcb`** - Disponibilidade: 🌐 Ambos - Comando: `git checkout -b` - Descrição: Cria e troca para uma nova branch. - Exemplo: `gcb feature/nova-funcao` - **`gp`** - Disponibilidade: 🌐 Ambos - Comando: `git push` - Descrição: Envia commits para o repositório remoto. - Exemplo: `gp` - **`gpl`** - Disponibilidade: 🌐 Ambos - Comando: `git pull` - Descrição: Baixa e integra mudanças do repositório remoto. - Exemplo: `gpl` - **`gf`** - Disponibilidade: 🌐 Ambos - Comando: `git fetch` - Descrição: Busca atualizações do remoto sem aplicar. - Exemplo: `gf` - **`gfa`** - Disponibilidade: 🌐 Ambos - Comando: `git fetch --all --prune` - Descrição: Busca de todos os remotos e remove branches deletadas. - Exemplo: `gfa` - **`gm`** - Disponibilidade: 🌐 Ambos - Comando: `git merge` - Descrição: Faz merge de uma branch. - Exemplo: `gm feature/x` - **`grb`** - Disponibilidade: 🌐 Ambos - Comando: `git rebase` - Descrição: Reaplica commits sobre outra base. - Exemplo: `grb main` - **`gcp`** - Disponibilidade: 🌐 Ambos - Comando: `git cherry-pick` - Descrição: Aplica commit específico na branch atual. - Exemplo: `gcp abc123` - **`gl`** - Disponibilidade: 🌐 Ambos - Comando: `git log --oneline --graph --decorate` - Descrição: Log compacto com grafo de branches. - Exemplo: `gl` - **`glamelog`** - Disponibilidade: 🌐 Ambos - Comando: `git log --pretty=format:"%h %ad %s" --date=short` - Descrição: Log compacto com datas. - Exemplo: `glamelog` - **`gd`** - Disponibilidade: 🌐 Ambos - Comando: `git diff` - Descrição: Exibe diferenças não staged. - Exemplo: `gd` - **`gds`** - Disponibilidade: 🌐 Ambos - Comando: `git diff --staged` - Descrição: Exibe diferenças já em stage. - Exemplo: `gds` - **`gb`** - Disponibilidade: 🌐 Ambos - Comando: `git branch` - Descrição: Lista branches locais. - Exemplo: `gb` - **`gba`** - Disponibilidade: 🌐 Ambos - Comando: `git branch -a` - Descrição: Lista todas as branches incluindo remotas. - Exemplo: `gba` - **`gbd`** - Disponibilidade: 🌐 Ambos - Comando: `git branch -d` - Descrição: Remove uma branch local. - Exemplo: `gbd feature/x` - **`gtag`** - Disponibilidade: 🌐 Ambos - Comando: `git tag` - Descrição: Cria ou lista tags. - Exemplo: `gtag v1.0.0` - **`gclone`** - Disponibilidade: 🌐 Ambos - Comando: `git clone` - Descrição: Clona um repositório. - Exemplo: `gclone https://github.com/user/repo.git` - **`gst`** - Disponibilidade: 🌐 Ambos - Comando: `git stash` - Descrição: Salva mudanças temporariamente no stash. - Exemplo: `gst` - **`gstp`** - Disponibilidade: 🌐 Ambos - Comando: `git stash pop` - Descrição: Restaura as últimas mudanças do stash. - Exemplo: `gstp` - **`grh`** - Disponibilidade: 🌐 Ambos - Comando: `git reset HEAD~1` - Descrição: Desfaz o último commit mantendo as alterações. - Exemplo: `grh` - **`gundo`** - Disponibilidade: 🌐 Ambos - Comando: `git restore .` - Descrição: Descarta todas as alterações não staged. - Exemplo: `gundo` - **`gwip`** - Disponibilidade: 🌐 Ambos - Comando: `git add -A && git commit -m "WIP"` - Descrição: Salva trabalho em progresso rapidamente. - Exemplo: `gwip` ## GitHub CLI - **`ghpr`** - Disponibilidade: 🌐 Ambos - Comando: `gh pr create` - Descrição: Abre wizard para criar um Pull Request. - Exemplo: `ghpr` - **`ghprl`** - Disponibilidade: 🌐 Ambos - Comando: `gh pr list` - Descrição: Lista Pull Requests abertos. - Exemplo: `ghprl` - **`ghprv`** - Disponibilidade: 🌐 Ambos - Comando: `gh pr view` - Descrição: Exibe detalhes do PR atual. - Exemplo: `ghprv` - **`ghprc`** - Disponibilidade: 🌐 Ambos - Comando: `gh pr checkout` - Descrição: Faz checkout de um PR por número. - Exemplo: `ghprc 42` - **`ghprs`** - Disponibilidade: 🌐 Ambos - Comando: `gh pr status` - Descrição: Status dos PRs relacionados ao branch atual. - Exemplo: `ghprs` - **`ghrl`** - Disponibilidade: 🌐 Ambos - Comando: `gh repo list` - Descrição: Lista repositórios do usuário autenticado. - Exemplo: `ghrl` - **`ghrc`** - Disponibilidade: 🌐 Ambos - Comando: `gh repo clone` - Descrição: Clona um repositório. - Exemplo: `ghrc owner/repo` - **`ghiss`** - Disponibilidade: 🌐 Ambos - Comando: `gh issue list` - Descrição: Lista issues abertas do repositório. - Exemplo: `ghiss` - **`ghissn`** - Disponibilidade: 🌐 Ambos - Comando: `gh issue create` - Descrição: Abre wizard para criar uma nova issue. - Exemplo: `ghissn` - **`ghrun`** - Disponibilidade: 🌐 Ambos - Comando: `gh run list` - Descrição: Lista execuções de CI/CD do GitHub Actions. - Exemplo: `ghrun` - **`ghrunw`** - Disponibilidade: 🌐 Ambos - Comando: `gh run watch` - Descrição: Acompanha a execução do workflow em tempo real. - Exemplo: `ghrunw` - **`ghwf`** - Disponibilidade: 🌐 Ambos - Comando: `gh workflow list` - Descrição: Lista workflows do GitHub Actions. - Exemplo: `ghwf` - **`ghwfr`** - Disponibilidade: 🌐 Ambos - Comando: `gh workflow run` - Descrição: Dispara um workflow manualmente. - Exemplo: `ghwfr deploy.yml` - **`ghrel`** - Disponibilidade: 🌐 Ambos - Comando: `gh release list` - Descrição: Lista releases do repositório. - Exemplo: `ghrel` - **`ghrelc`** - Disponibilidade: 🌐 Ambos - Comando: `gh release create` - Descrição: Cria uma nova release. - Exemplo: `ghrelc v1.0.0` - **`ghgist`** - Disponibilidade: 🖥️ Desktop - Comando: `gh gist create` - Descrição: Cria um Gist a partir de arquivo. - Exemplo: `ghgist file.sh` - **`ghssh`** - Disponibilidade: 🖥️ Desktop - Comando: `gh ssh-key list` - Descrição: Lista chaves SSH cadastradas no perfil do GitHub. - Exemplo: `ghssh` ## SSH - **`ssha`** - Disponibilidade: 🌐 Ambos - Comando: `ssh-add` - Descrição: Adiciona chave SSH ao agente. - Exemplo: `ssha ~/.ssh/id_ed25519` - **`sshal`** - Disponibilidade: 🌐 Ambos - Comando: `ssh-add -l` - Descrição: Lista chaves carregadas no agente SSH. - Exemplo: `sshal` - **`sshkeys`** - Disponibilidade: 🌐 Ambos - Comando: `ls -la ~/.ssh/` - Descrição: Lista todos os arquivos de chaves SSH. - Exemplo: `sshkeys` - **`sshconfig`** - Disponibilidade: 🌐 Ambos - Comando: `nano ~/.ssh/config` - Descrição: Edita o arquivo de configuração do SSH. - Exemplo: `sshconfig` - **`keygen`** - Disponibilidade: 🌐 Ambos - Comando: `ssh-keygen -t ed25519 -C` - Descrição: Gera nova chave SSH Ed25519. - Exemplo: `keygen 'email@x.com'` - **`ssh_copy_id`** - Disponibilidade: 🌐 Ambos - Comando: `~/.setupvibe/bin/ssh_copy_id --host HOST --user USUARIO [--pass SENHA]` - Descrição: Copia sua chave SSH pública para um servidor remoto usando senha inline ou prompt oculto. - Exemplo: `ssh_copy_id --host 192.0.2.10 --user root --pass 'senha'` ## Docker - **`d`** - Disponibilidade: 🌐 Ambos - Comando: `docker` - Descrição: Atalho para o comando docker. - Exemplo: `d ps` - **`dc`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose` - Descrição: Atalho para o docker compose. - Exemplo: `dc up -d` - **`dps`** - Disponibilidade: 🌐 Ambos - Comando: `docker ps` - Descrição: Lista containers em execução. - Exemplo: `dps` - **`dpsa`** - Disponibilidade: 🌐 Ambos - Comando: `docker ps -a` - Descrição: Lista todos os containers incluindo parados. - Exemplo: `dpsa` - **`dimg`** - Disponibilidade: 🌐 Ambos - Comando: `docker images` - Descrição: Lista imagens Docker disponíveis localmente. - Exemplo: `dimg` - **`dlog`** - Disponibilidade: 🌐 Ambos - Comando: `docker logs -f` - Descrição: Segue os logs de um container. - Exemplo: `dlog meu-container` - **`dex`** - Disponibilidade: 🌐 Ambos - Comando: `docker exec -it` - Descrição: Executa comando interativo em container. - Exemplo: `dex app bash` - **`dstart`** - Disponibilidade: 🌐 Ambos - Comando: `docker start` - Descrição: Inicia um container parado. - Exemplo: `dstart meu-container` - **`dstop`** - Disponibilidade: 🌐 Ambos - Comando: `docker stop` - Descrição: Para um container em execução. - Exemplo: `dstop meu-container` - **`drm`** - Disponibilidade: 🌐 Ambos - Comando: `docker rm` - Descrição: Remove um container. - Exemplo: `drm meu-container` - **`drmi`** - Disponibilidade: 🌐 Ambos - Comando: `docker rmi` - Descrição: Remove uma imagem. - Exemplo: `drmi minha-imagem` - **`dpull`** - Disponibilidade: 🌐 Ambos - Comando: `docker pull` - Descrição: Baixa imagem do registry. - Exemplo: `dpull nginx:alpine` - **`dbuild`** - Disponibilidade: 🌐 Ambos - Comando: `docker build -t` - Descrição: Constrói imagem com tag. - Exemplo: `dbuild app:latest .` - **`dstats`** - Disponibilidade: 🌐 Ambos - Comando: `docker stats` - Descrição: Monitora CPU/memória dos containers em tempo real. - Exemplo: `dstats` - **`dins`** - Disponibilidade: 🌐 Ambos - Comando: `docker inspect` - Descrição: Inspeciona detalhes de container ou imagem. - Exemplo: `dins app` - **`dip`** - Disponibilidade: 🌐 Ambos - Comando: `docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}'` - Descrição: IP do container. - Exemplo: `dip app` - **`dnet`** - Disponibilidade: 🌐 Ambos - Comando: `docker network ls` - Descrição: Lista redes Docker disponíveis. - Exemplo: `dnet` - **`dvol`** - Disponibilidade: 🌐 Ambos - Comando: `docker volume ls` - Descrição: Lista volumes Docker criados. - Exemplo: `dvol` - **`dprune`** - Disponibilidade: 🌐 Ambos - Comando: `docker system prune -af --volumes` - Descrição: Remove todos os recursos Docker não utilizados. - Exemplo: `dprune` - **`dcup`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose up -d` - Descrição: Sobe os serviços em background. - Exemplo: `dcup` - **`dcdown`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose down` - Descrição: Para e remove os containers do compose. - Exemplo: `dcdown` - **`dcstop`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose stop` - Descrição: Para os serviços sem remover containers. - Exemplo: `dcstop` - **`dcrestart`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose restart` - Descrição: Reinicia todos os serviços do compose. - Exemplo: `dcrestart` - **`dcps`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose ps` - Descrição: Lista os serviços do compose e seus estados. - Exemplo: `dcps` - **`dclog`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose logs -f` - Descrição: Segue os logs de todos os serviços do compose. - Exemplo: `dclog` - **`dclogs`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose logs --tail=100` - Descrição: Exibe as últimas 100 linhas dos logs do compose. - Exemplo: `dclogs` - **`dcbuild`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose build --no-cache` - Descrição: Reconstrói as imagens sem cache. - Exemplo: `dcbuild` - **`dcpull`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose pull` - Descrição: Atualiza imagens dos serviços do compose. - Exemplo: `dcpull` - **`dcexec`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose exec` - Descrição: Executa comando em serviço. - Exemplo: `dcexec app bash` ## Portainer - **`portainer-start`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose -f ~/.setupvibe/portainer-compose.yml up -d` - Descrição: Inicia o container do Portainer. - Exemplo: `portainer-start` - **`portainer-stop`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose -f ~/.setupvibe/portainer-compose.yml stop` - Descrição: Para o container do Portainer. - Exemplo: `portainer-stop` - **`portainer-restart`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose -f ~/.setupvibe/portainer-compose.yml restart` - Descrição: Reinicia o container do Portainer. - Exemplo: `portainer-restart` - **`portainer-update`** - Disponibilidade: 🌐 Ambos - Comando: `docker compose -f ~/.setupvibe/portainer-compose.yml pull && docker compose -f ~/.setupvibe/portainer-compose.yml up -d` - Descrição: Atualiza a imagem e reinicia o Portainer. - Exemplo: `portainer-update` ## PM2 - **`p`** - Disponibilidade: 🌐 Ambos - Comando: `pm2` - Descrição: Atalho para o comando PM2. - Exemplo: `p list` - **`p-start`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 start ~/ecosystem.config.js` - Descrição: Inicia todas as aplicações definidas no arquivo ecosystem global. - Exemplo: `p-start` - **`p-stop`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 stop ~/ecosystem.config.js` - Descrição: Para todas as aplicações definidas no arquivo ecosystem. - Exemplo: `p-stop` - **`p-restart`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 restart ~/ecosystem.config.js` - Descrição: Reinicia todas as aplicações definidas no arquivo ecosystem. - Exemplo: `p-restart` - **`pl`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 list` - Descrição: Lista todos os processos gerenciados pelo PM2. - Exemplo: `pl` - **`psave`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 save` - Descrição: Salva a lista de processos atual para restaurar no boot. - Exemplo: `psave` - **`plog`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 logs` - Descrição: Segue os logs de todos os processos em tempo real. - Exemplo: `plog` ## Agentlytics - **`agl-start`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 start agentlytics` - Descrição: Inicia o processo do Agentlytics no PM2. - Exemplo: `agl-start` - **`agl-stop`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 stop agentlytics` - Descrição: Para o processo do Agentlytics. - Exemplo: `agl-stop` - **`agl-restart`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 restart agentlytics` - Descrição: Reinicia o processo do Agentlytics. - Exemplo: `agl-restart` - **`agl-logs`** - Disponibilidade: 🌐 Ambos - Comando: `pm2 logs agentlytics` - Descrição: Exibe os logs específicos do Agentlytics. - Exemplo: `agl-logs` ## Gerenciadores de Pacotes - **`update`** - Disponibilidade: 🌐 Ambos - Comando: `brew update && brew upgrade` (macOS) / `sudo apt update...` (Linux) - Descrição: Atualiza o sistema e gerenciadores de pacotes. - Exemplo: `update` - **`apti`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo apt install` - Descrição: Instala um pacote via APT. - Exemplo: `apti htop` - **`aptr`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo apt remove` - Descrição: Remove um pacote via APT. - Exemplo: `aptr htop` - **`apts`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `apt search` - Descrição: Busca pacotes nos repositórios APT. - Exemplo: `apts nginx` - **`aptshow`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `apt show` - Descrição: Exibe detalhes de um pacote APT. - Exemplo: `aptshow git` - **`aptls`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `dpkg -l | grep` - Descrição: Filtra pacotes instalados. - Exemplo: `aptls nginx` - **`brewup`** - Disponibilidade: 🖥️ Desktop / ☁️ Server se instalado - Comando: `brew update && brew upgrade && brew cleanup` - Descrição: Atualiza Homebrew e remove versões antigas. - Exemplo: `brewup` - **`brewls`** - Disponibilidade: 🖥️ Desktop / ☁️ Server se instalado - Comando: `brew list` - Descrição: Lista todos os pacotes instalados via Homebrew. - Exemplo: `brewls` - **`brewinfo`** - Disponibilidade: 🖥️ Desktop / ☁️ Server se instalado - Comando: `brew info` - Descrição: Exibe informações sobre um pacote. - Exemplo: `brewinfo git` - **`brewsearch`** - Disponibilidade: 🖥️ Desktop / ☁️ Server se instalado - Comando: `brew search` - Descrição: Busca pacotes no Homebrew. - Exemplo: `brewsearch ripgrep` ## Linguagens & Frameworks (🖥️ Desktop) ### Laravel / PHP - **`art`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan` - Descrição: Atalho para o PHP Artisan. - Exemplo: `art list` - **`artm`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan migrate` - Descrição: Executa as migrations pendentes. - Exemplo: `artm` - **`artmf`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan migrate:fresh` - Descrição: Recria todas as tabelas do zero. - Exemplo: `artmf` - **`artmfs`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan migrate:fresh --seed` - Descrição: Recria as tabelas e popula com seeders. - Exemplo: `artmfs` - **`arts`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan serve` - Descrição: Inicia o servidor de desenvolvimento do Laravel. - Exemplo: `arts` - **`artq`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan queue:work` - Descrição: Inicia o worker de filas. - Exemplo: `artq` - **`artc`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear` - Descrição: Limpa todos os caches do Laravel. - Exemplo: `artc` - **`artt`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan test` - Descrição: Executa a suíte de testes do Laravel. - Exemplo: `artt` - **`artmake`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan make` - Descrição: Atalho para geração de código. - Exemplo: `artmake:controller UserController` - **`artr`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan route:list` - Descrição: Lista todas as rotas da aplicação. - Exemplo: `artr` - **`arttink`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan tinker` - Descrição: Abre o REPL interativo do Laravel. - Exemplo: `arttink` - **`artkey`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan key:generate` - Descrição: Gera uma nova chave de aplicação. - Exemplo: `artkey` - **`artopt`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan optimize:clear` - Descrição: Limpa todos os caches e otimizações. - Exemplo: `artopt` - **`artschedule`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan schedule:work` - Descrição: Inicia o worker de tarefas agendadas. - Exemplo: `artschedule` - **`artdb`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan db` - Descrição: Abre conexão interativa com o banco de dados. - Exemplo: `artdb` - **`artmodel`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan make:model` - Descrição: Cria um Model. - Exemplo: `artmodel Post -m` - **`artjob`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan make:job` - Descrição: Cria um Job para filas. - Exemplo: `artjob ProcessPayment` - **`artevent`** - Disponibilidade: 🖥️ Desktop - Comando: `php artisan event:list` - Descrição: Lista todos os eventos e listeners registrados. - Exemplo: `artevent` - **`ci`** - Disponibilidade: 🖥️ Desktop - Comando: `composer install` - Descrição: Instala dependências do composer.json. - Exemplo: `ci` - **`cu`** - Disponibilidade: 🖥️ Desktop - Comando: `composer update` - Descrição: Atualiza dependências para versões permitidas. - Exemplo: `cu` - **`creq`** - Disponibilidade: 🖥️ Desktop - Comando: `composer require` - Descrição: Adiciona um pacote. - Exemplo: `creq vendor/pacote` - **`creqd`** - Disponibilidade: 🖥️ Desktop - Comando: `composer require --dev` - Descrição: Adiciona pacote como dev-dependency. - Exemplo: `creqd phpunit/phpunit` - **`cdump`** - Disponibilidade: 🖥️ Desktop - Comando: `composer dump-autoload` - Descrição: Regenera o autoload do Composer. - Exemplo: `cdump` - **`crun`** - Disponibilidade: 🖥️ Desktop - Comando: `composer run` - Descrição: Executa um script do composer.json. - Exemplo: `crun dev` ### Node / JavaScript - **`ni`** - Disponibilidade: 🌐 Ambos - Comando: `npm install` - Descrição: Instala todas as dependências do package.json. - Exemplo: `ni` - **`nid`** - Disponibilidade: 🌐 Ambos - Comando: `npm install --save-dev` - Descrição: Instala pacote como dependência de desenvolvimento. - Exemplo: `nid typescript` - **`nr`** - Disponibilidade: 🌐 Ambos - Comando: `npm run` - Descrição: Executa script do package.json. - Exemplo: `nr build` - **`nrd`** - Disponibilidade: 🌐 Ambos - Comando: `npm run dev` - Descrição: Inicia o servidor de desenvolvimento. - Exemplo: `nrd` - **`nrb`** - Disponibilidade: 🌐 Ambos - Comando: `npm run build` - Descrição: Executa o build de produção. - Exemplo: `nrb` - **`nrt`** - Disponibilidade: 🌐 Ambos - Comando: `npm run test` - Descrição: Executa os testes. - Exemplo: `nrt` - **`nx`** - Disponibilidade: 🌐 Ambos - Comando: `npx` - Descrição: Executa pacote Node sem instalar globalmente. - Exemplo: `nx create-react-app my-app` - **`bi`** - Disponibilidade: 🌐 Ambos - Comando: `bun install` - Descrição: Instala dependências com Bun. - Exemplo: `bi` - **`br`** - Disponibilidade: 🌐 Ambos - Comando: `bun run` - Descrição: Executa script com Bun. - Exemplo: `br dev` - **`brd`** - Disponibilidade: 🌐 Ambos - Comando: `bun run dev` - Descrição: Inicia o dev server com Bun. - Exemplo: `brd` - **`brb`** - Disponibilidade: 🌐 Ambos - Comando: `bun run build` - Descrição: Build de produção com Bun. - Exemplo: `brb` - **`bx`** - Disponibilidade: 🌐 Ambos - Comando: `bunx` - Descrição: Executa pacote sem instalar, via Bun. - Exemplo: `bx cowsay hello` - **`pn`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm` - Descrição: Atalho para o pnpm. - Exemplo: `pn add axios` - **`pni`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm install` - Descrição: Instala dependências com pnpm. - Exemplo: `pni` - **`pnr`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm run` - Descrição: Executa script do package.json via pnpm. - Exemplo: `pnr build` - **`pnd`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm run dev` - Descrição: Inicia o dev server com pnpm. - Exemplo: `pnd` - **`pnb`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm run build` - Descrição: Build de produção com pnpm. - Exemplo: `pnb` - **`pnt`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm run test` - Descrição: Executa os testes com pnpm. - Exemplo: `pnt` - **`pnx`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm dlx` - Descrição: Executa pacote sem instalar via pnpm. - Exemplo: `pnx create-next-app` - **`pnadd`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm add` - Descrição: Adiciona dependência com pnpm. - Exemplo: `pnadd axios` - **`pnaddd`** - Disponibilidade: 🖥️ Desktop - Comando: `pnpm add -D` - Descrição: Adiciona dev-dependency com pnpm. - Exemplo: `pnaddd vitest` ### Python / uv - **`py`** - Disponibilidade: 🖥️ Desktop - Comando: `python3` - Descrição: Atalho para Python 3. - Exemplo: `py main.py` - **`pyv`** - Disponibilidade: 🖥️ Desktop - Comando: `python3 --version` - Descrição: Exibe a versão ativa do Python. - Exemplo: `pyv` - **`uvi`** - Disponibilidade: 🖥️ Desktop - Comando: `uv pip install` - Descrição: Instala pacote Python com uv. - Exemplo: `uvi requests` - **`uvs`** - Disponibilidade: 🖥️ Desktop - Comando: `uv run` - Descrição: Executa script com uv. - Exemplo: `uvs main.py` - **`venv`** - Disponibilidade: 🖥️ Desktop - Comando: `python3 -m venv .venv && source .venv/bin/activate` - Descrição: Cria e ativa virtualenv local. - Exemplo: `venv` - **`activate`** - Disponibilidade: 🖥️ Desktop - Comando: `source .venv/bin/activate` - Descrição: Ativa o virtualenv local do diretório. - Exemplo: `activate` ### Ruby / rbenv - **`rbv`** - Disponibilidade: 🖥️ Desktop - Comando: `rbenv versions` - Descrição: Lista versões do Ruby instaladas via rbenv. - Exemplo: `rbv` - **`rblocal`** - Disponibilidade: 🖥️ Desktop - Comando: `rbenv local` - Descrição: Define versão do Ruby para o diretório atual. - Exemplo: `rblocal 3.2.0` - **`rbglobal`** - Disponibilidade: 🖥️ Desktop - Comando: `rbenv global` - Descrição: Define a versão global do Ruby. - Exemplo: `rbglobal 3.2.0` - **`be`** - Disponibilidade: 🖥️ Desktop - Comando: `bundle exec` - Descrição: Executa comando no contexto do Bundler. - Exemplo: `be rails s` - **`binstall`** - Disponibilidade: 🖥️ Desktop - Comando: `bundle install` - Descrição: Instala gems do Gemfile. - Exemplo: `binstall` - **`bupdate`** - Disponibilidade: 🖥️ Desktop - Comando: `bundle update` - Descrição: Atualiza gems do Gemfile. - Exemplo: `bupdate` ### Rust / Cargo - **`cb`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo build` - Descrição: Compila o projeto Rust em modo debug. - Exemplo: `cb` - **`cbr`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo build --release` - Descrição: Compila em modo release otimizado. - Exemplo: `cbr` - **`crun2`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo run` - Descrição: Compila e executa o projeto Rust. - Exemplo: `crun2` - **`ct`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo test` - Descrição: Executa os testes do projeto. - Exemplo: `ct` - **`ccheck`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo check` - Descrição: Verifica erros sem gerar o binário. - Exemplo: `ccheck` - **`clippy`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo clippy` - Descrição: Executa o linter do Rust. - Exemplo: `clippy` - **`cfmt`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo fmt` - Descrição: Formata o código com rustfmt. - Exemplo: `cfmt` - **`cadd`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo add` - Descrição: Adiciona dependência ao projeto Rust. - Exemplo: `cadd serde` - **`crem`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo remove` - Descrição: Remove dependência do projeto Rust. - Exemplo: `crem serde` - **`cupdate`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo update` - Descrição: Atualiza todas as dependências do Cargo.lock. - Exemplo: `cupdate` - **`cdoc`** - Disponibilidade: 🖥️ Desktop - Comando: `cargo doc --open` - Descrição: Gera e abre a documentação do projeto no browser. - Exemplo: `cdoc` ### Go - **`gobuild`** - Disponibilidade: 🖥️ Desktop - Comando: `go build ./...` - Descrição: Compila todos os pacotes do projeto Go. - Exemplo: `gobuild` - **`gorun`** - Disponibilidade: 🖥️ Desktop - Comando: `go run .` - Descrição: Executa o pacote principal. - Exemplo: `gorun` - **`gotest`** - Disponibilidade: 🖥️ Desktop - Comando: `go test ./...` - Descrição: Executa todos os testes do projeto. - Exemplo: `gotest` - **`gomod`** - Disponibilidade: 🖥️ Desktop - Comando: `go mod tidy` - Descrição: Remove dependências não utilizadas do go.mod. - Exemplo: `gomod` - **`govet`** - Disponibilidade: 🖥️ Desktop - Comando: `go vet ./...` - Descrição: Verifica problemas comuns no código Go. - Exemplo: `govet` - **`gofmt`** - Disponibilidade: 🖥️ Desktop - Comando: `gofmt -w .` - Descrição: Formata todos os arquivos Go do diretório. - Exemplo: `gofmt` - **`goget`** - Disponibilidade: 🖥️ Desktop - Comando: `go get` - Descrição: Adiciona dependência ao projeto Go. - Exemplo: `goget github.com/gin-gonic/gin` - **`goclean`** - Disponibilidade: 🖥️ Desktop - Comando: `go clean -cache` - Descrição: Remove o cache de build do Go. - Exemplo: `goclean` - **`gocover`** - Disponibilidade: 🖥️ Desktop - Comando: `go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out` - Descrição: Cobertura HTML. - Exemplo: `gocover` - **`gowork`** - Disponibilidade: 🖥️ Desktop - Comando: `go work` - Descrição: Gerencia workspaces Go. - Exemplo: `gowork use ./pkg` ## DevOps & Sistema - **`anp`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-playbook` - Descrição: Executa um playbook. - Exemplo: `anp site.yml -i hosts` - **`ani`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-inventory --list` - Descrição: Exibe o inventário em formato JSON. - Exemplo: `ani` - **`anping`** - Disponibilidade: 🌐 Ambos - Comando: `ansible all -m ping` - Descrição: Testa conectividade com todos os hosts. - Exemplo: `anping` - **`anv`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-vault` - Descrição: Gerencia arquivos criptografados com Vault. - Exemplo: `anv edit secrets.yml` - **`anve`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-vault encrypt` - Descrição: Criptografa um arquivo com Vault. - Exemplo: `anve secrets.yml` - **`anvd`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-vault decrypt` - Descrição: Descriptografa um arquivo com Vault. - Exemplo: `anvd secrets.yml` - **`anvr`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-vault rekey` - Descrição: Recriptografa com nova senha. - Exemplo: `anvr secrets.yml` - **`ancheck`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-playbook --check` - Descrição: Simula execução do playbook sem aplicar mudanças. - Exemplo: `ancheck site.yml` - **`andiff`** - Disponibilidade: 🌐 Ambos - Comando: `ansible-playbook --check --diff` - Descrição: Simula e exibe diff das mudanças que seriam aplicadas. - Exemplo: `andiff site.yml` - **`anfacts`** - Disponibilidade: 🌐 Ambos - Comando: `ansible all -m setup` - Descrição: Coleta facts de todos os hosts do inventário. - Exemplo: `anfacts` ### Cron & Agendamento - **`cronb`** - Disponibilidade: 🌐 Ambos - Comando: `cronboard` - Descrição: Abre o dashboard TUI do Cronboard para gerenciar tarefas cron. - Exemplo: `cronb` - **`cronl`** - Disponibilidade: 🌐 Ambos - Comando: `crontab -l` - Descrição: Lista as tarefas cron do usuário atual. - Exemplo: `cronl` - **`crone`** - Disponibilidade: 🌐 Ambos - Comando: `crontab -e` - Descrição: Edita as tarefas cron do usuário atual. - Exemplo: `crone` - **`cronr`** - Disponibilidade: 🌐 Ambos - Comando: `crontab -r` - Descrição: Remove todas as tarefas cron do usuário atual (CUIDADO). - Exemplo: `cronr` ### Monitoramento & Processos - **`topc`** - Disponibilidade: 🌐 Ambos - Comando: `top -o cpu` (macOS) / `top -bn1 | head -20` (Linux) - Descrição: Monitora processos ordenados por uso de CPU. - Exemplo: `topc` - **`topm`** - Disponibilidade: 🖥️ Desktop macOS - Comando: `top -o mem` - Descrição: Monitora processos ordenados por uso de memória. - Exemplo: `topm` - **`psg`** - Disponibilidade: 🌐 Ambos - Comando: `ps aux | grep` - Descrição: Busca processos por nome. - Exemplo: `psg nginx` - **`df`** - Disponibilidade: 🌐 Ambos - Comando: `df -h` - Descrição: Uso de disco com tamanhos legíveis. - Exemplo: `df` - **`meminfo`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `free -h` - Descrição: Exibe uso de memória RAM e swap. - Exemplo: `meminfo` - **`diskinfo`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `df -h` - Descrição: Exibe uso de disco de todas as partições. - Exemplo: `diskinfo` - **`cpuinfo`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `lscpu` - Descrição: Exibe informações detalhadas sobre a CPU. - Exemplo: `cpuinfo` - **`sysinfo`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `hostnamectl` - Descrição: Exibe informações do sistema operacional e hostname. - Exemplo: `sysinfo` ### Systemd (Linux) - **`sstatus`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl status` - Descrição: Exibe o status de um serviço. - Exemplo: `sstatus nginx` - **`sstart`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl start` - Descrição: Inicia um serviço. - Exemplo: `sstart nginx` - **`sstop`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl stop` - Descrição: Para um serviço. - Exemplo: `sstop nginx` - **`srestart`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl restart` - Descrição: Reinicia um serviço. - Exemplo: `srestart nginx` - **`senable`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl enable` - Descrição: Habilita um serviço para iniciar no boot. - Exemplo: `senable nginx` - **`sdisable`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo systemctl disable` - Descrição: Desabilita um serviço no boot. - Exemplo: `sdisable nginx` - **`slogs`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo journalctl -u` - Descrição: Exibe logs de um serviço específico. - Exemplo: `slogs nginx` - **`syslog`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `sudo journalctl -f` - Descrição: Segue o log do sistema em tempo real. - Exemplo: `syslog` ## Rede & Web - **`myip`** - Disponibilidade: 🌐 Ambos - Comando: `curl -s ifconfig.me` - Descrição: Exibe o IP público da máquina. - Exemplo: `myip` - **`localip`** - Disponibilidade: 🌐 Ambos - Comando: `ipconfig getifaddr en0` (macOS) / `hostname -I...` (Linux) - Descrição: Exibe o IP local principal da máquina. - Exemplo: `localip` - **`ports`** - Disponibilidade: 🌐 Ambos - Comando: `lsof -iTCP -sTCP:LISTEN -n -P` (macOS) / `ss -tulnp` (Linux) - Descrição: Lista todas as portas em escuta. - Exemplo: `ports` - **`wholistening`** - Disponibilidade: ☁️ Server / 🖥️ Desktop Linux - Comando: `ss -tulnp` - Descrição: Alias alternativo para listar portas em escuta. - Exemplo: `wholistening` - **`flush`** - Disponibilidade: 🌐 Ambos - Comando: `dscacheutil...` (macOS) / `sudo systemd-resolve...` (Linux) - Descrição: Limpa o cache de DNS. - Exemplo: `flush` ### cURL / HTTP - **`get`** - Disponibilidade: 🌐 Ambos - Comando: `curl -s` - Descrição: GET request simples. - Exemplo: `get https://api.github.com` - **`post`** - Disponibilidade: 🌐 Ambos - Comando: `curl -s -X POST -H 'Content-Type: application/json'` - Descrição: POST JSON simples. - Exemplo: `post url -d '{"key":"val"}'` - **`headers`** - Disponibilidade: 🌐 Ambos - Comando: `curl -sI` - Descrição: Exibe apenas os headers HTTP da resposta. - Exemplo: `headers google.com` - **`httpcode`** - Disponibilidade: 🌐 Ambos - Comando: `curl -o /dev/null -s -w '%{http_code}\n'` - Descrição: Exibe somente o código HTTP da resposta. - Exemplo: `httpcode google.com` - **`timing`** - Disponibilidade: 🌐 Ambos - Comando: `curl -o /dev/null -s -w 'dns:%{time_namelookup}s...'` - Descrição: Latência detalhada. - Exemplo: `timing google.com` ### JSON / YAML - **`jpp`** - Disponibilidade: 🌐 Ambos - Comando: `python3 -m json.tool` - Descrição: Formata e valida JSON. - Exemplo: `cat data.json | jpp` - **`jsonf`** - Disponibilidade: 🌐 Ambos - Comando: `jq .` - Descrição: Formata JSON com cores via jq. - Exemplo: `cat data.json | jsonf` ### Segurança & Certs - **`certinfo`** - Disponibilidade: 🌐 Ambos - Comando: `openssl x509 -text -noout -in` - Descrição: Exibe detalhes de um certificado .pem. - Exemplo: `certinfo cert.pem` - **`certexpiry`** - Disponibilidade: 🌐 Ambos - Comando: `openssl x509 -enddate -noout -in` - Descrição: Exibe a data de expiração de um certificado. - Exemplo: `certexpiry cert.pem` - **`sslcheck`** - Disponibilidade: 🌐 Ambos - Comando: `openssl s_client -connect` - Descrição: Inspeciona TLS de um host. - Exemplo: `sslcheck google.com:443` - **`genpass`** - Disponibilidade: 🌐 Ambos - Comando: `openssl rand -base64 32` - Descrição: Gera uma senha aleatória segura de 32 bytes. - Exemplo: `genpass` ### Ambiente - **`envls`** - Disponibilidade: 🌐 Ambos - Comando: `env | sort` - Descrição: Lista todas as variáveis de ambiente ordenadas. - Exemplo: `envls` - **`envg`** - Disponibilidade: 🌐 Ambos - Comando: `env | grep` - Descrição: Filtra variáveis de ambiente. - Exemplo: `envg PATH` - **`dotenv`** - Disponibilidade: 🌐 Ambos - Comando: `export $(cat .env | grep -v '^#' | xargs)` - Descrição: Carrega variáveis do arquivo .env atual. - Exemplo: `dotenv` --- ### Executáveis auxiliares do SetupVibe: referência e uso - URL: https://promovaweb.com/docs/setupvibe/referencia/executaveis - Descrição: Consulte os executáveis auxiliares distribuídos pelo SetupVibe, seus caminhos, requisitos, argumentos e orientações para uso seguro no terminal local. > Scripts executáveis auxiliares — v0.41.11 O SetupVibe mantém scripts auxiliares reutilizáveis no diretório [`bin/`](https://github.com/promovaweb/setupvibe/tree/main/bin) do repositório. Durante a instalação, as edições Desktop e Server baixam esses arquivos diretamente do repositório para `~/.setupvibe/bin` e aplicam permissão de execução. ## Local de Instalação | Arquivo fonte | Caminho instalado | Edições | | -------------------------------------------------------------------------------------- | ------------------------------ | ---------------- | | [`bin/ssh_copy_id`](https://github.com/promovaweb/setupvibe/tree/main/bin/ssh_copy_id) | `~/.setupvibe/bin/ssh_copy_id` | Desktop e Server | O alias do shell aponta para o executável instalado: ```bash alias ssh_copy_id="$HOME/.setupvibe/bin/ssh_copy_id" ``` Os instaladores baixam o arquivo de: ```text https://raw.githubusercontent.com/promovaweb/setupvibe/main/bin/ssh_copy_id ``` ## `ssh_copy_id` Copia sua chave SSH pública local para um servidor remoto usando autenticação por senha. Ele cria `~/.ssh/authorized_keys` no servidor remoto se necessário, aplica permissões seguras e evita adicionar a mesma chave duas vezes. ### Requisitos - `ssh` - `sshpass` - Uma chave SSH pública local, normalmente uma destas: - `~/.ssh/id_ed25519.pub` - `~/.ssh/id_rsa.pub` - `~/.ssh/id_ecdsa.pub` ### Uso ```bash ssh_copy_id --host HOST --user USUARIO [--pass SENHA] [--key ~/.ssh/id_ed25519.pub] [--port 22] ``` ### Argumentos | Argumento | Obrigatório | Padrão | Descrição | | -------------- | ----------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--host` | Sim | nenhum | Hostname ou IP do servidor remoto. | | `--user` | Sim | nenhum | Usuário SSH remoto. | | `--pass` | Não | prompt | Senha SSH remota. Se omitida, o script pergunta com input oculto. | | `--key` | Não | detecção automática | Arquivo de chave pública a copiar. Um caminho de chave privada sem `.pub` é aceito se o `.pub` correspondente existir. | | `--port` | Não | `22` | Porta SSH remota. | | `-h`, `--help` | Não | nenhum | Exibe ajuda de uso. | ### Exemplos Perguntar a senha com segurança: ```bash ssh_copy_id --host 192.0.2.10 --user root ``` Passar a senha inline: ```bash ssh_copy_id --host 192.0.2.10 --user root --pass 'senha' ``` Usar uma chave pública e porta SSH customizadas: ```bash ssh_copy_id --host 192.0.2.10 --user deploy --key ~/.ssh/id_rsa.pub --port 2222 ``` ### Comportamento - Usa `sshpass -e` para passar a senha pela variável de ambiente `SSHPASS` em vez de argumento direto do comando `sshpass`. - Usa `StrictHostKeyChecking=accept-new` para aceitar uma nova chave de host na primeira conexão, mas continuar rejeitando chaves alteradas. - Desabilita autenticação por chave pública na etapa de cópia para garantir o uso da senha informada. - Define permissões remotas `700` para `~/.ssh` e `600` para `authorized_keys`. - Verifica correspondência exata antes de adicionar a chave, então execuções repetidas são idempotentes. ### Notas de Segurança Prefira omitir `--pass` para que o script pergunte a senha com input oculto. Passar `--pass` inline é útil para automações, mas pode expor a senha no histórico do shell ou em metadados de processo dependendo do ambiente. ### Solução de Problemas | Mensagem | Causa | Correção | | ----------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `sshpass não encontrado` | `sshpass` não está instalado ou não está no `PATH`. | Execute o SetupVibe novamente ou instale `sshpass`. | | `chave pública SSH não encontrada` | Nenhuma chave pública suportada foi encontrada. | Crie uma com `ssh-keygen -t ed25519 -C 'email@exemplo.com'` ou use `--key`. | | `informe --pass ou execute em um terminal interativo` | O comando foi executado sem `--pass` em contexto não interativo. | Passe `--pass` ou execute em um terminal interativo. | | `Falha ao adicionar a chave SSH` | Login SSH falhou ou o comando remoto falhou. | Verifique host, usuário, senha, porta e se autenticação por senha está habilitada no servidor. | ## Adicionando Novos Executáveis Ao adicionar outro executável auxiliar: 1. Adicione o script em `bin/`. 2. Mantenha o shebang na linha 1. 3. Adicione cabeçalho com nome, autor, versão, descrição e exemplos de uso. 4. Marque como executável com `chmod +x`. 5. Adicione uma referência direta via `safe_download` em `desktop.sh` e `server.sh`. 6. Adicione ou atualize aliases em `conf/zshrc-*.zsh`. 7. Documente o script neste arquivo e atualize a referência de aliases se necessário. 8. Valide com `bash -n`, `zsh -n` e `markdownlint`. ### Usar o Specsfy com Astro: guia do especialista técnico - URL: https://promovaweb.com/docs/specsfy/astro - Descrição: Como o especialista specsfy-specialist-astro soma escolhas de renderização, ilhas e performance do Astro ao fluxo do Specsfy, sem reescrever a spec. `$specsfy-specialist-astro` acrescenta ao fluxo do Specsfy as escolhas de renderização, conteúdo, ilhas e performance próprias de um site Astro. A skill usa a versão e a configuração do projeto, sem presumir o adapter ou o modo de saída. ## Confirmar a detecção O catálogo detecta Astro pela dependência `astro` em `package.json` ou pelos arquivos `astro.config.mjs` e `astro.config.ts`. Descubra no projeto a versão, o output mode, o adapter, as integrações e as fontes de conteúdo. ## Instalação ```bash specsfy skills detect --project . npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-astro --agent universal --copy --full-depth ``` Quando todas as recomendações exibidas forem aplicáveis, `--detected` instala o framework e os especialistas em uma única execução. Confira depois se `specsfy-specialist-astro` aparece no catálogo instalado: ```bash specsfy install --project . --detected ``` ## Aplicar na spec 1. Conduza a ideia até a spec conforme o [primeiro projeto](/docs/specsfy/comecando). 2. Peça ao agente para usar `$specsfy-specialist-astro` na fatia ativa. 3. Classifique cada rota afetada como estática, sob demanda ou endpoint. 4. Mantenha HTML estático por padrão e escolha uma diretiva `client:*` somente para a interação que precisa de hidratação. 5. Modele conteúdo com schemas e relações explícitas. Defina cache, headers, imagens e metadados quando aplicáveis. 6. Crie testes derivados do Gherkin para rotas, conteúdo inválido e comportamento hidratado. 7. Execute `astro check`, a suíte do projeto, o build de produção e o preview no runtime do adapter disponível no projeto. ## O que o especialista acrescenta - escolha explícita entre static, on-demand, island e endpoint. - proteção contra transporte de dados sensíveis para ilhas. - validação de slugs, relações e conteúdo. - semântica, canonical, sitemap e dados estruturados. - inspeção de payload cliente, Core Web Vitals e compatibilidade do adapter. ## Resultado esperado A fatia preserva a fonte normativa Specsfy e torna observáveis a estratégia de renderização, a hidratação necessária, os contratos de conteúdo e a validação no runtime alvo. ## Limites - não escolha SSR sem necessidade de sessão, personalização ou frescor. - não suponha APIs de Node em adapters edge. - não valide apenas no servidor de desenvolvimento. - confirme scripts e comandos disponíveis no `package.json`. Não use esse especialista para prescrever um adapter ou modo de saída sem evidência. A versão, o adapter, os scripts e as integrações são comprovados pelos manifests, lockfiles e pela configuração do projeto consumidor. ### Como atualizar uma especificação já definida no Specsfy - URL: https://promovaweb.com/docs/specsfy/atualizar-spec - Descrição: Como a skill specsfy-update-spec incorpora uma mudança posterior na mesma spec.md e reabre apenas as etapas afetadas pela alteração feita agora mesmo. Quando uma entrega já definida precisar mudar, use `specsfy-update-spec`. A skill incorpora a nova instrução na mesma `spec.md` e reconcilia as partes afetadas sem exigir que você escolha atos ou gates manualmente. ## Descreva o que mudou Durante ou depois da implementação, identifique a `spec.md` e diga diretamente o que deve mudar. Você pode adicionar, remover, corrigir ou mudar uma regra. A skill usará esse arquivo para encontrar os requisitos, testes e tarefas afetados: ```text Use $specsfy-update-spec em specs//0001-pagina-boas-vindas/spec.md: esqueci de pedir que o nome tenha no máximo 80 caracteres. ``` Se a spec já estiver clara na conversa, você pode usar uma instrução natural sem mencionar atos ou gates: ```text Quero adicionar uma regra à especificação atual. Remova o comportamento de visitante. Corrija o que acontece quando o nome estiver vazio. Mude esta entrega para exigir autenticação. ``` A skill preserva a instrução, compara-a com a spec existente e informa primeiro o resultado prático. Você não precisa escolher manualmente qual gate ou etapa reabrir. ## O que acontece | Tipo de mudança | Tratamento | | --- | --- | | correção interna sem efeito observável | mantém a spec | | esclarecimento sem novo significado | ajusta o texto e preserva os gates | | mudança de comportamento ou aceite | atualiza a spec e reabre o Ato I | | mudança de solução, tarefas ou testes | atualiza a spec e reabre o Ato II | | capacidade independente | encaminha para backlog ou nova spec | | definição material ausente | pergunta e retoma depois da resposta | Quando a mudança pertence à spec atual, a skill atualiza o arquivo, encaminha as etapas invalidadas e retorna à implementação somente depois das novas provas: ```text mudança posterior → update-spec → validate ou tasks → TDD/BDD → implement ↘ backlog, se faltar uma definição ``` Testes e tarefas que continuam válidos são preservados. Provas dependentes do comportamento anterior voltam a ficar pendentes. A implementação só é retomada depois de existir novo RED válido e os gates necessários voltarem a `Passed`. ## Resultado esperado - a nova instrução está incorporada à única `spec.md` normativa. - IDs e definições ainda válidos foram preservados. - os gates afetados foram reabertos. - validação, tarefas e testes foram reconciliados. - a etapa que recebeu o pedido foi retomada automaticamente. ## Limites - não cria `change-request.md`, `plan.md`, `tasks.md` ou outra fonte paralela. - não transforma uma capacidade independente em aumento silencioso de escopo. - não inventa uma definição material. - não altera código antes de atualizar a spec e preparar novo RED. - handoffs automáticos não autorizam deploy, publicação ou ação destrutiva. ## Quando usar outra skill - criar a primeira versão de uma spec. - capturar uma ideia ainda superficial. - editar código quando a spec continua correta. Depois da atualização, consulte [`specsfy-progress`](/docs/specsfy/skills/progress) para conferir o estado geral. A spec atualizada permanece como única fonte normativa do projeto. ### Backlog do Specsfy para refinar uma entrada antes da spec - URL: https://promovaweb.com/docs/specsfy/backlog - Descrição: Como o Backlog organiza e aprofunda uma entrada por perguntas guiadas, sem ainda definir tarefas nem autorizar alterações no código do projeto atual. O backlog recebe uma ideia que merece conversa, mas ainda não está pronta para virar especificação. Nele, você esclarece o problema, o público afetado e o efeito esperado sem definir arquitetura, tarefas ou código nessa etapa. Para apenas guardar um texto sem responder perguntas, use a [Inbox](/docs/specsfy/inbox). Depois que uma entrada for promovida, a `spec.md` passa a governar o comportamento, os gates, as tarefas e as evidências da entrega. ## Estrutura ```text specs/ ├── inbox/ │ └── 2026-07-28-143205-ideia.md ├── backlog/ │ └── 0001-ideia.md └── specs/ └── 0001-feature/ ├── spec.md └── research/ ``` O item começa leve e amadurece até produto, desenvolvimento e testes compreenderem o comportamento esperado. Ele não contém tarefas ou gates e nunca autoriza implementação diretamente. ## Organização do backlog ```text Produto └── Épico └── Funcionalidade ├── História ou requisito ├── Regra ├── Item técnico └── Melhoria ``` O épico representa um objetivo amplo. A funcionalidade delimita uma capacidade. Histórias e requisitos representam entregas menores e verificáveis. Regras, itens técnicos e melhorias também pertencem ao backlog quando tornam o comportamento ou sua operação possível. Nem toda ideia precisa começar com a hierarquia completa. Use `A esclarecer` no lugar de inventar uma relação. ## Anatomia de um item Logo abaixo do título, mantenha as metainformações em uma tabela, não em lista: | Metainformação | Valor | | --- | --- | | ID | `BACKLOG-0001` | | Status | `Captured` | | Produto | A esclarecer | | Épico | A esclarecer | | Funcionalidade | A esclarecer | | Tipo | A esclarecer | | Prioridade | Não priorizado | | Criado em | data ISO | | Spec promovida | Nenhuma | Conforme a conversa avança, o item pode registrar estas informações sem preencher campos que ainda não foram esclarecidos: - título, tipo e prioridade. - produto, épico e funcionalidade. - contexto do problema. - objetivo ou história do usuário. - comportamento esperado. - regras de negócio. - condições de aceite. - segurança, privacidade, desempenho, volume e auditoria. - dependências. - situações de erro e exceções. - dentro e fora de escopo. A profundidade é adaptativa. Uma alteração simples exige menos detalhes, enquanto autenticação, pagamentos, permissões, privacidade e processamento assíncrono exigem análise cuidadosa. O melhor item não é o mais longo, mas aquele que reduz a ambiguidade e permite verificar a entrega. ### Captura mínima e conversa Ao receber a ideia, `$specsfy-02-backlog` reaproveita a descrição original e confirma: - problema percebido. - pessoa afetada ou beneficiada. - resultado ou valor esperado. - contexto suficiente para distinguir a ideia. Se algo estiver ausente, vago, contraditório ou ambíguo, a skill pergunta uma lacuna relevante por vez e reavalia após cada resposta. Ela não usa questionário fixo, não repete o que já foi explicado e não persiste placeholders nesses campos. Se a pessoa não souber responder, explicita a lacuna sem inventar. Esse é o mínimo de captura, não um refinamento profundo. Hierarquia, prioridade, regras detalhadas, aceite e solução técnica podem ser refinados depois. ### Duplicatas e referências Antes de criar, a skill pesquisa termos da ideia em `specs/backlog/*.md`, `specs//*/spec.md` e `docs/**/*.md`. Ela separa possível duplicata de backlog relacionado, spec relacionada ou documentação útil. Uma possível duplicata exige confirmar se o item existente será atualizado ou se há uma diferença real. Fontes úteis ficam em `Referências relacionadas`, com o caminho e o tipo de relação. Elas não substituem o que você declarou. ## Padrões recorrentes | Capacidade | Informações que o backlog deve tornar objetivas | | --- | --- | | Autenticação | cadastro, tentativas, sessão, mensagens e autorização | | Notificações | propriedade, leitura, ações em lote e isolamento | | Permissões | perfil, operação, alvo, validação e auditoria | | PIX/pagamentos | estados, idempotência, webhook e dados sensíveis | | Exportação | filtros, autorização, volume, fila e expiração | Use a representação que reduz ambiguidade. Fluxos numerados ajudam em integrações, matrizes ajudam em permissões e cenários demonstram resultados e erros. Um requisito funcional descreve o que o sistema faz. Um requisito não funcional define condições mensuráveis de qualidade e operação. Troque “o sistema deve ser rápido” por um limite de latência, volume e ambiente verificáveis. ## Ordenar o backlog Mantenha o backlog realmente ordenado para que a próxima oportunidade fique visível no arquivo para todos os responsáveis. Compare os itens pelos fatores abaixo: 1. valor para a pessoa e para o negócio. 2. exposição de segurança, privacidade e operação. 3. dependências e entregas desbloqueadas. 4. urgência. 5. esforço. 6. pontos ainda desconhecidos. Prioridade é relativa. Classificar tudo como alta não cria uma ordem. Autenticação e autorização podem preceder melhorias visuais, assim como uma infraestrutura de notificações pode preceder os eventos que dependem dela. A tabela abaixo mostra como uma ordem real diferencia o que deve ser retomado primeiro do que pode esperar: | Ordem | Prioridade | Tipo | Item | Objetivo | | --- | --- | --- | --- | --- | | 1 | Alta | Épico | Gestão de usuários | Administrar acesso | | 2 | Alta | História | Realizar login | Acessar áreas privadas | | 3 | Alta | Regra | Controlar permissões | Restringir operações por perfil | | 4 | Média | Técnico | Notificações em fila | Evitar lentidão nas requisições | | 5 | Baixa | Melhoria | Preferências de notificação | Escolher canais | Cada linha aponta para um item próprio. Por exemplo, “realizar login” deve esclarecer cadastro ativo, comparação de e-mail, proteção da senha, tentativas inválidas, sessão, permissões, resultados de sucesso e falha e o que ficou fora do escopo. “Criar uma tela de login” não cobre esse comportamento. ## Fluxo ```text input → inbox → backlog → spec ``` 1. Use `$specsfy-02-backlog` quando a entrada ainda for geral. A skill pesquisa material relacionado, conversa até a captura mínima ficar clara e produz `specs/backlog/-.md`. A mesma skill pode organizar, priorizar e refinar o item progressivamente. 2. A mesma skill apresenta uma pergunta numerada por rodada e produz um brief enquanto houver escolhas materiais abertas. 3. Use `$specsfy-03-specify` somente quando houver intenção explícita de promover o material. A fonte normativa é criada em `specs//-/spec.md`. 4. Depois da promoção, mantenha o backlog como proveniência, marque-o `Promoted` e registre o caminho da spec. Ao concluir, a skill informa qual etapa assumirá o trabalho e executa automaticamente o avanço ou o retorno. A conversa mostra o nome da skill, o motivo da troca e o resultado esperado. Você acompanha essa transição sem repetir comandos, e nenhuma troca autoriza implementação. Backlog e spec possuem sequências independentes. `BACKLOG-0004` pode originar `SPEC-0002`, mas os números não precisam coincidir e não indicam prioridade. ## Estados do backlog | Estado | Significado | | --- | --- | | `Captured` | ideia preservada com contexto mínimo | | `Refining` | conversa ou pesquisa leve em andamento | | `Ready for specification` | contexto suficiente para criar a especificação | | `Promoted` | spec derivada criada e referenciada | ## Quando está refinado O item está pronto para especificação quando a equipe consegue responder às perguntas abaixo sem consultar suposições fora do arquivo: - Qual problema será resolvido e qual público será beneficiado? - Qual evento inicia o comportamento e qual resultado será produzido? - Qual papel pode executar a operação? - Quais regras, erros e exceções precisam ser respeitados? - Como verificar objetivamente o resultado? - Há implicações de segurança, privacidade, desempenho ou volume? - O que ficou fora da entrega? - Quais dependências ou definições continuam pendentes? O agente identifica lacunas e pergunta uma por rodada. Definições que alteram segurança, escopo, arquitetura ou experiência não são inventadas silenciosamente. Esse diagnóstico prepara a spec, mas ainda não autoriza desenvolvimento. ## Limites - Não implementar diretamente de um backlog. - Não exigir arquitetura, Gherkin ou plano técnico durante a captura inicial. - Não apagar a formulação original ao resumir. - Não promover automaticamente uma ideia. - Não tratar o backlog como fonte normativa depois da promoção. ## Próximo passo Quando o item estiver claro o bastante para uma conversa aprofundada, use [`specsfy-02-backlog`](/docs/specsfy/skills/backlog). A promoção para `spec.md` só acontece depois de refinamento suficiente e de uma instrução explícita para criar a especificação. ### CLI e TUI do Specsfy: comandos e dashboard no terminal - URL: https://promovaweb.com/docs/specsfy/cli - Descrição: Comandos do executável specsfy, atualização automática, dashboard no terminal e integração com o progresso das specs do projeto em andamento hoje. O executável `specsfy` instala e atualiza as skills, mostra o progresso, executa os testes detectados e abre um dashboard no terminal. Instale primeiro o CLI e o framework seguindo o [guia de instalação](/docs/specsfy/instalacao). Este guia assume que `specsfy --version` já responde no terminal e que o bootstrap foi executado no projeto consumidor. Para conduzir a primeira fatia depois do bootstrap, siga o [guia do primeiro projeto](/docs/specsfy/comecando). Para seleção técnica, automação e reabertura de gates, consulte o [uso avançado](/docs/specsfy/uso-avancado). Para consultar cada argumento, opção, efeito e formato de saída, use a [referência dos comandos](/docs/specsfy/referencia-cli). Os templates de ideia, backlog, spec, tarefas e informações permanentes ficam em `.specsfy/templates/`. Customizações com o mesmo nome ficam em `.specsfy/templates/custom/` e têm precedência sobre os arquivos padrão. Ao criar uma especificação, `specsfy-03-specify` renderiza o template resolvido em `specs/draft/-/spec.md`. O exemplo demonstra os três atos e as 18 seções para agentes, testes e diagnóstico do CLI, mas não governa uma feature. O cabeçalho renderizado é uma tabela Markdown de duas colunas, `Campo` e `Valor`, com um metadado por linha. ## Instalar e gerenciar skills Para preparar um projeto novo, o comando `install` pode publicar as bases e todos os especialistas detectados em uma única execução: ```bash specsfy doctor --project . specsfy install --project . --detected ``` Quando você já souber quais stacks precisam de orientação especializada, repita `--specialist` para instalar somente o conjunto indicado: ```bash specsfy install --project . \ --specialist specsfy-specialist-laravel \ --specialist specsfy-specialist-postgres ``` Depois da instalação inicial, os subcomandos de `skills` permitem listar o catálogo, detectar recomendações, adicionar uma skill ou atualizar as versões gerenciadas: ```bash specsfy skills list specsfy skills detect --project . npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-laravel --agent universal --copy --full-depth specsfy update --project . ``` ## Atualização automática Ao abrir `specsfy` ou `specsfy tui` em um terminal interativo, o CLI verifica a versão realmente publicada no registro npm. As tags semânticas de [`cli/`](https://github.com/promovaweb/specsfy/tree/main/cli/) servem para registrar a origem da versão quando o GitHub responde. O cache e as configurações globais ficam em `~/.specsfy/cli.json`, com permissão restrita ao usuário e intervalo padrão de 24 horas entre consultas. Quando existe uma versão publicada superior, o CLI apresenta a versão atual e pergunta se deve atualizar. Recusar abre o dashboard normalmente. Em uma instalação npm, aceitar executa `npm install --global @promovaweb/specsfy@latest`. Em um executável avulso, o CLI baixa `get.specsfy.dev`, valida a versão e substitui o arquivo atual. O processo encerra e a versão nova entra em uso na próxima abertura. Depois de recusar ou de uma tentativa que falhou, a mesma versão fica adiada até o próximo intervalo configurado. Isso evita a repetição do aviso a cada abertura. O comando explícito `specsfy upgrade` consulta novamente e ignora o adiamento. Se o executável for um symlink, o arquivo apontado é atualizado e o symlink continua disponível no `PATH`. O arquivo global separa `settings`, incluindo habilitação e intervalo da consulta, de `cache`, que registra horário, versão publicada, tag, commit, ETags, versão adiada e erro recente. Chaves desconhecidas são preservadas. A aplicação continua abrindo quando a rede está indisponível, a resposta é inválida ou a escrita falha, e o aviso fica para a próxima consulta. Como o monorepo é privado, o catálogo e a proveniência das tags são consultados com `GH_TOKEN`, `GITHUB_TOKEN` ou, na ausência dessas variáveis, com a sessão de `gh auth token`. O token não é copiado para `~/.specsfy/cli.json`. Em uma instalação global gerenciada pelo npm, `upgrade` atualiza o próprio CLI. Abra o comando novamente para conferir a nova versão: ```bash specsfy upgrade specsfy --version ``` Não confunda os dois fluxos: `specsfy update --project .` atualiza as skills do projeto, `specsfy upgrade` atualiza o programa global. O comando anterior `specsfy skills update` permanece como alias compatível. Se você instalou o executável Node com `curl -fL get.specsfy.dev`, a oferta automática também atualiza esse arquivo diretamente. O download só substitui o executável depois de confirmar a versão esperada. Uma falha preserva a versão atual e abre a TUI normalmente. ## Dashboard e progresso ## Ciclo de vida de specs O CLI move specs pelo ciclo `draft`, `defined`, `planned`, `in-progress`, `review` e `completed`. Ele atualiza o campo `Status` junto com a pasta: ```bash specsfy transition 0001-recuperar-senha defined --project . specsfy transition 0001-recuperar-senha planned --project . specsfy transition 0001-recuperar-senha in-progress --project . specsfy migrate --project . ``` Use `migrate` apenas para converter o layout anterior `specs/specs/`. Para recalibrar a execução, registre Effort e sua justificativa diretamente na fonte normativa: ```bash specsfy effort 0001-recuperar-senha 7 \ --reason "Inclui migração e integração externa." --project . ``` Execute sem argumentos dentro do projeto consumidor para abrir a TUI: ```bash specsfy ``` `specsfy tui --project PATH` abre explicitamente outro projeto. O dashboard é organizado em seis abas: - **Home**, com as estatísticas consolidadas. - **Backlogs**, com lista navegável na coluna esquerda e preview Markdown formatado na coluna direita. - **Specs**, com a tabela e o progresso de cada especificação. - **Testes**, com execução do runner detectado, resumo da última execução e saída detalhada em subabas separadas. - **Skills**, com catálogo tabular, painel de detalhes e uma prévia explícita das instalações e remoções pendentes. - **Sobre**, com a versão e a finalidade do CLI. No dashboard, os cards e as tabelas combinam estes dados para mostrar tanto o estado global quanto a situação de cada spec: - quantidade total e concluída de specs. - tarefas `T...` concluídas, pendentes e totais. - todos os itens de checklist concluídos, pendentes e totais. - gates aprovados por spec. - porcentagem e barra de progresso global. - porcentagem e barra de progresso de cada spec. ### Percurso visual #### Home: visão consolidada ![Dashboard Home](/docs/specsfy/cli/cli-dash.png) A Home reúne o total de specs, o avanço das tarefas e checklists e a porcentagem global. O diretório selecionado aparece no topo e o rodapé confirma quantas specs estão completas e se a atualização automática está ativa. #### Backlogs: lista e leitura lado a lado ![Backlogs](/docs/specsfy/cli/cli-backlogs.png) A aba Backlogs mantém a seleção na coluna esquerda e renderiza o Markdown do item na direita. Assim é possível conferir metainformação, status e conteúdo sem abandonar o dashboard. #### Specs: gates, tarefas e progresso ![Specs](/docs/specsfy/cli/cli-specs.png) A aba Specs compara status, gates, tarefas, checklists e porcentagem por especificação. A linha destacada pode ser aberta com `Espaço` para consultar a spec completa em um modal Markdown. Use `Esc` ou o botão **Fechar Esc** para voltar à lista. Dentro do modal, `Tab` e `Shift+Tab` alternam apenas entre a leitura e o fechamento, sem levar o foco aos controles que estão atrás da visualização. #### Skills: planejar antes de aplicar ![Skills](/docs/specsfy/cli/cli-skills.png) A aba Skills combina busca, filtros, plano, categoria e estado com o painel de detalhes da seleção. Os totais acima da tabela mostram instalações e remoções planejadas. Nada muda no projeto até a ação **Aplicar**. ## Testes do projeto Em um projeto Laravel com Pest, `specsfy test` detecta o runner e transmite a saída do teste no mesmo terminal: ```bash specsfy test --project . ``` O CLI detecta `artisan` e `pestphp/pest`, chama `php artisan test` diretamente na raiz selecionada, transmite a saída e preserva o exit code do runner. Ele não aceita uma string de shell arbitrária. Na aba **Testes**, `Executar testes ^X` inicia a mesma execução. A subaba **Resumo** mostra resultado, runner, comando, projeto, duração, exit code e os totais emitidos pelo Pest. A subaba **Testes** mantém a saída completa e rolável. Quando o projeto fornece um relatório Pest estruturado, cada falha é apresentada com nome do teste, arquivo, linha e mensagem. O progresso usa todos os checkboxes Markdown de `specs//*/spec.md`. Tarefas com ID `T...` também ganham estatística própria. Quando uma spec não possui checkboxes, os três gates são usados como projeção de fallback. A TUI calcula fingerprints dos backlogs, das specs e do `skills-lock.json`. Ela atualiza automaticamente as listas, previews, cards e seleção de skills quando esses arquivos mudam. O intervalo padrão é 0,75 segundo e pode ser configurado por projeto: ```bash specsfy config show --project . specsfy config set --project . --watch-interval 0.5 ``` O rodapé apresenta os atalhos disponíveis na aba atual. Use essas combinações para trocar de tela ou aplicar uma ação sem retirar o foco do terminal: - `Ctrl+Q`: sair. - `Ctrl+U`: atualizar. - `Ctrl+D`: detectar recomendações. - `Ctrl+B`: selecionar todas as skills do framework. - `Ctrl+E`: alternar o plano da skill destacada. - `Ctrl+V`: marcar os resultados visíveis. - `Ctrl+L`: limpar os resultados visíveis. - `Ctrl+A`: aplicar a seleção. - `Ctrl+R`: atualizar todas as skills Specsfy instaladas. - `Ctrl+T`, `Ctrl+N`, `Ctrl+C`: abrir os filtros Todas, Instaladas e Recomendadas. - `Ctrl+H`, `Ctrl+G`, `Ctrl+S`, `Ctrl+K`, `Ctrl+O`: abrir Home, Backlogs, Specs, Skills e Sobre. - `Ctrl+J`: abrir Testes. - `Ctrl+X`: executar os testes do projeto selecionado. Os atalhos são globais e aparecem nos próprios rótulos dos botões. A interface inteira também aceita: - `Tab` e `Shift+Tab` para percorrer controles. - setas para navegar listas e tabelas. - `Enter` ou `Espaço` para alternar o plano da skill destacada. - `Esc` para fechar o modal da spec, limpar a busca ou voltar à Home. - mouse para abas, listas, preview, filtros e botões. O campo de projeto entra em edição com `Enter` ou com um clique. A confirmação recarrega backlogs, specs e skills a partir do caminho informado. Ao fechar uma spec, a TUI restaura a seleção e o foco da lista que a abriu. Você pode continuar com as setas, abrir outra linha ou trocar de aba sem precisar pressionar `Tab` até encontrar um controle válido. A TUI usa a paleta escura oficial do Specsfy. O turquesa identifica o foco e a aba ativa, o violeta marca a linha selecionada e as ações primárias usam fundo petróleo com texto claro. Cada estado também mantém um rótulo visível, por isso continua compreensível quando a paleta configurada no terminal altera as cores. Na aba Skills, cada linha separa `Plano`, `Skill`, `Categoria` e `Estado`. O plano usa os valores `Instalar`, `Manter`, `Remover` e `Ignorar`. Ele expressa o que acontecerá sem executar a mudança imediatamente. O painel lateral mostra o identificador completo, a descrição, a recomendação e o plano da linha destacada. A alteração só ocorre ao acionar `Aplicar`. A configuração vive em `/.specsfy/config.json`. Valores desconhecidos adicionados pelo usuário são preservados quando o CLI atualiza uma opção. Para automação, `specsfy progress` pode emitir texto, JSON ou uma sequência de snapshots. Assim, outro processo recebe uma nova leitura somente quando o conteúdo das specs muda: ```bash specsfy progress --project . specsfy progress --project . --json specsfy progress --project . --watch specsfy progress --project . --watch --interval 0.5 --json ``` O JSON contém um objeto `summary` e a coleção `specs`. Com `--watch`, um novo snapshot é emitido somente quando o conteúdo das specs muda, o que evita leituras repetidas em uma integração. A instalação das bases e dos especialistas continua disponível na TUI e nos comandos de `skills`. O leitor mantém compatibilidade com `specs/-/spec.md` para projetos existentes, mas toda spec nova usa `specs/draft/`. Itens em `specs/backlog/` não entram na porcentagem de entrega. ## Justificativa de tamanho Comandos, dashboard e atalhos operam os mesmos arquivos do projeto. Reuni-los nesta página permite comparar a ação no terminal com o resultado mostrado na TUI, sem duplicar explicações sobre progresso e proteção de alterações locais. ## Segurança e reversibilidade - O destino padrão é `/.agents/skills`. - As regras centrais ficam em `/.specsfy/Spec.md`. - Template e exemplo ficam em `/.specsfy/templates/Spec.md` e `/.specsfy/examples/Spec.md`. - Templates personalizados ficam em `/.specsfy/templates/custom/`, fora do lock e protegidos até mesmo de operações com `--force`. - `AGENTS.md` e `CLAUDE.md` recebem somente blocos delimitados e atualizáveis. - O registro fica em `/.specsfy/skills-lock.json`. - Cada skill gerenciada registra um fingerprint de conteúdo no lock. - Uma execução repetida sobre a mesma versão não altera arquivos nem o lock. - Uma skill gerenciada e intacta pode receber uma versão nova sem `--force`. - Alterações locais fazem a atualização e a remoção serem recusadas. Use `--force` somente depois de confirmar que a versão customizada pode ser descartada. - Downloads dos catálogos usam checkout temporário, e `skills add` faz a instalação no projeto. - `specsfy skills remove ` remove somente o nome explícito e preserva conteúdo local divergente. - O CLI recusa a raiz reconhecida do workspace `promovaweb/specsfy`. ### Primeiro projeto completo com o Specsfy, passo a passo - URL: https://promovaweb.com/docs/specsfy/comecando - Descrição: Tutorial guiado que acompanha uma entrega pequena do início ao fim, da captura da ideia até a implementação validada, passando por cada skill base. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | primeira fatia de trabalho em um projeto consumidor | | Autoridade | metodologia executável de `skills/` | ## O que você vai construir Este tutorial acompanha uma página de boas-vindas em um projeto Laravel que já usa Pest. A rota recebe um nome e mostra uma saudação. Quando o nome não for informado, a página usa `visitante`. Você verá como uma ideia chega à implementação sem dividir a fonte normativa entre `plan.md`, `tasks.md` e outros arquivos. O exemplo mostra cada skill separadamente para facilitar a consulta, embora o agente consiga fazer as transições na mesma conversa. O tutorial depende de três condições verificáveis. Confirme a instalação, abra o agente na raiz do projeto consumidor e rode a suíte Pest existente: - o CLI e o framework foram instalados conforme o [guia de instalação](/docs/specsfy/instalacao). - o agente está aberto na raiz do projeto consumidor. - o repositório possui um runner Pest funcional. ## Escolha o diretório do projeto Você pode começar a conversa na raiz de um Hub e indicar o subdiretório do projeto. Instale e execute o setup com o mesmo caminho: ```bash specsfy install --project apps/portal specsfy doctor --project apps/portal ``` Depois, informe `apps/portal` ao `$specsfy-setup`. O agente cria contexto, specs, testes e código apenas nesse diretório. Ele não usa a raiz Git do Hub como destino por dedução. Antes de cada skill seguinte, o framework executa o setup novamente para verificar essa consistência, reutilizando o caminho já confirmado na conversa. ## Capture uma entrada Use `$specsfy-01-inbox` para guardar a formulação original em `specs/inbox/`. A captura não inicia perguntas nem altera o código: ```text Use $specsfy-01-inbox para capturar: criar uma página /boas-vindas que cumprimente o visitante pelo nome. ``` A skill grava um arquivo com data, horário e slug em `specs/inbox/`. O relato deve apontar um caminho semelhante a este: ```text specs/inbox/2026-07-28-143205-pagina-boas-vindas.md ``` Essa captura preserva o texto recebido e registra inferências separadamente. Ela ainda não cria backlog, spec, tarefas ou código. ## Refine a proposta no backlog Quando a ideia merecer refinamento, envie o arquivo para `$specsfy-02-backlog`. A skill lê a captura preservada, procura relações e cria um item numerado: ```text Use $specsfy-02-backlog para refinar specs/inbox/2026-07-28-143205-pagina-boas-vindas.md ``` Você também pode fornecer o texto diretamente. A skill procura material relacionado, esclarece somente o necessário para o backlog e grava um item numerado: ```text specs/backlog/0001-pagina-boas-vindas.md ``` O backlog organiza uma possibilidade de entrega, mas não autoriza alteração no código. Essa separação permite comparar e priorizar ideias antes de criar uma especificação normativa. Use `$specsfy-02-backlog` para aprofundar o item. A conversa pergunta uma lacuna aplicável por vez e retorna um brief: ```text Use $specsfy-02-backlog em specs/backlog/0001-pagina-boas-vindas.md ``` O agente reaproveita o conteúdo existente e pergunta uma lacuna relevante por vez. Neste exemplo, a resposta padrão muda o comportamento visível da página: ```text Agente: O que deve aparecer quando nenhum nome for informado? Você: Olá, visitante! ``` O refinamento do backlog produz um brief na conversa. Por padrão, ele não cria uma segunda fonte normativa nem modifica o backlog. ## Crie a especificação única Depois de resolver as dúvidas materiais, promova o backlog com `$specsfy-03-specify`: ```text Use $specsfy-03-specify para promover specs/backlog/0001-pagina-boas-vindas.md ``` A skill cria o diretório numerado e mantém a fonte normativa neste caminho: ```text specs//0001-pagina-boas-vindas/spec.md ``` Abra esse arquivo e confira se o problema, as pessoas afetadas, os requisitos, os limites e os cenários BDD representam a conversa. O Gherkin permanece na spec como referência legível. O Specsfy não cria uma suíte `.feature` separada. ## Comprove a definição Use `$specsfy-04-validate` para auditar a spec. A skill informa a localização de cada falha e só aprova o Definition Gate quando a definição estiver completa: ```text Use $specsfy-04-validate em specs//0001-pagina-boas-vindas/spec.md ``` Uma definição pronta termina a validação com estes dois sinais: ```text READY Definition Gate: Passed ``` `READY` confirma que a spec possui as informações necessárias para planejar. O estado ainda não afirma que a página existe. Se houver contradição ou uma escolha importante em aberto, a validação retorna à skill responsável antes de aprovar o gate. ## Organize as tarefas Use `$specsfy-05-tasks` para manter o plano e as tarefas dentro da mesma `spec.md`. O arquivo deve mostrar os requisitos cobertos e a dependência entre o teste em RED e cada tarefa de produção: ```text Use $specsfy-05-tasks em specs//0001-pagina-boas-vindas/spec.md ``` A skill separa testes, código, documentação e trabalho operacional, registra dependências e liga cada tarefa aos requisitos correspondentes. Ela não cria `tasks.md` nem altera o código de produção. ## Prove que o teste detecta a ausência da página Use `$specsfy-06-tdd-bdd` no modo de preparação: ```text Use $specsfy-06-tdd-bdd em specs//0001-pagina-boas-vindas/spec.md para preparar o TDD. ``` Como o projeto do exemplo usa PHP, a skill cria testes Pest derivados dos cenários BDD. Cada caso executável recebe seu marcador `SPECSFY:` junto à definição. A feature inteira e cada história ou requisito aplicável precisam ter, no mínimo, três casos distintos: caminho feliz, variação importante e falha ou limite material. Execute o teste focal e confirme o RED pelo motivo esperado. Uma rota ausente prova que o teste detecta o comportamento ainda não implementado. Erro de sintaxe, fixture quebrada ou dependência ausente precisa ser corrigido antes de o RED ser aceito. Depois que as tarefas e seus predecessores TDD estiverem coerentes, o `Plan Gate` pode chegar a `Passed`. ## Implemente e valide Com os gates de definição e plano aprovados, use `$specsfy-07-implement`: ```text Use $specsfy-07-implement em specs//0001-pagina-boas-vindas/spec.md ``` A implementação percorre cada tarefa em `RED → GREEN → REFACTOR`. Para uma tarefa de código, a skill exige um predecessor TDD com RED registrado, cria a menor mudança capaz de deixar o teste verde e executa a regressão aplicável. Os comandos, os resultados e os IDs cobertos entram como evidência na spec. Depois de cada tarefa de código, o agente chama `$specsfy-documentator`. Essa skill reconstrói a documentação técnica em `docs/` a partir do sistema existente e executa o modo `--check`. O fluxo só retoma a implementação quando a documentação representar o código atual. No fechamento, a implementação verifica aceite, regressão, rastreabilidade, documentação e Definition of Done. Uma entrega comprovada termina com: ```text Delivery Gate: Passed Status: Reviewing ``` ## Incorpore uma mudança posterior Imagine que, depois da primeira entrega, o nome precise aceitar no máximo 80 caracteres. Use `$specsfy-update-spec` na spec existente: ```text Use $specsfy-update-spec em specs//0001-pagina-boas-vindas/spec.md: o nome deve ter no máximo 80 caracteres. ``` Essa skill preserva a nova instrução, atualiza a `spec.md` e invalida somente as provas afetadas. Como o limite muda comportamento, o fluxo reabre desde o Ato I, percorre validação, tarefas e TDD/BDD, e só então retoma `$specsfy-07-implement`. A skill de atualização não altera código de produção automaticamente. Uma alteração restrita ao plano técnico reabre os Atos II e III. Uma correção editorial comprovadamente sem mudança de significado preserva os gates. Em todos os casos, o histórico continua na mesma spec. ## Consulte o estado final Use `$specsfy-progress` para projetar o estado sem editar arquivos: ```text Use $specsfy-progress para mostrar o resultado final. ``` O relatório mostra specs, gates, tarefas, checklists, pendências e o próximo trabalho disponível. Você também pode consultar o mesmo estado pelo CLI: ```bash specsfy progress --project . specsfy progress --project . --json specsfy tui --project . ``` Depois do aceite final, a entrega pronta aparece como `Complete` em `completed/`, com os três gates aprovados e sem pendência documental. Capturas em `specs/inbox/` e itens em `specs/backlog/` não entram nesse cálculo. ## Converse sobre a próxima escolha — `$specsfy-interviewer` Quando uma lacuna puder alterar escopo, plano, execução ou aceite, use `$specsfy-interviewer` na mesma spec. Ele registra respostas confirmadas e recalibra Effort, sem aprovar gates nem substituir a skill da etapa. ## Continue na mesma conversa Você não precisa enviar cada exemplo deste tutorial manualmente. Ao autorizar a jornada completa, uma skill anuncia o handoff, carrega a próxima responsabilidade e retoma a etapa anterior quando necessário. A transição automática não amplia permissões para deploy, publicação, instalação de especialista ou ação destrutiva. Agora aprofunde os [comandos do CLI e da TUI](/docs/specsfy/cli), consulte as [informações permanentes do projeto](/docs/specsfy/contexto-do-projeto) ou conheça o [uso avançado](/docs/specsfy/uso-avancado). ## Justificativa de tamanho O tutorial acompanha uma única entrega desde a captura até o estado `Complete`. Manter o exemplo em uma página permite conferir como cada arquivo e gate é produzido pelo resultado da etapa anterior. ## Manutenção deste guia Atualize esta página quando a sequência dos atos, a responsabilidade de uma skill base, os gates, os estados ou os caminhos canônicos mudarem. Use a metodologia executável em [`skills/`](https://github.com/promovaweb/specsfy/tree/main/skills/) como fonte e preserve `specs//-/spec.md` como a única fonte normativa de cada fatia no projeto consumidor. ### Informações permanentes do projeto mantidas pelo Specsfy - URL: https://promovaweb.com/docs/specsfy/contexto-do-projeto - Descrição: Como o Specsfy separa a descrição durável do sistema (PROJECT.md, STACK.md, RULES.md, DATABASE.md) das especificações de cada mudança pontual feita. O Specsfy separa a descrição durável do sistema das especificações de cada mudança. O arquivo `PROJECT.md` explica a finalidade da aplicação, enquanto cinco documentos em `.specsfy/` registram a stack, as instruções confirmadas, a persistência observada no código, os pacotes instalados e o perfil de interação do setup. As regras macro de interface ficam em `DESIGNSYSTEM.MD`, na raiz do projeto, e seguem um ciclo próprio com a skill especialista de design system. Execute `$specsfy-setup` depois de instalar o framework. Depois disso, o framework a executa obrigatoriamente antes de iniciar cada skill, inclusive em transições automáticas, para verificar e reconciliar os contextos iniciais e os blocos reservados de agentes. Na mesma conversa, a raiz confirmada é reaproveitada sem perguntar de novo. A skill detecta Laravel, Next.js e Astro pelos manifests e sugere o modelo correspondente. `$specsfy-documentator` acrescenta e atualiza `PACKAGES.md`. Juntas, as skills mantêm esta estrutura: ```text / ├── PROJECT.md ├── DESIGNSYSTEM.MD ├── docs/ │ └── packages/ │ ├── README.md │ └── -.md └── .specsfy/ ├── STACK.md ├── RULES.md ├── DATABASE.md ├── PACKAGES.md ├── USER-PROFILE.md └── SPECKIT.md # somente quando GitHub Spec Kit for detectado ``` O setup também reserva blocos delimitados para as diretrizes do Specsfy em `AGENTS.md` e `CLAUDE.md`. Conteúdo fora desses blocos pertence ao usuário e é preservado. A referência publicável das diretrizes vive em [`specsfy-setup`](https://github.com/promovaweb/specsfy/tree/main/skills/specsfy-setup/). | Arquivo | Conteúdo | Skill mantenedora | | --- | --- | --- | | `PROJECT.md` | finalidade e capacidades | `$specsfy-setup` cria o modelo | | `.specsfy/STACK.md` | stack e evidências | `$specsfy-aux-stack` | | `.specsfy/RULES.md` | regras explícitas confirmadas | `$specsfy-aux-rules` | | `.specsfy/DATABASE.md` | persistência e relações | `$specsfy-aux-database` | | `.specsfy/PACKAGES.md` | pacotes npm e Composer com finalidade | `$specsfy-documentator` | | `docs/packages/README.md` | índice dos pacotes Composer diretos e links para fichas de uso | `$specsfy-specialist-laravel-package-manager` | | `docs/packages/-.md` | instalação, configuração, uso local e testes do pacote | `$specsfy-specialist-laravel-package-manager` | | `.specsfy/USER-PROFILE.md` | nível de conhecimento, respostas confirmadas e fontes do setup | `$specsfy-setup` | | `.specsfy/SPECKIT.md` | constituição e fontes preservadas do GitHub Spec Kit | `$specsfy-setup` | | `DESIGNSYSTEM.MD` | defaults comuns de interface, CRUD, dashboards, estados e exceções | `$specsfy-setup` cria, `$specsfy-specialist-design-system` mantém | Os modelos ficam em `.specsfy/templates/Project.md`, `Stack.md`, `Rules.md`, `Database.md` e `UserProfile.md`, junto dos demais templates do framework. Para personalizar um deles, mantenha o mesmo nome em `.specsfy/templates/custom/`, essa cópia tem precedência e não é alterada pelo CLI. Durante o setup, `.specsfy/USER-PROFILE.md` guarda o nível de conhecimento confirmado e as respostas já fornecidas. O agente consulta esse arquivo, a conversa e as fontes do projeto antes de perguntar. Assuntos já respondidos ficam fora da próxima rodada, perguntas técnicas recebem mais contexto para iniciantes e podem usar versões, arquitetura e integrações diretamente para pessoas experientes. O setup também verifica como você administra cada informação principal do produto. Quando a jornada precisa de cadastro e manutenção, ele confirma as ações de criar, consultar, editar e apagar. Informações somente de leitura, históricos imutáveis e conteúdos mantidos por integrações não recebem um CRUD sem necessidade. Se o código e os documentos não deixarem essa necessidade clara, o setup pergunta antes de registrar a cobertura. Para cada tela de uso recorrente, o setup identifica o caminho pelos menus do sistema. Ele registra item, destino, permissão e comportamento responsivo em `INTERFACE.md`. Rotas técnicas e etapas abertas apenas por redirecionamento podem ficar fora do menu. Quando o destino ou a presença do link estiverem abertos, você escolhe em uma pergunta numerada antes da continuação. Ao terminar a preparação dos contextos e especialistas, o setup executa `$specsfy-documentator`. Essa etapa reconstrói a documentação técnica de todo o sistema existente em `docs/` e atualiza `.specsfy/PACKAGES.md`, mesmo quando a execução não começou por uma alteração recente no código. Use `$specsfy-data-discovery` antes de implementar quando ainda faltar explicar o que o produto precisa guardar, quem consulta cada informação e quando ela deixa de ser necessária. A skill registra as respostas confirmadas em uma seção própria de `DATABASE.md`, separada do que o código detectar depois. ## Projeto existente com GitHub Spec Kit O setup reconhece o GitHub Spec Kit pela constituição em `.specify/memory/constitution.md`. Quando ela existe, a skill lê a constituição e todos os arquivos regulares dentro de `specs/`, inclusive specs, planos, tarefas, contratos e anexos. O resultado aparece em `.specsfy/SPECKIT.md` como uma lista de caminhos, títulos, tipos e fingerprints SHA-256. Abra as fontes listadas antes de trabalhar na feature correspondente. A constituição continua governando o projeto e os artefatos do GitHub Spec Kit permanecem nos caminhos originais. O setup não escreve, move, converte ou remove arquivos de `.specify/` e `specs/`. Você pode acrescentar notas próprias fora do bloco `specsfy:speckit` em `.specsfy/SPECKIT.md`. Uma nova execução atualiza somente o bloco delimitado. Se a constituição divergir de `.specsfy/RULES.md`, preserve os dois textos e resolva a divergência antes de alterar a feature. Execute `$specsfy-aux-stack` após alterar frameworks, runtimes, ferramentas estruturais ou persistência. Execute `$specsfy-aux-database` sempre que criar ou alterar banco, schema, tabela, coleção, model persistente, campo, relação, índice ou migration. Use `$specsfy-aux-rules` para formular e acrescentar uma regra confirmada sem duplicar ou apagar regras anteriores. ## Monitoramento durante mudanças O monitor é executado pelas skills no início e no fim de uma mudança. Ele lê os arquivos staged, unstaged e untracked do Git para descobrir qual documento precisa ser revisto, mas não permanece como daemon em segundo plano: ```bash node .agents/skills/specsfy-setup/scripts/monitor_context.mjs \ --project . --check ``` | Sinal observado | Obrigação | | --- | --- | | manifest, lockfile ou configuração | `$specsfy-aux-stack` revisa `STACK.md` | | manifest ou lockfile npm/Composer | `$specsfy-documentator` reconstrói `PACKAGES.md` e `docs/` | | schema, model ou migration | `$specsfy-aux-database` revisa `DATABASE.md` | | código da aplicação | revisar `PROJECT.md` | | aplicação ou persistência | `$specsfy-documentator` reconstrói `docs/` e `PACKAGES.md` | | instrução ou convenção | `$specsfy-aux-rules` revisa `RULES.md` | `PENDING` impede a conclusão da tarefa e do Delivery Gate. Quando uma mudança de aplicação não altera história, finalidade, capacidades ou limites, registre essa avaliação na evidência da tarefa e execute novamente com `--acknowledge-project-no-change`. Para uma revisão de regras sem regra nova, use `--acknowledge-rules-no-change` somente depois de registrar a justificativa. Veja a topologia e o `--check` no guia de [documentação técnica do sistema](/docs/specsfy/documentacao-do-sistema). ## Preservação e atualização - O setup cria um arquivo de informações somente quando ele ainda não existe. Isso inclui `DESIGNSYSTEM.MD` e `.specsfy/USER-PROFILE.md`: os templates iniciais apresentam padrões comuns de interface, CRUD, dashboard e registro da conversa. Os arquivos continuam humanos e qualquer conteúdo existente é preservado. - As auxiliares atualizam apenas blocos detectados delimitados e preservam seções humanas. - Uma nova varredura nunca autoriza remover silenciosamente uma definição humana. - `DATABASE.md` usa tabelas Markdown para facilitar mapeamento e comparação. - `PACKAGES.md` deriva de manifests, lockfiles e metadados locais, preservando texto humano fora do bloco gerado. - Valores sensíveis não são lidos nem registrados. Cite somente nomes seguros de variáveis e caminhos das fontes. O estado implementado é comprovado pelas fontes do próprio projeto. Os manifests e lockfiles mostram a stack, enquanto schemas e migrations mostram a persistência. Os documentos resumem essas evidências e as definições humanas que precisam permanecer entre mudanças. Eles não substituem a `spec.md`, não registram gates e nunca devem copiar segredos, valores de `.env` ou registros de produção. ### Créditos e fontes oficiais confirmadas do Specsfy! - URL: https://promovaweb.com/docs/specsfy/creditos - Descrição: Autoria pública do Specsfy e fontes usadas para confirmar contribuições, identidade visual e componentes relacionados ao projeto oficial mantido. Esta página registra a autoria pública do Specsfy e aponta as fontes usadas para confirmar contribuições, identidade visual e componentes relacionados. O histórico Git preserva a autoria detalhada de cada mudança. ## Projeto e manutenção Specsfy é um projeto da [Promovaweb](https://promovaweb.com), criado e mantido por **Luiz Eduardo Oliveira Fonseca** com a comunidade. O contato público do projeto é [contato@promovaweb.com](mailto:contato@promovaweb.com). ## Comunidade Contribuições em documentação, código, testes e pesquisa fazem parte da evolução do projeto. O histórico do monorepo preserva a autoria de cada arquivo e commit, por isso este guia não mantém uma lista manual que ficaria desatualizada. ## Identidade Logos, cores, tipografia, voz, acessibilidade e regras de aplicação pertencem ao diretório [`brand/`](https://github.com/promovaweb/specsfy/tree/main/brand/). Use os ativos e orientações desse diretório ao apresentar o projeto. ## Componentes relacionados O instalador do Specsfy delega a instalação de skills ao projeto [`vercel-labs/skills`](https://github.com/vercel-labs/skills). O CLI pode usar o executável `skills` ou o fallback por `npx`, conforme documentado no [guia de instalação](/docs/specsfy/instalacao). ## Inspirações e fontes O Specsfy desenvolve um contrato executável próprio e reconhece estas referências como inspiração: - [GitHub Spec Kit](https://github.github.com/spec-kit/): aplicação de specification-driven development em etapas próximas ao código. - [OpenSpec](https://openspec.dev/): especificações e mudanças mantidas no repositório como um acordo leve entre o desenvolvedor responsável e o agente. - [*Categorias*, de Aristóteles](https://classics.mit.edu/Aristotle/categories.html): referência filosófica para classificar objetos, atributos, relações e estados antes de formular afirmações sobre eles. As referências não são dependências do Specsfy e não tornam os métodos equivalentes. As skills, os templates, os validadores e os testes deste repositório continuam sendo as fontes do comportamento executável. ## Como contribuir Localize primeiro o diretório responsável no [quadro dos módulos](https://github.com/promovaweb/specsfy/blob/main/docs/develop/modules.md), leia as instruções locais e preserve os limites de cada repositório Git. A documentação oficial fica neste repositório. O comportamento executável e os testes permanecem no módulo que implementa cada recurso. O histórico e os arquivos de licença de cada repositório comprovam autoria e licenciamento. Quando uma licença não estiver declarada, não presuma seus termos. A identidade oficial do Specsfy permanece em `brand/`. ### Deploy de aplicações com Specsfy, Ansible e Docker Swarm - URL: https://promovaweb.com/docs/specsfy/deploy - Descrição: Aprenda a preparar o SEMVER, publicar uma imagem imutável e coordenar Ansible e Docker Swarm com convergência observada e rollback planejado e testado. Deploy não começa no servidor. Ele começa quando a entrega recebe um número que acompanha o código, a imagem e o manifesto até o ambiente de destino. O Specsfy usa um arquivo chamado `SEMVER` na raiz do projeto para manter essa identidade. As skills de Docker, Docker Swarm, Ansible e engenharia de entrega consultam o mesmo valor. Assim, você consegue responder qual código foi compilado, qual imagem chegou ao registry e qual versão está ativa no cluster. Este capítulo acompanha o percurso completo. A aplicação sai de uma mudança validada, vira uma imagem imutável, passa pela preparação do servidor e chega ao Docker Swarm com um caminho conhecido de rollback. ## O arquivo SEMVER `SEMVER` contém uma única linha com a versão preparada. Você pode abrir o arquivo antes do deploy e comparar esse valor com a imagem que será publicada: ```text 1.4.0 ``` O formato segue `MAJOR.MINOR.PATCH`. Cada parte comunica um tipo diferente de mudança e impede que uma correção pareça uma quebra de compatibilidade: - aumente `PATCH` para uma correção compatível, como `1.4.0` para `1.4.1`. - aumente `MINOR` para uma capacidade nova e compatível, como `1.4.1` para `1.5.0`. - aumente `MAJOR` quando a interface pública deixa de ser compatível, como `1.5.0` para `2.0.0`. A skill `$specsfy-specialist-versioning` analisa o alcance da entrega, propõe o incremento e explica a consequência. Durante a preparação autorizada, ela atualiza o arquivo. Publicar imagem, criar tag, abrir uma GitHub Release ou alterar um servidor continua dependendo de autorização explícita. Se o projeto ainda não tiver o arquivo, informe a versão inicial: ```bash node .agents/skills/specsfy-specialist-versioning/scripts/semver.mjs \ init --initial 1.0.0 --project . ``` O mesmo utilitário permite consultar a versão antes de qualquer alteração e incrementá-la depois que o alcance da entrega estiver confirmado: ```bash node .agents/skills/specsfy-specialist-versioning/scripts/semver.mjs \ current --project . node .agents/skills/specsfy-specialist-versioning/scripts/semver.mjs \ bump patch --project . ``` O caminho pode mudar conforme a biblioteca de skills do agente. O contrato permanece o mesmo: `SEMVER` fica na raiz do projeto do usuário. ## Uma identidade, vários pontos de conferência A versão preparada precisa aparecer nos artefatos que representam a entrega: | Ponto | Exemplo para a versão `1.4.0` | | --- | --- | | Fonte local | `SEMVER` contém `1.4.0` | | Changelog | seção da versão `1.4.0` | | Imagem | `registry.example/app:1.4.0` | | Anotação OCI | `org.opencontainers.image.version=1.4.0` | | Manifesto | serviço aponta para `1.4.0` ou para seu digest | | Git | tag `v1.4.0` | | GitHub | release `v1.4.0` | O commit também pode gerar uma tag de imagem, como `git-a1b2c3d`. Depois da publicação, o digest `sha256:...` identifica o conteúdo exato promovido. O número explica a evolução para pessoas. O digest garante que todos os nodes baixem os mesmos bytes. ```mermaid flowchart TD P[Pedido em linguagem natural] --> D[specsfy-specialist-deploy] D --> I[Inventário dos servidores] I --> C[Teste das conexões] C --> K[Chaves públicas para deploy] D --> S[SEMVER] D --> V[Secrets no Ansible Vault] S --> T[Testes da aplicação] T --> B[Build único] B --> R[Registry e digest] R --> G[Tag Git e GitHub Release] K --> A[Ansible] V --> A R --> A A --> W[Managers e workers do Docker Swarm] W --> O[Stack, réplicas e healthchecks] ``` ## Como as skills trabalham juntas Você não precisa chamar cada especialista manualmente durante um fluxo de deploy. O catálogo declara as relações necessárias. Use `$specsfy-specialist-deploy` como entrada única para um release ou deploy completo. Ela gera a base operacional com: ```bash node .agents/skills/specsfy-specialist-deploy/scripts/scaffold.mjs \ --project . \ --image registry.example/equipe/aplicacao ``` O comando lê `SEMVER` na raiz e cria o `Dockerfile` com Open Swoole, o `compose.yaml` para desenvolvimento, o `stack.yaml` para produção e a pasta `ansible/`. Aplicações Laravel executam Octane com `--server=swoole`. O playbook cria o usuário `deploy`, instala o Docker Engine, ativa o Docker Swarm e publica a stack pelo manager. Se algum desses arquivos já existir, o gerador encerra sem sobrescrever o conteúdo. Por padrão, a stack também cria o serviço `cloudflared`. Ele participa da mesma rede overlay da aplicação e encaminha o hostname público para `http://app:8000`. A conexão parte do container para o Cloudflare, por isso o serviço Laravel não publica a porta `8000` no host de produção. ```mermaid flowchart LR C[Cloudflare] <-->|conexões de saída| T[cloudflared] T -->|rede overlay: http://app:8000| A[Laravel Octane] S[Docker Secret] -->|arquivo montado| T ``` O token do túnel entra no Ansible Vault como `vault_cloudflare_tunnel_token`. O playbook o converte no Docker Secret externo `cloudflare_tunnel_token`, montado em arquivo no container. A stack usa `--token-file`, o valor não aparece no YAML, nos argumentos do processo ou no repositório. Se você escolher Nginx, Traefik, HAProxy ou outro ingresso, diga isso ao pedir o deploy. A geração usa `--proxy external`, não cria `cloudflared` e deixa a configuração pública para a alternativa escolhida. O Cloudflare Tunnel só é omitido depois dessa escolha explícita. ### Opções do scaffold | Opção | Obrigatória | Padrão | Resultado | | --- | --- | --- | --- | | `--project ` | sim | nenhum | define a raiz que contém `SEMVER` | | `--image ` | sim | nenhum | define a imagem sem tag nem digest | | `--proxy ` | não | `cloudflare-tunnel` | aceita o padrão ou `external` | O gerador grava os arquivos no projeto indicado e encerra sem alterações se algum destino já existir. Ele também recusa `SEMVER` inválido, imagem com tag ou digest e valor de proxy desconhecido. Estes exemplos mostram as formas de uso da interface: ```bash node scripts/scaffold.mjs --project . --image registry.example/app node scripts/scaffold.mjs --project /srv/minha-app --image ghcr.io/equipe/app node scripts/scaffold.mjs --project . --image registry.example/app \ --proxy cloudflare-tunnel node scripts/scaffold.mjs --project . --image registry.example/app \ --proxy external node scripts/scaffold.mjs --project ../api --image ghcr.io/equipe/api \ --proxy external ``` Depois da geração, a skill pergunta quais senhas, tokens e chaves a aplicação consome e registra os nomes em `ansible/vault-fields.txt`. O utilitário solicita cada valor com entrada oculta. A senha do Vault vem da configuração externa ou do terminal, conforme o modo escolhido: ```bash ./deploy secrets ``` Cada resposta é adicionada automaticamente ao `vault.yml` como variável criptografada. O playbook transforma essas variáveis em Docker Secrets. A stack mantém somente os nomes externos e nunca recebe os valores protegidos. Se você repetir o comando, ele preserva os campos existentes e pergunta apenas pelos que ainda faltam. O próximo capítulo, [Servidores, conexões e comandos de deploy](/docs/specsfy/operacao-deploy), mostra a árvore criada no projeto, o cadastro de máquinas, a conta `deploy`, a sincronização das chaves públicas e os comandos curtos para outro painel do Herdr. ### Versionamento prepara a entrega `$specsfy-specialist-versioning` lê o estado atual, propõe `patch`, `minor` ou `major` e atualiza `SEMVER`. Ela compara o valor com a publicação anterior e recusa reutilizar um número já publicado. ### Docker produz a imagem `$specsfy-specialist-docker` carrega a versão quando a imagem deixa de servir apenas ao desenvolvimento local. O build recebe a tag SemVer, a tag do commit e as anotações OCI. A mesma imagem serve HTTP, filas, scheduler ou outros processos, com comandos próprios. A imagem é compilada uma vez. Staging e produção recebem o mesmo digest. Não há um novo build por ambiente. ### Ansible prepara os hosts `$specsfy-specialist-ansible` confere `SEMVER`, imagem e manifestos no preflight. Depois, prepara o Debian, autentica no registry, instala os arquivos versionados e valida a stack antes da escrita no cluster. Use `--check --diff` primeiro. Limite os hosts com `--limit` e aplique lotes com `serial` quando a alteração alcançar várias máquinas. Segredos ficam no Ansible Vault ou em um cofre externo, nunca no repositório. ### Docker Swarm aplica a versão `$specsfy-specialist-docker-swarm` recebe uma imagem já publicada. O arquivo de stack aponta para a tag conferida ou, de preferência, para o digest. O Swarm distribui as réplicas, respeita healthchecks e executa `update_config`. O retorno de `docker stack deploy` apenas confirma que o comando foi aceito. A entrega termina quando as réplicas convergem e os sinais da aplicação permanecem saudáveis. ## Sequência de uma entrega ### 1. Prepare a versão Revise a mudança concluída, escolha o incremento e atualize o changelog junto com `SEMVER`. Confirme que a versão é superior à tag mais recente. ```bash VERSION=$(tr -d '\n' < SEMVER) git tag --list "v${VERSION}" ``` Esse comando consulta o Git sem criar a tag. Uma linha vazia confirma que a versão ainda não foi usada no repositório local. ### 2. Teste e compile uma vez Rode a suíte do projeto antes do build. Passe a versão e o commit como metadados da imagem: ```bash VERSION=$(tr -d '\n' < SEMVER) COMMIT=$(git rev-parse --short=12 HEAD) docker build \ --label "org.opencontainers.image.version=${VERSION}" \ --label "org.opencontainers.image.revision=${COMMIT}" \ --tag "registry.example/app:${VERSION}" \ --tag "registry.example/app:git-${COMMIT}" \ . ``` Antes do push, confirme que a tag SemVer ainda não existe no registry. Uma tag publicada é imutável. Se for preciso corrigir o conteúdo, prepare um novo `PATCH`. ### 3. Publique o artefato antes da tag Git Com autorização explícita, envie a imagem e confira o digest retornado. Só depois crie `v1.4.0` no Git e a GitHub Release correspondente. Essa ordem evita uma release pública sem imagem disponível. Ela também mantém um caminho simples para repetir o deploy sem recompilar. ### 4. Valide os hosts e a stack O preflight do Ansible reúne as condições que precisam estar visíveis antes da escrita no cluster. A leitura deve confirmar: - acesso aos hosts e ao registry. - versão do Docker Engine e papel de cada node. - presença das redes externas necessárias. - existência dos Docker Secrets esperados. - serviço `cloudflared` na rede overlay, salvo quando outro proxy foi pedido. - token do túnel entregue por Docker Secret, sem valor literal na stack. - versão do manifesto igual ao conteúdo de `SEMVER`. - acesso ao digest publicado. - sintaxe aceita por `docker stack config`. Check mode prepara essa leitura sem implantar a stack. Depois da autorização, o playbook copia os manifestos e chama o deploy na ordem das dependências. ### 5. Observe a convergência Depois de `docker stack deploy`, acompanhe cada serviço até que a quantidade de réplicas ativas corresponda à quantidade desejada: ```bash docker stack services minha-stack docker service ps minha-stack_web docker service logs --since 10m minha-stack_web ``` Compare réplicas desejadas e ativas, healthchecks, taxa de erro, latência e consumo de recursos. Defina um prazo máximo para a convergência. Se o serviço não estabilizar, interrompa a promoção e use a versão anterior já publicada. ## Migrations durante o rollout Em um rolling update, versões antiga e nova podem executar ao mesmo tempo. A alteração do banco precisa aceitar essa convivência. Use o percurso expand/contract para separar a mudança compatível da remoção do formato anterior: 1. adicione coluna, tabela ou índice sem remover o contrato antigo. 2. publique código que entende os dois formatos. 3. migre ou preencha os dados necessários. 4. confirme que nenhum processo antigo depende do formato anterior. 5. remova o contrato antigo em outra versão. Execute a migration por uma única tarefa ou réplica. Se dois containers tentarem alterar o mesmo schema, o rollout pode parar no meio da atualização. Os serviços HTTP e os workers não devem disputar a mesma migration. ## Rollback faz parte da preparação Antes do deploy, registre a versão anterior e seu digest. O rollback de código volta a stack para essa imagem. O rollback de dados é outro procedimento: algumas migrations não podem ser desfeitas sem perda. Um plano mínimo deixa registrada a imagem que voltará ao ar, a relação com o banco e os sinais usados para interromper o rollout. Ele informa: - versão e digest anteriores. - comando para restaurar a referência da stack. - compatibilidade do banco com a versão anterior. - sinais que interrompem o rollout. - responsável por acompanhar a recuperação. No Swarm, `rollback_config` define paralelismo, intervalo, ordem e resposta a falhas. Teste esse percurso em um ambiente representativo antes da primeira execução em produção. ## Exemplo completo Considere uma aplicação na versão `1.3.2`. A entrega adiciona um endpoint sem quebrar clientes existentes. A skill propõe `minor`, então `SEMVER` passa para `1.4.0`. O pipeline testa o commit, cria `app:1.4.0` e `app:git-a1b2c3d`, publica ambas e registra o digest. A tag Git `v1.4.0` é criada depois dessa confirmação. O Ansible valida os nodes e instala o manifesto. O Swarm promove o digest com `start-first`, observa a convergência e mantém `1.3.2` disponível para rollback. Ao final, `SEMVER`, changelog, imagem, manifesto, tag Git e GitHub Release contam a mesma história. ## Antes de considerar o deploy concluído - `SEMVER` contém a versão preparada. - A versão é superior à última publicação. - Testes e build partiram do mesmo commit. - A imagem SemVer e a imagem do commit apontam para o mesmo digest. - O manifesto usa a imagem conferida. - A tag Git foi criada depois da publicação da imagem. - O preflight do Ansible passou no ambiente correto. - A stack convergiu e os sinais permaneceram saudáveis. - A versão anterior continua disponível para rollback. - O resultado foi registrado na especificação e no changelog. Para conhecer cada especialista, continue em [Skills especialistas](/docs/specsfy/especialistas). Para pipelines e automações adicionais, consulte [Uso avançado](/docs/specsfy/uso-avancado). ## Justificativa de tamanho Este capítulo mantém no mesmo percurso a versão, o artefato, a preparação dos hosts e a operação do cluster. A leitura conjunta permite conferir a passagem do `SEMVER` ao runtime sem separar etapas que dependem umas das outras. ### Design System no Specsfy: interface para aplicações web - URL: https://promovaweb.com/docs/specsfy/design-system - Descrição: Consulte o template e os defaults de interface do Specsfy para CRUD, dashboards, formulários, estados, DataGrid e Breadcrumb em aplicações. Veja o guia. `DESIGNSYSTEM.MD` é o documento do projeto consumidor que guarda as regras macro de interface. Ele orienta cada tela nova junto das regras do domínio, permissões, estados e telas relacionadas. ## Onde fica Depois de `specsfy install`, o template fica disponível em `.specsfy/templates/DESIGNSYSTEM.MD`. Ao executar o setup, o Specsfy cria `DESIGNSYSTEM.MD` na raiz somente se ele ainda não existir. O arquivo é humano, pertence ao projeto e passa a ser mantido pela skill especialista, não pelo lock do CLI. Instale a skill quando for criar ou revisar uma interface: ```bash specsfy skills install specsfy-specialist-design-system ``` Se a entrega já usa a coordenação completa de interface, instale: ```bash specsfy skills install specsfy-specialist-interface-experience ``` O catálogo resolve o especialista de design system junto das dependências de UX e UI. ## Como funciona Antes de projetar uma tela, o agente lê `DESIGNSYSTEM.MD`. Se você não informar uma direção visual, os defaults do arquivo são aplicados e registrados como direção padrão da entrega. Se você pedir algo diferente, a alteração entra em `Exceções da entrega` com alcance definido. Uma exceção de tela não muda o produto inteiro. `INTERFACE.md` continua registrando componentes, blocos, telas, props, eventos, estados e consumidores locais. Ele aponta para o design system e não repete as regras macro. ## Defaults para CRUD | Tela | Composição padrão | | --- | --- | | Lista | `PageHeader` compartilhado + resumo útil + `DataGrid` em largura total | | Detalhe | `PageHeader` compartilhado + `DetailLists` | | Criar | `PageHeader` compartilhado + seções de formulário em duas colunas responsivas | | Editar | `PageHeader` compartilhado + seções de formulário em duas colunas responsivas | O `PageHeader` é um componente único, configurado por props ou configuração para título, descrição, breadcrumb e ações. Lista, detalhe, criação e edição reutilizam essa mesma implementação, não duplicam sua marcação. A lista sempre mostra o `ID` em uma coluna visível do `DataGrid`. Cada linha inteira é o link para o detalhe, com suporte a mouse e teclado. Os botões `Editar` e `Apagar` ficam na própria linha como ações independentes e não disparam a navegação do detalhe. A permissão e a confirmação da ação destrutiva também fazem parte do contrato. Formulários usam labels visíveis acima dos campos. Quando um campo falha, ele fica com estado visual vermelho e mostra a mensagem abaixo do campo. O foco vai para o primeiro erro, os outros valores permanecem preenchidos e o resumo de erros oferece links quando há várias falhas. Toda tela também exibe um `Breadcrumb` no shell global. A trilha mantém o nome da equipe ativa visível entre o contexto inicial e o módulo, seguida do título da tela atual. Em Laravel, o padrão deve reaproveitar o `Breadcrumb` ou `Breadcrumbs` que já existir no layout, suas rotas e sua tipagem, sem criar uma segunda implementação. As linhas do `DataGrid` abrem o detalhe inteiro por clique ou teclado. Botões, checkboxes e menus da linha permanecem ações independentes, acima do link de detalhe. Criar e editar são divididos em seções. Cada seção tem contexto à esquerda e um painel de campos à direita, os campos relacionados usam duas colunas em telas largas e uma coluna no mobile. Campos longos, uploads e erros podem ocupar toda a largura. ## Defaults para dashboards e blocos Dashboards começam com `PageHeader`, período ou escopo, filtros, indicadores `KPI` contextualizados, uma visualização principal e uma lista ou `DataGrid` para investigação. Use primitives do `shadcn/ui` para controles fundamentais e blocos gratuitos do ReUI para composições comuns de CRUD e dashboard quando forem compatíveis com a stack. Registre origem, estados, acessibilidade e consumidores em `INTERFACE.md`. ## Cenários a cobrir Uma entrega de interface registra o recorte aplicável dos cenários do template: - lista com registros e lista vazia, - detalhe com status, ações e relações relevantes, - criação e edição válidas, - criação ou edição com erro de campo, - ausência de permissão, - falha de carregamento, - alteração não salva, - ação destrutiva e seu resultado. Para cada cenário, descreva pré-condição, ação, resposta, estado visual, foco, mensagem e próximo passo. A personalidade do produto vem dos dados, da linguagem, dos tokens, do ritmo e da hierarquia, não de uma decoração genérica. ## Revisão visual durante o desenvolvimento Toda tarefa que altera interface passa por uma revisão visual durante o desenvolvimento, mesmo sem pedido específico. Confira bordas, espaçamentos, margens, padding e tipografia, incluindo família, peso, tamanho, altura de linha, espaçamento entre letras, hierarquia e quebra de texto. Confira também alinhamento, largura, overflow, foco, zoom e conteúdo curto ou longo nos viewports e estados aplicáveis. Registre no item `VISUAL` da tarefa o método usado, os viewports, os estados, os ajustes feitos e o resultado. Quando a tarefa não tem interface, registre `Não aplicável` e o motivo concreto. ## Quando não usar Não use `DESIGNSYSTEM.MD` para listar props ou arquivos de um componente. Não use `INTERFACE.md` como substituto das regras macro. Não crie uma tela CRUD sem consultar a fonte, sem tratar estados ou sem registrar uma exceção ao default. ## Conferência Antes de concluir uma tela, confira: - `DESIGNSYSTEM.MD` existe e foi lido. - A tela exibe `Breadcrumb` com equipe, módulo e tela atual, em Laravel, o componente existente foi reaproveitado. - A composição corresponde à superfície CRUD. - Loading, vazio, erro, sucesso, permissão e não salvo foram cobertos quando aplicáveis. - A direção padrão ou a exceção tem alcance registrado. - `INTERFACE.md` recebeu os componentes e telas locais. ### Como o Specsfy documenta tecnicamente o sistema consumidor - URL: https://promovaweb.com/docs/specsfy/documentacao-do-sistema - Descrição: Como a skill specsfy-documentator reconstrói a visão técnica de uma aplicação consumidora em docs/, a partir da leitura direta do código real existente. `$specsfy-documentator` reconstrói a visão técnica de uma aplicação em `/docs/` e o inventário de dependências em `/.specsfy/PACKAGES.md`. Esses arquivos explicam o código e os pacotes do projeto consumidor e não se confundem com a documentação oficial da metodologia Specsfy. ## O que esta documentação explica A documentação reconstruída responde como a aplicação está montada no momento da varredura. Ela não tenta substituir a spec de uma entrega e não cria uma segunda lista de tarefas. Use a spec para entender por que uma mudança existe, quais requisitos ela atende e quais testes a comprovam. Use o diretório docs/ do projeto consumidor para entender a aplicação como um todo antes de alterar um módulo. Essa separação evita dois problemas comuns. O primeiro é usar uma documentação de arquitetura para aprovar comportamento que nunca foi definido. O segundo é copiar toda a arquitetura dentro de cada spec e deixá-la envelhecer depois da próxima mudança. A spec aponta apenas o contexto necessário para sua entrega, enquanto a documentação técnica volta a ser construída a partir do código, manifests, schemas, migrations e testes atuais. ## O que é gerado e o que é preservado A skill reconstrói somente blocos identificados pelo marcador specsfy:documentator. Texto humano escrito fora desses blocos permanece no arquivo. Isso permite acrescentar uma explicação de negócio, uma observação de suporte ou uma escolha editorial sem que a próxima varredura a apague. O conteúdo gerado descreve somente o que as fontes locais sustentam. Quando a skill encontra uma convenção, ela pode registrá-la como observação encontrada, mas não a apresenta como escolha humana confirmada. Escolhas explícitas do projeto continuam em PROJECT.md, RULES.md, na spec aplicável ou em um ADR, conforme o alcance da escolha. Execute `$specsfy-documentator` livremente para documentar um sistema legado ou atualizar sua visão técnica. Depois de cada tarefa de código concluída por `$specsfy-07-implement`, a transição para o documentador é obrigatória. A implementação só continua quando `docs/` representar o código atual. A skill lê o código completo e as fontes que descrevem a aplicação. Isso inclui os manifests, as migrations, as rotas e os testes, além das informações permanentes do projeto. Cada execução reconstrói blocos delimitados nos seguintes arquivos e preserva o texto humano externo: | Arquivo no consumidor | Conteúdo | | --- | --- | | `docs/README.md` | portal e ordem de leitura | | `docs/architecture.md` | componentes, dependências e UML Mermaid | | `docs/application.md` | módulos e implementações observadas | | `docs/database.md` | entidades, campos, relações e `erDiagram` | | `docs/flows.md` | rotas, `flowchart` e `sequenceDiagram` | | `docs/testing.md` | runners, comandos, inventário e resumo | | `docs/frontend.md` | views, páginas, componentes, React e Tailwind | | `docs/packages.md` | runtime, framework, nativos, integrados e terceiros | | `docs/packages/README.md` | índice Laravel de pacotes Composer diretos e fichas de uso | | `docs/packages/-.md` | instalação, configuração, uso local e testes de um pacote | | `docs/integrations.md` | serviços externos e nomes de configuração | | `docs/decisions.md` | escolhas explícitas e suas fontes | | `.specsfy/PACKAGES.md` | pacotes npm e Composer, versão, finalidade e fonte | ## Como ler cada documento O portal docs/README.md oferece uma ordem de leitura. architecture.md mostra a visão dos componentes e suas dependências. application.md aproxima essa visão do código, apontando módulos e implementações encontradas. database.md separa entidades, campos, relações e a origem dessas informações. flows.md mostra a passagem entre rotas, handlers, serviços e integrações para que um fluxo possa ser conferido de ponta a ponta. testing.md não promete cobertura que o repositório não mostra. Ele identifica os runners, os comandos disponíveis, arquivos de teste e o resumo observado. frontend.md só aparece com as superfícies que o projeto contém, como views, páginas, componentes, React ou Tailwind. integrations.md lista serviços e nomes seguros de configuração, jamais o valor de uma variável. decisions.md conserva escolhas que possuem fonte explícita, distinguindo uma escolha registrada de uma inferência do código. PACKAGES.md tem outro papel: tornar as dependências auditáveis. Ele lista o gerenciador, escopo, nome, versão, finalidade e fonte encontrada localmente. A finalidade pode estar ausente nos metadados. Nessa situação, o documento declara a ausência em vez de completar a coluna por suposição. ## Procedimento depois de uma mudança Depois de uma tarefa de código, a implementação chama o documentador. Você também pode executá-lo para iniciar a documentação de um sistema legado ou reconciliar uma alteração feita fora do fluxo: node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \ --project . Leia primeiro o portal, o arquivo diretamente relacionado à alteração e o resultado das seções geradas. Quando alguma relação, pacote ou integração não corresponder ao que o código demonstra, corrija a fonte que permite a inferência ou registre a limitação. Não edite o bloco gerado para alterar uma conclusão que a próxima execução voltará a produzir. Em seguida, execute o modo de conferência. Ele não escreve arquivos: compara a projeção atual com os blocos publicados. node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \ --project . --check O resultado aprovado mostra que a documentação corresponde às fontes atuais. Um resultado pendente indica que a aplicação, a persistência ou as dependências mudaram sem nova reconstrução, ou que a saída publicada foi modificada. ## Situações que impedem a conclusão O monitor de contexto e o modo check participam do Delivery Gate. A entrega não termina quando existe uma das condições abaixo: - código da aplicação alterado sem reconstruir docs/, - migration, schema ou modelo persistente alterado sem atualizar o mapa de dados e os documentos reconstruídos, - manifest ou lockfile alterado sem atualizar PACKAGES.md, - documentação gerada que não corresponde ao estado atual das fontes, - inclusão de segredo, valor de ambiente ou dado de produção em um documento. Quando a aplicação mudou mas sua finalidade, capacidades e limites não mudaram, registre essa avaliação na tarefa e use o reconhecimento permitido pelo monitor. Esse reconhecimento não dispensa a reconstrução de documentação técnica nem serve para ocultar uma mudança documental real. Em Laravel, o inventário acompanha a requisição pelas rotas, controllers e services, relaciona Eloquent e migrations e registra os testes Pest ou PHPUnit. Em projetos Node, Next.js, React ou Astro, a documentação mostra páginas, endpoints, componentes e scripts, além do runner observado no repositório. Cada pacote recebe a versão e a referência do repositório no GitHub. Quando essa origem não puder ser confirmada localmente, a documentação publica uma busca identificada como tal, em vez de inventar uma URL. O arquivo `.specsfy/PACKAGES.md` percorre todos os manifests npm e Composer do projeto e inclui também as dependências transitivas registradas em `package-lock.json` e `composer.lock`. A finalidade vem da descrição presente no lockfile, no pacote instalado ou no catálogo conhecido do documentador. Quando nenhuma dessas fontes existir, o arquivo declara que a finalidade não foi descrita nos metadados locais. Depois da reconstrução, a própria skill executa o modo `--check`. O comando compara os blocos gerados com o estado atual e falha quando `docs/` está desatualizado: node .agents/skills/specsfy-documentator/scripts/build_documentation.mjs \ --project . --check O monitor do setup também retorna `PENDING` quando o código da aplicação, a persistência ou as dependências mudaram sem uma nova reconstrução de `docs/`. Mudanças em manifests ou lockfiles exigem ainda a atualização de `.specsfy/PACKAGES.md`. Esse estado impede a conclusão da tarefa e do Delivery Gate. O código, os testes, os manifests, os schemas e as migrations comprovam o estado implementado. A spec governa o comportamento da mudança, enquanto `PROJECT.md` e `.specsfy/` preservam informações válidas para o sistema inteiro. Os arquivos em `/docs/` podem ser reconstruídos dessas fontes e não devem copiar segredos, valores de ambiente, registros de produção ou código integral. ### Skills especialistas do Specsfy por tecnologia usada - URL: https://promovaweb.com/docs/specsfy/especialistas - Descrição: Como as skills specsfy-specialist-* somam orientação técnica por tecnologia (Laravel, Astro, Next.js e outras) ao fluxo base do Specsfy usado hoje. As skills base conduzem a metodologia. As `specsfy-specialist-*` acrescentam orientação para a tecnologia encontrada no projeto, como Laravel, Astro, Next.js, Postgres ou Redis. Assim, você instala somente o conhecimento técnico usado pela aplicação. Na interface, cada uma usa o padrão `Specsfy - Especialista - Nome`, como `Specsfy - Especialista - Laravel`. O identificador de comando continua `specsfy-specialist-laravel`. Para criar ou alterar interfaces, `specsfy-specialist-interface-experience` coordena a entrega e carrega `specsfy-specialist-design-system` antes dos especialistas de UX, UI e componentes. O design system mantém as regras macro, defaults e cenários CRUD, a experiência examina a stack e o sistema atual, organiza as perguntas sobre telas e menus e garante uma fase específica de interface nas tarefas. ## Detectar e instalar O comando `detect` lê o projeto e mostra recomendações sem instalar arquivos. O catálogo local só deve ser alterado depois que você revisar os nomes retornados: ```bash specsfy skills detect ``` Depois da revisão, instale apenas os especialistas usados pela aplicação. A instalação sempre usa `npx skills add` e registra cada escolha no `skills-lock.json`, permitindo conferir depois quais arquivos são gerenciados: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-laravel \ --skill specsfy-specialist-postgres \ --skill specsfy-specialist-redis \ --agent universal --copy --full-depth ``` As skills base podem sugerir um especialista. Quando ele já estiver instalado, a transição é anunciada e continua na mesma conversa. Quando estiver ausente, o agente informa o especialista, a finalidade e as dependências, avisa que usará `npx skills add` e pede autorização específica para instalar. A transição entre skills nunca instala o catálogo inteiro automaticamente. ## Instalação no setup Ao iniciar o setup, você autoriza o Specsfy a detectar e instalar os especialistas diretamente ligados à stack encontrada, além de um núcleo comum para modelar dados, domínio, arquitetura e interfaces ReUI. Ele mostra os itens e usa `npx skills add` no projeto atual. Tecnologias sem sinal no código não entram na instalação. | Stack encontrada | Especialista | | --- | --- | | Laravel | Laravel e gestor de pacotes Laravel | | Supabase, PostgreSQL ou Redis | Supabase, PostgreSQL ou Redis correspondente | | React, Astro, Next.js ou TypeScript | especialista correspondente | | Tailwind CSS ou shadcn/ui | Tailwind CSS ou shadcn/ui correspondente | | ReUI solicitado para React e Tailwind | ReUI, React, Tailwind CSS e shadcn/ui | | Docker, Swarm ou Ansible | especialista de plataforma e versionamento correspondente | | OpenAPI, OpenTelemetry, Prometheus ou CI/CD | API, observabilidade ou entrega correspondente | ## Instalação manual Você pode instalar qualquer especialista do catálogo fora do setup. Essa opção serve para uma necessidade pontual que a stack ainda não revela, como revisão, acessibilidade ou pesquisa técnica: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-web-accessibility --agent universal --copy --full-depth ``` O setup não remove especialistas instalados manualmente. Eles permanecem no projeto e podem ser usados quando a entrega precisar deles. Para usar os componentes gratuitos do ReUI, instale o especialista e suas dependências resolvidas pelo catálogo: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-reui --agent universal --copy --full-depth ``` Ele prepara o registry ReUI para React 19, Tailwind CSS v4 e shadcn/ui, atende Laravel com Inertia e Vite e preserva o padrão de outros frameworks React. Nos CRUDs e dashboards compatíveis, ReUI é a base para consulta, filtros, formulários, indicadores, ações contextuais, anexos e mensagens de retorno. A skill consulta o catálogo gratuito antes de permitir a criação de componente manual equivalente. ## Gestor de pacotes Laravel `specsfy-specialist-laravel-package-manager` recebe a URL de um repositório GitHub, lê seu contrato Composer e sua documentação e compara o pacote com o que já existe no projeto. Quando a solicitação autoriza a instalação, executa `composer require` na raiz Laravel e confere o lockfile atualizado. O resultado documental fica em `docs/packages/`: - `README.md` é o índice dos pacotes Composer diretos, com versão, finalidade e link para cada ficha, - `-.md` explica instalação, configuração, uso local, testes e fontes consultadas, - `.specsfy/PACKAGES.md` continua sendo a relação completa, incluindo dependências transitivas. O especialista não repete uma instalação quando o pacote já aparece no manifest, no lockfile ou em `vendor/`. Se o repositório não expuser um pacote Composer compatível com Laravel, ele registra a lacuna e não altera os arquivos. ## Contrato de interfaces React Em Laravel com React, shadcn/ui e ReUI trabalham juntos: shadcn/ui fornece as primitives e ReUI fornece as composições gratuitas. Toda tela é construída por componentes React. A rota ou página coordena dados e compõe blocos, não reúne grade, formulário, filtros, diálogos, painel lateral e cartões reutilizáveis no mesmo arquivo. O setup cria `INTERFACE.md` e `DESIGNSYSTEM.MD` na raiz do projeto quando eles estão ausentes. O primeiro registra tokens, registries, telas e todos os blocos criados ou reaproveitados. O arquivo `DESIGNSYSTEM.MD` guarda as regras macro, defaults, padrões de CRUD e dashboard, estados e exceções com alcance, a skill especialista o mantém. Para cada bloco, informe arquivo, origem, finalidade, props e eventos, estados, acessibilidade, consumidores e como reaproveitar ou estender. A seção 10 de cada spec com interface usa a mesma relação para declarar os blocos React e os componentes shadcn/ui e ReUI escolhidos. As tarefas de interface atualizam o mapa antes de serem concluídas. Antes de desenvolver uma tela React, o planejamento e a implementação carregam `$specsfy-specialist-react-ui-components`. A skill procura primeiro os blocos existentes, orienta o reaproveitamento ou a adaptação e mantém `INTERFACE.md` alinhado ao código. Se ela ainda não estiver instalada, o fluxo retorna ao setup e instala o especialista detectado antes de escrever JSX ou TSX. Nas superfícies CRUD, a regra padrão é `PageHeader` e `DataGrid` para listas, com a linha inteira abrindo o detalhe por clique ou teclado, `PageHeader` e `DetailLists` para detalhes, e `PageHeader` com seções de formulário em duas colunas responsivas para criar e editar. Botões, checkboxes e menus internos ficam independentes da navegação da linha. Erros de campo ficam vermelhos e recebem mensagem abaixo do campo. Toda tela também exibe `Breadcrumb` com a equipe ativa, o módulo e o título atual. Em Laravel, o padrão reaproveita o `Breadcrumb` ou `Breadcrumbs` existente no layout. ## Catálogo por domínio | Domínio | Especialistas | | --- | --- | | backend e dados | Laravel, Supabase, Postgres, Redis e APIs web | | frontend | React, Astro, Next.js, TypeScript e Tailwind CSS | | interface | design system, experiência de interface, shadcn/ui, UI, UX e acessibilidade web | | plataforma | versionamento, Docker, Docker Swarm, Ansible e engenharia de entrega | | qualidade | segurança, observabilidade e performance | | design técnico | arquitetura e modelagem de domínio | | engenharia | code review, debugging, prototipação, pesquisa e conflitos Git | Cada especialista explica o fluxo de trabalho e as validações próprias da sua tecnologia. Uma mudança em Eloquent pode combinar Laravel e Postgres, por exemplo, mas uma alteração isolada em uma página Astro não precisa carregar orientações de todo o catálogo. ## Relação com as bases - `specsfy-02-backlog` identifica a necessidade. - `specsfy-03-specify` registra requisitos e atributos de qualidade. - `specsfy-04-validate` seleciona lentes de revisão. - `specsfy-05-tasks` usa checklists técnicos para decompor trabalho. - `specsfy-06-tdd-bdd` preserva RED/GREEN. - `specsfy-07-implement` executa de acordo com a stack. - `specsfy-update-spec` revisa requisitos e atributos de qualidade afetados por uma mudança posterior. - `specsfy-progress` identifica a orientação técnica aplicável e executa a transição automática. A presença de um especialista não aprova gates. O Plan Gate ainda exige um RED válido, e o Delivery Gate depende dos testes e das evidências registradas na spec.

Catálogo de especialistas

Escolha uma área para abrir a documentação completa da especialista, entender quando ela entra no trabalho e conferir as validações próprias do domínio.

Backend Laravel Laravel seguro do domínio à operação Ler documentação Backend Gestor de pacotes Laravel Instala e documenta pacotes Composer Laravel Ler documentação Backend Supabase Supabase com RLS, Auth e operação segura Ler documentação Dados PostgreSQL PostgreSQL correto, rápido e recuperável Ler documentação Frontend Tailwind CSS Tailwind com tokens e responsividade Ler documentação Dados Redis Redis resiliente para cache, filas e locks Ler documentação Plataforma Docker Imagens e Compose seguros e reproduzíveis Ler documentação Plataforma Deploy Deploy versionado em Docker Swarm via Ansible Ler documentação Plataforma Debian Server Hosts Debian para aplicações e clusters Ler documentação Plataforma Docker Swarm Stacks Swarm com rollout e recuperação Ler documentação Plataforma Ansible Automação Ansible idempotente e segura Ler documentação Frontend React React composto, acessível e testável Ler documentação Interface ReUI Interfaces React e Tailwind com ReUI gratuito Ler documentação Interface Componentes de UI React Biblioteca React e Tailwind para interfaces Ler documentação Frontend Astro Astro server-first com ilhas eficientes Ler documentação Frontend Next.js Next.js com boundaries e cache explícitos Ler documentação Linguagem TypeScript TypeScript estrito e contratos seguros Ler documentação Interface shadcn/ui shadcn/ui para aplicações e dashboards Ler documentação Interface Design System Governança visual e padrões globais de SaaS Ler documentação Interface Design de UI Interfaces e dashboards claros e consistentes Ler documentação Interface Design de UX Fluxos úteis, compreensíveis e validados Ler documentação Interface Experiência de Interface Descoberta e entrega de interfaces completas Ler documentação Qualidade Acessibilidade Web WCAG, semântica, teclado e foco Ler documentação Qualidade Segurança de aplicações Ameaças, controles e testes de segurança Ler documentação Arquitetura Arquitetura de software Boundaries, decisões e evolução arquitetural Ler documentação Arquitetura APIs Web Contratos HTTP compatíveis e resilientes Ler documentação Operação Observabilidade Logs, métricas, traces, SLOs e alertas Ler documentação Qualidade Engenharia de desempenho Performance medida, explicada e protegida Ler documentação Operação Versionamento SEMVER alinhado entre release e deploy Ler documentação Operação Engenharia de entrega CI/CD, artefatos, rollout e rollback Ler documentação Engenharia Revisão de código Revisão por contrato, risco e evidência Ler documentação Engenharia Depuração Diagnóstico por reprodução e hipótese Ler documentação Engenharia Modelagem de domínio Linguagem, invariantes e boundaries de domínio Ler documentação Dados Modelagem de Dados Entidades, relações e dados persistentes Ler documentação Engenharia Prototipação Protótipos focados em reduzir incerteza Ler documentação Engenharia Pesquisa técnica Pesquisa rastreável em fontes primárias Ler documentação Engenharia Resolução de conflitos Git Conflitos resolvidos pela intenção dos lados Ler documentação Engenharia Gitflow Branches Gitflow por decisão explícita do projeto Ler documentação ### Especialista Ansible no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/ansible - Descrição: Consulte o guia da especialista Ansible no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto tem playbooks, roles, `inventory`, `ansible.cfg` ou `requirements.yml`/`galaxy.yml` de collections. - Acionar também para revisar se uma automação existente é realmente idempotente antes de rodá-la contra um ambiente compartilhado. - Não acionar para orquestrar serviços já containerizados em cluster, usar `$specsfy-specialist-docker-swarm` nesse caso, Ansible aqui entra no provisionamento do host, não na orquestração de serviços do Swarm. - Combinar com `$specsfy-specialist-delivery-engineering` quando a execução do playbook é uma etapa de um pipeline de deploy. ## Fluxo Apresente o plano, informe o progresso e termine com arquivos alterados e validações executadas. Para texto público, siga o Contrato Editorial Compartilhado aplicável ao projeto consumidor. 1. Em release ou deploy completo, trabalhar sob `$specsfy-specialist-deploy` e usar o `SEMVER`, a imagem e os manifestos já preparados pela orquestradora. 1. Confirmar hosts, grupos, ambiente-alvo, método de conexão e escopo exato de hosts antes de qualquer execução com efeito. 1. Usar `./deploy check-hosts` para apresentar todos os hosts em tabela e confirmar o módulo `ping` antes da primeira task remota. Usar `./deploy sync-keys` para adicionar somente chaves públicas ao usuário `deploy`, sem excluir entradas existentes do `authorized_keys`. 1. Inspecionar a precedência de variáveis aplicável (ver tabela em `references/standards.md`) e as versões fixadas de collections e `ansible-core`. 1. Modelar o estado desejado com módulos idempotentes e roles coesas, uma responsabilidade por role. 1. Proteger secrets com Ansible Vault ou um provedor externo (lookup em cofre gerenciado), nunca em texto plano no repositório. 1. Para execução pelo agente, usar `./deploy run --non-interactive` sob a orquestradora de deploy. Respeitar arquivo, script, Vault IDs e configuração nativa já fornecidos. Sem fonte externa, orientar `./deploy configure-vault` no terminal humano. Não pedir ou ler a senha pela conversa. O comando `./deploy run` permanece manual, com entrada oculta. 1. Validar sintaxe, `ansible-lint`, check mode e diff sem revelar segredos no output. 1. Testar a role em ambiente descartável e repetir a mesma execução para provar que a segunda rodada não relata `changed`. 1. Aplicar em produção com serialização (`serial`), limites (`--limit`) e regra de parada (`max_fail_percentage`/`any_errors_fatal`) compatíveis com o alcance da mudança. ## Padrões - Criar um preflight separado para conferir versão do controlador, sistema do alvo, acesso ao Docker, papel de manager, login no registry, collections, imagem imutável e Docker Secrets antes do play com escrita. - Quando a stack usar Cloudflare Tunnel, criar `cloudflare_tunnel_token` a partir de `vault_cloudflare_tunnel_token` com `no_log: true`. A stack recebe somente o nome do Docker Secret. - Copiar manifests versionados para um diretório estável no host, validar cada um com `docker stack config` e publicar as stacks em ordem de dependência. - Após cada publicação, consultar as réplicas até atingir a convergência ou encerrar com erro após tentativas limitadas. Não concluir pelo retorno do módulo de deploy isoladamente. - Tratar check mode com honestidade: tasks de inspeção podem usar `check_mode: false`, tasks que alteram estado devem ser puladas ou suportar a simulação. O preflight precisa permanecer útil sem implantar stacks. - Usar FQCN (`ansible.builtin.copy`, não `copy`) e módulos declarativos, evitando `shell`/`command` sempre que existir módulo idempotente equivalente. - Dar nomes acionáveis a tasks e handlers (`name:` descreve o efeito, não o módulo), notificar handler somente quando a task realmente mudar estado. - Separar `defaults/main.yml` (configurável pelo consumidor da role), `vars/main.yml` (interno, não deve ser sobrescrito) e secrets (Vault ou lookup externo) em arquivos distintos. - Fixar collections em `requirements.yml` com versão e validar a matriz de compatibilidade com o `ansible-core` instalado antes de atualizar. - Usar `changed_when`/`failed_when` apenas para representar a semântica real do comando, nunca para silenciar uma falha genuína ou fingir idempotência em um `shell`/`command` que sempre relata mudança. - Restringir privilégio (`become` só na task que precisa) e usar `no_log: true` em qualquer task que manipule segredo, mesmo que o valor pareça inofensivo no log. - Não depender da ordem acidental dos hosts ou da execução paralela padrão quando a task tiver efeito colateral entre hosts (ex.: um serviço que só um host por vez pode reiniciar), usar `serial` e `throttle` explicitamente nesses casos. ## Antipadrões - `shell`/`command` sem `creates`, `removes` ou `changed_when` explícito: a task relata `changed` toda vez, mesmo quando o estado final é idêntico, isso quebra a leitura de "o que realmente mudou" em uma execução e mascara uma automação não idempotente. - Handler notificado incondicionalmente (fora de uma task que só dispara `notify` quando `changed`): reinicia serviço a cada execução, inclusive quando nada mudou, criando indisponibilidade desnecessária. - Variável de ambiente (produção/staging) só resolvida por `group_vars` genérico sem revisar a precedência real: um `-e` na linha de comando ou uma `host_vars` mais específica pode silenciosamente sobrescrever o valor esperado. - Vault decriptado e commitado por engano, ou segredo interpolado em um `debug:`/log sem `no_log`: o segredo vaza pelo histórico do Git ou pelo output da execução, mesmo que o arquivo fonte esteja corretamente criptografado. ## Validação - `ansible-playbook --syntax-check`, `ansible-lint` e execução em `--check --diff` (check mode) antes de qualquer aplicação real, confirmando que o diff não expõe segredo. - Duas execuções consecutivas no mesmo alvo: a segunda não deve relatar nenhuma task como `changed`, essa é a prova operacional de idempotência, não uma inspeção visual do código. - Testes de handlers (o serviço realmente reinicia quando deveria), de templates (renderização correta por ambiente) e de falha parcial (`any_errors_fatal`, `max_fail_percentage` se comportam como esperado quando um host falha no meio do batch). - Confirmação explícita do inventory e do `--limit` usados antes de qualquer mutação remota, nunca aceitar "rodar em todos os hosts" como default silencioso. - Não declarar uma role "idempotente" ou "segura" sem as duas execuções consecutivas e o check mode acima, a leitura do playbook não substitui a execução real contra um ambiente descartável. ## Skills relacionadas - `$specsfy-specialist-deploy` coordena a automação completa do servidor, esta skill cuida das roles e do playbook Ansible. - `$specsfy-specialist-versioning` mantém `SEMVER` alinhado à imagem e aos manifestos transportados pela automação. - `$specsfy-specialist-docker-swarm` quando o host provisionado por Ansible entra em um cluster Swarm, Ansible prepara o node, Swarm orquestra os serviços dentro dele. - `$specsfy-specialist-delivery-engineering` quando a execução do playbook é uma etapa de pipeline com promoção entre ambientes. - `$specsfy-specialist-application-security` para revisão de gestão de segredo, rotação de credencial e hardening do host provisionado. - `$specsfy-specialist-debian-server` para preparar APT, SSH, sysctl, systemd, firewall e Docker Engine antes da automação da aplicação. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-ansible/references/standards.md) para estrutura de roles, precedência de variáveis, idempotência, segurança operacional e comandos de teste, com fontes oficiais da documentação do Ansible. ### Especialista Segurança de aplicações no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/application-security - Descrição: Consulte o guia da especialista Segurança de aplicações no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando a mudança introduz ou toca trust boundary, identidade, entrada externa (upload, URL, query, deserialize) ou dado sensível. - Acionar também antes de desenhar uma feature com superfície de ataque nova (novo endpoint público, nova integração, novo tipo de usuário) para fazer threat modeling preventivo. - Não acionar como substituto de revisão de credenciais de pipeline/deploy — usar `$specsfy-specialist-delivery-engineering` para isso, aqui o foco é a aplicação e seus dados, não a esteira de entrega. - Combinar com `$specsfy-specialist-postgres`/`$specsfy-specialist-supabase` quando o risco envolve modelagem de acesso a dado por linha ou tenant. ## Fluxo 1. Mapear ativos, atores, trust boundaries, entradas externas e efeitos (o que muda de estado) antes de pensar em controle. 2. Definir ameaças plausíveis e seu impacto real antes de escolher controles — não implementar defesa para uma ameaça que não existe no contexto do sistema. 3. Verificar autenticação, autorização por objeto (não só por rota) e separação de tenants em toda operação que lê ou muta dado. 4. Validar toda entrada pelo tipo, tamanho e destino esperado, normalizar saída conforme o contexto de renderização, proteger operações mutáveis contra replay e CSRF quando aplicável. 5. Revisar gestão de secrets, criptografia em trânsito e em repouso, ciclo de vida de sessão, dependências vulneráveis e configuração de produção. 6. Materializar testes positivos (fluxo autorizado funciona) e negativos (fluxo não autorizado falha) nos boundaries críticos identificados. 7. Registrar risco residual, owner, sinal de observabilidade associado e plano de resposta — nenhum sistema fica "100% seguro", apenas com risco conhecido e monitorado. ## Padrões - Negar por padrão e conceder o menor privilégio necessário para cada identidade e operação. - Autorizar no servidor em toda operação e em todo objeto acessado — nunca confiar em uma verificação apenas client-side ou em um ID de objeto vindo do cliente sem revalidar propriedade/tenant. - Tratar upload de arquivo, URL fornecida pelo usuário, template renderizado com dado externo, query dinâmica e deserialização de dado externo como entradas hostis por padrão. - Não implementar criptografia própria, usar primitivas e bibliotecas estabelecidas. Nunca logar segredo, token, senha ou dado sensível, mesmo em ambiente de debug. - Rotacionar credenciais periodicamente e preferir identidade temporária (tokens de curta duração, STS/OIDC) a segredo estático de longa duração. - Mitigar abuso com limites por ator e por recurso (rate limit por usuário/ API key/tenant), não apenas por IP — um IP compartilhado (NAT, proxy) penaliza usuários legítimos e um atacante distribuído contorna limite só por IP. - Ao corrigir uma vulnerabilidade, corrigir a causa raiz e adicionar teste de regressão, sem divulgar detalhe de exploração além do necessário para quem precisa corrigir ou validar. ## Antipadrões - Verificar autorização apenas pela rota (`/admin/*` protegido) sem verificar o objeto específico acessado dentro da rota: um usuário autenticado como tenant A consegue acessar `/api/orders/123` de um tenant B só trocando o ID na URL (IDOR — Insecure Direct Object Reference). - Validar entrada só no client (JavaScript no navegador) sem revalidar no servidor: qualquer requisição direta à API contorna completamente a validação client-side. - Confiar em `Content-Type` ou extensão de arquivo declarados pelo cliente para decidir como processar um upload: permite disfarçar um arquivo malicioso como um tipo inofensivo. - Guardar segredo de aplicação (chave de API, senha de banco) em variável de ambiente sem controle de acesso ao processo/log, ou logar o payload completo de uma requisição que contém token de autenticação — o segredo vaza por um canal indireto mesmo com o "cofre" correto na origem. - Anunciar "sistema seguro" ou "vulnerabilidade corrigida" sem teste negativo específico comprovando que o vetor original não funciona mais. ## Validação - Casos de teste negativos: acesso sem autenticação, com identidade errada, com tenant errado e replay de uma requisição já processada — todos devem falhar de forma controlada. - Análise de dependências vulneráveis e varredura de secrets vazados com as ferramentas já adotadas pelo projeto, rodada como parte do fluxo normal, não apenas manualmente antes de um release grande. - Configuração segura de produção: headers de segurança (ex.: `Content-Security-Policy`, `Strict-Transport-Security`), atributos de cookie (`HttpOnly`, `Secure`, `SameSite`) e política de CORS restrita à origem realmente necessária. - Evidência concreta de cada controle reivindicado e do risco residual que permanece — nunca declarar algo "seguro" em linguagem absoluta sem o teste que comprova. ## Skills relacionadas - `$specsfy-specialist-ansible` e `$specsfy-specialist-docker` implementam hardening de host, container e runtime, esta skill define ameaça, privilégio e controle que a configuração precisa provar. - `$specsfy-specialist-laravel`, `$specsfy-specialist-nextjs` e `$specsfy-specialist-shadcn-ui` implementam superfícies de aplicação, autorização, validação server-side e exposição de dados permanecem aqui. - `$specsfy-specialist-code-review` aplica a revisão ampla e `$specsfy-specialist-observability` registra sinais de abuso sem vazar dados sensíveis. - `$specsfy-specialist-postgres` e `$specsfy-specialist-supabase` para modelagem de autorização por linha/tenant no nível de dado (RLS, constraints). - `$specsfy-specialist-delivery-engineering` para hardening de credenciais de pipeline, assinatura de artefato e supply chain. - `$specsfy-specialist-web-api-design` quando o risco nasce do desenho do contrato de API (verbos, versionamento, exposição de campo sensível). Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-application-security/references/standards.md) para checklist de threat modeling por boundary, ASVS, segurança de API e supply chain, com fontes primárias. ### Especialista Astro no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/astro - Descrição: Consulte o guia da especialista Astro no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto tem `astro.config` ou dependência `astro` e a tarefa envolve página, layout, componente `.astro`, content collection, endpoint ou ilha de interatividade. - Acionar também para decidir output mode (static/server), escolher a diretiva `client:*` certa, ou diagnosticar JS enviado ao cliente maior que o esperado. - Não acionar para a lógica interna de um componente React/Vue/Svelte hidratado dentro de uma ilha, usar `$specsfy-specialist-react` (ou equivalente) para o comportamento do componente em si, mantendo este especialista para a decisão de quando e como hidratá-lo. - Combinar com `$specsfy-specialist-web-accessibility` para landmarks, headings e navegação por teclado do site, e com `$specsfy-specialist-performance-engineering` quando o sintoma for Core Web Vitals fora do SLO. ## Fluxo 1. Descobrir versão do Astro, output mode (`static`/`server`), adapter, integrações ativas e fontes de conteúdo (Markdown, MDX, CMS remoto) antes de recomendar. 2. Classificar cada rota alterada como estática (conhecida no build), sob demanda (server-rendered por requisição) ou endpoint (contrato HTTP com `GET`/`POST` explícitos). 3. Manter HTML estático e zero-JS por padrão, hidratar apenas o componente que precisa de interação, com a diretiva `client:*` mais restritiva possível para o caso. 4. Modelar conteúdo com content collections e schema (Zod) explícito, tratar frontmatter inválido como erro de build, não como dado tolerado. 5. Definir caching, headers, assets e imagens (`astro:assets`) por rota, coerente com o output mode escolhido. 6. Testar `astro check`, build de produção, conteúdo inválido no schema e o comportamento hidratado de cada ilha isoladamente. 7. Medir payload de JS enviado ao cliente e Core Web Vitals no adapter alvo real, não apenas no dev server. ## Padrões - Usar a menor diretiva de hidratação compatível com a interação: `client:visible` para algo abaixo da dobra, `client:idle` para algo de baixa prioridade, `client:load` só quando a interação precisa estar pronta imediatamente, nunca `client:load` por padrão em tudo. - Não transportar para uma ilha mais dado do que ela usa para renderizar — cada prop de uma ilha vira JSON serializado no HTML e conta no payload. - Manter layouts e componentes `.astro` server-first, um componente `.astro` nunca precisa de diretiva `client:*` porque ele não hidrata — apenas os componentes de framework (React/Vue/Svelte) embutidos hidratam. - Validar todo conteúdo (frontmatter, parâmetros de rota, body de endpoint) na fronteira com schema explícito, tratar slug duplicado ou rota colidente como erro de build, não como comportamento silencioso. - Escolher `server` output (SSR) apenas quando personalização por requisição, sessão ou frescor de dado realmente justificar — do contrário, `static` é mais rápido, mais barato e mais simples de cachear. - Preservar `canonical`, sitemap e dados estruturados (JSON-LD) coerentes com a URL final de cada página, inclusive em conteúdo gerado dinamicamente. - Não assumir APIs completas do Node (`fs`, `process`) dentro de adapters edge, confirmar o runtime do adapter alvo antes de usar uma dependência server-only. ## Antipadrões - `client:load` aplicado "por garantia" em toda ilha da página — infla o JS enviado mesmo quando `client:visible` ou `client:idle` bastariam. - Passar o objeto de dado completo (ex.: registro inteiro do banco) como prop para uma ilha que só exibe dois campos — cada byte extra é serializado e enviado ao navegador. - Content collection sem schema Zod, "confiando" que o frontmatter está correto — um campo ausente só aparece como bug em produção, não em build. - Usar `server` output para o site inteiro quando só uma rota (ex.: um dashboard autenticado) precisa de SSR — perde cache estático nas páginas que não precisavam disso. - Confundir a responsabilidade desta skill com a do framework hidratado: um bug de estado dentro de uma ilha React é problema de `$specsfy-specialist-react`, não de configuração de ilha. ## Validação - Rodar `astro check`, a suíte de testes do projeto e o build de produção completo antes de considerar a mudança pronta. - Inspecionar o HTML servido com JavaScript desabilitado (deve continuar navegável e legível) e então validar a hidratação de cada ilha isoladamente. - Percorrer links internos, páginas de erro (404/500), imagens otimizadas e a presença de RSS/sitemap/metadados quando o site os expõe. - Fazer preview no runtime real do adapter (não só `astro dev`), medindo payload de JS por rota e Core Web Vitals antes/depois da mudança. - Não declarar uma página "estática" ou "zero-JS" sem inspecionar o HTML gerado, linguagem absoluta sem essa evidência é proibida. ## Skills relacionadas - `$specsfy-specialist-react-ui-components` fornece referências TSX para ilhas React, esta skill decide onde a ilha existe e como ela hidrata no Astro. - `$specsfy-specialist-react` (ou o framework de UI equivalente) para a lógica interna do componente hidratado dentro de uma ilha. - `$specsfy-specialist-web-accessibility` para landmarks, headings e ordem de foco do site publicado. - `$specsfy-specialist-performance-engineering` para investigar Core Web Vitals com metodologia de medição própria. - `$specsfy-specialist-web-api-design` quando um endpoint Astro expõe um contrato HTTP consumido por outro cliente além do próprio site. - `$specsfy-specialist-typescript` para o schema de content collections, props de componente e tipos de endpoint. - `$specsfy-specialist-tailwind-css` e `$specsfy-specialist-shadcn-ui` para a camada de estilo e os componentes visuais usados em layouts e ilhas. - Não use `$specsfy-specialist-nextjs` para decisões deste projeto: são frameworks distintos com fronteiras server/client e cache diferentes, migrar um padrão de um para o outro sem checar a skill correspondente costuma quebrar a semântica de cache. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-astro/references/standards.md) para modos de renderização, ilhas, content collections, actions, imagens e deploy, com fontes oficiais. ### Especialista Revisão de código no Specsfy: fluxo e validação - URL: https://promovaweb.com/docs/specsfy/especialistas/code-review - Descrição: Consulte o guia da especialista Revisão de código no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando houver um diff, branch ou PR concreto para avaliar antes de mergear ou publicar. - Acionar também quando o pedido for "segunda opinião" sobre uma mudança já escrita, mesmo sem PR aberto. - Não acionar para desenhar uma decisão estrutural nova do zero — use `$specsfy-specialist-software-architecture`, a revisão avalia o que já foi decidido e escrito, não substitui a decisão. - Combinar com `$specsfy-specialist-application-security` quando o diff tocar autenticação, autorização, dados sensíveis ou entrada externa, e com `$specsfy-specialist-domain-modeling` quando o achado for sobre nomes, invariantes ou fronteiras de domínio confusas. ## Fluxo 1. Fixar a base de comparação e o escopo exato do diff, revisar um diff sem base clara produz achados sobre código que a mudança não tocou. 2. Ler spec, issue, critérios de aceite e instruções do repositório aplicáveis antes de julgar, sem isso, "correto" vira opinião pessoal. 3. Mapear cada arquivo alterado para o comportamento e o boundary que ele afeta (dado, permissão, contrato de API, config, dependência). 4. Avaliar corretude, casos de borda, segurança, concorrência e efeito operacional antes de estilo — estilo só bloqueia quando automação não o cobre. 5. Inspecionar os testes pela evidência que fornecem: eles falhariam sem a correção, ou só cobrem a linha sem provar o comportamento? 6. Confirmar cada achado suspeito lendo o código real e os chamadores/ consumidores antes de reportar — reduz falso positivo. 7. Relatar por severidade, com localização exata (`arquivo:linha`), condição que dispara a falha, impacto e correção provável. ## Padrões - Priorizar bugs e risco concreto, não transformar preferência de estilo em bloqueador. - Cada achado descreve condição de entrada, consequência observável e a evidência que comprova (linha, teste, log). - Considerar compatibilidade com clientes existentes, concorrência, plano de rollback e observabilidade da mudança, não só o caminho feliz. - Verificar se o teste adicionado falharia sem a correção real — teste que passa antes e depois da mudança não prova nada. - Distinguir escopo ausente do PR (bloqueador de merge) de melhoria futura opcional (comentário, não bloqueio). - Não repetir achado que lint, formatter ou type checker automatizado já cobre, aponte só o que a automação não vê. - Declarar explicitamente "nenhum achado nesta lente" quando for o caso, sem linguagem que implique ausência de risco além do observado. ## Antipadrões - Bloquear por gosto pessoal de nome de variável ou formatação quando o projeto já tem linter configurado para isso — desperdiça o orçamento de atenção da revisão nos achados que importam. - Aprovar porque "os testes passam", sem checar se o teste novo de fato cobre o comportamento da mudança (teste tautológico ou sem asserção real). - Revisar arquivo por arquivo sem montar o fluxo entre eles — perde efeitos cruzados, como uma função que muda de assinatura sem todos os chamadores ajustados. - Reportar "parece inseguro" sem apontar o vetor concreto — achado de segurança sem trust boundary e entrada específica não é acionável. ## Validação - Revisar o diff completo, incluindo arquivos de configuração, migrations e chamadores/consumidores fora do diff que o comportamento afeta. - Conferir cada achado relatado contra o estado real do código e da suíte de testes antes de publicar — achado não confirmado não entra no relatório. - Ordenar a lista final por severidade (probabilidade × impacto), não pela ordem em que os arquivos aparecem no diff. - Resumir cobertura da revisão (o que foi olhado) e risco residual (o que não foi possível confirmar) ao final. - Não declarar um diff "seguro" ou "correto" sem a evidência acima — linguagem absoluta sem prova é proibida. ## Skills relacionadas - `$specsfy-specialist-debugging` fornece reprodução e causa raiz quando o review encontra um defeito ainda não explicado. - `$specsfy-specialist-typescript` aprofunda contratos de tipo e `$specsfy-specialist-web-accessibility` aprofunda semântica, teclado e WCAG quando esses riscos aparecem no diff. - `$specsfy-specialist-application-security` quando o diff tocar identidade, autorização, dado sensível ou entrada externa — a revisão de segurança aprofunda o que esta skill só sinaliza. - `$specsfy-specialist-software-architecture` quando o achado for sobre acoplamento, boundary ou decisão estrutural que o diff expõe, não apenas sobre o diff em si. - `$specsfy-specialist-merge-conflict-resolution` quando a revisão precisar ser refeita após uma resolução de conflito, já que a resolução pode mudar o comportamento resultante. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-code-review/references/standards.md) para as lentes de revisão, a escala de severidade, o formato de achado e as fontes oficiais de referência. ### Especialista Modelagem de Dados no Specsfy: guia técnico - URL: https://promovaweb.com/docs/specsfy/especialistas/data-modeling - Descrição: Consulte o guia da especialista Modelagem de Dados no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. Use esta skill para entender e evoluir dados persistentes, sem escolher banco ou biblioteca por suposição. Leia a stack, o sistema atual, migrations, schemas, models, contratos e testes antes de propor alteração. ## Trabalho 1. Identifique as entidades, seus papéis e as relações observadas no código. 2. Registre campos, tipos, obrigatoriedade, origem, ciclo de vida e quem pode consultar ou alterar cada informação. 3. Descreva unicidade, consistência, retenção, exclusão, histórico e migração quando forem pertinentes. 4. Atualize a seção de dados da spec e encaminhe respostas confirmadas para `$specsfy-aux-database` e `.specsfy/DATABASE.md`. 5. Derive cenários para criação, leitura, atualização, exclusão, autorização e dados inválidos. A implementação usa o especialista do banco detectado. Não invente campos, relações ou tecnologia. A pessoa confirma o que o produto precisa guardar quando o sistema atual não responder. ## Quando usar - Use ao alterar tabelas, schemas, models, migrations ou contratos persistentes. - Use também ao mapear relações e ciclos de vida antes de criar uma spec. - Não use para escolher uma biblioteca de banco sem dados do projeto. ## Fluxo 1. Ler stack, migrations, schemas, models e testes existentes. 2. Separar entidades, relações, campos e estados observados. 3. Registrar regras de unicidade, retenção, exclusão e histórico. 4. Comparar a proposta com os contratos e consultas atuais. 5. Encaminhar a confirmação para a skill de banco do projeto. 6. Exigir uma tarefa `[MIGRATION]` com arquivo versionado para qualquer mudança ligada ao banco e conferir sua aplicação em uma base de teste. ## Padrões - Cada campo registra tipo, origem, presença e ciclo de vida. - Cada relação informa cardinalidade e forma de carga. - Toda migration preserva dados existentes ou descreve a conversão necessária. ## Antipadrões - Criar campos sem uso observado no produto. - Alterar uma relação sem conferir queries, factories e testes. - Escolher tecnologia antes de ler o stack existente. ## Validação - Rode os testes e validadores ligados ao modelo persistente. - Confira a migration em uma cópia do banco e compare o schema resultante. - Confirme o arquivo, o comando de aplicação e a consulta do estado da migration antes de encerrar a tarefa. - Não declare o modelo pronto sem uma saída verificável do projeto. ## Skills relacionadas - `$specsfy-aux-database` para manter o mapa persistente do projeto. - `$specsfy-specialist-postgres` para detalhes próprios do Postgres. - `$specsfy-specialist-laravel` para migrations e models Laravel. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-data-modeling/references/standards.md) para fontes de modelagem, migrations e contratos persistentes. ### Especialista Debian Server no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/debian-server - Descrição: Consulte o guia da especialista Debian Server no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para instalação, hardening, atualização ou diagnóstico de um host Debian usado por aplicações, containers ou Docker Swarm. - Acionar para APT, systemd, journald, SSH, nftables, sysctl, discos, mounts, usuários, grupos, timezone, NTP e Docker Engine no host. - Não assumir uma versão Debian. Ler `/etc/os-release`, arquitetura, kernel, init, filesystem, capacidade e função do servidor antes de propor mudanças. - Não executar reboot, upgrade de distribuição, alteração de SSH ou firewall remoto sem acesso alternativo e autorização específica. ## Fluxo 1. Sob `$specsfy-specialist-deploy`, perguntar quais máquinas compõem o ambiente e registrar alias, endereço, porta SSH, usuário inicial e papel no Swarm em `ansible/inventory.yml`. Ao adicionar um servidor, preservar todas as entradas atuais e testar o novo host antes de configurá-lo. 2. Registrar versão, arquitetura, kernel, uptime, carga, memória, discos, mounts, rede, unidades com falha e pacotes pendentes. 3. Identificar o papel do host, serviços expostos, janela de manutenção, acesso de recuperação e estado gerenciado por Ansible. 4. Criar o usuário operacional `deploy`, adicionar suas chaves públicas SSH e definir sudo e permissões sem retirar o acesso atual antes de testar uma segunda sessão. 5. Configurar APT e atualizações de segurança, planejando reinícios de serviço e reboot quando kernel ou bibliotecas exigirem. 6. Aplicar firewall compatível com a topologia. Em Swarm, incluir tráfego de controle, descoberta e overlay somente entre nodes autorizados. 7. Persistir ajustes de kernel em `/etc/sysctl.d/`, aplicar de forma condicional e medir o comportamento do workload depois da mudança. 8. Validar systemd, journald, espaço, inodes, relógio, DNS, conectividade e reinicialização controlada em ambiente apropriado. ## Padrões - Usar repositórios correspondentes à release instalada e verificar a origem de pacotes externos. Não misturar suites Debian para obter uma versão nova. - Manter serviços em unidades systemd ou pacotes oficiais, com restart, dependências, limites e logs definidos. Não sustentar processo por sessão SSH. - Preferir nftables no Debian atual e salvar a configuração carregada no boot. Testar uma nova sessão administrativa antes de fechar conexões existentes. - Criar arquivos pequenos e nomeados em `/etc/sysctl.d/`, registrar a finalidade de cada parâmetro e evitar um bloco genérico sem owner. - Configurar rotação e retenção de logs conforme disco disponível. Alertar para uso de filesystem e inodes antes que o Docker pare de criar camadas. - Tratar acesso ao socket Docker e ao grupo `docker` como acesso administrativo amplo ao host. ## Antipadrões - Executar `apt full-upgrade` e reboot sem conferir serviços, console de recuperação e retorno automático da aplicação. - Alterar `sshd_config` e reiniciar SSH antes de validar a configuração e abrir uma segunda sessão autenticada. - Liberar portas de banco, Redis ou painel no host quando os consumidores estão na mesma rede privada ou overlay. - Aplicar `sysctl -w` sem arquivo em `/etc/sysctl.d/`: o ajuste desaparece no reboot e o estado observado deixa de corresponder à automação. - Manter dados persistentes de containers em disco local sem placement, backup e restore testados. ## Validação - `systemd-analyze verify` para unidades próprias e `systemctl --failed` após a alteração. - `sshd -t` antes de recarregar SSH, nova sessão autenticada antes de encerrar a conexão que aplicou a mudança. - `nft --check --file /etc/nftables.conf` antes do reload e teste de portas a partir das redes que devem ou não alcançar o host. - `sysctl --system` seguido da leitura dos parâmetros e novo teste após reboot. - `apt-get --simulate upgrade`, inspeção de `needrestart` quando disponível e confirmação de timers usados por atualizações automáticas. - Para host Docker, conferir daemon, rotação de logs, espaço, inodes, redes e persistência antes e depois da manutenção. ## Skills relacionadas - `$specsfy-specialist-deploy` coordena a preparação completa do servidor, este especialista define o estado Debian do host. - `$specsfy-specialist-ansible` automatiza e repete a configuração do host, este especialista define o estado Debian que a automação deve produzir. - `$specsfy-specialist-docker` governa imagem e runtime do container, este especialista cuida do daemon, kernel, disco e serviço Docker do host. - `$specsfy-specialist-docker-swarm` governa managers, workers, stacks e redes overlay depois que os nodes estão preparados. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-debian-server/references/standards.md) para baseline Debian, operação do Docker e comandos de inspeção com fontes oficiais. ### Especialista Depuração no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/debugging - Descrição: Consulte o guia da especialista Depuração no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando houver um comportamento observado divergente do esperado, com ou sem reprodução confiável ainda estabelecida. - Acionar também para falha intermitente ("flaky"), regressão após deploy ou degradação de performance com sintoma concreto (timeout, erro, lentidão reportada). - Não acionar para otimizar um sistema que já se comporta corretamente e sem sintoma — isso é `$specsfy-specialist-performance-engineering`, que parte de um SLO e não de uma falha. - Combinar com `$specsfy-specialist-observability` quando o ambiente de produção não expuser sinal suficiente para instrumentar o boundary certo. ## Fluxo 1. Capturar comportamento esperado, comportamento observado, ambiente exato e o momento/frequência da última ocorrência — sem isso a hipótese é chute. 2. Construir uma reprodução confiável ou, quando reprodução direta não for viável, um sinal observável e repetível (log, métrica, trace) que correlacione com a falha. 3. Reduzir input, componentes envolvidos e janela de tempo até o menor caso que ainda reproduz a falha — cada elemento removido que não muda o resultado é uma variável eliminada da hipótese. 4. Formular hipóteses falsificáveis e ordená-las pela facilidade de teste e pela probabilidade dado o sintoma observado, não pela mais interessante. 5. Instrumentar o boundary mais discriminante entre as hipóteses restantes — o ponto onde uma hipótese prevê um valor e a outra prevê outro. 6. Identificar causa, extensão do impacto (só esse caminho, ou a classe inteira de chamadas) e o mecanismo exato pelo qual ela produz o sintoma. 7. Se autorizado a corrigir, aplicar a menor mudança que remove a causa e adicionar teste de regressão que falha sem a correção. ## Padrões - Não alterar mais de uma causa candidata por vez — mudar duas coisas ao mesmo tempo invalida a atribuição de causa quando o sintoma desaparece. - Separar correlação temporal de causalidade: "começou depois do deploy X" é uma pista, não uma prova, até isolar o mecanismo. - Preservar evidência (logs, estado, dump) antes de reiniciar processo ou limpar estado — o ambiente que falhou pode ser irreproduzível depois. - Comparar ambiente bom e ruim sistematicamente: mesma versão, config, dados, carga e ordem de operações, variando um fator por vez. - Tratar flakiness como sintoma de concorrência, timing, estado compartilhado ou dependência externa até haver prova do contrário — nunca como "só rodar de novo". - Remover instrumentação temporária, verbosa ou sensível (dado pessoal, segredo) antes de concluir o diagnóstico. - Descrever a causa no nível do mecanismo ("a race entre X e Y permite leitura antes da escrita completar"), nunca só no nível do sintoma ("às vezes falha"). ## Antipadrões - "Adicionar print e rodar de novo" sem hipótese prévia — gera ruído, raramente reduz o espaço de busca e é frequentemente indistinguível de tentativa aleatória. - Corrigir o primeiro ponto onde o erro aparece, sem verificar se ali é a origem ou apenas onde o efeito se torna visível (o `NullPointerException` raramente nasce onde é lançado). - Declarar "corrigido" porque a reprodução manual parou de falhar uma vez — sem reprodução automatizada e determinística, a ausência do sintoma pode ser apenas sorte ou mudança de timing. - Ignorar teste flaky como "instável, não relacionado" sem investigar — flakiness é evidência de bug real de concorrência ou estado compartilhado na maioria dos casos, não ruído a suprimir. ## Validação - A reprodução falha de forma determinística antes da correção e passa de forma determinística depois, no mesmo ambiente. - O teste de regressão adicionado falha pelo motivo correto quando a correção é revertida (não por outro motivo incidental). - Cenários adjacentes ao caminho corrigido foram verificados quanto a efeito colateral da mudança. - Existe registro conciso de causa (mecanismo), evidência que a comprova e prevenção (teste, invariante, alarme) adicionada. - Não declarar a causa "resolvida" sem essa evidência — atribuir causa por intuição sem reprodução ou teste de regressão é proibido. ## Skills relacionadas - `$specsfy-specialist-technical-research` confirma comportamento externo, errata ou compatibilidade quando a causa depende de documentação primária. - `$specsfy-specialist-observability` para instrumentar produção quando o sinal disponível não é suficiente para discriminar hipóteses. - `$specsfy-specialist-performance-engineering` quando o sintoma for degradação sem erro funcional — o diagnóstico de causa raiz aqui pode entregar a esta skill a decisão de qual otimização vale o custo. - `$specsfy-specialist-code-review` para revisar a correção e o teste de regressão antes do merge. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-debugging/references/standards.md) para técnicas de reprodução e isolamento, causas comuns de flakiness, ferramentas por ambiente e fontes oficiais. ### Especialista Engenharia de entrega no Specsfy: guia técnico - URL: https://promovaweb.com/docs/specsfy/especialistas/delivery-engineering - Descrição: Consulte o guia da especialista Engenharia de entrega no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando o projeto tem pipeline (`*.yml` de CI/CD), estratégia de release, promoção entre ambientes ou plano de rollout/rollback. - Acionar também para escolher entre rolling, blue-green, canary ou feature flag diante de uma mudança específica. - Não acionar para a implantação de baixo nível dentro de um cluster Swarm (use `$specsfy-specialist-docker-swarm`) nem para decidir qual sinal prova que o rollout está saudável (use `$specsfy-specialist-observability`) — aqui o foco é o desenho do pipeline e da estratégia de promoção. - Combinar com `$specsfy-specialist-application-security` quando o pipeline manipula credenciais de produção ou publica artefato assinado. ## Fluxo 1. Em release ou deploy completo, trabalhar sob `$specsfy-specialist-deploy` e usar o `SEMVER` preparado pela `$specsfy-specialist-versioning` para artefato, changelog e tag. 1. Mapear commit, artefato, ambientes, aprovações necessárias e owner de cada promoção antes de desenhar o pipeline. 1. Tornar build e testes reproduzíveis a partir de lockfiles versionados — nunca resolver dependência "mais recente" no momento do build. 1. Produzir o artefato imutável uma única vez e promovê-lo, sem recompilação, entre ambientes (o binário testado em staging é bit-a-bit o mesmo publicado em produção). 1. Separar credenciais, permissões e trust boundaries por job — o job que builda não tem a credencial que publica em produção. 1. Coordenar migrations de schema com compatibilidade entre a versão antiga e a nova da aplicação durante toda a janela de rollout (expand/contract). 1. Definir a estratégia de rollout, os sinais objetivos de sucesso, o critério de pausa e o mecanismo de rollback antes do primeiro deploy real. 1. Registrar proveniência (de onde veio o artefato), versão, evidência de teste e resultado do rollout de forma auditável. ## Padrões - Usar menor privilégio, credenciais temporárias (OIDC/STS em vez de secret estático de longa duração) e actions/dependências de pipeline fixadas por hash ou versão exata, não por tag móvel (`@latest`, `@main`). - Não reconstruir o artefato para cada ambiente, construir uma vez, assinar ou gerar digest, e promover a mesma referência imutável. - Impedir concorrência incompatível (dois deploys do mesmo serviço ao mesmo tempo) e impedir deploy de um commit que não passou pelo pipeline de teste completo. - Manter ambientes reproduzíveis por infraestrutura como código, configuração de ambiente fica fora do artefato (env vars, secret manager), nunca embutida no build. - Exigir smoke checks funcionais e observabilidade ativa antes de considerar um rollout concluído — "o deploy terminou sem erro" não é o mesmo que "o serviço está saudável". - Tratar rollback de código (reverter para o binário anterior) e rollback de dados (reverter uma migration já aplicada) como problemas distintos com planos distintos — nem toda migration é reversível sem perda de dado. - Preservar trilha auditável de quem promoveu o quê, quando e com qual aprovação, sem jamais registrar segredo em log ou artefato de auditoria. ## Antipadrões - Pipeline que builda a imagem de novo em cada ambiente (`build` no job de staging e outro `build` no job de produção): o artefato testado em staging não é garantidamente o mesmo que vai para produção, mesmo com o mesmo Dockerfile — dependências resolvidas "latest" ou cache diferente produzem binários diferentes. - Feature flag sem owner nem expiração: acumula flags mortas que ninguém lembra o propósito, aumentando a superfície de combinações não testadas. - Migration de schema aplicada no mesmo deploy que remove a coluna antiga: quebra a versão anterior da aplicação se o rollback de código precisar rodar contra o schema já alterado — use expand (adicionar) num deploy e contract (remover) só depois que nenhuma versão antiga depende da coluna. - Secret de produção acessível a um job que roda em pull request de fork externo: o contexto de PR externo não deve ter acesso a nenhum secret de ambiente protegido. ## Validação - Lint/validação estática do pipeline, execução completa em branch segura e um teste deliberado de falha (o pipeline realmente para e não promove artefato quando um step crítico falha). - Verificação de digest do artefato, SBOM e assinatura/proveniência (attestation) quando essas práticas forem adotadas pelo projeto. - Ensaio completo de rollout e de rollback em ambiente representativo antes da primeira execução em produção — não confiar apenas na leitura da configuração do provedor. - Confirmação de gates de aprovação, branch protection e permissões configuradas no provedor (não apenas no arquivo de workflow, que pode ser sobrescrito por quem tem permissão de push). - Não declarar um pipeline "seguro" ou um rollout "concluído" sem essas evidências, ausência de erro no log não é prova de saúde do serviço. ## Skills relacionadas - `$specsfy-specialist-deploy` coordena o release e o deploy completos, esta skill cuida do pipeline e das promoções. - `$specsfy-specialist-versioning` prepara `SEMVER` e mantém o número alinhado entre artefato, changelog, tag e promoção. - `$specsfy-specialist-ansible` aplica configuração idempotente em hosts, esta skill governa promoção, aprovação e proveniência da entrega. - `$specsfy-specialist-software-architecture` define boundaries e restrições estruturais que o pipeline materializa entre ambientes. - `$specsfy-specialist-observability` para os sinais objetivos (erro, latência, saturação) que decidem continuar, pausar ou reverter um rollout. - `$specsfy-specialist-docker-swarm` quando o alvo do deploy é um cluster Swarm — esta skill desenha o pipeline até o ponto de promoção, a outra executa o rollout dentro do cluster. - `$specsfy-specialist-application-security` para hardening de credenciais de pipeline, supply chain e assinatura de artefato. - `$specsfy-specialist-performance-engineering` quando o rollout precisa de um baseline de performance antes de liberar tráfego total. - `$specsfy-specialist-gitflow` quando o projeto declarar Gitflow como estratégia de branch — aquela skill entrega a branch e a tag corretas (merge de `release/*`/`hotfix/*` em `main`), esta decide como o pipeline reage a elas. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-delivery-engineering/references/standards.md) para etapas mínimas de pipeline, comparação de estratégias de release e supply chain, com fontes oficiais. ### Especialista Deploy no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/deploy - Descrição: Consulte o guia da especialista Deploy no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando a pessoa pedir release ou deploy de uma aplicação em servidor. - Acionar para preparar um servidor que receberá stacks Docker Swarm via Ansible. - Acionar quando a pessoa pedir para cadastrar, adicionar, substituir ou conferir um servidor do ambiente. - Não executar push, provisionamento ou mudança remota sem alvo e autorização explícitos. ## Fluxo Apresente o plano, informe o progresso por etapa e encerre com arquivos alterados, validações e pendências. Para texto público, siga o Contrato Editorial Compartilhado aplicável ao projeto consumidor. 1. Confirmar a raiz do sistema do usuário e acionar `$specsfy-specialist-versioning` para ler ou preparar `SEMVER`. 2. Inspecionar `Dockerfile`, Compose, stack e `ansible/` existentes. Comparar PHP, extensões, dependências, assets, entrypoint, usuário interno, portas, healthcheck e comando do Octane com a aplicação atual. Preservar trechos personalizados e apresentar o diff antes de substituir um arquivo sem marcações gerenciadas. 3. Executar o gerador somente na primeira preparação, quando todos os destinos estiverem ausentes: ```bash node scripts/scaffold.mjs --project --image / ``` O padrão inclui Cloudflare Tunnel na stack. Se a pessoa pedir outro proxy, gerar sem `cloudflared` com `--proxy external` e configurar a alternativa solicitada em etapa própria. 4. Acionar `$specsfy-specialist-debian-server` para levantar as máquinas uma por rodada. Registrar hostname, endereço, porta SSH, usuário de conexão e papel `manager` ou `worker` em `ansible/inventory.yml`, preservando os hosts já cadastrados. Quando chegar uma máquina nova, adicionar somente esse host. 5. Testar todos os hosts declarados antes de qualquer alteração remota. A skill executa o utilitário, mas também mostra a forma curta para uso no Herdr: ```bash ./deploy check-hosts ``` 6. Localizar apenas chaves públicas `~/.ssh/*.pub` na máquina controladora e adicioná-las ao `authorized_keys` do usuário `deploy`. Nunca ler, copiar ou transmitir uma chave privada. Manter acessos remotos já cadastrados. 7. Perguntar quais senhas, tokens, chaves e keys a aplicação consome e registrar os nomes em `ansible/vault-fields.txt`. Não pedir os valores na conversa. O utilitário solicita cada valor com entrada oculta e grava o YAML criptografado: ```bash ./deploy secrets ``` A repetição mantém os campos existentes e pergunta somente os ausentes. No padrão Cloudflare Tunnel, incluir `vault_cloudflare_tunnel_token`. O serviço lê o token pelo arquivo `/run/secrets/cloudflare_tunnel_token`. 8. Gerar a referência da imagem com `docker-tag`. Recusar qualquer tag Docker diferente do valor presente em `SEMVER`. 9. Acionar `$specsfy-specialist-debian-server` e `$specsfy-specialist-docker` para definir o estado do host e do Docker Engine. 10. Acionar `$specsfy-specialist-ansible` para criar ou revisar roles idempotentes que criam o usuário `deploy`, instalam Docker Engine, configuram daemon, firewall, permissões e diretórios da aplicação. 11. Acionar `$specsfy-specialist-docker-swarm` para definir managers, workers, redes e stacks. O playbook executa `docker swarm init` somente quando o manager ainda não participa de um swarm e usa tokens protegidos para joins. 12. Validar Ansible em syntax check, lint, check mode e duas execuções num alvo descartável. Validar a stack com `docker stack config`. 13. Com autorização para o alvo informado, usar `./deploy run --non-interactive` quando o agente executar o deploy. A senha vem de uma fonte externa já configurada. Na ausência dessa fonte, orientar a pessoa a executar `./deploy configure-vault` no próprio terminal, não pedir, ler ou imprimir a senha na conversa. Preservar `./deploy run` como caminho manual. Aplicar o playbook, publicar a imagem versionada e executar `docker stack deploy` pelo manager. 14. Conferir réplicas, healthchecks, logs, versão e digest. Guardar o comando de rollback para a versão anterior. ## Padrões - Ler [references/vault.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-deploy/references/vault.md) antes de configurar a senha, migrar scripts existentes ou executar pelo agente. A fonte explícita tem precedência sobre ambiente e `ansible.cfg`, o cadastro local é a alternativa quando nenhuma fonte nativa existe. Falha de uma fonte encerra a execução. - Não executar `configure-vault` pela IA para preencher a senha. Esse comando pertence à preparação humana, em terminal com entrada oculta. - Atualizar projetos existentes por diff, preservando personalizações. O scaffold continua recusando sobrescrita e a atualização da skill não migra automaticamente `./deploy` ou `ansible/`. - `SEMVER` na raiz do sistema do usuário governa imagem, manifesto, tag Git e release. - Gerar `compose.yaml` para desenvolvimento e `stack.yaml` para produção. Toda produção usa a stack pelo Docker Swarm, não use Compose como runtime de produção. - Em Laravel, exigir `laravel/octane` e Open Swoole. A imagem instala `openswoole`, Compose e stack executam Octane com `--server=swoole`. - Sugerir Cloudflare Tunnel como entrada pública padrão. Executar `cloudflared` como serviço da stack, ligado à mesma rede overlay da aplicação e sem porta pública no serviço Laravel. O hostname do túnel aponta para `http://app:8000`. - Trocar o padrão somente quando a pessoa pedir outro proxy. Nesse caso, não gerar o serviço `cloudflared` nem o secret do token. - Ansible configura o servidor e o estado do Swarm. Não deixe uma sequência manual de comandos SSH como procedimento principal. - Criar o usuário de serviço `deploy`, adicionar somente esse usuário ao grupo `docker` e atribuir a ele os diretórios da aplicação. O grupo concede acesso administrativo amplo ao host e não deve incluir contas sem essa função. - Manter `ansible/inventory.yml` como mapa dos servidores conhecidos. Uma inclusão preserva os hosts atuais, testa a nova conexão e só então configura o node e seu papel no Swarm. - Mostrar `./deploy check-hosts`, `./deploy secrets`, `./deploy sync-keys` ou `./deploy run` quando a pessoa precisar copiar uma ação para outro painel do Herdr. A skill executa esses utilitários sem exigir memorização. - Em nova chamada, ler novamente a aplicação e reconciliar apenas o que mudou. O gerador serve ao primeiro bootstrap e não deve sobrescrever arquivos existentes para simular atualização. - Use módulos idempotentes e `community.docker`, comandos necessários para iniciar ou integrar o swarm precisam de condições baseadas no estado atual. - Mantenha managers em número ímpar e restrinja as portas do Swarm aos nodes autorizados. - Publique uma imagem uma vez e promova o mesmo digest entre ambientes. - Senhas, tokens e chaves entram em um Ansible Vault criado por prompt seguro. O Ansible transforma os valores descriptografados em Docker Secrets com `no_log: true`, a stack guarda apenas nomes e mounts externos. ## Antipadrões - Usar `latest` ou outra tag que não reproduza `SEMVER`. - Executar `docker swarm init` em toda rodada do playbook. - Expor token de join em log, variável aberta ou arquivo commitado. - Guardar senha, token ou chave no `stack.yaml`, em variável aberta ou na imagem. - Passar o token do Cloudflare Tunnel por argumento, variável aberta ou arquivo versionado. - Conceder `sudo` irrestrito ao usuário `deploy` sem necessidade confirmada. - Fazer build no servidor ou recompilar uma imagem para cada ambiente. - Considerar o deploy concluído apenas porque o comando retornou código zero. ## Validação - Comprovar o prompt manual, arquivo externo, script de cofre e configuração nativa em um alvo descartável. Sem senha válida, a execução deve parar antes de conectar aos hosts. Conferir permissões `700` e `600`, confirmação de substituição e ausência de valores secretos na saída do configurador. - Executar `current`, `docker-tag` e `verify-docker-tag` pela skill de versionamento. - Confirmar que `deploy` existe, pertence ao grupo `docker`, acessa o daemon e é owner dos diretórios da aplicação. - Confirmar Docker Engine ativo, manager alcançável e swarm em estado `active`. - Executar o playbook duas vezes, a segunda rodada deve terminar sem mudanças. - Comparar a imagem de cada serviço com `SEMVER` e com o digest publicado. - Observar a convergência e ensaiar rollback em ambiente compatível. ## Skills relacionadas - `$specsfy-specialist-versioning` governa a versão do sistema do usuário. - `$specsfy-specialist-debian-server` define o estado base do host. - `$specsfy-specialist-docker` prepara e publica a imagem. - `$specsfy-specialist-ansible` automatiza o servidor e o cluster. - `$specsfy-specialist-docker-swarm` governa serviços, rollout e rollback. - `$specsfy-specialist-delivery-engineering` governa pipeline e promoção entre ambientes quando esses componentes fizerem parte da entrega. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-deploy/references/standards.md) antes de criar ou alterar o playbook de provisionamento e deploy. ### Especialista Design System no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/design-system - Descrição: Consulte o guia da especialista Design System no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar Esta skill governa o documento `DESIGNSYSTEM.MD` do projeto consumidor. Ela define linguagem visual, shell, composição de superfícies, estados e regras de negócio expostas na interface. O documento orienta UX, UI, experiência de interface e componentes React. Use antes de criar ou revisar uma tela, um fluxo CRUD, uma navegação, um formulário ou um componente global. Use também quando o documento não existir, estiver desatualizado ou entrar em conflito com uma tela já projetada. Não use esta skill para catalogar componentes, props ou arquivos locais. Esse registro pertence a `INTERFACE.md`, que deve apontar para as escolhas macro sem copiá-las. ## Fontes obrigatórias Leia, nesta ordem: 1. `DESIGNSYSTEM.MD` na raiz do projeto consumidor, se existir. 2. `.specsfy/templates/DESIGNSYSTEM.MD` para criar a fonte ausente. 3. `INTERFACE.md` para conhecer componentes e telas já registradas. 4. `.specsfy/STACK.md`, manifests, rotas, telas, permissões e regras do domínio relacionadas à entrega. Quando a fonte não existir, copie o template gerenciado para `DESIGNSYSTEM.MD` e preencha apenas o contexto já confirmado. Não esconda lacunas com texto genérico. ## Fluxo 1. Identifique o produto, o módulo, a superfície e o fluxo afetado. 2. Compare a solicitação com `DESIGNSYSTEM.MD` e preserve as regras já ativas. 3. Se a pessoa não informa direção visual, aplique os defaults do documento e registre isso como direção padrão da entrega. 4. Se a pessoa fornece uma direção diferente, registre a exceção, seu alcance e a regra que ela substitui. Uma exceção de tela não altera o produto todo. 5. Atualize o documento somente quando a regra tiver alcance macro. Registre componentes e telas específicas em `INTERFACE.md`. 6. Mapeie os cenários canônicos da superfície antes de entregar a orientação para UX, UI ou implementação. 7. Retorne os arquivos lidos, a regra aplicada, as exceções registradas e os cenários cobertos. Em toda entrega visual, faça a revisão durante o desenvolvimento mesmo sem pedido da pessoa. Confira bordas, espaçamentos, margens, padding e tipografia do sistema nos viewports e estados relevantes. Registre o método, o resultado e os ajustes no item `VISUAL` da tarefa. ## Padrões ### Defaults obrigatórios para SaaS Quando não houver direção visual contrária, aplique estas composições: - Lista de CRUD: `PageHeader` + resumo útil + `DataGrid`. Use busca, filtros, ordenação, paginação, seleção e ações por linha quando o volume ou o domínio pedir. - Detalhe: `PageHeader` + `DetailLists`, com status, próxima ação e relações ou atividade quando forem úteis para o domínio. - Criar e editar: `PageHeader` + seções de formulário em duas colunas responsivas, com coluna de contexto e painel de campos. - Formulário: labels visíveis acima dos campos, ajuda contextual, valores preservados e estado de envio. - Erro de campo: borda, fundo ou ícone semântico vermelho, mensagem visível abaixo do campo, associação semântica e foco no primeiro erro. - Erros múltiplos: resumo no início com links para os campos afetados. - Tela: `loading`, vazio, erro, sucesso, sem permissão, conteúdo parcial e não salvo quando o fluxo comportar esses estados. - Breadcrumb: obrigatório em toda tela da aplicação, com o nome da equipe ativa visível antes do módulo e do título atual. Em Laravel, reaproveitar o `Breadcrumb` ou `Breadcrumbs` existente no layout e seus tipos de rota. - DataGrid: linha inteira clicável para abrir o detalhe, com equivalente de teclado e controles internos protegidos por `TableRowAction` ou equivalente. - CRUD: todas as telas reutilizam o mesmo `PageHeader` componentizado, a lista usa `DataGrid` em largura total, exibe a coluna `ID` e oferece botões de editar e apagar na linha. O link da linha leva ao detalhe sem capturar os botões. - Componentes recorrentes de cabeçalho, tabela, linha, ações, formulário, estados e feedback entram em `INTERFACE.md` e são reaproveitados antes de uma nova implementação. Esses defaults não significam aparência genérica. A personalidade vem da hierarquia dos dados, linguagem do domínio, tipografia, tokens, ritmo, estados, contraste e uso do shell. A composição deve informar e orientar a tarefa. ## Dashboards e blocos comuns Quando a entrega incluir um dashboard, use `PageHeader`, período ou escopo, filtros, uma faixa curta de `KPI` com valor, unidade, período, comparação e fonte, seguida da tendência ou distribuição principal e de uma lista detalhada ou `DataGrid` para investigação. Cada indicador e visualização deve declarar loading, vazio, erro e atualização, além de alternativa textual ou tabular para gráficos. Use primitives do `shadcn/ui` para controles fundamentais e blocos gratuitos do ReUI para composições de CRUD e dashboard quando eles atenderem à tarefa. Adapte tokens, dados, permissões, acessibilidade e linguagem do produto. Registre origem, estados e consumidores em `INTERFACE.md`. ## Formulários de criar e editar Organize criar e editar em seções independentes. Cada seção apresenta contexto à esquerda e o painel de campos à direita. No painel, campos relacionados usam duas colunas nos breakpoints largos e uma coluna no mobile, campos longos, uploads e erros podem ocupar toda a largura. O rodapé mantém cancelar e salvar próximos do resultado da ação. ## Breadcrumb e shell Toda tela renderiza o `Breadcrumb` no shell global. A trilha deve mostrar a equipe ativa, o módulo e a tela atual, usando labels reais e links válidos nos itens anteriores. Em aplicações Laravel, localize e reaproveite o componente `Breadcrumb` ou `Breadcrumbs` já presente no layout, junto da tipagem dos itens, adapte apenas a composição necessária para inserir a equipe sem duplicar o primitive. A equipe e a tela atual continuam visíveis no mobile. ## Cenários que toda entrega deve cobrir Consulte a seção `Cenários canônicos` do template e registre o recorte aplicável em `DESIGNSYSTEM.MD` ou na spec da entrega: - lista com registros, - lista vazia, - detalhe com status e ações, - criação válida, - edição válida, - criação ou edição com erro de campo, - ausência de permissão, - falha de carregamento, - alteração não salva, quando houver edição, - resultado de ação destrutiva, quando houver exclusão ou cancelamento. Para cada cenário, informe pré-condição, ação, resposta, estado visual, foco, mensagem e próximo passo. ## Limites e handoff - UX define fluxo, arquitetura da informação e linguagem da tarefa a partir desta fonte. - UI define tokens, hierarquia, composição visual e estados a partir desta fonte. - Componentes React escolhem primitives e composições compatíveis depois de ler esta fonte e `INTERFACE.md`. - A skill de experiência de interface coordena a entrega e não deve iniciar uma tela sem carregar `DESIGNSYSTEM.MD`. ## Antipadrões - Parede de cards quando a pessoa precisa comparar registros. - Formulário sem seções quando o domínio tem grupos de informação distintos. - Duas colunas no mobile ou uma grade que separa campo, ajuda e erro. - Placeholder usado como único label. - Erro indicado somente por ícone, cor ou toast distante do campo. - Tela sem `PageHeader`, sem estado vazio ou sem caminho de recuperação. - Dashboard que mostra números sem pergunta, período, unidade ou próxima ação. - Dashboard que usa uma parede de cartões sem hierarquia ou investigação. - Bloco de ReUI ou primitive de shadcn/ui usado sem adaptar dados, estados, permissões e tokens do produto. - Novo token ou componente criado sem verificar o documento e `INTERFACE.md`. - Exceção visual local registrada como regra global sem alcance explícito. - CRUD com cabeçalhos duplicados, DataGrid estreito, ID oculto ou sem ações de editar e apagar na linha. ## Validação Antes do handoff, confira: - `DESIGNSYSTEM.MD` existe na raiz do projeto consumidor e tem classificação, política, defaults, estados, cenários e histórico. - A lista usa `DataGrid` e `PageHeader`. - Toda tela tem `Breadcrumb` com o nome da equipe ativa, módulo e tela atual. - Laravel reaproveita o `Breadcrumb` ou `Breadcrumbs` já existente no layout. - O detalhe usa `DetailLists` e `PageHeader`. - Criar e editar usam seções, coluna de contexto, painel de campos em duas colunas nos breakpoints largos e uma coluna no mobile. - Erros de campo aparecem em vermelho abaixo do campo e têm associação semântica. - A direção padrão ou a exceção está registrada com alcance. - `INTERFACE.md` contém somente o registro local da entrega. - A spec e as tarefas cobrem estados, permissão, foco, mensagens e retorno. - O dashboard, quando existir, tem filtros, contexto dos indicadores, alternativa acessível para visualizações e investigação detalhada. - Primitives shadcn/ui e blocos ReUI têm origem, estados e consumidores registrados em `INTERFACE.md`. - Cada tarefa possui o item `VISUAL` concluído antes de `EVIDENCE`, com a conferência de bordas, espaçamentos, margens, padding e tipografia ou a justificativa concreta de que não há interface. Execute os testes e validadores da stack quando houver implementação. Para a skill do Specsfy, execute `quick_validate.py` e a suíte do monorepo. ## Skills relacionadas - [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-design-system/references/standards.md) - `skills/templates/DESIGNSYSTEM.MD` - `skills/templates/Interface.md` - `specsfy-specialist-interface-experience` - `specsfy-specialist-ux-design` - `specsfy-specialist-ui-design` - `specsfy-specialist-react-ui-components` ### Especialista Docker no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/docker - Descrição: Consulte o guia da especialista Docker no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para escrever ou revisar `Dockerfile`, `docker-compose.yml`, `.dockerignore`, política de tag/registry ou depurar um container que não builda, não sobe ou não responde a healthcheck. - Acionar também para reduzir tamanho de imagem, eliminar segredo vazado em camada ou corrigir processo que não recebe `SIGTERM` corretamente. - Não acionar para orquestração de múltiplos nós, rollout com réplicas, secrets de cluster ou rede overlay — usar `$specsfy-specialist-docker-swarm` para isso, Docker Compose aqui é ambiente local/CI, não topologia de produção multi-host. - Combinar com `$specsfy-specialist-application-security` para revisão de supply chain (SBOM, proveniência, dependências vulneráveis) e com a skill de linguagem/framework do projeto para o conteúdo do build em si. ## Fluxo 1. Descobrir arquitetura alvo (amd64/arm64), runtime base (linguagem, versão), build context real e o contrato de execução esperado (variáveis, portas, volumes) antes de propor mudança. 2. Inspecionar `Dockerfile`, `.dockerignore`, `docker-compose.yml` e a política de imagem/tag já em uso pelo projeto. 3. Quando a imagem fizer parte de uma release ou deploy, executar esta etapa sob `$specsfy-specialist-deploy`. Usar a versão entregue por `$specsfy-specialist-versioning`, gerar a referência com `docker-tag` e recusá-la quando `verify-docker-tag` apontar diferença. 4. Separar dependências de build e runtime com estágios (`multi-stage build`) claros — a imagem final não deve conter compilador, cache de pacote ou fonte que não roda em produção. 5. Fixar artefatos de forma reproduzível (lockfile, versão de base image pinada ou por digest) e reduzir contexto de build e camadas mutáveis. 6. Executar o processo como usuário não root, limitar privilégios (`cap_drop`, sem `--privileged`) e nunca embutir segredo na imagem. 7. Definir healthcheck, tratamento de sinal (`SIGTERM`, `SIGINT`), volumes, redes e configuração externa (env, arquivo montado) explicitamente. 8. Construir a imagem, escanear vulnerabilidades e testá-la exatamente como será executada em produção (mesmo usuário, mesmas variáveis). ## Padrões - Em aplicações com extensões nativas, dividir compilação em estágios independentes por família. Uma alteração em Redis, mídia ou servidor de aplicação não precisa invalidar toda a toolchain. - Quando vários serviços usam o mesmo código, produzir uma imagem única e selecionar modos de processo no entrypoint, como HTTP, scheduler, filas e WebSocket. Cada modo recebe healthcheck, sinal e escrita compatíveis com sua função. - Publicar referências imutáveis para SemVer e commit, conferir se ambas ainda não existem e registrar o digest usado pelo deploy. A tag Git só deve ser publicada depois que a imagem estiver disponível no registry. - Gerar caches de framework no entrypoint quando eles dependem de configuração fornecida no runtime. Não transportar cache de configuração criado durante o build para ambientes com valores diferentes. - Preferir base mínima compatível (slim/alpine quando a stack suporta) e fixar por digest (`@sha256:...`) quando reprodutibilidade byte-a-byte importar mais que atualização automática de patch. - Ordenar instruções para maximizar cache (dependências antes do código fonte) sem esconder atualização de dependência — um `COPY package*.json` seguido de `RUN install` antes do `COPY . .` cacheia a instalação enquanto o código muda, sem congelar a versão instalada. - Usar mounts de secret e cache do BuildKit (`RUN --mount=type=secret`, `--mount=type=cache`) para credenciais de build e cache de package manager — nunca `ARG`/`ENV` para segredo, pois ambos persistem no histórico de camadas da imagem final. - Nunca copiar o repositório inteiro sem `.dockerignore` — `.git`, `node_modules`, artefatos de build local e `.env` vazam para o contexto e infla o tamanho/tempo de build. - Tratar o processo principal como PID 1 conscientemente: usar `ENTRYPOINT` em forma exec (`["cmd"]`, não `CMD cmd args` em shell form) para receber sinais corretamente, ou um init mínimo (`--init`/`tini`) quando o processo não reaper zumbis. - Manter dado persistente fora da camada gravável do container (volume nomeado ou bind mount) — dado na camada do container morre com o container. - Definir limites de recurso e filesystem raiz somente leitura (`--read-only` + volumes explícitos para o que precisa escrever) quando o workload permitir, reduzindo superfície de ataque em runtime. ## Antipadrões - `latest` como única tag em produção — não é reprodutível e não permite saber qual código está rodando sem inspecionar o container. - `ADD` para copiar arquivo local (em vez de `COPY`) — `ADD` também descompacta e busca URL, comportamento implícito que surpreende quem lê o Dockerfile depois. - `USER root` implícito (ausência de `USER`) em imagem que serve tráfego — processo comprometido dentro do container tem privilégio de root do container, ampliando o impacto de qualquer vulnerabilidade na aplicação. - Instalar dependência de build (compilador, headers) na mesma camada final sem multi-stage — infla a imagem e aumenta a superfície de vulnerabilidade escaneável sem benefício em runtime. - Healthcheck que só verifica "processo escutando na porta" sem checar dependência crítica (banco, fila) — o orquestrador considera o container saudável mesmo quando ele não consegue de fato servir a requisição. ## Validação - Build limpo sem cache (`--no-cache`) e build incremental (com cache) — ambos devem produzir uma imagem funcionalmente equivalente. - Executar a imagem com o usuário, arquitetura e variáveis de ambiente reais do ambiente alvo, não apenas com defaults de desenvolvimento. - Exercitar healthcheck, `docker stop` (shutdown gracioso dentro do prazo configurado), portas publicadas, volumes, resolução DNS interna e o comportamento quando uma dependência declarada está indisponível. - Gerar SBOM/rodar scanner de vulnerabilidade disponível no projeto e inspecionar tamanho e número de camadas da imagem final. - Não declarar uma imagem "segura" sem o scanner rodado, nem "reproduzível" sem builds repetidos produzindo o mesmo resultado funcional a partir do mesmo commit. ## Skills relacionadas - `$specsfy-specialist-deploy` coordena a entrega completa, esta skill cuida somente da imagem e do Compose de desenvolvimento. - `$specsfy-specialist-versioning` prepara `SEMVER` e confere a identidade da imagem antes da publicação. - `$specsfy-specialist-docker-swarm` para orquestração multi-nó, secrets de cluster, rede overlay e rollout de serviços — este especialista cobre a imagem e o Compose local, não o cluster de produção. - `$specsfy-specialist-application-security` para supply chain (SBOM, proveniência, CVE de dependência) e hardening além do container. - `$specsfy-specialist-observability` para logging, métricas e tracing do processo dentro do container. - `$specsfy-specialist-postgres`, `$specsfy-specialist-redis` para o que roda dentro da imagem/serviço (modelagem de schema, estrutura de dado, persistência) — esta skill cobre o empacotamento (imagem oficial, volume, healthcheck), não a decisão interna do banco/cache. - `$specsfy-specialist-supabase` quando o ambiente local do projeto for orquestrado pela CLI do Supabase sobre Docker. - `$specsfy-specialist-laravel` para os contratos de execução da aplicação empacotada (workers de fila, scheduler, variáveis de ambiente esperadas). - `$specsfy-specialist-debian-server` para kernel, filesystem, systemd, APT e Docker Engine do host que executa a imagem. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-docker/references/standards.md) para build, Compose, segurança, supply chain e operação. ### Especialista Docker Swarm no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/docker-swarm - Descrição: Consulte o guia da especialista Docker Swarm no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto orquestra múltiplos nós com `docker swarm init/join`, `docker stack deploy` ou arquivos de stack com `deploy:`. - Acionar também para decidir topologia de managers/workers, rollout, rollback ou recuperação de quorum. - Não acionar para desenvolvimento local com `docker compose up` em uma única máquina, nem para build de imagem — usar `$specsfy-specialist-docker` nesse caso, muitas chaves do Compose (`profiles`, `depends_on.condition`, `build` em runtime) não têm efeito em `docker stack deploy`. - Combinar com `$specsfy-specialist-delivery-engineering` quando o rollout faz parte de um pipeline de release, e com `$specsfy-specialist-observability` para decidir os sinais que autorizam ou revertem o rollout. ## Fluxo 1. Em release ou deploy completo, trabalhar sob `$specsfy-specialist-deploy`. Conferir o `SEMVER` preparado por `$specsfy-specialist-versioning`, executar `verify-docker-tag` antes de `docker stack deploy` e interromper quando a tag for diferente. 1. Mapear managers, workers, zonas, labels, quorum e dependências externas (registry, storage, DNS) antes de qualquer mudança de topologia. 1. Validar que a imagem publicada é a mesma testada e que o arquivo de stack usa apenas chaves suportadas por `docker stack deploy` (não todo o schema do Compose). 1. Definir services, redes, ports, volumes, configs e secrets, com um owner claro para cada recurso compartilhado. 1. Configurar replicas, placement constraints/preferences, `resources.limits`/`reservations`, healthcheck e `restart_policy`. 1. Projetar `update_config` e `rollback_config` (paralelismo, delay, ordem `start-first`/`stop-first`, `failure_action`) garantindo que a versão nova e a antiga coexistam sem quebrar contrato de API/dados durante o rollout. 1. Aplicar em um swarm representativo (staging com topologia equivalente, não um único nó) e observar convergência com `docker service ps` e `docker service logs`. 1. Documentar procedimento de deploy, rollback, rotação de secret, backup do estado do Raft e plano de recuperação de perda de manager. ## Padrões - Em deploy coordenado por `$specsfy-specialist-deploy`, usar Cloudflare Tunnel como entrada pública padrão. Manter `cloudflared` e a aplicação na mesma rede overlay, sem publicar a porta do Laravel no host. Aceitar outro proxy quando a pessoa pedir essa troca de forma explícita. - Entregar o token do túnel por Docker Secret montado como arquivo e iniciar `cloudflared` com `--token-file`. Nunca guardar o valor na stack. - Separar dependências, aplicação e ingress em stacks diferentes. Publicar em ordem de dependência, aguardar a convergência declarada de cada serviço e só então abrir o caminho público. - Concentrar migrations em uma réplica escolhida. Os demais serviços iniciam com migrations desativadas para impedir concorrência durante rollout. - Usar a mesma imagem imutável para HTTP, filas, scheduler e WebSocket, com comandos e healthchecks próprios. Manter o worker de contingência em zero réplica quando outro supervisor de filas estiver ativo. - Criar redes overlay externas e criptografadas antes das stacks. Serviços de dados ficam apenas na rede interna, um tunnel outbound-only pode eliminar portas públicas no host quando esse desenho atende ao projeto. - Manter número ímpar de managers (1, 3 ou 5) e nunca deixar o quorum dependente de um único manager em produção. - Publicar imagens imutáveis por digest (`image@sha256:...`) acessíveis por todos os nodes, um node não pode divergir por ter build local. - Usar secrets/configs versionados por nome (`app_secret_v2`) e nunca embutir segredo em variável de ambiente do arquivo de stack. - Separar rede de ingress, rede interna de serviço e rede de dados, não expor uma porta de serviço interno via `ports:` publicado. - Definir `resources.limits` e `reservations` explicitamente, não depender de capacidade implícita do node mais folgado. - Aplicar `placement.constraints` apenas com labels administradas (`node.labels.*`), nunca com hostname hardcoded. - Não assumir que uma opção do Compose (`profiles`, `build`, `develop`, `depends_on` com `condition`) é respeitada por `stack deploy` — validar contra a lista de campos suportados antes de depender dela. ## Antipadrões - Rolling update sem `update_config.order: start-first` em serviço com poucas réplicas: a réplica antiga cai antes da nova ficar saudável, e o serviço fica momentaneamente sem capacidade. - Volume local (`bind` ou volume nomeado sem driver distribuído) em serviço com múltiplas réplicas ou reagendamento: o dado "desaparece" quando o scheduler realoca o container para outro node. - Secret alterado in-place trocando o conteúdo do arquivo referenciado: Swarm trata secrets como imutáveis por nome, a mudança correta é criar uma nova versão (`app_secret_v2`), anexá-la ao serviço e só então remover a antiga. - Confundir `docker-compose.yml` de desenvolvimento com o arquivo de stack de produção: healthcheck, `deploy:`, secrets e redes overlay costumam faltar ou divergir entre os dois. ## Validação - Rodar `docker stack config --compose-file ` (ou validação equivalente do provedor) antes do deploy para detectar erro de interpolação e de schema. - Observar `docker service ps `, `docker service logs`, réplicas desejadas vs atuais e eventos do node durante todo o rollout, não apenas no fim. - Simular falha de worker e, em ambiente autorizado e com backup validado, perda de um manager, confirmando que o quorum sobrevive com os managers restantes. - Provar rollback de aplicação (`docker service update --rollback` ou `rollback_config`) e a compatibilidade de migrations de dados durante a janela em que as duas versões coexistem. - Não declarar a stack "pronta para produção" sem esses quatro pontos verificados, "funcionou no meu node" não é evidência de convergência do cluster. ## Skills relacionadas - `$specsfy-specialist-deploy` coordena servidor, imagem, Ansible e publicação da stack, esta skill governa somente o Swarm. - `$specsfy-specialist-versioning` prepara `SEMVER` e confere a versão usada pela imagem e pelo manifesto da stack. - `$specsfy-specialist-ansible` prepara e mantém os nodes, esta skill governa quorum, scheduler, services e redes do Swarm. - `$specsfy-specialist-laravel` define os contratos da aplicação e `$specsfy-specialist-redis` a persistência/cache usados pelos services. - `$specsfy-specialist-docker` para build de imagem, Dockerfile e desenvolvimento local com Compose — fronteira: Swarm começa onde a aplicação passa a rodar em múltiplos nós com estado de cluster. - `$specsfy-specialist-delivery-engineering` quando o rollout do serviço faz parte de um pipeline de release com promoção entre ambientes. - `$specsfy-specialist-observability` para instrumentar os sinais (health, taxa de erro, latência) que decidem continuar, pausar ou reverter um rollout. - `$specsfy-specialist-debian-server` para portas do cluster, kernel, filesystem e serviço Docker dos nodes. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-docker-swarm/references/standards.md) para topologia do Raft, ciclo de vida de secrets/configs, redes overlay, estratégias de rollout e disaster recovery, com fontes oficiais da documentação do Docker. ### Especialista Modelagem de domínio no Specsfy: guia técnico - URL: https://promovaweb.com/docs/specsfy/especialistas/domain-modeling - Descrição: Consulte o guia da especialista Modelagem de domínio no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando um termo do domínio for ambíguo, dois contextos usarem a mesma palavra com sentidos diferentes, ou uma regra/invariante não tiver owner claro. - Acionar também antes de desenhar uma entidade nova quando não estiver claro se ela é entidade, value object, evento ou apenas uma projeção. - Não acionar para decidir topologia de serviços, banco ou infraestrutura — isso é `$specsfy-specialist-software-architecture`, a modelagem de domínio informa essa decisão, não a substitui. - Combinar com `$specsfy-specialist-software-architecture` quando um bounded context novo implicar um boundary de serviço ou de dados novo. ## Fluxo 1. Identificar atores, seus objetivos, os comandos que emitem, os fatos que já ocorreram (eventos) e as regras que restringem transições. 2. Coletar os termos reais usados pelas pessoas do domínio — não os nomes de tabela ou classe já existentes — e expor sinônimos e colisões de sentido. 3. Construir cenários concretos: caminho feliz, limite, falha e efeito do tempo (o que muda se o comando chegar tarde, duplicado ou fora de ordem). 4. Formular cada invariante como uma afirmação sempre verdadeira e atribuir o owner (o componente/agregado capaz de garanti-la no momento da escrita). 5. Agrupar comportamento pelo que precisa mudar junto e ser consistente imediatamente — isso define o limite do aggregate, não a conveniência de consulta. 6. Testar cada boundary proposto contra um caso que o atravessa: um dado correto no meio já quebra a fronteira, o boundary está no lugar errado. 7. Atualizar glossário, mapa de contexto e ADR na fonte autorizada do projeto — nunca criar um documento de modelo paralelo. ## Padrões - Nomear pelo vocabulário do domínio (linguagem ubíqua), nunca pela camada técnica ("Gerenciador", "Handler", "Processor" sozinhos não são domínio). - Distinguir entidade (identidade + ciclo de vida), value object (definido pelo valor, imutável), evento (fato já ocorrido, nome no passado) e projeção (leitura derivada, não fonte de verdade) pelo comportamento que cada um exige, não pela conveniência de implementação. - Manter cada invariante junto do componente capaz de garanti-la atomicamente — invariante que depende de dois agregados sem coordenação é invariante quebrada sob concorrência. - Não agrandar um aggregate para facilitar uma consulta, consultas compostas usam projeção/read model, não um aggregate maior que o necessário para consistência. - Separar bounded contexts quando o mesmo termo tem modelos legítimos e incompatíveis (ex.: "Cliente" no contexto de Vendas vs. "Cliente" no contexto de Suporte podem ter atributos e ciclo de vida diferentes). - Nomear eventos no passado ("PedidoConfirmado") e comandos no imperativo ("ConfirmarPedido") — a diferença de tempo verbal comunica se algo já aconteceu ou está sendo solicitado. - Validar cada definição com um exemplo que a satisfaz e um contraexemplo que a quebraria — uma definição sem contraexemplo geralmente é vaga demais para implementar. ## Antipadrões - **Anemic domain model**: entidades que são só sacos de campos (getters/ setters) enquanto toda a regra vive em serviços externos — perde a garantia de invariante no ponto de mutação e espalha a regra por múltiplos callers que podem esquecê-la. - Usar o mesmo nome de campo/classe em dois bounded contexts assumindo que significam a mesma coisa — força um dos dois a distorcer seu modelo para caber no vocabulário do outro. - Aggregate que cobre o "gráfico de objetos inteiro" para nunca ter que unir dados depois — cria contenção de escrita e trava concorrência que nada no domínio exige. - Documentar o modelo em um arquivo à parte da fonte autorizada (spec, código) — o documento diverge do sistema real na primeira mudança não sincronizada. ## Validação - A linguagem usada em spec, código, UI e nomes de coluna/tabela é a mesma para o mesmo conceito, e distinta quando o conceito é distinto entre contextos. - Existem cenários (exemplo + contraexemplo) que exercitam cada invariante e cada transição relevante do modelo. - Nenhum dado tem dois owners capazes de escrever de forma concorrente e inconsistente sem coordenação explícita. - As decisões de modelo (glossário, invariante, boundary) estão registradas apenas na fonte autorizada do projeto, sem cópia paralela desatualizável. - Não declarar um modelo "correto" sem os cenários acima — um modelo sem contraexemplo testado é uma hipótese, não uma validação. ## Skills relacionadas - `$specsfy-specialist-merge-conflict-resolution` preserva intenção quando conflitos atingem nomes e invariantes do modelo. - `$specsfy-specialist-prototyping` testa hipóteses do domínio sem promover o protótipo a fonte normativa. - `$specsfy-specialist-ux-design` valida o vocabulário na jornada e `$specsfy-specialist-web-api-design` o expõe como contrato público sem transferir ownership. - `$specsfy-specialist-software-architecture` quando um bounded context novo implicar um boundary de serviço, banco ou deployment. - `$specsfy-specialist-technical-research` quando a decisão de modelo depender de como um sistema externo já define o mesmo conceito. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-domain-modeling/references/standards.md) para artefatos de modelagem, perguntas-guia, e as fontes primárias de DDD e event storming. ### Especialista Gitflow no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/gitflow - Descrição: Consulte o guia da especialista Gitflow no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando a pessoa pedir explicitamente o modelo Gitflow (branches `main`/`master`, `develop`, `feature/*`, `release/*`, `hotfix/*`) ou quando já existir configuração `git flow` (`git config --get-regexp '^gitflow\.'`) ou instrução do projeto declarando essa escolha. - Acionar também para nomear, sequenciar ou fechar uma branch `feature/`, `release/` ou `hotfix/` dentro de um projeto que já declarou Gitflow como estratégia de branch. - Não acionar para propor Gitflow a um projeto que não pediu isso — a escolha do modelo de branch é decisão explícita de quem conduz o projeto, nunca inferida pela presença de uma branch chamada `develop` ou pelo volume de branches abertas. - Não acionar para resolver um conflito já em andamento (`$specsfy-specialist-merge-conflict-resolution`) nem para desenhar o pipeline ou a promoção de artefato entre ambientes (`$specsfy-specialist-delivery-engineering`) — aqui o foco é a topologia e a política das branches, não a resolução textual nem a entrega. ## Fluxo 1. Confirmar que a pessoa pediu Gitflow explicitamente, ou apontar a configuração/instrução existente que já declara essa escolha, antes de aplicar qualquer convenção — nunca presumir Gitflow a partir da estrutura do repositório. 2. Verificar o estado real das branches (`git branch -a`, `git config --get-regexp '^gitflow\.'`) para saber se `main`/`master` e `develop` já existem e se a nomenclatura das branches auxiliares já diverge do padrão adotado. 3. Definir com a pessoa os nomes das branches permanentes (`main` de produção, `develop` de integração) e os prefixos das branches de vida curta (`feature/`, `release/`, `hotfix/`, `support/` quando aplicável). 4. Registrar a decisão como regra confirmada do projeto (`$specsfy-aux-rules` grava em `.specsfy/RULES.md`), incluindo prefixos, branch-alvo de cada tipo e política de merge — não deixar a convenção apenas verbal. 5. Orientar a abertura, a integração e o fechamento de cada tipo de branch: `feature/*` parte de e volta para `develop`, `release/*` parte de `develop` e vai para `main` e `develop`, `hotfix/*` parte de `main` e vai para `main` e `develop`, sempre com `merge --no-ff`. 6. Coordenar a tag de versão no merge de `release/*` ou `hotfix/*` em `main`, alinhando com a estratégia de versionamento já adotada pelo projeto (semver ou outra). 7. Verificar que `develop` recebeu de volta toda correção aplicada em `release/*` ou `hotfix/*` antes de considerar o ciclo fechado — divergência aqui reaparece como regressão no próximo release. ## Padrões - Usar `git merge --no-ff` para toda integração de `feature/*`, `release/*` e `hotfix/*` — merge fast-forward apaga o registro de que aquela branch existiu, do qual a auditoria de release do Gitflow depende. - Nomear com prefixo consistente e o mesmo separador em todo o projeto (`feature/`, `release/`, `hotfix/`), não misturar convenções (`feature-x` e `feature/y` no mesmo repositório). - Fazer `release/*` e `hotfix/*` partirem exatamente do commit de `develop` ou `main` correspondente, sem cherry-pick seletivo de commits ainda não integrados. - Aplicar em `release/*` somente correção de bug, texto, documentação e preparação de release (changelog, versão) — funcionalidade nova não entra numa branch de release já aberta, volta para a próxima `feature/*`. - Fechar todo `hotfix/*` mesclando em `main` (com tag) e em `develop` (ou na `release/*` aberta, se houver uma) na mesma operação — hotfix que só chega em `main` desaparece do próximo release. - Apagar a branch de vida curta (`feature/*`, `release/*`, `hotfix/*`) depois do merge confirmado nos dois destinos — branch finalizada e não apagada convida retrabalho sobre código já integrado. ## Antipadrões - Push direto ou merge fast-forward em `main`/`develop` sem passar por `feature/`, `release/` ou `hotfix/`: quebra a rastreabilidade que justifica adotar Gitflow em vez de um modelo mais simples. - Funcionalidade nova adicionada dentro de uma `release/*` já aberta "para aproveitar a janela": aumenta o escopo testado depois do corte e atrasa a liberação sem necessidade. - Hotfix mesclado apenas em `main`, deixando `develop` divergente: a próxima `release/*` cortada de `develop` reintroduz o bug já corrigido em produção. - Adotar Gitflow num projeto com deploy contínuo várias vezes ao dia: a sobrecarga de branches longas de `release`/`hotfix` conflita com entrega contínua, nesse contexto, avalie com a pessoa se GitHub Flow ou trunk-based atende melhor antes de aplicar Gitflow por hábito. - Confundir "temos uma branch chamada develop" com "o projeto usa Gitflow": sem a política de merge, os prefixos e o ciclo de release completos, é apenas uma branch com esse nome, não o modelo. ## Validação - `git log --graph --oneline --all` (ou `git log --first-parent main`) mostrando os merges `--no-ff` de cada `feature/`, `release/` ou `hotfix/` como commits de merge identificáveis, não commits lineares indistinguíveis. - `git branch -a --merged develop` e `git branch -a --merged main` conferidos antes de apagar uma branch de vida curta, garantindo que o merge realmente aconteceu nos dois destinos esperados. - Tag de versão presente em `main` para cada `release/*` ou `hotfix/*` fechado (`git tag --contains `), e a mesma correção presente em `develop` (`git log develop --oneline | grep ` ou equivalente). - `.specsfy/RULES.md` (ou instrução equivalente do projeto) registrando a convenção de nomes e a política de merge, revisitada por `$specsfy-aux-rules` quando alguém a violar. - Não declarar "o projeto segue Gitflow" apenas porque existe uma branch `develop`, a evidência exige prefixos consistentes, merges `--no-ff` rastreáveis e o ciclo de `release`/`hotfix` fechado nos dois destinos. ## Skills relacionadas - `$specsfy-specialist-merge-conflict-resolution` quando uma integração de `feature/`, `release/` ou `hotfix/` já em andamento gerar conflito — esta skill decide a topologia e a política de branch, a outra resolve o conflito textual ou semântico já aberto. - `$specsfy-specialist-delivery-engineering` quando o merge em `main` ou a tag de release precisar disparar pipeline, build de artefato ou promoção entre ambientes — esta skill entrega a branch e a tag corretas, a outra decide como o pipeline reage a elas. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-gitflow/references/standards.md) para o mapa completo de branches, os comandos `git flow` equivalentes em Git puro e as fontes oficiais do modelo. ### Especialista Experiência de Interface no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/interface-experience - Descrição: Consulte o guia da especialista Experiência de Interface no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar ao criar ou alterar tela, dashboard, lista, formulário, jornada ou CRUD usado por pessoas. - Acionar antes de UX, UI e implementação para entender o sistema existente e organizar a conversa sobre a interface. - Não usar para endpoint, job ou mudança interna sem superfície para pessoas. ## Fluxo 1. Carregar `$specsfy-setup` e ler `.specsfy/STACK.md`, `.specsfy/PACKAGES.md`, manifests, instruções locais e documentação atual. Carregar `$specsfy-specialist-design-system` e ler `DESIGNSYSTEM.MD` antes de propor qualquer tela. Se o arquivo não existir, criar a fonte a partir de `.specsfy/templates/DESIGNSYSTEM.MD`. Executar `node .agents/skills/specsfy-setup/scripts/inspect_interface.mjs --project ` para localizar rotas, componentes e tecnologias antes da leitura detalhada. 2. Examinar as telas, fluxos, rotas, componentes, conteúdo, permissões, estados e testes ligados à área afetada. Registrar o que a pessoa já consegue fazer, o que deve permanecer e o que a entrega muda. 3. Identificar framework, roteamento, primitives, estilos, formulários e runner de testes usados pelo projeto. Seguir essas fontes e não trocar tecnologia ou biblioteca sem confirmação da pessoa. 4. Aplicar o contrato central de perguntas somente para lacunas reais: perguntar uma lacuna por rodada sobre telas, fluxo de informação, formulário, formato de ação e composição. Quando a pessoa não informa direção visual, aplicar os defaults de `DESIGNSYSTEM.MD` e registrar a direção padrão. Só perguntar sobre composição quando o pedido contrariar uma regra existente. Oferecer opções textuais compatíveis com o sistema atual, `Escrever outra resposta`, `Gere outras opções` e `Avançar`. 5. Registrar na seção 10 da spec a stack observada, cada tela, o fluxo, os formulários, a composição, os estados e a acessibilidade. Um CRUD não pode ficar restrito a API, banco ou serviço. Para CRUD, mapear sempre lista com `PageHeader` e `DataGrid` com detalhe clicável por linha, detalhe com `PageHeader` e `DetailLists`, e criar ou editar com `PageHeader` e seções de formulário em duas colunas responsivas. Toda tela também deve mapear `Breadcrumb` com equipe, módulo e tela atual, em Laravel, reaproveitar o componente já usado pelo layout. O `PageHeader` é um único componente reutilizável entre essas telas. A listagem ocupa a largura disponível, mostra o `ID` em coluna própria e oferece editar e apagar na linha, além do link para o detalhe. 6. Criar na seção 14 a `Fase de interface`, com uma tarefa por tela e testes para navegação, formulário, validações, feedback e teclado. 7. Chamar `$specsfy-specialist-ux-design` para jornada e `$specsfy-specialist-ui-design` para composição. Em projetos React, carregar `$specsfy-specialist-react-ui-components` para selecionar, reaproveitar e adaptar componentes antes de escrever JSX ou TSX, além de `$specsfy-specialist-react` para a implementação da stack. Para outra tecnologia, carregar o especialista equivalente detectado pelo setup. ## Resultado esperado Uma interface informativa, funcional e reconhecível para a tarefa, coerente com o sistema existente e com a personalidade do produto. O plano mostra telas, formulários, estados, regras de negócio, componentes e testes. A implementação preserva tudo fora do alcance registrado. ## Padrões - Mapear cada tela, ação, formulário, estado e retorno no plano. - Preservar a stack, os componentes e os padrões de navegação já observados. - Registrar teclado, foco, responsividade e mensagens junto da tela afetada. - Renderizar `Breadcrumb` em todas as telas, mantendo o nome da equipe ativa visível. Em Laravel, reutilizar `Breadcrumb` ou `Breadcrumbs` existente e sua tipagem de itens. - Aplicar `DESIGNSYSTEM.MD` como fonte macro e `INTERFACE.md` como registro local. - Usar `DataGrid`, `DetailLists` e `PageHeader` nas superfícies CRUD definidas, a linha abre o detalhe e controles internos permanecem independentes. - Reutilizar o mesmo `PageHeader` componentizado em todas as telas CRUD, manter `DataGrid` em largura total com `ID`, editar e apagar visíveis na linha. - Conferir bordas, espaçamentos, margens, padding e tipografia durante o desenvolvimento, mesmo sem pedido da pessoa, e registrar o resultado no item `VISUAL` da tarefa. - Organizar criar e editar em seções com coluna de contexto, painel em duas colunas nos breakpoints largos e uma coluna no mobile. - Mostrar erro de campo em vermelho, com mensagem abaixo do campo e foco útil. - Projetar a hierarquia pelos dados, linguagem e estados do produto, sem cair em uma composição visual genérica. ## Antipadrões - Propor uma tela sem ler as rotas e os componentes atuais. - Tratar CRUD como endpoint sem descrever a interação da pessoa. - Validar somente o estado feliz e ignorar vazio, erro ou permissão. ## Validação - Confirmar que a pessoa recebeu pergunta sobre as telas em toda entrega que cria ou altera uma interface. - Conferir que a seção 10 registra a stack e o sistema atual antes da proposta. - Confirmar que `DESIGNSYSTEM.MD` foi lido ou criado e que a direção padrão ou exceção está registrada com alcance. - Executar `validate_spec.mjs`, `validate_tasks.mjs` e `validate_interface_tasks.mjs` conforme a etapa. - Verificar mobile e desktop, loading, vazio, erro, sucesso, permissão, teclado e foco antes de concluir a interface. ## Skills relacionadas - `$specsfy-specialist-ux-design` para jornada, tarefas e conteúdo. - `$specsfy-specialist-ui-design` para composição visual e estados. - `$specsfy-specialist-react-ui-components` para selecionar e reaproveitar componentes nas telas React. - `$specsfy-specialist-design-system` para regras macro, defaults e cenários CRUD. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-interface-experience/references/standards.md) para fontes de acessibilidade e inspeção de interfaces. ### Especialista Laravel no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/laravel - Descrição: Consulte o guia da especialista Laravel no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o repositório tem `artisan`, `composer.json` com `laravel/framework`, e a tarefa envolve rotas, controllers, models, policies, form requests, jobs, eventos, cache, config ou testes Laravel. - Acionar também para revisão de PR Laravel, diagnóstico de N+1, fila travada, autorização quebrada ou migration arriscada. - Não acionar para decisão pura de schema, índice ou plano de query — usar `$specsfy-specialist-postgres` e trazer o resultado para o Eloquent. - Combinar com `$specsfy-specialist-application-security` quando a mudança tocar autenticação, mass assignment, upload ou dado sensível, e com `$specsfy-specialist-supabase` quando o Postgres for gerenciado por Supabase em vez de instância própria. ## Fluxo 1. Ler `composer.json`/`composer.lock` para confirmar versão do framework, PHP e pacotes relevantes (Sanctum, Horizon, Octane, Scout) antes de supor comportamento por memória. 2. Tratar Laravel Octane com Open Swoole e o pacote `laravel/octane` como runtime obrigatório. Quando estiver ausente, incluir instalação e configuração no trabalho antes de considerar a aplicação pronta para execução ou deploy. 3. Mapear a requisição do ponto de entrada até domínio, persistência, efeitos assíncronos e resposta, identificando o boundary onde a regra de negócio já vive no projeto (Action, Service, Model rico). 4. Localizar convenções irmãs — como o projeto organiza Form Requests, Policies, Resources e Jobs — e seguir o padrão existente em vez de introduzir um novo. 5. Definir autorização, validação, transação, idempotência e modo de falha antes de escrever código, especialmente para jobs e webhooks. 6. Escrever o teste focal (Pest ou PHPUnit conforme o projeto), implementar a menor fatia que o torna verde e então refatorar. 7. Se a tarefa criar ou alterar schema, tabela, coluna, índice, relação ou model persistente, exigir a tarefa `[MIGRATION]`, criar o arquivo com `php artisan make:migration`, aplicar no banco de teste e conferir com `php artisan migrate:status --env=testing`. 8. Inspecionar as queries geradas (`DB::listen`, Telescope, Debugbar ou `EXPLAIN` via `$specsfy-specialist-postgres`) quando cardinalidade ou latência importarem. 9. Executar testes, análise estática (Larastan/PHPStan) e formatter (Pint) disponíveis no projeto antes de considerar a tarefa concluída. 10. Verificar impacto operacional — migration em produção, workers, scheduler, cache de config — e registrar risco quando a ação exigir autorização externa. ## Padrões - Executar HTTP com Laravel Octane, Open Swoole e `--server=swoole`. Instalar a extensão `openswoole` na imagem e limpar estado por requisição, singletons e propriedades estáticas não podem transportar dados entre usuários nos workers persistentes. - Manter controllers finos: validação em Form Requests, autorização em Policies/Gates, regra de negócio no boundary já adotado pelo projeto. - Tratar Eloquent como acesso a dados: eager load explícito (`with`, `withCount`) sempre que uma coleção acessar relação em loop, nunca escrever N+1 e justificar "está rápido o bastante por enquanto". - Selecionar colunas (`select`) quando a tabela for larga ou a listagem não precisar do model completo, preferir `chunkById`/`lazyById` para varreduras grandes em vez de carregar tudo em memória. - Projetar jobs idempotentes: `ShouldBeUnique`/lock quando duplicidade for possível, timeout e tentativas explícitos, `failed()` tratando o efeito colateral de falha definitiva. - Migrations compatíveis com o volume real: `expand → migrar dado → contract` para mudança incompatível em tabela grande, nunca um único `ALTER` bloqueante sem medir o lock esperado. - Nunca confiar em validação do cliente nem autorizar somente na UI — Policy/Gate roda no servidor em toda ação e em todo objeto, não só na rota de criação. - Proteger mass assignment com `$fillable` (ou `$guarded` deliberado) e nunca passar `$request->all()` direto para `create`/`update` sem validação prévia. - Não criar abstração, evento, pacote ou camada extra sem um segundo consumidor real e benefício verificável — três controllers parecidos não justificam um framework interno. - Exigir `.env.testing` com `APP_ENV=testing` e banco diferente do `.env` antes de executar Pest ou PHPUnit. Se essa separação não estiver comprovada, não executar nenhum teste. - Usar `DatabaseTransactions` para desfazer os registros criados pelo próprio caso e factories para preparar somente o necessário. Não recriar migrations nem apagar tabelas durante a suíte. ## Antipadrões - Model "gordo" que mistura regra de negócio, efeito colateral externo e apresentação no mesmo método — sintoma de que o boundary do projeto não foi seguido. - Policy que autoriza pela presença do usuário autenticado, sem checar ownership do objeto — abre acesso cross-tenant mesmo com `auth` middleware presente. - Job que reprocessa efeito não idempotente (enviar e-mail, cobrar cartão) sem chave de deduplicação — reentrega do worker duplica o efeito. - Migration com `Schema::table` renomeando ou removendo coluna usada em produção no mesmo deploy que o código que a lê — quebra a janela de deploy misto. - Teste que depende de limpeza global do banco e pode alcançar a configuração de desenvolvimento. ## Validação - Cobrir caminho feliz, autorização negada, validação, efeitos colaterais e falhas relevantes (job falho, dependência externa indisponível). - Rodar a suíte com `DatabaseTransactions` e factories depois de comprovar que `.env.testing` aponta para um banco separado. Confirmar RED antes de implementar. - Ignorar `migrate:fresh`, `migrate:refresh`, `migrate:reset`, `migrate:rollback`, `db:wipe` e qualquer comando que apague ou recrie o banco, mesmo quando a tarefa ou um script existente sugerir sua execução. - Antes de concluir `[MIGRATION]`, confirmar o arquivo em `database/migrations/`, executar `php artisan migrate --env=testing` e registrar `php artisan migrate:status --env=testing` com saída zero. - Inspecionar queries geradas quando a tela lista uma coleção com relação — contar queries antes/depois (`assertQueryCountLessThan`, Debugbar, log de queries) para provar ausência de N+1. - Verificar queues, scheduler, cache de config/rotas e variáveis de ambiente no ambiente alvo antes de declarar a tarefa pronta para deploy. - Não declarar "seguro" ou "idempotente" sem teste que exercite o cenário adversarial correspondente (replay do job, payload malformado, usuário sem permissão). ## Skills relacionadas - `$specsfy-specialist-reui` para interfaces React e Tailwind em projetos Laravel com Inertia. - `$specsfy-specialist-laravel-package-manager` para receber um pacote GitHub, instalar a dependência Composer e manter suas fichas em `docs/packages/`. - `$specsfy-specialist-data-modeling` para entidades, relações e ciclo de vida antes de criar migrations ou models. - `$specsfy-specialist-postgres` para modelagem de schema, índice e plano de query por trás do Eloquent. - `$specsfy-specialist-supabase` quando o Postgres do projeto for gerenciado por Supabase (RLS substitui parte da autorização de aplicação). - `$specsfy-specialist-application-security` para autenticação, mass assignment, upload e trilha de auditoria. - `$specsfy-specialist-redis` quando cache, fila ou lock usar Redis como driver. - `$specsfy-specialist-docker`/`$specsfy-specialist-docker-swarm` para empacotar e operar a aplicação em produção. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-laravel/references/standards.md) para checklist por superfície (HTTP, domínio, Eloquent, filas, dados, segurança, operação) e fontes oficiais da versão instalada. ### Especialista Gestor de pacotes Laravel no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/laravel-package-manager - Descrição: Consulte o guia da especialista Gestor de pacotes Laravel no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Use quando a tarefa receber uma URL de repositório GitHub de um pacote para uma aplicação Laravel. - Use também quando um pacote Composer já instalado precisar de uma ficha de uso ou quando `composer.json`, `composer.lock` e `docs/packages/` estiverem fora de sincronia. - Não use para pacotes npm, para PHP sem Laravel ou para publicar uma biblioteca no Packagist. ## Fluxo 1. Confirme a raiz do projeto e normalize a URL HTTPS do GitHub para `github.com//`. Aceite somente segmentos com letras minúsculas, números, ponto, sublinhado ou hífen, recuse URLs que não apontem para um repositório GitHub identificável. 2. Leia as instruções locais, `composer.json`, `composer.lock`, `.specsfy/PACKAGES.md`, `docs/packages/README.md` e as fichas existentes antes de propor qualquer pacote ou comando. Considere os pacotes já instalados antes de procurar uma alternativa nova. 3. Consulte no repositório informado o `composer.json`, o README, a documentação de configuração, a versão publicada e os exemplos de uso. Registre separadamente o que a fonte declara, o que o projeto local mostra e o que ainda não foi confirmado. 4. Identifique o nome Composer, a versão do PHP, as versões do Laravel, os requisitos adicionais, o comando de instalação, os arquivos de configuração, os comandos de publicação e a forma de teste. Se o repositório não expuser um pacote Composer compatível, pare antes de alterar o projeto e explique a lacuna. Se o pacote não estiver publicado no Packagist, confira `repositories` no manifest e peça autorização específica antes de acrescentar uma origem VCS. 5. Procure o pacote em `composer.json`, `composer.lock`, `vendor/composer/` e no código. Se ele já estiver instalado, reutilize-o e não execute outro `composer require`. 6. Quando o pacote ainda não existir e a solicitação atual autorizar a instalação, execute na raiz do projeto `composer require `. Use `--dev` somente quando o próprio projeto tratar o pacote como dependência de desenvolvimento. Não execute comandos de pós-instalação copiados do README sem conferir sua finalidade e autorização. 7. Crie ou atualize `docs/packages/-.md` com nome Composer, versão do lockfile, URL GitHub, finalidade, instalação, configuração, uso observado no projeto, testes e fontes consultadas. Preserve notas humanas fora da seção gerenciada. 8. Crie ou atualize `docs/packages/README.md` como índice de todos os pacotes Composer declarados pelo projeto, com versão, finalidade curta e link para cada ficha. Aponte para `.specsfy/PACKAGES.md` quando a pessoa precisar da relação completa, incluindo dependências transitivas. ## Padrões - `composer.lock` informa a versão instalada, nunca derive uma versão apenas da tag mais recente do GitHub ou de uma restrição do manifest. - O nome da ficha usa o nome Composer normalizado, com `/` convertido em `-`. A mesma ficha deve continuar sendo atualizada quando a versão mudar. - O índice lista dependências de produção e desenvolvimento separadamente e não transforma uma dependência transitiva em escolha do projeto. - Cada ficha informa o ponto de entrada real usado pela aplicação, como provider, facade, middleware, command, migration, config ou classe, quando esse ponto existir no código local. - Comandos de instalação, publicação e teste aparecem acompanhados da razão para executá-los e do arquivo que deve mudar. - Nunca copie segredos, valores de `.env`, código inteiro do pacote ou documentação extensa de terceiros para `docs/packages/`. ## Antipadrões - Instalar antes de ler o `composer.json` e o lockfile: pode introduzir uma versão incompatível ou repetir uma dependência já presente. - Tratar qualquer repositório PHP como pacote Laravel: isso mistura biblioteca genérica, aplicação e extensão sem identificar o contrato Composer. - Executar `php artisan vendor:publish`, migrations ou scripts do pacote sem confirmar o efeito e a autorização: esses comandos podem alterar arquivos, banco ou configuração. - Criar uma ficha genérica baseada somente no README: a documentação deixa de explicar como o pacote aparece no projeto consumidor. ## Validação - Confirme que a URL, o nome Composer, a versão e os requisitos aparecem em fontes primárias ou nos arquivos locais correspondentes. - Execute `composer validate --strict` e confira `composer show ` quando o pacote estiver instalado. - Rode os testes, formatter e análise estática já disponíveis no projeto, não introduza um runner novo só para validar o pacote. - Confira que `docs/packages/README.md` lista cada dependência direta do `composer.json`, que cada link aponta para uma ficha existente e que a ficha informa quando a finalidade ainda não foi confirmada. - Verifique links, comandos, nomes de configuração e exemplos contra a versão instalada. Não declare compatibilidade, segurança ou funcionamento sem uma fonte ou teste correspondente. ## Skills relacionadas - `$specsfy-specialist-laravel` orienta o uso do pacote dentro de HTTP, Eloquent, filas, autorização e testes Laravel. - `$specsfy-specialist-technical-research` ajuda a comparar documentação, versões e fontes primárias quando o repositório não esclarecer uma dúvida. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-laravel-package-manager/references/standards.md) para o contrato das fichas, a hierarquia de fontes e os comandos Composer aplicáveis. ### Especialista Resolução de conflitos Git no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/merge-conflict-resolution - Descrição: Consulte o guia da especialista Resolução de conflitos Git no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando um `git merge`, `git rebase` ou `git cherry-pick` já está em andamento e há arquivos marcados como unmerged. - Não acionar para decidir qual branch deveria ter ganho a mudança em termos de produto — isso é decisão de quem pediu a integração, esta skill resolve o texto e o comportamento resultante, não reabre a decisão de negócio. - Combinar com `$specsfy-specialist-code-review` depois da resolução — o resultado combinado precisa da mesma revisão que qualquer diff novo teria. ## Fluxo 1. Inspecionar o estado exato da operação (merge, rebase, cherry-pick), quais branches/commits estão envolvidos e quais arquivos estão unmerged. 2. Para cada hunk em conflito, recuperar a intenção de cada lado — o que a mudança tentava alcançar, não apenas o texto literal. 3. Classificar o conflito: textual (mesma linha, texto diferente), estrutural (mesma função/bloco reorganizado), semântico (sem marcador de texto, mas comportamento incompatível — ex.: assinatura mudou de um lado, caller não ajustado do outro) ou gerado (lockfile, arquivo build). 4. Construir o resultado que preserva as duas intenções quando elas são compatíveis — a resolução correta raramente é escolher um lado inteiro. 5. Quando as intenções são genuinamente incompatíveis, escolher pelo objetivo da integração (o que a spec/issue que motivou a integração pede) e registrar o trade-off descartado. 6. Remover todos os marcadores de conflito, validar sintaxe/parse do arquivo e rodar os checks focais (lint, typecheck) nos arquivos tocados. 7. Continuar a operação (`git merge --continue`/`git rebase --continue`) e executar a suíte de regressão relevante antes de publicar. ## Padrões - Nunca usar `git checkout --ours`/`--theirs` (ou resolução estratégica `-X ours`/`-X theirs`) em lote por conveniência — cada hunk pode ter uma resolução correta diferente, aplicar uma estratégia global descarta mudanças reais de um dos lados sem revisão. - Não editar um arquivo gerado (lockfile, build output, código gerado) sem atualizar a fonte que o gera e regenerar — editar o gerado diretamente diverge na próxima geração. - Preservar mudanças de schema, migrations, testes e contratos de API de ambos os lados quando elas não colidem de fato — um conflito num arquivo vizinho não autoriza descartar uma mudança de schema em outro. - Reavaliar imports, renomes e chamadas mesmo em arquivos sem marcador textual — um rename de um lado e um novo uso do nome antigo do outro lado não gera conflito Git, mas quebra em runtime ou build. - Não introduzir comportamento novo além do estritamente necessário para resolver o conflito — a resolução não é uma oportunidade de refactor. - Não usar `--abort`, force push ou reset destrutivo sem pedido explícito de quem está conduzindo a integração — a operação em andamento pode representar trabalho de resolução já feito por outra pessoa. - Conferir ao final que nenhum arquivo permanece unmerged e que o índice está limpo antes de continuar a operação. ## Antipadrões - Resolver "compilando" apenas: o arquivo perde os marcadores e builda, mas o comportamento resultante nunca foi comparado contra a intenção de nenhum dos dois lados — conflito semântico sobrevive disfarçado de resolvido. - Rebase que reescreve commits já publicados e compartilhados sem alinhar com quem mais trabalha sobre eles — quebra o histórico de outra pessoa silenciosamente. - Resolver todos os hunks de um arquivo grande de uma vez sem revisar cada um isoladamente — aumenta a chance de aceitar um hunk errado por fadiga. - Confiar em `git rerere` para repetir uma resolução anterior sem reconfirmar que o contexto ao redor não mudou o suficiente para invalidar a resolução gravada. ## Validação - `git status` sem nenhum arquivo unmerged e sem marcador de conflito residual em nenhum arquivo (`grep` por `<<<<<<<` no diretório de trabalho). - Diff combinado revisado hunk a hunk contra a intenção reconstruída de ambos os lados. - Typecheck, build e testes focais dos arquivos tocados executados, mais a suíte de regressão relevante ao comportamento integrado. - Histórico resultante e o destino do push (branch, force ou não) confirmados antes de publicar — nunca publicar uma resolução sem essa checagem quando o histórico foi reescrito. - Não declarar a integração "resolvida" sem essa evidência — resolução sem build/teste revalidado é apenas ausência de marcador, não correção comprovada. ## Skills relacionadas - `$specsfy-specialist-code-review` para revisar o resultado combinado como qualquer diff novo, já que a resolução pode introduzir comportamento não coberto pelos PRs originais isoladamente. - `$specsfy-specialist-domain-modeling` quando o conflito semântico revelar que dois lados modelaram o mesmo conceito de domínio de forma incompatível — o conflito é sintoma de um boundary não alinhado. - `$specsfy-specialist-gitflow` quando o merge/rebase em conflito envolver `feature/`, `release/` ou `hotfix/` de um projeto que declarou Gitflow — aquela skill decide a topologia e o destino do merge, esta resolve o conflito textual ou semântico já aberto. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-merge-conflict-resolution/references/standards.md) para comandos de diagnóstico, tipos de conflito sem marcador textual e fontes oficiais do Git. ### Especialista Next.js no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/nextjs - Descrição: Consulte o guia da especialista Next.js no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto depende de `next`/`next.config` e a tarefa envolve rota, layout, Server/Client Component, Server Action, route handler, cache, middleware, metadata ou deploy. - Acionar também para diagnosticar waterfalls de dados, hydration mismatch, ou cache servindo dado obsoleto/entre usuários. - Não acionar para hooks, estado ou composição de componentes que não dependem do framework, usar `$specsfy-specialist-react` nesse caso e voltar aqui só para a fronteira server/client. - Combinar com `$specsfy-specialist-application-security` quando a rota expõe mutation, upload ou dado sensível, e com `$specsfy-specialist-performance-engineering` quando o sintoma for Web Vitals ou TTFB fora do SLO. ## Fluxo 1. Confirmar versão do Next.js, router (App ou Pages), runtime (Node vs Edge), deployment target e flags experimentais ativas — a semântica de cache e de Server Components muda entre versões. 2. Mapear a rota alterada: layout, `loading`, `error`, `not-found` e onde está o boundary entre dado (server) e interação (client). 3. Manter componentes Server por padrão, marcar `"use client"` apenas no componente folha que realmente precisa de hook, evento ou API do navegador — nunca no layout ou página inteira por conveniência. 4. Definir explicitamente cache, revalidação e tags de cada fonte de dado, tratar o comportamento padrão como contrato da versão instalada, não como suposição. 5. Validar entrada e checar autorização dentro de cada Server Action e route handler, como se fosse um endpoint HTTP público — porque é. 6. Projetar metadata, streaming (`loading.js`/`Suspense`), imagens/fontes e o caminho de recuperação de erro (`error.js`, `not-found.js`). 7. Executar lint, typecheck, testes, build de produção e checar o resultado no runtime real do adapter/host alvo, não só no `next dev`. ## Padrões - Não mover a árvore inteira para `"use client"` para "resolver" um erro de hook, isolar a interatividade no componente folha certo. - Nunca importar segredo, cliente de banco ou módulo server-only dentro de um Client Component — o bundler pode incluí-lo no JS enviado ao navegador. - Colocar o fetching o mais próximo possível de quem consome o dado, medir e eliminar waterfalls sequenciais evitáveis (requisições que dependem umas das outras sem necessidade real). - Tratar cache como contrato explícito por rota: declarar se cada fonte de dado é estática, revalidada por tempo, revalidada por tag ou dinâmica — nunca herdar o default sem checar a versão instalada. - Revalidar (`revalidatePath`/`revalidateTag`) imediatamente após qualquer mutation que afete dado já cacheado, sem isso a UI mostra estado obsoleto. - Proteger toda Server Action com a mesma disciplina de um endpoint público: autenticar, autorizar por objeto e validar payload — o cliente pode chamá-la diretamente, fora do fluxo de UI esperado. - Usar middleware apenas para lógica curta e compatível com o runtime da rota (Edge tem API restrita), lógica pesada pertence ao route handler ou à camada de aplicação. - Documentar qualquer acoplamento a comportamento específico do host/adapter (headers, streaming, limites de tempo) em vez de deixá-lo implícito. ## Antipadrões - `"use client"` no topo de `layout.tsx` ou `page.tsx` só porque um filho precisa de interatividade — arrasta toda a subárvore para o cliente e perde os benefícios de Server Components. - Buscar o mesmo dado em múltiplos componentes aninhados sem cache ou deduplicação, criando uma cascata de requisições sequenciais visível no waterfall de rede. - Mutar dado via Server Action e não revalidar o path/tag correspondente — a UI parece "quebrada" porque mostra o cache antigo até o próximo refresh completo. - Confiar em variável de ambiente sem prefixo público (`NEXT_PUBLIC_`) dentro de um Client Component — ela não existirá no bundle do navegador. - Tratar uma Server Action como "só acessível pela UI" e pular autorização — ela é uma rota HTTP como outra qualquer e pode ser chamada diretamente. ## Validação - `next build` completo (mais lint/typecheck do projeto) e leitura do relatório de rotas que ele imprime (estático `○`, dinâmico `λ`, ISR), conferir se isso bate com a intenção declarada no passo 4 do Fluxo. - Exercitar `loading`, `error`, `not-found`, redirects e autorização em cada rota alterada, incluindo acesso direto por URL sem navegação client-side. - Provar cache hit/miss e invalidation: mutar o dado, checar que a rota revalida, e confirmar que nenhum dado vaza entre usuários/sessões diferentes por chave de cache mal escopada. - Medir bundle do cliente, imagens, fontes e Web Vitals (LCP, INP, CLS) antes e depois da mudança quando a rota for sensível a performance. - Não declarar uma rota "seções server-first" ou "cache correto" sem essa evidência, linguagem absoluta sem prova é proibida. ## Skills relacionadas - `$specsfy-specialist-astro` cobre projetos Astro e suas ilhas, não transportar cache ou fronteiras server/client entre os frameworks. - `$specsfy-specialist-web-accessibility` aprofunda WCAG, foco e tecnologia assistiva nas rotas e Client Components. - `$specsfy-specialist-react` para hooks, estado, efeitos e composição independentes do framework — use em conjunto para qualquer Client Component não trivial. - `$specsfy-specialist-react-ui-components` e `$specsfy-specialist-ui-design` para a biblioteca visual e a composição de página, antes de decidir a fronteira server/client aqui. - `$specsfy-specialist-application-security` para autorização, upload e dado sensível em Server Actions e route handlers. - `$specsfy-specialist-performance-engineering` para investigar Web Vitals, TTFB ou regressão de performance com metodologia própria. - `$specsfy-specialist-typescript` para tipar params de rota, payload de Server Action e retorno de data fetching de forma segura. - `$specsfy-specialist-tailwind-css` e `$specsfy-specialist-shadcn-ui` para a camada de estilo e os componentes visuais renderizados dentro de cada Server/Client Component. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-nextjs/references/standards.md) para fronteiras server/client, cache, Server Actions, streaming, segurança e checklist de produção, com fontes oficiais. ### Especialista Observabilidade no Specsfy: fluxo e validação - URL: https://promovaweb.com/docs/specsfy/especialistas/observability - Descrição: Consulte o guia da especialista Observabilidade no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto no código. ## Quando usar - Acionar quando o pedido envolve instrumentação (logs, métricas, traces), investigação de incidente, definição de SLI/SLO ou construção de dashboard/alerta. - Acionar também para definir o sinal objetivo que autoriza continuar, pausar ou reverter um rollout. - Não acionar para diagnosticar a causa raiz de uma latência específica já detectada — usar `$specsfy-specialist-performance-engineering` para profiling e otimização, observability aqui é sobre desenhar o sistema de sinais, não sobre investigar um caso pontual já instrumentado. - Combinar com `$specsfy-specialist-delivery-engineering` quando o sinal definido aqui vai decidir um `failure_action` de rollout. ## Fluxo 1. Definir as perguntas operacionais reais ("o checkout está funcionando para o usuário?") e as jornadas críticas antes de escolher qualquer ferramenta. 2. Estabelecer SLIs (indicadores medíveis) e SLOs (alvo aceitável) com orçamento de erro explícito quando o serviço tiver criticidade que justifique. 3. Mapear os trust/system boundaries (HTTP, fila, job, banco) e o contexto de correlação que precisa atravessá-los (trace id, request id). 4. Instrumentar eventos, métricas e spans com cardinalidade controlada desde o desenho, não como correção posterior. 5. Proteger dados sensíveis na telemetry (redaction, mascaramento) e definir política de retenção por tipo de sinal. 6. Construir dashboards organizados por decisão (o que essa tela me ajuda a decidir?) e alertas organizados por ação (o que eu faço quando esse alerta dispara?). 7. Validar a telemetry nos três estados — sucesso, falha e degradação parcial — antes de confiar nela durante um incidente real. ## Padrões - Logs estruturados (chave-valor ou JSON) com evento nomeado, severidade, identificador de correlação e contexto mínimo necessário — nunca uma string livre concatenada que exige regex para extrair dado. - Métricas usam apenas labels de cardinalidade limitada e conhecida (endpoint normalizado, código de status, tenant se o volume de tenants for baixo), nunca user id, URL crua com query string ou mensagem de erro bruta como label — cada valor único de label multiplica as séries armazenadas. - Traces preservam o mesmo contexto de correlação atravessando HTTP, fila e job assíncrono — um trace que "quebra" na borda de uma fila não serve para depurar o problema mais comum (latência distribuída entre serviços). - Alertas refletem impacto real ao usuário ou risco iminente de violar o SLO, e todo alerta tem owner e runbook alcançável — alerta sem ação associada é ruído que treina a equipe a ignorar alertas. - Dashboards começam pela visão de saúde agregada (RED/USE) e permitem drill-down até o sinal granular, não o inverso. - Sampling de traces preserva 100% dos erros e das transações de negócio crítico, mesmo reduzindo a amostragem do caminho feliz de alto volume. - A própria telemetry falha de modo seguro (degrada, não derruba o produto) — um exportador de métricas fora do ar nunca pode derrubar a aplicação que instrumenta. ## Antipadrões - "Logar tudo" sem estrutura nem nível de severidade consistente: aumenta custo de armazenamento e reduz a capacidade real de encontrar o evento relevante durante um incidente — volume de log não é observabilidade. - Métrica com label de alta cardinalidade (ex.: `user_id` ou `order_id` como label): explode o número de séries temporais armazenadas e pode derrubar ou encarecer drasticamente o backend de métricas. - Alerta configurado em uma métrica de causa em vez de uma métrica de sintoma (ex.: alertar em "CPU alta" em vez de "taxa de erro/latência acima do SLO"): gera ruído em picos benignos e não necessariamente detecta o impacto real ao usuário. - Dashboard que só existe porque "parecia útil na hora", sem revisão periódica: acumula painéis obsoletos que competem por atenção com os painéis que realmente importam durante um incidente. ## Validação - Gerar telemetry ponta a ponta em um cenário controlado e confirmar que a correlação (trace id) atravessa todos os boundaries mapeados. - Verificar cardinalidade projetada, custo estimado, retenção configurada e que campos sensíveis passam por redaction antes de sair do serviço. - Confirmar que os alertas configurados realmente disparam no cenário que deveriam (teste ou simulação) e que o runbook vinculado é executável por alguém que não escreveu o código. - Rodar, contra um cenário de falha conhecido, as queries que a equipe usaria durante um incidente real, confirmando que elas retornam o sinal esperado dentro de um tempo útil. - Não declarar um sistema "observável" apenas por existir dashboard, a prova é a equipe conseguir responder à pergunta operacional original usando apenas a telemetry, sem acesso a código ou banco. ## Skills relacionadas - `$specsfy-specialist-debugging` consome os sinais para isolar causa e pede instrumentação adicional quando a evidência é insuficiente. - `$specsfy-specialist-docker` e `$specsfy-specialist-docker-swarm` expõem runtime, service e node signals, esta skill define correlação e decisão. - `$specsfy-specialist-postgres` e `$specsfy-specialist-redis` produzem sinais de dados/cache com cardinalidade e retenção controladas aqui. - `$specsfy-specialist-web-api-design` define correlação e erro no contrato, esta skill mede o comportamento do endpoint em operação. - `$specsfy-specialist-performance-engineering` para diagnóstico de causa raiz de uma latência ou gargalo já detectado pelos sinais aqui definidos. - `$specsfy-specialist-delivery-engineering` quando o sinal de saúde definido aqui alimenta a decisão de continuar ou reverter um rollout. - `$specsfy-specialist-application-security` quando a telemetry precisa registrar (ou deliberadamente não registrar) eventos de segurança. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-observability/references/standards.md) para os pilares de observabilidade, frameworks de dashboard (RED/USE), SLIs/SLOs e fontes oficiais de OpenTelemetry. ### Especialista Engenharia de desempenho no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/performance-engineering - Descrição: Consulte o guia da especialista Engenharia de desempenho no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando há relato de lentidão, throughput baixo, uso excessivo de recursos, bundle grande ou dúvida de capacidade para um pico esperado. - Acionar também para revisar uma otimização já proposta e confirmar se ela tem baseline medido e hipótese, ou se é apenas intuição. - Não acionar para desenhar o sistema de métricas/alertas de produção em si — usar `$specsfy-specialist-observability` para isso, aqui o foco é diagnosticar e resolver um problema de performance específico já observado ou suspeitado. - Combinar com `$specsfy-specialist-postgres` quando o gargalo estiver em query/índice, e com `$specsfy-specialist-delivery-engineering` quando a correção precisa de um guardrail automático no pipeline. ## Fluxo 1. Definir a jornada, a métrica, o percentil-alvo, a carga esperada e o orçamento de performance antes de tocar em qualquer código. 2. Reproduzir o problema com ambiente e volume de dados representativos — nunca diagnosticar sobre um dataset de desenvolvimento minúsculo. 3. Medir o baseline atual e decompor o tempo por boundary (cliente, rede, aplicação, banco, dependência externa) para saber onde o tempo é gasto. 4. Formular uma hipótese específica e usar o profiler/trace adequado ao boundary identificado, não um chute de otimização genérica. 5. Alterar um único fator relevante por vez e medir novamente sob as mesmas condições do baseline. 6. Testar que a correção preserva a corretude sob carga real, timeout e retry — uma otimização que quebra sob concorrência não é uma otimização. 7. Criar um guardrail (teste de regressão de performance, orçamento no pipeline) que impeça a regressão voltar despercebida. ## Padrões - Usar percentis (p50, p95, p99) e a distribuição completa, nunca apenas a média — a média esconde a cauda longa que mais afeta a experiência real. - Separar explicitamente latência de cliente, rede, aplicação, banco e dependências externas antes de decidir onde otimizar. - Medir tanto cache frio quanto cache quente, e sob condição concorrente real, não apenas uma requisição isolada. - Não adicionar camada de cache antes de provar o custo do caminho sem cache e definir a estratégia de invalidação — cache é a fonte mais comum de bug de dado obsoleto quando adicionado sem essa prova. - Preservar corretude sob carga, timeout e retry: uma otimização que reduz latência média mas introduz race condition ou perda de retry não é aceitável. - Controlar o observer effect (o próprio profiler/instrumentação alterando o resultado medido) e garantir aquecimento (warm-up) antes de medir JIT, cache de disco ou connection pool. - Definir capacidade e headroom a partir do cenário de pico real esperado, não da média de tráfego observada hoje. ## Antipadrões - Otimizar a partir de "isso parece lento" sem baseline medido: sem número antes e depois, é impossível saber se a mudança ajudou, não teve efeito ou piorou em outro percentil. - Adicionar índice, cache ou paralelismo para resolver um sintoma sem identificar o boundary real do gargalo: resolve o sintoma medido no ambiente de teste e não move a agulha em produção, ou move o gargalo para outro lugar sem reduzir a latência percebida. - Comparar médias entre duas versões em vez de comparar a mesma distribuição de percentis sob a mesma carga: uma média melhor pode esconder uma cauda p99 pior. - Escalar hardware/réplicas antes de investigar N+1 query, chamada serial que poderia ser paralela, ou round-trip de rede evitável — a causa mais comum de lentidão em sistemas web é excesso de round-trips, não falta de CPU. ## Validação - Benchmark repetível com o baseline arquivado (não apenas anotado informalmente) para comparação futura. - Profiling de CPU, memória, I/O ou queries conforme a evidência do passo de decomposição, não um profiler genérico "por garantia". - Teste de carga com critérios de sucesso explícitos (percentil-alvo sob carga-alvo) e limites seguros para não afetar produção real durante o teste. - Regressão automática no pipeline, com sensibilidade proporcional à estabilidade histórica da métrica — métrica ruidosa precisa de margem maior para não gerar falso positivo constante. - Não declarar uma mudança "mais rápida" sem o baseline antes/depois nas mesmas condições, "parece mais rápido" não é evidência. ## Skills relacionadas - `$specsfy-specialist-astro` e `$specsfy-specialist-nextjs` aplicam budgets e correções no framework depois que a medição localiza o gargalo. - `$specsfy-specialist-debugging` isola defeitos funcionais que aparecem sob carga sem confundi-los com oportunidade de otimização. - `$specsfy-specialist-software-architecture` trata mudança estrutural quando o boundary, e não uma implementação local, limita capacidade. - `$specsfy-specialist-web-api-design` preserva retry, paginação e contrato durante otimizações de throughput e latência. - `$specsfy-specialist-observability` para o sistema de sinais que detecta degradação em produção antes que vire incidente. - `$specsfy-specialist-postgres` e `$specsfy-specialist-redis` quando o gargalo identificado está em query, índice ou estratégia de cache. - `$specsfy-specialist-delivery-engineering` para transformar o guardrail de performance em um gate automático do pipeline. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-performance-engineering/references/standards.md) para Web Vitals, metodologia de benchmark, teste de carga, profiling e orçamentos de performance, com fontes oficiais. ### Especialista PostgreSQL no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/postgres - Descrição: Consulte o guia da especialista PostgreSQL no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para desenhar schema, escrever ou revisar SQL, escolher índice, analisar plano (`EXPLAIN`), diagnosticar lock/deadlock, planejar migration ou dimensionar backup/restore em Postgres. - Acionar também quando um ORM (Eloquent, Prisma, Drizzle) gerar SQL ineficiente e a causa raiz for modelagem ou índice, não a API do ORM. - Não acionar para decisões específicas de Supabase (RLS, Auth, Realtime, Edge Functions) — usar `$specsfy-specialist-supabase`, que aplica Postgres por baixo com essas camadas adicionais. - Combinar com `$specsfy-specialist-laravel` quando o ponto de entrada for Eloquent e com `$specsfy-specialist-performance-engineering` quando o gargalo abranger além do banco (aplicação, rede, cache). ## Fluxo 1. Descobrir versão do Postgres, extensões instaladas, volume atual, crescimento esperado, workload (OLTP, analítico, misto) e quem é o owner dos dados antes de recomendar. 2. Modelar invariantes com tipos precisos, `NOT NULL`, `CHECK`, `UNIQUE`, chaves estrangeiras e normalização adequada ao caso de uso. 3. Escrever a consulta mais simples que expressa a regra e medir o plano real com `EXPLAIN (ANALYZE, BUFFERS)` sobre dados representativos, nunca sobre uma tabela vazia ou de desenvolvimento. 4. Selecionar índice pelo workload observado (predicados do `WHERE`, `ORDER BY`, `JOIN`) — nunca por "essa coluna é consultada" isoladamente. 5. Analisar isolation level, duração de transação, ordem de aquisição de locks e concorrência esperada sob a carga real. 6. Planejar a migration com compatibilidade entre a versão antiga e nova da aplicação durante o deploy, e um caminho de rollback testável. 7. Marcar a execução como `[MIGRATION]`, apontar o arquivo versionado, aplicar em uma base de teste e consultar o histórico do migrador antes de concluir. 8. Validar backup, restore, monitoramento e capacidade no ambiente alvo antes de declarar a mudança pronta para produção. ## Padrões - Preferir constraint do banco (`NOT NULL`, `CHECK`, `UNIQUE`, FK, `EXCLUDE`) para toda invariante que sempre deve valer — validação só na aplicação permite dado inconsistente por qualquer segundo caminho de escrita. - Evitar `SELECT *` em código de produção, tipos imprecisos (`text` para enum fechado, `float` para dinheiro) e índice redundante que duplica outro já existente com prefixo igual. - Nunca adicionar índice sem ler padrão de escrita, tamanho da tabela, seletividade do predicado e o plano antes/depois — índice mal escolhido piora escrita sem acelerar leitura. - Manter transação curta (evitar I/O externo, espera de usuário ou chamada de rede dentro dela) e ordem de aquisição de locks consistente entre todos os caminhos de código para evitar deadlock. - Rodar `EXPLAIN (ANALYZE, BUFFERS)` somente em ambiente onde executar a consulta de verdade é seguro (não em produção sem `ROLLBACK`/replica). - Aplicar expand/contract em mudança de schema incompatível ou em tabela de alto volume: nunca renomear/remover coluna lida em produção no mesmo passo que a adiciona. - Conceder o menor privilégio necessário e separar papéis de migration (DDL), aplicação (DML) e leitura (`SELECT` apenas) — a aplicação nunca conecta com um role que pode `DROP TABLE`. ## Antipadrões - Índice criado por "essa coluna aparece no WHERE", ignorando seletividade — em coluna de baixa cardinalidade (booleano, status com poucos valores) o planner frequentemente prefere seq scan e o índice só custa em escrita. - `ALTER TABLE ... ADD COLUMN ... NOT NULL DEFAULT` em versão antiga do Postgres (< 11) reescrevendo a tabela inteira sob lock — em versões atuais isso é otimizado para `DEFAULT` constante, mas `DEFAULT` com função volátil ainda reescreve. - Transação longa mantendo lock enquanto espera resposta de rede ou confirmação do usuário — bloqueia autovacuum de limpar tuplas mortas e aumenta bloat. - Paginação por `OFFSET` grande em tabela que cresce — custo cresce linearmente com o offset, preferir paginação por keyset (`WHERE id > :cursor ORDER BY id LIMIT :n`). - Backup automatizado nunca restaurado — "temos backup" sem um restore completo testado é uma suposição não verificada, não uma garantia. ## Validação - Testar integridade (constraints violadas geram erro esperado), concorrência (dois writers simultâneos não corrompem invariante) e as queries críticas do caminho quente. - Comparar `EXPLAIN (ANALYZE, BUFFERS)` antes/depois com cardinalidade realista, não com a tabela vazia do ambiente de desenvolvimento. - Estimar o lock e o tempo de rewrite de qualquer DDL contra o tamanho real da tabela em produção antes de agendar a janela de deploy. - Conferir cada tarefa `[MIGRATION]` pelo arquivo, pelo comando de aplicação e pela consulta do histórico do migrador, todos registrados com saída zero. - Provar restore periodicamente a partir do backup real, incluindo o tempo que o processo leva (RTO) — backup sem restore testado não é uma garantia de recuperação. - Não declarar uma mudança "sem impacto de performance" sem o plano comparado, não declarar um schema "íntegro" sem os testes de constraint e concorrência acima. ## Skills relacionadas - `$specsfy-specialist-data-modeling` para entidades, relações e ciclo de vida antes dos detalhes específicos do Postgres. - `$specsfy-specialist-application-security` define ameaça, autorização e isolamento que constraints, roles e RLS materializam no banco. - `$specsfy-specialist-supabase` quando o Postgres for gerenciado por Supabase (RLS, Auth, Realtime, pooling específico). - `$specsfy-specialist-laravel` quando o ponto de entrada for Eloquent e a correção precisar refletir em migration/model. - `$specsfy-specialist-performance-engineering` quando o gargalo não se resolver só com índice/plano (rede, cache, aplicação). - `$specsfy-specialist-observability` para métricas e alertas de banco em produção (conexões, locks, replicação, lag). - `$specsfy-specialist-redis` quando parte do estado consultado estiver em cache fora do banco — o Postgres continua sendo a fonte de verdade que o Redis nunca substitui. - `$specsfy-specialist-docker` para empacotar e operar o servidor Postgres em container (imagem oficial, volume de dados, healthcheck) — decisão de schema, índice e plano continuam aqui. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-postgres/references/standards.md) para tipos, índices, concorrência, segurança, migrations, operação e fontes oficiais. ### Especialista Prototipação no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/prototyping - Descrição: Consulte o guia da especialista Prototipação no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando existe uma pergunta técnica, de interação ou visual específica que só um artefato executável (não um documento) consegue responder com confiança. - Acionar também para comparar duas ou mais alternativas concretas antes de uma decisão cara de reverter. - Não acionar quando a pergunta já tem resposta documentada em fonte primária — nesse caso `$specsfy-specialist-technical-research` resolve mais rápido e sem o custo de construir algo. - Não promover o código do protótipo diretamente a produção — a fidelidade reduzida do protótipo (sem cobertura, sem tratamento de erro, sem segurança) é uma escolha deliberada válida apenas enquanto ele é descartável. ## Fluxo 1. Formular uma única pergunta e o critério que decide a resposta antes de escrever qualquer código — sem isso, o protótipo vira exploração sem fim. 2. Definir o que precisa ser real (o mecanismo sob teste) e o que pode ser simulado ou mockado (tudo que não afeta a resposta à pergunta). 3. Escolher a fidelidade mínima suficiente, um tempo limite explícito e um local claramente descartável no repositório ou fora dele. 4. Construir mais de uma alternativa quando a comparação direta entre elas for mais informativa que testar uma só contra a expectativa. 5. Executar o cenário planejado e coletar evidência observável — não impressão subjetiva de "parece que funciona". 6. Responder à pergunta original explicitamente (aceita, rejeitada ou ainda inconclusiva) e registrar as limitações do que foi testado. 7. Descartar o protótipo ou arquivá-lo explicitamente como não-produção, sem deixar nenhuma dependência de runtime apontando para ele. ## Padrões - Não confundir uma demo convincente com uma arquitetura válida — um protótipo que "funciona na demo" não provou nada sobre concorrência, escala, erro ou segurança que não foi deliberadamente exercitado. - Manter dados reais, credenciais de produção e integrações reais fora do protótipo, salvo quando a própria pergunta exige testar contra o sistema real (e mesmo assim, com escopo e autorização explícitos). - Para protótipo de interface, usar conteúdo realista (não "texto genérico") e estados extremos (texto muito longo, lista vazia, erro) — a pergunta sobre UI raramente é sobre o caminho feliz. - Para protótipo de lógica/estado, expor as transições e invariantes numa interface mínima (CLI, teste executável) que as torne observáveis, em vez de escondê-las atrás de uma UI completa desnecessária à pergunta. - Não gastar tempo com abstração, cobertura de teste ou acabamento visual fora do que a pergunta exige — isso é o oposto do propósito do protótipo. - Marcar o código como descartável de forma que impeça import acidental por código de produção (diretório isolado, nome inequívoco, sem export público). - Converter todo aprendizado relevante em requisito, decisão registrada ou teste no owner correto (spec, ADR, backlog) — o protótipo em si não é fonte de verdade depois de descartado. ## Antipadrões - Deixar o protótipo "temporário" rodando em produção porque "funcionou" — sem a validação completa (segurança, erro, escala) que o protótipo deliberadamente pulou, ele carrega risco invisível para produção. - Testar várias perguntas ao mesmo tempo no mesmo protótipo — quando o resultado é ambíguo, não dá para saber qual variável causou o quê. - Investir em polimento visual ou arquitetura "só por garantia" quando a pergunta era puramente sobre viabilidade técnica de um mecanismo. - Herdar a dívida do protótipo silenciosamente: reaproveitar o arquivo do protótipo como base do código de produção sem reescrevê-lo com os padrões normais de qualidade. ## Validação - O critério de decisão foi definido antes da execução, e o resultado é reproduzível por outra pessoa que rode o mesmo cenário. - A pergunta original tem resposta explícita: hipótese aceita, rejeitada ou ainda inconclusiva (e, nesse caso, o que falta para decidir). - As limitações do protótipo e as diferenças em relação ao que produção exigiria estão registradas explicitamente. - Nenhum artefato do protótipo permanece conectado ao runtime final — verificado, não apenas assumido. - Não declarar uma abordagem "viável para produção" só com base no protótipo — isso exige a implementação e validação completas descritas no padrão do projeto. ## Skills relacionadas - `$specsfy-specialist-technical-research` quando a pergunta puder ser respondida por fonte primária sem precisar construir nada. - `$specsfy-specialist-domain-modeling` quando o protótipo revelar um conceito de domínio ainda não modelado — o aprendizado vira modelo, não fica preso ao código descartável. - `$specsfy-specialist-ux-design` ou `$specsfy-specialist-ui-design` quando o protótipo for de interface e precisar de rigor de fluxo ou hierarquia visual além da pergunta pontual. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-prototyping/references/standards.md) para níveis de fidelidade por tipo de pergunta, formato de saída e fontes oficiais. ### Especialista React no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/react - Descrição: Consulte o guia da especialista React no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o pedido envolve componente, hook, context, formulário, lista, efeito ou estado em React puro (CRA, Vite, RSC-agnóstico). - Acionar também para revisar por que um componente rerenderiza demais, por que um efeito roda em loop, ou como decidir onde um estado deve viver. - Não acionar para decisão de Server vs Client Component, cache de dados ou roteamento de framework, usar `$specsfy-specialist-nextjs` nesse caso. - Não acionar para escolher ou adaptar uma biblioteca de componentes visuais prontos, usar `$specsfy-specialist-react-ui-components` com `$specsfy-specialist-ui-design` para isso. - Combinar com `$specsfy-specialist-typescript` quando o componente expõe props públicas ou modela estado com union discriminada, e com `$specsfy-specialist-web-accessibility` para auditoria aprofundada de teclado e leitor de tela. ## Fluxo 1. Para uma tela ou formulário, ler `INTERFACE.md` e a seção de interface da spec antes do código. Confirmar telas, fluxo de informação, campos, validações, padrão de abertura e estados. Se o material não existir, retornar ao `$specsfy-specialist-ux-design` e `$specsfy-specialist-ui-design`, não trocar uma interface pedida por endpoint ou componente vazio. 2. Confirmar versão do React, renderer, framework (se houver), convenções do projeto e estratégia de testes já em uso. Quando a tela usar shadcn/ui, identificar antes a base de primitives instalada, seguindo `$specsfy-specialist-shadcn-ui`, nunca deduzir Radix ou Base UI pela aparência do componente. Se `.specsfy/STACK.md` não declarar React ou o projeto não tiver essa dependência, não inicie esta implementação: encaminhe ao especialista da stack observada. 3. Modelar os estados visíveis (nominal, loading, empty, error, stale, optimistic), os eventos que os produzem e quem é o dono de cada dado. 4. Projetar a árvore de componentes com responsabilidades e props pequenas, preferir composição (`children`, slots) a um componente com dezenas de flags booleanas. 5. Manter cada estado no dono mais próximo capaz de resolvê-lo, derivar valores durante o render em vez de sincronizar com `useEffect`. 6. Usar effects apenas para sincronizar com um sistema externo (DOM, subscription, rede, storage) — nunca para computar algo a partir de props e state já disponíveis. 7. Implementar semântica HTML e navegação por teclado antes do acabamento visual, então cobrir com teste de comportamento observável. 8. Medir performance somente quando houver sintoma real (profiler, métrica de produção), então memoizar ou dividir o componente com medição registrada, não por precaução. 9. Registrar em `INTERFACE.md` cada bloco criado, alterado ou reaproveitado: responsabilidade, arquivo, props, eventos, estados, acessibilidade e telas consumidoras. ## Padrões - Preferir composição a um componente genérico com muitas props de configuração, dividir quando a árvore de decisão interna cresce. - Em Laravel com React, usar shadcn/ui para primitives e ReUI para composições gratuitas. Página e rota compõem blocos React, grade, formulário, filtros, overlays e cartões reutilizáveis são componentes próprios e documentados em `INTERFACE.md`. - Nunca copiar uma prop para `state` só para "guardar o valor inicial", isso cria dessincronia — leia a prop diretamente ou derive durante o render. - Não usar `useEffect` para computar um valor derivável de props/state existentes, use uma variável comum ou `useMemo` quando o cálculo for caro. - Tornar loading, empty, error, stale e success estados explícitos da UI, não branches implícitos de um único booleano `loading`. - Usar `key` estável e vinda dos dados (id) em listas, nunca o índice do array quando a ordem pode mudar, item pode ser removido ou reordenado. - Isolar cada `Context.Provider` pela frequência de mudança e responsabilidade — um context que muda a cada tecla não deve envolver a árvore inteira. - Não memoizar (`memo`/`useMemo`/`useCallback`) sem medição prévia, memoização tem custo de comparação e só compensa com renders caros ou comprovadamente frequentes. - Testar pelo comportamento observável pelo usuário (texto, papel, estado), nunca por detalhes de implementação de hooks internos. ## Antipadrões - Efeito que sincroniza estado local com uma prop (`useEffect(() => setX(prop), [prop])`) — sintoma de estado duplicado, a fonte da verdade já é a prop. - Cadeia de effects que dispara outro effect via mudança de state ("effect chain") — geralmente colapsa em um único handler de evento ou em cálculo direto durante o render. - `useEffect` sem array de dependências completo, "silenciado" com `// eslint-disable` — esconde bug de closure obsoleta em vez de resolvê-lo. - Context único guardando todo o estado global da aplicação ("god context") — qualquer mudança rerenderiza toda a árvore, prefira contexts menores ou uma biblioteca de estado dedicada quando o grafo de dependências crescer. - Confundir este escopo com o de `$specsfy-specialist-nextjs`: adicionar `"use client"` em cascata para "resolver" um erro de hook, em vez de mover a interatividade para o componente folha correto. ## Validação - Percorrer a superfície alterada inteira por teclado e testar com leitor de tela quando houver papel, foco ou anúncio novo. - Escrever testes para cada estado modelado no passo 2 do Fluxo (nominal, loading, empty, error, stale, optimistic) e para a recuperação de erro. - Checar o console por warnings do React (chaves, hooks fora de ordem, atualização de estado após unmount) e por avisos de hydration quando houver SSR. - Rodar profiling ou bundle analysis somente quando uma hipótese concreta de performance existir, anexar a medição antes/depois. - Não declarar um componente "acessível" ou "performático" sem a comprovação acima, linguagem absoluta sem prova é proibida. ## Skills relacionadas - `$specsfy-specialist-reui` para composições React e Tailwind do catálogo gratuito. - `$specsfy-specialist-astro` governa a fronteira da ilha e `$specsfy-specialist-shadcn-ui` identifica a base de primitives e governa os componentes visuais, esta skill governa o comportamento React dentro deles. - `$specsfy-specialist-tailwind-css` estiliza o componente sem assumir ownership de estado, effect ou concorrência. - `$specsfy-specialist-nextjs` para fronteira server/client, cache de dados e roteamento — este especialista trata React independente de framework. - `$specsfy-specialist-react-ui-components` e `$specsfy-specialist-ui-design` para escolher e compor uma biblioteca visual pronta, este especialista entra depois, para ownership de estado, efeitos e testes. - `$specsfy-specialist-typescript` para tipar props, estado e union discriminada de forma exaustiva. - `$specsfy-specialist-web-accessibility` para auditoria aprofundada além do teclado básico validado aqui. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react/references/standards.md) para modelagem de estado, effects, composição, listas, context, testes e performance, com fontes oficiais. ### Especialista Componentes de UI React no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/react-ui-components - Descrição: Consulte o guia da especialista Componentes de UI React no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando uma interface React precisar ser criada a partir dos 231 exemplos TSX versionados em `assets/components/`. - Acionar para comparar variantes de navegação, formulário, dados, feedback, marketing ou tipografia sem introduzir uma biblioteca de runtime. - Não acionar para corrigir estado, effects ou concorrência sem trabalho visual, usar `$specsfy-specialist-react`. - Usar sempre com `$specsfy-specialist-ui-design`, que decide hierarquia, composição e densidade antes da escolha do asset. ## Fluxo 1. Anunciar o uso conjunto, carregar `$specsfy-specialist-design-system` e `$specsfy-specialist-ui-design` antes de escolher uma referência. Aplicar `DESIGNSYSTEM.MD` como fonte macro e `INTERFACE.md` como registro local. 2. Inspecionar versão do React, framework, Tailwind, design system, componentes locais, ícones e estratégia de testes do projeto consumidor. Se houver shadcn/ui, confirmar com `$specsfy-specialist-shadcn-ui` a base de primitives de cada componente antes de adaptar o asset. 3. Confirmar com UX e UI a tarefa principal, telas, fluxo de informação, formulário, padrão de abertura, hierarquia, composição, densidade, estados e breakpoints. O catálogo não escolhe esses pontos. 4. Para um CRUD autenticado, selecionar primeiro as famílias de `PageHeader`, `DataGrid`, `DetailLists`, formulário e feedback. Para um dashboard, selecionar `PageHeader`, filtros, indicadores, visualização principal e investigação detalhada. Manter as superfícies distintas antes de consultar o catálogo. 5. Escolher a família em [references/catalog.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react-ui-components/references/catalog.md) e listar somente os assets candidatos em `assets/components//`. 6. Ler a menor quantidade de arquivos TSX capaz de comparar variantes. 7. Adaptar a referência aos tokens, componentes, rotas, dados e convenções observados, não substituir a arquitetura local pela estrutura do exemplo. 8. Implementar todos os estados relevantes e validar comportamento, aparência, responsividade e acessibilidade. Para páginas completas, ler [references/composition-map.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react-ui-components/references/composition-map.md). Para conduzir uma escolha incremental, ler [references/conversation-flow.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react-ui-components/references/conversation-flow.md). ## Padrões - Tratar os arquivos em `assets/` como referências copiáveis, nunca como pacote ou dependência de runtime. - Preservar semântica, teclado, foco, `aria-*`, `sr-only`, `alt`, dark mode e breakpoints úteis ao adaptar. - Preferir tokens, primitives, `Link`, imagens e componentes já publicados no projeto consumidor. - Substituir dados mockados, URLs externas, `href="#"` e copy de demonstração. - Confirmar dependências explícitas do asset, como Headless UI ou Heroicons, antes de usá-las, não instalar pacotes sem autorização. - Manter a composição definida por `$specsfy-specialist-ui-design`, a disponibilidade de um exemplo não justifica adicionar uma seção. - Respeitar os defaults de CRUD: `DataGrid` para lista, `DetailLists` para detalhe, `PageHeader` em todas as superfícies e formulários de criar e editar organizados em seções com duas colunas responsivas. - Fazer a linha do `DataGrid` abrir o detalhe por clique ou teclado e proteger botões, checkboxes e menus internos com `TableRowAction` ou equivalente. - Renderizar `Breadcrumb` em toda tela, mantendo o nome da equipe ativa, o módulo e a tela atual. Em Laravel, reutilizar `Breadcrumb` ou `Breadcrumbs` existente no layout em vez de criar outro primitive. - Agrupar campos relacionados em duas colunas nos breakpoints largos e uma no mobile, usar largura total para campos longos e mensagens de erro. - Para dashboards, usar blocos ReUI ou primitives shadcn/ui compatíveis com a pergunta, o escopo, os filtros, os indicadores e os estados da tela. - Renderizar erro de campo em vermelho com mensagem abaixo do campo, foco no primeiro erro e valores preservados. - Dar personalidade à tela por hierarquia, dados, linguagem e estados do produto, sem copiar uma composição genérica do catálogo. - Combinar com `$specsfy-specialist-react` para ownership de estado, effects, concorrência ou testes React e com `$specsfy-specialist-web-accessibility` para auditoria aprofundada. ## Antipadrões - Copiar uma página inteira e manter dados mockados, imports inexistentes ou links `#`, o exemplo deixa de ser referência e vira dívida acoplada. - Escolher um asset pela aparência antes de definir tarefa e hierarquia, isso faz o catálogo dirigir o produto em vez de servir à intenção da tela. - Instalar todas as dependências citadas por um exemplo sem mapear os primitives locais, cria duas fontes concorrentes de componentes e tokens. - Transformar componentes estáticos em Client Components por conveniência, aumenta JavaScript enviado e mistura apresentação com estado sem necessidade. ## Validação - Executar os testes, lint e typecheck já definidos pelo projeto consumidor. - Exercitar estados nominal, loading, empty, error, disabled e permission denied quando forem relevantes. - Verificar mobile e desktop, zoom, overflow, conteúdo curto/longo, teclado, foco, contraste e reduced motion. - Confirmar que imports e assets externos existem e que nenhum pacote foi introduzido implicitamente. - Revisar a interface final com [references/interface-quality-checklist.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react-ui-components/references/interface-quality-checklist.md) e com `$specsfy-specialist-ui-design`. - Não declarar a interface integrada sem demonstrar interação por teclado, estados adversos e ausência de overflow nos breakpoints suportados. - Confirmar que `DESIGNSYSTEM.MD` foi lido e que qualquer exceção visual tem alcance registrado. ## Skills relacionadas - `$specsfy-specialist-interface-experience` organiza a descoberta e a entrega completa da tela antes da seleção dos componentes React. - `$specsfy-specialist-shadcn-ui` identifica a base de primitives e fornece componentes adaptáveis, esta skill fornece composições TSX copiáveis, não uma dependência runtime. - `$specsfy-specialist-ui-design` governa composição, hierarquia, densidade e coerência visual, esta skill fornece material React adaptável. - `$specsfy-specialist-design-system` governa regras macro e padrões CRUD antes da seleção dos assets. - `$specsfy-specialist-react` governa ownership de estado, effects, concorrência e testes de comportamento. - `$specsfy-specialist-tailwind-css` governa tokens e utilitários usados na adaptação visual. - `$specsfy-specialist-web-accessibility` conduz auditoria WCAG e testes com tecnologia assistiva além da checagem básica da interface. - `$specsfy-specialist-nextjs` ou `$specsfy-specialist-astro` governa a fronteira server/client e o roteamento do framework hospedeiro. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-react-ui-components/references/standards.md) para regras de seleção, adaptação, estado, dependências e comprovação, e carregue os demais arquivos de `references/` somente no passo do Fluxo que os solicita. ### Especialista Redis no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/redis - Descrição: Consulte o guia da especialista Redis no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para desenhar cache, sessão, rate limiter, lock distribuído, fila simples ou stream sobre Redis/Valkey, ou para diagnosticar cache stampede, hot key, eviction inesperada ou indisponibilidade. - Acionar também para revisar configuração de persistência (RDB/AOF), Cluster/Sentinel ou política de memória em produção. - Não acionar para modelar o dado durável de origem — Redis é acelerador ou estrutura efêmera, a fonte de verdade e sua integridade pertencem a `$specsfy-specialist-postgres` (ou ao banco relevante). - Combinar com `$specsfy-specialist-observability` para métricas e alertas de cache em produção, e com `$specsfy-specialist-laravel`/outro framework quando o driver de cache/fila da aplicação for Redis. ## Fluxo 1. Definir a finalidade do dado (cache, sessão, fila, lock, contador), quem é o source of truth, a consistência necessária e a tolerância real à perda daquele dado se o Redis reiniciar vazio. 2. Estimar cardinalidade, tamanho médio do valor, taxa de escrita/leitura, TTL necessário e o padrão de acesso (aleatório, sequencial, hot key concentrada). 3. Escolher a estrutura de dado e um esquema de chave namespaced e estável (`app:recurso:id`), evitando chave dinâmica demais que exploda a cardinalidade de chaves. 4. Projetar explicitamente cache stampede, estratégia de invalidação, retry e o comportamento da aplicação quando o Redis está indisponível (fail open vs fail closed). 5. Configurar limite de memória, política de eviction e persistência (ou ausência dela) conforme o papel do dado — cache tolera perda, lock e contador de negócio não. 6. Testar concorrência (duas escritas simultâneas na mesma chave), expiração no meio de uma operação, indisponibilidade do Redis e recuperação (cold start após restart/failover). 7. Medir hit rate, latência (p50/p99), uso de memória, número de conexões e hot keys antes de declarar a solução pronta. ## Padrões - Dar TTL explícito a toda chave de cache e definir, por chave, quem é responsável por invalidá-la (evento de escrita, TTL curto, ambos). - Evitar comandos que bloqueiam o event loop single-threaded do Redis em produção — `KEYS *`, `FLUSHALL`/`FLUSHDB` fora de manutenção controlada, `SORT` sem `LIMIT` em coleção grande, usar `SCAN` com cursor para iteração. - Usar operações atômicas nativas (`INCR`, `SETNX`, `GETEX`) ou script Lua (`EVAL`/`EVALSHA`, executado atomicamente pelo Redis) quando a invariante exigir "ler e escrever" sem condição de corrida. - Tratar lock distribuído como lease com timeout e dono verificável: gerar um token único no `SET key token NX PX ttl`, e só liberar com script que confirma `GET key == token` antes do `DEL` — nunca `DEL` incondicional. - Separar namespace/database lógico e política de eviction por workload incompatível — cache volátil e dado que não pode ser evictado (fila, lock) não competem pela mesma política de memória. - Não serializar objeto sem versão de schema embutida (dificulta migração futura do formato) nem guardar segredo (senha, token bruto) em valor sem necessidade — Redis não é cofre de segredo. - Confirmar a semântica de entrega antes de tratar Redis como fila: Pub/Sub é fire-and-forget (assinante ausente perde a mensagem), Streams com consumer group oferece at-least-once com ACK explícito e precisa de reprocessamento idempotente do lado consumidor. ## Antipadrões - Cache sem jitter no TTL: muitas chaves expirando no mesmo instante geram thundering herd contra o banco — adicionar variação aleatória ao TTL ou usar lock/refresh antecipado evita o pico simultâneo. - Retry cego de comando não idempotente após timeout — se o comando original foi processado mas a resposta se perdeu, o retry duplica o efeito, use operação idempotente ou token de deduplicação. - Chave com cardinalidade não controlada (`session:` sem TTL, acumulando para sempre) — memória cresce sem bound até o Redis começar a evictar ou cair por OOM. - Lock distribuído implementado com `SETNX` + `DEL` simples, sem TTL — um processo que trava ou morre antes do `DEL` deixa o lock preso indefinidamente. - Tratar `maxmemory-policy` padrão (`noeviction`) como cache automático — com `noeviction`, ao atingir o limite de memória o Redis passa a **rejeitar escritas** em vez de evictar, o que derruba a aplicação se ela não trata esse erro. ## Validação - Exercitar miss, hit, expiração no meio da operação, cache stampede simulado e Redis indisponível — cada cenário com o comportamento esperado documentado, não "deve funcionar". - Verificar limite de memória, política de eviction, persistência e failover (Sentinel/Cluster) em ambiente que reproduz a topologia real, não apenas uma instância única de desenvolvimento. - Observar `INFO`, slow log (`SLOWLOG GET`) e métricas do cliente sem expor valor sensível nos logs. - Comparar o comportamento da aplicação com e sem cache para provar que o cache não introduziu dado desatualizado ou inconsistente no caminho crítico. - Não declarar um lock "seguro" sem o teste de dois processos concorrentes disputando a mesma chave, nem uma fila "confiável" sem o teste de reprocessamento por reentrega. ## Skills relacionadas - `$specsfy-specialist-performance-engineering` mede se Redis reduz o gargalo e verifica custo, cauda de latência e regressão sob carga. - `$specsfy-specialist-postgres` quando Redis for cache derivado de dado cuja fonte de verdade e integridade são do banco relacional. - `$specsfy-specialist-observability` para métricas, alertas e dashboards de cache em produção. - `$specsfy-specialist-laravel` quando o cliente for o driver de cache/ fila/sessão do framework. - `$specsfy-specialist-docker`/`$specsfy-specialist-docker-swarm` para empacotar e operar Redis/Sentinel/Cluster. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-redis/references/standards.md) para estruturas de dado, persistência, cluster, segurança e padrões de cache. ### Especialista ReUI no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/reui - Descrição: Consulte o guia da especialista ReUI no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. O Specsfy é opinativo: para interfaces React e Tailwind, shadcn/ui fornece as primitives e o ReUI fornece as composições gratuitas. Esta é a base padrão da Promovaweb para CRUDs e telas de produto. ## Quando usar Use para telas React que precisam de componentes ReUI gratuitos. Em Laravel, use quando o frontend React estiver em Inertia, Vite ou outra integração já configurada. Em Next.js, Astro ou React puro, mantenha o roteamento e a hidratação definidos pelo framework hospedeiro. ## Fluxo 1. Leia `INTERFACE.md`, stack, `components.json`, Tailwind, primitives locais e telas afetadas. Quando `INTERFACE.md` não existir, execute `$specsfy-setup` antes de criar interface. 2. Confirme React 19, Tailwind CSS v4 e shadcn/ui antes de iniciar o registry. Carregue `$specsfy-specialist-shadcn-ui` junto desta skill para inicializar ou auditar `components.json`, aliases, tema e primitives. 3. Leia [references/setup.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-reui/references/setup.md) para preparar o projeto e escolher a variante Base UI ou Radix já usada. 4. Use [references/catalog-free.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-reui/references/catalog-free.md) para escolher apenas itens gratuitos e compatíveis com a jornada definida. Leia também [references/components-free.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-reui/references/components-free.md) para percorrer todas as famílias públicas antes de criar uma alternativa. Para Laravel com React, leia obrigatoriamente [references/shadcn-components.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-reui/references/shadcn-components.md). 5. Instale o menor conjunto necessário pelo comando `npx shadcn@latest add` retornado pelo registry, nunca por cópia manual de URLs ou itens premium. 6. Leia a API e exemplos reais do item antes de adaptar dados, ações, estados, rotas e permissões do sistema. 7. Divida a interface em componentes React: a página compõe o fluxo, o domínio concentra grade, formulário, filtros e ações, primitives e composições reutilizáveis ficam nos diretórios já definidos pelo projeto. 8. Atualize `INTERFACE.md` com cada bloco criado ou alterado: arquivo, origem shadcn/ui ou ReUI, finalidade, props e eventos, estados, acessibilidade, consumidores e regra de reaproveitamento ou extensão. 9. Valide a tela com os testes, typecheck, lint e build do projeto. ## Padrões - Todo CRUD com interface React e Tailwind usa ReUI como base visual: Data Grid ou List para consulta, Filters para recorte, Form e campos ReUI para criação e edição, Dialog ou Sheet para ações contextuais e Alert/Badge para retorno e status. Não crie uma alternativa manual quando o catálogo gratuito já atender a interação. - Em listas com detalhe, o Data Grid torna a linha inteira clicável e acessível por teclado. Botões, checkboxes e menus internos ficam em uma camada de ação própria, como `TableRowAction`, para não abrir o detalhe por engano. - Em criar e editar, use Form em seções: contexto à esquerda e painel de campos à direita, com duas colunas nos breakpoints largos e uma no mobile. - Toda tela tem `Breadcrumb` com o nome da equipe ativa, o módulo e o título atual. Em Laravel, reutilize o `Breadcrumb` ou `Breadcrumbs` já existente no layout e a tipagem usada pelas rotas. - Registre `@reui` em `components.json` com `https://reui.io/r/{style}/{name}.json`, itens `c-*` são gratuitos. - Preserve a biblioteca de primitives já presente: Base UI e Radix têm APIs diferentes, embora o estilo Tailwind seja equivalente. - Adicione os tokens semânticos ReUI de sucesso, informação, aviso, inversão e ações destrutivas somente quando a tela os usar. - Em Laravel, mantenha Form Requests, policies e validação no servidor, ReUI melhora a experiência, não substitui os contratos PHP. - Em Laravel, complete Vite, Inertia React, React 19, Tailwind v4 e shadcn/ui antes do registry ReUI. Blade, Livewire e Vue exigem uma migração registrada na spec antes de receber componentes React. - Use componentes compostos para a tarefa real, com dados reais, estados vazio, carregando, erro, sucesso, teclado e foco. - Uma rota não concentra a implementação de grade, formulário, filtros, diálogo, painel lateral ou cartão reutilizável. Extraia cada parte para um componente React com responsabilidade e API claras. - Registre em `INTERFACE.md` todos os componentes gratuitos usados de ReUI e shadcn/ui, além de cada bloco React próprio, com explicação, caminho, API, estados, consumidores e forma correta de reutilização ou extensão. ## Antipadrões - Usar blocos, ícones ou templates premium, esta skill trabalha apenas com o catálogo gratuito e não cria `REUI_LICENSE_KEY`. - Migrar primitives existentes de Radix para Base UI, ou o contrário, para instalar um componente. - Copiar dados demonstrativos, imports ausentes ou APIs inventadas do catálogo. - Tratar validação visual como validação de autorização ou persistência. - Criar tabelas, filtros, modais, upload ou formulários CRUD próprios sem consultar primeiro o catálogo gratuito ReUI. ## Validação - Execute os comandos detectados do projeto e teste a navegação por teclado, foco, responsividade, tema e estados da tela. - Confirme que cada item instalado começa com `@reui/c-` ou é dependência pública instalada pelo próprio registry. - Verifique `components.json`, imports e tokens adicionados antes de encerrar. ## Skills relacionadas - `$specsfy-specialist-react` governa estado e testes React. - `$specsfy-specialist-tailwind-css` governa tokens e utilitários Tailwind. - `$specsfy-specialist-shadcn-ui` governa primitives e `components.json`. - `$specsfy-specialist-laravel` governa backend, Inertia, autorização e testes Laravel. - `$specsfy-specialist-ui-design` e `$specsfy-specialist-ux-design` definem a experiência antes da escolha de componentes. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-reui/references/standards.md) para fontes oficiais, tokens e comandos, e as referências de setup e catálogo quando aplicar ReUI. ### Especialista shadcn/ui no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/shadcn-ui - Descrição: Consulte o guia da especialista shadcn/ui no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. Para interfaces React e Tailwind da Promovaweb, esta skill prepara as primitives, `components.json`, aliases e tema. Quando a tela precisar de CRUD ou composição de produto, carregue `$specsfy-specialist-reui` em conjunto: ela instala primeiro componentes gratuitos ReUI sobre esta base. ## Quando usar - Acionar quando o projeto tem `components.json` ou componentes shadcn já incorporados, ou quando a pessoa pede explicitamente um componente shadcn/ui (Data Table, Sidebar, Dialog, Form, Chart). - Acionar também para identificar se o shadcn/ui do projeto usa Base UI, Radix ou React Aria antes de compor um padrão (dashboard, formulário, overlay). - Não acionar para o sistema de tokens/utilitários Tailwind em si, combinar com `$specsfy-specialist-tailwind-css` para isso. - Não acionar quando o projeto usa uma biblioteca de componentes visual diferente (galeria copiável não-Radix), nesse caso avaliar `$specsfy-specialist-react-ui-components` com `$specsfy-specialist-ui-design`. - Combinar com `$specsfy-specialist-web-accessibility` para auditoria aprofundada além da acessibilidade já garantida pelo primitive Radix. ## Fluxo 1. Confirmar framework, versão do shadcn/ui, `components.json` (aliases de import, estilo, CSS variables) e o registry configurado antes de adicionar qualquer componente. 2. Identificar a base de primitives em uso: começar pelos imports dos componentes shadcn já incorporados e confirmar no manifest. Classificar `@base-ui/react` como Base UI, `radix-ui` ou `@radix-ui/react-*` como Radix e `react-aria-components` ou `@react-aria/*` como React Aria. Se os componentes usarem mais de uma base ou os sinais não bastarem, registrar a base por arquivo e não adicionar, migrar ou reescrever primitives até esclarecer a divergência. 3. Auditar os componentes já incorporados no projeto e suas customizações locais antes de adicionar um novo, para não duplicar ou divergir de um componente equivalente já existente. 4. Escolher o primitive da base identificada pelo comportamento e semântica exigidos (diálogo modal vs popover vs sheet lateral), não pela aparência mais próxima do design. 5. Adicionar o menor conjunto de componentes necessário e revisar o código gerado linha a linha — ele é copiado para o projeto e passa a ser mantido por quem o adicionou. 6. Adaptar tokens, variantes (`cva`) e composição ao design do projeto sem remover roles, `aria-*`, gestão de foco ou atalhos de teclado oferecidos pela base identificada. 7. Construir todos os estados reais do componente (loading, empty, error, disabled, permission denied), não apenas o estado nominal mostrado na documentação. 8. Testar teclado, foco, responsividade, submissão de formulário e os dois temas (claro/escuro) antes de considerar o componente pronto. 9. Atualizar `INTERFACE.md` para cada primitive ou bloco criado, alterado ou reaproveitado, incluindo arquivo, origem, finalidade, API, estados, acessibilidade, consumidores e orientação de extensão. ## Padrões - Não tratar shadcn/ui como dependência opaca versionada num pacote, o código copiado pertence ao projeto e qualquer bug ou desvio de acessibilidade nele é responsabilidade do time, não "responsabilidade da lib". - Usar somente APIs, atributos de estado e composição próprios da base identificada. Base UI, Radix e React Aria expõem contratos semelhantes, mas seus imports, props e atributos não são intercambiáveis. - Preservar roles ARIA, labels, gestão de foco (foco inicial, trap e retorno ao trigger) e Escape quando a base os oferece, customização visual não pode remover esse comportamento. - Centralizar tokens de tema (CSS variables) num único lugar, nunca editar dezenas de componentes individualmente para trocar uma cor de marca ou ajustar o tema. - Em projetos React da Promovaweb, usar shadcn/ui junto do ReUI: o primeiro atende primitives e o segundo atende composições gratuitas de produto. Toda tela é uma composição de componentes React, não um arquivo monolítico. - Compor um Data Table para o caso de uso real (colunas, ordenação, filtro, seleção, paginação necessários) em vez de importar um componente universal com todas as capacidades possíveis "por garantia". - Fazer a Sidebar responder a viewport (colapsar em mobile), densidade de navegação e destacar a rota atual de forma perceptível. - Validar todo formulário também no servidor (a validação client-side é UX, não segurança) e associar cada mensagem de erro ao campo correspondente via `aria-describedby`/label. - Atualizar um componente já customizado apenas depois de comparar o diff entre a versão nova do registry e as customizações locais — um `add` ingênuo pode sobrescrever uma correção de acessibilidade feita anteriormente. ## Antipadrões - Assumir que todo shadcn/ui usa Radix porque o componente tem a mesma API pública. Isso introduz imports e props incompatíveis com Base UI ou React Aria. - Importar um Dialog do shadcn/ui e remover o `aria-describedby`/título por achar "redundante visualmente" — quebra o anúncio do leitor de tela sobre o que o diálogo faz. - Editar o arquivo gerado do componente para "consertar" um estilo em vez de ajustar o token/variant central — a próxima pessoa que atualizar o componente perde a correção sem saber que ela existia. - Tratar o Data Table como componente único e genérico para toda tabela do sistema, acumulando props condicionais até virar impossível de entender — compor uma tabela por caso de uso a partir dos blocos do registry. - Validar formulário só no cliente (schema no front) e nunca repetir a validação no servidor — qualquer requisição direta ao endpoint ignora a validação do formulário. - Rodar `shadcn add` sobre um componente já customizado sem diff prévio, perdendo silenciosamente ajustes de acessibilidade ou de negócio feitos localmente. ## Validação - Rodar typecheck, lint, testes e build do projeto após adicionar ou modificar um componente. - Percorrer a navegação completa por teclado: abrir/fechar overlay, focus trap dentro do Dialog/Sheet, e retorno do foco ao elemento que o abriu. - Testar em mobile e desktop, tema claro e escuro, zoom alto e conteúdo longo/truncado nas células de tabela e nos rótulos. - Exercitar os estados de tabela (vazio, carregando, erro, com dados), gráfico (sem dado, com dado), formulário (pendente, erro, sucesso, reabrir após falha preservando valores) e sidebar (colapsada, expandida, rota ativa) realmente usados pela tela. - Não declarar um componente "acessível" só porque veio do shadcn/ui, qualquer customização precisa da comprovação acima antes da afirmação. ## Skills relacionadas - `$specsfy-specialist-astro` governa integração e hidratação quando primitives React são usadas como ilha Astro. - `$specsfy-specialist-tailwind-css` para o sistema de tokens e utilitários que sustenta o tema dos componentes. - `$specsfy-specialist-react` para a lógica de estado, effects e testes do componente React por trás de cada primitive shadcn/ui. - `$specsfy-specialist-typescript` para tipar variantes `cva` e schemas de formulário (`zod` + `react-hook-form`). - `$specsfy-specialist-nextjs` quando o formulário submete para uma Server Action — validação e autorização server-side pertencem a essa skill. - `$specsfy-specialist-react-ui-components` e `$specsfy-specialist-ui-design` quando o projeto precisa de uma galeria de referências visuais mais ampla ou de definições de composição de página. - `$specsfy-specialist-web-accessibility` para auditoria além do que a base instalada oferece por padrão. - `$specsfy-specialist-application-security` para validação de formulário no servidor e autorização de mutations expostas por Server Actions/endpoints. Leia [references/primitives.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-shadcn-ui/references/primitives.md) antes de alterar um componente shadcn/ui para identificar a base instalada. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-shadcn-ui/references/standards.md) para registry, padrões de dashboard, Data Table, formulário, overlay e chart, com fontes oficiais. ### Especialista Arquitetura de software no Specsfy: guia - URL: https://promovaweb.com/docs/specsfy/especialistas/software-architecture - Descrição: Consulte o guia da especialista Arquitetura de software no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar para decisão com custo alto de reverter: introduzir um serviço, uma fila, um cache distribuído, mudar o boundary entre módulos ou a direção de uma dependência estrutural. - Acionar também quando um atributo de qualidade (latência, disponibilidade, consistência, capacidade) precisar virar critério explícito de decisão. - Não acionar para renomear, mover arquivo ou refatorar localmente sem impacto de boundary — isso é manutenção, não decisão arquitetural. - Rodar `$specsfy-specialist-domain-modeling` primeiro quando o boundary em disputa for de um conceito de domínio ainda não modelado — a arquitetura decide onde colocar um boundary já definido pelo domínio, não o inventa. ## Fluxo 1. Definir finalidade do sistema, restrições reais (orçamento, prazo, time disponível) e cenários de atributo de qualidade mensuráveis (não adjetivos como "escalável"). 2. Mapear o estado observado: owners de dados, dependências existentes entre módulos/serviços, fluxos de runtime críticos e onde a dor atual está. 3. Identificar as forças em conflito, as decisões que seriam caras de reverter depois e os riscos de cada caminho. 4. Comparar opções pelos mesmos critérios (os cenários do passo 1) e pelo custo operacional real de cada uma — rede, consistência distribuída, observabilidade adicional, times a coordenar. 5. Escolher a menor estrutura que satisfaz os cenários definidos — a opção mais simples que atende o atributo de qualidade vence por padrão. 6. Definir plano de transição: compatibilidade durante a migração, observabilidade para detectar regressão e um caminho de rollback real. 7. Registrar a decisão (ADR) e verificar os boundaries propostos por teste de dependência automatizado ou análise estática, quando possível. ## Padrões - Dar a cada módulo responsabilidade, dados e interface claros — um módulo sem contrato explícito vira acoplamento implícito para quem o consome. - Direcionar dependências das políticas voláteis para as estáveis (regra de dependência): módulo de negócio não deve depender de detalhe de framework/infra, o inverso é o padrão saudável. - Evitar introduzir serviço, fila, cache ou camada de abstração sem um cenário consumidor real e mensurável que a justifique — abstração especulativa cria custo permanente por benefício hipotético. - Separar explicitamente a arquitetura implementada (o que existe hoje) da arquitetura desejada (para onde está migrando) — tratá-las como a mesma coisa esconde dívida e trabalho pendente. - Expressar todo atributo de qualidade como cenário mensurável: estímulo, ambiente, resposta esperada, medida (ex.: "sob 200 req/s, p99 < 300ms"), nunca como adjetivo solto. - Manter decisões facilmente substituíveis como locais e reversíveis, e tornar explícitas (ADR) apenas as decisões realmente caras de mudar depois. - Evoluir arquitetura por seams verificáveis e incrementais (strangler fig, expand/contract) em vez de reescrita completa — reescrita total raramente entrega no prazo e perde conhecimento acumulado no sistema atual. ## Antipadrões - Adotar microsserviços porque "é o padrão da indústria" sem um cenário de escala, time ou deployment independente que o justifique — o custo de consistência distribuída e operação multiplicada é real e imediato, o benefício é hipotético até que o cenário apareça. - Big ball of mud: módulos sem fronteira nem direção de dependência definida, onde qualquer parte pode chamar qualquer outra diretamente. - Big design up front sem cenário de qualidade mensurável — arquitetura "para o futuro" sem estímulo concreto que a justifique tende a resolver o problema errado e travar decisões reversíveis cedo demais. - Adicionar uma camada de indireção genérica "para flexibilidade futura" quando existe apenas um consumidor real hoje — paga o custo de complexidade antes de haver qualquer evidência de que a flexibilidade será usada. ## Validação - Caminhos críticos, modos de falha, requisitos de consistência e capacidade foram avaliados contra os cenários definidos, não só o caminho feliz. - Existem testes de arquitetura ou de dependência (quando a linguagem/ ferramenta permitir) que travam a direção de dependência decidida. - Há ensaio da migração: compatibilidade durante a transição, plano de rollback testado, não apenas descrito. - Impactos em segurança, dados e operação foram revisados como parte da decisão, não como reflexão posterior. - Não declarar uma arquitetura "escalável" ou "resiliente" sem o cenário mensurável e a evidência que o comprova — linguagem absoluta sem prova é proibida. ## Skills relacionadas - `$specsfy-specialist-technical-research` reúne evidência primária quando a decisão depende de capacidade, limite ou compatibilidade externa. - `$specsfy-specialist-domain-modeling` para decidir o boundary de um conceito de domínio antes de decidir o boundary de serviço/módulo. - `$specsfy-specialist-delivery-engineering` para o plano de rollout e rollback de uma migração arquitetural. - `$specsfy-specialist-performance-engineering` quando o atributo de qualidade em disputa for latência ou capacidade sob carga real. - `$specsfy-specialist-code-review` para verificar que o código implementado respeita os boundaries decididos aqui. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-software-architecture/references/standards.md) para views arquiteturais, formato de ADR, atributos de qualidade e fontes primárias. ### Especialista Supabase no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/supabase - Descrição: Consulte o guia da especialista Supabase no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto tem `supabase/config.toml`, migrations em `supabase/migrations/`, ou clientes `@supabase/supabase-js` e a tarefa envolve RLS, Auth, Storage, Realtime, Edge Functions ou ambiente local Supabase (`supabase start`). - Acionar também para revisão de política de acesso, policy RLS ausente ou incorreta, ou exposição indevida de `service_role`. - Não acionar para tuning puro de índice/plano/isolation do Postgres subjacente sem o contexto Supabase — usar `$specsfy-specialist-postgres` e trazer o resultado de volta para as policies. - Combinar com `$specsfy-specialist-application-security` quando a revisão envolver JWT, claims customizadas ou superfícies de autorização fora do banco. ## Fluxo 1. Identificar SDK usado (`@supabase/supabase-js`, `ssr`, framework específico), projeto, schemas expostos via API, migrations existentes e estratégia de ambientes (local, preview, produção). 2. Mapear identidades, tenants, papéis (`anon`, `authenticated`, papéis customizados) e a origem de cada claim usada em decisão de acesso (`auth.uid()`, `auth.jwt()`, metadata). 3. Modelar tabelas, funções e views no Postgres primeiro — a API REST/ GraphQL e os tipos gerados são derivados do schema, não o contrário. 4. Definir privilégios (`GRANT`) para o objeto e políticas RLS para cada operação (`SELECT`, `INSERT`, `UPDATE`, `DELETE`) e papel, negando por padrão. 5. Implementar a migration versionada e testar com usuários representativos de cada papel, incluindo o caso sem sessão (`anon`). 6. Validar Auth, Storage, Realtime ou Edge Functions apenas quando o projeto de fato os usa — não configurar superfície que a aplicação não expõe. 7. Verificar tipos TypeScript gerados, estratégia de pooling (session vs transaction), logs e política de backup/rollback antes de considerar pronto. ## Padrões - Habilitar RLS em toda tabela de schema exposto à API e negar por padrão — tabela com RLS desabilitada em schema público é acessível por qualquer `anon` que descubra o nome. - Nunca expor `service_role` no cliente (browser, app mobile, bundle público), ela ignora RLS e só pertence a ambiente de servidor confiável. - Testar cada policy separadamente para `anon`, `authenticated` e qualquer papel de aplicação — uma policy que "parece" restringir mas usa `USING (true)` equivale a não ter policy. - Tratar como superfície crítica: funções `SECURITY DEFINER` (rodam com privilégio do dono, não do chamador — precisam de `search_path` fixo e validação interna própria), claims customizadas no JWT (podem ser manipuladas se a fonte não for confiável) e buckets de Storage marcados como públicos. - Versionar toda mudança de schema em migration (`supabase migration new`), edição manual no dashboard de produção diverge do histórico e quebra `supabase db diff`/CI. - Separar autorização de produto (o que este usuário pode fazer com este registro) da mera autenticação (quem é o usuário) — RLS resolve a primeira, Auth resolve a segunda. - Planejar conexão direta (poucas conexões persistentes, migrations), session pool (compatibilidade ampla, `PREPARE` funciona) ou transaction pool (alta concorrência, serverless) conforme o workload e o driver. ## Antipadrões - Policy `USING (true)`/`WITH CHECK (true)` deixada "temporariamente" para destravar desenvolvimento e nunca revisada antes de produção — equivale a RLS desabilitada. - Checar tenant/ownership só no cliente (filtrar a query pelo `tenant_id` no frontend) sem policy correspondente no banco — qualquer chamada direta à API contorna o filtro. - Função `SECURITY DEFINER` sem `SET search_path = ''`/schema fixo — permite sequestro de função por objeto de mesmo nome em outro schema no `search_path` do chamador. - Migration aplicada manualmente em produção via dashboard, divergindo do histórico versionado — o próximo `db push`/`db diff` não sabe reconciliar o estado real. - Confiar em claim customizada do JWT sem validar sua origem (ex.: campo gravável pelo próprio usuário sendo usado como papel de autorização). ## Validação - Provar acesso permitido e negado com identidades reais de teste para cada papel, incluindo sessão ausente (`anon`) e o "vizinho" de outro tenant. - Executar `supabase db reset`/lint/migrations no ambiente local antes de promover — o projeto local reproduz o schema e as policies de produção. - Conferir tipos gerados (`supabase gen types`) atualizados, replicação/ Realtime restrita ao mesmo modelo de tenancy, policies de Storage por bucket, e segredos de Edge Functions fora do código-fonte. - Avaliar recuperação e exportação dos dados além do backup gerenciado — testar um restore ou export completo, não assumir que o backup automático garante RTO aceitável. - Não declarar uma tabela "protegida por RLS" sem o teste negativo (acesso que deveria falhar, falhando de fato). ## Skills relacionadas - `$specsfy-specialist-docker` cobre serviços locais e imagens auxiliares, esta skill governa os contratos gerenciados da plataforma Supabase. - `$specsfy-specialist-postgres` para modelagem de schema, índice, plano de query e isolation por trás do Supabase. - `$specsfy-specialist-application-security` para modelagem de ameaça de JWT, claims e superfícies de autorização além de RLS. - `$specsfy-specialist-laravel` quando o mesmo projeto tiver um backend Laravel consumindo o mesmo Postgres além do Supabase. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-supabase/references/standards.md) antes de alterar RLS, Auth, schemas expostos, Storage, Realtime ou estratégia de conexão. ### Especialista Tailwind CSS no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/tailwind-css - Descrição: Consulte o guia da especialista Tailwind CSS no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando o projeto depende de `tailwindcss` e a tarefa envolve classe utilitária, tema, variante, responsividade ou dark mode. - Acionar também para decidir se um padrão visual repetido deve virar token, `@apply` local ou componente extraído. - Não acionar para a escolha da biblioteca de componentes em si (Radix, shadcn/ui), usar `$specsfy-specialist-shadcn-ui` ou `$specsfy-specialist-react-ui-components` para isso e voltar aqui para o sistema de tokens e classes que os sustenta. - Combinar com `$specsfy-specialist-web-accessibility` para contraste, zoom e `prefers-reduced-motion`. ## Fluxo 1. Confirmar a versão do Tailwind, a integração (Vite, PostCSS, framework) e onde os tokens são declarados (`tailwind.config.js` ou `@theme` em CSS na v4) — a sintaxe de configuração muda entre gerações. 2. Traduzir o layout e os estados da interface em constraints responsivas (breakpoints ou `@container`) antes de escrever a primeira classe. 3. Reutilizar tokens semânticos já existentes (cor, espaçamento, radius, tipografia) antes de recorrer a valor arbitrário (`w-[137px]`). 4. Implementar mobile-first: escrever o estilo base para a tela menor e sobrepor apenas o que muda nos breakpoints maiores. 5. Cobrir estados interativos (`hover`, `focus-visible`, `disabled`, `aria-*`) e preferências do usuário (`dark`, `motion-reduce`, `forced-colors`) desde a primeira versão do componente, não como retrofit. 6. Extrair um componente (não `@apply`) quando o padrão repetido representa uma unidade semântica reconhecível (um "Card", um "Badge"), e não apenas uma coincidência visual entre dois lugares. 7. Validar o CSS gerado no build de produção: nenhuma classe usada dinamicamente deve estar ausente por não ser detectável estaticamente pelo scanner de conteúdo. ## Padrões - Manter cor, espaçamento, radius e tipografia como tokens com nome de intenção (`bg-surface`, `text-muted`) sempre que o projeto já tiver um sistema de design — não introduzir valor solto que dribla o token existente. - Expressar estado (hover, foco, seleção, erro) com variantes do próprio Tailwind (`hover:`, `aria-selected:`, `data-[state=open]:`), nunca escondendo a lógica de estado em concatenação de string opaca fora da vista do build. - Não usar `@apply` como substituto geral de componente — ele recria uma folha de estilo tradicional dentro do utility-first e perde a colocação (a classe deixa de estar ao lado do elemento que ela estiliza). - Garantir que toda classe construída dinamicamente (template string, concatenação condicional) seja detectável estaticamente pelo scanner de conteúdo — usar mapas completos de classes literais em vez de montar a classe por concatenação de partes (`text-${color}-500` não funciona: o scanner não executa o template). - Tratar dark mode, `prefers-reduced-motion`, `prefers-contrast` e `forced-colors` como requisito de design, não como camada opcional adicionada depois. - Preferir layout fluido (`flex`, `grid`, unidades relativas) e `@container` quando o componente precisa responder ao próprio contêiner (ex.: um card que muda de layout dentro de uma sidebar estreita), não ao viewport inteiro. - Não multiplicar valores arbitrários (`p-[13px]`, `text-[15px]`) sem antes perguntar se um novo token de escala deveria existir — um valor arbitrário isolado é aceitável, vários próximos e repetidos indicam token ausente. ## Antipadrões - Classe montada por concatenação de variável (`` `bg-${color}-500` ``) — o scanner de conteúdo do Tailwind não executa JS, então essa classe nunca é gerada no CSS final, use um mapa literal de classes completas. - `@apply` usado para recriar dezenas de componentes CSS tradicionais — perde a vantagem de colocation do utility-first e cria uma folha de estilo paralela difícil de rastrear. - Cor, espaçamento ou radius hardcoded (`#3b82f6`, `17px`) ao lado de um sistema de tokens já existente — quebra o tema (claro/escuro, marca) na primeira mudança centralizada. - Adicionar dark mode, foco visível ou movimento reduzido só depois de uma reclamação de acessibilidade, em vez de tratá-los como parte do componente desde a primeira versão. - Confundir a responsabilidade desta skill com a escolha de biblioteca de componentes prontos — Tailwind é a camada de utilitários/tema, a escolha de "qual Data Table usar" pertence a `$specsfy-specialist-shadcn-ui`/`$specsfy-specialist-react-ui-components`. ## Validação - Rodar o build de produção e inspecionar se alguma classe esperada está ausente do CSS final (sinal de classe não detectável estaticamente). - Testar em viewports pequenos e grandes, com container real quando o componente usar `@container`, em zoom 200% e 400% (reflow a 320px de largura equivalente), sem perda de conteúdo ou scroll horizontal indesejado. - Percorrer `hover`, `focus-visible`, `disabled`, `loading`, `error` e `selected` visualmente e por teclado. - Checar contraste nos temas claro e escuro, e o comportamento com `prefers-reduced-motion`/`forced-colors` ativados no sistema operacional. - Não declarar um componente "responsivo" ou "acessível" apenas por ter classes `sm:`/`dark:` presentes, a evidência acima é obrigatória antes da afirmação. ## Skills relacionadas - `$specsfy-specialist-reui` para composições React e Tailwind do catálogo gratuito. - `$specsfy-specialist-shadcn-ui` para o sistema de componentes construído sobre Tailwind + Radix, este especialista cobre o token/utilitário que o sustenta. - `$specsfy-specialist-react`, `$specsfy-specialist-nextjs` e `$specsfy-specialist-astro` fornecem o componente/framework onde as classes Tailwind são aplicadas, esta skill não decide estrutura de componente nem fronteira server/client. - `$specsfy-specialist-typescript` tipa variantes `cva` quando o projeto expõe props de estilo fortemente tipadas. - `$specsfy-specialist-react-ui-components` e `$specsfy-specialist-ui-design` para a escolha e composição visual da página. - `$specsfy-specialist-web-accessibility` para contraste, zoom, reflow e `prefers-reduced-motion` em profundidade. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-tailwind-css/references/standards.md) para camadas de tokens, variantes, `@container`, detecção de classes e migração entre versões, com fontes oficiais. ### Especialista Pesquisa técnica no Specsfy: fluxo e validação - URL: https://promovaweb.com/docs/specsfy/especialistas/technical-research - Descrição: Consulte o guia da especialista Pesquisa técnica no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar quando uma decisão de arquitetura, biblioteca ou abordagem depende de um fato técnico que ninguém confirmou com fonte primária. - Acionar também para comparar alternativas antes de uma decisão cara de reverter, ou para verificar se um comportamento assumido ainda é válido na versão atual de uma dependência. - Não acionar para reconfirmar uma escolha já decidida só para produzir justificativa — isso é viés de confirmação, não pesquisa. - Combinar com `$specsfy-specialist-software-architecture` quando a pesquisa embasar diretamente uma decisão estrutural registrável em ADR. ## Fluxo 1. Formular a pergunta específica, a decisão que ela vai suportar, o escopo e a recência necessária (comportamento de hoje, ou histórico é suficiente?). 2. Definir de antemão que evidência confirmaria ou refutaria cada alternativa — sem isso, qualquer resultado parece confirmar a hipótese inicial. 3. Priorizar, nesta ordem: especificação/standard, documentação oficial versionada, código-fonte e changelog oficiais, experimento reproduzível no ambiente alvo, e só então fonte secundária. 4. Verificar versão, data de publicação e aplicabilidade ao ambiente real observado no projeto — um comportamento documentado para outra versão não é evidência para a versão em uso. 5. Triangular toda afirmação crítica para a decisão com uma segunda fonte independente, e executar experimento controlado quando a documentação não resolver a dúvida. 6. Separar explicitamente fatos confirmados, inferências (prováveis mas não confirmadas), riscos e lacunas que permanecem sem evidência. 7. Sintetizar com links diretos à fonte, próximos à afirmação específica que sustentam, e a implicação concreta para a decisão em jogo. ## Padrões - Não usar snippet de fórum, blog pessoal ou resposta de IA genérica como autoridade sobre comportamento de API quando existe fonte primária acessível — usar como pista para onde procurar a fonte primária, não como citação final. - Citar a página e a seção específica da fonte próxima da afirmação, não um link genérico para a home da documentação. - Sintetizar preservando o contexto necessário para a decisão, evitar transcrição extensa que apenas desloca o trabalho de leitura para depois. - Registrar versão e data de qualquer fonte cujo comportamento pode mudar entre releases — sem isso, a conclusão expira silenciosamente. - Quando duas fontes conflitam, declarar o conflito explicitamente em vez de escolher uma silenciosamente sem justificar por que ela prevalece. - Não criar um `research.md` paralelo à fonte normativa do projeto, a pesquisa é indexada e vive no local que a spec do projeto consumidor define. - Tratar benchmark publicado por fornecedor da própria tecnologia como evidência interessada — útil como ponto de partida, nunca como conclusão final sem reprodução independente. ## Antipadrões - Pesquisar depois de já ter decidido, buscando apenas confirmação — a pergunta formulada no passo 1 já nasce enviesada ("por que X é melhor", em vez de "X ou Y, e sob que critério"). - Citar "a documentação diz" sem link nem versão — torna a afirmação impossível de reverificar quando o comportamento mudar. - Copiar benchmark de marketing de um fornecedor como se fosse medição neutra do ambiente do projeto. - Resolver uma pergunta com múltiplas fontes conflitantes escolhendo a que confirma a preferência inicial, sem registrar que havia conflito. ## Validação - Cada conclusão que sustenta a decisão tem evidência direta e rastreável (link + versão + data), não apenas afirmação de memória. - As fontes usadas correspondem à versão e ao runtime real do projeto consumidor, não a uma versão genérica ou desatualizada. - Experimentos executados são reproduzíveis por outra pessoa e não alteram produção nem dado real. - Lacunas e incerteza residual estão explícitas na síntese final, não escondidas atrás de uma conclusão mais confiante do que a evidência permite. - Não apresentar uma hipótese não triangulada como fato — linguagem que implica certeza sem a evidência correspondente é proibida. ## Skills relacionadas - `$specsfy-specialist-domain-modeling` usa fontes externas para alinhar conceitos sem substituir o vocabulário validado do domínio. - `$specsfy-specialist-prototyping` transforma incerteza técnica em experimento descartável com hipótese e critério de parada. - `$specsfy-specialist-software-architecture` quando a pesquisa embasar uma decisão estrutural registrável em ADR. - `$specsfy-specialist-laravel-package-manager` quando a pesquisa precisar confirmar documentação, versão ou instalação de um pacote Composer Laravel. - `$specsfy-specialist-debugging` quando a "pesquisa" for, na verdade, investigar por que um comportamento observado diverge do documentado — nesse caso o diagnóstico de causa raiz é o objetivo, não a comparação de alternativas. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-technical-research/references/standards.md) para a hierarquia de fontes, a matriz de avaliação de evidência e o formato de síntese. ### Especialista TypeScript no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/typescript - Descrição: Consulte o guia da especialista TypeScript no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar quando a tarefa envolve `tsconfig`, erro de compilação, modelagem de tipo, generics, módulos ou declarations de biblioteca. - Acionar também para revisar uma API pública TS/JS antes de publicá-la, ou para decidir como validar um dado que entra de fora (rede, arquivo, env). - Não acionar para a lógica de negócio ou de framework em si (React, hooks, rotas) — combine com a skill do framework e use esta para o contrato de tipos que ele expõe. - Combinar com `$specsfy-specialist-web-api-design` quando o tipo modela um contrato de API consumido por outro serviço. ## Fluxo 1. Ler `tsconfig` (strict flags ativas), `package.json#type`, bundler e runtime alvo, e a versão do TypeScript instalada antes de recomendar uma sintaxe ou opção específica. 2. Identificar as fronteiras não confiáveis do código alterado (entrada de rede, arquivo, variável de ambiente, resposta de terceiro) e os tipos que formam a API pública do módulo. 3. Modelar os estados válidos com unions discriminadas e narrowing, eliminando por construção combinações de campos que nunca deveriam coexistir. 4. Deixar a inferência trabalhar internamente, anotar explicitamente apenas onde o contrato precisa ficar estável (assinatura pública, retorno de função exportada). 5. Eliminar `any`, `as` e `!` injustificados na área alterada — cada um deve ter uma razão documentada ou dar lugar a narrowing real. 6. Validar todo dado externo em runtime com um schema antes de tratá-lo como o tipo esperado, tipo estático não impede um payload malformado em produção. 7. Rodar typecheck sem emissão, testes, lint e build em todos os targets reais (Node, browser, edge) antes de considerar a mudança pronta. ## Padrões - Ativar as opções strict compatíveis com o projeto (`strict`, `strictNullChecks`, `noUncheckedIndexedAccess` quando viável) e corrigir os erros revelados por elas, nunca silenciá-los com cast cosmético. - Preferir uma union discriminada (`{ status: "ok"; data: T } | { status: "error"; error: E }`) a combinações de booleanos/campos opcionais que permitem estado inválido (`{ loading: true; data: T; error: E }` simultâneos). - Usar `unknown` — não `any` — para dado ainda não validado numa fronteira, e só tratá-lo como o tipo esperado depois de narrowing ou parse explícito. - Manter generics mínimos: um parâmetro de tipo só se justifica quando expressa uma relação real entre dois ou mais valores (entrada e saída, chave e valor), generic sem essa relação é complexidade sem benefício. - Preferir union de literais ou objeto `as const` a `enum` quando interoperabilidade com JS puro ou serialização simples importa — `enum` gera código em runtime e tem regras de comparação próprias. - Separar imports `import type` de imports de valor, e respeitar a configuração ESM/CJS do projeto (`moduleResolution`, `type` no `package.json`) em vez de assumir a interoperabilidade de outro projeto. - Testar o tipo público quando uma regressão de inferência seria observável para quem consome a biblioteca (ex.: com `tsd` ou um teste de compilação dedicado), não apenas o comportamento em runtime. ## Antipadrões - `as SomeType` para silenciar um erro do compilador sem checar se o valor realmente tem essa forma — é uma promessa não verificada que quebra em runtime na primeira divergência. - `!` (non-null assertion) em uma cadeia de acesso a propriedade só para "passar no build" — esconde exatamente o caso `null`/`undefined` que o `strictNullChecks` foi ativado para pegar. - Tipar a resposta de uma API externa direto do retorno de `fetch` sem validação — o tipo é uma afirmação do desenvolvedor, não uma garantia, um contrato mudou no backend e o app só descobre com um crash em produção. - Generic decorativo (`function identity(x: T): T`) usado como se desse segurança adicional sem expressar nenhuma relação real entre parâmetros. - Duplicar um tipo já exportado por outro módulo com um nome ligeiramente diferente ("tipo gêmeo") em vez de importar e reexportar — os dois divergem silenciosamente na próxima mudança. ## Validação - Rodar typecheck sem emissão (`tsc --noEmit` ou equivalente) e o build de todos os targets configurados (Node, browser, edge) antes de considerar a mudança pronta. - Escrever teste runtime para cada validação de dado externo e para serialização/deserialização de tipos que atravessam uma fronteira (rede, storage). - Quando o projeto publica uma biblioteca, checar as declarations geradas (`.d.ts`) e testar compatibilidade com pelo menos um consumidor real ou simulado. - Buscar na área alterada por `@ts-ignore`, `@ts-expect-error` sem comentário explicativo, `as any`, cast duplo (`as unknown as T`) e tipos duplicados — cada ocorrência é uma dívida a justificar ou remover. - Não declarar o código "type-safe" apenas porque compila, sem validação runtime nas fronteiras e sem os testes acima, a garantia é só estática. ## Skills relacionadas - `$specsfy-specialist-react` para a lógica de componente que consome os tipos modelados aqui (props, estado, union de eventos). - `$specsfy-specialist-nextjs` e `$specsfy-specialist-astro` consomem estes tipos para params de rota, Server Actions/endpoints e content collections, esta skill não decide roteamento ou fronteira server/client. - `$specsfy-specialist-tailwind-css` e `$specsfy-specialist-shadcn-ui` usam tipos desta skill para variantes (`cva`) e schemas de formulário fortemente tipados. - `$specsfy-specialist-web-api-design` quando o tipo espelha um contrato de API consumido por outro serviço — a fonte de verdade do contrato vive lá. - `$specsfy-specialist-code-review` para revisão ampla além de tipos, quando a mudança também afeta lógica de negócio ou arquitetura. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-typescript/references/standards.md) para modelagem de estado com tipos, configuração strict, módulos, bibliotecas e validação runtime, com fontes oficiais. ### Especialista Design de UI no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/ui-design - Descrição: Consulte o guia da especialista Design de UI no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para definir ou revisar hierarquia, grid, shell, densidade, tokens, estados visuais, tabelas, formulários e navegação de uma interface. - Acionar quando uma tela funciona, mas a composição dificulta escaneamento, comparação, priorização ou recuperação de erros. - Não acionar para descobrir se o fluxo resolve a necessidade da pessoa, usar `$specsfy-specialist-ux-design` para pesquisa, jornada e teste de tarefa. - Combinar com `$specsfy-specialist-react-ui-components` quando a implementação React puder partir de uma referência TSX copiável. ## Fluxo 1. Carregar `$specsfy-specialist-design-system` e ler `DESIGNSYSTEM.MD` antes da composição. Confirmar que a jornada e o fluxo de informação foram definidos com a pessoa. Para tela ou formulário novo, registrar a tarefa principal, as telas, os campos, as validações e o padrão de abertura escolhido. Se não houver direção visual, aplicar os defaults do documento e só retornar à UX quando faltar uma resposta sobre comportamento ou tarefa. 2. Ler a stack observada, tokens, componentes, breakpoints e screenshots atuais antes de propor uma linguagem nova. Quando o sistema já existir, inspecionar também as telas e fluxos afetados, sua navegação, conteúdo, permissões e estados antes de mudar a composição. Preserve framework, primitives, estilos e convenções locais. Só proponha nova biblioteca quando a pessoa confirmar a mudança ou quando a stack não oferecer uma base identificável. 3. Identificar pessoa, tarefa principal, frequência, dispositivo, densidade e consequência do erro, ordenar conteúdo e ações por essa prioridade. 4. Para CRUD, aplicar a matriz macro: lista com `PageHeader` e `DataGrid`, detalhe com `PageHeader` e `DetailLists`, criar e editar com `PageHeader` e seções de formulário em duas colunas responsivas. Cada seção tem coluna de contexto e painel de campos, registrar a justificativa apenas para uma exceção explícita. 5. Mapear dados, unidades, permissões e estados nominal, loading, empty, partial, error, offline e permission denied antes do layout. 6. Escolher shell, navegação e grid coerentes com a arquitetura da informação, usar a matriz em [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-ui-design/references/standards.md). 7. Definir hierarquia por agrupamento, contraste, escala e espaço e mapear cada escolha para tokens semânticos. 8. Implementar ou especificar componentes e casos extremos em todos os breakpoints sem criar variantes equivalentes às já existentes. 9. Durante o desenvolvimento, conferir bordas, espaçamentos, margens, padding e tipografia do sistema, mesmo sem pedido da pessoa. Compare renderização, inspeção DOM ou outra forma equivalente nos estados e viewports relevantes. 10. Validar conteúdo real, legibilidade, responsividade, acessibilidade e consistência com comprovação visual e comportamental. Registrar o resultado no item `VISUAL` da tarefa. Quando a implementação usar React, carregar `$specsfy-specialist-react-ui-components` depois de definir a composição para escolher referências TSX sem transferir a escolha visual para o catálogo de exemplos. ## Padrões - Dashboard responde perguntas, não é coleção de cards decorativos. - Colocar visão geral antes do detalhe e ação junto do objeto afetado. - Usar tabela para comparação densa, lista para leitura e cards para entidades distintas. - Preservar posição, filtros e contexto ao navegar entre lista e detalhe. - Exibir unidade, período, origem, atualização e vazio nos dados. - Manter ação destrutiva distinta, explicada e reversível quando possível. - Definir tokens semânticos e uma escala limitada de spacing/tipografia. - Construir personalidade por dados, linguagem, tokens, ritmo e estados, não por uma pilha genérica de cards. - Exibir labels acima dos campos e erro de campo em vermelho abaixo do campo. - Usar duas colunas para campos relacionados nos breakpoints largos, uma coluna no mobile e largura total para campos longos, ajuda, upload e erros. - Tornar a linha inteira do `DataGrid` a navegação do detalhe, manter botões, checkboxes e menus internos acima do link da linha. - Manter `Breadcrumb` em todas as telas, com a equipe ativa, o módulo e a tela atual. Em Laravel, adaptar o `Breadcrumb` ou `Breadcrumbs` já renderizado pelo shell existente. - Usar um único `PageHeader` componentizado e reutilizável em lista, detalhe, criação e edição do CRUD. - Usar `DataGrid` em largura total na lista, mostrar sempre a coluna `ID`, transformar a linha em link para o detalhe e manter botões de editar e apagar independentes dentro da linha. ## Antipadrões - Distribuir métricas em cards idênticos sem pergunta, período ou comparação, a tela exibe números, mas não permite interpretar variação ou prioridade. - Criar uma nova cor, spacing ou variante para cada tela, o design system perde vocabulário comum e torna mudanças globais imprevisíveis. - Usar placeholder como label, ícone sem texto acessível ou cor como único estado, o significado desaparece conforme interação e acessibilidade. - Esconder ações frequentes em menus para obter uma tela “limpa”, aumenta custo operacional e reduz descoberta sem diminuir complexidade real. - Usar cards para uma lista que pede comparação ou substituir `PageHeader` por um título solto. - Duplicar o markup do `PageHeader` por tela, esconder o `ID`, estreitar o `DataGrid` ou deixar editar e apagar fora da linha do registro. ## Validação - Comparar cenários nominal, loading, empty, partial, error, offline e permission denied na mesma composição. - Conferir `DataGrid`, `DetailLists`, `PageHeader` e formulários em seções com duas colunas responsivas conforme a superfície CRUD. - Conferir `Breadcrumb` em cada tela, com o nome da equipe visível e o item atual marcado como página. Em Laravel, confirmar o reaproveitamento do componente já existente. - Conferir que uma exceção ao `DESIGNSYSTEM.MD` tem alcance registrado. - Exercitar conteúdo curto/longo, números extremos, tradução expandida e preferências de data, moeda e timezone. - Verificar viewport mínimo suportado, zoom 200%, reflow, contraste, teclado, foco e reduced motion. - Auditar tokens e componentes novos contra os já publicados e justificar qualquer duplicação. - Conferir bordas, espaçamentos, margens, padding e tipografia nos estados e viewports relevantes durante a implementação, registrando o resultado no item `VISUAL`. - Revisão final conjunta com `$specsfy-specialist-react-ui-components` quando algum asset React tiver sido adaptado. - Não declarar a interface consistente ou responsiva sem screenshots ou inspeção equivalente nos estados e viewports críticos. ## Skills relacionadas - `$specsfy-specialist-reui` para composições React e Tailwind já definidas no catálogo gratuito. - `$specsfy-specialist-interface-experience` para mapear telas, ações e estados antes da composição visual. - `$specsfy-specialist-nextjs` governa a fronteira server/client e o roteamento da interface, esta skill governa composição e estados visuais. - `$specsfy-specialist-prototyping` testa alternativas de composição no menor nível de fidelidade necessário antes da implementação definitiva. - `$specsfy-specialist-shadcn-ui` fornece primitives e variantes, esta skill decide hierarquia e coerência do sistema que os utiliza. - `$specsfy-specialist-ux-design` governa pesquisa, jornada, arquitetura da informação e validação de tarefas. - `$specsfy-specialist-react-ui-components` fornece exemplos TSX depois que a composição e a hierarquia estão definidas. - `$specsfy-specialist-design-system` fornece regras macro, defaults e cenários canônicos antes da composição visual. - `$specsfy-specialist-web-accessibility` conduz auditoria WCAG, teclado e tecnologia assistiva. - `$specsfy-specialist-tailwind-css` traduz tokens e variantes para utilitários quando essa é a stack observada. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-ui-design/references/standards.md) para matrizes de layout, densidade, dados, tokens, estados e regras de revisão visual. ### Especialista Design de UX no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/ux-design - Descrição: Consulte o guia da especialista Design de UX no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar para investigar comportamento, estruturar jornadas, arquitetura da informação, formulários, onboarding, conteúdo e recuperação de erros. - Acionar quando há dúvida sobre o problema, a sequência, a linguagem ou a capacidade de uma pessoa concluir uma tarefa. - Não acionar para acabamento visual isolado, usar `$specsfy-specialist-ui-design` quando intenção e fluxo já estão validados. - Combinar com `$specsfy-specialist-prototyping` quando uma hipótese precisar de artefato descartável antes de implementação. ## Fluxo 1. Carregar `$specsfy-specialist-design-system` e ler `DESIGNSYSTEM.MD` antes de propor a solução. Quando a entrega criar ou mudar uma interface para pessoas, conduzir a descoberta. Perguntar, pelo contrato central, que telas existem, como a informação percorre o fluxo, quais campos e validações entram no formulário e como cada ação abre: página, painel lateral, modal, área expandida ou outro formato. Se a pessoa não informar direção visual, aplicar os defaults do `DESIGNSYSTEM.MD`, perguntar sobre composição somente quando houver conflito ou lacuna de tarefa. Reaproveitar contexto já confirmado e perguntar somente o que falta. 2. Ler a stack e as telas existentes antes de sugerir um fluxo visual. A jornada deve usar a tecnologia e os padrões observados, se a camada de interface não estiver clara, encaminhar a pergunta para a pessoa. Examinar o sistema atual para identificar o que a pessoa já vê, faz e espera em cada tela afetada antes de propor uma alteração. 3. Formular a hipótese de comportamento antes de escolher método, definir público, contexto, frequência e consequência de falha. 4. Mapear material existente e marcar separadamente fato observado, inferência, hipótese e preferência interna. 5. Selecionar método proporcional à pergunta e ao impacto de falha usando [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-ux-design/references/standards.md), definir recrutamento, consentimento, roteiro e regra de parada. 6. Mapear jornada atual com entradas, escolhas, esperas, erros, canais, dependências e handoffs, não apagar exceções críticas. 7. Prototipar na fidelidade mínima que torne a hipótese testável sem simular comportamento que altere o resultado. 8. Conduzir sessões com tarefas e prompts neutros, registrando sucesso, erro, tempo, hesitação, compreensão e citações relevantes. 9. Sintetizar achados por comprovação, severidade, alcance e impacto, separar claramente achado, interpretação, recomendação e questão aberta. Não escolher painel lateral, modal ou outro padrão por preferência interna. Registrar a resposta textual da pessoa e encaminhar a composição para `$specsfy-specialist-ui-design`. Para CRUD, cobrir lista com linha clicável, vazio, detalhe, criação e edição em seções de duas colunas responsivas, erro de campo, ausência de permissão e falha de carregamento. ## Padrões - Usar linguagem do domínio e revelar complexidade progressivamente. - Manter status do sistema, próximo passo e possibilidade de recuperação visíveis. - Pedir informação no momento necessário e explicar o motivo. - Evitar confirmação para ações triviais, oferecer undo quando mais seguro. - Preservar dados após erro e apontar correção no contexto. - Projetar onboarding como caminho para valor, não tour obrigatório. - Não usar dark patterns, urgência artificial ou consentimento ambíguo. - Usar a hierarquia de dados e linguagem do produto para dar personalidade à experiência, mantendo `PageHeader`, `DataGrid`, `DetailLists` e formulários em seções de duas colunas responsivas nos defaults do sistema. - Manter `Breadcrumb` em todas as telas, com a equipe ativa, o módulo e a tela atual. Em Laravel, reaproveitar o componente que o shell já renderiza. ## Antipadrões - Perguntar “você gostou?” ou apresentar a solução antes da tarefa, mede cortesia e racionalização, não capacidade de uso. - Transformar uma única sessão ou fala em regra universal, sem recorrência, contexto e triangulação, a comprovação não sustenta abrangência. - Recrutar apenas colegas ou especialistas quando o produto serve iniciantes, o vocabulário e os atalhos observados deixam de representar o público. - Entregar uma lista de soluções sem rastrear cada item ao achado, preferência da equipe passa a parecer conclusão de pesquisa. - Medir apenas tempo sem distinguir abandono, sucesso assistido e erro crítico, o número mascara a qualidade real da conclusão. ## Validação - Demonstrar que cada pergunta de pesquisa tem método, participante e comprovação compatíveis com a escolha que pretende orientar. - Rastrear achados até notas ou gravações consentidas e recomendações até achados, anonimizar dados conforme política do projeto. - Incluir públicos, dispositivos, contextos e tecnologias assistivas relevantes ao impacto da tarefa, registrando lacunas de recrutamento. - Revalidar mudanças estruturais com as mesmas tarefas críticas e comparar sucesso independente, erro e compreensão. - Não declarar uma experiência “intuitiva” ou validada sem comprovação observada e limites explícitos da amostra. ## Skills relacionadas - `$specsfy-specialist-reui` para a composição React depois de validar jornada e tarefas. - `$specsfy-specialist-interface-experience` para organizar telas, ações e estados da interface durante a descoberta. - `$specsfy-specialist-ui-design` materializa hierarquia visual e estados depois que tarefa e fluxo estão definidos. - `$specsfy-specialist-design-system` define defaults, exceções por alcance e cenários CRUD antes da arquitetura de informação. - `$specsfy-specialist-prototyping` cria o artefato mínimo para testar uma hipótese de interação. - `$specsfy-specialist-web-accessibility` avalia conformidade e uso com tecnologias assistivas além do recorte de pesquisa. - `$specsfy-specialist-domain-modeling` alinha vocabulário e invariantes quando a experiência atravessa regras complexas do domínio. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-ux-design/references/standards.md) para escolher método, estruturar pesquisa, avaliar formulários, conteúdo, onboarding e serviços. ### Especialista Versionamento no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/versioning - Descrição: Consulte o guia da especialista Versionamento no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar pela `$specsfy-specialist-deploy` ao preparar release, imagem destinada a deploy, tag Git ou promoção entre ambientes. - Em pedido completo de release ou deploy, devolver a coordenação para `$specsfy-specialist-deploy` depois de preparar e conferir a versão. - Não publicar imagem, tag, GitHub Release nem executar deploy sem autorização explícita. A preparação local pode criar ou atualizar `SEMVER`. ## Fluxo 1. Localizar a raiz do projeto e ler `SEMVER`, tags Git, changelog e artefatos relacionados à entrega. 2. Criar `SEMVER` somente quando ele estiver ausente e a versão inicial tiver sido confirmada. 3. Classificar a alteração como `patch`, `minor` ou `major`, explicar o efeito e propor a próxima versão antes de escrever. 4. Atualizar `SEMVER` durante a preparação autorizada e propagar o mesmo valor para metadados, imagem e manifestos que pertencem à entrega. 5. Executar testes e conferir que a versão é superior à publicação anterior. 6. Quando houver autorização para publicar, enviar primeiro o artefato imutável. Criar a tag Git e a GitHub Release somente depois que o artefato estiver disponível. 7. Entregar a versão, o digest, o commit, os ambientes alcançados e os comandos de reversão. ## Padrões - Manter `SEMVER` na raiz com uma única versão estável `MAJOR.MINOR.PATCH` e quebra de linha final. - Usar `patch` para correção compatível, `minor` para capacidade compatível e `major` para mudança incompatível. - Tratar `SEMVER` como fonte da versão preparada. Tags Git, anotações OCI, changelog e referência da stack devem reproduzir o mesmo valor. - Publicar imagens com tag SemVer e commit, registrar o digest e fazer o deploy por digest quando a plataforma permitir. - Conferir se uma tag imutável já existe antes do push. Nunca substituir uma imagem ou tag publicada. - Usar o utilitário local para operações determinísticas: ```bash node scripts/semver.mjs current --project . node scripts/semver.mjs bump patch --project . node scripts/semver.mjs verify 1.4.1 --project . node scripts/semver.mjs docker-tag registry.example/app --project . node scripts/semver.mjs verify-docker-tag registry.example/app:1.4.1 --project . ``` Ao instalar a skill, ajuste o primeiro caminho para apontar para `specsfy-specialist-versioning/scripts/semver.mjs` dentro da biblioteca de skills do agente. ## Antipadrões - Usar `latest` como identidade de uma entrega. - Alterar `SEMVER` depois que a imagem já foi compilada com outro valor. - Criar a tag Git antes de confirmar a presença da imagem no registry. - Recompilar o mesmo número para corrigir uma publicação. Prepare um novo incremento. - Misturar a preparação local com autorização implícita para publicar ou alterar um ambiente remoto. ## Validação - Executar `current` e `verify` para confirmar o conteúdo de `SEMVER`. - Gerar a tag Docker com `docker-tag` e executar `verify-docker-tag` antes do build, push ou deploy, uma tag diferente do `SEMVER` interrompe o fluxo. - Comparar a versão com a tag Git anterior e recusar valor igual ou inferior. - Comparar `SEMVER`, tag da imagem, anotações OCI, changelog e manifesto de deploy. - Confirmar o digest publicado antes de criar a tag Git. - Conferir que o rollback aponta para uma versão e um digest já disponíveis. ## Skills relacionadas - `$specsfy-specialist-deploy` é a única responsável por coordenar o fluxo completo de release ou deploy. - `$specsfy-specialist-docker` constrói e publica a imagem identificada pela versão preparada aqui. - `$specsfy-specialist-docker-swarm` aplica no cluster a imagem e o digest conferidos por esta skill. - `$specsfy-specialist-ansible` transporta os manifestos versionados e executa o preflight nos hosts. - `$specsfy-specialist-delivery-engineering` coordena testes, promoção, tag e GitHub Release. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-versioning/references/standards.md) para a correspondência entre SemVer, Git, imagens OCI e a sequência de publicação. ### Especialista Acessibilidade Web no Specsfy: guia técnico - URL: https://promovaweb.com/docs/specsfy/especialistas/web-accessibility - Descrição: Consulte o guia da especialista Acessibilidade Web no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto. ## Quando usar - Acionar ao implementar ou auditar páginas, componentes, formulários, dashboards, mídia e fluxos críticos contra WCAG e semântica da plataforma. - Acionar para bugs de teclado, foco, nome acessível, contraste, zoom, reflow, leitor de tela ou outras tecnologias assistivas. - Não acionar apenas para preferência visual sem barreira observável, usar `$specsfy-specialist-ui-design`. - Combinar com a skill do framework para corrigir o código sem transferir a responsabilidade de conformidade ao framework. ## Fluxo 1. Descobrir política, nível WCAG, navegadores, tecnologias assistivas, público e fluxos críticos, separar auditoria de conformidade de teste de usabilidade. 2. Inventariar barreiras por estrutura, percepção, teclado, foco, formulário, atualização dinâmica, mídia e autenticação usando [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-web-accessibility/references/standards.md). 3. Corrigir HTML e comportamento nativos antes de adicionar ARIA ou widget customizado, verificar nome, papel, valor, estado e relações calculados. 4. Implementar teclado, ordem lógica, foco visível, foco não encoberto e gestão após abertura, fechamento, navegação e atualização assíncrona. 5. Validar contraste, zoom, reflow, espaçamento de texto, target size, forced colors, orientação, movimento e alternativas de mídia. 6. Executar análise automática e inspeção manual, classificar cada achado por critério, impacto, caminho de reprodução e correção verificável. 7. Exercitar tarefas críticas com tecnologia assistiva representativa e documentar cobertura, limitações, exceções e risco residual. ## Padrões - Nenhuma ação depende apenas de hover, cor, gesto ou pointer preciso. - Todo controle tem nome, papel, valor e estado corretos. - Modal prende foco, fecha por mecanismo previsível e devolve foco. - Erros são associados aos campos e resumidos quando necessário. - Updates assíncronos anunciam somente informação relevante. - Charts oferecem texto/tabela equivalente e não dependem de cor. - ARIA nunca corrige semântica nativa incorreta. ## Antipadrões - Declarar conformidade porque axe ou um linter zerou, automação não confirma ordem de foco, linguagem, alternativas equivalentes ou fluxo completo. - Aplicar `role`, `tabindex` e handlers a `div` quando um elemento nativo cobre o contrato, recria parcialmente teclado e semântica do browser. - Usar `aria-label` para substituir texto visível sem necessidade, nomes divergentes quebram reconhecimento por voz e manutenção. - Mover foco em toda atualização assíncrona, interrompe leitura e contexto. Anuncie status proporcional e mova foco somente quando a tarefa exigir. - Ocultar overflow para “resolver” reflow, o conteúdo continua inacessível, apenas deixa de ser alcançável visualmente. ## Validação - Executar fluxo completo por teclado, sem armadilha, perda ou foco encoberto, conferir ordem e retorno de foco em overlays. - Verificar resize de texto a 200% e reflow equivalente a 320 CSS px para conteúdo vertical, além de spacing de texto e orientação suportada. - Medir contraste de texto, componentes e indicadores de foco e testar forced colors e reduced motion quando aplicáveis. - Combinar axe/linter com inspeção do accessibility tree e leitor de tela nos fluxos de maior risco. - Não declarar conformidade WCAG sem mapear critérios, escopo, evidência, limitações e exceções, “acessível” não é sinônimo de teste automatizado verde. ## Skills relacionadas - `$specsfy-specialist-react-ui-components` e `$specsfy-specialist-shadcn-ui` fornecem componentes que esta skill audita por semântica, foco, teclado e nome acessível. - `$specsfy-specialist-tailwind-css` implementa contraste, forced colors, reflow e reduced motion nos utilitários e tokens observados. - `$specsfy-specialist-ui-design` governa hierarquia, tokens e estados visuais que precisam satisfazer contraste, reflow e foco. - `$specsfy-specialist-ux-design` pesquisa compreensão e sucesso de tarefa, inclusive com pessoas que usam tecnologias assistivas. - `$specsfy-specialist-react` e `$specsfy-specialist-astro` ou `$specsfy-specialist-nextjs` implementam a correção no framework observado. - `$specsfy-specialist-code-review` amplia a revisão para riscos além do recorte de acessibilidade. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-web-accessibility/references/standards.md) para critérios WCAG 2.2, contratos de componentes, formulários, conteúdo dinâmico e matriz de testes. ### Especialista APIs Web no Specsfy: documentação técnica - URL: https://promovaweb.com/docs/specsfy/especialistas/web-api-design - Descrição: Consulte o guia da especialista APIs Web no Specsfy, com quando usar, fluxo, padrões, antipadrões e validação técnica para o seu projeto na aplicação. ## Quando usar - Acionar ao projetar ou revisar contratos HTTP, REST, JSON, webhooks ou descrições OpenAPI para consumidores internos ou externos. - Acionar para decisões de recursos, métodos, status, erros, paginação, idempotência, concorrência, autenticação e compatibilidade. - Não acionar para RPC ou eventos como se fossem recursos HTTP sem primeiro confirmar o estilo do contrato real. - Combinar com `$specsfy-specialist-application-security` para threat modeling, credenciais, abuso e trust boundaries. ## Fluxo 1. Descobrir consumidores, casos de uso, estilo existente, volume, latência, disponibilidade, trust boundaries e política de compatibilidade. 2. Modelar recursos, identidade, relações, invariantes e ownership sem expor tabelas ou objetos internos como contrato por conveniência. 3. Definir operações, schemas, headers, status e Problem Details, registrar a semântica de retry por operação usando [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-web-api-design/references/standards.md). 4. Projetar autenticação, autorização por recurso/tenant, idempotência, precondições e concorrência antes de implementar handlers. 5. Especificar paginação, filtros, ordenação determinística, limites, rate limiting e comportamento diante de dados mutáveis. 6. Materializar OpenAPI/JSON Schema e contract tests positivos, negativos e de compatibilidade executados contra a implementação. 7. Definir logs, métricas, correlação, depreciação, migração e critérios para remover comportamento antigo sem quebrar consumidores conhecidos. ## Padrões - Usar semântica HTTP coerente e status específicos. - Manter formato de erro estável, acionável e sem vazamento. - Usar cursor quando dados mudam durante paginação extensa. - Tornar criação/retry seguros com chave de idempotência quando necessário. - Proteger webhooks com assinatura, timestamp, replay defense e reentrega. - Evitar breaking changes silenciosas e campos com semântica ambígua. - Não expor modelo de persistência como contrato por conveniência. ## Antipadrões - Responder `200` para todo resultado e codificar falha apenas no body, caches, clientes e observabilidade perdem a semântica do protocolo. - Repetir POST após timeout sem idempotência ou reconciliação, uma resposta perdida pode duplicar cobrança, pedido ou efeito externo. - Paginar por offset em coleção grande e mutável sem ordenação estável, itens são duplicados ou omitidos entre páginas. - Autorizar somente no endpoint/lista e não no recurso carregado, IDs válidos atravessam tenants ou escopos. - Versionar a URL para toda mudança aditiva, multiplica contratos ativos sem resolver disciplina de compatibilidade. ## Validação - Executar contract tests de request, response, headers e Problem Details contra exemplos válidos e inválidos da descrição. - Provar autorização por recurso e tenant com identidade correta, identidade cruzada, credencial expirada e escopo insuficiente. - Simular retry, duplicação, timeout após commit, corrida de atualização e paginação enquanto itens entram e saem. - Fazer lint e validação estrutural de OpenAPI/JSON Schema e comparar breaking changes contra a última versão publicada. - Não declarar compatibilidade ou idempotência sem evidência de replay e teste automatizado do contrato observado pelo consumidor. ## Skills relacionadas - `$specsfy-specialist-astro` implementa endpoints no framework, esta skill mantém o contrato HTTP consumível fora do próprio site. - `$specsfy-specialist-application-security` cobre threat modeling, OAuth, proteção de segredo, abuso e trust boundaries. - `$specsfy-specialist-domain-modeling` define vocabulário e invariantes antes de expô-los como recursos. - `$specsfy-specialist-typescript` modela tipos internos sem torná-los automaticamente a fonte pública do contrato. - `$specsfy-specialist-observability` define telemetria e SLOs além dos campos de correlação do contrato. - `$specsfy-specialist-performance-engineering` mede throughput e latência sem alterar semântica para ganhar benchmark. Leia [references/standards.md](https://github.com/promovaweb/specsfy/blob/main/specialists/specsfy-specialist-web-api-design/references/standards.md) para matrizes de método, erros, idempotência, concorrência, paginação, webhooks e evolução compatível. ### Inbox do Specsfy para capturar entradas antes do backlog - URL: https://promovaweb.com/docs/specsfy/inbox - Descrição: Como o Specsfy preserva uma entrada em specs/inbox/ antes do refinamento, sem fazer perguntas nem transformá-la em compromisso de entrega no projeto. `specs/inbox/` recebe entradas antes de qualquer refinamento ou definição de produto. A captura é deliberadamente rápida. O agente guarda o texto sem fazer perguntas e sem transformá-lo em compromisso de entrega. ## Capturar ```text Use $specsfy-01-inbox para guardar esta entrada: quero permitir que a pessoa continue um formulário em outro dispositivo. ``` O agente grava a captura em `specs/inbox/` com data, hora e um nome derivado do conteúdo: ```text specs/inbox/AAAA-MM-DD-HHMMSS-.md ``` Data e hora evitam uma fila numerada artificial e preservam a ordem real de chegada. Se duas capturas tiverem o mesmo nome no mesmo segundo, o Specsfy adiciona um sufixo sem sobrescrever a anterior. ## O que o arquivo organiza - metadados e integridade do texto original. - texto original completo. - resumo processado. - problema ou oportunidade. - pessoas e valor percebidos. - sinais de escopo, regras ou solução. - dependências, falhas possíveis e direções futuras. - pontos a revisar no futuro. - rastreabilidade para backlog ou spec derivados. Declarações, inferências e lacunas permanecem identificadas. Um campo sem base no texto aparece como não identificado, em vez de receber uma resposta inventada. Quando o texto indicar que o sistema precisa guardar, consultar, compartilhar ou apagar informações, a Inbox registra o sinal sem perguntar. No backlog, `$specsfy-data-discovery` conversa sobre essas informações antes de o item ser considerado pronto. O texto será versionado no Git. Não inclua senhas, tokens, chaves privadas ou dados pessoais sensíveis. Se o agente detectar um segredo evidente, ele não grava a captura e orienta você a remover o conteúdo sensível antes de reenviar. ## Inbox, backlog e spec ```text captura sem perguntas → backlog refinável → spec normativa ``` - `specs/inbox/` preserva o input. - `specs/backlog/` organiza algo escolhido para refinamento. - `specs//-/spec.md` governa comportamento e entrega. Uma captura pode permanecer indefinidamente na Inbox. Quando quiser avançar, use `$specsfy-02-backlog` com o caminho do arquivo. ## Sessões de descoberta do MVP `$specsfy-mvp-milestone-interviewer` pode usar Inboxes para capturar respostas novas durante a conversa. Isso não se aplica à importação de `MVP.md`: nela a skill cria `M01` e seleciona somente requisitos de desenvolvimento para gerar backlog e spec Draft diretamente. Os temas de negócio e produto permanecem no `MVP.md`, sem Inbox. O backlog reaproveita as respostas declaradas no trecho técnico e pergunta somente o que permanece ausente, ambíguo ou contraditório antes de uma promoção. `BRAND.md`, quando existir, orienta as perguntas, mas não é copiado para as capturas. Se o projeto estiver em um submódulo Git, a skill procura os dois arquivos na raiz do Hub somente quando eles não existirem no projeto. ## Templates instalados O CLI mantém em `.specsfy/templates/` os modelos usados para criar entradas, backlogs, specs e informações permanentes do projeto: ```text Inbox.md Backlog.md Spec.md Tasks.md Project.md Stack.md Rules.md Database.md ``` Para personalizar um modelo, copie somente o arquivo desejado para `.specsfy/templates/custom/` e preserve o mesmo nome. A versão em `custom/` tem precedência sobre a cópia padrão. O instalador protege alterações locais nos templates gerenciados, mas `--force` pode substituí-los. O conteúdo de `custom/` nunca é gerenciado nem sobrescrito. ### Instalação do Specsfy: CLI, skills e atualização segura - URL: https://promovaweb.com/docs/specsfy/instalacao - Descrição: Como baixar o CLI do Specsfy, instalar as skills em um projeto consumidor, conferir o resultado e atualizar sem perder customizações locais feitas. ## Classificação | Campo | Valor | | --- | --- | | Natureza | normativo | | Escopo | instalação do CLI e do framework em um projeto consumidor | | Autoridade | interfaces públicas de `cli/` e `skills/` | ## Instale o CLI O Specsfy requer Node.js 22.20 ou uma versão mais recente. O pacote oficial publicado no npm instala o comando no ambiente global do usuário: ```bash npm install --global @promovaweb/specsfy ``` Execute `specsfy --version` para confirmar que o terminal localiza o comando e que o Node.js consegue abrir o aplicativo: ```bash specsfy --version ``` Uma resposta com o número da versão confirma a instalação. Se o terminal mostrar `specsfy: command not found`, consulte o diretório global do npm e confirme se o diretório de executáveis está no `PATH`: ```bash npm prefix --global specsfy --version ``` O download em `get.specsfy.dev` continua disponível para instalações mantidas em `$HOME/.local/bin`. Esse executável inclui as dependências do CLI, mas também requer Node.js 22.20 ou superior: ```bash mkdir -p "$HOME/.local/bin" curl -fL get.specsfy.dev -o "$HOME/.local/bin/specsfy" chmod +x "$HOME/.local/bin/specsfy" ``` ## Prepare o projeto consumidor Abra a raiz do repositório que receberá a metodologia. Não execute a instalação dentro do monorepo oficial do Specsfy, porque o CLI reconhece essa raiz como ambiente de desenvolvimento e recusa a operação: ```bash cd caminho/do/projeto specsfy doctor --project . specsfy install --project . ``` O diagnóstico confere Node.js 22.20 ou superior, Git, npm, o diretório do projeto e o `npx`. Toda materialização usa `npx skills add`, inclusive quando o CLI foi instalado pelo npm. `install` repete as verificações necessárias antes de escrever qualquer arquivo e reúne todas as correções na mesma mensagem. Quando o projeto estiver em um Hub, use o subdiretório escolhido pela pessoa em `--project`, como `specsfy install --project apps/portal`. O setup confirma o mesmo caminho e mantém nele os contextos, as specs e o trabalho de código. O instalador publica as etapas numeradas a partir de `.agents/skills/specsfy-01-inbox`, grava o contrato central em `.specsfy/Spec.md` e adiciona templates, exemplos e registros técnicos em `.specsfy/`, inclusive `.specsfy/templates/DESIGNSYSTEM.MD` para as regras macro de interface. Ele também insere blocos gerenciados em `AGENTS.md` e `CLAUDE.md`, preservando o conteúdo que já existe fora desses blocos. Ao executar `$specsfy-setup`, o template também gera `DESIGNSYSTEM.MD` na raiz do projeto quando o arquivo ainda não existe. O setup preserva um arquivo local existente e deixa a aplicação pronta para registrar seus padrões de CRUD, dashboard e interface. O mesmo setup gera `.specsfy/USER-PROFILE.md` quando esse arquivo ainda não existe. Na conversa, ele identifica o nível de conhecimento, consulta respostas já registradas e adapta a explicação das próximas perguntas. O arquivo local e as respostas confirmadas são preservados entre execuções. Para personalizar um template sem impedir atualizações, copie-o para `.specsfy/templates/custom/` com o mesmo nome. Essa versão tem precedência e nunca é sobrescrita pelo instalador, inclusive com `--force`. A instalação inclui as quatorze skills base, entre elas as quatro de conversa e milestones, além do setup, do documentador do sistema e das três skills auxiliares. Ela prepara os arquivos usados pelo agente, mas não cria uma spec de produto nem altera o código da aplicação. ## Confira os arquivos instalados Na mesma raiz, liste o catálogo e consulte o progresso. O primeiro comando deve mostrar as skills instaladas, e o segundo deve conseguir ler o diretório de specs: ```bash specsfy skills list specsfy progress --project . ``` O catálogo deve mostrar as skills do Specsfy. Em um projeto novo, o comando de progresso pode retornar zero specs. Esse resultado confirma que o CLI leu o repositório e ainda não encontrou arquivos em `specs//-/spec.md`. O comando sem subcomando abre a interface visual no diretório atual. O nome do projeto aparece no topo e as abas devem carregar mesmo quando ainda não houver spec: ```bash specsfy ``` O dashboard deve carregar as abas do projeto mesmo quando as tabelas ainda estiverem vazias. Use `Ctrl+Q` para sair. ## Atualize sem perder customizações Para atualizar o próprio CLI instalado pelo npm: ```bash specsfy upgrade specsfy --version ``` Na instalação pelo arquivo de `get.specsfy.dev`, repita o download e a permissão de execução quando o npm não gerenciar o executável. Para atualizar as skills já instaladas, execute `specsfy update`. O CLI compara os fingerprints e preserva os arquivos customizados: ```bash specsfy update --project . ``` `specsfy skills update --project .` continua aceito para automações anteriores. O Specsfy registra fingerprints dos arquivos gerenciados. Uma atualização normal substitui versões intactas e preserva arquivos customizados. Se o CLI informar que encontrou alterações locais, revise a diferença. `--force` descarta a customização protegida no arquivo indicado. ## Corrija falhas comuns - **Comando ausente:** confira o resultado de `npm prefix --global` e o `PATH` usado pelo terminal. - **Node.js incompatível:** execute `node --version`. O aplicativo requer Node.js 22.20 ou uma versão mais recente. - **Permissão negada:** execute novamente `chmod +x "$HOME/.local/bin/specsfy"` quando usar o download. Em instalações pelo npm, configure um diretório global gravável pelo seu usuário. - **Mensagem `npx não encontrado`:** instale ou repare o npm e disponibilize `npx` no `PATH`. - **Arquivo gerenciado customizado:** preserve sua versão ou compare as mudanças oficiais e só então repita o comando com `--force`. Com o ambiente conferido, siga o [primeiro projeto](/docs/specsfy/comecando) para criar uma entrega pequena e observar a primeira `spec.md`. O [guia do CLI e da TUI](/docs/specsfy/cli) detalha os comandos de atualização, progresso, testes e configuração. ### Guia completo do usuário do Specsfy: visão geral e leitura - URL: https://promovaweb.com/docs/specsfy/introducao - Descrição: Visão geral do Specsfy — como a metodologia organiza ideia, definição, plano, testes e implementação em uma única especificação rastreável e única. O Specsfy ajuda você a transformar uma ideia em software testado sem espalhar requisitos, planos e tarefas por vários arquivos. Você conversa normalmente com o agente, e as skills organizam o trabalho em uma única especificação. Nesse arquivo, você consegue conferir o que será entregue, quais testes comprovam o comportamento e o que já foi concluído. Este guia começa pela lógica da metodologia, prepara o ambiente e acompanha uma entrega completa. Os capítulos seguintes explicam a rotina com o CLI, as mudanças posteriores e os recursos avançados. Você não precisa conhecer a implementação do framework para seguir esse percurso. ## Leia online ou como ebook Este mesmo percurso compõe a edição portátil **v1.8.0**. Use o PDF para leitura e impressão ou o EPUB em leitores que permitem ajustar fonte e tamanho: - [PDF](https://github.com/promovaweb/specsfy/blob/main/ebook/Specsfy-Guia-do-Usuario-v1.8.0.pdf), para leitura, compartilhamento e impressão. - [EPUB](https://github.com/promovaweb/specsfy/blob/main/ebook/Specsfy-Guia-do-Usuario-v1.8.0.epub), para leitores digitais com fonte e tamanho ajustáveis. Os dois formatos são reconstruídos a partir destas páginas. O [manifesto da edição](/docs/specsfy/downloads/build.json) informa a versão vigente e os hashes usados para conferir se o PDF e o EPUB correspondem ao mesmo build. ## Percurso pedagógico Siga a ordem abaixo na primeira leitura. Quando já conhecer o método, use os links para voltar diretamente à tarefa que precisa executar. ### 1. Entenda a metodologia Comece pela [Metodologia](/docs/specsfy/metodo). Cada entrega mantém o problema, os requisitos, os exemplos de comportamento, o plano técnico, as tarefas, os testes e as evidências em uma única `spec.md`. O capítulo mostra como esse arquivo muda ao longo do trabalho e o que comprova a passagem entre os atos. Os três atos ligam cada fase a uma evidência verificável na `spec.md`: 1. **Ato I — Definir:** entender e validar o que deve ser entregue. 2. **Ato II — Projetar e provar:** preparar tarefas e obter o RED, a falha esperada antes da implementação. 3. **Ato III — Entregar e validar:** implementar, obter testes verdes e registrar evidências. Para interpretar cada campo da spec, consulte a [Referência do método](/docs/specsfy/referencia-do-metodo). Ela detalha Effort, estados, transições, gates, IDs, pesquisa, tarefas e progresso. ### 2. Instale o Specsfy Com o método entendido, siga a [Instalação](/docs/specsfy/instalacao) para instalar o CLI e preparar seu repositório. Ao final, `specsfy skills list` mostra as skills disponíveis e `specsfy progress --project .` confirma que o CLI consegue ler o projeto, mesmo que ainda não exista uma spec. ### 3. Faça a primeira entrega Use [Primeiro projeto](/docs/specsfy/comecando) como tutorial guiado. Você começa com uma mudança pequena, acompanha a criação da `spec.md` e termina conferindo os testes e as evidências registradas, sem precisar decorar cada skill. Para preservar uma ideia sem iniciar a especificação, escolha uma destas entradas: - preserve um texto sem perguntas na [Inbox](/docs/specsfy/inbox). - refine e priorize uma proposta no [Backlog](/docs/specsfy/backlog). - organize o MVP e o roadmap com [Milestones](/docs/specsfy/milestones). ### 4. Aprofunde o fluxo base O índice de [Skills base](/docs/specsfy/skills/introducao) apresenta o fluxo completo. Leia cada etapa nesta ordem: 1. [Capturar uma entrada](/docs/specsfy/skills/inbox). 2. [Refinar no backlog](/docs/specsfy/skills/backlog). 3. [Criar a especificação](/docs/specsfy/skills/specify). 4. [Validar a definição](/docs/specsfy/skills/validate). 5. [Preparar as tarefas](/docs/specsfy/skills/tasks). 6. [Preparar TDD e BDD](/docs/specsfy/skills/tdd-bdd). 7. [Implementar](/docs/specsfy/skills/implement). 8. [Atualizar a especificação](/docs/specsfy/skills/update-spec). 9. [Consultar o progresso](/docs/specsfy/skills/progress). 10. [Conversar com a spec](/docs/specsfy/skills/interviewer). 11. [Entrevistar o MVP](/docs/specsfy/skills/mvp-milestone-interviewer). 12. [Descobrir informações a guardar](/docs/specsfy/skills/data-discovery). 13. [Planejar o roadmap](/docs/specsfy/skills/roadmap-milestone-interviewer). 14. [Governar milestones](/docs/specsfy/skills/milestone-governor). Essas páginas explicam quando usar cada skill, como descrever a tarefa em linguagem natural, o resultado esperado, os erros comuns e o próximo passo. Quando uma delas precisar perguntar, você recebe uma pergunta numerada por rodada. Ela traz três ou mais opções numeradas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde o início da conversa. Cada área aceita no máximo oito perguntas, salvo se você pedir mais e informar quantas deseja responder. Depois de avançar, você informa se quer encerrar definitivamente as perguntas daquela área, responder depois ou retomar agora. O encerramento é respeitado até você reabrir a área, o adiamento preserva os pontos para retomada. No setup, o perfil persistente em `.specsfy/USER-PROFILE.md` registra o nível de conhecimento e as respostas já confirmadas. O agente consulta esse arquivo, a conversa e as fontes do projeto antes de perguntar novamente. ### 5. Opere o projeto no dia a dia Depois da primeira entrega, escolha os guias ligados à sua rotina: - [CLI e TUI](/docs/specsfy/cli): interface visual e acompanhamento. - [Referência dos comandos](/docs/specsfy/referencia-cli): parâmetros, efeitos, saídas e exemplos do CLI. - [Informações permanentes do projeto](/docs/specsfy/contexto-do-projeto): stack, regras, banco e convenções. - [Design system de interface](/docs/specsfy/design-system): regras macro, padrões CRUD, estados e exceções com alcance. - [Documentação do sistema](/docs/specsfy/documentacao-do-sistema): documentação técnica derivada da aplicação. - [Mudanças posteriores](/docs/specsfy/atualizar-spec): como incorporar um novo requisito à mesma especificação. ### 6. Avance quando precisar Os próximos guias são opcionais. Consulte-os quando a entrega exigir uma integração ou tecnologia específica: - [Especialistas](/docs/specsfy/especialistas), para conhecimento técnico adicional. - [Como funciona o Deploy da aplicação](/docs/specsfy/deploy), para ligar `SEMVER`, imagem, Ansible e Docker Swarm em um deploy verificável. - [Servidores e comandos de deploy](/docs/specsfy/operacao-deploy), para cadastrar servidores, conferir conexões, sincronizar chaves públicas e usar os comandos curtos no Herdr. - [Senha do Vault e deploy pela IA](/docs/specsfy/senha-vault), para configurar a senha fora do Git e alternar entre execução manual e automatizada. - [Uso avançado](/docs/specsfy/uso-avancado), para automação e integrações. - aplicação em projetos [Laravel](/docs/specsfy/laravel), [Astro](/docs/specsfy/astro) ou [Next.js](/docs/specsfy/nextjs). - [Quadro técnico](https://github.com/promovaweb/specsfy/blob/main/docs/develop/modules.md), para conhecer os módulos do monorepo. - [Créditos](/docs/specsfy/creditos), para autoria e identidade do projeto. Se você pretende contribuir ou modificar o próprio framework, continue no [guia técnico](https://github.com/promovaweb/specsfy/blob/main/docs/develop/README.md). Ele é um percurso separado do uso em projetos consumidores. ## Conversa contínua entre etapas Quando uma etapa depende de outra skill, o agente anuncia a transição, explica o que falta e retoma o trabalho na mesma conversa. Você acompanha a mudança de etapa sem repetir a instrução inicial nem escolher manualmente cada skill. ## A ideia central em um exemplo Imagine uma página de boas-vindas. Você pode preservar a ideia, refiná-la no backlog e promovê-la até chegar a: ```text specs//0001-pagina-boas-vindas/spec.md ``` Em seguida, o agente valida a definição, organiza tarefas, prepara testes, implementa e registra evidências nesse mesmo arquivo. Se depois você solicitar um botão novo, a alteração retorna à mesma `spec.md`. O agente reabre somente os atos cujas provas perderam validade, sem criar `plan.md`, `tasks.md` ou outra fonte normativa. Para começar esse percurso com orientação passo a passo, siga agora [a Metodologia](/docs/specsfy/metodo). ### Usar o Specsfy com Laravel: guia técnico do especialista - URL: https://promovaweb.com/docs/specsfy/laravel - Descrição: Como o especialista specsfy-specialist-laravel soma verificações próprias do Laravel ao fluxo do Specsfy, da detecção à execução dos testes reais. `$specsfy-specialist-laravel` acrescenta verificações próprias do Laravel ao fluxo do Specsfy. A spec continua governando a mudança, e o especialista segue as convenções e a versão comprovadas pelo projeto. ## Confirmar a detecção O catálogo detecta Laravel por `artisan`, `composer.json` ou pela dependência `laravel/framework`. Confirme a versão e as extensões em `composer.json` e `composer.lock`. Uma API só deve orientar a implementação quando existir na versão usada pela aplicação. ## Instalação Na raiz do projeto, `--detected` instala o framework e o especialista quando o catálogo reconhece Laravel: ```bash specsfy install --project . --detected ``` Para revisar a recomendação sem instalar arquivos, use `skills detect`. A saída deve incluir `specsfy-specialist-laravel` quando `artisan` ou a dependência do framework for encontrada: ```bash specsfy skills detect --project . ``` Quando o nome já estiver confirmado, `npx skills add` instala somente o especialista Laravel e registra os arquivos gerenciados: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-laravel --agent universal --copy --full-depth ``` Para adotar um pacote Laravel a partir de um repositório GitHub, instale também o gestor de pacotes: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-laravel-package-manager --agent universal --copy --full-depth ``` Depois, peça ao agente: ```text Use $specsfy-specialist-laravel-package-manager com https://github.com/organizacao/pacote. Leia a documentação, confira se o pacote já está instalado e, com autorização, instale-o e documente seu uso. ``` O especialista lê `composer.json`, `composer.lock`, `.specsfy/PACKAGES.md` e as fichas atuais antes de executar Composer. Para cada dependência direta, ele mantém uma ficha em `docs/packages/-.md` e atualiza `docs/packages/README.md` com versão, finalidade e links. Pacotes já instalados são reaproveitados, dependências transitivas continuam relacionadas em `.specsfy/PACKAGES.md`. ## Aplicar na spec 1. Capture ou promova a ideia pelo [primeiro projeto](/docs/specsfy/comecando). 2. Peça ao agente para usar `$specsfy-specialist-laravel` na fatia ativa. 3. Confirme a versão, extensões, convenções locais e o caminho da requisição. 4. Na definição e no plano, registre autorização e validação. Quando a mudança alcançar persistência ou execução assíncrona, inclua transações, idempotência, filas, falhas e uma tarefa `[CODE] [MIGRATION]` separada. Essa tarefa aponta para o arquivo em `database/migrations/` e inclui os comandos de aplicação e consulta do estado. 5. Derive testes para caminho feliz, autorização, validação, efeitos e falhas. 6. Antes de qualquer teste, crie `.env.testing` com `APP_ENV=testing` e um `DB_DATABASE` ou `DB_URL` explícito, diferente do destino usado pelo `.env`. 7. Implemente controllers finos e mantenha as regras na camada já adotada pelo projeto. Inspecione as consultas e o N+1 quando a quantidade de relações puder aumentar o tempo da resposta. 8. Confira o ambiente e o comando antes de executar os checks: ```bash node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \ --project . --command "php artisan test" ``` Somente a saída `SAFE` permite continuar. `PENDING` encerra a etapa até a configuração ser corrigida. `IGNORED` descarta o comando, sem pedir autorização para forçá-lo. Quando houver uma migration planejada, aplique-a no banco de teste protegido e confirme o resultado antes de concluir a tarefa: ```bash php artisan migrate --env=testing php artisan migrate:status --env=testing ``` O registro da tarefa precisa conter o caminho exato da migration e a saída com exit code zero dos dois comandos. Criar um model, alterar uma consulta ou fazer os testes passarem não substitui essa conferência. 1. Em Laravel com Pest, o CLI oferece: ```bash specsfy test --project . ``` O CLI detecta `artisan` e `pestphp/pest`, chama `php artisan test` e preserva o exit code. Ele não recebe uma string arbitrária de shell. A verificação anterior continua obrigatória antes desse comando. ## O que o especialista acrescenta - contratos HTTP, Form Requests, policies, resources e bindings. - Eloquent, eager loading, casts e transações conscientes. - jobs idempotentes, tentativas, backoff e tratamento de falha. - migrations compatíveis com volume, locks, rollback e deploy misto. - verificação de queues, scheduler, cache, configuração e ambiente. - leitura, instalação autorizada e documentação de pacotes Composer recebidos por URL GitHub. ## Resultado esperado A spec continua sendo a fonte normativa, enquanto os testes e a implementação consideram as falhas possíveis do Laravel observado no projeto e na versão instalada. ## Limites - não aplique a skill a PHP sem Laravel. - não presuma APIs pela versão mais recente da documentação. - não execute migration, deploy ou comando operacional fora da autorização registrada na tarefa e do ambiente de teste protegido. - não execute teste sem `.env.testing` separado do banco de desenvolvimento. - não use `RefreshDatabase`, `DatabaseMigrations`, `migrate:fresh`, `migrate:refresh`, `migrate:reset`, `migrate:rollback` ou `db:wipe`, use `DatabaseTransactions`, factories e limpeza limitada aos registros criados pelo próprio caso. - não confie apenas na validação ou autorização da interface. Não use esse especialista para PHP sem Laravel nem para fixar uma versão que o projeto não comprova. O código, `composer.json`, `composer.lock`, os testes e a configuração local permanecem como evidência do estado da aplicação. ### Como funciona a metodologia do Specsfy na prática diária - URL: https://promovaweb.com/docs/specsfy/metodo - Descrição: Como o Specsfy organiza definição, plano, testes e implementação em uma única especificação, através dos três atos e seus gates de evidência real. O Specsfy ajuda você a transformar uma necessidade em uma entrega comprovada. Você explica o que precisa, e o agente organiza a definição, o plano, os testes e a implementação na mesma especificação. A metodologia existe para responder, durante todo o trabalho, a três perguntas: 1. **O que será entregue?** 2. **O que comprova que o plano está pronto?** 3. **Qual evidência comprova que a entrega funciona?** Você não precisa decorar comandos nem escolher cada skill. O agente identifica a etapa atual, anuncia as transições e mantém o trabalho na mesma conversa. Antes de iniciar uma descoberta, o setup lê o sistema que já existe. Ele reúne instruções do projeto, manifests, configuração, código, rotas, dados, integrações, interfaces, testes e documentação. Essa leitura evita sugestões desconectadas da aplicação e registra o que precisa continuar igual antes de propor uma mudança. ## Uma única especificação Cada mudança escolhida possui uma única fonte normativa. O caminho permite que você reconheça a sequência e o assunto ao listar o diretório de specs: ```text specs//-/spec.md ``` `NNNN` é o número da spec, como `0001`. O `slug` identifica o assunto, como `recuperar-senha`. Assim, o caminho `0001-recuperar-senha` pode ser localizado sem abrir o arquivo. A pasta também mostra o estado operacional da entrega: ```text draft → defined → planned → in-progress → review → completed ``` O campo `Status` dentro da spec espelha essa pasta. Use `specsfy transition` para mover o pacote inteiro, e não mova arquivos manualmente. `completed/` mantém o histórico das entregas finalizadas. Ao abrir a `spec.md`, você encontra o comportamento esperado, o plano e as provas que permitem conferir o estado atual: - o problema e o resultado esperado. - as pessoas afetadas e as regras que precisam ser respeitadas. - histórias, requisitos e limites. - exemplos de comportamento escritos em BDD. - as escolhas registradas, as possíveis falhas e o plano técnico. - tarefas, testes e evidências da execução. - gates e estado atual da entrega. O plano e as tarefas ficam dentro da própria spec. O Specsfy não cria `plan.md` ou `tasks.md`, então a explicação da entrega não se divide entre arquivos com estados diferentes. ## Effort e conversa contínua Cada spec inclui `Effort`, uma estimativa de 1 a 10 da capacidade de raciocínio e execução necessária. A pontuação não é prazo: 1–2 indica trabalho atômico, 3–6 mudança local, 7–8 integração ou migração e 9–10 uma entrega com alta incerteza ou revisão humana frequente. O entrevistador do Specsfy conversa com você quando uma lacuna puder mudar a próxima etapa. Ele atualiza a justificativa de Effort conforme a definição, o plano e a execução ganham forma. A Inbox continua sem perguntas. A [Referência do método](/docs/specsfy/referencia-do-metodo) detalha a escala de Effort, os perfis exibidos pelo progresso, os estados e os gates apresentados neste guia. ## Interfaces fazem parte da definição Quando a entrega cria ou muda uma tela usada por pessoas, o Specsfy pergunta antes do código como a experiência deve funcionar. A conversa cobre as telas, o fluxo de informação, os menus e a navegação principal, os campos e validações do formulário, a composição e o formato de cada ação, como página, painel lateral, modal ou outra alternativa. As opções usam texto completo, e você sempre pode escolher `Escrever outra resposta`, `Gere outras opções` ou `Avançar`. Antes das perguntas, o Specsfy analisa a stack e o sistema atual quando ele existe. Ele observa rotas, telas, componentes, conteúdo, permissões, estados e testes para preservar o que já funciona e sugerir uma continuação coerente. O agente não troca React, Tailwind, shadcn/ui ou outra tecnologia por suposição. Um CRUD com interface não é considerado pronto apenas por ter banco, serviço ou API. A spec registra telas, menus, formulário, navegação, estados de carregamento, vazio, erro e sucesso, além do uso por teclado. O plano gera tarefas e testes para essa interface antes da implementação. Essas tarefas aparecem em uma `Fase de interface` própria na seção 14 da spec. Cada tela tem uma tarefa com caminho, comportamento e teste de interação. ## Da ideia até o código Nem todo texto precisa virar uma entrega imediatamente. Você escolhe o destino de acordo com o quanto já definiu: - Uma **ideia** preserva seu texto em `specs/inbox/` sem perguntas e sem autorizar implementação. - O **backlog** guarda uma proposta que merece organização e refinamento, mas ainda não foi escolhida para entrega. Ela vive em `specs/backlog/`. - A **spec** representa uma entrega escolhida. A partir dela, definição, plano, testes, código e evidências passam a seguir o mesmo contrato. O percurso mais completo preserva a ideia, aprofunda as definições e só chega ao código depois do plano e do RED: ```text inbox → backlog → spec → plano e RED → código → validação ``` Você também pode começar com “implemente recuperação de senha”. O agente só altera o código depois de verificar as definições ausentes e conduzir as etapas correspondentes. ## Os três atos Os atos são grupos de trabalho. Cada um termina com um **gate**, que é um ponto de controle baseado em evidência. Um **gate** aprovado não significa apenas “parece bom”: significa que as condições daquela etapa foram verificadas. ### Escolha o destino da ideia **Objetivo:** preservar a ideia sem transformá-la imediatamente em spec. **Sua participação:** você informa a ideia e escolhe quando vale refiná-la ou promovê-la. Se solicitar apenas a captura, o agente não inicia o refinamento. **Prova técnica:** a captura recebe um arquivo próprio em `specs/inbox/`. Se você escolher o refinamento, ela segue para o backlog. A `spec.md` normativa só aparece depois de uma promoção explícita. Essa separação mantém a caixa de entrada leve e impede que toda observação se transforme em código ou em uma especificação extensa. ### Ato I — Definir o que precisa mudar **Objetivo:** entender o problema e transformar a intenção em comportamento que possa ser conferido. **Sua participação:** você responde apenas às dúvidas que realmente mudam a entrega. O agente reaproveita o que já foi informado e apresenta uma pergunta numerada por rodada. Ela inclui três ou mais opções, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. O ciclo faz no máximo oito perguntas por área: cada conjunto de respostas atualiza a análise. O avanço mantém uma confirmação para você encerrar a área, responder depois ou retomar agora. O encerramento é respeitado até uma reabertura explícita. O adiamento mantém os pontos registrados e o Definition Gate pendente até serem resolvidos. **Prova técnica:** a spec registra a finalidade, as pessoas afetadas, os requisitos, os limites e os cenários BDD. A validação procura contradições, definições em aberto e dúvidas que impedem o planejamento. O Ato I termina quando a validação registra este gate na `spec.md`: ```text Definition Gate: Passed ``` Esse estado permite que o agente organize o plano a partir dos requisitos e cenários já conferidos. O código ainda não foi alterado, e o Plan Gate continua pendente. ### Ato II — Planejar e preparar o RED **Objetivo:** definir como a mudança será construída e demonstrar que os testes conseguem detectar a ausência do novo comportamento. **Sua participação:** você confirma escolhas de produto ou estratégia que alteram o resultado. Os detalhes técnicos que o repositório consegue comprovar podem ser derivados do código, da stack e das regras do projeto. **Prova técnica:** o agente registra as tarefas, os contratos, as informações afetadas, as possíveis falhas e a reversibilidade na spec. Depois, transforma os cenários BDD em testes TDD executáveis e observa o **RED**, uma falha causada pela funcionalidade que ainda não existe. O Ato II termina quando as tarefas e os testes permitem registrar: ```text Plan Gate: Passed ``` O RED precisa falhar pelo motivo esperado. Erro de sintaxe, dependência ausente ou ambiente quebrado não prova que o teste protege o comportamento. ### Ato III — Entregar e conferir o resultado **Objetivo:** implementar cada tarefa e reunir evidências atuais de que o resultado atende à definição. **Sua participação:** você acompanha novas escolhas ou mudanças de escopo. O agente registra cada comando executado e apresenta o resultado verificável, sem exigir que você conduza os ciclos de teste. **Prova técnica:** cada tarefa de código parte de um teste que falha pelo motivo esperado, recebe a menor implementação capaz de deixá-lo verde e termina com refatoração protegida pela suíte: ```text RED → GREEN → REFACTOR ``` - **RED:** o teste falha pela razão esperada. - **GREEN:** a menor implementação faz o teste passar. - **REFACTOR:** o código é melhorado sem mudar o comportamento. Depois, o agente executa o aceite e a regressão completa, verifica a ligação entre cada requisito e seu teste, atualiza os registros permanentes do projeto e reconstrói a documentação aplicável. O Ato III termina quando o aceite, a regressão e a documentação permitem registrar: ```text Delivery Gate: Passed Status: Reviewing ``` Depois do aceite final, a spec passa por `review/` para `completed/`, com `Status: Complete`. A entrega concluída possui código e evidência atual. Você pode abrir a spec e localizar os comandos, os resultados e os testes que comprovam esse estado. ## Como BDD e TDD trabalham juntos O BDD (desenvolvimento orientado por comportamento) descreve o resultado que produto e desenvolvimento precisam discutir. O TDD (desenvolvimento orientado por testes) transforma esse comportamento em uma prova executável no projeto. O **BDD** descreve o comportamento em uma linguagem que produto, desenvolvimento e testes conseguem discutir. Por exemplo: ```gherkin Cenário: cliente solicita recuperação de senha Dado que existe um cadastro para o e-mail informado Quando o cliente solicita a recuperação Então o sistema confirma a solicitação sem revelar informações privadas ``` Esse cenário mostra a regra e o resultado esperado, mas o texto Gherkin não é executado como uma suíte separada pelo Specsfy. O **TDD** transforma o comportamento em testes executáveis na ferramenta já usada pelo projeto. Primeiro o teste falha pelo motivo correto. Depois, a implementação faz o teste passar. Em resumo: - BDD ajuda a definir **o comportamento que importa**. - TDD comprova **que o código apresenta esse comportamento**. Essa ligação evita uma descrição clara sem prova automática e também impede que um teste técnico seja aceito sem representar a necessidade registrada. ## O agente conduz as transições As skills dividem responsabilidades, mas você não precisa operar o fluxo como uma lista de comandos. Quando uma etapa depende de outra, o agente: 1. informa de qual skill está saindo e para qual está indo. 2. explica a pendência que motivou a transição. 3. resolve a pendência na skill responsável. 4. retorna à etapa anterior quando necessário. Por exemplo, se a implementação encontrar um teste ausente, o agente volta ao planejamento e à preparação TDD, obtém um RED válido e só então retoma o código. Ele não aprova um gate apenas para contornar a pendência. ## Mudanças durante o trabalho Se a necessidade mudar depois que a spec já existe, explique a alteração em linguagem normal. O novo requisito entra na mesma `spec.md`, sem criar uma segunda especificação. O Specsfy reabre somente as provas que perderam validade: - Uma mudança de comportamento reabre definição, plano e entrega. - Uma mudança apenas na estratégia técnica reabre plano e entrega. - Uma evidência desatualizada exige somente a repetição da validação correspondente. Use [`specsfy-update-spec`](/docs/specsfy/skills/update-spec) para incorporar a nova instrução. A skill informa quais gates perderam validade e retoma a primeira etapa afetada. ## Informações que permanecem entre entregas Além da spec de cada entrega, o projeto mantém informações que valem para o sistema inteiro: - `PROJECT.md`: finalidade, capacidades e limites do projeto. - `.specsfy/STACK.md`: tecnologias estruturais e suas evidências. - `.specsfy/RULES.md`: regras confirmadas para o trabalho. - `.specsfy/DATABASE.md`: visão da persistência e das relações. O agente consulta esses arquivos antes de planejar e os revisa durante a implementação. Assim, uma nova entrega começa com a arquitetura, as convenções e o banco já documentados. ## O que você encontra ao final Uma mudança completa deixa na `spec.md` um caminho auditável entre requisito, teste, tarefa e evidência: - a intenção e as escolhas estão na spec. - cada requisito aponta para condições de aceite. - os cenários BDD explicam o comportamento. - os testes TDD demonstram o resultado no código. - as tarefas registram execução e evidências. - os gates mostram quais etapas foram realmente comprovadas. - a documentação reflete o sistema implementado. Para consultar esse estado sem alterar arquivos, use [`specsfy-progress`](/docs/specsfy/skills/progress). ## Limites do método O método não define requisitos importantes sem você, não transforma toda ideia em spec e não trata pesquisa como requisito aprovado. Também não aceita erro de ambiente como RED nem substitui os testes e as ferramentas do seu projeto. ## Justificativa de tamanho Este guia mantém os três atos, os gates e a relação entre BDD e TDD na mesma página para que você possa comparar o percurso completo sem alternar entre explicações parciais. O [guia de instalação](/docs/specsfy/instalacao) prepara o CLI e o framework. Depois, o [primeiro projeto](/docs/specsfy/comecando) aplica os três atos a uma página de boas-vindas e mostra os gates na `spec.md`. ### Milestones no Specsfy: organize MVP, roadmap e progresso - URL: https://promovaweb.com/docs/specsfy/milestones - Descrição: Organize MVP e roadmap no Specsfy com milestones, vínculos entre specs e backlog, sincronização do progresso e critérios claros de conclusão no projeto. ## Classificação | Campo | Valor | | --- | --- | | Natureza | guia de uso | | Escopo | MVP, roadmap, specs e backlog de projetos consumidores | | Autoridade | uso público da capacidade de milestones | Uma milestone é um estado demonstrável do produto. Ela responde o que precisa estar funcionando antes de seguir para o próximo marco. Não é sprint, versão, épico, componente ou uma pasta de tarefas. ## Comece pelo MVP Use `$specsfy-mvp-milestone-interviewer` depois de apresentar a ideia do produto. A conversa começa com a finalidade, quem será atendido e qual jornada precisa funcionar. Depois de cada resposta, o agente resume o entendimento e faz a próxima pergunta que falta para definir o menor produto utilizável. A entrevista termina quando você puder confirmar uma frase como: “o MVP estará pronto quando uma equipe comercial conseguir capturar um lead, consultá-lo e atribuir uma responsável em ambiente publicado”. O agente propõe normalmente de quatro a oito milestones. Para cada uma, você aprova objetivo, condição de saída, fora de escopo, dependências e specs iniciais. Só depois disso ele cria ou reorganiza os arquivos. ## Arquivos do projeto ```text PROJECT.md specs.md specs/ ├── milestones/ │ ├── M01.md │ └── M02.md ├── backlog/ └── /-/spec.md ``` `specs.md` é o mapa do projeto: mostra a sequência das specs, o estado de cada uma e os marcos vinculados. A fonte de comportamento continua em cada `spec.md`, o objetivo e a condição de saída ficam no arquivo de milestone. ## Vincule specs e backlog Inclua o campo `Milestones` nas tabelas de uma spec ou de um item do backlog: ```md | Milestones | M02, M04 | ``` Uma spec possui uma milestone principal na maioria dos casos. Ela pode ter outro vínculo quando a mesma capacidade contribui para dois estados reais do produto. O backlog aparece no marco como trabalho relacionado, mas não aumenta o percentual de conclusão. ## Atualize o mapa automaticamente Depois de alterar relações ou status, execute: ```bash specsfy milestones sync --project . ``` O comando atualiza blocos identificados em `specs.md` e em `specs/milestones/MNN.md`. Texto fora desses blocos continua seu. Um marco referenciado por spec ou backlog e ainda sem arquivo recebe um esqueleto, para você completar na entrevista. `specsfy transition` também sincroniza o mapa depois de mover uma spec. Use o comando direto quando tiver alterado vínculos no Markdown ou refinado backlog. ## Cinco usos do comando ```bash # Criar ou atualizar o índice no projeto atual. specsfy milestones sync # Declarar explicitamente a raiz do projeto atual. specsfy milestones sync --project . # Consumir o resultado em outra automação local. specsfy milestones sync --project . --json # Atualizar um projeto em outro diretório. specsfy milestones sync --project ../crm # Atualizar relações depois de editar uma spec ou backlog. specsfy milestones sync --project . ``` O progresso considera specs com `Status: Complete`. A milestone só é concluída quando suas specs necessárias estiverem completas e você confirmar que a condição de saída foi demonstrada ou validada. ## Planeje o que vem depois Quando o MVP estiver aceito, use `$specsfy-roadmap-milestone-interviewer`. Ele parte dos limites já aprovados e organiza evolução, integrações, automações e hipóteses que dependem de uso real. Se uma resposta mudar o núcleo do MVP, o agente pede confirmação e encaminha a alteração da spec para `$specsfy-update-spec`. Para revisar o mapa existente e encontrar relações ausentes, use `$specsfy-milestone-governor`. Ele sincroniza a projeção, aponta lacunas e propõe ajustes, não altera objetivo ou condição de saída sem sua confirmação. ### Usar o Specsfy com Next.js: guia técnico do especialista - URL: https://promovaweb.com/docs/specsfy/nextjs - Descrição: Como o especialista specsfy-specialist-nextjs soma escolhas de Server e Client Components, cache e rotas do Next.js ao fluxo do Specsfy usado hoje. `$specsfy-specialist-nextjs` acrescenta ao fluxo do Specsfy as escolhas de Server e Client Components, cache, mutations, rotas e deploy próprias do Next.js. A skill confirma o router e a versão porque os padrões de cache mudam entre gerações do framework. ## Confirmar a detecção O catálogo detecta Next.js pela dependência `next` em `package.json` ou por `next.config.js`, `next.config.mjs` e `next.config.ts`. Confirme a versão e o router. O runtime, o destino de deploy e as flags ativas também precisam ser registrados no plano. ## Instalação ```bash specsfy skills detect --project . npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-nextjs --agent universal --copy --full-depth ``` Quando todas as recomendações forem aplicáveis, `--detected` instala as bases e os especialistas em uma única execução. Confira depois se `specsfy-specialist-nextjs` aparece no catálogo instalado: ```bash specsfy install --project . --detected ``` ## Aplicar na spec 1. Conduza a ideia até a spec pelo [primeiro projeto](/docs/specsfy/comecando). 2. Peça ao agente para usar `$specsfy-specialist-nextjs` na fatia ativa. 3. Mapeie a rota, o layout e os estados `loading`, `error` e `not-found`. Registre também o limite entre o código do servidor e a interação no navegador. 4. No App Router, mantenha componentes no servidor por padrão e mova ao cliente apenas o componente que requer estado, eventos ou APIs do navegador. 5. Defina cache, revalidation, tags e comportamento dinâmico explicitamente. 6. Trate Server Actions e Route Handlers como superfícies públicas: valide autenticação, autorização e entrada em cada mutation. 7. Derive testes para estados, redirects, autorização, invalidação e isolamento de dados entre usuários. 8. Execute lint, typecheck, testes, build e runtime de produção conforme os scripts do `package.json`. ## O que o especialista acrescenta - controle do limite entre Server e Client Components. - prevenção de segredos e módulos server-only no bundle cliente. - análise de waterfalls, streaming e recuperação de erro. - cache como contrato compatível com a versão instalada. - metadata, assets, bundle, imagens, fontes e Web Vitals. ## Resultado esperado As escolhas de renderização, cache e segurança ficam rastreadas pela spec e provadas por testes e build na versão e no router realmente usados. ## Limites - não presuma App Router ou semântica de cache sem confirmar a versão. - não mova uma árvore inteira ao cliente por conveniência. - não use middleware para lógica longa ou incompatível com o runtime. - não assuma comportamento específico do host sem documentá-lo. Não use esse especialista para escolher App Router, Pages Router ou runtime sem evidência. O código, `package.json`, o lockfile e a configuração comprovam o router, a versão, o runtime e os scripts disponíveis no projeto consumidor. ### Operação de deploy no Specsfy: servidores, conexões e chaves - URL: https://promovaweb.com/docs/specsfy/operacao-deploy - Descrição: Cadastre servidores, teste conexões e sincronize chaves públicas com os comandos curtos do deploy coordenado pelo Specsfy e executado via Ansible. A `specsfy-specialist-deploy` prepara os arquivos do projeto e mantém a lista de máquinas que receberão a aplicação. Este capítulo detalha essa camada operacional: onde cada arquivo fica, como uma máquina entra no ambiente, o que o teste de conexão comprova e quais comandos curtos você pode copiar no Herdr. ## Onde a automação fica no seu projeto A skill trabalha a partir da raiz que você confirmou. Os arquivos permanecem junto do sistema para que o Git mostre quando a infraestrutura muda com o código: ```text meu-projeto/ ├── deploy ├── SEMVER ├── Dockerfile ├── compose.yaml ├── stack.yaml ├── docker/ │ └── entrypoint.sh └── ansible/ ├── inventory.yml ├── inventory.example.yml ├── check-hosts.py ├── create-vault.sh ├── vault.py ├── deploy.yml ├── keys.yml ├── sync-keys.yml ├── secrets.yml ├── vault-fields.txt ├── group_vars/ │ ├── all.yml │ └── all/ │ └── vault.yml └── templates/ └── stack.yaml.j2 ``` No modo padrão, `vault-fields.txt` inclui `vault_cloudflare_tunnel_token`. Você informa esse valor pelo prompt oculto de `./deploy secrets`, junto dos demais secrets ainda ausentes. O template da stack monta o Docker Secret no serviço `cloudflared`, que compartilha a rede overlay com `app`. O arquivo `deploy` oferece nomes curtos para ações que você pode copiar em outro painel do Herdr. Você não precisa iniciar o fluxo por esses comandos. Um pedido como “faça o deploy desta aplicação” continua sendo a entrada normal, e a IA executa as ferramentas conforme o estado encontrado. ## O que muda quando você pede outro deploy Na primeira preparação, o gerador cria a base quando nenhum dos destinos existe. Nas chamadas seguintes, a IA não executa o gerador sobre os mesmos arquivos. Ela lê a aplicação outra vez, compara a infraestrutura atual com as necessidades do código e modifica somente o que precisa acompanhar a entrega. O `Dockerfile` recebe uma revisão própria. Em Laravel, a skill confere a versão do PHP, as extensões exigidas pelo Composer, o pacote `laravel/octane`, a extensão `openswoole`, o build dos assets, o entrypoint, as permissões, a porta, o healthcheck e o comando `octane:start --server=swoole`. Uma dependência nova que exija outra extensão PHP deve aparecer nessa análise antes do build. O mesmo exame alcança `compose.yaml`, `stack.yaml`, `docker/` e `ansible/`. Quando um arquivo possui personalizações do projeto, a skill preserva esses trechos e apresenta a comparação dos arquivos alterados antes de substituir uma estrutura sem marcações gerenciadas. Repetir o pedido não significa gerar tudo novamente. Significa reconciliar o estado existente com a aplicação que será publicada. Essa reconciliação também confere o ingresso. Sem uma escolha diferente, a IA mantém Cloudflare Tunnel como serviço da stack. Quando você pedir outro proxy, ela remove ou deixa de gerar os componentes do túnel e prepara a alternativa solicitada sem misturar tokens entre os dois caminhos. ## Como os servidores entram no inventário Antes da primeira conexão, a orquestradora aciona o especialista de Debian e pergunta quais máquinas fazem parte do ambiente. A conversa trata um servidor por rodada. Para cada máquina, você confirma: | Campo | O que representa | Exemplo | | --- | --- | --- | | alias | nome estável dentro do Ansible | `app01` | | endereço | IP ou hostname alcançável | `203.0.113.10` | | porta | porta usada pelo SSH | `22` | | usuário inicial | conta que já consegue entrar no host | `root` | | papel | função do node no Docker Swarm | `manager` | Essas respostas formam `ansible/inventory.yml`. O arquivo de exemplo ensina o formato, mas nunca substitui o inventário real durante uma conexão. Quando você disser “adicione um novo servidor”, a skill lê os hosts atuais e pergunta somente pelos dados da nova máquina. Depois, ela acrescenta o host ao grupo escolhido, testa o SSH, sincroniza as chaves públicas, prepara o usuário `deploy`, instala o Docker e integra o node ao Swarm. Os servidores anteriores permanecem no arquivo e não são renomeados ou removidos nessa operação. ## A conta do servidor e a conta do container O host e o container usam nomes diferentes porque cumprem funções diferentes. No Debian, `deploy` é a conta operacional que recebe as chaves SSH, pertence ao grupo `docker` e administra os diretórios sob `/opt/apps`. Dentro da imagem, `app` continua sendo a conta sem privilégios que executa o Laravel Octane. ```text máquina local ──SSH──> deploy@servidor ──Docker──> container: usuário app ``` O acesso por senha da conta `deploy` permanece desabilitado. O grupo `docker` concede controle amplo sobre o host, por isso a automação não adiciona outras contas a esse grupo sem uma necessidade confirmada. ## Teste das conexões Antes de alterar qualquer servidor, a skill executa o teste abaixo. Assim, um host inacessível aparece na tabela antes que o playbook modifique outra máquina: ```bash ./deploy check-hosts ``` O comando lê `ansible/inventory.yml`, chama o módulo `ping` do Ansible e mostra uma linha por máquina: ```text SERVIDOR ENDEREÇO PORTA USUÁRIO PAPEL ESTADO -------- ------------- ----- ------- ------- ---------- app01 203.0.113.10 22 root manager conectado app02 203.0.113.11 22 deploy worker conectado ``` O estado `conectado` confirma que o Ansible conseguiu autenticar e executar o módulo remoto. Ele não afirma que o Docker ou a aplicação estejam saudáveis. Se qualquer host estiver inacessível, o comando termina com erro e o deploy para antes da primeira escrita remota. ## Sincronização das chaves públicas A automação procura arquivos com o padrão `~/.ssh/*.pub` na máquina que está executando o agente. Somente o conteúdo das chaves públicas entra no `authorized_keys` de `deploy` em cada servidor cadastrado. Arquivos privados, como `id_ed25519` ou `id_rsa` sem o sufixo `.pub`, não são abertos nem enviados. Quando você quiser executar apenas essa etapa em um painel do Herdr, use: ```bash ./deploy sync-keys ``` A operação primeiro executa `check-hosts`. Depois, mantém as chaves já presentes e inclui somente as ausentes. Ela não usa sincronização exclusiva e, portanto, não remove o acesso de outra máquina administrativa. ## Comandos curtos para o Herdr | Comando | Finalidade | Efeito persistente | | --- | --- | --- | | `./deploy check-hosts` | listar o inventário e testar conexões | nenhum | | `./deploy secrets` | incluir campos ausentes | atualiza o Vault | | `./deploy sync-keys` | autorizar chaves `.pub` | atualiza os hosts | | `./deploy run` | aplicar o playbook com senha manual | atualiza Swarm e stack | | `./deploy configure-vault` | cadastrar senha externa | grava arquivo local fora do Git | | `./deploy run --non-interactive` | publicar com fonte de senha pronta | atualiza Swarm e stack | O inventário padrão é `ansible/inventory.yml`. Para conferir outro arquivo sem alterar o projeto, defina `ANSIBLE_INVENTORY` somente para aquela execução. Estes exemplos cobrem as ações disponíveis: ```bash ./deploy check-hosts ANSIBLE_INVENTORY=ansible/inventory.staging.yml ./deploy check-hosts ./deploy secrets ./deploy sync-keys ./deploy run ``` `check-hosts` não recebe senhas como argumentos. `secrets` abre prompts ocultos e não aceita valores pela linha de comando. `sync-keys` recusa continuar quando não encontra uma chave pública local. `run` testa as conexões antes do playbook e solicita a senha do Vault no próprio terminal no modo manual. Volte ao capítulo [Como funciona o Deploy da aplicação](/docs/specsfy/deploy) para acompanhar build, publicação, rollout, migrations, rollback e conferência da versão ativa. O capítulo [Senha do Vault e deploy pela IA](/docs/specsfy/senha-vault) explica o cadastro externo, os dois modos de execução e a migração de scripts existentes. ### Referência do Specsfy CLI: comandos, opções e exemplos - URL: https://promovaweb.com/docs/specsfy/referencia-cli - Descrição: Consulte comandos, argumentos, opções, saídas, efeitos persistentes, recusas e exemplos do Specsfy CLI para uso interativo e automação. Veja a aplicação. Esta referência descreve a interface pública do `specsfy` 0.8.1. O caminho informado por `--project` deve apontar para a raiz do projeto consumidor. Sem essa opção, o CLI usa o diretório atual. Os comandos que consultam catálogo ou versões privadas usam `GH_TOKEN`, `GITHUB_TOKEN` ou a sessão de `gh auth token`. Para aprender o percurso pela interface visual, consulte o [guia do CLI e da TUI](/docs/specsfy/cli). Para preparar o primeiro projeto, comece pela [instalação](/docs/specsfy/instalacao). ## `specsfy` Abre a TUI no diretório atual. Não recebe argumentos. Antes do dashboard, pode consultar uma versão estável mais recente e pedir autorização para atualizar o pacote global. A recusa ou uma falha de rede preserva a versão instalada. Exemplos: ```bash specsfy cd aplicativo && specsfy GH_TOKEN="$TOKEN_SPECSFY" specsfy GITHUB_TOKEN="$TOKEN_SPECSFY" specsfy SPECSFY_SPECIALISTS_CATALOG=/tmp/catalog.json specsfy ``` ## `specsfy install` Instala as skills base, regras, templates, exemplo e blocos gerenciados no projeto. `--detected` acrescenta os especialistas encontrados pela stack. `--specialist ` pode ser repetido. `--force` permite substituir conteúdo gerenciado que recebeu alteração local. `--json` emite a lista de caminhos alterados como JSON. O comando recusa a raiz do monorepo oficial. Exemplos: ```bash specsfy install --project . specsfy install --project ./aplicativo --json specsfy install --project . --detected specsfy install --project . --specialist specsfy-specialist-laravel specsfy install --project . --detected --force --json ``` ## `specsfy doctor` Verifica Node.js, Git, npm, acesso de leitura e escrita ao projeto e a disponibilidade do `npx`. A resolução usa `npx` encontrado no `PATH` ou o override técnico `SPECSFY_NPX_COMMAND`, a instalação materializa skills por `npx skills add`. `--json` retorna cada item, seu estado e o comando encontrado. Qualquer requisito ausente produz exit code 1. Exemplos: ```bash specsfy doctor specsfy doctor --project . specsfy doctor --project ./api specsfy doctor --json specsfy doctor --project ./api --json ``` ## `specsfy update` Atualiza todas as skills Specsfy registradas no projeto, incluindo skills base, auxiliares, setup, documentador e especialistas. Skills externas e templates customizados permanecem intocados. `--force` substitui conteúdo gerenciado alterado e `--json` informa os caminhos modificados. O comando executa o diagnóstico de instalação antes do download. Exemplos: ```bash specsfy update specsfy update --project . specsfy update --project ./api specsfy update --force specsfy update --project ./api --force --json ``` ## `specsfy upgrade` Consulta novamente a versão publicada no npm e atualiza o próprio CLI pelo pacote `@promovaweb/specsfy@latest`. O npm só é executado quando a versão encontrada é superior à versão atual, o que impede downgrade e ignora um adiamento anterior. `--json` informa se houve atualização e as versões envolvidas. O projeto não é alterado. Exemplos: ```bash specsfy upgrade specsfy upgrade --json GH_TOKEN="$TOKEN_SPECSFY" specsfy upgrade GITHUB_TOKEN="$TOKEN_SPECSFY" specsfy upgrade --json PATH="$HOME/.npm-global/bin:$PATH" specsfy upgrade ``` ## `specsfy skills list` Lista o catálogo do framework e dos especialistas. `--json` entrega objetos estruturados para automação. A leitura consulta o catálogo remoto, exceto quando `SPECSFY_SPECIALISTS_CATALOG` aponta para uma fonte local. Exemplos: ```bash specsfy skills list specsfy skills list --json specsfy skills list --json > /tmp/specsfy-skills.json GH_TOKEN="$TOKEN_SPECSFY" specsfy skills list SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy skills list --json ``` ## `specsfy skills detect` Compara os arquivos do projeto com as regras do catálogo e retorna as skills recomendadas. `--project ` seleciona a raiz e `--json` fornece saída estruturada. O comando apenas consulta, sem instalar arquivos. Exemplos: ```bash specsfy skills detect specsfy skills detect --project . specsfy skills detect --project ./api --json GH_TOKEN="$TOKEN_SPECSFY" specsfy skills detect --project . SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy skills detect --json ``` ## `specsfy skills install` Depois de revisar a recomendação e autorizar a instalação, este comando usa `npx skills add` com o repositório oficial e somente os nomes necessários. Ele materializa a skill no projeto atual, não instale o catálogo inteiro por padrão. Exemplos: ```bash specsfy skills install specsfy-specialist-laravel specsfy skills install specsfy-specialist-postgres --project ./api specsfy skills install specsfy-specialist-laravel specsfy-specialist-postgres specsfy skills install specsfy-specialist-react-ui-components --project . specsfy skills install specsfy-specialist-interface-experience --project . ``` ## `specsfy skills remove` Remove somente as skills nomeadas e preserva skills externas presentes no mesmo lock. Os nomes são obrigatórios. Conteúdo local divergente impede a remoção, a menos que `--force` seja informado. A saída lista os caminhos alterados. Exemplos: ```bash specsfy skills remove specsfy-specialist-laravel specsfy skills remove specsfy-specialist-postgres --project ./api specsfy skills remove specsfy-specialist-laravel specsfy-specialist-postgres specsfy skills remove specsfy-specialist-react-ui-components --project . specsfy skills remove specsfy-specialist-laravel --project . --force ``` ## `specsfy skills update` Alias compatível de `specsfy update`. Atualiza todas as skills Specsfy já instaladas. `--project ` seleciona o projeto. `--force` permite substituir conteúdo gerenciado alterado e `--json` retorna os caminhos. Skills externas e arquivos de `.specsfy/templates/custom/` permanecem intocados. Exemplos: ```bash specsfy skills update specsfy skills update --project . specsfy skills update --project ./api specsfy skills update --force specsfy skills update --project ./api --force ``` ## `specsfy transition` Move uma spec para `draft`, `defined`, `planned`, `in-progress`, `review` ou `completed` e atualiza o campo `Status` no mesmo ato. O identificador e o estado são obrigatórios. `--json` inclui o caminho resultante e o handoff opcional do ClickUpfy. O comando recusa transições não permitidas e sincroniza os milestones após a escrita. Exemplos: ```bash specsfy transition 0001-recuperar-senha defined specsfy transition 0001-recuperar-senha planned --project . specsfy transition 0001-recuperar-senha in-progress --json specsfy transition 0001-recuperar-senha review --project ./api specsfy transition 0001-recuperar-senha completed --project . --json ``` ## `specsfy migrate` Move specs do layout anterior para as pastas do ciclo de vida e alinha o campo `Status`. `--project ` seleciona a raiz. `--json` retorna a coleção `migrated`. Quando não há fonte legada, a execução não altera arquivos. Exemplos: ```bash specsfy migrate specsfy migrate --project . specsfy migrate --project ./api specsfy migrate --json specsfy migrate --project ./api --json ``` ## `specsfy effort` Registra a pontuação inteira de 1 a 10 e sua justificativa na spec. O identificador, a pontuação e `--reason ` são obrigatórios. `--json` inclui o resultado e o handoff opcional do ClickUpfy. Pontuação fora do intervalo ou spec ambígua é recusada. Exemplos: ```bash specsfy effort 0001-recuperar-senha 3 --reason "Alteração local." specsfy effort 0001-recuperar-senha 5 --reason "Inclui testes de integração." specsfy effort 0001-recuperar-senha 7 --reason "Inclui migração." --project . specsfy effort 0001-recuperar-senha 8 --reason "Depende de API externa." --json specsfy effort 0001-recuperar-senha 10 \ --reason "Entrega distribuída." --project ./api --json ``` ## `specsfy progress` Lê specs e calcula estados, gates, Effort, tarefas, checklists e porcentagens. `--json` retorna `summary` e `specs`. `--watch` permanece ativo e só emite um novo snapshot após mudança das fontes. `--interval ` configura a espera do watch e deve ser maior que zero. O comando não altera o projeto. Exemplos: ```bash specsfy progress specsfy progress --project . specsfy progress --project ./api --json specsfy progress --watch specsfy progress --project . --watch --interval 0.5 --json ``` ## `specsfy milestones sync` Projeta os vínculos declarados nas specs e no backlog para `specs.md` e `specs/milestones/MNN.md`. Somente blocos gerados são substituídos. `--json` retorna o caminho do índice e os totais de cada milestone. Referências inválidas ou metadados ambíguos interrompem a escrita. Exemplos: ```bash specsfy milestones sync specsfy milestones sync --project . specsfy milestones sync --project ./api specsfy milestones sync --json specsfy milestones sync --project ./api --json ``` ## `specsfy test` Detecta um projeto Laravel com Pest, executa `php artisan test`, transmite a saída e devolve o mesmo exit code. `--project ` seleciona a raiz. O comando não aceita uma string arbitrária de shell e recusa projetos sem runner compatível. Antes de iniciar o processo PHP, exige `.env.testing` com `APP_ENV=testing` e um `DB_DATABASE` ou `DB_URL` explícito, separado do `.env`. Também recusa `RefreshDatabase` e `DatabaseMigrations`. A TUI aplica o mesmo gate, quando a configuração estiver pendente, nenhum teste é iniciado. Exemplos: ```bash specsfy test specsfy test --project . specsfy test --project ./api NO_COLOR=1 specsfy test --project . specsfy test --project "./aplicativo Laravel" ``` ## `specsfy tui` Abre explicitamente o dashboard para o projeto selecionado. `--project` recebe um caminho e usa o diretório atual por padrão. A TUI pode escrever configuração, instalar skills e executar testes somente após uma ação da pessoa. `Ctrl+Q` encerra a interface. Exemplos: ```bash specsfy tui specsfy tui --project . specsfy tui --project ./api GH_TOKEN="$TOKEN_SPECSFY" specsfy tui --project . SPECSFY_SPECIALISTS_CATALOG=./catalog.json specsfy tui --project . ``` ## `specsfy config show` Lê a configuração efetiva de `.specsfy/config.json`. `--project` seleciona a raiz e `--json` fornece saída estruturada. A ausência do arquivo usa os valores padrão e não cria configuração. Exemplos: ```bash specsfy config show specsfy config show --project . specsfy config show --project ./api specsfy config show --json specsfy config show --project ./api --json ``` ## `specsfy config set` Grava o intervalo de atualização da TUI em `.specsfy/config.json`. `--watch-interval ` é obrigatório e aceita número positivo. `--project` seleciona a raiz e `--json` retorna a configuração resultante. Chaves desconhecidas existentes são preservadas. Exemplos: ```bash specsfy config set --watch-interval 0.5 specsfy config set --project . --watch-interval 0.75 specsfy config set --project ./api --watch-interval 1 specsfy config set --watch-interval 2 --json specsfy config set --project ./api --watch-interval 5 --json ``` ## Justificativa de tamanho A referência mantém comandos, parâmetros, efeitos, recusas e exemplos no mesmo arquivo para que a cobertura automatizada compare a gramática executável com uma única fonte. Separar cada comando impediria essa conferência direta e espalharia opções compartilhadas por várias páginas. ## Confirmação e diagnóstico Depois de qualquer escrita, confirme o resultado com uma leitura compatível: `skills list`, `progress`, `milestones sync --json` ou `config show --json`. Falhas do CLI são impressas em `stderr` com o prefixo `erro:` e retornam exit code diferente de zero. `--help` mostra a gramática instalada e `--version` confirma qual release está sendo executada. ### Referência do método do Specsfy: estados, gates e Effort - URL: https://promovaweb.com/docs/specsfy/referencia-do-metodo - Descrição: Consulte estados, gates, Effort, seções e rastreabilidade da spec do Specsfy para interpretar cada etapa e confirmar a entrega no projeto com segurança. Este capítulo explica os campos, estados e provas de uma entrega no Specsfy. Use-o junto do [guia da metodologia](/docs/specsfy/metodo) quando quiser interpretar uma `spec.md`, a tela de progresso ou uma pergunta do agente com precisão. ## A spec como registro único Cada entrega escolhida possui uma única fonte normativa: ```text specs//-/spec.md ``` `NNNN` mantém a sequência de criação e o `slug` identifica o assunto. A pasta mostra o estado operacional. O campo `Status` no topo da spec é o espelho desse estado. Use `specsfy transition` para alterar os dois juntos, pois mover a pasta manualmente deixa o registro inconsistente. A spec não é um relatório preenchido no final. Ela recebe a definição no Ato I, o plano e o RED no Ato II, e as tarefas com seus resultados no Ato III. Código, testes, pesquisa e documentação derivada podem ficar em outros arquivos, mas a ligação entre eles permanece na spec. ## Leitura do sistema existente Antes de uma skill propor tecnologia, telas ou implementação, o setup percorre as fontes relevantes do projeto: instruções, manifests, configuração, aplicação, rotas, persistência, integrações, interface, testes e documentação. Ele usa essa leitura para preservar convenções, comportamento e fontes já existentes. Quando houver muitas fontes, informa o conjunto lido antes de avançar, uma sugestão não substitui a análise do código existente. | Campo ou seção | O que registra | Como usar | | --- | --- | --- | | `Status` e pasta | posição da entrega no fluxo | identificar a próxima atividade permitida | | `Effort` | capacidade de raciocínio e execução necessária | calibrar acompanhamento, não prazo | | Gates | prova de prontidão de cada ato | impedir avanço prematuro | | Seções 1–7 | problema, escopo, comportamento e requisitos | conferir o que será entregue | | Seções 8–15 | plano, testes, tarefas e relações | conferir como a entrega será construída | | Seções 16–18 | dependências, escolhas e conclusão | conferir limites e encerramento | ## Effort `Effort` é uma escala inteira de 1 a 10 para a capacidade de raciocínio, investigação, coordenação e execução pedida pela entrega no estado atual. Não representa horas, dias, preço, quantidade de pessoas ou prazo prometido. Uma tarefa curta pode ter Effort alto quando envolve autorização delicada, migração difícil de reverter ou integração pouco conhecida. Uma tarefa longa pode ficar em faixa menor quando segue uma convenção já comprovada e tem testes diretos. O valor inicial é uma hipótese de trabalho. Ele pode mudar depois de uma resposta confirmada, da leitura do repositório, de uma dependência descoberta ou de um resultado de teste. O CLI guarda valor anterior, data e justificativa no histórico da própria spec. Assim, a pessoa que retoma a entrega consegue ver o motivo de cada recalibração. ### Faixas e perfis | Effort | Perfil exibido | Situação típica | Acompanhamento | | --- | --- | --- | --- | | 1–2 | `light` | ajuste atômico em padrão conhecido | escopo e teste focal | | 3–4 | `standard` | mudança local com testes diretos | requisitos, arquivos e variações | | 5–6 | `standard` | vários arquivos ou integração conhecida | dependências, testes e ordem | | 7–8 | `high` | mudança transversal, migração ou integração externa | contratos, dados, reversão e documentação | | 9–10 | `maximum` | arquitetura ou incerteza relevante | descoberta progressiva e revisão frequente | As faixas orientam o perfil exibido pelo progresso, mas não autorizam pular um gate. Uma entrega de Effort 1 ainda precisa de definição, plano compatível e prova de entrega. Uma entrega de Effort 9 pode ser dividida em entregas menores quando seus comportamentos forem independentes. ### Quando atualizar Atualize Effort quando um fato mudar a capacidade necessária: mais módulos, dados existentes, integração externa, autorização, compatibilidade ou revisão humana recorrente podem elevar a faixa. Escopo menor, padrão já comprovado ou dependência removida podem reduzi-la. Não altere o número para comunicar urgência, pressão comercial ou preferência por modelo. Registre o fato que mudou a estimativa. Uma justificativa como “passou de 4 para 7 porque inclui migração de dados existentes e compatibilidade com uma API publicada” permite revisar o valor mais tarde. Depois da confirmação, use: ```bash specsfy effort <1-10> --reason "" ``` O entrevistador pode conduzir essa atualização, mas não inventa justificativa nem transforma Effort em autorização para implementar. ### Effort não é prioridade Prioridade responde o que deve receber atenção antes. Effort responde quanta capacidade a entrega exige. Um ajuste urgente pode ter Effort 2. Um estudo que ficará para depois pode ter Effort 8. O backlog ordena itens por valor, urgência, dependências, exposição operacional, esforço e informações ausentes. A spec usa Effort para tornar a execução transparente. ## Estados e transições O ciclo canônico é: ```text draft → defined → planned → in-progress → review → completed ``` | Pasta | `Status` | O que já existe | O que ainda não vale | | --- | --- | --- | --- | | `draft` | `Draft` | intenção e definição em construção | tratar requisitos como aprovados | | `defined` | `Defined` | Definition Gate aprovado | implementar ou declarar plano pronto | | `planned` | `Planned` | plano, tarefas e RED compatíveis | editar código sem iniciar a execução | | `in-progress` | `Implementing` | tarefas e verificações em execução | concluir com trabalho pendente | | `review` | `Reviewing` | Delivery Gate aprovado | alterar sem retornar à etapa necessária | | `completed` | `Complete` | aceite final e documentação atual | incluir nova solicitação por edição direta | ### O significado de cada estado Em `draft`, o agente esclarece problema, resultado, atores, escopo, regras, casos-limite e comportamento observável. Uma dúvida que muda produto, dados, segurança, aceite ou plano impede o gate da definição. Pesquisa pode apoiar a conversa, mas precisa ter conclusão e impacto registrados na spec. Em `defined`, problema, limites, histórias, requisitos e cenários BDD permitem planejar sem adivinhar o que será aceito. Uma mudança de comportamento retorna a spec para `draft` e torna o gate da definição pendente novamente. Em `planned`, há plano técnico, tarefas, dependências, contratos, plano de teste e RED válido. Um RED não vale quando falha por sintaxe, fixture incompleta, dependência ausente ou ambiente indisponível. Ele precisa apontar a ausência do comportamento pretendido. Em `in-progress`, cada tarefa segue a ordem registrada ou uma alteração justificada. Uma tarefa de código percorre RED, GREEN e REFACTOR, registrando comando, resultado, IDs cobertos e arquivos envolvidos. Descoberta que muda o comportamento retorna ao primeiro ato cuja prova perdeu validade. Em `review`, a entrega já passou pelo Delivery Gate e aguarda aceite final. Um retorno de aceite pode levar a `in-progress` para correção técnica ou a um ato anterior quando a definição também mudar. Em `completed`, o pacote preserva o histórico. Uma solicitação nova inicia ou atualiza uma entrega ativa, em vez de alterar diretamente a spec concluída. ### Retornos permitidos | Origem | Destinos aceitos | Motivo de retorno | | --- | --- | --- | | `draft` | `draft`, `defined` | a definição ainda está aberta | | `defined` | `draft`, `defined`, `planned` | requisito, escopo ou aceite mudou | | `planned` | `defined`, `planned`, `in-progress` | plano revelou problema na definição ou RED precisa ser refeito | | `in-progress` | `planned`, `in-progress`, `review` | tarefa, teste ou plano perdeu validade | | `review` | `in-progress`, `review`, `completed` | aceite final encontrou trabalho pendente | | `completed` | `completed` | entrega fechada não recebe edição direta | Mudança apenas de estratégia técnica retorna a `planned`. Mudança de comportamento retorna a `draft`. Uma comprovação vencida, como regressão executada antes da última alteração, pede nova verificação. O método não repete etapas por ritual: ele evita aprovar um resultado novo com uma prova antiga. ## Gates Um gate fica `Pending` enquanto sua etapa não tem a comprovação exigida e fica `Passed` quando as condições foram verificadas e registradas. Ele não é uma estimativa de qualidade nem um botão de aprovação manual. ### Definition Gate O gate do Ato I exige problema e resultado observável, escopo incluído e fora de escopo, atores, regras, histórias, requisitos funcionais e não funcionais, três cenários BDD distintos para cada item principal e nenhuma lacuna P1 que impeça o planejamento. Quando a entrega tem interface para pessoas, ele exige também telas, fluxo de informação, menus e navegação principal, formulário, composição, estados e acessibilidade descritos na seção 10. Um CRUD sem telas e formulário mantém o gate pendente. Termo ambíguo, requisito sem forma de teste, história sem aceite ou conflito entre seções mantêm o gate pendente. ### Plan Gate O gate do Ato II exige plano técnico proporcional, contratos e dados aplicáveis, tarefas com IDs e dependências, estratégia TDD derivada do BDD, RED válido, plano de testes e ordem de execução. Uma lista de tarefas vaga, sem referências, ou um teste sem cenário correspondente não torna o plano pronto. ### Delivery Gate O gate do Ato III exige tarefas tratadas, GREEN para os testes derivados do comportamento, aceite e regressão no estado atual, rastreabilidade entre histórias, requisitos, cenários, testes e tarefas, registros dos comandos e documentação atualizada quando a mudança a alcança. Um teste verde isolado não fecha o gate, pois ele pode cobrir somente parte do comportamento. ## Anatomia completa da spec A tabela inicial da spec identifica o formato, o ID, o slug, o estado, Effort, o vínculo opcional com ClickUp, os três gates, a versão do contrato de comprovação e a data de atualização. Não use essa tabela para esconder uma mudança material: o detalhamento fica na seção que trata do assunto e a tabela apenas torna o estado geral legível. ### Ato I: seções 1 a 7 | Seção | Finalidade | O que precisa ficar claro | | --- | --- | --- | | 1. Problema e resultado | separar a dor atual da mudança desejada | contexto observável, resultado esperado e métrica verificável | | 2. Research e esclarecimentos | registrar o que foi investigado e o que ainda está aberto | pergunta, fonte, conclusão, impacto, dúvidas respondidas e dúvidas abertas | | 3. Escopo e atores | delimitar quem participa e o que a entrega cobre | incluído, fora de escopo, objetivos e permissões dos atores | | 4. Princípios e restrições | preservar regras já confirmadas pelo projeto | regras de governança, arquitetura, qualidade ou compatibilidade | | 5. Histórias de usuário | explicar valor por ator | capacidade, valor, prioridade, requisito e teste independente | | 6. Cenários BDD de aceite | tornar o comportamento observável | condição inicial, ação, resultado e IDs cobertos | | 7. Requisitos | declarar obrigações do sistema | funções, qualidades mensuráveis, erros e casos-limite | A seção 1 não deve antecipar a solução. “Criar uma tela” descreve uma possível implementação, enquanto “permitir que uma pessoa recupere acesso sem revelar se um e-mail existe” descreve o resultado e seu limite. A métrica de sucesso precisa ter um alvo ou uma observação verificável, não uma impressão genérica. A seção 2 diferencia pesquisa de escolha. Um R-001 pode registrar uma documentação de API consultada e concluir que determinado endpoint exige idempotência. A regra que a entrega adotará aparece depois na seção de restrições, requisitos, plano ou escolhas. Se a fonte externa foi realmente consultada, seu registro local em research/ preserva origem, versão ou data e o ponto usado na conclusão. Na seção 3, “fora de escopo” protege tanto o projeto quanto a expectativa de quem acompanha a entrega. Por exemplo, uma entrega que permite solicitar troca de senha pode deixar explícito que não inclui autenticação social, gestão de perfis ou alteração do visual de todas as telas. Atores não são apenas pessoas: um serviço externo, um job ou um administrador pode ter objetivo, permissão e limite próprios. Nas seções 5, 6 e 7, a mesma necessidade aparece em três níveis. A história explica para quem a capacidade gera valor. O requisito declara a obrigação. O cenário mostra um exemplo que pode ser aceito ou recusado. Essa diferença evita história vaga, requisito sem teste e cenário que não representa valor. ### Ato II: seções 8 a 15 | Seção | Finalidade | Perguntas que a seção responde | | --- | --- | --- | | 8. Plano técnico | tornar a implementação compreensível antes da execução | quais módulos, dados, contratos, arquivos e compatibilidades serão afetados? | | 9. Modelo de dados | explicar persistência e ciclo de vida da informação | quais entidades, estados, transições, retenção e migrações existem? | | 10. Interfaces e contratos | registrar superfícies de integração e a experiência para pessoas | quais telas, menus, formulários, fluxos, ações, APIs, eventos, entradas, saídas e falhas importam? | | 11. Estratégia TDD | derivar testes executáveis do BDD | qual caso falha primeiro, por qual motivo e como ficará verde? | | 12. Plano de testes e rastreabilidade | ligar requisito à comprovação | qual cenário, nível, arquivo ou comando cobre cada item? | | 13. Validações | registrar os gates e achados | qual comando foi executado, qual resultado produziu e o que falta? | | 14. Tarefas | dividir a entrega em ações verificáveis | o que fazer, em qual ordem, com quais referências e dependências? | | 15. Ordem de execução | expor dependências reais | qual é o caminho crítico, o paralelismo e o menor conjunto entregável? | O plano técnico é proporcional ao alcance. Uma alteração local pode registrar um componente, teste e arquivo. Uma migração precisa explicar compatibilidade, ordem, reversão e retenção. Quando uma categoria não se aplica, escreva “Não aplicável” com a razão, em vez de deixar uma lacuna que pareça esquecimento. Quando o cabeçalho declara `Interface para pessoas: Sim`, a seção 10 também registra a stack e o sistema atual observados, a responsabilidade de cada tela, os menus, seus itens e destinos, como a pessoa avança e retorna no fluxo, os campos e validações dos formulários, o padrão de abertura de ações, a disposição dos elementos e os estados de interface. O Specsfy analisa rotas, telas, componentes, conteúdo, permissões e testes antes de perguntar as lacunas reais. Assim, painel lateral, modal, página ou outro padrão não vira uma escolha escondida do agente nem substitui o que já existe sem confirmação. Uma spec de interface também possui `Fase de interface` na seção 14. Cada tela recebe tarefa própria com caminho, testes de navegação, formulário, validações, feedback e teclado. O validador não aceita a fase ausente ou com menos tarefas do que as telas registradas. O modelo de dados descreve estados de domínio, não o estado da pasta da spec. Por exemplo, um pagamento pode transitar de pendente para confirmado ou cancelado, enquanto a spec que altera pagamentos pode estar em planned. Mantenha as duas máquinas de estado separadas para não confundir o ciclo da entrega com o ciclo da informação do produto. A estratégia TDD e o plano de testes são complementares. A seção 11 explica a sequência RED, GREEN e REFACTOR para o caso. A seção 12 permite localizar a relação entre requisito, cenário BDD, nível de teste, arquivo e comando. O marcador SPECSFY: no teste deve usar os IDs da spec. O resultado é uma cadeia que uma pessoa consegue seguir nos dois sentidos. A seção 13 registra o resultado de cada gate e os achados de revisão. Um achado especializado usa identificador, severidade, estado, referências e comprovação. Marcar um achado como aceito não o torna invisível: a spec precisa mostrar o motivo, o responsável e o limite aceito. Nas tarefas, [P] indica possibilidade de execução paralela apenas quando as dependências realmente permitem. Depends: none não é enfeite: significa que a tarefa pode começar sem outra tarefa da spec. A ordem de execução consolida essa informação em caminho crítico, tarefas paralelas e estratégia de MVP. ### Ato III: seções 16 a 18 | Seção | Finalidade | O que registrar | | --- | --- | --- | | 16. Dependências, riscos e suposições | expor condições externas e hipóteses | dependência, consequência, mitigação e condição que ainda precisa de confirmação | | 17. Decisões | preservar escolhas confirmadas | escolha, motivo, referências atingidas e ato que precisa ser revisto se ela mudar | | 18. Definition of Done | fechar o contrato de entrega | critérios de conclusão, aceite, documentação e comprovações finais | Dependências são itens fora do controle imediato da tarefa, como uma API, aprovação, credencial fornecida por outra equipe ou migração prévia. Suposições são premissas ainda não confirmadas. Registre ambas de forma explícita para que um teste verde não esconda uma condição externa não atendida. A seção 17 não substitui um ADR para uma escolha arquitetural transversal nem substitui as seções de requisito e plano. Ela conserva a escolha da entrega e mostra o que precisa ser reavaliado quando a escolha for revista. O histórico é mais útil quando registra alternativas descartadas e seu motivo, sem reescrever o passado como se a escolha atual sempre tivesse sido conhecida. A Definition of Done é o fechamento da entrega concreta. Ela reúne gates, testes, aceite, regressão, rastreabilidade, documentação e pendências tratadas. Não use uma lista genérica copiada de outra spec. Cada item precisa corresponder ao comportamento, aos dados e às integrações daquela entrega. ## Identificadores e rastreabilidade | Prefixo | Representa | Uso | | --- | --- | --- | | `US-001` | história de usuário | valor para um ator | | `FR-001` | requisito funcional | comportamento obrigatório | | `NFR-001` | requisito não funcional | condição mensurável de qualidade ou operação | | `AC-001` | cenário BDD de aceite | caminho principal, regra ou limite | | `T001` | tarefa | ação que atende referências declaradas | | `R-001` | pesquisa | pergunta, conclusão, fonte e impacto | | `FIND-*` | achado de revisão | tipo, severidade, estado e referência | Cada história principal possui três cenários distintos. Em geral, um cobre o caminho principal, outro uma regra crítica e outro uma falha ou limite. O cenário declara os IDs cobertos. O teste TDD usa o marcador `SPECSFY:` com os mesmos IDs. Essa cadeia mostra requisito sem teste e teste sem comportamento definido. ## Tarefas, pesquisa e progresso Uma tarefa registra ID, tipo, história relacionada, ação, caminho, referências e dependências. O checklist abaixo dela deixa seis movimentos auditáveis: | Movimento | Pergunta respondida | | --- | --- | | `PREP` | escopo, referências, dependências e baseline estão claros? | | `EXECUTE` | qual entrega foi produzida no caminho declarado? | | `VERIFY` | qual verificação focal confirmou o resultado? | | `VISUAL` | a interface respeita bordas, espaçamentos, margens, padding e tipografia, ou por que a revisão não se aplica? | | `EVIDENCE` | qual comando, resultado e IDs permitem conferir o trabalho? | | `IMPROVE` | houve melhoria de processo ou há motivo registrado para não aplicá-la? | Pesquisa responde uma pergunta, mas não aprova sozinha uma regra de produto. Registre pergunta, conclusão, fonte, localizador e impacto. Fonte externa consultada requer registro local em `research/`, enquanto a conclusão normativa fica na spec, ligada ao escopo, requisito ou plano. `specsfy progress` lê as specs sem alterá-las. Ele mostra estado, Effort, perfil, gates e contagens. Sua porcentagem é uma projeção, não uma aprovação: com checklists, ela usa itens concluídos sobre itens totais, e sem checklists, gates aprovados sobre gates totais. Use a porcentagem para localizar trabalho pendente. Use gates, resultados de teste e leitura da spec para confirmar um avanço. ## Dúvidas frequentes | Dúvida | Resposta | | --- | --- | | Posso implementar com Definition Gate aprovado? | Não. Falta o plano e o RED do Ato II. | | Testes verdes permitem mover para `completed`? | Não. Falta aceite final em `review` e documentação aplicável. | | Effort 10 significa dez dias? | Não. É a maior faixa de capacidade necessária. | | RED de ambiente quebrado vale? | Não. O RED precisa indicar ausência do comportamento. | | Pesquisa é requisito aprovado? | Não. A conclusão precisa ser incorporada e confirmada na spec. | | Porcentagem de progresso aprova a entrega? | Não. Ela apenas projeta itens ou gates concluídos. | Retorne ao [guia da metodologia](/docs/specsfy/metodo) para a jornada ou à página da skill que corresponde ao estado atual da sua spec. ## Justificativa de tamanho Este capítulo reúne contratos que antes apareciam em páginas diferentes ou em menções breves: Effort, estados, transições, gates, seções da spec, rastreabilidade, tarefas, pesquisa e progresso. Mantê-los próximos permite comparar o significado de cada campo sem exigir leitura do código ou salto entre vários guias. As páginas das skills continuam explicando como executar cada etapa, enquanto esta referência preserva os conceitos compartilhados. ### Senha do Ansible Vault no Specsfy: deploy manual e por IA - URL: https://promovaweb.com/docs/specsfy/senha-vault - Descrição: Configure a senha do Ansible Vault fora do Git e use o deploy manual ou pela IA, com arquivos externos, scripts de cofre e exemplos dos comandos. ## Configurar a senha fora do projeto Você pode continuar digitando a senha a cada deploy ou preparar a máquina para que a IA execute a publicação sem perguntas. Nos dois casos, os valores da aplicação permanecem criptografados no Ansible Vault. A configuração externa muda somente a maneira de fornecer a senha que abre esse arquivo. ### Comando configure-vault Execute `./deploy configure-vault` no seu terminal. O comando pede a senha atual do Vault duas vezes e grava um arquivo fora do repositório. A senha não aparece na tela, nos argumentos do processo ou nas mensagens do configurador. Ela fica em texto simples no arquivo local, com permissão `600`, dentro de uma pasta com permissão `700`. Seu usuário e administradores da máquina podem ler esse arquivo, por isso, use somente uma máquina sob seu controle. O destino padrão é `~/.config/specsfy/vault/-/password`. O hash identifica o caminho real do checkout e separa projetos com nomes iguais. A variável `XDG_CONFIG_HOME`, quando definida com caminho absoluto, substitui `~/.config`. Mover o checkout exige configurar o novo caminho ou fornecer a fonte explicitamente. | Opção | Tipo e padrão | Efeito | | --- | --- | --- | | `--vault-password-file ` | caminho opcional | escolhe outro arquivo externo | | `--show-path` | booleano, desativado | mostra somente o destino, sem criar nem ler a senha | O configurador recusa caminhos dentro do worktree e links simbólicos. Antes de substituir um arquivo, pede confirmação, responder `n` ou usar Enter preserva o conteúdo. Senhas diferentes na confirmação também preservam o arquivo. O comando exige terminal para cadastrar e não aceita a senha como argumento. Sucesso retorna código `0`, falha retorna `1`, opção inválida `2` e cancelamento por Ctrl+C `130`. Estes cinco usos cobrem o cadastro, a consulta e a separação de configurações: ```bash # Cadastrar a senha na localização padrão deste projeto ./deploy configure-vault ``` ```bash # Conferir o destino sem abrir o arquivo ./deploy configure-vault --show-path ``` ```bash # Cadastrar um arquivo externo específico para produção ./deploy configure-vault \ --vault-password-file "$HOME/.config/minha-app/producao/password" ``` ```bash # Conferir um destino personalizado antes do cadastro ./deploy configure-vault --show-path \ --vault-password-file "$HOME/.config/minha-app/producao/password" ``` ```bash # Usar uma raiz de configuração diferente nesta máquina XDG_CONFIG_HOME="$HOME/.config-automacao" ./deploy configure-vault ``` Um destino personalizado precisa ser informado nas execuções seguintes por `--vault-password-file`, `ANSIBLE_VAULT_PASSWORD_FILE` ou `ansible.cfg`. O cadastro padrão é descoberto automaticamente pelo modo sem interação do mesmo checkout e usuário. A consulta `--show-path` ajuda a conferir permissões com `stat`, sem revelar o conteúdo. ### Trocar, remover ou configurar outra máquina Para substituir a cópia local da senha, execute o mesmo comando de cadastro, confirme com `s` e informe a senha atual. Isso não altera a criptografia do Vault. Quando a intenção for mudar a senha que criptografa os dados, faça a rotação pelo Ansible e atualize depois todas as fontes que fornecem essa senha. Para remover o cadastro padrão, confira primeiro o caminho e remova somente aquele arquivo: ```bash ./deploy configure-vault --show-path rm -- "$(./deploy configure-vault --show-path)" ``` Após a remoção, o deploy manual continua disponível. O modo da IA só funciona quando outra fonte estiver configurada. Para um arquivo personalizado, remova o caminho que você cadastrou e retire a referência correspondente do ambiente ou de `ansible.cfg`. Essa remoção não apaga o Vault criptografado do projeto. Em outra máquina, execute o cadastro novamente no checkout correspondente. Não envie o arquivo da senha pelo Git. A configuração é local ao usuário que executa o Ansible, um agente executado em container ou por outro usuário precisa receber sua própria fonte de senha e acesso SSH ao ambiente autorizado. ## Deploy manual e deploy pela IA ### Comando run `./deploy run` mantém a entrada manual: pede a senha no terminal, mesmo quando existe uma fonte externa. A senha digitada fica em um arquivo temporário com permissão `600` durante a execução, removido ao concluir ou cancelar normalmente. Um encerramento forçado por `SIGKILL` pode deixar esse temporário na máquina. `./deploy run --non-interactive` usa uma fonte configurada e não pede dados. Antes de conectar aos servidores, valida localmente a descriptografia de `ansible/group_vars/all/vault.yml`. Depois, testa os hosts e aplica o playbook. Senha incorreta, fonte ausente ou falha do cofre encerram a execução, sem recorrer a uma pergunta ou tentar outra fonte. | Opção | Tipo e padrão | Uso | | --- | --- | --- | | `--non-interactive` | booleano, desativado | habilita execução pela IA ou CI/CD | | `--vault-password-file ` | caminho opcional | arquivo ou script executável que fornece a senha | | `--vault-id @` | texto opcional, repetível | associa uma fonte a um ambiente | As opções de fonte em `run` exigem `--non-interactive`. A ordem de escolha é: fontes explícitas do comando, configuração nativa resolvida pelo Ansible, cadastro externo padrão deste checkout. A configuração nativa inclui `ANSIBLE_VAULT_PASSWORD_FILE`, `ANSIBLE_VAULT_IDENTITY_LIST` e `ansible.cfg`, com a precedência do próprio Ansible. Os IDs permitem usar mais de uma senha no mesmo Vault. Fontes com `@prompt` são recusadas nesse modo. O comando exige Python 3.10 ou superior e os executáveis `ansible-config`, `ansible-inventory`, `ansible` e `ansible-playbook`. O ambiente também precisa de acesso SSH por chave e das permissões de elevação usadas pelo playbook. O modo sem interação desativa as perguntas de SSH, sudo e Vault, não concede permissões adicionais. Uma configuração de cofre deve estar autenticada antes da execução. Scripts que fornecem senha não podem depender de perguntas. Nos cinco exemplos abaixo, confirme os hosts declarados no arquivo selecionado antes de publicar. O alvo padrão continua sendo `ansible/inventory.yml`: ```bash # Publicar manualmente, digitando a senha ./deploy run ``` ```bash # Permitir que a IA use o cadastro padrão já preparado ./deploy run --non-interactive ``` ```bash # Usar um arquivo externo informado nesta execução ./deploy run --non-interactive \ --vault-password-file "$HOME/.config/minha-app/producao/password" ``` ```bash # Usar uma fonte fornecida pela automação, como um script de cofre ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.local/bin/minha-app-vault-client" \ ./deploy run --non-interactive ``` ```bash # Selecionar hosts e identidade de staging explicitamente ANSIBLE_INVENTORY=ansible/inventory.staging.yml \ ./deploy run --non-interactive \ --vault-id "staging@$HOME/.config/minha-app/staging/password" ``` O script de cofre imprime somente a senha em stdout e retorna código `0`. Mensagens de diagnóstico pertencem a stderr e não devem conter segredos. O Ansible pode chamar o script várias vezes durante um deploy, por isso a fonte precisa aceitar consultas repetidas. No CI/CD, configure o secret pelo mecanismo do provedor e disponibilize um arquivo temporário protegido ou um script para consulta, limpe o temporário ao final do job. A execução mostra a tabela de conexões e o resultado do playbook. Código `0` confirma o sucesso dos comandos, a IA ainda deve conferir os serviços e a versão publicada. Falhas de configuração ou execução retornam `1`, argumentos inválidos retornam `2` e Ctrl+C retorna `130`. Sem fonte pronta, a IA informa a pendência e orienta o cadastro humano, sem pedir a senha na conversa. ## Cadastro de segredos com a mesma configuração ### Comando secrets `./deploy secrets` continua solicitando os valores ausentes da aplicação no terminal. Para a senha do Vault, reaproveita as mesmas fontes explícitas, nativas ou locais do modo automatizado. Sem nenhuma fonte configurada, pede também a senha. O comando não recebe valores secretos como argumentos. As opções `--vault-password-file ` e `--vault-id @` são opcionais, com os mesmos tipos e ordem de escolha de `run`. Não há `--non-interactive` para cadastrar valores: quando faltam campos, o terminal humano é obrigatório. Com todos os campos presentes, o comando encerra sem perguntas ou alterações. O arquivo `ansible/vault-fields.txt` contém os nomes desejados, um por linha, no formato `vault_` seguido de letras minúsculas, números ou sublinhados. O utilitário preserva campos existentes e publica o YAML atualizado somente depois de criptografar todos os novos valores. Uma falha intermediária mantém o arquivo original. É necessário ter `ansible-vault` instalado. ```bash # Cadastrar os campos faltantes usando a fonte já configurada ./deploy secrets ``` ```bash # Cadastrar com um arquivo externo específico ./deploy secrets \ --vault-password-file "$HOME/.config/minha-app/producao/password" ``` ```bash # Consultar o cofre por um script já autenticado ./deploy secrets \ --vault-password-file "$HOME/.local/bin/minha-app-vault-client" ``` ```bash # Identificar a senha usada para os novos valores ./deploy secrets \ --vault-id "producao@$HOME/.config/minha-app/producao/password" ``` ```bash # Reutilizar uma fonte definida no ambiente ANSIBLE_VAULT_PASSWORD_FILE="$HOME/.config/minha-app/producao/password" \ ./deploy secrets ``` Com várias identidades, configure também `vault_encrypt_identity` em `ansible.cfg`, ou `ANSIBLE_VAULT_ENCRYPT_IDENTITY`, para indicar qual delas criptografa os campos novos. O comando informa somente o caminho atualizado ou que todos os campos já existem. Os códigos de saída seguem o cadastro externo: `0` para sucesso, `1` para falha, `2` para argumentos inválidos e `130` para cancelamento. ## Atualizar scripts que já existem Atualizar a skill instalada não substitui os scripts do seu projeto. Peça à IA para comparar a versão atual de `deploy`, `ansible/create-vault.sh`, `ansible/check-hosts.py` e o novo `ansible/vault.py` com uma geração temporária, preservando suas personalizações. O scaffold recusa sobrescrever arquivos existentes. Depois da migração, valide os dois modos em um ambiente de teste e faça o cadastro externo na máquina que executará o deploy. ### Refinar uma entrada no Backlog com specsfy-02-backlog - URL: https://promovaweb.com/docs/specsfy/skills/backlog - Descrição: Como usar a skill specsfy-02-backlog para criar, aprofundar e atualizar um item em specs/backlog/ por meio de perguntas guiadas no projeto consumidor. Esta skill transforma uma entrada da Inbox em backlog refinável. Ela procura itens parecidos, registra o contexto inicial e, quando necessário, conduz uma pergunta prioritária por vez até produzir um brief pronto para especificar. ## Quando usar Use quando quiser organizar uma captura em `specs/inbox/`, avaliar uma oportunidade ou fechar lacunas sobre público, finalidade, regras, limites, privacidade, falhas e resultado esperado. Para apenas salvar sem perguntas, use `specsfy-01-inbox`. Não use para planejar tarefas, escrever testes ou iniciar código, pois um item de backlog ainda não passou pelos gates que autorizam essas etapas. ## Como descrever a tarefa Descreva a entrada e o destino esperado na mesma mensagem. A skill usará esse texto para criar um item reconhecível em `specs/backlog/`, sem tratá-lo como autorização para implementar. Por exemplo: ```text Use $specsfy-02-backlog para refinar esta entrada: permitir que a pessoa escolha o idioma da interface. ``` Quando houver itens parecidos em `specs/backlog/`, inclua a situação que diferencia esta entrada das demais. Isso ajuda a skill a atualizar o item correto e a manter visíveis as definições que continuam abertas: ```text Anote no backlog: clientes internacionais não entendem os e-mails atuais. Ainda não decidimos quais idiomas serão oferecidos. ``` ## Exemplo passo a passo 1. Você apresenta a entrada ou aponta o arquivo da Inbox. 2. O agente também pode ler a origem em `specs/inbox/`. 3. Ele procura itens semelhantes em `specs/backlog/` e nas specs. 4. Ele pergunta uma lacuna material por vez. 5. Você responde: “o problema afeta e-mails e a interface”. 6. A skill cria o item com `.specsfy/templates/custom/Backlog.md` quando presente ou com `.specsfy/templates/Backlog.md`: ```text specs/backlog/0003-idioma-da-interface.md ``` O item registra problema, público, resultado esperado e dúvidas abertas. Ele continua sendo backlog e não autoriza implementação. Quando a entrega incluir interface, o refinamento também pergunta somente o que ainda não foi dito sobre telas, fluxo de informação, menus e navegação principal, formulário, padrão de abertura da ação e disposição dos elementos. Você pode pedir alternativas para uma página, painel lateral ou modal. As respostas ficam registradas em texto para orientar a spec. Antes disso, o agente analisa o sistema existente. Rotas, telas, componentes, conteúdo, permissões, estados, testes e stack indicam o que deve ser preservado e evitam sugestões incompatíveis com o projeto. ## Como o ciclo termina O refinamento faz no máximo oito perguntas por área. Cada rodada traz exatamente uma pergunta numerada. Ela oferece três ou mais opções numeradas, `Escrever outra resposta`, `Gere outras opções` e `Avançar`. Ao escolher outras opções, o agente mantém a pergunta e apresenta sugestões diferentes. O agente reconsidera o pedido e as respostas antes de montar a próxima rodada. Ao chegar a oito perguntas, o agente resume o que foi confirmado e o que ficou aberto. Ele só continua se você pedir explicitamente mais perguntas e informar quantas quer responder. `Avançar` existe desde a primeira rodada. Na rodada seguinte, você escolhe se quer encerrar definitivamente as perguntas daquela área, responder depois ou voltar a responder agora. O encerramento fica registrado e é respeitado até você reabrir a área. O adiamento preserva os pontos para retomada. Quando ainda houver lacunas aplicáveis, a spec permanece `Status: Draft` e o `Definition Gate: Pending`. ## O que esperar - perguntas adaptadas ao caso, agrupadas em rodadas numeradas. - preservação das suas palavras. - indicação de duplicatas ou relações. - distinção entre fato, hipótese e escolha confirmada. - um brief pronto para especificar. - um caminho claro para retomar depois. - nenhuma `spec.md` criada automaticamente sem promoção. ## Erros comuns - transformar o backlog em uma especificação completa. - inventar solução técnica quando o problema ainda está aberto. - criar um segundo item sem procurar duplicatas. - tratar o item como aprovação para implementar. - responder categorias como um formulário fixo. - esconder uma dúvida para encurtar a conversa. ## Próximo passo Quando o backlog estiver claro, use [`specsfy-03-specify`](/docs/specsfy/skills/specify). Se ainda houver uma decisão material aberta, continue o ciclo nesta mesma skill. ### Descobrir informações do produto com specsfy-data-discovery - URL: https://promovaweb.com/docs/specsfy/skills/data-discovery - Descrição: Use specsfy-data-discovery para descrever dados do produto, sugerir formatos e registrar respostas confirmadas em DATABASE.md. Veja a entrevista. Use `$specsfy-data-discovery` (`specsfy-data-discovery`) quando uma jornada depender de informações que o sistema precisa lembrar, mostrar para alguém, alterar ou apagar. A conversa usa palavras do seu produto e salva apenas o que você confirmar em `.specsfy/DATABASE.md`. ## Quando usar Use durante o backlog, depois de uma Inbox, durante a descoberta de `MVP.md` ou antes de consolidar uma spec. A skill é útil quando ainda não está claro o que cada pedido, pessoa, atendimento ou outro item do produto precisa guardar. ## Como descrever a tarefa ```text Use $specsfy-data-discovery para entender o que nosso sistema precisa lembrar sobre cada reserva, quem consulta essas informações e quando elas deixam de ser necessárias. ``` ## Exemplo passo a passo ```text Inbox sobre reservas → conversa sobre informações a guardar → DATABASE.md → backlog refinado ``` O agente pode perguntar o que você precisa lembrar sobre uma reserva, quem pode consultar ou corrigir as informações e quando uma reserva deixa de valer. Você responde com a situação real do seu trabalho, sem precisar nomear partes internas do sistema. Depois, ele sugere a forma mais adequada para registrar cada informação, como texto curto, data, valor em dinheiro ou escolha entre opções. A sugestão só é salva depois que você confirmar que ela atende ao uso real. ## O que esperar Cada resposta confirmada aparece na seção `Informações a guardar confirmadas` de `.specsfy/DATABASE.md`. Ela informa para que a informação serve, o que deve ser lembrado, o formato sugerido, o que fica ligado, quem usa e quando muda ou sai do sistema. ## Erros comuns - tentar escolher a tecnologia antes de explicar a necessidade do produto, - tratar uma hipótese como informação confirmada, - copiar dados reais de clientes, senhas ou chaves para a conversa, - pular a conversa quando a jornada depende de informações guardadas. ## Próximo passo Volte ao `$specsfy-02-backlog` para concluir o refinamento ou ao `$specsfy-03-specify` para consolidar a fonte normativa da entrega. ### Entregar código no Specsfy com specsfy-07-implement - URL: https://promovaweb.com/docs/specsfy/skills/implement - Descrição: Como a skill specsfy-07-implement executa as tarefas aprovadas da spec, sempre a partir de um teste focal em RED antes de escrever qualquer código. Esta skill executa as tarefas aprovadas da spec em ordem. Ela altera produção somente quando existe um plano válido e um teste focal em RED. ## Quando usar Use para implementar a próxima tarefa pronta, continuar uma entrega ou concluir uma feature planejada. Não use para pular definição, planejamento ou testes. Quando uma autorização ou escolha for necessária, a skill apresenta exatamente uma pergunta numerada. Ela contém três ou mais respostas sugeridas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa ```text Use $specsfy-07-implement para executar a próxima tarefa pronta de specs//0004-recuperar-senha/spec.md. ``` Quando houver mais de uma tarefa pronta, indique o ID da tarefa que deve ser executada: ```text Implemente T003 da spec 0004 e valide a regressão. ``` ## Exemplo passo a passo 1. A skill confirma Definition Gate e Plan Gate aprovados. 2. Para uma interface, confere as telas, menus, formulário, ações e estados definidos. 3. Em React, carrega `$specsfy-specialist-react-ui-components`, localiza os componentes atuais e define quais serão reaproveitados ou adaptados antes de escrever JSX ou TSX. 4. Verifica a tarefa predecessora e o RED atual. 5. Em Laravel, confirma `.env.testing` separado do `.env` e passa o comando pelo `check_database_safety.mjs`. Sem `SAFE`, interrompe antes do teste. 6. Faz a menor mudança de produção, incluindo a tela e a interação previstas. 7. Executa o teste focal até obter GREEN. 8. Em uma tarefa `[MIGRATION]`, aplica o arquivo no banco de teste e consulta o estado das migrations. 9. Faz a revisão visual obrigatória quando a tarefa puder alterar a interface, mesmo sem pedido específico. Confere bordas, espaçamentos, margens, padding, tipografia, alinhamento, largura, overflow, foco, zoom e conteúdo curto ou longo nos viewports e estados aplicáveis. 10. Refatora sem alterar o comportamento. 11. Executa a regressão e atualiza os registros da tarefa: ```text T003 [x] Implementar solicitação sem revelar existência do cadastro Teste focal: passou Revisão visual: Não aplicável; a tarefa altera somente a regra de serviço. Regressão: passou ``` O checklist normativo da tarefa segue `PREP`, `EXECUTE`, `VERIFY`, `VISUAL`, `EVIDENCE` e `IMPROVE`. O item `VISUAL` registra a inspeção da interface ou o motivo concreto para sua não aplicação. Para `[MIGRATION]`, o comentário `specsfy:evidence` precisa listar o arquivo criado, o comando de aplicação e a consulta de estado, todos com saída zero. `verify_evidence.mjs` confere os três elementos. A existência do model ou do teste não substitui essa comprovação. Durante o aceite final, `--delivery` também recusa qualquer tarefa `[MIGRATION]` que permaneça aberta. Depois de cada tarefa de código, a skill chama o documentador do projeto consumidor. A execução só continua quando `docs/` estiver atualizado. ## O que esperar - uma tarefa por vez. - mudanças limitadas ao escopo aprovado. - testes focais e regressão. - documentação aplicável atualizada. - status e checkboxes comprovados por evidência. ## Erros comuns - implementar com gate pendente. - aceitar um RED causado por dependência ausente. - ampliar o escopo sem atualizar a spec. - implementar um CRUD como API sem os menus, as telas e o formulário aprovados. - marcar conclusão sem regressão. - marcar uma tarefa de banco sem criar, aplicar e conferir a migration. - rodar teste no banco do `.env` ou aceitar um comando que recrie o banco. - deixar `docs/`, `PROJECT.md` ou os arquivos `.specsfy/` incompatíveis com o código alterado. ## Próximo passo Continue com a próxima tarefa ou consulte [`specsfy-progress`](/docs/specsfy/skills/progress). Se surgir uma necessidade nova, use [`specsfy-update-spec`](/docs/specsfy/skills/update-spec). ### Capturar entradas na Inbox com a skill specsfy-01-inbox - URL: https://promovaweb.com/docs/specsfy/skills/inbox - Descrição: Como usar a skill specsfy-01-inbox para registrar uma entrada, oportunidade ou necessidade sem interromper o fluxo com perguntas nem iniciar código. Esta skill funciona como uma caixa de entrada: recebe seu texto, guarda o original e organiza uma primeira leitura sem interromper você com perguntas. ## Quando usar Use quando quiser anotar uma entrada, oportunidade, necessidade ou pensamento para retomar depois. O arquivo fica em `specs/inbox/`. Não use para refinar prioridade, decidir requisitos ou iniciar implementação. Esses trabalhos pertencem às etapas seguintes. ## Como descrever a tarefa ```text Use $specsfy-01-inbox para capturar: seria útil avisar clientes quando uma entrega atrasar, talvez por e-mail. ``` Se preferir uma instrução curta, escreva “guarde na Inbox” e inclua o texto original na mesma mensagem. A skill organiza a captura sem exigir um formato prévio. ## Exemplo passo a passo 1. Você envia o texto livre. 2. O agente preserva o texto original. 3. Sem fazer perguntas, ele separa o resumo, o problema ou a oportunidade, as pessoas afetadas, o resultado esperado, as dependências e os pontos que ainda precisam de revisão. 4. Ele cria um nome com data, hora e slug. 5. Ele informa o caminho criado e encerra a captura. ## O que esperar ```text specs/inbox/2026-07-28-143205-avisar-clientes-sobre-atrasos.md ``` O arquivo diferencia o que você declarou, o que foi inferido e o que ainda precisa ser revisto. Nenhum backlog, spec, tarefa ou código é criado. Os metadados incluem horário da captura, origem, slug, status, hash do texto original e links futuros para backlog ou spec. ## Erros comuns - esperar que a captura faça perguntas ou complete definições ausentes. - tratar a análise inicial como requisito aprovado. - implementar diretamente a partir de `specs/inbox/`. - editar o texto original em vez de registrar uma evolução no backlog. - procurar o template dentro da skill: o padrão vive em `.specsfy/templates/Inbox.md`, e uma personalização homônima em `.specsfy/templates/custom/` tem precedência. ## Próximo passo Deixe a entrada guardada ou use [`specsfy-02-backlog`](/docs/specsfy/skills/backlog) quando quiser refiná-la. ### Conversar sobre uma spec com a skill specsfy-interviewer - URL: https://promovaweb.com/docs/specsfy/skills/interviewer - Descrição: Use specsfy-interviewer para registrar respostas confirmadas, resolver lacunas e recalibrar Effort sem aprovar gates ou alterar o estado da spec. `specsfy-interviewer` ajuda você a resolver lacunas que podem mudar a próxima etapa da spec. Ele lê o estado atual, apresenta exatamente uma pergunta numerada por rodada e só registra respostas que você confirmou. A pergunta traz três ou mais opções numeradas, `Escrever outra resposta`, `Gere outras opções` e `Avançar`. Depois de avançar, você escolhe entre encerrar definitivamente as perguntas da área, responder depois ou retomar agora. A skill registra a escolha e respeita o encerramento até uma reabertura explícita. ## Quando usar Use durante `draft`, `defined`, `planned`, `in-progress` ou `review` quando uma escolha de produto, escopo, dependência, teste ou aceite ainda estiver aberta. A Inbox não usa entrevistador: ela preserva sua mensagem sem perguntas. ## Como descrever a tarefa Peça “converse comigo sobre a spec de login social antes de montar as tarefas” ou informe o ID da spec e a dúvida que precisa resolver. ## Exemplo passo a passo O entrevistador lê a spec e agrupa os pontos que impedem o plano, como o provedor de identidade, o comportamento quando a conta já existe e o método de recuperação. Você pode escolher uma opção, escrever outra resposta ou avançar. ```text specs/planned/0042-login-social/spec.md ``` Depois de cada resposta, ele verifica se mudou a estimativa de execução. Se necessário, registra `Effort`, data e justificativa com o comando do CLI. ## O que esperar Effort vai de 1 a 10 e mede a capacidade de execução necessária, não duração: - 1–2: alteração atômica, - 3–6: trabalho local ou integração conhecida, - 7–8: migração ou integração transversal, - 9–10: arquitetura ou incerteza que pede revisão humana frequente. O histórico fica na própria `spec.md`, para que você entenda por que a estimativa mudou. ## Erros comuns - usar o entrevistador para capturar uma Inbox, que não recebe perguntas, - esperar que ele aprove um gate ou mova a pasta sem a skill da etapa, - usar Effort como prazo ou vinculá-lo a um modelo específico. ## Próximo passo O entrevistador não aprova gates, implementa código ou move a spec. Ao fechar a lacuna, ele entrega o trabalho à skill responsável pela fase atual. Quando ClickUpfy estiver instalado e houver uma tarefa vinculada, essa skill também atualiza a projeção remota. ### Skills base do Specsfy: visão geral do fluxo completo - URL: https://promovaweb.com/docs/specsfy/skills/introducao - Descrição: Visão geral das skills base do Specsfy e como escolher a etapa certa para cada situação, do registro de uma ideia até a implementação final feita. As skills base dividem o método por responsabilidade. Você pode chamar uma delas pelo nome ou explicar o resultado esperado. O agente lê o estado da spec, seleciona a etapa responsável e anuncia cada transição necessária. ## Nomes exibidos Os comandos técnicos continuam, por exemplo, como `$specsfy-02-backlog`. Na interface, as sete etapas centrais aparecem como `Specsfy - 01 - Inbox` até `Specsfy - 07 - Implementar`. As skills adicionais usam `Specsfy - Nome`, e as técnicas usam `Specsfy - Especialista - Nome`. ## Como responder às perguntas Toda skill que precisa perguntar segue o mesmo formato desde a primeira rodada: 1. apresenta uma pergunta com o rótulo `Pergunta 1` e espera sua resposta, 2. oferece pelo menos três respostas sugeridas e numeradas abaixo dela, 3. acrescenta `Escrever outra resposta` para você informar seu próprio texto, 4. acrescenta `Gere outras opções` para mostrar alternativas diferentes à mesma pergunta, 5. acrescenta `Avançar` para abrir a confirmação de encerramento da área, adiamento ou retomada imediata. Você pode responder com combinações como `1.2` ou `1.4: meu texto`. O número da opção é convertido no texto completo antes de gerar qualquer contexto. Ao escolher `Avançar`, a rodada seguinte pergunta se você quer encerrar definitivamente as perguntas daquela área, responder depois ou voltar a responder agora. Se encerrar, a skill registra sua escolha e não pergunta sobre a área novamente, a menos que você a reabra. Se adiar, os pontos ficam registrados para retomada. Nenhuma das escolhas inventa uma resposta ou aprova uma etapa incompleta. Inbox, progresso, auxiliares de stack e banco e documentador não conduzem entrevista. Essas skills registram ou projetam o que já existe e encaminham qualquer pergunta para uma etapa conversacional. | Etapa | Skill | Resultado principal | | --- | --- | --- | | capturar sem perguntas | [`specsfy-01-inbox`](/docs/specsfy/skills/inbox) | arquivo em `specs/inbox/` | | refinar uma entrada e aprofundar definições | [`specsfy-02-backlog`](/docs/specsfy/skills/backlog) | item em `specs/backlog/` e brief na conversa | | criar a fonte única | [`specsfy-03-specify`](/docs/specsfy/skills/specify) | `spec.md` | | revisar definição | [`specsfy-04-validate`](/docs/specsfy/skills/validate) | Definition Gate confiável | | decompor o plano | [`specsfy-05-tasks`](/docs/specsfy/skills/tasks) | tarefas dentro da spec | | preparar e executar testes | [`specsfy-06-tdd-bdd`](/docs/specsfy/skills/tdd-bdd) | RED/GREEN rastreável | | produzir a mudança | [`specsfy-07-implement`](/docs/specsfy/skills/implement) | código, testes e evidência | | incorporar mudança posterior | [`specsfy-update-spec`](/docs/specsfy/skills/update-spec) | spec atualizada e gates reabertos | | consultar o estado | [`specsfy-progress`](/docs/specsfy/skills/progress) | relatório somente leitura | | conversar conforme a fase | [`specsfy-interviewer`](/docs/specsfy/skills/interviewer) | respostas confirmadas e Effort recalibrado | | definir o MVP e seus marcos | [`specsfy-mvp-milestone-interviewer`](/docs/specsfy/skills/mvp-milestone-interviewer) | milestones aprováveis do MVP | | descobrir o que o sistema precisa guardar | [`specsfy-data-discovery`](/docs/specsfy/skills/data-discovery) | respostas confirmadas em `DATABASE.md` | | planejar a evolução | [`specsfy-roadmap-milestone-interviewer`](/docs/specsfy/skills/roadmap-milestone-interviewer) | milestones pós-MVP | | manter a projeção | [`specsfy-milestone-governor`](/docs/specsfy/skills/milestone-governor) | `specs.md` e progresso derivado | ## Encontre a skill pelo estado do trabalho Uma anotação que precisa ser preservada vai para `specsfy-01-inbox`. Quando você quiser comparar essa ideia com itens existentes e esclarecer o mínimo necessário, `specsfy-02-backlog` cria ou atualiza o arquivo numerado e aprofunda as definições que mudam o comportamento e entrega um brief na conversa. Com a intenção de criar uma entrega confirmada, `specsfy-03-specify` monta a `spec.md` e `specsfy-04-validate` comprova o Ato I. A skill `specsfy-05-tasks` organiza o plano, chama `specsfy-06-tdd-bdd` para materializar os testes e só aprova o Plan Gate depois de um RED válido. `specsfy-07-implement` executa as tarefas com evidência e documentação atualizada. Uma necessidade surgida depois da definição retorna à mesma spec por `specsfy-update-spec`. Para apenas consultar gates, tarefas e o próximo trabalho sem alterar arquivos, use `specsfy-progress`. Quando uma lacuna puder alterar a próxima etapa, chame `specsfy-interviewer`. Ele conversa com a spec sem substituir a skill que valida, planeja, implementa ou conclui. Para organizar um produto inteiro, comece pelo `specsfy-mvp-milestone-interviewer`. Depois do aceite do MVP, use o `specsfy-roadmap-milestone-interviewer`. O `specsfy-milestone-governor` mantém o mapa derivado de specs e backlog. O guia [Milestones](/docs/specsfy/milestones) explica arquivos, relações e sincronização. Quando uma conversa revelar informações que o sistema precisa lembrar, use `specsfy-data-discovery`. A skill pergunta em linguagem simples e mantém o registro em `.specsfy/DATABASE.md` antes de o backlog ou a spec avançar. Volte ao [guia completo](/docs/specsfy/introducao) ou leia [como a metodologia funciona](/docs/specsfy/metodo). ### Governar milestones com a skill specsfy-milestone-governor - URL: https://promovaweb.com/docs/specsfy/skills/milestone-governor - Descrição: Use specsfy-milestone-governor para projetar o progresso dos milestones, encontrar vínculos ausentes e manter somente blocos derivados do projeto. Use `$specsfy-milestone-governor` (`specsfy-milestone-governor`) para revisar relações entre milestones, specs e backlog. Ele executa a projeção derivada, sugere vínculos ausentes e mantém `specs.md` atualizado sem substituir a escrita humana dos marcos. ## Quando usar Use depois de criar, alterar ou concluir specs vinculadas a milestones. Se uma relação precisar de confirmação, a skill apresenta exatamente uma pergunta numerada. Ela contém três ou mais sugestões, `Escrever outra resposta` `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa Peça: “revise os milestones do projeto e sincronize o mapa”. ## Exemplo passo a passo ```text Specs e backlog vinculados → sync → specs.md e progresso dos marcos atualizados ``` ## O que esperar A skill mostra relações ausentes e atualiza somente blocos gerados. ## Erros comuns - tratar percentual de tarefas como aceite do marco, - esperar que a skill escreva uma condição de saída sem confirmação. ## Próximo passo A condição de saída continua dependendo de validação confirmada. Veja [Milestones](/docs/specsfy/milestones) para o comando e o modelo de arquivos. ### Explorar o MVP com specsfy-mvp-milestone-interviewer - URL: https://promovaweb.com/docs/specsfy/skills/mvp-milestone-interviewer - Descrição: Use specsfy-mvp-milestone-interviewer para importar MVP.md como Milestone 1.0, com BRAND.md como contexto e conversa em Inboxes antes do backlog. Consulte. Use `$specsfy-mvp-milestone-interviewer` (`specsfy-mvp-milestone-interviewer`) para explorar o menor produto utilizável sem perder o caminho da conversa. A skill lê `MVP.md` e `BRAND.md` da raiz do projeto. Quando o projeto é um submódulo Git e esses arquivos não estão nele, ela os procura na raiz do Hub que contém o submódulo. A importação preserva o contexto comercial e de produto no próprio `MVP.md`, somente requisitos de desenvolvimento entram no Specsfy. Quando você escolher uma opção pelo número, a captura registra o texto da opção escolhida, e não somente `1`, `2` ou `3`. ## Quando usar Use antes de criar um conjunto de specs para um produto novo ou quando o MVP ainda não tem uma jornada confirmada. Se `MVP.md` existir, a skill o importa como `specs/milestones/M01.md` e cria backlog e spec somente para os temas que descrevem algo a ser desenvolvido. Ela não cria Inboxes nessa importação e não copia visão, público, negócio, métricas ou posicionamento para `specs/`. Nenhum arquivo existente é substituído. Um arquivo no projeto tem prioridade. O Hub só entra na busca quando o projeto é um submódulo Git e o arquivo local está ausente. Assim, um `MVP.md` ou `BRAND.md` específico do projeto não é trocado pelo contexto compartilhado. Cada rodada traz uma pergunta numerada. Abaixo dela, você recebe três ou mais sugestões, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. Quando a jornada indicar que o sistema precisa guardar informações, a skill pergunta, uma por vez, sobre cada informação ausente ou ambígua durante a entrevista do backlog correspondente. São no máximo oito perguntas por área, para continuar, você precisa pedir mais e indicar quantas deseja responder. As respostas confirmadas ficam em `.specsfy/DATABASE.md`. ## Como descrever a tarefa Peça: “use o entrevistador de MVP para organizar os marcos do meu sistema de leads”. ## Exemplo passo a passo ```text MVP.md → filtro de desenvolvimento → M01 + backlogs e specs Draft → milestones sincronizadas ``` ## O que esperar O importador cria `M01` e só cria backlog e spec Draft para temas que representam capacidades ou comportamentos a serem desenvolvidos. Visão, público, princípios, modelo de negócio e contexto ficam somente no `MVP.md` e não viram trabalho de desenvolvimento nem Inbox. Antes de perguntar, ele aplica defaults seguros quando encontra um rótulo explícito ou uma formulação inequívoca, registra o campo preenchido, a base usada e a lacuna que ficou aberta. Cada backlog também recebe o trecho que o originou como registro confirmado. A própria skill carrega `$specsfy-02-backlog`, que reaproveita os defaults e só pergunta por lacunas, ambiguidades, contradições ou escolhas reais. Ela chama `$specsfy-data-discovery` quando houver dados ambíguos e retorna à fila até entrevistar todos. Depois sincroniza os milestones e só chama `$specsfy-03-specify` para gerar uma spec Draft para cada backlog. Os campos sem resposta confiável ficam marcados como `Pendente`. A seção 10 de cada spec Draft também registra menus e navegação principal, usando o que o MVP informar ou `Pendente` quando essa parte não existir. A skill não implementa código, não executa tarefas e não passa os gates durante a conversa. ## Erros comuns - pedir tarefas técnicas antes de entrevistar todos os backlogs gerados, - misturar uma hipótese da conversa com o texto que foi registrado, - esperar que a importação implemente código ou aprove uma spec com lacunas. ## Próximo passo Leia [Milestones](/docs/specsfy/milestones) para conhecer arquivos e sincronização. ### Consultar o estado do Specsfy com specsfy-progress - URL: https://promovaweb.com/docs/specsfy/skills/progress - Descrição: Como a skill specsfy-progress lê todas as specs e apresenta gates, tarefas, checklists e próximo trabalho, sem alterar nenhum estado do projeto atual. Esta skill lê todas as specs e apresenta uma visão geral de gates, tarefas, checklists, falhas que impedem avanço e próximo trabalho. Ela não altera nenhum estado. ## Quando usar Use para saber quanto falta, qual falha impede uma entrega, qual tarefa está pronta ou quais specs foram concluídas. ## Como descrever a tarefa Para receber uma síntese na conversa, descreva o projeto que deseja consultar: ```text Use $specsfy-progress para mostrar o progresso do projeto. ``` No terminal, use o CLI para obter a mesma leitura das fontes canônicas: ```text specsfy progress --project . ``` ## Exemplo passo a passo 1. A skill lê `specs//*/spec.md`. 2. Calcula o estado a partir de gates e checkboxes. 3. Não consulta um relatório paralelo. 4. Apresenta: ```text Specs: 2 Complete: 1 Implementing: 1 Tarefas: 7 de 10 concluídas Próximo trabalho: T004 da spec 0004-recuperar-senha Pendências impeditivas: nenhuma ``` Se os metadados estiverem incoerentes, o relatório mostra a pendência em vez de inventar um percentual confiável. ## O que esperar - leitura somente das fontes canônicas. - totais de specs e tarefas. - gates pendentes. - falhas impeditivas e próximo trabalho. - saída humana ou JSON pelo CLI. ## Erros comuns - alterar checkboxes durante a consulta. - manter um segundo arquivo de progresso. - calcular conclusão só pelo número de arquivos. - esconder spec inválida do relatório. - confundir progresso com autorização para implementar. ## Próximo passo Abra a página da skill indicada pelo próximo trabalho. Para acompanhar continuamente no terminal, use: ```text specsfy progress --project . --watch ``` ### Planejar o roadmap com specsfy-roadmap-milestone-interviewer - URL: https://promovaweb.com/docs/specsfy/skills/roadmap-milestone-interviewer - Descrição: Use specsfy-roadmap-milestone-interviewer depois do MVP para organizar milestones futuras, dependências e capacidades sem reabrir o núcleo aceito. Use `$specsfy-roadmap-milestone-interviewer` (`specsfy-roadmap-milestone-interviewer`) depois que o MVP estiver aceito. Ele entrevista você sobre o que vem depois e propõe marcos de evolução sem alterar silenciosamente a jornada central já aprovada. ## Quando usar Use quando o MVP já possui objetivo e condição de saída confirmados. Cada rodada traz uma pergunta numerada. Abaixo dela, você recebe três ou mais sugestões, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa Peça: “planeje o roadmap depois do MVP com milestones”. ## Exemplo passo a passo ```text MVP aceito → entrevista de evolução → milestones pós-MVP → specs candidatas ``` ## O que esperar Você recebe uma sequência recomendada, dependências e hipóteses que ainda dependem de uso real. ## Erros comuns - usar o roadmap para mudar o núcleo do MVP sem confirmação, - chamar uma feature isolada de milestone. ## Próximo passo Mudanças no núcleo seguem por `$specsfy-update-spec`. Consulte [Milestones](/docs/specsfy/milestones) para revisar a estrutura resultante. ### Criar a especificação no Specsfy com specsfy-03-specify - URL: https://promovaweb.com/docs/specsfy/skills/specify - Descrição: Como usar a skill specsfy-03-specify para criar a fonte única da entrega no arquivo spec.md a partir de um backlog refinado no projeto consumidor atual. Esta skill cria a fonte única da entrega no arquivo `spec.md`. Ao abrir esse arquivo, você encontra a descoberta usada como base para os requisitos, os comportamentos que orientam o plano e a ligação entre tarefas, testes e evidências. Essa concentração evita que arquivos paralelos apresentem versões diferentes da mesma entrega. ## Quando usar Use para promover um backlog refinado ou criar uma spec nova ainda em estado Draft. Para mudar uma spec que já foi definida, use update-spec. Se precisar confirmar arquivo, síntese ou próximo passo, a skill apresenta uma pergunta numerada. Ela inclui três ou mais respostas sugeridas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa Quando a ideia já tiver sido refinada no backlog, informe o caminho do item: ```text Use $specsfy-03-specify para promover specs/backlog/0003-idioma-da-interface.md. ``` Quando o refinamento do backlog tiver produzido um brief na conversa, peça a criação com base nas definições registradas: ```text Use $specsfy-03-specify para criar uma especificação para recuperação de senha com base nas definições desta conversa. ``` ## Exemplo passo a passo 1. A skill confirma a raiz do projeto e o próximo número disponível. 2. Ela lê as instruções, o brief e as evidências necessárias. 3. Cria o pacote: ```text specs//0004-recuperar-senha/ ├── spec.md └── research/ # somente quando houver pesquisa externa ``` Em seguida, ela preenche o Ato I com requisitos e cenários, mantém as escolhas ainda abertas claramente marcadas e executa os validadores. Um resultado incompleto permanece pendente em vez de receber uma aprovação sem evidência. Quando falta uma decisão material, a skill entrega a conversa ao ciclo de refinamento do backlog e retoma depois. Se você escolher `avançar`, a spec pode registrar o brief parcial, mas permanece Draft com o Definition Gate pendente. A mesma o refinamento não é reaberto imediatamente nessa retomada. Os arquivos em `research/` apoiam as escolhas registradas, mas nunca substituem o texto normativo de `spec.md`. Quando houver divergência, a entrega e seus validadores devem seguir a spec. ## O que esperar - formato `Specsfy/2.0`. - IDs rastreáveis para histórias, requisitos e condições de aceite. - cenários que cobrem sucesso, variação e falha. - para interfaces, telas, fluxo de informação, menus e navegação principal, formulários, composição, estados e acessibilidade na seção 10. - a stack e as telas atuais analisadas, com o que será preservado e alterado. - uma única fonte normativa. - status Draft ou Defined conforme a evidência real. ## Erros comuns - criar `plan.md`, `tasks.md` ou `research.md`. - copiar uma fonte externa como requisito sem confirmação. - aprovar gates com campos incompletos. - misturar várias entregas grandes na mesma spec. - descrever um CRUD apenas com API, serviço ou banco, sem a experiência que a pessoa precisa usar. ## Próximo passo Use [`specsfy-04-validate`](/docs/specsfy/skills/validate) para provar que a definição está pronta. Se uma escolha importante faltar, a transição volta para [`specsfy-02-backlog`](/docs/specsfy/skills/backlog). ### Planejar as tarefas no Specsfy com specsfy-05-tasks - URL: https://promovaweb.com/docs/specsfy/skills/tasks - Descrição: Como a skill specsfy-05-tasks transforma uma definição aprovada em tarefas pequenas, ordenadas e verificáveis dentro da spec.md do projeto atual. Esta skill transforma uma definição aprovada em tarefas pequenas, ordenadas e verificáveis. As tarefas ficam na seção 14 da própria `spec.md`. ## Quando usar Use depois do Definition Gate ou quando uma alteração exigir replanejamento. Não use para escrever código nem para marcar uma tarefa como concluída. Se houver mais de um recorte, ordem ou próximo passo possível, a skill reúne a consulta em uma pergunta numerada. Ela oferece três ou mais sugestões, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa ```text Use $specsfy-05-tasks em specs//0004-recuperar-senha/spec.md. ``` Se a spec contiver mais de uma entrega observável, indique a fatia vertical que deve ser planejada primeiro: ```text Prepare as tarefas da primeira fatia vertical da spec 0004. ``` ## Exemplo passo a passo 1. A skill lê a spec e o código existente. 2. Identifica a menor entrega observável: solicitar o link. 3. Liga cada tarefa aos requisitos e às condições de aceite correspondentes. 4. Faz cada tarefa de produção depender de um teste com RED registrado. 5. Registra: ```text T001 [ ] Criar caso TDD para solicitação válida — cobre AC-001 T002 [ ] Criar caso TDD para e-mail desconhecido — cobre AC-002 T003 [ ] Implementar solicitação sem revelar existência do cadastro ``` Quando a spec declara uma interface, o plano inclui tarefas para telas, menus, navegação, formulário, ações e seus testes de navegação, validação e recuperação de erro. Uma tarefa de API ou persistência não substitui essas tarefas. Quando qualquer tarefa cria ou altera schema, tabela, coluna, índice, relação ou model persistente, o plano inclui uma tarefa separada com as tags `[CODE] [MIGRATION]`. Ela aponta para o arquivo versionado e fica entre os testes TDD e o código que passa a usar a nova estrutura. ```text T004 [CODE] [MIGRATION] Criar tabela em database/migrations/2026_09_04_120000_create_clients_table.php ``` O `VERIFY` registra um comando que aplica a migration no banco de teste e outro que consulta seu estado. Em Laravel, por exemplo: ```bash php artisan migrate --env=testing php artisan migrate:status --env=testing ``` Sem a tarefa `[MIGRATION]`, o validador recusa um plano que crie ou altere a estrutura do banco. Consultar ou usar uma tabela existente não exige migration por si só. Essas tarefas ficam em uma `Fase de interface` dedicada. Há uma tarefa por tela registrada, usando os componentes e a stack já existentes no projeto. Em projetos React, o `PREP` de cada tarefa carrega `$specsfy-specialist-react-ui-components` antes da escrita de JSX ou TSX. Se o especialista estiver ausente, o fluxo retorna ao setup para instalar a skill detectada antes de liberar o código da tela. Depois de registrar as tarefas, a skill chama `specsfy-06-tdd-bdd` para materializar os testes. O Plan Gate só pode ser aprovado quando todos os predecessores exigidos possuem RED válido. ## O que esperar - tarefas pequenas e com resultado verificável. - ordem explícita de dependência. - testes com RED como predecessores do código. - caminhos e comandos reais do projeto. - migration explícita para toda tarefa ligada ao banco. - tarefas mantidas dentro da fonte única. ## Erros comuns - criar `tasks.md`. - escrever tarefas vagas como “fazer backend”. - colocar várias mudanças independentes em uma tarefa. - planejar sem inspecionar a stack real. - marcar uma tarefa pronta sem evidência. ## Próximo passo Use [`specsfy-06-tdd-bdd`](/docs/specsfy/skills/tdd-bdd) em modo `prepare` para materializar o próximo teste e observar RED. ### Preparar os testes no Specsfy com specsfy-06-tdd-bdd - URL: https://promovaweb.com/docs/specsfy/skills/tdd-bdd - Descrição: Como a skill specsfy-06-tdd-bdd transforma cenários da spec em testes executáveis e produz o RED que autoriza o início da implementação real do código. Esta skill usa os cenários da spec para criar testes executáveis. Ela mantém a rastreabilidade entre o comportamento descrito e a prova no código. ## Quando usar Use para preparar o RED que autoriza a implementação, executar um ciclo RED–GREEN–REFACTOR ou verificar testes e rastreabilidade. Se precisar escolher runner, comando ou caso focal, a skill apresenta exatamente uma pergunta numerada. Ela contém três ou mais respostas sugeridas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa Para preparar o próximo teste focal e produzir a evidência de RED, use o modo `prepare`: ```text Use $specsfy-06-tdd-bdd em modo prepare para specs//0004-recuperar-senha/spec.md. ``` Para conferir os testes e a rastreabilidade de uma entrega existente, use o modo `verify`: ```text Use $specsfy-06-tdd-bdd em modo verify na spec 0004. ``` ## Exemplo passo a passo 1. A skill seleciona a próxima condição de aceite. 2. Encontra o runner real do projeto. 3. Em Laravel, exige `.env.testing` com destino explícito e separado do `.env`. 4. Confere o comando com `check_database_safety.mjs`. Se o resultado não for `SAFE`, não executa nenhum teste. 5. Cria um teste com marcador de rastreabilidade. 6. Executa somente o teste focal. 7. Confirma: ```text RED válido: o teste falhou porque a recuperação ainda não foi implementada. Caso: TDD-AC-001 ``` Depois da implementação, a skill repete o teste focal e executa a regressão para confirmar que o comportamento ficou GREEN sem quebrar o restante. O bloco Gherkin da spec é uma referência legível. A prova automatizada fica na suíte normal do projeto, não em um arquivo `.feature` nem em uma segunda suíte. ## O que esperar - caso de teste ligado a uma condição de aceite da spec. - comando e resultado registrados. - distinção entre falha esperada e problema de ambiente. - cobertura de sucesso, regra e limite. - regressão depois do GREEN. ## Erros comuns - chamar erro de configuração de RED. - escrever produção no modo `prepare`. - criar testes que não correspondem às condições de aceite. - considerar o Gherkin sozinho como teste executado. - aprovar o plano sem prova focal. - executar teste para descobrir se a conexão está correta. - recriar ou limpar todo o banco para preparar a suíte. ## Próximo passo Com RED válido e tarefa pronta, use [`specsfy-07-implement`](/docs/specsfy/skills/implement). Para apenas reorganizar as tarefas, volte a [`specsfy-05-tasks`](/docs/specsfy/skills/tasks). ### Incorporar mudanças no Specsfy com specsfy-update-spec - URL: https://promovaweb.com/docs/specsfy/skills/update-spec - Descrição: Como a skill specsfy-update-spec atualiza uma spec já definida, planejada ou concluída, reabrindo apenas os atos cujas provas perderam validade hoje. Esta skill atualiza uma spec que já foi definida, planejada, iniciada ou concluída. A nova necessidade entra na mesma fonte, e somente os atos cujas provas perderam validade são reabertos. ## Quando usar Use quando uma entrega existente precisar incorporar algo esquecido, adicionar ou remover comportamento, corrigir uma definição ou mudar uma regra já registrada. Para criar a primeira versão da spec, use specify. A update-spec depende de uma fonte existente para comparar a nova instrução com requisitos, testes, tarefas e gates já registrados. ## Como descrever a tarefa ```text Use $specsfy-update-spec para adicionar expiração de 30 minutos à specs//0004-recuperar-senha/spec.md. ``` Para remover um comportamento, identifique a exigência e o arquivo `spec.md` que deve ser revisto. Assim, a skill consegue localizar testes e tarefas que ficariam incompatíveis com a remoção: ```text Remova a exigência de SMS da spec 0004 e ajuste o trabalho afetado. ``` ## Exemplo passo a passo 1. A skill preserva literalmente a nova instrução. 2. Lê requisitos, testes, tarefas, gates e evidências atuais. 3. Classifica a mudança: ```text Mudança de definição: altera comportamento e condição de aceite. Atos reabertos: I, II e III. ``` Com o impacto identificado, a skill atualiza a mesma `spec.md` e invalida somente os gates que perderam validade. Depois, retoma refinamento, validação, tarefas, testes e implementação na ordem necessária. A nova evidência é registrada sem apagar o histórico relevante. Se a mudança abrir escolhas materiais, o refinamento do backlog apresenta exatamente uma pergunta numerada por rodada e reavalia o contexto após a resposta. A pergunta oferece três ou mais opções numeradas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. O ciclo faz no máximo oito perguntas por área. O avanço abre uma confirmação para encerrar definitivamente as perguntas daquela área, responder depois ou retomar agora. O encerramento é respeitado até você reabrir a área. O adiamento preserva os pontos e mantém o Ato I reaberto, sem iniciar outra vez o mesmo ciclo nessa retomada. ## O que esperar - instrução original preservada. - impacto explicado na retomada. - nenhuma spec duplicada. - trabalho já válido mantido. - transições automáticas até o estado coerente. ## Erros comuns - editar apenas o código e deixar a spec antiga. - reabrir todos os gates sem analisar impacto. - manter teste ou tarefa que contradiz a nova instrução. - esconder a mudança em notas soltas. - criar uma segunda especificação para a mesma entrega. ## Próximo passo A própria skill encaminha para a etapa reaberta. Depois da atualização, use [`specsfy-progress`](/docs/specsfy/skills/progress) para revisar o estado geral. ### Validar a definição no Specsfy com specsfy-04-validate - URL: https://promovaweb.com/docs/specsfy/skills/validate - Descrição: Como usar a skill specsfy-04-validate para revisar a spec como se fosse código em linguagem natural e aprovar o Definition Gate do projeto atual. Esta skill revisa a spec como código em linguagem natural. Primeiro verifica o formato. Depois avalia clareza, completude, consistência e possibilidade de teste. ## Quando usar Use para comprovar o Ato I ou quando uma mudança exigir nova validação da definição. Também é útil para auditar uma spec sem alterar sua intenção. Quando a validação depender de uma escolha sua, a rodada traz exatamente uma pergunta numerada. Ela oferece três ou mais respostas sugeridas, `Escrever outra resposta`, `Gere outras opções` e `Avançar` desde a primeira rodada. ## Como descrever a tarefa ```text Use $specsfy-04-validate em specs//0004-recuperar-senha/spec.md. ``` ## Exemplo passo a passo 1. A skill confirma o caminho e o formato `Specsfy/2.0`. 2. Verifica se os requisitos possuem exemplos suficientes. 3. Encontra uma lacuna: “a validade do link não foi decidida”. 4. Retorna para o refinamento do backlog e registra a validade de 30 minutos. 5. Executa novamente os validadores. 6. Atualiza a seção de gates: ```text Definition Gate: Passed Status: Defined ``` Quando o plano inclui uma tarefa `[MIGRATION]`, a validação final também confere a entrega registrada pela implementação. A tarefa só pode terminar quando a comprovação relaciona o arquivo versionado da migration, o comando que a aplicou no banco de teste e o comando que consultou o estado depois da aplicação. Uma tarefa `[MIGRATION]` ainda aberta também impede o Delivery Gate. Uma falha de parser, fixture ou ambiente não serve como prova de requisito ausente. ## O que esperar - problemas apontados com localização e motivo. - nenhuma aprovação baseada em suposição. - verificação das evidências externas citadas. - conferência da aplicação das migrations previstas no plano. - retorno automático à etapa que pode resolver a lacuna. - gate aprovado somente após nova validação. ## Erros comuns - marcar READY sem resolver uma ambiguidade material. - confundir estrutura válida com conteúdo suficiente. - criar um relatório paralelo em vez de atualizar a seção correta. - compensar um Ato I incompleto em uma etapa posterior. ## Próximo passo Com o Definition Gate aprovado, use [`specsfy-05-tasks`](/docs/specsfy/skills/tasks). Se a validação encontrar uma escolha aberta, use [`specsfy-02-backlog`](/docs/specsfy/skills/backlog). ### Uso avançado do Specsfy: recursos e automações extras - URL: https://promovaweb.com/docs/specsfy/uso-avancado - Descrição: Recursos usados depois da primeira spec — seleção de especialistas, progresso em JSON, atualização visual e retomada de mudanças posteriores no projeto. Este guia reúne recursos usados depois da primeira spec: seleção de especialistas, progresso em JSON, atualização visual e retomada de uma mudança posterior. Para acompanhar os exemplos, conclua o [primeiro projeto](/docs/specsfy/comecando), mantenha o CLI e o framework instalados e execute os comandos na raiz do projeto consumidor. ## Detecte e instale orientação técnica Comece com `skills detect` para ler as recomendações do catálogo sem alterar o projeto: ```bash specsfy skills detect --project . ``` Quando todas as recomendações forem aplicáveis, `--detected` instala o framework e os especialistas em uma única execução. O `skills-lock.json` registra os arquivos publicados: ```bash specsfy install --project . --detected ``` Quando o catálogo listar tecnologias que não pertencem à aplicação, repita `--specialist` somente com os nomes confirmados. Assim, o instalador publica as bases e ignora as recomendações que não foram escolhidas: ```bash specsfy install --project . \ --specialist specsfy-specialist-laravel \ --specialist specsfy-specialist-postgres ``` Em um projeto já preparado, acrescente somente os especialistas escolhidos com `npx skills add`: ```bash npx skills add https://github.com/promovaweb/specsfy \ --skill specsfy-specialist-laravel --agent universal --copy --full-depth ``` A detecção usa manifests, dependências e arquivos reconhecidos pelo catálogo. O comando de instalação só deve ser executado depois da revisão. Os especialistas orientam escolhas técnicas, mas não criam specs nem aprovam gates. ## Automatize a leitura de progresso ```bash specsfy progress --project . --json specsfy progress --project . --watch --interval 0.5 --json ``` O JSON contém `summary` e `specs`. Com `--watch`, um snapshot novo aparece somente quando o conteúdo das specs muda. Painéis podem consumir essa saída para leitura, mas os gates continuam sendo editados apenas na `spec.md` pela skill responsável. ## Ajuste a atualização visual ```bash specsfy config show --project . specsfy config set --project . --watch-interval 0.5 ``` A configuração vive em `/.specsfy/config.json` e preserva chaves desconhecidas. Consulte todos os recursos no [guia do CLI](/docs/specsfy/cli). ## Atualize sem perder customizações ```bash specsfy update --project . ``` O CLI usa fingerprints para distinguir conteúdo gerenciado intacto de customização local. Uma diferença local faz a atualização ou a remoção ser recusada. Use `--force` somente depois de revisar a comparação e confirmar que o conteúdo protegido pode ser descartado. Quando o CLI foi instalado pelo npm, o comando abaixo atualiza o pacote global: ```bash specsfy upgrade ``` Quando a instalação usa o executável Node oficial, `specsfy upgrade` pode substituí-lo automaticamente. Para fazer a troca manual, use o download e restaure a permissão: ```bash curl -fL get.specsfy.dev -o "$HOME/.local/bin/specsfy" chmod +x "$HOME/.local/bin/specsfy" ``` ## Incorpore uma mudança na spec Quando lembrar de algo depois da definição, use a entrada explícita: ```text Use $specsfy-update-spec em specs//-/spec.md: quero adicionar, remover, corrigir ou mudar esta especificação. ``` Quando um requisito observável muda, a skill reabre a definição. O Definition, o Plan e o Delivery Gate precisam de evidência nova. Quando apenas o plano técnico muda, ela reabre o Ato II e o Ato III. A spec alterada invalida as provas que dependiam da versão anterior e preserva tarefas e evidências ainda compatíveis. As skills fazem transições e retomadas na mesma conversa. Esse handoff não amplia autorização para instalar, publicar, fazer deploy ou executar ação destrutiva. Consulte [Atualizar uma especificação](/docs/specsfy/atualizar-spec) para a classificação completa e exemplos em linguagem comum. ## Limites - `--force` pode descartar customizações protegidas. - `--detected` depende do catálogo e do estado observado no projeto. - A TUI e o progresso projetam estado, mas não substituem a spec. - o especialista não substitui a confirmação da versão, das convenções e das falhas possíveis no projeto. O resultado esperado é um projeto com especialistas escolhidos de forma explícita, automação somente de leitura e gates coerentes com a versão atual da spec. --- ## Páginas-chave ### Promovaweb - URL: https://promovaweb.com/ - Descrição: Iniciativa focada em Martech, IA e infraestrutura soberana, com formações, ebooks e ferramentas. ### Planos - URL: https://promovaweb.com/planos - Descrição: Comparativo dos planos Martech, IA Makers e Founders. ### Plano Martech - URL: https://promovaweb.com/planos/martech - Descrição: Plano de automação, CRM, dados e operação de marketing. ### Plano IA Makers - URL: https://promovaweb.com/planos/ia-makers - Descrição: Plano de desenvolvimento com IA, agentes e Vibe Coding. ### Plano Founders - URL: https://promovaweb.com/planos/founders - Descrição: Acompanhamento para fundadores que constroem software e negócio. ### Plano Founders, segunda turma - URL: https://promovaweb.com/planos/founders-2-turma - Descrição: Oferta vigente da segunda turma do Plano Founders. ### Trilha DevOps - URL: https://promovaweb.com/devops - Descrição: Trilha de infraestrutura soberana, servidores e operação. ### Formações - URL: https://promovaweb.com/formacoes - Descrição: Diretório das formações por plano. ### Ferramentas - URL: https://promovaweb.com/ferramentas - Descrição: Stack de ferramentas usada nos projetos e formações. ### Ebooks - URL: https://promovaweb.com/ebooks - Descrição: Biblioteca de ebooks publicados para leitura no navegador. ### Glossário - URL: https://promovaweb.com/glossario - Descrição: Verbetes sobre IA, automação, infraestrutura e desenvolvimento. ### Podcasts - URL: https://promovaweb.com/podcasts - Descrição: Programas e episódios em vídeo da Promovaweb. ### Vídeos - URL: https://promovaweb.com/videos - Descrição: Catálogo de vídeos e playlists do canal. ### Changelog - URL: https://promovaweb.com/changelog - Descrição: Registro público de atualizações dos sistemas. ### Comunidade - URL: https://promovaweb.com/comunidade - Descrição: Programação e acompanhamento da comunidade. ### Discord - URL: https://promovaweb.com/discord - Descrição: Acesso à comunidade no Discord. ### FAQ - URL: https://promovaweb.com/faq - Descrição: Perguntas frequentes sobre planos e acesso. ### Contato - URL: https://promovaweb.com/contato - Descrição: Canais de suporte, vendas e parcerias. ### Links - URL: https://promovaweb.com/links - Descrição: Destinos oficiais da Promovaweb. ### Recursos - URL: https://promovaweb.com/recursos - Descrição: Diretório de recursos e materiais. ### Instalador - URL: https://promovaweb.com/instalador - Descrição: Instalador e configurador de ambiente local. ### Parcerias - URL: https://promovaweb.com/parcerias - Descrição: Afiliados e parceiros recomendados. ### Materiais - URL: https://promovaweb.com/materiais - Descrição: Central de materiais para download. ### Luiz Eduardo - URL: https://promovaweb.com/luizeof - Descrição: Biografia, trajetória e relações oficiais. ### Vibe Coding - URL: https://promovaweb.com/vibe-coding - Descrição: Definição, fluxo e condições de aceite de Vibe Coding. ### Termos de Serviço - URL: https://promovaweb.com/terms - Descrição: Termos de uso do site.