code-tour

Code Tour

Crie arquivos CodeTour .tour para walkthroughs de base de código que abrem diretamente em arquivos reais e intervalos de linhas. Os tours ficam em .tours/ e são destinados ao formato CodeTour, não a anotações Markdown avulsas.

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

• o que ele está vendo
• por que é importante
• qual caminho seguir em seguida

Crie apenas arquivos .tour JSON. Não modifique o código fonte como parte deste skill.

Quando Usar

Use este skill quando:

• o usuário pedir um code tour, 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 de um serviço ou pacote
• walkthrough de revisão de PR ancorado nos arquivos alterados
• tour de RCA mostrando o caminho da falha
• tour de revisão de segurança sobre limites de confiança e verificações-chave

Quando NÃO Usar

Em vez de code-tour	Use
Uma explicação avulsa no chat já basta	responda diretamente
O usuário quer documentação em prosa, não um artefato .tour	documentation-lookup ou edição de docs do repositório
A tarefa é implementação ou refatoração	faça o trabalho de implementação
A tarefa é onboarding amplo na base de código sem artefato de tour	codebase-onboarding

Fluxo de Trabalho

1. Descubra

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 passos antes de entender a forma do código.

2. Inferir o leitor

Decida a persona e a profundidade a partir da solicitação.

Formato da solicitação	Persona	Profundidade sugerida
"onboarding", "novo integrante"	new-joiner	9-13 passos
"tour rápido", "visão geral"	vibecoder	5-8 passos
"arquitetura"	architect	14-18 passos
"tour deste PR"	pr-reviewer	7-11 passos
"por que isso quebrou"	rca-investigator	7-11 passos
"revisão de segurança"	security-reviewer	7-11 passos
"explique como esta funcionalidade funciona"	feature-explainer	7-11 passos
"depure este caminho"	bug-fixer	7-11 passos

3. Leia e verifique as âncoras

Todo caminho de arquivo e âncora de linha devem ser reais:

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

Nunca chute números de linha.

4. Escreva o .tour

Escreva em:

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

Mantenha o caminho determinístico e legível.

5. Valide

Antes de finalizar:

• todo caminho referenciado existe
• toda linha ou seleção é válida
• o primeiro passo está ancorado em um arquivo ou diretório real
• o ref aponta para um branch ou commit que realmente possui todo arquivo referenciado pelo tour (veja abaixo)
• o tour conta uma história coerente, em vez de apenas listar arquivos

O Campo ref

ref vincula o tour a um branch ou commit do git. Ele importa mais do que parece: quando ref não é o branch que o leitor tem checkout, o CodeTour abre o arquivo de cada passo a partir dessa revisão no git, não dos arquivos no disco. Se um arquivo não estiver nessa revisão, o passo 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 ignorar.

Escolha ref por tipo de tour:

Tipo de tour	Defina ref como
Tour de PR	o branch do PR — nunca o branch base
Onboarding / arquitetura	o branch em que o leitor estará (geralmente main), ou omita
Não tem certeza	omita ref, assim o CodeTour lê os arquivos diretamente do disco

O caso de PR é a armadilha comum: um PR geralmente adiciona arquivos novos, e arquivos novos ainda não existem no branch base. Aponte ref para a base (ex.: develop) e todo passo em um arquivo novo falhará ao abrir.

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

Tipos de Passo

Conteúdo

Use com moderação, geralmente apenas para um passo de encerramento:

{ "title": "Próximos Passos", "description": "Agora você pode rastrear o caminho da solicitação de ponta a ponta." }

Não faça do primeiro passo apenas conteúdo.

Diretório

Use para orientar o leitor para um módulo:

{ "directory": "src/services", "title": "Camada de Serviços", "description": "A lógica central de orquestração fica aqui." }

Arquivo + linha

Este é o tipo de passo padrão:

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Portão de Autenticação", "description": "Toda requisição protegida passa por aqui primeiro." }

Seleção

Use quando um bloco de código específico importa mais que o arquivo inteiro:

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Pipeline de Requisições",
  "description": "Este bloco conecta validação, autenticação e execução downstream."
}

Padrão

Use quando as linhas exatas podem variar:

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Ponto de Entrada da Aplicação" }

URI

Use para PRs, issues ou documentação quando útil:

{ "uri": "https://github.com/org/repo/pull/456", "title": "O PR" }

Regra de Escrita: SMIG

Cada descrição deve responder:

• Situação: o que o leitor está vendo
• Mecanismo: como funciona
• Implicação: por que isso importa para esta persona
• Pegadinha: o que um leitor esperto pode perder

Mantenha as descrições compactas, específicas e fundamentadas no código real.

Estrutura Narrativa

Use este arco a menos que a tarefa exija claramente algo diferente:

1. orientação
2. mapa do módulo
3. caminho de execução principal
4. caso de borda ou pegadinha
5. encerramento / próximo movimento

O tour deve parecer um caminho, não um inventário.

Exemplo

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Tour do Serviço de API",
  "description": "Walkthrough do caminho de requisição para o serviço de pagamentos.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Raiz do Código Fonte",
      "description": "Todo o código em tempo de execução do serviço começa aqui."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Ponto de Entrada",
      "description": "O servidor inicializa aqui e conecta middlewares antes de qualquer rota ser acessada."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Rotas de Pagamento",
      "description": "Toda requisição de pagamento entra por este roteador antes de atingir a lógica do serviço."
    },
    {
      "title": "Próximos Passos",
      "description": "Agora você pode seguir qualquer requisição de pagamento de ponta a ponta com as âncoras principais no lugar."
    }
  ]
}

Anti-Padrões

Anti-padrão	Correção
Listagem plana de arquivos	Conte uma história com dependência entre os passos
Descrições genéricas	Nomeie o caminho de código concreto ou o padrão
Âncoras chutadas	Verifique cada arquivo e linha primeiro
Passos demais para um tour rápido	Corte agressivamente
Primeiro passo é apenas conteúdo	Ancôre o primeiro passo em um arquivo ou diretório real
Persona inadequada	Escreva para o leitor real, não para um engenheiro genérico

Melhores Práticas

• mantenha a contagem de passos proporcional ao tamanho do repositório e profundidade da persona
• use passos de diretório para orientação, passos de arquivo para substância
• para tours de PR, cubra os arquivos alterados primeiro
• para monorepos, escopo nos pacotes relevantes em vez de percorrer tudo
• encerre com o que o leitor pode fazer agora, não com um resumo

Skills Relacionados

• codebase-onboarding
• coding-standards
• council
• formato oficial upstream: microsoft/codetour