code-tour

Code Tour

Crie arquivos CodeTour .tour para walkthroughs de bases de código que abrem diretamente arquivos e intervalos de linhas reais. Os tours ficam em .tours/ e são destinados ao formato CodeTour, e não a notas ad hoc em Markdown.

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

• o que ele(a) está vendo
• por que isso importa
• 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 linear

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 com fronteiras de confiança e verificações-chave

Quando NÃO usar

Em vez de code-tour	Use
Uma explicação avulsa no chat é suficiente	responda diretamente
O usuário quer docs 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 da base de código sem um 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/aplicações
• 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.

Forma da solicitação	Persona	Profundidade sugerida
"onboarding", "novo membro"	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 âncoras

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

• 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 adivinhe 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 contém todos os arquivos que o tour referencia (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. É mais importante do que parece: quando ref não é o branch que o leitor tem em checkout, o CodeTour abre o arquivo de cada passo a partir daquela revisão no git, e não dos arquivos no disco. Se um arquivo não existir naquela revisão, o passo não abrirá — o leitor verá "Não foi possível abrir o editor porque o arquivo não foi encontrado" mesmo que o arquivo esteja bem ali. O tour e seus comentários ainda aparecem, então a causa real é fácil de passar despercebida.

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 deixe vazio
Não tem certeza	deixe ref vazio, para que o CodeTour leia os arquivos diretamente do disco

O caso de PR é a armadilha comum: um PR geralmente adiciona novos arquivos, e novos arquivos ainda não existem no branch base. Aponte ref para o 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 requisição de ponta a ponta." }

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

Diretório

Use para orientar o leitor a 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 for mais importante que o arquivo inteiro:

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

Padrão

Use quando as linhas exatas podem mudar:

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

URI

Use para PRs, issues ou docs quando for útil:

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

Regra de Escrita: SMIG

Cada descrição deve responder a:

• 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.

Forma Narrativa

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

1. orientação
2. mapa de módulos
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 de runtime 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 alcançada."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Rotas de Pagamentos",
      "description": "Toda requisição de pagamentos entra por este roteador antes de atingir a lógica de serviço."
    },
    {
      "title": "Próximos Passos",
      "description": "Agora você pode seguir qualquer requisição de pagamento de ponta a ponta com as principais âncoras 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 ou padrão de código concreto
Âncoras adivinhadas	Verifique cada arquivo e linha primeiro
Muitos passos para um tour rápido	Corte agressivamente
Primeiro passo é apenas conteúdo	Ancore o primeiro passo em um arquivo ou diretório real
Incompatibilidade de persona	Escreva para o leitor real, não para um engenheiro genérico

Melhores práticas

• mantenha o número 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 aos pacotes relevantes em vez de fazer tour de 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