code-tour

Visão geral do code-tour skill

O que o code-tour cria

O code-tour skill ajuda um agente de IA a produzir arquivos JSON .tour para a extensão VS Code CodeTour. Um tour é um passo a passo guiado que conecta etapas explicativas a arquivos e números de linha reais, normalmente armazenado em .tours/. O skill foi pensado para exploração estruturada de repositórios, não para edição de código: seu limite principal é criar apenas arquivos de tour e evitar alterações no código-fonte.

Melhor uso para redação técnica e onboarding

Use code-tour em trabalhos de redação técnica quando você precisa de um caminho de onboarding, guia para contribuidores, walkthrough de arquitetura, tour de revisão de PR, roteiro de revisão de segurança, trilha de análise de causa-raiz ou explicação do tipo “como isso funciona”. Ele funciona melhor quando o leitor tem uma persona clara: novo engenheiro de backend, mantenedor de frontend, revisor, responsável por incidentes, staff engineer ou stakeholder não técnico que precisa de um percurso curado pelos detalhes de implementação.

Por que isso é melhor do que um prompt genérico

Um prompt genérico pode resumir arquivos de forma solta. O code-tour skill direciona o agente para um artefato utilizável: etapas narrativas voltadas a uma persona, com âncoras concretas em arquivos e linhas. Isso importa porque um tour precisa ser navegável no VS Code, deve referenciar caminhos existentes e precisa explicar por que cada parada é importante, em vez de apenas despejar um resumo de pastas. A saída útil não é “o que existe no repo”; é “onde este leitor deve clicar primeiro, depois, e por quê”.

Pontos a considerar antes de instalar

O skill tem um SKILL.md focado e não inclui scripts, regras ou pacotes de referência adicionais. Isso torna o code-tour install leve, mas também significa que a qualidade depende bastante do acesso ao repositório e do nível de detalhe do prompt. Ele funciona melhor quando o agente consegue inspecionar a árvore de arquivos, o README, arquivos de configuração e pontos de entrada do código-fonte. Não é uma boa escolha se você quer apenas documentação em texto, diagramas Mermaid, edições no código-fonte ou um tour para arquivos que o agente não consegue ler.

Como usar o code-tour skill

Instalação do code-tour e contexto do repositório

Instale a partir do repositório de origem com sua ferramenta de skills, por exemplo:

npx skills add alirezarezvani/claude-skills --skill code-tour

Após a instalação, verifique o caminho do skill se necessário: engineering/code-tour/skills/code-tour/SKILL.md. No projeto de destino, o agente deve primeiro inspecionar o diretório raiz, README.md, configurações de pacote ou build e os um ou dois primeiros níveis de pastas antes de rascunhar. O tour deve ser salvo como um arquivo JSON .tour em .tours/, compatível com a extensão VS Code CodeTour.

Entradas de que o skill precisa

Para um bom code-tour usage, forneça cinco coisas: o público, o objetivo, o escopo, a profundidade desejada e quaisquer arquivos ou nomes de features que precisam ser incluídos. Pedido fraco: “faça um tour deste repo.” Pedido forte: “Crie um CodeTour para um novo engenheiro de backend explicando o ciclo de vida da requisição de login, do registro da rota à validação, lógica de serviço, acesso ao banco de dados e tratamento de erros. Mantenha entre 8 e 12 etapas e ancore cada uma em arquivos e linhas reais.”

Se o tour for para redação técnica, adicione a finalidade de publicação: documento de onboarding, apoio a release notes, guia interno de arquitetura, material de revisão ou artefato de aprendizado pós-incidente.

Fluxo de trabalho sugerido para um primeiro tour

Comece pela descoberta, não pela escrita. Peça ao agente para identificar o propósito do projeto, linguagens, frameworks, pontos de entrada e diretórios importantes. Depois, escolha um caminho narrativo: da configuração à primeira feature, da requisição à resposta, da ação na UI à API, do sintoma do bug à causa-raiz ou do diff do PR ao risco. Só então ele deve gerar o arquivo .tour. Essa sequência reduz âncoras quebradas e evita um “tour de pastas” superficial, que apenas nomeia diretórios sem ensinar como o sistema funciona.

Padrão prático de prompt

Use um prompt como:

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

Isso funciona porque dá ao agente um quadro de decisão, não apenas um assunto.

FAQ do code-tour skill

Quando devo usar code-tour em vez de documentação?

Use code-tour quando a navegação pelo código é o próprio produto. A documentação tradicional é melhor para conceitos, políticas ou referência de API. Um CodeTour é melhor quando os leitores precisam abrir arquivos em sequência e entender relações entre rotas, serviços, testes, configurações e pontos de entrada.

Iniciantes podem usar o code-tour skill?

Sim, mas iniciantes devem limitar o pedido. Peça primeiro um tour pequeno: uma feature, um caminho de bug ou um recorte de arquitetura. Pedidos amplos como “explique toda a base de código” costumam gerar tours ruidosos, a menos que o repositório seja minúsculo. Para repositórios muito pequenos, com menos de alguns poucos arquivos de código-fonte, um tour rápido e direto geralmente é suficiente.

O code-tour edita o código da minha aplicação?

Não. A saída esperada é um arquivo JSON .tour, normalmente colocado em .tours/. O limite explícito do skill é evitar modificações no código-fonte. Se seu fluxo precisa de correções de código, testes ou refatorações, use primeiro outro skill de engenharia e depois use code-tour para documentar o caminho resultante.

O que pode prejudicar um bom resultado com code-tour?

Os maiores bloqueios são falta de acesso ao repositório, público vago, ausência de limite de escopo e caminhos de arquivo não verificados. As etapas do CodeTour dependem de âncoras reais. Se o agente não consegue ler os arquivos de destino ou se os números de linha mudam muito durante edições ativas, gere o tour depois que o código estabilizar ou peça primeiro âncoras por caminho e refine as linhas depois.

Como melhorar o code-tour skill

Crie prompts de code-tour específicos por persona

A forma mais rápida de melhorar a saída do code-tour é nomear o leitor. “Novo contribuidor” gera um caminho diferente de “revisor de segurança” ou “redator técnico preparando material de onboarding”. Inclua o que o leitor já sabe e o que ele precisa conseguir fazer depois do tour. Isso muda a seleção das etapas, a profundidade da explicação e o vocabulário.

Peça narrativa, não inventário

Um tour fraco lista arquivos. Um tour forte conta uma história: onde a execução começa, como os dados se movem, onde as decisões acontecem, onde estão os riscos e quais testes comprovam o comportamento. Peça ao agente para conectar cada parada à anterior e incluir uma frase de “por que isso importa” em cada etapa. Isso é especialmente valioso para redação técnica porque o artefato final se torna ensinável, não apenas clicável.

Itere depois da primeira saída

Após o primeiro rascunho .tour, revise três pontos: caminhos de arquivo quebrados ou imprecisos, etapas amplas demais e transições ausentes. Depois, peça revisões direcionadas: “divida a etapa 4 em etapas de rota e serviço”, “adicione o teste que cobre esse comportamento” ou “reduza o detalhe de frontend e foque no tratamento de erros da API.” Iterar costuma ser mais eficaz do que pedir um tour perfeito de todo o repo em uma única tentativa.

Valide as âncoras antes de compartilhar

Antes de publicar um CodeTour, abra-o no VS Code com a extensão CodeTour e confirme que cada caminho e linha leva ao lugar esperado. Se o repositório muda com frequência, prefira tours ligados a arquivos de arquitetura estáveis, testes ou pontos de entrada, e gere novamente os números de linha depois de grandes refatorações. Isso mantém o code-tour skill útil como material de onboarding, em vez de virar um mapa desatualizado.