O handbook de AI Product Engineering.

Capítulo 1: A especificação executável.

Cinco designers de produto receberam o mesmo brief: uma interface de gestão de frota logística, um coordenador tomando conta de cinquenta motoristas por dia, em região rural com infraestrutura ruim. O brief descrevia o problema e evitava de propósito qualquer palavra de interface. Nada de mapa, nada de sidebar, nada de dashboard. Cada um escreveu o prompt do seu jeito, na mesma ferramenta.

Do outro lado, colamos o mesmo brief cru na mesma ferramenta, cinco vezes, sem nenhum designer no meio.

As cinco saídas sem designer trouxeram a mesmíssima hierarquia de informação. Cartões de indicador no topo, toda vez, nas cinco. É esse o experimento que publicamos no AIMEDIA 2026 (IARIA), onde o artigo recebeu o Best Paper Award, e é dele que sai o resto deste capítulo.

O que o estudo achou, e o que ele não achou

Dois pesquisadores pontuaram as dez saídas de forma independente, em quatro dimensões estruturais (lógica de navegação, hierarquia de informação, ontologia de componentes e cobertura de estados), numa escala somada de 0 a 8, em que 8 significa totalmente padronizado. As saídas sem designer ficaram em 5,0 de média. As com prompt de designer, em 3,0. A diferença tem d de Cohen de 1,26, com intervalo de confiança de 0,2 a 3,8.

Esse intervalo largo merece ser dito antes de qualquer conclusão: são cinco execuções por grupo, uma ferramenta só, um domínio só. É um piloto exploratório e precisa de replicação. Nós mesmos previmos convergência em pelo menos três das quatro dimensões e encontramos em uma. E o primeiro avaliador não foi cegado aos prompts, um viés que declaramos no paper. O estudo completo traz o livro de códigos, a concordância entre avaliadores e todas as ameaças à validade, para quem quiser auditar em vez de acreditar.

Cuidado com uma leitura fácil aqui. "A mesma hierarquia nas cinco" vale para uma dimensão específica; no placar somado das quatro, as execuções sem designer variaram de 4 a 7. A ferramenta não repete a mesma tela: ela repete a mesma decisão estrutural onde o domínio aperta e improvisa onde ele abre espaço. A implicação prática, se isso se confirmar em outros domínios, é que especificar rende mais justamente onde você tem mais liberdade de projeto.

Teve ainda um resultado que nós não tínhamos previsto: em quatro das cinco execuções sem designer, o modelo desenhou estado de erro e indicador de offline sem que o prompt pedisse. Como o brief falava em região rural com infraestrutura precária, a leitura mais provável é que ele estava respondendo ao contexto do problema, e não inventando do nada. Registramos isso como limitação: essa dimensão do nosso instrumento acabou medindo o quanto o modelo responde ao brief, não o quanto ele converge.

Duas ressalvas que o próprio estudo faz e que mudam como você lê o número. A primeira: convergência não é sinônimo de resultado ruim. Em domínio bem estabelecido, o padrão canônico costuma ser a resposta certa, e o que medimos foi variedade estrutural, não qualidade. A segunda: a diferença de média foi puxada por dois dos cinco designers; os outros três produziram variações sobre o mesmo esqueleto. Separar diversidade real de variação de superfície vai exigir amostra maior.

A convergência começa antes da IA responder

Tem um detalhe nesse experimento que eu não canso de mostrar para designer: o brief não tinha nenhuma palavra de interface. Nada de mapa, sidebar, dashboard, card. Foi escrito assim de propósito, para ver que estrutura emergiria sozinha.

Os cinco designers, sem combinar entre si, digitaram essas palavras nos prompts deles.

Quer dizer que a padronização não nasceu quando a ferramenta desenhou. Ela nasceu na hora em que o designer traduziu um problema de negócio ("coordenar cinquenta motoristas em região com internet ruim") para vocabulário de tela ("dashboard com sidebar e cards"). Essa tradução é automática depois de anos de prática, e é aí que a maior parte do espaço de solução morre. A IA executou uma decisão que já tinha sido tomada no teclado do humano.

É o tipo de coisa que você consegue verificar hoje, sozinho, no seu último prompt.

O que separou os prompts, e não foi tempo de carreira

Chamamos de Specification Literacy a competência que apareceu aqui: a capacidade de traduzir intenção de design num prompt estruturado e restritivo, que afasta a IA dos padrões default. O nome é nosso; a base vem da literatura de fixação em design, que já mostrava, antes de existir IA generativa, como um exemplo pronto reduz a exploração de alternativas.

E ela não veio com tempo de carreira. O designer com 7 anos de profissão escreveu o prompt mais curto do grupo, cerca de 120 palavras e 4 restrições, e a interface dele saiu com pontuação 6, mais padronizada que quatro das cinco execuções sem designer nenhum. O prompt mais elaborado veio de alguém com pouco mais de 3 anos de carreira e familiaridade máxima com ferramentas de IA. No nosso conjunto pequeno, intimidade com a ferramenta acompanhou a sofisticação do prompt mais de perto do que anos de design. É sinal direcional, não resultado confirmado.

Os dois resultados mais distantes do padrão vieram de estratégias diferentes entre si. Um participante escreveu cerca de 2.500 palavras, com mais de 45 restrições e uma dúzia de antipadrões explícitos ("nada de seção dashboard", "nada de glassmorphism", "nada de conceito bonito de portfólio que ignora função") e terminou com pontuação 2. Outro escreveu cerca de 500 palavras, sem nenhuma negação, mas especificando a estrutura em seções numeradas e colunas, e terminou com pontuação 1, o mais distante de todos.

O que os dois têm em comum não é tamanho nem estilo: é serem específicos. Os dois prompts que ficaram colados no padrão foram justamente os que deram instrução geral, sem antipadrão e sem estrutura explícita. Especificidade foi o divisor, por qualquer um dos dois caminhos.

Vale dizer o preço: as 2.500 palavras compraram uma queda de 4 pontos em relação ao prompt de 120. Vinte vezes mais esforço de escrita. Tirar a IA do piloto automático custa trabalho, e é honesto saber quanto antes de prometer que é fácil.

As cinco partes de uma especificação executável

O estudo não testou nenhum formato de especificação: ele comparou o que cinco pessoas escreveram por conta própria. O formato abaixo é o meu, montado a partir do que apareceu nos prompts mais específicos e do que eu uso no dia a dia. Trate como ponto de partida testável, não como resultado de pesquisa:

1. Intenção. O problema do usuário em uma frase, com o resultado esperado. É o porquê da solução, antes dela.
2. Contexto. Quem usa, em que situação, com que restrição real: dispositivo, conexão, acessibilidade, idioma.
3. Decisões já tomadas. Design system, tom de voz, padrões do produto. O que você não fixar aqui entra por default.
4. Critérios de aceite. Como você verifica que ficou pronto, em termos checáveis: um teste que passa, um fluxo que completa, um número que bate. "Ficar bonito" é esperança.
5. Antipadrões. O que a IA deve evitar, com nome. É a parte que quase ninguém escreve, e apareceu no prompt do participante que mais se distanciou do padrão por essa via.

Essa lista é o trabalho que design sempre exigiu: entender o problema antes da solução, conhecer o contexto, respeitar o sistema, definir o que é pronto. A IA não aposentou nada disso.

O mesmo pedido, nos dois formatos

Vamos ao concreto, com o brief do estudo. Primeiro, um pedido comum:

Preciso de um dashboard de gestão de frota logística. O coordenador acompanha os motoristas e resolve problemas de entrega. Faz um layout limpo e moderno, com cards de indicadores e menu lateral.

Duas linhas e a estrutura inteira já foi decidida: dashboard, cards, menu lateral. Sobrou para a IA escolher a cor.

Agora o mesmo pedido nas cinco partes:

Intenção. Um coordenador precisa manter cinquenta entregas do dia dentro do prazo, percebendo cedo qual delas vai atrasar. Sucesso é ele agir antes do cliente ligar reclamando.

Contexto. Uso em região rural com conexão instável e telefone tocando. A tela fica aberta o dia inteiro num monitor, olhada de longe entre uma ligação e outra. A informação precisa ser legível a dois metros de distância.

Decisões já tomadas. Usar os componentes e os tokens do nosso design system. Português do Brasil. Estados de carregando, vazio e erro são obrigatórios, não opcionais.

Critérios de aceite. Em menos de três segundos olhando a tela, dá pra dizer quais entregas estão em risco agora. A tela continua utilizável quando a conexão cai. Navegação completa por teclado.

Antipadrões. Não use fileira de cartões de indicador no topo: aqui a métrica agregada não ajuda quem age em caso individual. Não trate isso como relatório; é ferramenta de plantão. Não esconda o estado de risco atrás de filtro ou aba. Não use verde e vermelho como único sinal de status.

O segundo texto não é mais bonito. É mais decidido, e a parte mais difícil dele está no fim, nas quatro frases que começam com "não".

Escrever antipadrão custa porque exige que você já tenha uma opinião sobre o que costuma dar errado ali. É aí que a sua experiência entra no trabalho, em vez de ficar assistindo à IA preencher os buracos.

Como testar a sua especificação

A tentação é rodar a mesma especificação duas vezes e comparar. A mesma variação de 4 a 7 que apareceu nas execuções sem designer mostra por que isso não basta: a mesma entrada já produz saídas diferentes por conta da aleatoriedade da ferramenta. Duas rodadas não separam o efeito da sua especificação do ruído do modelo.

O que ajuda é comparar por dimensão, não no olhômetro. Rode algumas vezes e responda por escrito: a navegação mudou? a hierarquia mudou? os componentes mudaram? Onde tudo varia menos uma coisa, aquela coisa está sendo decidida por algo mais forte que o seu texto, seja o domínio, seja a ferramenta. Onde varia justamente onde você foi explícito, vale desconfiar que a sua restrição não chegou.

Isso não isola causa, e nem tenta. Serve para você parar de atribuir a si mesmo um resultado que a ferramenta ia entregar de qualquer jeito.

Por que isso importa agora

Porque a promessa de velocidade sem critério já está sendo cobrada. Um estudo randomizado da METR, de 2025, constatou que desenvolvedores experientes ficaram 19% mais lentos ao usar assistentes de IA nas tarefas do experimento, enquanto se achavam mais rápidos. Gerar ficou barato. Responder pelo que foi gerado, não.

A parte que continua exigindo alguém respondendo por ela é decidir o que deve existir e verificar se existiu. Especificação é o nome da primeira metade disso.

Pratique agora

Pegue o último pedido que você fez a uma IA e reescreva no formato das cinco partes, dando atenção especial aos antipadrões, que é a parte que costuma faltar. Depois rode os dois e compare por dimensão.

Na última tela que você entregou com IA: quanto daquilo você especificou, e quanto foi a ferramenta escolhendo o caminho mais comum enquanto você olhava?

Este capítulo é aberto e não vende nada. Se quiser rodar o exercício de forma guiada, o método Especificação executável está aberto na mesma casa, e funciona dentro do seu próprio agente pelo conector da Xikota.ai.

Entre na sua conta pra marcar este capítulo como concluído e acompanhar seu progresso.

Capítulo 2: O arquivo que o agente lê antes de você falar.

Eu perdi três execuções de agente pelo mesmo motivo, em dias diferentes, antes de escrever uma linha a respeito. O erro era bobo: eu passava um payload estruturado por um caminho que chegava do outro lado como texto solto, e o agente saía trabalhando com a coisa errada. Nas três vezes eu diagnostiquei do zero. Na terceira, escrevi uma frase num arquivo que todo agente meu lê antes de começar. Nunca mais aconteceu.

O prejuízo não foi o erro. Foi ter diagnosticado três vezes.

Especificação morre com a tarefa. Contexto não.

O capítulo 1 terminou num ponto que vale reabrir aqui: especificar bem é o que separa o seu resultado da média que a ferramenta produz sozinha. O que ficou de fora é que uma especificação boa tem duas metades com prazos de validade muito diferentes.

Uma metade é da tarefa: esta tela, este fluxo, este componente, este estado vazio. Ela nasce e morre no pedido, e tem que morrer mesmo, porque a próxima tarefa é outra.

A outra metade não é da tarefa. É do produto. Que produto é esse, pra quem ele existe, que tecnologia ele usa, como se escreve uma mensagem de erro nele, o que é proibido, e o que já deu errado antes. Isso não muda entre um pedido e outro. Você só repete porque escreveu no lugar errado.

E o lugar errado quase sempre é o mesmo: a conversa. Que eu já disse em outro canto e repito aqui porque é o eixo deste capítulo, o chat esquece e o arquivo lembra. O que este capítulo acrescenta é o desenho do arquivo: o que entra, o que fica de fora, e por que ele perde a validade se ninguém cuidar.

Os seis blocos, e o que cada um evita

O dossiê de contexto do produto é um documento único que qualquer agente lê antes de qualquer tarefa. Em algumas ferramentas ele tem nome e lugar fixos; a ideia funciona em qualquer uma, inclusive colando o texto no começo da sessão. A ordem abaixo não é decorativa: ela vai do que nunca muda para o que muda toda semana.

1. O produto em três frases. O que é, pra quem, e o que ele nunca deve ser. Sem essa terceira frase o agente resolve um problema vizinho que ninguém pediu.
2. Stack e estrutura. Tecnologias, onde vive cada coisa, como se roda e como se testa. É o que separa a resposta que funciona da resposta que parece certa e não roda na sua máquina.
3. Design system. Tokens, componentes canônicos, o que é proibido escrever na mão. Aqui mora o botão novo que ninguém aprovou.
4. Voz e conteúdo. Idioma, tom, palavras banidas, como se escreve um erro e um estado vazio. Sem isso a sua interface fala igual a todas as outras.
5. Regras duras. Acessibilidade mínima, privacidade, o que exige aprovação humana. É a lista das decisões que continuam sendo suas.
6. Armadilhas conhecidas. Os erros que agentes já cometeram neste produto e não podem repetir.

Os cinco primeiros você consegue escrever numa tarde, olhando pro que já existe. O sexto não dá pra escrever de véspera, e é justamente ele que decide se o dossiê fica vivo.

O bloco seis é o único que cresce sozinho

Documentação morre porque nasce completa e nunca mais é tocada. O bloco de armadilhas nasce vazio e cresce toda vez que alguma coisa dá errado, o que garante que ele esteja sempre falando do produto de verdade e não do produto que você imaginou no começo.

A disciplina que faz ele crescer é uma só, e também já é pública: corrigiu a mesma coisa pela segunda vez, para e escreve a regra. Trinta segundos. É a Regra das Duas Vezes.

O detalhe que costuma faltar é como escrever a linha. Regra sem o porquê vira superstição, e a primeira pessoa que discordar apaga. Cada armadilha precisa de três coisas na mesma frase: o que não fazer, o que acontece se fizer, e o que fazer no lugar. "Não use caminho relativo aqui, porque o diretório de trabalho muda no meio da sessão e o comando roda na pasta errada; use caminho absoluto." Assim, quem ler daqui a seis meses, inclusive você, consegue julgar se a regra ainda vale.

Quando a regra velha briga com a decisão nova

Esse bloco cria um problema que só aparece uns meses depois: uma armadilha escrita em março pode contradizer uma decisão tomada em agosto, e o agente obedece às duas com a mesma disciplina. Ele não sabe qual é mais recente nem qual tem mais autoridade.

A saída é barata e precisa estar no próprio dossiê: cada linha de armadilha leva a data, e o documento diz, logo no começo, quem ganha em caso de conflito. No meu, a ordem é essa: regra dura vence armadilha, e entre duas armadilhas vence a mais nova. Sem isso, o arquivo que devia acelerar vira um segundo lugar onde procurar a verdade.

Por que duas telas, e não vinte

A vontade de colocar tudo é forte e é uma armadilha. Um dossiê que passa de umas duas telas começa a atrapalhar em vez de ajudar, por duas razões que se somam.

A primeira é sua: documento grande ninguém revisa, e dossiê que ninguém revisa acumula regra morta. Regra morta é pior que regra ausente, porque o agente obedece com a mesma disciplina as duas.

A segunda é da ferramenta, e tem evidência publicada. No benchmark NoLiMa, apresentado no ICML de 2025, a acurácia cai conforme o contexto cresce: em 32 mil tokens, onze dos doze modelos testados ficaram abaixo da metade do desempenho que tinham com contexto curto. Um estudo do mesmo ano, com o título nada sutil de Context Length Alone Hurts LLM Performance Despite Perfect Retrieval, isolou o comprimento como causa: mesmo garantindo que a informação certa continuava perfeitamente recuperável, mediu queda de 13,9% a 85%. Esse segundo ainda é preprint, então leia como direcional. Os dois apontam para o mesmo lugar: encher o contexto não é de graça.

Tem ainda um efeito de posição que explica por que a ordem dos blocos importa. O estudo Lost in the Middle (Liu e colegas, TACL 2024) mediu que os modelos acertam mais quando a informação relevante está no começo ou no fim do contexto, e erram mais quando ela está no meio, numa curva em U. Se o seu dossiê tem uma regra que não pode ser ignorada de jeito nenhum, ela não fica no miolo.

Regra prática: se uma linha não muda nenhuma decisão do agente, ela não é contexto, é enfeite. Corte.

O que não entra

Não entra a tarefa de hoje: isso é prompt, e prompt é descartável. Não entra segredo, chave nem senha, porque o dossiê circula junto com o pedido. Não entra histórico de decisão em prosa longa, que é assunto de documento à parte; no dossiê fica só a decisão, em uma linha. E não entra nada que você não esteja disposto a defender daqui a seis meses.

Pratique agora

Abra um documento em branco e escreva os cinco primeiros blocos olhando pro produto que você tem na mão agora. Uma tarde, no máximo. Deixe o bloco seis vazio, com o título escrito.

Depois disso, uma disciplina só: na próxima vez que você corrigir um agente pela segunda vez pelo mesmo motivo, pare e escreva a linha, com o porquê junto.

A pergunta que fecha o capítulo é a mesma que eu me fiz depois da terceira execução perdida: qual erro você já diagnosticou mais de uma vez este mês, e onde ele está escrito?

Este capítulo é aberto e não vende nada. O método Dossiê de contexto do produto está aqui no site, aberto e de graça, com o passo a passo pra montar o arquivo junto com o seu agente. Se preferir rodar sem sair da sua ferramenta, o conector da Xikota.ai entrega esse mesmo método dentro dela.

Entre na sua conta pra marcar este capítulo como concluído e acompanhar seu progresso.