Caderno

Desenvolvimento assistido por IA no meu próprio portfólio

Como trabalhei com um agente de IA no design deste site: um brief com resultados verificáveis, skills de design e escrita, e scripts que mediram o resultado.

Read in English

Índice

Desenhei a primeira versão deste portfólio à mão. O LinkedIn e os portfólios feitos com IA estavam então a ter muita exposição, por isso renovei o visual com IA. A renovação funcionava e o conteúdo era real, mas o design estava mais pesado do que precisava. Todas as secções abriam com o mesmo andaime: um pequeno rótulo em maiúsculas com o número da secção e um sufixo, um slogan com serifa por baixo, e depois cartões com etiquetas coloridas. A ideia de “caderno de engenharia” aparecia cinco vezes: marcas de secção, linhas de cota, uma fotografia colada com fita e inclinada, notas na margem e sublinhados a caneta vermelha. Nenhuma parecia uma escolha, porque estavam todas ligadas ao mesmo tempo.

A limpeza nasceu da necessidade de simplificar esse design, porque mais simples é melhor. Apliquei-lhe o que a minha tese defende para a IA em qualquer fase do trabalho: escrever o que significa estar feito, deixar o agente trabalhar com base nisso, e verificar o resultado com algo que não seja a opinião do próprio agente.

O topo antigo da página inicial (versão inglesa) em modo escuro: um rótulo vermelho em maiúsculas, o nome com um ponto final vermelho, uma frase longa, um ponto de estado, três botões e um grafo colorido com legenda.
Antes: a página inicial depois da renovação com IA, com o rótulo em maiúsculas e monoespaçado, o ponto final vermelho, três estilos de botão, o grafo com cores por tipo e a sua legenda, e o rótulo de secção com § por baixo.
O novo topo da página inicial (versão inglesa) em modo escuro: uma pequena linha cinzenta acima do nome, uma frase de posicionamento em duas linhas, um botão vermelho «View work» e uma ligação de texto, e um grafo cinzento do percurso.
Depois: uma linha simples acima do nome, uma frase de posicionamento, dois botões, um grafo monocromático e um rótulo de secção simples.

O brief

O ponto de partida foi um brief que escrevi eu, com ideias de discussões no Reddit sobre o que torna uma interface gerada reconhecível e com a ajuda do Claude na redação. Era concreto quanto aos resultados e deixava o método em aberto:

  • uma fonte com serifa e uma sem serifa, com a monoespaçada só para código, datas e valores de especificação;
  • uma escala tipográfica, um raio de canto, uma cor de destaque e dois estilos de botão;
  • nada de animações ao fazer scroll, sombras, inclinações ou emoji como ícones;
  • texto simples, com uma lista de expressões proibidas em que a renovação se apoiava (“reliable systems”, “with the spec as the anchor”, “drawn to”, “along the way”);
  • manter o que era meu: o brilho do topo, a grelha de pontos, o logótipo e a fotografia ao entardecer na página de contacto.

Trazia também as regras que valem para tudo neste site: nada de número de telefone ou morada, e nada inventado. Se um facto não podia ser verificado, passava a um TODO visível ou ficava de fora.

O processo

Corri-o no Claude Code com três skills instaladas, e o Claude escreveu alguns scripts para as verificações.

Impeccable, antes e depois

O Impeccable é uma skill de design com um comando de crítica, um comando de auditoria e um detetor baseado em regras para padrões comuns de interfaces geradas. A crítica, antes de qualquer alteração, deu ao site 27/40 nas heurísticas de Nielsen, com 1/4 em design estético e minimalista. O detetor encontrou 9 problemas nas páginas construídas, incluindo 37 travessões só na página do Apex, números de secção em todas as secções, uma hierarquia tipográfica em que os tamanhos pequenos eram 12, 14,4 e 15,2 px, e uma caixa de destaque com uma risca colorida de lado.

Depois da passagem, a auditoria deu 19/20. Atualizar o Impeccable da versão 3.9 para a 4.8 perto do fim valeu a pena: a nova versão desenha cada página em largura de computador e de telemóvel e encontrou problemas que a primeira não via, como etiquetas de gráficos com cerca de 9 px, anos de um gráfico com contraste de 3,2:1 sobre o brilho do topo no telemóvel, e logótipos sem margem interior. Ficou tudo corrigido. O único alerta que restava era o fundo creme da página, que mantive nessa altura.

Humanizer para o texto

O humanizer reescreve texto que soa a gerado: contrastes do tipo “não X, mas Y”, frases finais de uma linha, listas forçadas de três, travessões por todo o lado, negritos usados como decoração. Correu sobre todo o texto visível, em inglês e em português. Nessa altura, os textos da interface e a maior parte dos ficheiros de dados já não precisavam de nada. Os artigos e os dados da página do Apex precisavam: retirou vários contrastes com “em vez de”, um parágrafo final que repetia a abertura de um artigo, e frases como “Confiança não é evidência”, que repetiam a frase anterior. A regra que mais me importava era manter os factos e não acrescentar nenhum. O resumo da dissertação e a tese ficaram palavra por palavra.

frontend-design como segunda opinião

A skill frontend-design enumera os traços à volta dos quais as páginas geradas se juntam hoje. Dois aplicavam-se a este site: o fundo esbranquiçado quente com títulos com serifa, e os rótulos de secção em maiúsculas com linhas de metadados separadas por ·. O brief definia ambos, por isso ficaram numa primeira fase; uma crítica posterior levou-me a abandonar os rótulos em maiúsculas e, por fim, também o fundo quente. Tudo o resto dessa lista (uma palavra destacada no título, números de secção, animações de entrada em cada secção, sombras nos cartões) desapareceu.

Verificações medidas

A parte que manteria em qualquer projeto é a verificação. O Claude escreveu pequenos scripts em Playwright que mediam o site construído:

  • um script de métricas que lê o estilo calculado de cada elemento de texto visível em 7 páginas, em 2 larguras e nos 2 temas, e reporta famílias tipográficas, tamanhos, raios de canto, número de elementos em maiúsculas, usos da cor de destaque por ecrã e falhas de contraste;
  • 27 verificações de funcionamento: tema, mudança de língua, filtros, botões de copiar, o foco preso no menu de telemóvel, ausência de scroll horizontal;
  • um verificador de ligações sobre todas as páginas construídas e todas as ligações externas;
  • Lighthouse em 8 páginas, em telemóvel e computador.

O resultado, medido: 7 tamanhos de letra (14, 16, 17, 20, 28, 40 e 56 px), raios de 4 px e de pílula, no máximo 2 usos da cor de destaque por ecrã, sem contar com o logótipo, 0 falhas de contraste, 0 ligações internas partidas, e desempenho no Lighthouse entre 98 e 100, com 100 em tudo o resto. As capturas de antes e depois de 6 páginas, em 2 larguras e nos 2 temas, estão no repositório, ao lado de um relatório que liga cada ponto do brief à sua evidência.

Onde o meu critério continuou a contar

Algumas decisões ficaram comigo.

  • O brief pedia uma lista curta na secção de Experiência da página inicial. Quando a vi publicada, era uma lista aborrecida ao lado de uma cronologia de Formação com logótipos, por isso a Experiência usa agora a mesma cronologia.
  • O brief mantinha o brilho do topo como marca. Mais tarde reduzi o violeta a um canto discreto, porque num ecrã escuro era a coisa mais forte da página.
  • O detetor assinalava o fundo creme. Mantive-o durante algum tempo porque gostava dele, sabendo que é uma das escolhas geradas mais comuns, e depois troquei-o por um esbranquiçado neutro e voltei a verificar os pares de cores.
  • Dois passos correram em modo degradado, e o relatório di-lo: a instalação do humanizer foi bloqueada da primeira vez, por isso a primeira revisão do texto aplicou as regras à mão, e a crítica inicial correu num só contexto, quando o Impeccable pede duas avaliações independentes.

Uma segunda ronda

A 5 de novembro voltei a correr as mesmas três skills sobre o site. A crítica deu 20/32, um valor que não se pode comparar com os 27/40 anteriores: o método foi diferente e duas heurísticas não se aplicavam. As capturas acima mostram o fim da primeira passagem, por isso já não correspondem ao site em todos os detalhes.

A maior parte do que resultou daqui foi estrutural ou pequena:

  • O Trabalho subiu na página inicial, com o diagrama do Apex, e a página do Apex ganhou uma barra de secções e um topo mais curto.
  • Os rótulos de secção em maiúsculas passaram a títulos sem serifa, e o fundo creme passou a um esbranquiçado neutro.
  • O formulário de contacto ganhou um limite de tempo nos pedidos, erros anunciados e um estado de foco visível.
  • A faixa de fases, o grafo de commits e o mapa de calor passaram a ser acessíveis por teclado, e as ligações isoladas chegaram a uma área de toque de 24 px.
  • A passagem do humanizer encontrou texto correto mas pobre. A tese aparecia em quase a mesma frase três vezes na página inicial, e o cartão do Outfolio nunca dizia o que é o Outfolio.

Duas das correções vieram de eu olhar para o site publicado. Ainda havia setas em algumas ligações, por isso pedi texto simples em todo o lado. Os cartões de trabalho estavam desequilibrados, com espaço vazio nos projetos sem capturas, e o cartão do Apex era diferente na página inicial e na de trabalho. Agora há um só cartão do Apex, e os cartões de projeto são iguais e só com texto.

A descoberta maior foi o diário do Apex, uma página feita à mão que a primeira passagem nunca tinha medido. Tinha uma cor de destaque violeta, uma fonte de títulos e um botão de tema próprios, 31 elementos em maiúsculas e nenhuma versão portuguesa. O detetor encontrou ali 55 problemas, e 0 nas páginas principais. A minha própria reavaliação da auditoria, com base no axe, no detetor e nas capturas, deu 15/20 contra os 19/20 anteriores, em parte porque já contava com essa página.

Pedi ao Claude que reconstruísse o diário dentro do design do site, nas duas línguas, e depois voltei a correr tudo. O Lighthouse encontrou um deslocamento de layout de 0,177 na página inicial em português no telemóvel, causado por uma fonte que chegava tarde. Pré-carregá-la resolveu o problema. A mesma verificação mostrou três ficheiros de fontes que todas as páginas descarregavam e nenhuma usava, por isso também saíram, o que alargou todos os parágrafos, porque o navegador estava a medir o ch a partir de um deles. O detetor apanhou isso com 22 avisos de comprimento de linha, e a largura do texto voltou ao que era.

A execução final: o Lighthouse em 11 páginas, em telemóvel e computador, deu 99 a 100 em desempenho e 100 em tudo o resto. O detetor não encontra problemas nas páginas construídas em nenhuma das larguras, o axe não acusa nada em 12 páginas, em 2 larguras e nos 2 temas, e o script de métricas lê 7 tamanhos de letra e 0 elementos em maiúsculas, sem contar com as etiquetas de gráficos dentro de SVG. A minha reavaliação da auditoria dá 19/20. Uma nova crítica, feita por um agente Claude separado que não tinha visto as pontuações anteriores nem o resultado do detetor, deu 24/32. O seu ponto principal coincide com o ponto que não dei à auditoria: serifa e carmesim sobre esbranquiçado continua a ser um visual familiar, e o traçado do percurso, a única ideia original do site, não chegava aos telemóveis. Por isso tratei disso depois da crítica: o percurso desce agora o topo da página no telemóvel e segue as cronologias de Experiência e Formação a carmesim, e o tom rosa no modo claro quase desapareceu. Isso abdica do limite de 2 usos da cor de destaque por ecrã da primeira passagem, de propósito.

O que voltaria a usar

Escrever o brief como uma lista de resultados verificáveis. Dar ao agente skills que codificam gosto, para que não invente uma linguagem de design do zero. Depois medir o resultado com scripts, em todas as páginas, e guardar a evidência no repositório. O mesmo agente fez a renovação e a maior parte da limpeza; da segunda vez tinha um brief e verificações a que responder.