fernbrook-labs/beginner-reference-book

Criar um guia de referência para iniciantes (guia introdutório)

Criar um guia de referência introdutório para uma linguagem de programação ou framework, seguindo exatamente o mesmo design, as mesmas funcionalidades e a mesma abordagem dos guias introdutórios já criados para TypeScript, Rust, Angular e Go (os modelos estão em references/examples/). O resultado são os seguintes dois itens:

• Um arquivo HTML único colocado na área de trabalho (GuiaIntrodutórioDeOO.html. Abre com um duplo clique).
• Uma página de compartilhamento do claude.ai (não listada; o usuário a compartilha pelo menu Compartilhar). Criado apenas quando o ambiente possui a ferramenta Artifact (como Claude Code).

Para manter o mesmo design, a aparência e o comportamento usam os componentes deste skill (assets/ e scripts/) diretamente. Não reescrever o CSS ou JavaScript a cada vez. Escrever apenas o conteúdo do livro (o texto) e o método de verificação do código específico da linguagem.

O maior valor de um guia de referência é que os códigos e resultados apresentados são realmente corretos. Exemplos de código, mensagens de erro e resultados de execução devem ser sempre verificados em compiladores reais ou Playgrounds oficiais (não escrever baseado em suposição). Descrições de versões e novos recursos também devem ser verificadas nas notas de versão oficiais antes de escrever.

Este é um trabalho longo que leva várias horas. A cada etapa, informe ao usuário, em 1 a 2 frases, o que está sendo feito.

1. Verificar a entrada

A entrada é o texto escrito após o nome do skill (frequentemente anexado como ARGUMENTS: no final do corpo deste skill) ou o nome da linguagem/framework na solicitação do usuário.

• Quando nada é escrito: não iniciar o trabalho. Perguntar de volta: "Qual linguagem de programação ou framework você gostaria de criar um guia de referência?" (usar AskUserQuestion com até 4 opções como Python, Java, React, Vue.js. Para outras opções, usar "Outro" para que o usuário possa escrever livremente).
• Quando algo que não é uma linguagem de programação ou framework é escrito: explicar o motivo em uma frase e pedir que o usuário insira novamente uma linguagem ou framework. Verificar a nova entrada da mesma forma e não prosseguir até que uma entrada correta seja fornecida.
• Para o tratamento de itens ambíguos, variações de escrita e múltiplas especificações, bem como exemplos de frases a serem usadas, consulte "Verificação da entrada" em references/questions.md. Se tiver dúvidas, leia-o.

Em ambientes onde AskUserQuestion não está disponível, fazer a mesma pergunta em texto e parar por ali.

2. Pesquisar antes de perguntar

Para escrever corretamente a descrição das opções, verifique os seguintes itens antes de perguntar (deve ser rápido, alguns minutos. Nenhum download grande ainda).

1. Versão estável mais recente e data de lançamento: verificar no site oficial ou nas notas de versão. Usado para o "Compatível com OO" do guia.
2. Se existe um Playground oficial (site oficial executável no navegador): se sim, verificar se há uma interface para enviar código para compilação/execução externamente, se é possível abrir uma URL com o código embutido, ou se é do tipo link compartilhável (salva o código no servidor).
3. Se já está instalado no computador (verificar com python --version, etc.). Se não estiver, verificar o tamanho da instalação temporária (tamanho do download oficial).
4. Espaço livre em disco (no Windows PowerShell: Get-PSDrive C, no Git Bash: df -h /c, no macOS/Linux: df -h ~).
5. Regras do ambiente do usuário (CLAUDE.md, AGENTS.md, etc.). Por exemplo, se houver uma regra como "não tocar em pastas sincronizadas com a nuvem (como OneDrive)", segui-la desde a pesquisa até a limpeza final.

Os métodos de pesquisa e as opções de verificação específicas para cada linguagem estão em references/verification.md.

3. Perguntar sobre as opções (as mesmas opções de antes)

Usar AskUserQuestion para perguntar as 4 coisas a seguir de uma só vez. Escrever as opções da mesma forma que nos guias de referência anteriores (o modelo textual está em references/questions.md). Colocar a opção recomendada em primeiro lugar, com o rótulo "(Recomendado)". Em ambientes sem AskUserQuestion (como Codex), apresentar as mesmas 4 perguntas e opções em uma lista numerada (incluindo também um resumo do sumário) e aguardar a resposta.

1. Público-alvo: por exemplo, "Experiente em JS/TS (Recomendado)", "Iniciante em programação". Ajustar ao público: para frameworks baseados em TypeScript (Angular, NestJS, etc.), usar "Experiente em TypeScript (Recomendado)"; para frameworks Python (Django, etc.), usar "Experiente em Python (Recomendado)".
2. Escopo: "Apenas o básico (curto, 8-9 capítulos)", "Básico + recursos comuns (Recomendado, 12-14 capítulos)", "Avançado (longo, 16-18 capítulos)". Mostrar o sumário em preview para cada opção.
3. Formato: "Mesmo formato de antes (Recomendado)" = HTML único na área de trabalho + página de compartilhamento, com perguntas de verificação, botão de copiar código, registro de capítulos lidos e busca por palavras-chave. Além disso, "Apenas arquivo HTML", "Escolher funcionalidades". Em ambientes onde não é possível criar uma página de compartilhamento (sem ferramenta Artifact), "Mesmo formato de antes" será apenas o arquivo HTML. Nesse caso, não oferecer "Apenas arquivo HTML" e não mencionar a página de compartilhamento na descrição.
4. Método de verificação: com base nos resultados da pesquisa, listar apenas os métodos disponíveis. "Verificar no Playground oficial", "Instalar temporariamente e verificar", "Verificar com OO já instalado", etc. Quando o espaço em disco é limitado, recomendar um método que não instale nada no computador.

Dependendo da resposta, pode-se fazer mais uma pergunta.

• "Escolher funcionalidades" → perguntar com seleção múltipla sobre: perguntas de verificação no final dos capítulos, botão de copiar código, marcação de capítulos lidos, glossário e busca por palavras-chave.
• Se o Playground usado para verificação for do tipo "link compartilhável" (como o Go Playground, que salva o código no servidor e cria um link), perguntar se deve "criar link compartilhável" ou "copiar e colar". Links compartilháveis tornam o código público e não podem ser apagados, portanto, obter consentimento explícito. Playgrounds que abrem URLs com código embutido (Rust, TypeScript) não salvam, então não perguntar.

Todo o conteúdo selecionado deve ser respeitado no trabalho subsequente. Não perguntar novamente sobre algo que já foi perguntado.

4. Planejar

1. Definir o sumário (consulte references/writing-guide.md). Cada capítulo deve ter aproximadamente 10 minutos de leitura. Para linguagens, o último capítulo deve ser "Como ler erros comuns". Os sumários dos 4 livros anteriores estão em references/past-books.md.
2. Escrever o spec.json (consulte references/book-spec.md para itens e exemplos). Incluir: nome da capa, versão, público-alvo, títulos dos capítulos, linguagem do código, como abrir o Playground, identidade visual (cor da marca), etc.
3. Identidade visual: usar a cor oficial da marca da linguagem ou framework. O arquivo scripts/make_palette.mjs cria cores claras e escuras a partir de uma única cor e verifica se o contraste é legível (chamado automaticamente pelo new_book.mjs).

5. Criar o modelo e escrever o texto

1. O diretório de trabalho deve ser criado dentro de um diretório temporário da sessão (como o scratchpad do Claude Code; se não houver, criar uma nova pasta dentro do diretório temporário do sistema operacional). Não criar dentro de pastas sincronizadas com a nuvem (como OneDrive).
2. Criar o modelo: node <este skill>/scripts/new_book.mjs <pasta_do_livro> --spec spec.json
   • São gerados: book.json, palette.json, src/body.html, src/ja-errors.json.
   • O src/body.html já vem com a estrutura do sumário, capa, instruções de uso, esqueleto dos capítulos, esqueleto das perguntas de verificação e esqueleto dos apêndices. Substituir todos os <!-- TODO ... --> (se algum permanecer, a montagem resultará em "necessita correção").
3. Antes de começar a escrever, ler os modelos. Em references/examples/, há extratos dos 4 livros anteriores (capa, instruções de uso, um capítulo representativo, o capítulo de erros e apêndices) — todos já montados e verificados com os componentes deste skill. Na tabela em references/examples/README.md, selecionar 1 ou 2 livros próximos ao que será criado e ler seus body.html (para linguagens, go e rust; para frameworks baseados em TypeScript, angular e typescript, etc.). Ver exemplos reais ajuda a alinhar o tom do texto, a profundidade das explicações, o tamanho das seções, a apresentação dos exemplos de código e a granularidade das perguntas de verificação muito mais do que ler regras descritas em palavras. No entanto, imitar apenas o estilo de escrita; sempre verificar novamente os fatos, como versões e recursos. Não copiar frases dos modelos substituindo apenas as palavras.
4. Escrever o texto. Seguir references/components.md para os componentes HTML (caixas, tabelas, procedimentos, perguntas de verificação, cabeçalhos de erro, etc.), references/code-blocks.md para a formatação dos exemplos de código e references/writing-guide.md para as regras de escrita. Como há muitos capítulos, é recomendável escrever alguns capítulos por vez, montar e verificar.

6. Verificar os exemplos de código

node <este skill>/scripts/build.mjs extract <pasta_do_livro>   # Extrair exemplos de código para work/
node <este skill>/scripts/checkers/go-playground.mjs <pasta_do_livro>   # Script de verificação específico da linguagem (tabela abaixo)
node <este skill>/scripts/build.mjs render <pasta_do_livro>    # Criar HTML em dist/ com os resultados embutidos

Script de verificação	Quando usar
checkers/go-playground.mjs	Go. Compila, executa, go vet e gofmt no Playground oficial do Go. Usar --share para criar link compartilhável
checkers/rust-playground.mjs	Rust. Compila, executa e mostra dicas de tipo no Playground oficial do Rust
checkers/typescript-local.mjs	TypeScript/JavaScript. TypeScript instalado temporariamente, com erros (incluindo tradução oficial para o japonês), balões e execução
checkers/local-command.mjs	Python, Java, C#, etc. Verifica e executa com comandos locais (ou instalados temporariamente)

Para linguagens ou frameworks não listados aqui (como Angular, que requer mostrar a tela renderizada), criar um novo script de verificação que gere resultados no mesmo formato (work/results.json). O formato dos resultados está em references/code-blocks.md; a abordagem de criação e exemplos anteriores estão em references/verification.md.

• Repetir até que render mostre "Necessita correção: nenhum". Para exemplos que devem conter erros, escrever // ❌ na linha (para avisos, // ⚠) para que, a cada montagem, seja verificado se o erro esperado aparece.
• Ler dist/report.txt e verificar se as mensagens de erro, resultados de execução e exibição de tipos correspondem à descrição no texto principal.
• Qualquer coisa instalada temporariamente deve ser colocada apenas dentro do diretório temporário da sessão, e o local do cache também deve ser direcionado para lá (consulte references/verification.md).

7. Verificar visualmente

Executar scripts/test_guide.py. O script serve o conteúdo de dist/ em um host local (127.0.0.1) na porta especificada.

python <este skill>/scripts/test_guide.py --book <livro> --port 8770 --search "<palavra_que_aparece_no_texto>"

• É necessário ter o Playwright do Python e o Chromium. Se não estiverem instalados, perguntar ao usuário se pode instalá-los (algumas centenas de MB no total). Se não for possível instalar, pular esta verificação e relatar o fato.
• Repetir até que todos os testes passem. Em seguida, inspecionar visualmente as capturas de tela em <livro>/shots/ (capa, instruções de uso, cada capítulo, tabela de referência, modo escuro e mobile) para verificar se há overflow, cores ilegíveis ou quebras de layout.
• Verificar também se os links externos no texto abrem e se os links do Playground abrem corretamente (abrir e executar pelo menos um).

8. Entregar e limpar

1. Se estiver previsto criar links compartilháveis, criá-los somente após o texto estar finalizado (usar --share) e verificar se todos os links abrem o código correto.
2. Copiar dist/full.html para a área de trabalho do usuário (no Windows: C:\Users\<usuário>\Desktop, no macOS: ~/Desktop) com o nome GuiaIntrodutórioDeOO.html. Se já existir um arquivo com o mesmo nome, perguntar ao usuário antes de sobrescrever.
3. Se o formato incluir página de compartilhamento e o ambiente suportar a ferramenta Artifact, chamar o quickstart e publicar dist/artifact.html (ícone: book, descrição: uma frase em japonês). Informar que a página publicada é não listada e que o compartilhamento deve ser feito pelo menu Compartilhar do usuário. Em ambientes sem suporte, pular esta etapa.
4. Remover instalações temporárias, caches e capturas de tela. Se o trabalho tiver escrito em locais compartilhados (como cache do npm), verificar e remover apenas o que foi criado pelo próprio trabalho.
5. Relatar em japonês: localização do arquivo, URL da página de compartilhamento (se criada), conteúdo (resumo do sumário), itens verificados (quantidade) e observações (ambientes não verificados, limitações do Playground, etc.).

Materiais de referência

Arquivo	Quando ler
references/questions.md	Verificação da entrada e como perguntar sobre as opções (modelos de texto)
references/book-spec.md	Como escrever spec.json e book.json
references/writing-guide.md	Estrutura de capítulos, regras de escrita e precisão
references/components.md	Componentes HTML para o texto
references/code-blocks.md	Formatação de exemplos de código, atributos e formato dos resultados dos scripts de verificação
references/verification.md	Métodos de verificação por linguagem, procedimentos de instalação temporária e limpeza
references/past-books.md	Sumários, cores, métodos de verificação e observações dos 4 livros anteriores
references/examples/README.md	Como selecionar modelos de texto (extratos dos 4 livros). Ler antes de escrever o texto