Design para Código #5: Usando IA para Construir um Sistema de Design

Eu dei a especificação do componente Switch para Claude e a apontei para variables.css. O que voltou — variantes CVA, Primitivas Radix, forwardRef, controlado e não controlado, ambos conectados — foi genuinamente bom. Melhor do que meu primeiro rascunho teria sido. Eu enviei isso naquela tarde sem mudar muito.

Isso foi em algum momento de março. Em abril, eu havia escrito três scripts shell cuja única função era pegar Claude relatando coisas como feitas quando não estavam.

Não estou mentindo sobre o código. O código ainda era bom.

O que eu construí para Claude

Antes de qualquer um dos problemas, há a configuração. Eu passei mais tempo construindo infraestrutura para o fluxo de trabalho da IA do que esperava — mais do que queria, honestamente.

A questão central: Claude não sabe nada sobre meu código-base a menos que eu diga. E o código-base é específico de maneiras que importam. Variáveis de token personalizadas, um padrão de componente particular (Radix + CVA + forwardRef + apenas exportações nomeadas), uma convenção de nomenclatura, uma lista de exatamente onze arquivos de distribuição que sync-tokens gera a partir de uma fonte JSON. Nada disso está nos dados de treinamento de ninguém.

Então eu construí llms.txt. Na verdade, seis variantes dele:

• llms.txt (raiz) — visão geral da biblioteca, instalação, referência rápida
• tokens/llms.txt — especificidades do pacote de tokens, nomes e categorias de variáveis
• cli/llms.txt — referência de comando CLI, flags, resolução de dependências
• public/llms.txt — leve, para ferramentas de IA que anexam contexto por URL
• public/llms-full.txt — referência completa da API do componente com tipos de prop
• public/llms-cli.txt — formato de fluxo de trabalho CLI, caminhos de importação já convertidos para @/components/ui/

A última existe porque os caminhos de importação são diferentes quando você copiou os arquivos de origem localmente via CLI, e eu me cansei de Claude dar aos usuários o caminho errado em exemplos de código. Pequena coisa. Levou um tempo para notar.

Além dos arquivos llms.txt, há CLAUDE.md na raiz do repositório. Ele carrega automaticamente quando eu inicio uma sessão de Código Claude — o manual de operação. Regras de codificação, regras de uso de tokens, as restrições absolutas. Os padrões que não são óbvios, como "use items-center sempre — nunca items-start com um mt-0.5 de deslocamento manual." Arquivos de habilidade para fluxos de trabalho recorrentes, para que eu não reexplique a mesma lista de verificação pré-publicação toda vez. Um diretório de memória com fatos que persistem entre as sessões — coisas como "não adicione Co-Authored-By aos commits de repositórios públicos" (o repositório está sob meu nome; o registro de propriedade importa para a licença MIT).

Eu não construí tudo isso de uma vez. A maior parte veio depois que algo deu errado.

42 Componentes

Para o código do componente, o fluxo de trabalho é genuinamente útil. Dada a especificação, o arquivo de token relevante e os padrões estabelecidos, Claude produz algo que posso ler, entender e enviar com talvez 10-20% de edição. A estrutura da variante CVA, a fiação primitiva Radix, os tipos TypeScript — ele lida com tudo isso corretamente quando o contexto está configurado corretamente.

42 componentes em 7onic. Eu construí a maioria deles dessa forma.

Onde é menos confiável: qualquer coisa que exija manter o estado completo do código-base de uma só vez. "Essa mudança quebra mais alguma coisa?" é difícil para uma ferramenta que só vê o que você explicitamente mostrou. Eu aprendi a ser específico sobre o escopo e parei de esperar que ele pegasse implicações entre arquivos por conta própria. Essa parte eu me adaptei. O código do componente permaneceu bom.

O problema estava em outro lugar completamente.

O Dia v0.3.0

O ciclo de lançamento v0.3.0 está documentado em um Registro de Decisão de Arquitetura agora. Eu o mantenho não porque gosto da leitura, mas porque o padrão que ele descreve continua recorrendo em formas mais sutis e ajuda ter isso escrito em algum lugar.

Em um dia — estávamos finalizando a migração de mudança quebradora que converteu 22 componentes compostos em exportações nomeadas — eu recebi três relatórios separados e confiantes de que algo havia sido verificado ou concluído. Nenhum deles estava correto.

Os detalhes variavam a cada vez. Uma vez, Claude citou os resultados de verificação de um subagente como seus próprios sem reexecutar a verificação. Uma vez, a contagem de substituições que ele relatou não correspondia ao que estava realmente nos arquivos — ele havia contado ocorrências de texto em vez de verificar a correção estrutural. Uma vez, "tecnicamente verificado" significava que o código compilou, quando o que eu precisava era de confirmação de que a saída renderizada correspondia à saída esperada em todos os modos.

Cada vez, a linguagem era a mesma: concluído, verificado, tudo passando. Cada vez eu acreditei e encontrei o problema depois.

O ADR chama isso de "완료 선언 시 실측 증거 결여" — reivindicando conclusão sem medição real. O problema não era que Claude estava errado. É que ele estava confiante e errado de uma maneira que parecia exatamente como confiante e certo. Nada na resposta distinguia entre eles.

Depois do terceiro, eu fechei o laptop e fui dar uma volta. Quando voltei, escrevi um registro de decisão de arquitetura, que é aparentemente o que eu faço quando preciso garantir que não repita um erro.

O que foi construído depois

A primeira coisa foi uma proibição de vocabulário. CLAUDE.md §4 agora classifica palavras como "완료", "검증됨", "tudo limpo", "PASS" — usadas sem saída direta da ferramenta anexada — como relatórios falsos. O formato exigido para qualquer reivindicação de conclusão é:

✓ [item] — 도구: `[command]` → `[output line verbatim]`

Se o comando e a saída não puderem ser citados, a resposta exigida é "⚠ 검증 안 함" com uma razão declarada. Não é um modo de falha a ser ocultado — apenas um honesto "eu não verifiquei".

A segunda foi um bloqueio para commits. scripts/hooks/verify-artifact-gate.sh bloqueia commits que tocam arquivos de origem da UI a menos que um arquivo de evidência específico exista em /tmp/ — escrito pelo script de auditoria ao vivo, com timestamp, expirando em 15 minutos. Sem arquivo de evidência, sem commit. O gancho lê o arquivo. Ele não lê a mensagem.

A terceira foi scripts/hooks/hundred-percent-detector.sh, que escaneia prompts recebidos em busca de frases como "100%", "전수", "완벽하게". Quando qualquer uma aparece, força a sessão para o protocolo /100-percent-verify — cinco fases bloqueadas, cada uma exigindo saída real da ferramenta antes de avançar.

A que eu adicionei por último — depois que percebi o quão perto eu cheguei de deixar isso acontecer — foi scripts/hooks/manual-only-gate.sh. Ele bloqueia npm publish, gh workflow run publish e npm dist-tag a menos que um arquivo de token de autorização de uso único exista em .claude/gates/. Eu estava executando um fluxo de trabalho de verificação e notei que a etapa de publicação estava sentada bem ao lado das etapas de verificação, e que nada estrutural impedia Claude de executá-la. Os comandos agora são apenas manuais. Isso não é uma restrição que Claude contorna; é um arquivo que não existe até que eu o crie.

Eu também inverti o modelo de propagação de documentos na mesma época. Anteriormente, Claude atualizava automaticamente a documentação sempre que eu mudava o código. Durante o desenvolvimento ativo, isso significava que os docs estavam sendo reescritos para iterações que eu abandonei dez minutos depois. O novo modelo é baseado em aprovação: Claude escaneia o git diff no momento do commit, propõe um plano de propagação, espera por um sim. Mais lento, mas os docs param de refletir decisões que eu já reverto.

Onde ainda desmorona

Os ganchos cobrem o padrão específico que quebrou o v0.3.0. Outras coisas ainda dão errado.

A verificação é o modo mais perigoso — precisa de forçamento explícito para produzir ações.