rzhang569/guia-de-estudo

Guia de Estudo

Você produz uma página HTML autossuficiente por exame, construída a partir de uma pasta do curso com arquivos simples, usando scripts/build.py. A página tem três partes:

• Notas, uma seção por aula. Cada afirmação cita um slide. Cada tópico vem com caixas em linguagem simples, exemplos resolvidos, figuras e caixas vermelhas de "armadilha". Uma caixa de prática no final de cada seção permite que o aluno se teste logo após a leitura.
• Um centro de prática com quatro abas:
  • um banco de prática com feedback instantâneo e explicação para cada opção;
  • respostas curtas passo a passo com crédito parcial;
  • simulados cronometrados retirados de seu próprio pool, nas proporções do exame real;
  • um caderno de erros que se preenche sozinho.
• Um relatório de progresso, que a página mantém para você. Você o lê depois e escreve novos exercícios que miram no que o aluno realmente errou.

O motor (assets/engine.js) e os estilos (assets/page.css) estão prontos e testados, então seu trabalho é o conteúdo e as questões. A maior parte do que torna uma página útil está nos arquivos de referência; leia-os quando chegar àquela etapa.

Quando você estiver prestes a...	Leia
escrever as seções de aula	references/content-standard.md
escrever ou auditar questões, ou calibrar o simulado	references/question-bank.md
verificar um nome de campo, o formato do progresso ou a documentação do banco	references/data-format.md

examples/demo/ é um curso pequeno completo (fictício PROB 101, três aulas). Quando não tiver certeza de como algo deve parecer, copie o padrão de suas fontes: sections/*.html, practice.json, mock.json e short.json.

Não leia assets/engine.js, assets/page.css ou qualquer review.html gerado. build.py os inlineia, eles têm dezenas de milhares de tokens, e nada neles precisa de suas edições.

Nos comandos abaixo, <skill-dir> é a pasta que contém este SKILL.md. Se python3 não for encontrado (comum no Windows), use python ou py -3.

1. Descubra o que é o exame

Obtenha estes fatos antes de escrever qualquer coisa. Pesquise-os quando possível, e pergunte ao aluno apenas o que você não puder encontrar:

• Exame: data e hora, duração em minutos, quais aulas estão no escopo, o formato e os materiais permitidos. Formato significa tipos de questão, quantas de cada e seus pontos. Materiais significa folhas de consulta, calculadora ou nada.
• Fontes: slides (PDFs ou links), leituras, o site do curso, e quaisquer questões oficiais de prática, resultados de quizzes ou exame de amostra.
• Aluno: o idioma que desejam para a página (lang: zh ou en para a interface; escreva o conteúdo no idioma deles) e quão forte é sua base. Um aluno que diz "estou perdido" precisa de caixas em linguagem simples em quase todos os tópicos.

Se você puder navegar, pesquise o curso você mesmo: a página de cronograma, o plano de ensino e os resultados de quizzes postados. Procure padrões que valham a pena contar ao aluno, como "as questões de verificação em sala vêm logo após um slide específico" ou "o banco oficial diz que usa o mesmo formato do exame". Coloque a logística na seção hero da página.

Verifique a política de IA do curso no plano de ensino. Alguns cursos proíbem material de estudo gerado por IA ou banem ajuda de IA em trabalhos avaliados. Se a política proibir isso, avise o aluno antes de construir. Nunca coloque respostas de lição de casa avaliada na página.

2. Calibre o simulado sem spoilers

Os alunos geralmente querem guardar o exame de amostra oficial para uma tentativa cronometrada. Então não leia suas questões; meça-o em vez disso:

python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf

O script nunca imprime texto de questão, opção ou cenário. Ele imprime:

• o número de páginas e questões, e as opções por questão;
• valores de pontos, o limite de tempo e as instruções de capa (calculadora, anotações);
• títulos de partes e intervalos de questões que compartilham um cenário ("Questões 11–14 …");
• os números das questões que remetem a material anterior.

Use a saída para definir as seções do simulado (tipos e contagens) e o limite de tempo. Uma questão que remete, como uma resposta curta reutilizando um cenário anterior, pertence àquele cenário ao descrever a estrutura do exame.

Se o script não puder lhe dizer algo, reporte como desconhecido e peça ao aluno para olhar a página de capa. Não escreva sua própria sonda que imprima palavras ou números de dentro das questões. Mesmo um "total" ou "%" perdido sugere o tópico de uma questão, e os números em uma equação entregam a questão.

Pergunte antes de abrir qualquer amostra ou chave de resposta. Mesmo quando o aluno permitir a leitura, use-a apenas para calibração (estrutura, dificuldade, estilo). Nunca copie suas questões ou cenários para a página.

3. Configure a pasta do curso

python3 <skill-dir>/scripts/build.py --init <course-dir>

Isso copia o curso de demonstração. Em seguida, edite course.json:

• title, lang e lectures. Rótulos de aula são exatamente o que questões e grupos usam, por exemplo "L1" ou "L5–L6".
• storageKey: único por curso e exame, por exemplo "bio201-mt1". O progresso é armazenado sob ele, então nunca o mude depois que o aluno começou.
• mock.sections: uma entrada por tipo de questão, na ordem do exame, com contagens correspondendo ao papel real.
• mock.minutes: limites para escolher. Inclua o real; se o simulado omitir questões longas, também ofereça um proporcionalmente mais curto.

Exclua as seções e questões da demonstração à medida que as substituir. Veja references/data-format.md para cada campo.

4. Escreva as seções

Escreva um arquivo por aula em sections/ (10-l1.html, 20-l2.html, …), mais 00-hero.html para logística e uma lista final de armadilhas. Cada aula é uma <section class="part" id="...">. Sua caixa de prática aparece automaticamente quando um grupo de prática aponta para aquele id com "sec".

references/content-standard.md tem a receita completa e o HTML para cada componente. Em resumo: cite cada afirmação, abra aulas difíceis com um glossário e analogias, dê a cada tópico uma linha de abertura, um exemplo concreto antes de qualquer fórmula, uma caixa em linguagem simples, uma figura onde uma imagem ajudar, e uma caixa de armadilha para o que questões verdadeiro/falso torcem.

5. Escreva as questões

Existem três bancos. references/question-bank.md tem as regras e a lista de verificação de auditoria.

• practice.json: 8–15 questões por aula. Misture escolha única, verdadeiro/falso, múltipla escolha e preenchimento, além de um flashcard ocasional. Cada opção tem sua própria explicação.
• mock.json: suas próprias questões, nunca cópias de itens de prática. Mire cerca de duas vezes o que um papel extrai de cada tipo, para que papéis repetidos difiram. Combine com o estilo do exame real.
• short.json (opcional): versões passo a passo dos tipos de resposta curta do exame. Cada passo é um preenchimento tolerante, uma escolha ou uma auto-verificação contra a resposta modelo.

6. Construa e verifique

python3 <skill-dir>/scripts/build.py <course-dir>

Erros param a construção. Avisos vêm das verificações do banco de questões; corrija-os a menos que tenha um motivo para não fazer isso. Eles sinalizam padrões como:

• a resposta correta é a opção mais longa em muitas questões;
• uma letra é a resposta mostrada com muita frequência;
• toda múltipla escolha tem o mesmo número de respostas;
• uma questão do simulado é uma questão de prática com números novos.

Adicione --strict para fazer os avisos terminarem a construção com código de saída 2 (a página ainda é escrita), para que você possa continuar corrigindo até que esteja limpa. Em seguida, abra <course-dir>/review.html em um navegador e verifique:

• o console não mostra erros e as fórmulas renderizam;
• responder a uma questão de prática, um passo de resposta curta e um simulado completo funciona;
• a 375 px de largura, nada rola a página lateralmente (figuras e tabelas rolam dentro de suas próprias caixas);
• nenhum texto em uma figura sobrepõe uma linha, uma ponta de seta ou outro texto (faça uma captura de tela).

7. Entregue

• Local (qualquer agente): forneça o caminho do arquivo. O progresso é salvo no localStorage daquele navegador. O botão Exportar progresso no centro de prática dá ao aluno um JSON para colar de volta para você.
• claude.ai artifact (apenas Claude; experimental, ainda não testado de ponta a ponta): publique o HTML construído e conceda a capacidade db. Se window.claude.use("db") estiver disponível, o motor espelha o progresso para os documentos progress/practice e progress/mock e mantém um resumo em progress/report. Antes de confiar nele, responda a uma questão na página publicada e leia progress/report de volta. Se o documento estiver faltando, diga ao aluno para usar Exportar progresso.

Diga ao aluno em duas ou três linhas como usar a página: leia uma seção, faça sua caixa de prática, simulados perto do fim, e o caderno de erros no dia anterior.

8. Feche o ciclo

Quando o aluno voltar, leia o progresso dele antes de mudar qualquer coisa. Use o JSON exportado que ele colar ou enviar (seu campo report), ou o documento progress/report do banco se a sincronização de artefato estiver funcionando. O relatório lista:

• precisão na primeira tentativa por aula;
• cada questão de prática errada, com o que ele respondeu e a resposta certa;
• passos de resposta curta que ele errou;
• histórico de simulados, mais as questões erradas e sinalizadas do último papel.

Então:

1. Nomeie os pontos fracos em algumas linhas. Conte aulas abaixo de cerca de 80% de precisão na primeira tentativa, equívocos repetidos e passos de resposta curta que continuam falhando. Conte também questões sinalizadas como inseguras, mas respondidas corretamente; essas também são conhecimento instável.
2. Escreva novos exercícios para cada ponto fraco. Refaça a mesma pergunta com palavras, números ou cenários diferentes; nunca repita a questão que ele errou. Adicione-os a practice.json com novos ids, e a mock.json se o pool do simulado estiver ralo ali.
3. Corrija a explicação, não apenas as questões. Se um equívoco se repete, a seção provavelmente o explica mal. Adicione uma caixa em linguagem simples, um exemplo resolvido ou uma figura voltada exatamente para essa confusão.
4. Reconstrua, depois diga ao aluno o que mudou e onde.

Mantenha o progresso salvo válido ao editar

Os registros são indexados por storageKey, id da questão e índice original da opção. Então:

• mantenha o storageKey e os ids existentes;
• não reordene, insira ou exclua opções em questões que já foram respondidas (adicione uma nova questão em vez disso);
• não reutilize um id antigo para uma questão diferente;
• se o significado ou a resposta de uma questão mudar, dê a ela um novo id e remova o antigo. Registros para ids removidos são ignorados, não mal interpretados.

O motor embaralha a ordem em que as opções são mostradas com uma semente do id, então os índices armazenados permanecem corretos. Para mudar a letra que uma resposta é mostrada, defina "show" (veja references/data-format.md) em vez de reordenar opções. Corrigir erros de digitação ou redação em enunciados e explicações é sempre seguro, assim como editar o HTML da seção.

O que os alunos pediram

Essas lições vêm da construção de páginas de revisão que foram usadas para exames reais:

• Explicações abstratas não funcionaram. Os alunos pediram números concretos primeiro ("jogue uma moeda 10 vezes…"), depois a fórmula, com derivações recolhidas e rotuladas como não estando no exame.
• Estudar várias aulas antes de praticar era exaustivo. É por isso que cada seção termina com sua própria caixa de prática.
• A rigidez com o formato era irritante, como ser marcado errado por 1/2 em vez de 0.5. O motor compara respostas numéricas por valor; liste variantes de texto em accept.
• Os alunos aprendem padrões de resposta rápido. A resposta correta era geralmente a opção mais longa, toda múltipla escolha tinha 3 respostas, e a resposta correta era sempre B. A construção audita os dois primeiros; o motor embaralha a ordem de exibição.
• Um simulado que reutilizava questões de prática media memória, não compreensão. É por isso que o pool do simulado é separado.
• Os alunos queriam selecionar texto de opção para copiá-lo, e um temporizador que envia automaticamente quando o tempo acaba.