Fluxo de Trabalho com IA

Este projeto foi construído com Claude Code. A maioria das alegações de “construído com IA” ficam-se pelo rótulo. Aqui está o panorama completo: o que a IA sabe, como as sessões funcionam, como é o processo de prompting na prática e onde o humano traça a linha. Se está a construir com IA ou se simplesmente tem curiosidade sobre como isso realmente funciona, isto é para si.

O Que a IA Sabe

O Claude Code tem um ficheiro de memória persistente que transporta contexto entre sessões. Em vez de re-explorar a base de código em cada conversa, retoma de onde parámos. Eis o que contém (higienizado):

Identidade do Projeto

Nome da aplicação, localização do código-fonte, licença, identificador da aplicação
Relação de fork: o upstream é o En Croissant de Francisco Salgueiro, mantemos o nosso próprio fork de forma independente
Porquê o fork: o mantenedor do upstream declinou a funcionalidade de TTS, o que é justo — visões diferentes para o mesmo projeto

Regras de Compilação

Apenas pnpm — o npm quebra o vanillaExtract (ecrã branco em runtime, sem erro, simplesmente nada)
Node.js 22+ necessário (o Vite 7 precisa de crypto.hash)
Sempre pnpm format && pnpm lint:fix antes de fazer commit
Fechar a aplicação antes de substituir o binário (“Text file busy”)
Após mover diretórios de código-fonte, cargo clean para limpar referências de caminhos obsoletos

Conhecimento da Arquitetura

Quais ficheiros são responsáveis por quais funcionalidades (atoms em atoms.ts, navegação da árvore em tree.ts, motor TTS em tts.ts)
Porquê todos os atoms de TTS precisam de getOnInit: true (leituras imperativas via store.get() antes do React subscrever)
Como funciona a cache de áudio (chaves provider:voiceId:lang:text)
A correção de coordenadas do chessground é feita via CSS, não é um fork da biblioteca
Disposição dos dados: o que reside onde, o que é symlink, o que sobrevive a reinícios da aplicação

O Que Não Sabe

A memória não contém chaves de API, passwords nem credenciais. Referencia as suas localizações de armazenamento (nomes de atoms no localStorage) mas nunca os valores. A IA gera código que lê as chaves a partir das definições — nunca vê nem manipula os segredos reais.

O Que É Dito à IA

Para além do ficheiro de memória, o Claude Code segue regras integradas no seu sistema:

Não sobre-engenheirar. Fazer apenas as alterações diretamente solicitadas. Uma correção de bug não precisa que o código circundante seja limpo. Três linhas de código semelhantes são melhores do que uma abstração prematura.
Não inventar URLs. Nunca fabricar links ou endpoints.
Ler antes de editar. Nunca propor alterações a código que não tenha lido.
Preferir editar a criar. Não criar novos ficheiros a menos que seja absolutamente necessário.
Sem vulnerabilidades de segurança. Atenção a injection, XSS e problemas do OWASP top 10.
Perguntar quando incerto. Se uma instrução for ambígua, perguntar em vez de adivinhar.
Medir duas vezes, cortar uma. Operações destrutivas (force push, reset —hard, apagar ficheiros) requerem aprovação explícita do humano.

Escrever Bons Prompts

A diferença entre uma interação útil com a IA e uma frustrante está quase sempre no prompt.

Ser específico sobre o que se pretende. Não “corrige o bug” mas “a chave de cache do TTS não inclui o nome do provider, por isso ao mudar de ElevenLabs para Google reproduz áudio em cache do ElevenLabs em vez de gerar áudio novo.”

Incluir contexto que a IA não tem. A IA pode ler o seu código, mas não pode ler a sua mente. “O utilizador reportou que as coordenadas estão invertidas no tabuleiro” é menos útil do que “o CSS em chessgroundBaseOverride.css tem as filas e colunas trocadas — o original do Francisco tinha-as invertidas.”

Declarar as restrições. “Não criar novos ficheiros” ou “usar o padrão de atoms existente” ou “isto precisa de funcionar sem chave de API” dizem à IA onde estão as barreiras.

Dizer o que não se quer. “Não adicionar tratamento de erros para casos que não podem acontecer” ou “não refatorar o código circundante” previne a sobre-engenharia — o modo de falha mais comum da IA.

O padrão é: intenção + contexto + restrições. Domine isso e a IA torna-se dramaticamente mais útil.

Modo de Planeamento: Usar um Claude para Dar Prompts a Outro

O Claude Code tem um “modo de planeamento” que separa o pensar do fazer. No modo de planeamento, a IA lê ficheiros, explora a base de código e produz um plano — mas não escreve código. Revemos o plano, ajustamo-lo, e depois mudamos para o modo de implementação onde a IA executa.

Porque é que isto funciona? Porque a parte mais difícil de qualquer tarefa de programação não é escrever o código. É descobrir que código escrever — quais ficheiros alterar, que padrões seguir, que casos extremos existem. O modo de planeamento dedica toda a atenção a essa questão antes de uma única linha ser escrita.

Deste projeto: quando reestruturámos o menu de Ajuda para adicionar o seletor de Idioma, a conversa em modo de planeamento explorou como funcionam os menus do Tauri, que atoms já existiam, como o visualizador de documentação resolvia caminhos de recursos e qual era a API do diálogo de confirmação. Quando mudámos para implementação, a IA tinha um mapa completo das alterações. Sem falsos arranques.

Essencialmente, está-se a usar uma instância da IA como arquiteto sénior e outra como o programador. Mesmo modelo, papéis diferentes.

Como Funcionam as Sessões

Uma sessão típica é assim:

O humano declara a intenção. “Adicionar nota de caching à secção do KittenTTS.” “Remover a telemetria PostHog.” “As classificações de qualidade estão erradas, eis o que deviam ser.”
A IA lê os ficheiros relevantes. Não adivinha o que está num ficheiro. Lê-o, compreende o estado atual e depois propõe alterações. Múltiplos ficheiros são lidos em paralelo quando são independentes.
A IA faz a alteração. Edições cirúrgicas em ficheiros existentes. Não reescritas — modificações cirúrgicas que preservam tudo em redor.
O humano revê. Cada edição é mostrada antes de ser gravada em disco. O humano aprova, rejeita ou redireciona. “Não, isso é demasiado suave — diz que é genuinamente mau.” “Move esse parágrafo para cima.” “Não era isso que eu queria dizer.”
Commit quando indicado. A IA nunca faz commit por iniciativa própria. O humano diz “commit” ou “commit and push.” Os commits incluem Co-Authored-By: Claude Opus 4.6 — sempre atribuído, nunca escondido.

Janelas de Contexto e Save States

Cada conversa de IA tem uma janela de contexto — a quantidade total de texto que consegue manter em memória de uma vez. Quando a conversa fica suficientemente longa, as mensagens mais antigas são comprimidas para abrir espaço.

Duas estratégias: manter as conversas focadas (uma tarefa por conversa), e usar save states (o Claude Code guarda transcrições como ficheiros JSONL que se podem retomar com o contexto completo restaurado). O ficheiro de memória serve um propósito diferente — é uma base de conhecimento persistente que sobrevive a todas as conversas.

O Que a IA Propõe vs. O Que é Publicado

A primeira sugestão da IA raramente é a versão final. Uma troca típica:

A IA redige algo razoável
O humano diz “demasiado corporativo” ou “sê mais direto” ou “isso está errado, eis porquê”
A IA ajusta
O humano aprova

O gosto, o tom e a decisão final são sempre humanos. A IA trata da velocidade — ler ficheiros, compreender contexto, fazer edições precisas numa base de código que consegue manter em memória. O humano trata do julgamento — o que construir, como deve parecer, quando parar.

Skills e Slash Commands

O Claude Code suporta “skills” — prompts reutilizáveis armazenados como ficheiros markdown no diretório .claude/commands/. Invocam-se com um slash command, como /translate-docs.

Este projeto usa uma skill /translate-docs que automatiza a tradução de documentação para múltiplos idiomas. O ficheiro da skill contém as instruções completas: quais ficheiros traduzir, que formato usar, como lidar com blocos de código e links, que tom manter. Em vez de explicar tudo isso de cada vez, basta escrever /translate-docs e a IA sabe exatamente o que fazer.

As skills codificam processo, não apenas informação. Podem ser construídas para qualquer fluxo de trabalho recorrente: correr testes, fazer deploy, rever PRs, atualizar changelogs.

Princípios de Programação

O documento completo de princípios está no repositório em .claude/01_UNIVERSAL_PRINCIPLES.md. Começou com Clean Code de Robert C. Martin (2008) mais adições para a era da IA. Depois tivemos uma conversa honesta sobre o que ainda se mantém válido e o que já não.

O Que É Intemporal

Nomes que revelam a intenção. Sempre. Para sempre.
As funções fazem uma coisa. O verdadeiro princípio é a coerência, não o tamanho.
Sem efeitos secundários. Continua a ser a fonte da maioria dos bugs.
Os comentários explicam o porquê, não o quê.
Responsabilidade Única. Um módulo deve ter uma única razão para mudar.
Programar para interfaces, não para implementações.
Não engolir erros. Cada erro é informação.
Design emergente: passa todos os testes, sem duplicação, expressa intenção, minimiza complexidade. Por esta ordem.

O Que É Contextual

Estes princípios são sólidos, mas as regras específicas refletem um mundo pré-IA ou específico de uma linguagem. Aplicamos o espírito, não a letra:

DRY. Duplicação que diverge ao longo do tempo é perigosa. Mas extrair cada padrão repetido para uma abstração cria indireção que pode ser pior. Por vezes, três linhas legíveis aqui mesmo são melhores do que uma abstração prematura noutro ficheiro.
Cerimónia estrita de TDD. O princípio — entregar código testado, saber que funciona — é inegociável. A cerimónia — o teste deve existir antes do código — foi desenhada para um fluxo de trabalho onde os humanos escrevem devagar. Escreva testes. Certifique-se de que passam. Se o teste ou o código veio primeiro é menos importante do que se ambos existem.
A Regra do Escuteiro. “Deixar o acampamento mais limpo” — sim. Mas o escuteiro limpava o acampamento, não a floresta inteira. Corrija o que toca. Não refatore a estrutura inteira de um ficheiro porque alterou uma linha nele.

Adições da Era da IA

Orientação baseada em princípios escala melhor do que regras. O princípio permite julgamento; a regra é frágil.
Se o agente construiu, o agente consegue manter. Manter o contexto das conversas e os artefactos. Documentar o processo de construção, não apenas o resultado.
Claro em vez de esperto. O sistema que construiu isto precisa de reconstruir o raciocínio e modificá-lo corretamente. Estrutura explícita vence pequenas abstrações engenhosas.
Isto poderia tornar-se infraestrutura? Uma ferramenta resolve um problema para si. Infraestrutura permite que outros construam em cima. Projete em conformidade.

Onde o Humano Traça a Linha

A IA é uma ferramenta. Uma extraordinariamente boa. Mas há coisas que não faz:

Decisões de produto. Que funcionalidades construir, o que cortar, como a aplicação se deve sentir. “A classificação de qualidade do System TTS deve dizer ‘passável’ porque é genuinamente mau” — isso é um julgamento humano baseado em realmente o ouvir.
Gosto. A IA pode escrever prosa limpa, mas a voz do projeto, a decisão de ser frontal sobre a qualidade, a escolha de creditar o Francisco de forma proeminente — essas são escolhas humanas.
Ética. Remover o PostHog não foi uma tarefa de refatoração. Foi “a página de definições diz que não recolhemos telemetria, mas há uma chave de API PostHog ativa no código. Isto é uma mentira. Corrige.” A IA executou. O humano identificou o problema e preocupou-se com ele.
Xadrez. O tabuleiro não quer saber das suas ferramentas.

Porquê Partilhar Isto

Porque “construído com IA” tornou-se um termo vazio. Toda a gente o diz. Ninguém o mostra. A questão interessante não é se a IA esteve envolvida — é como esteve envolvida, e o que o humano realmente contribuiu.

Esta é a resposta. O humano traz a visão, o gosto, o julgamento e a responsabilidade. A IA traz a velocidade, a memória e a disposição incansável para ler mensagens de erro do Rust às 2 da manhã.

Nenhum dos dois constrói isto sozinho. Ambos são creditados. Esse é o acordo.

En Parlant~ é um fork do En Croissant de Francisco Salgueiro, construído com Claude Code da Anthropic.