Código-para-Curso

Código-para-Curso (Codebase-to-Course)

Transforme qualquer base de código em um curso interativo e impressionante. A saída é um diretório contendo styles.css, main.js, arquivos HTML por módulo e um index.html montado — abra-o diretamente no navegador sem necessidade de configuração (a única dependência externa é a CDN do Google Fonts). O curso ensina como o código funciona por meio de módulos com navegação por rolagem, visualizações animadas, questionários incorporados e traduções de código para linguagem simples.

Boas-Vindas na Primeira Execução

Quando a skill for acionada pela primeira vez e o usuário não tiver especificado uma base de código, apresente-se e explique o que você faz:

Posso transformar qualquer base de código em um curso interativo que ensina como ela funciona — sem necessidade de conhecimento técnico.

Basta me indicar um projeto:

• Uma pasta local — ex.: "transforme ./meu-projeto em um curso"
• Um link do GitHub — ex.: "crie um curso a partir de https://github.com/usuario/repositorio"
• O projeto atual — se você já está em uma base de código, basta dizer "transforme isso em um curso"

Vou ler o código, entender como tudo se encaixa e gerar um lindo curso HTML de página única com diagramas animados, explicações em linguagem simples e questionários interativos. Tudo roda no seu navegador — sem configuração necessária.

Se o usuário fornecer um link do GitHub, clone o repositório primeiro (git clone <url> /tmp/<nome-do-repo>) antes de iniciar a análise. Se ele disser "esta base de código" ou algo similar, use o diretório de trabalho atual.

Para Quem É Este Curso

O aluno-alvo é um "vibe coder" — alguém que constrói software instruindo ferramentas de IA por meio de linguagem natural, sem uma formação tradicional em ciência da computação. Pode ser que ele mesmo tenha construído este projeto (sem olhar o código), ou pode ter encontrado um projeto open-source interessante no GitHub e queira entender como ele é construído. De qualquer forma, ele ainda não entende o que está acontecendo nos bastidores.

Presuma que não há conhecimento técnico. Cada conceito de CC — de variáveis a APIs e bancos de dados — precisa ser explicado em linguagem simples como se o aprendiz nunca tivesse encontrado o termo. Sem jargões sem definição. Sem "como você provavelmente sabe". O tom deve ser de um amigo inteligente explicando coisas, não de um professor dando aula.

Os objetivos deles são práticos, não acadêmicos:

• Ter conhecimento técnico suficiente para orientar ferramentas de IA de forma eficaz — tomar melhores decisões de arquitetura e stack
• Detectar quando a IA está errada — identificar alucinações, capturar padrões ruins, saber quando algo parece estranho
• Intervir quando a IA fica presa — sair de loops de bugs, depurar problemas, desbloquear a si mesmos
• Construir software mais avançado com qualidade e confiabilidade de nível de produção
• Ser tecnicamente fluente o suficiente para discutir decisões com engenheiros com confiança
• Adquirir o vocabulário do software — aprender os termos técnicos precisos para descrever requisitos de forma clara e inequívoca para agentes de IA (ex.: saber dizer "pacote de namespace" em vez de "pasta compartilhada")

Eles NÃO estão tentando se tornar engenheiros de software. Eles querem que a programação seja um superpoder que amplifica o que eles já fazem bem. Eles não precisam escrever código do zero — precisam ler código, entendê-lo e dirigi-lo.

Por Que Esta Abordagem Funciona

Esta skill inverte o modelo tradicional do ensino de CC. O modelo antigo é: memorize conceitos por anos → eventualmente construa algo → finalmente veja o sentido (a maioria desiste antes do passo 3). Este modelo é: construa algo primeiro → experimente funcionar → agora entenda como funciona.

O aprendiz já tem o contexto que alunos tradicionais não têm — eles usaram o aplicativo, sabem o que ele faz, podem até ter descrito suas funcionalidades em linguagem natural. O curso encontra o aprendiz onde ele está: "Você conhece aquele botão pelo qual clica? Aqui está o que acontece nos bastidores quando você clica nele."

Cada módulo responde "por que eu deveria me importar?" antes de "como funciona?" A resposta para "por que me importar?" é sempre prática: porque esse conhecimento ajuda você a orientar a IA melhor, depurar mais rápido ou tomar decisões de arquitetura mais inteligentes.

A saída baseada em diretório é intencional: separar CSS/JS do conteúdo significa que a IA nunca regenera código repetitivo, cada módulo é escrito de forma independente (mantendo o tamanho pequeno e a qualidade alta), e o index.html montado funciona offline sem nenhuma configuração.

---

O Processo

Fase 1: Análise da Base de Código

Antes de escrever o HTML do curso, entenda profundamente a base de código. Leia todos os arquivos principais, rastreie os fluxos de dados, identifique o "elenco de personagens" (componentes/módulos principais) e mapeie como eles se comunicam. A minuciosidade aqui compensa — quanto mais você entender, melhor será o curso.

O que extrair:

• Os principais "atores" (componentes, serviços, módulos) e suas responsabilidades
• A jornada principal do usuário (o que acontece quando alguém usa o aplicativo do início ao fim)
• APIs principais, fluxos de dados e padrões de comunicação
• Padrões de engenharia inteligentes (cache, carregamento preguiçoso, tratamento de erros etc.)
• Bugs reais ou pegadinhas (se visíveis no histórico do git ou em comentários)
• A stack de tecnologia e por que cada peça foi escolhida

Descubra você mesmo o que o aplicativo faz lendo o README, os pontos de entrada principais e o código da interface. Não peça ao usuário para explicar o produto — ele também pode não estar familiarizado com ele. O curso deve começar explicando o que o aplicativo faz em linguagem simples (uma breve "aqui está o que essa coisa faz e por que é interessante") antes de mergulhar em como funciona. O primeiro módulo deve começar com uma ação concreta do usuário — "imagine que você cola uma URL do YouTube e clica em Analisar — aqui está o que acontece nos bastidores."

Fase 2: Design do Currículo

Estruture o curso como 4-6 módulos. A maioria dos cursos precisa de 4-6. Só vá para 7-8 se a base de código genuinamente tiver tantos conceitos distintos que valham a pena ensinar. Menos módulos, mas melhores, superam mais módulos, mas superficiais.

O arco sempre começa do que o aprendiz já conhece (o comportamento visível ao usuário) e avança para o que ele não conhece (o código subjacente). Pense nisso como um zoom: comece amplo com a experiência e, em seguida, retire camadas progressivamente.

Posição do Módulo	Propósito	Por que é importante para um vibe coder
1	"Aqui está o que este app faz — e o que acontece quando você o usa"	Comece pelo produto (o que faz, por que é interessante) e depois rastreie uma ação central do usuário no código. Baseia tudo em algo concreto.
2	Conheça os atores	Saiba quais componentes existem para que você possa dizer à IA "coloque esta lógica em X, não em Y"
3	Como as peças se comunicam	Entenda o fluxo de dados para que você possa depurar problemas do tipo "não está aparecendo"
4	O mundo externo (APIs, bancos de dados)	Saiba o que é externo para que você possa avaliar custos, limites de taxa e modos de falha
5	Os truques inteligentes	Aprenda padrões (cache, chunking, tratamento de erros) para que você possa solicitá-los à IA
6	Quando as coisas quebram	Construa intuição de depuração para que você possa escapar de loops de bugs da IA
7	O panorama geral	Veja a arquitetura completa para que você possa tomar melhores decisões sobre o que construir em seguida

Este é um cardápio, não uma lista de verificação. Escolha os módulos que servem à base de código — uma ferramenta CLI simples precisa de 4, não de 7. Adapte o arco à complexidade da base de código.

O princípio-chave: Cada módulo deve se conectar a uma habilidade prática — orientar a IA, depurar, tomar decisões. Se um módulo não ajudar o aprendiz a FAZER algo melhor, corte-o ou reformule-o até que ajude.

Cada módulo deve conter:

• 3-6 telas (subseções que fluem dentro do módulo)
• Pelo menos uma tradução código-com-inglês
• Pelo menos um elemento interativo (questionário, visualização ou animação)
• Um ou dois blocos de destaque "aha!" com insights universais de CC
• Uma metáfora que ancora o conceito técnico na vida cotidiana — mas NUNCA reutilize a mesma metáfora em módulos diferentes e NUNCA recorra à metáfora do "restaurante" (é muito usada). Escolha metáforas que se encaixem organicamente no conceito específico. As melhores metáforas parecem inevitáveis para o conceito, não forçadas.

Elementos interativos obrigatórios (todo curso deve incluir TODOS estes):

• Animação de Chat em Grupo — pelo menos uma em todo o curso. São as conversas no estilo iMessage/WeChat entre componentes. São um dos elementos mais envolventes e devem sempre aparecer, mesmo que você precise enquadrar criativamente o conceito de um módulo como uma conversa entre atores.
• Animação de Fluxo de Mensagens / Fluxo de Dados — pelo menos uma em todo o curso. A animação passo a passo de pacotes entre atores. Se a base de código tiver qualquer tipo de requisição/resposta, pipeline de dados ou processo de várias etapas, anime-o. Toda base de código tem dados fluindo em algum lugar — encontre-o.
• Blocos de Tradução Código ↔ Português — pelo menos um por módulo (já exigido acima, mas reiterando: isso é inegociável).
• Questionários — pelo menos um por módulo (múltipla escolha, cenário, arrastar e soltar ou encontre o bug — qualquer tipo de questionário conta).
• Dicas de Glossário — em todo termo técnico, no primeiro uso por módulo.

Esses cinco tipos de elemento são a espinha dorsal de todo curso. Outros elementos interativos (diagramas de arquitetura, alternância de camadas, cartões de padrões etc.) são opcionais e devem ser adicionados quando couberem. Mas os cinco acima devem estar SEMPRE presentes — sem exceções.

NÃO apresente o currículo para aprovação — apenas construa-o. O usuário quer um curso, não um documento de planejamento. Projete o currículo internamente e depois vá direto para a construção. Se eles quiserem mudanças, dirão depois de ver o resultado.

Depois de projetar o currículo, decida qual caminho de construção usar:

• Base de código simples (CLI de propósito único, aplicativo web pequeno, biblioteca, um ponto de entrada claro, 5 ou menos módulos) → vá diretamente para a Fase 3 Sequencial.
• Base de código complexa (aplicativo full-stack, vários serviços, site com muito conteúdo, monorepo ou 6+ módulos) → vá primeiro para a Fase 2.5 e depois para a Fase 3 Paralela.

Fase 2.5: Briefs de Módulo (apenas para bases de código complexas)

Para bases de código complexas, escreva um brief para cada módulo antes de escrever qualquer HTML. Este é o passo crítico que permite a escrita paralela — cada brief dá a um agente tudo o que ele precisa sem reler a base de código.

Leia references/module-brief-template.md para a estrutura do modelo. Leia references/content-philosophy.md para as regras de conteúdo que devem orientar a escrita do brief.

Para cada módulo, escreva um brief em course-name/briefs/0N-slug.md contendo:

• Arco de ensino (metáfora, gancho de abertura, insight-chave)
• Trechos de código pré-extraídos (copiados da base de código com caminhos de arquivo e números de linha)
• Lista de verificação de elementos interativos com detalhes suficientes para construí-los
• Quais seções de quais arquivos de referência o agente escritor precisa
• O que os módulos anterior e seguinte cobrem (para transições)

Os trechos de código são a etapa crítica de economia de tokens. Pré-extraindo-os no brief, os agentes escritores nunca precisam ler a base de código.

Fase 3: Construir o Curso

A saída do curso é um diretório, não um único arquivo. Todos os CSS e JS são arquivos de referência pré-construídos — nunca os regenere. Seu trabalho é escrever apenas o conteúdo HTML.

Estrutura de saída:

course-name/
  styles.css       ← copiado literalmente de references/styles.css
  main.js          ← copiado literalmente de references/main.js
  _base.html       ← shell personalizado (título, cor de destaque, pontos de navegação)
  _footer.html     ← copiado literalmente de references/_footer.html
  build.sh         ← copiado literalmente de references/build.sh
  briefs/          ← briefs de módulo (apenas para bases complexas, pode excluir após construção)
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← montado por build.sh (não escreva manualmente)

Passo 1 (ambos os caminhos): Configuração — Crie o diretório do curso. Copie estes quatro arquivos literalmente usando Leitura + Escrita (não regenere seus conteúdos):

• references/styles.css → course-name/styles.css
• references/main.js → course-name/main.js
• references/_footer.html → course-name/_footer.html
• references/build.sh → course-name/build.sh

Passo 2 (ambos os caminhos): Personalizar _base.html — Leia references/_base.html, depois escreva-o em course-name/_base.html com exatamente três substituições:

• Ambas as instâncias de COURSE_TITLE → o título real do curso
• Os quatro placeholders ACCENT_* → os valores de cor de destaque escolhidos (escolha uma paleta dos comentários em _base.html)
• NAV_DOTS → um <button class="nav-dot" ...> por módulo

Passo 3: Escrever módulos — Aqui os caminhos divergem.

Caminho Sequencial (bases de código simples)

Leia references/content-philosophy.md e references/gotchas.md. Em seguida, escreva os módulos um de cada vez. Para cada módulo, escreva course-name/modules/0N-slug.html contendo apenas o bloco <section class="module" id="module-N"> e seu conteúdo. Não inclua tags <html>, <head>, <body>, <style> ou <script>.

Leia references/interactive-elements.md para os padrões HTML de cada tipo de elemento interativo. Leia references/design-system.md para as convenções visuais.

Caminho Paralelo (bases de código complexas)

Distribua os módulos para subagentes em lotes de até 3. Cada agente recebe:

• Seu brief de módulo (de course-name/briefs/)
• references/content-philosophy.md e references/gotchas.md
• Apenas as seções de references/interactive-elements.md e references/design-system.md listadas no brief

Cada agente escreve seu(s) arquivo(s) de módulo em course-name/modules/. Módulos curtos (3 telas, um questionário) podem ser pareados — dois briefs dados a um único agente.

O que os agentes NÃO recebem: a base de código completa (trechos estão no brief), SKILL.md, briefs de outros módulos ou seções de arquivos de referência não necessárias.

Depois que todos os agentes terminarem, faça uma verificação rápida de consistência no contexto principal: pontos de navegação correspondem aos módulos, transições entre módulos são coerentes, sem mudanças óbvias de tom.

Passo 4 (ambos os caminhos): Montar — Execute build.sh a partir do diretório do curso:

cd course-name && bash build.sh

Isso produz index.html. Abra-o no navegador.

Regras críticas:

• Nunca regenere styles.css ou main.js — sempre copie de ...