Tour de Código

Crie arquivos CodeTour .tour para percorrer bases de código que abrem diretamente em arquivos e intervalos de linhas reais. Os tours residem em .tours/ e são destinados ao formato CodeTour, não a anotações Markdown ad hoc.

Um bom tour é uma narrativa para um leitor específico:

• o que ele está vendo
• por que isso importa
• qual caminho ele deve seguir em seguida

Crie apenas arquivos JSON .tour. Não modifique o código-fonte como parte desta habilidade.

Quando Usar

Use esta habilidade quando:

• o usuário pedir um tour de código, tour de onboarding, walkthrough de arquitetura ou tour de PR
• o usuário disser "explique como X funciona" e quiser um artefato guiado reutilizável
• o usuário quiser um caminho de aprendizado para um novo engenheiro ou revisor
• a tarefa for melhor atendida por uma sequência guiada do que por um resumo plano

Exemplos:

• onboarding de um novo mantenedor
• tour de arquitetura para um serviço ou pacote
• walkthrough de revisão de PR ancorado em arquivos alterados
• tour de RCA mostrando o caminho da falha
• tour de revisão de segurança de limites de confiança e verificações chave

Quando NÃO Usar

Fluxo de Trabalho

1. Descobrir

Explore o repositório antes de escrever qualquer coisa:

• README e pontos de entrada de pacotes/aplicativos
• estrutura de pastas
• arquivos de configuração relevantes
• os arquivos alterados se o tour for focado em PR

Não comece a escrever etapas antes de entender a forma do código.

2. Inferir o leitor

Decida a persona e a profundidade com base na solicitação.

3. Ler e verificar âncoras

Todo caminho de arquivo e âncora de linha deve ser real:

• confirme se o arquivo existe
• confirme se os números das linhas estão dentro do intervalo
• se estiver usando uma seleção, verifique o bloco exato
• se o arquivo for volátil, prefira uma âncora baseada em padrão

Nunca adivinhe números de linha.

4. Escrever o .tour

Escreva para:

.tours/<persona>-<focus>.tour

Mantenha o caminho determinístico e legível.

5. Validar

Antes de finalizar:

• todo caminho referenciado existe
• toda linha ou seleção é válida
• a primeira etapa está ancorada em um arquivo ou diretório real
• o ref aponta para um branch ou commit que realmente tem todos os arquivos que o tour referencia (veja abaixo)
• o tour conta uma história coerente em vez de listar arquivos

O Campo ref

ref vincula o tour a um branch ou commit git. Isso é mais importante do que parece: quando ref não é o branch que o leitor tem em checkout, o CodeTour abre o arquivo de cada etapa dessa revisão no git, não dos arquivos no disco. Se um arquivo não estiver nessa revisão, a etapa não abrirá — o leitor verá "O editor não pôde ser aberto porque o arquivo não foi encontrado" mesmo que o arquivo esteja ali. O tour e seus comentários ainda aparecem, então a causa real é fácil de perder.

Escolha ref por tipo de tour:

O caso do PR é a armadilha comum: um PR geralmente adiciona novos arquivos, e novos arquivos ainda não existem no branch base. Apontar ref para a base (por exemplo, develop) e toda etapa em um novo arquivo falhará ao abrir.

Antes de finalizar, confirme se o arquivo de cada etapa realmente existe no ref que você escolheu.

Tipos de Etapa

Conteúdo

Use com moderação, geralmente apenas para uma etapa de encerramento:

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

Não faça da primeira etapa apenas conteúdo.

Diretório

Use para orientar o leitor em um módulo:

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

Arquivo + linha

Este é o tipo de etapa padrão:

…