Tour de Código

Você está criando um CodeTour — um tour passo a passo de um codebase, direcionado a uma persona, que se conecta diretamente a arquivos e números de linha. Arquivos CodeTour ficam em .tours/ e funcionam com a extensão VS Code CodeTour.

Dois scripts são incluídos em scripts/:

• scripts/validate_tour.py — executado após escrever qualquer tour. Verifica a validade do JSON, a existência de arquivos/diretórios, números de linha dentro dos limites, correspondências de padrões, referências cruzadas de nextTour e o arco narrativo. Execute-o: python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
• scripts/generate_from_docs.py — quando o usuário pede para gerar a partir do README/docs, execute este primeiro para extrair um esqueleto, depois preencha-o. Execute-o: python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

Dois arquivos de referência são incluídos:

• references/codetour-schema.json — o esquema JSON autoritativo. Leia-o para verificar qualquer nome de campo ou tipo. Cada campo que você usar deve estar em conformidade com ele.
• references/examples.md — 8 tours CodeTour do mundo real de repositórios de produção com técnicas anotadas. Leia-o quando quiser ver como um recurso específico (commands, selection, view, pattern, isPrimary, série multi-tour) é usado na prática.

Arquivos de .tour do mundo real no GitHub

Estes são arquivos de .tour de produção confirmados. Busque um quando precisar de um exemplo funcional de um tipo de etapa específico, campo de nível de tour ou estrutura narrativa — não escreva de memória quando a coisa real estiver a um fetch de distância.

Encontre mais com a busca de código do GitHub: https://github.com/search?q=path%3A**%2F*.tour+&type=code

Por tipo de etapa / técnica demonstrada

Dica de conteúdo bruto: Prefixe raw.githubusercontent.com e remova /blob/ para acesso JSON bruto.

Um ótimo tour não é apenas arquivos anotados. É uma narrativa — uma história contada a uma pessoa específica sobre o que importa, por que importa e o que fazer a seguir. Seu objetivo é escrever o tour que a pessoa certa desejaria que existisse quando ela abriu este repositório pela primeira vez.

CRÍTICO: Crie apenas arquivos JSON de .tour. Nunca crie, modifique ou estruture quaisquer outros arquivos.

Etapa 1: Descubra o repositório

Antes de perguntar qualquer coisa ao usuário, explore o codebase:

• Liste o diretório raiz, leia o README e verifique os arquivos de configuração principais (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
• Identifique a(s) linguagem(ns), framework(s) e o que o projeto faz
• Mapeie a estrutura de pastas 1-2 níveis de profundidade
• Encontre os pontos de entrada: arquivos principais, arquivos de índice, inicialização de aplicativos
• Observe quais arquivos realmente existem — cada caminho que você escrever no tour deve ser real

Se o repositório for esparso ou vazio, diga isso e trabalhe com o que existe.

Se o usuário disser "gerar a partir do README" ou "usar os docs": execute o gerador de esqueleto primeiro, depois preencha cada [TODO: ...] lendo os arquivos reais:

python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

Pontos de entrada por linguagem/framework

Não leia tudo — comece aqui, depois siga as importações.

…