O(a) senhor(a) pede ao Claude Code para fazer um jogo de xadrez no navegador. Abre a página: o tabuleiro está lá, as peças posicionadas, um peão segue direitinho o mouse. Dá para jogar. Mas, como teste, arrasta o peão direto três casas para a frente - e ele fica lá. Depois tenta mover as pretas duas vezes seguidas. A página de novo não reclama de nada.
Até essas duas jogadas, o projeto parecia quase pronto. Agora fica claro que o essencial ainda não funciona: ninguém verifica as regras. Dá para pedir ao agente que bloqueie esse movimento do peão. Mas em seguida vai ser preciso tratar da vez de cada lado, do xeque, do roque, da promoção do peão. Depois de cada correção sobra a mesma pergunta: qual condição ainda ficou de fora?
Nesse momento vale a pena parar e procurar código pronto para essa tarefa. As regras do xadrez já estão implementadas na biblioteca chess.js. Basta passar a ela uma jogada e receber o resultado da verificação. Assim, o seu próprio código fica responsável por uma ligação clara: pegar a ação feita no tabuleiro, verificá-la pela biblioteca e mostrar a posição correta das peças.
Falta entregar a biblioteca ao navegador e ligá-la ao funcionamento da página. Uma das formas é carregá-la por um link via CDN. A seguir vemos como isso funciona e por que o simples aparecimento de um link no código ainda não significa que o peão parou de andar para onde quiser.
O que a biblioteca faz
Uma biblioteca é código de outra pessoa que o(a) senhor(a) conecta ao próprio projeto para não escrever de novo o que já foi escrito. chess.js é exatamente esse caso: ela sabe como cada peça se move, o que são xeque e roque, consegue listar todas as jogadas permitidas a partir da posição atual e dizer se a partida acabou.
E aqui é fácil cair numa armadilha: conectar a biblioteca e esperar que o jogo simplesmente funcione. Não vai funcionar. A biblioteca guarda as regras e a posição da partida na própria memória, ela não desenha nada e nem imagina que a página tem um tabuleiro.
| Quem | Pelo que é responsável | O que acontece sem isso |
|---|---|---|
A biblioteca chess.js | as regras e a posição atual da partida: quais jogadas são possíveis, de quem é a vez, se o jogo acabou | ninguém verifica as jogadas, o tabuleiro permite qualquer coisa |
| Interface da página | o tabuleiro, as peças, o arrastar, o destaque das casas | não há o que jogar: as regras existem, mas não há como aplicá-las |
| Código de ligação | passa a jogada feita para a biblioteca e redesenha o tabuleiro conforme a resposta dela | as regras e a imagem vivem separadas e não se influenciam |
Veja o que acontece numa jogada comum. O(a) senhor(a) arrasta o peão de e2 direto para e5. A interface percebe o arraste, o código de ligação pergunta à biblioteca "essa jogada é permitida?", a biblioteca responde "não" - e o código de ligação devolve a peça a e2. Se ninguém fizer essa pergunta, o peão fica tranquilamente em e5: nada impede a página de desenhá-lo ali.
As duas situações terminam na mesma ação: o código de ligação mostra a posição vinda da biblioteca. Depois de uma jogada permitida, ela já está atualizada; depois de uma proibida, continua a mesma, e é por isso que a peça volta à casa de origem.
Daí vem uma conclusão sobre como formular o pedido. O pedido "conecte o chess.js" pode ser cumprido ao pé da letra - vai aparecer uma linha de carregamento, e só. O que é preciso pedir é a ligação: a jogada feita no tabuleiro vai para a biblioteca, a resposta da biblioteca decide se a peça se move, e a posição depois da jogada vem do estado da biblioteca, não de onde o(a) senhor(a) soltou o mouse.
É fácil confundir os dois, porque ambos são "conectados". Um skill muda o comportamento do próprio agente - amplia suas instruções, dá a ele uma nova capacidade. Uma biblioteca não tem nada a ver com o agente: é código dentro da sua aplicação, que roda no navegador do usuário. O agente pode conectá-la, mas depois ela funciona sem ele também.
Como o navegador recebe o código via CDN
O arquivo da biblioteca precisa vir de algum lugar. Dá para baixá-lo e colocá-lo junto da própria página, ou apontar no código da página um link para esse arquivo em um serviço externo. Para isso costuma-se usar uma CDN (Content Delivery Network, rede de entrega de conteúdo). É uma rede de servidores que entregam arquivos aos usuários a partir de lugares diferentes. Via CDN são entregues, por exemplo, imagens, estilos e bibliotecas JavaScript. No nosso exemplo, o serviço jsDelivr entrega o arquivo da biblioteca.
Quando o(a) senhor(a) abre a página, o navegador lê o código dela e encontra o link para a biblioteca. Ele solicita o arquivo nesse endereço, faz o download e depois executa o código da página que usa a biblioteca. A biblioteca roda no navegador do usuário. A CDN entrega o código dela; a verificação das jogadas de xadrez já acontece no seu próprio dispositivo.
A moldura no diagrama separa o navegador do serviço externo. Depois do carregamento, a biblioteca fica dentro da página: o código de ligação fala com ela ali mesmo. Não é preciso enviar cada jogada para a CDN.
Para o chess.js, a conexão fica assim:
<script type="module">
import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'
const chess = new Chess()
console.log(chess.fen())
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>Aqui há três detalhes importantes. O primeiro é type="module". A biblioteca chega como um módulo ES, e a única forma de tirar Chess dela é por importação; uma tag comum <script src="..."> simplesmente não vai processar esse mesmo arquivo - ela vai falhar no export embutido. Algumas bibliotecas também têm uma forma antiga de distribuição, sem módulos: nesse caso uma tag comum basta, e uma variável global aparece sozinha na página. O chess.js não tem esse tipo de build, então só existe uma opção.
O segundo detalhe é o número da versão direto no endereço, chess.js@1.4.0. A forma de conectar e os nomes dos métodos vêm da documentação da versão exata que está no link. Um endereço sem número mais cedo ou mais tarde vai levar a outro arquivo, e o código escrito conforme a documentação antiga vai quebrar.
E o terceiro detalhe, o mais discreto, é o sufixo /+esm no fim do endereço. Não é enfeite, é um pedido à CDN para montar o arquivo justamente na forma de módulo: sem ele, o mesmo endereço traz outro build, e o import não encontra nada.
Para confirmar que a biblioteca realmente carregou, não é preciso montar o jogo inteiro: acrescente algumas linhas no mesmo <script type="module"> e abra o console do navegador (a aba Console no painel de desenvolvedor, F12 ou Ctrl+Shift+I):
// um peão branco não vai direto de e2 para e5
try {
chess.move('e5')
} catch (error) {
console.log('jogada rejeitada:', error.message) // Invalid move: e5
}
chess.move('e4') // mas essa jogada a biblioteca aceita
console.log(chess.turn()) // b, vez das pretasA posição inicial no console, a jogada rejeitada e a vez das pretas depois de e4 - isso significa que o arquivo chegou e as regras estão funcionando. Depois disso resta ligá-las ao tabuleiro.
E uma ressalva, para não criar ilusões. A CDN não elimina a dependência da rede. O navegador pode reaproveitar o arquivo do cache, a cópia que ele mesmo guardou, então não é obrigatório baixá-lo de novo toda vez que a página é aberta. Mas se não houver uma cópia adequada e a CDN estiver indisponível, a biblioteca não vai carregar e o jogo não conseguirá trabalhar com as regras dela.
Um erro nessa etapa quase sempre está na própria conexão: endereço errado, versão errada, forma errada de importação. Não reescreva a linha ao acaso - peça ao agente para conferi-la e descobrir exatamente o que divergiu. Uma verificação curta em vez de meia hora testando variações.
Como isso funciona junto com o Claude Code
O pedido "conecte a biblioteca via CDN" deixa para o agente várias decisões: de onde tirar o arquivo, qual versão escolher, como carregá-la nessa página e como confirmar o resultado. É mais prático deixar essas decisões explícitas já no pedido. A seguir estão prompts para situações diferentes; não é preciso enviar todos em sequência.
Escolher o link para conectar
Se o agente sugerir uma biblioteca, peça primeiro que ele descubra como conectá-la ao seu projeto. Assim o(a) senhor(a) terá um endereço concreto e uma explicação de onde ele veio.
Veja como minha página está estruturada e se o chess.js já está conectado.
Procure na documentação da biblioteca e do jsDelivr um jeito de carregar via CDN
adequado para o navegador. Sugira uma URL com uma versão específica e explique
as partes do endereço. Traga links para a documentação. Não mude o código ainda.
Se não conseguir checar a documentação, diga isso.Na resposta, procure o número da versão, a forma de conexão e o motivo da escolha. Só um "aqui está o link que funciona" não basta: por ele não dá para saber se o agente conferiu o endereço com a documentação nem se o arquivo serve para a sua página.
Conectar a biblioteca ao tabuleiro
Quando o endereço estiver escolhido, dê ao agente uma tarefa com resultado visível. Para uma página HTML simples, dá para já indicar que o(a) senhor(a) quer manter a forma existente de rodar a página.
Conecte o chess.js pelo endereço de CDN escolhido, com versão fixa.
Mantenha a forma existente de rodar a página. Ligue a biblioteca
ao tabuleiro: passe a ela cada jogada e mostre a posição a partir do estado dela.
Se a jogada for inválida, devolva a peça à casa de origem.
Mostre onde a conexão foi adicionada e onde a resposta da biblioteca é tratada.Aqui há dois resultados separados: o navegador recebeu a biblioteca, e as ações no tabuleiro passaram a acontecer segundo as regras dela. Ao pedir para ver os dois pontos no código, o(a) senhor(a) consegue ver exatamente o que o agente adicionou.
Verificar o resultado no navegador
A presença do link no HTML só confirma que o arquivo foi editado. O próximo pedido ajuda a verificar o carregamento em si e o comportamento do jogo.
Abra a página e verifique o carregamento do chess.js na aba Network
do painel de desenvolvedor. Verifique erros no Console. Depois, a partir da
posição inicial, tente e2-e5: a jogada deve ser rejeitada, o peão deve ficar em e2.
Em seguida faça e2-e4: a jogada deve passar, a vez deve ir para as pretas.
Relate o que observou em cada etapa. Se você não tiver acesso a um navegador,
me dê passos curtos de verificação e indique que você mesmo não verificou.
Na aba Network aparecem as requisições de rede da página, no Console, as mensagens e erros do código dela. Se o arquivo carregou, mas o peão continua indo para e5, é no tratamento da jogada que se deve procurar a causa. Só trocar o link da CDN não conserta essa ligação.
Resolver um erro de carregamento
Em caso de falha, passe ao agente o texto exato do erro no Console e o endereço da requisição que falhou no Network. Assim ele pode verificar a causa específica, em vez de testar links ao acaso.
Depois de conectar a biblioteca, a página apresenta um erro.
Texto do Console: [cole a mensagem inteira].
URL e resultado da requisição no Network: [cole o endereço e o status].
Verifique se o arquivo está acessível, se o formato dele serve para o nosso import
e se os nomes no código correspondem à documentação da versão escolhida.
Primeiro diga a causa com base nesses dados, depois faça a correção mínima
e repita a verificação. Não mude ao mesmo tempo a CDN, a versão e o código do jogo.Substitua o texto entre colchetes pelos seus próprios dados. Se não houver nenhuma requisição da biblioteca no Network, diga isso também: é uma pista útil. Depois da correção, repita a verificação das duas jogadas para confirmar que toda a ligação voltou a funcionar.
Prever a indisponibilidade da CDN
Se a biblioteca não carregar, um tabuleiro com aparência ativa pode criar a falsa impressão de que ainda dá para jogar. Peça ao agente para deixar esse estado claro ao usuário.
Trate a situação em que não foi possível carregar o chess.js da CDN.
Enquanto a biblioteca não estiver pronta, não permita fazer jogadas. Em caso de erro, mostre
uma mensagem clara e a possibilidade de tentar carregar a página de novo.
Verifique o comportamento com a requisição à CDN bloqueada e depois
de remover o bloqueio. Considere o cache: só desligar a rede pode deixar
disponível uma cópia carregada antes. Descreva exatamente como testou a falha.É mais prático fazer essa verificação separadamente de uma partida comum. No fim, o(a) senhor(a) deve ver dois estados claros: a biblioteca está disponível e as jogadas são verificadas; o carregamento falhou e a página explica por que ainda não dá para jogar.
GO TO FULL VERSION