Voltar ao blog

Documentação Determinística: Como Transformei a Automação de Design em um Sistema Auditável

Publicado em 2 de julho de 2026

Explorando como transformar conhecimento tácito em processos explícitos e auditáveis através de uma arquitetura de harness para automação de UI/UX com IA.

Durante o mapeamento operacional de um projeto recente, percebi que a qualidade do trabalho automatizado não estava sendo limitada pela capacidade da IA em desenhar, mas pela minha incapacidade de comunicar com precisão o que deveria ser feito. Cada sessão com Claude era uma negociação. Cada resultado era uma surpresa. Cada correção era um passo atrás.

Isso me levou a uma pergunta fundamental: como outras disciplinas (engenharia de software, por exemplo) resolvem esse problema de escala e qualidade? A resposta veio rápido: através de documentação determinística. Não documentação como registro passivo do que foi feito, mas como especificação ativa do que deve ser feito.

Passei minhas férias estudando arquitetura de agentes e sistemas de automação. O resultado foi a construção de um harness para Figma que transforma decisões tácitas em processos explícitos, auditáveis e repetíveis. Mas o verdadeiro aprendizado foi este: a documentação não é um artefato que você cria depois. É a estrutura que permite que a automação funcione.

O Problema Real: Conhecimento Tácito vs. Conhecimento Explícito

Quando você trabalha em design de produtos por mais de uma década, acumula conhecimento que não está escrito em lugar nenhum. Você sabe, por exemplo, que um botão "ghost" é diferente de um botão "destructive" não apenas visualmente, mas semanticamente. Você sabe quando reutilizar um componente e quando criar um novo. Você sabe como manter coerência em uma jornada de múltiplas telas.

Esse conhecimento vive na sua cabeça. E enquanto viver lá, ele não pode ser transferido, auditado ou escalado.

A IA sofre do mesmo problema que um júnior recém-contratado: ela não tem acesso a esse conhecimento tácito. Quando você pede para ela "construir uma tela", ela faz uma série de suposições. Algumas acertam. Outras não. E você passa horas em revisão tentando corrigir o que poderia ter sido especificado desde o início.

A solução não é pedir prompts melhores. É transformar o conhecimento tácito em conhecimento explícito através de documentação estruturada.

A Arquitetura da Documentação: Motor vs. Conteúdo

A primeira decisão foi separar o que é universal do que é específico. No harness que criei, essa separação é física:

O Motor engloba as regras de processo que são válidas para qualquer cliente. Isso inclui o arquivo CLAUDE.md (que define como os agentes devem trabalhar), os templates de componentes, os padrões técnicos e os procedimentos reutilizáveis. Quando aprendo algo que melhora o processo de interpretar wireframes, isso vira uma melhoria no Motor que beneficia todos os projetos.

O Conteúdo reside em diretórios isolados por cliente, contendo o design system específico, as decisões tomadas, os aprendizados do projeto e o estado das jornadas. Isso garante que o conhecimento de um cliente nunca vaze para outro.

Essa separação é crucial porque permite operar múltiplos clientes com o mesmo harness sem misturar contexto. Mas mais importante que isso, permite que o Motor evolua independentemente, transformando correções pontuais em melhorias sistêmicas.

Os Cinco Agentes e a Separação de Responsabilidades

A tentação inicial era ter um único agente fazendo tudo: "leia o wireframe e construa a tela". O problema é que isso mistura duas responsabilidades que precisam ser separáveis: decidir o que construir e executar a construção.

Se o mesmo agente decide e executa na mesma respiração, não existe ponto de checagem no meio. Um erro de interpretação vira automaticamente um erro de execução, sem chance de revisão.

Por isso estruturei o harness com cinco agentes especializados, cada um com escopo restrito:

O Interpreter recebe wireframes e histórias de usuário. Sua única responsabilidade é decidir o que construir. Ele não constrói nada. Ele analisa cada elemento do wireframe e pergunta: esse elemento já existe como componente? Posso reutilizá-lo direto? É parecido o suficiente para criar uma variante? Ou é realmente novo?

Mas aqui está o detalhe crítico: o Interpreter não apenas decide. Ele documenta por que decidiu. Ele lista os componentes que considerou e por que os descartou. Essa documentação fica visível para aprovação humana antes de qualquer construção acontecer.

O Builder executa exatamente o que foi decidido pelo Interpreter. Ele tem permissão de escrita no Figma e constrói uma tela por vez. Mas ele não decide nada. Ele recebe um plano estruturado e o executa. Se o plano está errado, a culpa não é dele. O ponto de checagem já passou.

O Documenter registra o que foi construído em arquivos Markdown. Ele transforma o conhecimento implícito em conhecimento explícito. Mas ele só trabalha com componentes que foram validados, nunca com rascunhos.

O Auditor verifica a consistência técnica. Ele pergunta: os tokens estão hardcoded? A nomenclatura está correta? Existem componentes duplicados? Ele trabalha com padrões técnicos documentados no arquivo COMPONENT_STANDARDS.md.

O Validator verifica se o resultado final cumpre o objetivo semântico da jornada. Ele pergunta: as telas construídas resolvem o problema que o wireframe e a história de usuário descrevem? Existe coerência entre as telas? Ele trabalha com a história de usuário e o wireframe original como referência.

A separação de responsabilidades não é apenas organizacional. É técnica. Claude Code tem uma restrição importante: subagentes não conseguem confirmar prompts de aprovação interativos. Isso significa que qualquer ferramenta de escrita usada por um subagente é tratada como ação que precisa ser explicitamente permitida com antecedência. Essa restrição técnica valida a separação decisão/execução de forma natural.

A Lógica de Reuso: Evitando a Duplicação de Componentes

O núcleo da eficiência do harness está em sua capacidade de evitar a duplicação de componentes. Essa é a dor real que vejo em projetos legados: 15 variações de um botão que deveria ter 3, componentes com nomes diferentes que fazem a mesma coisa, nomenclaturas confusas.

Para cada elemento do wireframe, o Interpreter avalia três camadas de correspondência contra os componentes já documentados:

Estrutural: O elemento tem a mesma composição interna que um componente existente? Os mesmos sub-elementos, na mesma disposição?

Funcional: Tem o mesmo propósito dentro da jornada? Resolve o mesmo tipo de problema?

Variante Coberta: A diferença encontrada (um estado, um conteúdo diferente) já existe como variante documentada, ou é nova?

O resultado dessa avaliação sempre cai em uma de três categorias:

• Reuso Direto: O componente existe e pode ser usado exatamente como está
• Nova Variante: O componente existe, mas precisa de uma variante nova para cobrir esse caso de uso
• Componente Novo: Nenhuma correspondência real foi encontrada

Essa disciplina só funciona porque existe um template fixo de documentação de componente. Cada componente tem campos específicos como "Quando usar", "Quando NÃO usar" e "Componentes relacionados". São exatamente esses campos que o Interpreter consulta para decidir se um candidato serve ou não.

Sem essa documentação estruturada, o Interpreter teria que adivinhar. Com ela, ele decide com base em critérios explícitos.

A Memória: Transformando Volatividade em Persistência

Claude não retém nada entre sessões por padrão. Cada nova conversa começa do zero. Isso é um problema fundamental para automação de longo prazo: como você garante que uma correção feita hoje não será repetida como erro amanhã?

A solução é simples: tudo que precisa persistir vira arquivo versionado.

Journey-state.md é a memória de curto prazo de uma jornada. Quando o Builder constrói a primeira tela, ele relata o que fez em texto. Eu (ou a sessão principal) registro esse relato no journey-state.md. Quando o Builder é chamado de novo para a segunda tela, ele recebe o journey-state.md atualizado como parte do contexto. Isso garante que o mesmo tipo de elemento seja resolvido de forma consistente em telas diferentes.

Memory/decisions.md registra decisões não-óbvias. Por exemplo: "usar variante ghost, não destructive, por pedido do cliente". Isso evita que a mesma correção seja feita várias vezes em sessões futuras.

Memory/learnings.md captura padrões que se repetem e merecem virar regra permanente. Se descobrirmos que componentes de formulário sempre precisam de um label específico, isso vira uma regra no Motor, não uma decisão repetida.

Memory/component-changelog.md é o histórico cronológico de criação e alteração de componentes oficiais. Não é apenas um registro, é auditoria.

Essa abordagem transforma cada correção feita hoje em uma regra que evita o mesmo erro amanhã. A documentação não é um artefato passivo. É a estrutura viva que permite que o sistema aprenda.

A Ordem das Coisas: Por Que Validator Vem Antes de Documenter

Essa é uma decisão de ordem que parece pequena, mas evita um problema sério. Se o Documenter registrasse um componente novo no design system logo após o Builder criá-lo, antes de qualquer validação semântica, correria-se o risco de oficializar um componente que nasceu de uma interpretação errada do wireframe.

Uma vez oficial, esse componente passaria a ser oferecido como opção de reuso em tarefas futuras, propagando o erro.

Por isso existe um estágio intermediário: componentes novos entram primeiro em design-system/components/_draft/ (rascunho). Existem no Figma e estão documentados, mas não são oferecidos pelo Interpreter como opção de reuso até serem promovidos para a pasta oficial, o que só acontece depois da aprovação do Validator.

Essa ordem não é arbitrária. É uma barreira que impede que erros de interpretação se tornem parte permanente do design system.

Padrões Técnicos: Tornando Componentes Legíveis para Máquinas

Documentar o que um componente é (nome, variantes, tokens) não basta. É preciso garantir que ele foi construído de um jeito que permite ao modelo (e ao MCP) reconhecê-lo de forma confiável.

Por isso existe o arquivo COMPONENT_STANDARDS.md, com regras como:

• Nomenclatura por função, não por aparência. Card/Product, nunca Card/Blue
• Diferenças de estado viram variantes do mesmo componente, nunca componentes separados
• Nenhum valor de cor, espaçamento ou tipografia pode estar hardcoded. Sempre vinculado a um token
• Componentes aninhados precisam ser instâncias vinculadas, nunca cópias soltas
• Uso obrigatório de Auto Layout. Sem isso, a extração de estrutura via MCP fica ambígua

Esses padrões não existem para satisfazer purismo técnico. Existem porque tornam os componentes legíveis para o harness. Sem eles, mesmo com boa documentação em Markdown, o Figma real poderia estar construído de um jeito que o MCP não consegue interpretar de forma confiável.

A documentação técnica não é um luxo. É uma necessidade funcional.

Isolamento e Segurança: Documentação Como Barreira

Como a conta Figma é corporativa única, com os projetos de cada cliente organizados internamente dentro dela, o isolamento entre clientes não é feito por credencial separada. É feito por configuração e documentação.

Cada projeto tem um arquivo PROJECT.md que declara explicitamente o file-key do Figma daquele cliente. Antes de qualquer operação de escrita, o Builder confirma que o destino corresponde ao file-key declarado. Se não corresponder, ele para e alerta. Nunca prossegue.

Isso significa que a proteção contra "escrever no projeto errado" é uma regra de processo documentada, não uma barreira técnica de permissão. Exige disciplina, mas é suficiente dado que há um único token.

A memória do projeto (decisões, aprendizados, changelog) é sempre isolada por projeto, nunca compartilhada entre clientes, por razão de confidencialidade. Essa isolação também é documentada.

O Que Ficou de Fora: Decisões Conscientes

Nem toda lacuna identificada precisa ser resolvida agora. Algumas decisões foram adiadas de propósito, com o trade-off já registrado:

Onboarding de design systems legados e desorganizados é tratado como projeto totalmente separado, com processo próprio, porque tem cadência e risco muito diferentes do uso do dia a dia.

Rollback automatizado no Figma é manual via histórico nativo. O estágio rascunho/oficial já reduz bastante a necessidade disso.

Múltiplos aprovadores: por ora, um único humano aprova. Mas o campo já existe nos registros para facilitar expansão futura sem retrabalho de formato.

Responsividade e breakpoints: campo já previsto no template de componente, mas sem processo funcional até haver um caso real que exija.

Essas decisões não são fraquezas. São reconhecimentos de que a perfeição é inimiga do funcional. A documentação deixa claro o que foi deixado de fora e por quê, permitindo que futuras iterações sejam informadas.

Conclusão: Documentação Como Infraestrutura

A automação de design não falha porque a IA não consegue desenhar. Falha porque o conhecimento que deveria guiar a IA está preso na cabeça das pessoas. Transformar esse conhecimento tácito em conhecimento explícito, estruturado e auditável é o trabalho real.

A documentação determinística não é um artefato que você cria depois de automatizar. É a infraestrutura que permite que a automação funcione. É o que transforma a IA de uma ferramenta imprevisível em um motor determinístico de execução.

O papel do designer está mudando. Deixamos de ser artesãos de pixels para nos tornarmos arquitetos de sistemas. E a documentação é o material de construção.