VIABLE-Learning-Lab/construindo-para-aprendizes

Construindo para aprendizes

Você sabe escrever o código. O que você não pode ver daqui é a sala: trinta crianças abrindo isso às 9:05 de um único endereço escolar, um Chromebook compartilhado, um quiz cujas respostas estão a um "Exibir código-fonte" de distância, um tutor que faz o dever de casa, uma chave que a turma pode gastar. Siga isto, em ordem, e diga em palavras simples: a pessoa que você está ajudando pode nunca ter lido código.

Comandos aqui dizem viable-harness. Até que esteja no npm, use npx github:VIABLE-Learning-Lab/viable em seu lugar.

1. Pergunte antes de construir

Pergunte o que você não pode saber a partir do pedido, em uma mensagem, depois escreva as respostas em LEARNERS.md na raiz do projeto.

• Quem são os aprendizes? Menores de 13, de 13 a 17, ou adultos: isso muda o que é permitido.
• O que eles devem ser capazes de fazer depois? Uma frase. Isso decide para que serve a ferramenta.
• Onde e quantos? Em horário de aula em computadores da escola, ou em casa? Quantos ao mesmo tempo? Eles compartilham computadores?
• Com o que você tem que trabalhar? Um Chromebook não pode rodar um servidor ou os comandos abaixo. Quem irá hospedá-lo?
• Precisa de IA enquanto os aprendizes usam? Frequentemente não: você pode construir um quiz sem IA.
• O que é mantido, e quem vê? Alguém precisa de um nome, ou um código basta?
• Quem cuidará dele no próximo semestre? Outras pessoas dependerão dele?

Se eles quiserem que a IA responda aos aprendizes, pergunte isto na mesma mensagem, porque cada uma pode mudar a resposta:

• De quem é a conta que paga, e o provedor dela permite esses aprendizes? Diga agora, para qualquer um menor de 18 anos, que a chave pessoal de um professor muitas vezes não pode ser usada para isso. referencias/dados-do-aprendiz.md diz o que três provedores pedem. Leia antes de enviar a mensagem.
• Quem é avisado quando um aprendiz diz algo alarmante, e com que rapidez?
• Quanto pode gastar em um dia, e o que os aprendizes devem ver então?
• Por quanto tempo uma conversa é mantida?

Adicione isto ao AGENTS.md ou CLAUDE.md do projeto, para que sessões posteriores mantenham:

Aprendizes usam isto. Leia LEARNERS.md primeiro. Nunca coloque uma chave de modelo, um gabarito de respostas que conta, ou o nome de um aprendiz na página ou em um prompt. Execute `viable-harness review` antes de compartilhar.

2. Construa o mínimo que faz o trabalho

Cada etapa adiciona algo que uma pessoa tem que executar, pagar e responder. Pare na etapa mais baixa que faz o trabalho, e diga a eles por quê.

Etapa	O que é	O que envolve
0. Uma página	Sem contas, nada salvo em um servidor, sem IA enquanto os aprendizes usam	Quase nada. A maioria dos quizzes, jogos e simulações pertencem aqui
1. Uma página que lembra	Trabalho salvo sob um código de turma, sem nomes	Um banco de dados com regras, e excluir o que é mantido
2. IA ao lado do aprendiz	Um modelo respondendo aos aprendizes	Um servidor segurando a chave, um orçamento por turma, regras para a IA, testes, o que acontece quando um aprendiz diz algo alarmante, e, já que um adulto deve poder ler, um banco de dados e uma página para o professor. É aqui que uma pequena página se torna um aplicativo: cerca de mil linhas com seus testes, quando tentamos
3. Nomes e registros	Uma lista de turma, trabalho por pessoa, notas	Regras para os dados, por quanto tempo são mantidos, e geralmente o acordo da escola
4. Um estudo	Consentimento, condições, uma exportação	Um comitê de revisão, e um registro de qual versão fez o quê

Pare e diga isso, quem quer que peça, e ofereça a coisa mais próxima que vale a pena construir:

• IA que escreve PEIs, planos 504, planos de comportamento ou relatórios de progresso. Eles precisam de informações de muitas fontes ao longo do tempo (Common Sense).
• Um chat aberto com crianças que nenhum adulto pode ler.
• Qualquer coisa que decida uma nota, uma colocação ou uma punição por si só.

Se aprendizes reais vão usá-lo, não é mais um protótipo. "Eu fiz sozinho" não isenta uma ferramenta da revisão da escola (CoSN). Diga a eles cedo.

3. A partir da etapa 2, decida quem executa o quê

Uma Skill molda o que você escreve. Na sala de aula, alguém ainda tem que segurar a chave, vigiar o orçamento e responder por isso. Ofereça estas opções, com o que cada uma custa a eles, e deixe-os escolher.

Eles querem	Use	Eles ainda fazem
Uma turma com um tutor de IA, e nenhuma página própria	Plataforma de Aprendizagem VIABLE: diga o que está ensinando	Nada para construir, então diga isso antes de construir qualquer coisa
Sua própria página, com outra pessoa cuidando das chaves, limites e tráfego	A API VIABLE como endpoint do modelo: uma chave por turma, cada uma com suas próprias requisições por minuto, tokens diários e custo mensal, e uso para consultar	Um pequeno servidor que segura a chave
Sua própria página e sua própria conta de modelo	Seu servidor, com os padrões em referencias/sala-de-aula.md	Tudo
Tudo em seu próprio servidor	O Motor VIABLE	Executar um servidor
Um estudo com consentimento e condições	A Plataforma de Desenvolvedor VIABLE	Nada para hospedar

Se os aprendizes forem menores de 18, peça que consultem o VIABLE Lab sobre o que se aplica antes de confiar em uma opção VIABLE, como com qualquer provedor. Esta Skill não pode responder isso por eles, e nem você.

4. Encontre o que precisa, em vez de adivinhar

• Padrões e habilidades: viable-harness catalog "<algumas palavras>" encontra padrões abertos, conjuntos de dados e ferramentas com suas licenças. Verifique uma licença antes de confiar em um.
• O que os aprendizes erram: viable-harness misconceptions "<algumas palavras>", para matemática. Construa respostas erradas e dicas a partir disso.
• O que a pesquisa diz para fazer: viable-harness guidance "<algumas palavras>" dá o que fazer em um momento do ensino, cada peça nomeando seus estudos. Mantenha a fonte junto, e não cite um estudo que você não obteve de uma fonte: citações inventadas são comuns.

Com o servidor MCP do Harness conectado, a ferramenta find_public_goods, a ferramenta find_misconceptions e a ferramenta find_guidance fazem o mesmo.

5. Mantenha isto enquanto constrói

Antes de escrever qualquer coisa para as etapas 2 a 4, leia referencias/sala-de-aula.md e referencias/dados-do-aprendiz.md. Para uma IA que responde a aprendizes, leia também referencias/ia-ao-lado-dos-aprendizes.md.

• Chaves e o que a IA recebe ficam em um servidor. A página chama seu servidor.
• Contagem por aprendiz ou por turma, nunca por endereço. Uma escola é geralmente um endereço. Com um código de turma e sem nomes, você não pode distinguir um aprendiz de outro: conte por turma, com um limite aproximado por navegador.
• Dê a cada turma um orçamento contado no servidor, com uma mensagem clara quando acabar, e uma página que ainda funcione sem IA.
• Nenhum nome de aprendiz em um prompt, e nenhum script de análise ou publicidade em páginas que os aprendizes abrem. O que uma criança digita também pode conter dados pessoais, então as regras do provedor cobrem o próprio chat.
• Respostas ficam em um servidor quando contam. Não acredite em um navegador que diz que uma resposta estava correta.
• Computadores compartilhados: o que um aprendiz escreveu não aparece na página para o próximo. "Você é o Sam?" pega erros, mas qualquer um pode pressionar Sim.
• Um professor permanece no controle: eles abrem, podem parar, e podem ver quem está preso. Sem nomes, "quem" é um número.
• Leia e funcione para todos: o nível de leitura dos aprendizes, uso de teclado e leitores de tela, WCAG 2.1 AA, uma tela pequena e uma rede lenta.

6. Verifique antes de alguém usar

viable-harness review

Ele lê o texto do projeto para o que as salas de aula tropeçam, sem modelo e sem nada sair do computador. Corrija o que ele diz que deve ser corrigido, e leia o resto com a pessoa que você está ajudando. Uma linha que você olhou e com a qual está satisfeito pode dizer por quê, em um comentário com viable-review: ok, como um limite alto em códigos errados. Ele não pode ver se um orçamento funciona, o que acontece na sala de aula, ou acessibilidade: um resultado limpo não é uma aprovação.

Se a ferramenta tiver uma IA que responde a aprendizes, copie tutor-tests.json para o projeto, e mude a pergunta e a resposta para o próprio assunto da ferramenta. Ele pede respostas, insiste, diz algo alarmante, dá uma resposta correta e uma errada, e tenta acessar o prompt. As pessoas e lugares nele são inventados. Execute no que a IA recebe:

OPENAI_API_KEY=<uma chave para aquele endpoint> viable-harness test tutor-tests.json --endpoint https://api.openai.com/v1 --endpoint-model <seu modelo> --system "$(cat prompt.txt)" --judge-model <outro modelo>

--endpoint é qualquer endereço compatível com OpenAI, terminando em /v1. Ele faz 28 chamadas de modelo, alguns centavos no máximo em um modelo pequeno. Se o professor pode mudar o quanto a IA ajuda, execute em cada configuração: viable-harness draft-tests escreve casos para uma configuração.

Em seguida, ensaie a sala, com um substituto para o modelo se você não tiver chave:

• Dois navegadores ao mesmo tempo em um endereço, com a segunda pessoa não vendo nada da primeira.
• Feche a página no meio de uma frase e volte. Atinga o orçamento. Desligue o modelo.
• Diga algo alarmante como um aprendiz, depois veja o que o professor vê, enquanto eles estão fazendo outra coisa.
• A menor tela que eles usarão, e a própria rede da escola, se possível: filtros bloqueiam novos endereços.

7. Entregue honestamente

Diga à pessoa, em palavras simples: o que faz; o que mantém, onde e por quanto tempo; quem pode ver; o que custa e o que acontece no limite; o que você verificou; e o que ninguém verificou. Nunca diga que é seguro ou que está em conformidade com FERPA, COPPA ou qualquer lei. Você não pode saber isso, e apenas uma pessoa pode responder por isso. Dê a eles a lista de perguntas que sua escola fará, de referencias/dados-do-aprendiz.md.