Code Tour
Crie arquivos CodeTour — walkthroughs passo a passo direcionados a personas de uma base de código que linkam diretamente para arquivos e números de linha. Os arquivos CodeTour ficam em .tours/ e funcionam com a extensão CodeTour do VS Code.
Visão Geral
Um bom tour é uma narrativa — uma história contada a uma pessoa específica sobre o que importa, por que importa e o que fazer em seguida. Crie apenas arquivos .tour em JSON. Nunca modifique o código-fonte.
Quando Usar Esta Skill
- Usuário pede para criar um tour de código, tour de integração ou walkthrough de arquitetura
- Usuário diz "tour para este PR", "explique como X funciona", "vibe check", "tour de RCA"
- Usuário quer um guia do contribuidor, revisão de segurança ou walkthrough de investigação de bug
- Qualquer solicitação de walkthrough estruturado com âncoras de arquivo/linha
Workflow Principal
1. Descobrir o repositório
Antes de perguntar qualquer coisa, explore a base de código:
Em paralelo: liste o diretório raiz, leia o README, verifique os arquivos de configuração.
Depois: identifique linguagem(s), framework(s), propósito do projeto. Mapeie a estrutura de pastas 1-2 níveis de profundidade. Encontre pontos de entrada — cada caminho no tour deve ser real.
Se o repositório tiver menos de 5 arquivos fonte, crie um tour de profundidade rápida independentemente da persona — não há conteúdo suficiente para justificar um tour profundo.
2. Inferir a intenção
Uma mensagem deve ser suficiente. Infira persona, profundidade e foco silenciosamente.
| O usuário diz |
Persona |
Profundidade |
| "tour para este PR" |
pr-reviewer |
padrão |
| "por que X quebrou" / "RCA" |
rca-investigator |
padrão |
| "integração" / "novo integrante" |
new-joiner |
padrão |
| "tour rápido" / "vibe check" |
vibecoder |
rápido |
| "arquitetura" |
architect |
profundo |
| "segurança" / "revisão de auth" |
security-reviewer |
padrão |
| (sem qualificador) |
new-joiner |
padrão |
Quando a intenção for ambígua, padrão para persona new-joiner com profundidade padrão — é a mais geralmente útil.
3. Ler os arquivos reais
Todo caminho de arquivo e número de linha deve ser verificado. Um tour apontando para a linha errada é pior do que nenhum tour.
4. Escrever o tour
Salve em .tours/<persona>-<foco>.tour.
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Título Descritivo — Persona / Objetivo",
"description": "Para quem é isso e o que eles entenderão depois.",
"ref": "<branch-ou-commit-atual>",
"steps": []
}
Tipos de passo
| Tipo |
Quando usar |
Exemplo |
| Content |
Apenas intro/encerramento (máx. 2) |
{ "title": "Bem-vindo", "description": "..." } |
| Directory |
Orientar para um módulo |
{ "directory": "src/services", "title": "..." } |
| File + line |
O cavalo de batalha |
{ "file": "src/auth.ts", "line": 42, "title": "..." } |
| Selection |
Destacar um bloco de código |
{ "file": "...", "selection": {...}, "title": "..." } |
| Pattern |
Correspondência regex (arquivos voláteis) |
{ "file": "...", "pattern": "class App", "title": "..." } |
| URI |
Link para PR, issue, doc |
{ "uri": "https://...", "title": "..." } |
Contagem de passos
| Profundidade |
Passos |
Usar para |
| Rápido |
5-8 |
Vibecoder, exploração rápida |
| Padrão |
9-13 |
A maioria das personas |
| Profundo |
14-18 |
Architect, RCA |
Escrevendo descrições — fórmula SMIG
- S — Situação: O que o leitor está olhando?
- M — Mecanismo: Como este código funciona?
- I — Implicação: Por que isso importa para esta persona?
- G — Armadilha: O que uma pessoa inteligente erraria?
5. Validar
Personas
| Persona |
Objetivo |
Deve cobrir |
| Vibecoder |
Captar o vibe rapidamente |
Ponto de entrada, módulos principais. Máx. 8 passos. |
| New joiner |
Ramp-up estruturado |
Diretórios, configuração, contexto de negócio |
| Bug fixer |
Causa raiz rapidamente |
Gatilho -> pontos de falha -> testes |
| RCA investigator |
Por que falhou |
Cadeia de causalidade, âncoras de observabilidade |
| Feature explainer |
Ponta a ponta |
UI -> API -> backend -> armazenamento |
| PR reviewer |
Revisar corretamente |
Histórico de mudanças, invariantes, áreas de risco |
| Architect |
Forma e razão |
Limites, trade-offs, pontos de extensão |
| Security reviewer |
Limites de confiança |
Fluxo de auth, validação, manipulação de segredos |
| Refactorer |
Reestruturação segura |
Junções, dependências ocultas, ordem de extração |
| External contributor |
Contribuir com segurança |
Áreas seguras, convenções, armadilhas |
Arco Narrativo
- Orientação — passo
file ou directory (nunca passo somente de conteúdo primeiro — fica em branco no VS Code)
- Mapa de alto nível — 1-3 passos de diretório mostrando módulos principais
- Caminho principal — passos de arquivo/linha, o coração do tour
- Encerramento — o que o leitor agora pode fazer, acompanhamentos sugeridos
Anti-Padrões
| Anti-padrão |
Correção |
| Listagem de arquivos — "este arquivo contém os modelos" |
Conte uma história. Cada passo depende do anterior. |
| Descrições genéricas |
Nomeie o padrão específico único desta base de código. |
| Adivinhar números de linha |
Nunca escreva uma linha que não verificou lendo. |
| Muitos passos para profundidade rápida |
Realmente corte passos. |
| Arquivos alucinados |
Se não existe, pule o passo. |
| Encerramento de recapitulação — "cobrimos X, Y, Z" |
Diga ao leitor o que ele agora pode fazer. |
| Passo somente de conteúdo como primeiro |
Ancore o passo 1 a um arquivo ou diretório. |
Referências Cruzadas
- Relacionado:
engineering/codebase-onboarding — para integração mais ampla além dos tours
- Relacionado:
engineering/pr-review-expert — para workflows de revisão de PR automatizados
- Extensão CodeTour: microsoft/codetour
- Tours do mundo real: coder/code-server
1---2name: code-tour3description: Use quando o usuário pedir para criar um arquivo CodeTour .tour — walkthroughs passo a passo direcionados a personas que linkam para arquivos reais e números de linha. Gatilho para: criar um tour, tour de integração, tour de arquitetura, tour de revisão de PR, explicar como X funciona, vibe check, tour de RCA, guia do contribuidor, ou qualquer solicitação de walkthrough de código estruturado.4---56# Code Tour78Crie arquivos **CodeTour** — walkthroughs passo a passo direcionados a personas de uma base de código que linkam diretamente para arquivos e números de linha. Os arquivos CodeTour ficam em `.tours/` e funcionam com a [extensão CodeTour do VS Code](https://github.com/microsoft/codetour).910## Visão Geral1112Um bom tour é uma **narrativa** — uma história contada a uma pessoa específica sobre o que importa, por que importa e o que fazer em seguida. Crie apenas arquivos `.tour` em JSON. Nunca modifique o código-fonte.1314## Quando Usar Esta Skill1516- Usuário pede para criar um tour de código, tour de integração ou walkthrough de arquitetura17- Usuário diz "tour para este PR", "explique como X funciona", "vibe check", "tour de RCA"18- Usuário quer um guia do contribuidor, revisão de segurança ou walkthrough de investigação de bug19- Qualquer solicitação de walkthrough estruturado com âncoras de arquivo/linha2021## Workflow Principal2223### 1. Descobrir o repositório2425Antes de perguntar qualquer coisa, explore a base de código:2627Em paralelo: liste o diretório raiz, leia o README, verifique os arquivos de configuração.28Depois: identifique linguagem(s), framework(s), propósito do projeto. Mapeie a estrutura de pastas 1-2 níveis de profundidade. Encontre pontos de entrada — cada caminho no tour deve ser real.2930Se o repositório tiver menos de 5 arquivos fonte, crie um tour de profundidade rápida independentemente da persona — não há conteúdo suficiente para justificar um tour profundo.3132### 2. Inferir a intenção3334Uma mensagem deve ser suficiente. Infira persona, profundidade e foco silenciosamente.3536| O usuário diz | Persona | Profundidade |37|-----------|---------|-------|38| "tour para este PR" | pr-reviewer | padrão |39| "por que X quebrou" / "RCA" | rca-investigator | padrão |40| "integração" / "novo integrante" | new-joiner | padrão |41| "tour rápido" / "vibe check" | vibecoder | rápido |42| "arquitetura" | architect | profundo |43| "segurança" / "revisão de auth" | security-reviewer | padrão |44| (sem qualificador) | new-joiner | padrão |4546Quando a intenção for ambígua, padrão para persona **new-joiner** com profundidade **padrão** — é a mais geralmente útil.4748### 3. Ler os arquivos reais4950**Todo caminho de arquivo e número de linha deve ser verificado.** Um tour apontando para a linha errada é pior do que nenhum tour.5152### 4. Escrever o tour5354Salve em `.tours/<persona>-<foco>.tour`.5556```json57{58 "$schema": "https://aka.ms/codetour-schema",59 "title": "Título Descritivo — Persona / Objetivo",60 "description": "Para quem é isso e o que eles entenderão depois.",61 "ref": "<branch-ou-commit-atual>",62 "steps": []63}64```6566### Tipos de passo6768| Tipo | Quando usar | Exemplo |69|------|-------------|---------|70| **Content** | Apenas intro/encerramento (máx. 2) | `{ "title": "Bem-vindo", "description": "..." }` |71| **Directory** | Orientar para um módulo | `{ "directory": "src/services", "title": "..." }` |72| **File + line** | O cavalo de batalha | `{ "file": "src/auth.ts", "line": 42, "title": "..." }` |73| **Selection** | Destacar um bloco de código | `{ "file": "...", "selection": {...}, "title": "..." }` |74| **Pattern** | Correspondência regex (arquivos voláteis) | `{ "file": "...", "pattern": "class App", "title": "..." }` |75| **URI** | Link para PR, issue, doc | `{ "uri": "https://...", "title": "..." }` |7677### Contagem de passos7879| Profundidade | Passos | Usar para |80|-------|-------|---------|81| Rápido | 5-8 | Vibecoder, exploração rápida |82| Padrão | 9-13 | A maioria das personas |83| Profundo | 14-18 | Architect, RCA |8485### Escrevendo descrições — fórmula SMIG8687- **S — Situação**: O que o leitor está olhando?88- **M — Mecanismo**: Como este código funciona?89- **I — Implicação**: Por que isso importa para esta persona?90- **G — Armadilha**: O que uma pessoa inteligente erraria?9192### 5. Validar9394- [ ] Todo caminho de `file` relativo à raiz do repo (sem `/` inicial ou `./`)95- [ ] Todo `file` confirmado como existente96- [ ] Todo `line` verificado lendo o arquivo97- [ ] Primeiro passo tem âncora `file` ou `directory`98- [ ] No máximo 2 passos somente de conteúdo99- [ ] `nextTour` corresponde ao `title` de outro tour exatamente, se definido100101## Personas102103| Persona | Objetivo | Deve cobrir |104|---------|------|------------|105| **Vibecoder** | Captar o vibe rapidamente | Ponto de entrada, módulos principais. Máx. 8 passos. |106| **New joiner** | Ramp-up estruturado | Diretórios, configuração, contexto de negócio |107| **Bug fixer** | Causa raiz rapidamente | Gatilho -> pontos de falha -> testes |108| **RCA investigator** | Por que falhou | Cadeia de causalidade, âncoras de observabilidade |109| **Feature explainer** | Ponta a ponta | UI -> API -> backend -> armazenamento |110| **PR reviewer** | Revisar corretamente | Histórico de mudanças, invariantes, áreas de risco |111| **Architect** | Forma e razão | Limites, trade-offs, pontos de extensão |112| **Security reviewer** | Limites de confiança | Fluxo de auth, validação, manipulação de segredos |113| **Refactorer** | Reestruturação segura | Junções, dependências ocultas, ordem de extração |114| **External contributor** | Contribuir com segurança | Áreas seguras, convenções, armadilhas |115116## Arco Narrativo1171181. **Orientação** — passo `file` ou `directory` (nunca passo somente de conteúdo primeiro — fica em branco no VS Code)1192. **Mapa de alto nível** — 1-3 passos de diretório mostrando módulos principais1203. **Caminho principal** — passos de arquivo/linha, o coração do tour1214. **Encerramento** — o que o leitor agora pode fazer, acompanhamentos sugeridos122123## Anti-Padrões124125| Anti-padrão | Correção |126|---|---|127| **Listagem de arquivos** — "este arquivo contém os modelos" | Conte uma história. Cada passo depende do anterior. |128| **Descrições genéricas** | Nomeie o padrão específico único desta base de código. |129| **Adivinhar números de linha** | Nunca escreva uma linha que não verificou lendo. |130| **Muitos passos** para profundidade rápida | Realmente corte passos. |131| **Arquivos alucinados** | Se não existe, pule o passo. |132| **Encerramento de recapitulação** — "cobrimos X, Y, Z" | Diga ao leitor o que ele agora pode *fazer*. |133| **Passo somente de conteúdo como primeiro** | Ancore o passo 1 a um arquivo ou diretório. |134135## Referências Cruzadas136137- Relacionado: `engineering/codebase-onboarding` — para integração mais ampla além dos tours138- Relacionado: `engineering/pr-review-expert` — para workflows de revisão de PR automatizados139- Extensão CodeTour: [microsoft/codetour](https://github.com/microsoft/codetour)140- Tours do mundo real: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)
ricneves-ai