Do chat ao seu ambiente de agentes, uma aula curta de cada vez. Você organiza arquivos, ensina procedimentos à IA e monta rotinas que consegue conferir. Cada aula traz no fim o material completo do tópico para quem quer ir mais fundo.
Módulo 1 · Modelos: escolha pela tarefa
Comparar modelos com uma tarefa real e um critério de qualidade.
Metade pública do par de chaves do SSH. Fica cadastrada na VPS; a outra metade, a chave privada, fica só no seu computador e nunca é colada em lugar nenhum.
Cópia do .env com os mesmos nomes de variáveis e valores fictícios. Mostra o que é preciso preencher sem dar acesso a nada, por isso pode ser compartilhada.
Documento curto em que você anota como um trabalho com IA funciona: ferramentas, acesso, decisões e pendências. Pode ser uma nota no celular. No módulo 4 ele vira um arquivo da pasta do projeto.
Exemplo de modelo de classificação citado no curso. Não conversa: recebe um texto e alternativas fechadas e devolve uma escolha, um sim ou não, ou uma nota.
Arquivos de consulta com fatos estáveis, decisões e causas de falhas, que o agente lê quando você indica. Não muda o modelo; alguém precisa mantê-los em dia.
Você consegue desenhar as sete peças do seu sistema de IA e apontar qual delas falta para concluir uma tarefa real desta semana.
Quando a resposta sai ruim, a reação comum é trocar de ferramenta ou escrever um pedido maior. Muitas vezes o problema está em outra peça: faltou o arquivo, a permissão ou a forma de conferir. Esta aula mostra onde procurar.
Em 1 minuto
Um modelo produz texto a partir do que você entrega.
Não existe melhor modelo: existe o adequado à tarefa.
O resultado depende de sete peças, e a falha costuma estar numa delas.
1O modelo trabalha com o que recebe
Quando este curso fala em IA, fala em modelos de linguagem, as LLMs. Um modelo é um mecanismo treinado para produzir texto a partir do que você entrega.
Ele não enxerga a sua escola, a sua equipe nem a reunião da semana passada. O que falta no pedido, ele completa com o jeito mais comum de responder.
Denise, coordenadora pedagógica, pediu um plano para a reunião de pais. Sem a pauta, a IA imaginou prioridades. Com a pauta e a ata anterior coladas, voltou uma proposta que ela conseguiu conferir.
Chat de IA
VocêMonte um plano para a reunião de pais do 8º ano.
IASugestão de plano: 1. Boas-vindas. 2. Apresentação do projeto pedagógico. 3. Calendário de provas…
Prioridades inventadas. Nada disso estava na pauta da escola.
VocêMonte um plano para a reunião de pais do 8º ano, usando só a pauta e a ata abaixo. Marque o que ficou pendente da reunião anterior.
[pauta colada]
[ata anterior colada]
IAPlano a partir da pauta enviada:
1. [item 1 da pauta]
2. [item 2 da pauta]
Pendente da ata anterior: [pendência registrada na ata]
Mesma IA. Agora cada item aponta para um papel que Denise tem na mão.
Toque nos dois botões e compare o que a IA recebeu em cada caso.
2Não existe o melhor modelo
Existem vários modelos, com nomes, tamanhos e custos diferentes. A pergunta "qual é o melhor?" não tem resposta útil.
A pergunta que ajuda é outra: qual modelo resolve esta tarefa, neste prazo, com este custo e com o quanto você vai precisar conferir? Por isso o módulo compara modelos com uma tarefa real, e não com opinião.
Lúcia, professora de ciências, parou de procurar "a melhor IA". Agora ela pergunta qual ferramenta corrige a lista de exercícios do 8º ano no tempo que ela tem.
Pergunta que trava
"Qual é a melhor IA?"
Cada pessoa responde uma coisa. Nenhuma resposta vale para a sua tarefa.
Pergunta que decide
"Qual modelo resume esta ata em dez linhas, hoje, e me deixa conferir os três responsáveis?"
Dá para testar e comparar.
3Sete peças fazem o sistema
Um modelo produz respostas. Um sistema organiza como essas respostas viram trabalho. O OSWork combina sete peças: modelo, interface, arquivos, instruções, ferramentas, memória e automações.
O nome OSWork é uma metáfora de organização. Você não vai trocar o sistema do seu computador.
Denise desenhou as sete caixas para a tarefa "ata da reunião de pais". Tinha modelo e interface. Faltavam os arquivos: a pauta estava no e-mail de outra pessoa.
Bancada de Denise · ata da reunião
1 Modelo — o chat da escola ✓
2 Interface — a janela do chat ✓
3 Arquivos — pauta e ata anterior ✗ falta
4 Instruções — regras fixas que a IA segue (módulo 5) · ?
5 Ferramentas — o que a IA pode executar, como gravar arquivo (módulo 3) · ?
6 Memória — o que fica guardado entre conversas (módulo 5) · ?
7 Automações — tarefas que rodam sem você abrir o chat (módulos 7 e 8) · ?
1O modelo raciocina sobre o que recebe.
2A interface recebe o objetivo.
3Os arquivos dão evidência. Sem eles, a IA imagina.
4As peças 4 a 7 ganham um módulo cada. Por enquanto, um "?" basta.
Quer uma comparação do dia a dia?
Pense numa pequena oficina. A habilidade do profissional importa, mas ferramentas, materiais e critérios de qualidade também decidem o resultado.
Teste-se
No computador da escola, o plano da reunião saiu certo. No celular, com o mesmo chat, a IA inventou dois itens. Você tinha colado só metade da pauta. Qual peça falhou?
4Corrija a peça certa
Separar as peças evita o reflexo de escrever um pedido cada vez maior. Primeiro você pergunta onde a falha nasceu. Depois corrige só ali.
E uma peça nunca sai do sistema: você. O modelo raciocina, as ferramentas executam, e quem confere é você.
A IA de Lúcia disse que tinha salvo as notas, mas o arquivo não apareceu. Faltava uma ferramenta com permissão para gravar. Escrever o pedido de novo não resolveria.
Sintoma → peça que falta
1 Inventou prioridades → arquivos: a pauta e a ata
2 Disse que salvou, e não salvou → ferramenta com permissão para gravar
3 Ninguém sabe se está certo → você, que confere
A terceira linha não é uma das sete peças: é quem usa o sistema.
Se travou aqui, é normalSete peças parecem muitas no começo. Nesta aula você só precisa julgar três: modelo, interface e arquivos. Nas outras quatro, um "?" é a resposta certa por enquanto.
Pratique agora 0/3
Desenhe as sete peças de uma tarefa sua
Pronto quando você circular, entre modelo, interface e arquivos, a peça que falta numa tarefa real desta semana. Cerca de 8 minutos, no papel ou nas Notas do celular.
É só um desenho: nada é enviado para ninguém. Se todas as peças parecerem presentes, escolha uma tarefa que deu retrabalho recentemente.
Você acabou de enxergar o seu uso de IA como um sistema e apontar a peça que falta.
Cola da aula
Sete peças
Modelo certo para a tarefanão existe o melhor em geral.
Falhou?ache a peça antes de reescrever o pedido. Quem confere é você.
Seu próximo passo
Você já sabe localizar a peça que falta quando a IA erra.
Hoje, no próximo pedido que voltar ruim, anote numa linha qual peça faltou antes de tentar de novo.
Na próxima aula: se o modelo é uma peça, que tipos de modelo existem? Texto, imagem, vídeo e classificação resolvem coisas diferentes.
Material complementar · IA como sistema de trabalhoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Quando este curso fala em IA, fala em modelos de linguagem, as LLMs. Um modelo é um mecanismo treinado para produzir texto a partir do que você entrega. Existem vários, com nomes, tamanhos e custos diferentes, e a primeira pergunta costuma ser qual é o melhor. Essa pergunta não tem resposta útil: não existe melhor modelo, existe o modelo adequado à tarefa, ao prazo, ao custo e ao nível de conferência que aquele trabalho exige. Por isso o módulo compara modelos com uma tarefa real, e não com opinião. Um modelo produz respostas; um sistema organiza como essas respostas viram trabalho. O OSWork combina modelo, interface, arquivos, instruções, ferramentas, memória e automações. Pense em uma pequena oficina: a habilidade do profissional importa, mas ferramentas, materiais e critérios de qualidade também determinam o resultado. Não estamos instalando um novo sistema operacional de computador: usamos essa expressão como uma metáfora de organização.
Por que aprender
Sem essa distinção, toda falha vira tentativa de escrever um prompt maior. Às vezes falta apenas o arquivo de entrada, uma permissão ou a forma de conferir a saída. Separar as peças permite corrigir o ponto certo.
Uma coordenadora pede um plano de reunião. Sem pauta, a IA imagina prioridades. Com pauta e ata anterior, ela consegue preparar uma proposta verificável.
✓ Faça
Desenhe sete caixas com as peças do sistema. Marque quais você já tem e qual falta para concluir uma tarefa.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Modelo
Interface
Arquivos
Instruções
Ferramentas
Memória
Automações
As sete peças do sistema. Marque o que você já tem e o que falta para concluir uma tarefa.
Aula 1 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 1 · Aula 2 de 6
Separe por função antes de comparar nomes
Você consegue dizer, para cada tarefa que repete, que tipo de modelo ela pede — texto, imagem, vídeo ou classificação — antes de escolher um nome.
Adotar um modelo como "o melhor" fecha a porta para tudo que ele não faz. Um modelo excelente de texto não gera um vídeo. Um classificador não escreve o seu relatório. Esta aula ensina a separar por função primeiro.
Em 1 minuto
Quatro funções: texto, imagem, vídeo e classificação.
Nomes e versões mudam; a função da tarefa fica.
Centrais dão acesso a vários modelos por um único ponto.
1Quatro funções, quatro tipos de modelo
Modelos de linguagem, as LLMs, escrevem, resumem, explicam e programam. Modelos de imagem e de vídeo geram ou editam material visual.
Existem ainda os modelos de classificação. Eles não conversam: recebem alternativas e devolvem uma escolha, um sim ou não, ou uma nota.
Lúcia listou o que faz com IA num mês. Resumir a ata do conselho de classe pede texto. A capa da feira de ciências pede imagem. Separar duzentos comentários da turma pede classificação.
Tarefas de Lúcia · por função
1 Texto
resumir a ata do conselho de classe
2 Imagem
capa da feira de ciências
3 Vídeo
vinheta de dez segundos da feira
4 Classificação
separar comentários em "dúvida", "elogio" e "reclamação"
1Texto: escrever, resumir, explicar.
2Imagem: gerar ou editar figuras.
3Vídeo: gerar clipes.
4Classificação: escolher e pontuar.
2Nomes mudam, a função fica
ChatGPT, Gemini e Copilot são chats: por trás de cada um há modelos de linguagem. Dentro de cada tipo há famílias com nomes próprios. Em texto, a família GPT tem Sol, Terra e Luna, além do GPT-6 Astra. A família Claude tem Opus e Fable.
Você não precisa decorar essa lista: esses nomes são de uma consulta de 20/09/2026. Nomes, versões e disponibilidade mudam. Por isso a escolha acontece quando a tarefa aparece, e pode ser outra na semana seguinte.
Denise ouviu de uma colega que "tal modelo é o melhor" e quis usá-lo para tudo. Ao pedir a arte do convite da festa junina, descobriu que ele só escrevia texto.
Escolha pelo nome
"Vou usar o modelo que todo mundo elogia, para tudo."
A arte do convite não sai: o modelo é de texto.
Escolha pela função
Convite em texto: um modelo de linguagem. Arte do convite: um modelo de imagem.
Cada tarefa vai para o tipo que sabe fazê-la.
3O classificador não conversa, escolhe
Um classificador, como o Jev, recebe um texto e uma lista fechada de alternativas. Ele devolve uma escolha, e não um parágrafo.
Para triar muitos itens entre poucas categorias, isso pode ser mais simples de conferir do que uma conversa. É uma hipótese para testar, não uma garantia. Dá para experimentar a ideia hoje no próprio chat: cole os itens e peça "responda só com uma destas categorias".
Lúcia colou no chat um comentário de aluno e as três categorias, pedindo só a categoria. Voltou uma palavra só. Ela conferiu dez respostas na mão antes de confiar nas outras.
Classificador
VocêComentário: "Não entendi a parte da fotossíntese que caiu na prova."
Categorias: dúvida · elogio · reclamação
IAdúvida
Uma escolha entre as alternativas dadas. Fácil de conferir em lote.
Teste-se
Denise recebeu 300 respostas abertas de pais sobre o horário de entrada. Ela quer saber quantas pedem mudança. Que tipo de modelo ela testa primeiro?
4Centrais abrem várias portas por um ponto
Há ainda as centrais, que dão acesso a vários provedores por um único ponto. O OpenRouter reúne modelos de linguagem. O Kie reúne modelos de imagem e de vídeo.
A disponibilidade varia por conta, por plano e por liberação. Um modelo que aparece para uma colega pode não aparecer para você.
Para a vinheta de dez segundos da formatura, Denise não precisou assinar um serviço de vídeo por modelo. Numa central de imagem e vídeo, comparou dois modelos no mesmo lugar, com uma conta só.
Central de texto
OpenRouter
Vários modelos de linguagem num só ponto de acesso.
Central de imagem e vídeo
Kie
Vários modelos de imagem e de vídeo num só ponto de acesso.
Cada central tem crédito próprio. A aula 5 mostra como isso entra na conta.
Se travou aqui, é normalA lista de nomes cansa e envelhece rápido. Guarde só as quatro funções. Os nomes você consulta em "Onde consultar os nomes atuais", na prática desta aula, quando a tarefa aparecer.
Pratique agora 0/3
Classifique as suas três tarefas mais repetidas
Pronto quando cada tarefa tiver um tipo de modelo e só depois um nome. Cerca de 8 minutos, no papel ou nas Notas do celular.
Ninguém vê essa lista além de você. Ficou em dúvida entre dois tipos? Escreva os dois: o laboratório do módulo, no material complementar da aula 6, compara na prática.
TAREFA 1: <ex.: resumir a ata do conselho>
Tipo: <texto, imagem, vídeo ou classificação>
Nome para testar: <preencha por último>
TAREFA 2: <…>
Tipo: <…>
Nome para testar: <…>
TAREFA 3: <…>
Tipo: <…>
Nome para testar: <…>
Você acabou de escolher pela função antes do nome, para as tarefas que mais se repetem.
Cola da aula
Função antes do nome
Quatro tipostexto, imagem, vídeo, classificação.
Nomes envelhecemconsulte a data e a fonte antes de escolher.
Centraisvários provedores num ponto, com crédito próprio.
Seu próximo passo
Você já sabe separar as suas tarefas pelo tipo de modelo que cada uma pede.
Guarde a lista da prática num documento ou nas Notas. Se fizer o laboratório opcional do módulo, no fim da aula 6, você testa uma dessas tarefas em dois modelos.
Na próxima aula: dentro do mesmo modelo ainda existe um controle, o esforço de raciocínio. Aumentar nem sempre melhora.
Material complementar · Tipos de IA e para que servemTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Antes de comparar nomes, separe por função. Modelos de linguagem, as LLMs, escrevem, resumem, explicam e programam: aí entram famílias como GPT, com Sol, Terra e Luna, o GPT-6 Astra, e a família Claude, com Opus e Fable. Modelos de imagem e de vídeo geram ou editam material visual. E existem modelos de classificação, como o Jev, que não conversam: recebem alternativas e devolvem uma escolha, um sim ou não, ou uma nota. Há ainda as centrais, que dão acesso a vários provedores por um único ponto: o OpenRouter para modelos de linguagem e o Kie para imagem e vídeo. Nomes, versões e disponibilidade mudam; esta consulta é de 20/09/2026.
Por que aprender
Adotar um modelo como o melhor fecha a porta para tudo que ele não faz. Uma LLM excelente não gera um vídeo, e um classificador não escreve o seu relatório. Entender para que cada tipo serve vem antes de escolher, e a escolha acontece quando a tarefa aparece, podendo ser outra na semana seguinte. Disponibilidade também varia por conta, cliente, autenticação e liberação.
Conceitos-chave
Texto; imagem; vídeo; classificação; centrais de acesso; disponibilidade.
Na prática
Resumir uma ata pede um modelo de linguagem. Triar duzentos comentários entre três categorias pode caber melhor em um classificador como o Jev. Produzir uma vinheta de dez segundos exige um modelo de vídeo, normalmente acessado por uma central. São hipóteses para testar, não garantias.
Experimente agora
Liste as três tarefas de IA que você mais repete. Ao lado de cada uma escreva o tipo de modelo que ela pede e só depois o nome que pretende testar; consulte as fontes no fim do módulo.
Texto · LLMs — resumir e escrever
Imagem — gerar e editar
Vídeo — gerar clipes
Classificação — escolher e pontuar
OpenRouter · texto
Kie · imagem e vídeo
Separe por função antes de comparar nomes. As centrais dão acesso a vários provedores por um ponto só.
Aula 2 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 1 · Aula 3 de 6
Modelo e esforço são dois controles
Você consegue repetir um pedido mudando só o esforço de raciocínio e dizer, com uma evidência, se o resultado melhorou.
Muita gente liga o esforço máximo em toda tarefa, por garantia. Isso pode gastar mais tempo e mais consumo sem melhorar nada. E nenhum esforço traz de volta o documento que faltou no pedido.
Em 1 minuto
O modelo é o mecanismo; o esforço é uma configuração dele.
Comece pelo padrão. Complete as entradas antes de subir o esforço.
Para comparar, mude um controle só e mantenha o resto igual.
1Dois eixos diferentes
O modelo é o mecanismo escolhido. O esforço de raciocínio é uma configuração desse mecanismo: quanto ele analisa antes de responder.
Níveis mais altos podem gastar mais tempo e mais tokens. Os nomes do seletor mudam entre o Chat, o Work e o Codex. Não existe uma lista única de níveis que valha para todos os produtos.
Denise achava que trocar o nível era trocar de IA. Descobriu que, no mesmo modelo, dá para pedir uma resposta rápida ou uma análise mais longa.
Seletor do chat
1 Modelo: [o modelo escolhido]
2 Esforço: [nível atual] · [nível acima]
1Primeiro controle: qual mecanismo trabalha.
2Segundo controle: quanto ele analisa. Os nomes dos níveis variam de produto para produto.
2Mais esforço não traz o arquivo que faltou
Aumentar o esforço não fornece um documento que ficou de fora. Se a resposta depende de um dado, o dado precisa estar no pedido.
Primeiro complete as entradas. Depois avalie se o problema pede mais análise.
Lúcia queria saber por que a planilha de notas da secretaria discordava da dela. No esforço máximo, sem as planilhas, recebeu hipóteses gerais. No padrão, com as duas planilhas coladas, recebeu a linha exata da diferença.
Esforço máximo, sem planilhas
Pedido: "Por que as duas planilhas de notas não batem?"
Resultado: uma lista de causas possíveis, sem apontar nenhuma.
Padrão, com as duas planilhas
Pedido: o mesmo, com as duas planilhas coladas.
Resultado: "[aluno] tem nota diferente na [avaliação] entre as duas versões."
Saldo: a entrada certa resolveu o que o controle no máximo não resolveu.
3Comece pelo padrão
Para a maioria das tarefas do dia a dia, o esforço padrão resolve. Reserve mais análise para o que envolve várias etapas ou muitos dados.
Denise precisava reescrever um convite de cinco linhas para a reunião de pais. No padrão, a resposta veio em segundos e servia.
Chat de IA · esforço padrão
VocêReescreva este convite em tom cordial, em até cinco linhas. Mantenha a data e o horário exatamente como estão.
[convite colado]
IAQueridas famílias, convidamos vocês para [o evento do convite] no dia [data do convite], às [horário do convite]…
Tarefa curta e bem definida: o padrão basta.
Teste-se
Primeira rodada: esforço padrão, uma planilha. Segunda rodada: esforço máximo, duas planilhas. A segunda saiu melhor. O que dá para concluir sobre o esforço?
4Compare em condições iguais
Para saber se o esforço ajudou, repita o mesmo pedido, com o mesmo material, no mesmo modelo. Mude só o esforço.
Depois registre: houve uma melhora que você consegue mostrar? Um fato a mais, um erro a menos, uma conta certa. "Ficou melhor" sem evidência não conta.
Lúcia pediu a mesma correção comentada duas vezes. No nível mais alto, apareceu um erro de unidade que o padrão tinha deixado passar. Ela anotou qual foi.
Registro do teste de Lúcia
1 Pedido: igual nas duas rodadas
2 Material: a mesma resposta do aluno
3 Esforço: padrão → mais análise
4 Melhora demonstrável: apontou o erro de unidade (km em vez de m)
1O pedido não muda.
2O material não muda.
3Só um controle muda.
4A melhora é algo que você aponta com o dedo.
Se travou aqui, é normalSeu chat pode não mostrar um controle de esforço: depende do produto e do plano. Nesse caso, anote "sem controle de esforço" no registro e faça outra comparação de um controle só: troque apenas o modelo. É um teste diferente, mas o método é o mesmo. Sem nenhum dos dois controles? Compare dois chats que você já usa, com o mesmo pedido e o mesmo material.
Pratique agora 0/3
Rode o mesmo pedido em dois níveis de esforço
Pronto quando o registro disser se houve melhora demonstrável, com a evidência. Cerca de 10 minutos, no chat que você já usa. Procure o controle de esforço perto da caixa de mensagem ou no seletor de modelo; às vezes ele aparece como uma opção de raciocínio ou de "pensar mais".
Use um material seu que não seja sigiloso, ou invente um curto. Se as duas respostas saírem iguais, isso também é um resultado: o padrão basta para essa tarefa.
PEDIDO (igual nas duas rodadas)
<ex.: aponte os erros desta resposta de aluno e explique cada um em uma linha>
MATERIAL (igual nas duas rodadas)
<cole aqui o texto, a tabela ou a resposta>
REGISTRO
Controle que mudei: <esforço · modelo · chat>
Rodada 1 · <ex.: esforço padrão> · o que veio: <…>
Rodada 2 · <ex.: esforço acima> · o que veio: <…>
Melhora demonstrável? <sim ou não> · evidência: <o fato a mais ou o erro a menos>
Você acabou de testar um controle de cada vez e decidir com evidência.
Cola da aula
Dois controles
Modelo × esforçosão eixos diferentes; o nome dos níveis varia.
Entrada primeironenhum esforço substitui o arquivo que faltou.
Um controle por vezmelhora só conta com evidência.
Seu próximo passo
Você já sabe testar se mais esforço vale a pena numa tarefa sua.
Na próxima tarefa longa, rode primeiro no padrão. Só suba o esforço se conseguir dizer o que faltou na resposta.
Na próxima aula: "melhorou" precisa de uma régua. Você vai escrever três critérios antes de pedir e usar a régua para escolher entre duas respostas.
Material complementar · Modelo não é esforço de raciocínioTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
O modelo é o mecanismo escolhido. O esforço de raciocínio é uma configuração desse mecanismo. Níveis mais altos podem gastar mais tempo e tokens, unidades de processamento de texto. Os nomes do seletor mudam entre Chat, Work e Codex; não existe uma lista única de Instant, Medium, High e Pro que represente todos os produtos.
Por que aprender
Pedir o máximo em toda tarefa pode aumentar consumo sem melhorar o resultado. Aumentar esforço também não fornece um documento que estava faltando. Primeiro complete as entradas, depois avalie se o problema pede mais análise.
Conceitos-chave
Modelo e esforço são eixos diferentes; comece pelo padrão; compare em condições iguais.
Na prática
Para reescrever um convite de cinco linhas, o padrão pode resolver. Para explicar por que duas planilhas discordam, fornecer as duas planilhas costuma importar mais que mover um controle.
Sequência para experimentar
Prepare uma cópia de treino.
Repita um pedido no mesmo modelo, mudando somente o esforço. Registre se houve melhora que você consegue demonstrar.
Registre o resultado observado e a próxima correção.
Aula 3 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 1 · Aula 4 de 6
Uma régua transforma opinião em observação
Você consegue escrever três critérios antes do pedido e usar essa régua para decidir, sem discussão, qual de duas respostas serve.
Sem critério, você escolhe a resposta mais bonita. Um resumo pode soar convincente e trocar um nome ou inventar um prazo. Esta aula mostra como decidir pelo que a resposta contém, e não pelo tom.
Em 1 minuto
Escreva a régua antes de fazer o pedido.
Três critérios: fiel aos dados, no formato combinado, com conclusões verificáveis.
Guarde uma resposta ruim para lembrar o que você quer evitar.
1Defina antes de pedir
Uma régua de qualidade diz, antes do pedido, quais fatos precisam aparecer, quais erros são inaceitáveis e como a saída será usada.
Escrita antes, ela não se deixa levar pela resposta. Escrita depois, ela costuma aprovar o que chegou.
Denise ia pedir o resumo da reunião de planejamento da feira de ciências. Antes de abrir o chat, escreveu três linhas num papel.
Desejo
"Quero um resumo bom da reunião."
Qualquer texto bem escrito passa.
Régua
1. Os três responsáveis, sem prazo que não está na ata.
2. Uma seção de pendências.
3. Cada frase dá para achar na ata.
Saldo: três perguntas de sim ou não, respondidas em menos de um minuto.
2Três critérios pequenos bastam
Para começar, use três critérios. Fidelidade aos dados: nenhum dado do material muda ou some. Formato combinado: o tamanho e as seções que você pediu. Conclusões verificáveis: nada é acrescentado que não dê para achar no material.
Os três critérios são o molde. Em cada tarefa, eles viram itens concretos. Na ata de Denise, fidelidade virou "os três responsáveis, sem prazo inventado"; formato virou "uma seção de pendências"; verificável virou "cada frase dá para achar na ata".
Lúcia usou o mesmo molde para o resumo de um capítulo do livro de ciências. Os itens mudaram: conceitos do capítulo, uma página, cada afirmação com o número da página.
Régua de Lúcia · resumo do capítulo
1 Fidelidade: só conceitos que estão no capítulo
2 Formato: uma página, em tópicos
3 Verificável: cada tópico com o número da página
1Nada inventado, nada alterado.
2A forma que você vai usar.
3Um caminho para conferir cada afirmação.
3A resposta mais bonita pode ser a pior
O teste precisa refletir o trabalho que você vai entregar, e não uma demonstração feita para impressionar. Uma frase elegante não compensa perder um responsável.
Denise recebeu duas versões do resumo. A primeira era fluida e agradável de ler. A segunda era seca. Ela passou a régua nas duas.
Duas respostas · mesma ata
IAA reunião foi produtiva e cheia de energia. Lúcia vai organizar os grupos com o entusiasmo de sempre, e Marcos reserva o pátio até sexta-feira. A feira promete!
Faltou Renata e "até sexta-feira" não está na ata. Não há pendências. "Cheia de energia" não dá para achar na ata. Reprovada nos três itens.
IADecisões: Lúcia organiza os grupos. Marcos reserva o pátio. Renata compra o material.
Pendências: confirmar a data com a direção.
Três responsáveis, nenhum prazo inventado, pendência registrada. Passa nos três.
Toque nos dois botões e passe a régua do passo 1 em cada resposta.
Teste-se
A resposta traz os três responsáveis, tem a seção de pendências e termina com "a equipe saiu motivada". Isso não está na ata. Qual critério reprova?
4Anote o esperado, o observado e guarde a ruim
Transforme a régua numa tabela de quatro colunas: critério, esperado, observado e passou? Assim a decisão fica escrita e dá para repetir o teste depois.
Guarde também uma resposta ruim. Ela lembra o que você está tentando evitar.
Lúcia colou a tabela no fim do documento de correções. Na semana seguinte, usou a mesma régua para comparar um modelo novo, sem começar do zero.
Tabela da régua · resumo da feira
1 Fidelidade · esperado 3 responsáveis, 0 prazo inventado · observado 3 e 0 · passou ✓
2 Formato · esperado 1 seção de pendências · observado 1 · passou ✓
3 Verificável · esperado toda frase na ata · observado sim · passou ✓
Resposta ruim guardada: a versão A, sem Renata
1Critério e esperado vêm antes do pedido.
2Observado vem de contar na resposta.
3Passou é sim ou não, sem "mais ou menos".
Se travou aqui, é normalEscrever critério parece burocracia na primeira vez. Comece com um só: "nenhum dado que não está no material". Os outros dois aparecem sozinhos depois da primeira resposta errada.
Pratique agora 0/3
Passe a régua em duas respostas
Pronto quando você preencher a tabela para as duas respostas e escolher uma com base nela. Cerca de 10 minutos. Anote no papel ou no bloco de notas.
É um caso fictício, feito para treinar: não há dado de ninguém. Discordou do gabarito? Releia a ata e confira linha por linha.
O material (fictício): Excursão do 7º A ao museu de ciências. Saída da escola às 7h30, retorno às 12h. A autorização assinada pelos responsáveis deve ser entregue até quinta-feira. Cada aluno leva o próprio lanche.
O pedido feito à IA: "Escreva um aviso curto para as famílias com as informações da excursão."
Abrir as duas respostas (depois de escrever a sua régua)
Resposta 1: "Olá, famílias! Nossa turma vai viver um dia incrível no museu de ciências. Saída às 7h30 e retorno às 13h. Não esqueçam o lanche!"
Resposta 2: "Excursão do 7º A ao museu de ciências. Saída às 7h30, retorno às 12h. Entreguem a autorização assinada até quinta-feira. Cada aluno leva o próprio lanche."
Ver o gabarito
Uma régua possível, um item por critério. Fidelidade: horários, autorização e prazo de quinta-feira iguais ao material. Formato: aviso curto, até quatro linhas. Verificável: toda informação está no material. A Resposta 1 reprova em fidelidade (o retorno mudou para 13h e a autorização sumiu) e em verificável (acrescentou um "dia incrível" que não está no material); passa no formato. A Resposta 2 passa nos três. Se a sua régua tinha outros itens, confira cada um do mesmo jeito: esperado, observado, passou?
Você acabou de decidir entre duas respostas por uma régua escrita, e não pelo tom.
Cola da aula
Régua de qualidade
Antes do pedidoescreva o que precisa aparecer e o que não pode.
Três critériosfidelidade, formato, conclusões verificáveis.
Tabelacritério, esperado, observado, passou? E guarde uma resposta ruim.
Seu próximo passo
Você já sabe escolher uma resposta por critério, e não pela aparência.
Hoje, antes do próximo resumo que pedir à IA, escreva a régua em três linhas e confira a resposta com ela.
Na próxima aula: testar dois modelos custa. Você vai descobrir de qual conta sai esse custo, porque assinatura e chave de acesso cobram de jeitos diferentes.
Material complementar · Crie uma régua de qualidadeTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Uma régua transforma opinião em observação. Defina antes do pedido quais fatos precisam aparecer, quais erros são inaceitáveis e como a saída será usada. Use três critérios pequenos: fidelidade aos dados, formato combinado e possibilidade de verificar as conclusões.
Por que aprender
Sem critério, você escolhe a resposta mais bonita. Um relatório pode soar convincente e alterar valores. O teste deve refletir o trabalho que você precisa entregar, não uma demonstração feita para impressionar.
Em uma ata fictícia com três responsáveis, o teste exige os três nomes, nenhum prazo inventado e uma seção de pendências. Uma frase elegante não compensa perder um responsável.
✓ Faça
Use a tabela: critério | esperado | observado | passou? Guarde uma resposta ruim também para lembrar o que está tentando evitar.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Aula 4 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 1 · Aula 5 de 6
Assinatura e chave de acesso são contas diferentes
Você consegue identificar o método de acesso de cada ferramenta de IA e registrá-lo na ficha do projeto, sem expor nenhuma credencial.
Um teste pode estar consumindo uma conta diferente da que você imagina. Assinar um chat não dá saldo livre para qualquer programa. Se hoje você só usa o chat pela sua conta, a sua ficha terá uma linha. As outras entram quando o curso chegar a esses programas, no módulo 3.
Em 1 minuto
Entrar com a conta usa os direitos e limites do seu plano.
Uma chave de acesso cobra por consumo, em outra conta.
Registre o método na ficha. Nunca a credencial.
1Entrar com a conta usa o seu plano
Fazer login com a conta do ChatGPT usa os direitos e os limites dessa conta. Eles vêm do plano e do espaço de trabalho dela. O que você pode usar, e quanto, vem do plano.
Esses limites e regras mudam. A fonte de verdade é a configuração atual da sua conta, e não o que alguém contou.
Lúcia usa o chat pela conta da escola. Quando atingiu o limite de uso do dia, descobriu que o limite era do plano da escola, e não dela.
Configurações da conta
1 Plano: [nome do plano da escola]
2 Espaço de trabalho: [nome da escola]
3 Uso: limites do plano
1O plano diz o que a conta pode usar.
2O espaço de trabalho diz de quem é a conta.
3O limite vem daí, não do modelo.
2A chave de acesso cobra por consumo
Programas usam a IA por uma API. Para isso, usam uma chave de API, cobrada por consumo na plataforma.
Assinar o chat não significa receber saldo livre para qualquer programa que chame a API. São duas contas, com duas cobranças.
Denise rodou um programa de relatórios com uma chave de API da escola. Os tokens gastos apareceram na plataforma, e não na assinatura do chat.
Entrar com a conta
Quem usa: você, na tela do chat ou num agente conectado à conta.
Cobrança: o plano da conta, com os limites dele.
Chave de API
Quem usa: um programa.
Cobrança: por consumo, na plataforma da API.
Os dois caminhos podem usar um modelo com nome parecido e ainda assim cobrar de contas diferentes.
3Centrais têm crédito próprio
Centrais como o OpenRouter e o Kie têm crédito próprio, cobrado por consumo. Ele é separado de qualquer assinatura.
Então existem pelo menos três lugares de onde o dinheiro pode sair: o plano do chat, a plataforma da API e o crédito da central.
Lúcia gerou os cartazes da semana da leitura numa central, com um crédito pequeno que ela mesma comprou para testar. O crédito acabou no meio do lote. A assinatura do chat continuava ativa, mas não cobria aquilo.
De onde sai cada custo
1 Plano do chat
uso pela tela ou por agente conectado à conta
2 Plataforma da API
programas com chave de API, por consumo
3 Crédito da central
modelos acessados pela central, por consumo
Teste-se
Lúcia assina um plano do chat. Ela gera cartazes numa central, e o crédito da central acabou. O que resolve?
4Confira o método antes de uma execução longa
Antes de deixar algo rodando por muito tempo, confira qual método está ativo: nas configurações da ferramenta, veja o plano da conta ou a chave em uso. Mais adiante, no Codex, um comando no terminal mostra isso.
Na ficha do projeto, anote o método: conta, chave ou central. A credencial em si nunca vai para a ficha, para um pedido ou para um print.
Antes de pedir o resumo das quarenta atas do ano, Denise conferiu nas configurações e escreveu na ficha: "chat da escola · conta da escola · limite do plano". Sem nenhuma senha.
Ficha de Denise · acesso
1 Ferramenta: chat da escola
2 Método: conta da escola
3 Onde conferi: Configurações › Plano
4 Limite de gasto: o limite do plano · Credencial: não anotada
Como vai ser no Codex, a partir do módulo 3
Terminal
$ codex login status
Logged in using ChatGPT
A primeira linha é o que você digita. A segunda, em inglês, diz "conectado usando o ChatGPT": o método é a conta.
Com uma chave de API ativa, a resposta cita a chave, mas nunca o valor completo.
Se travou aqui, é normalO Codex só chega no módulo 3. Por enquanto, confira o método na tela de configurações da ferramenta que você usa e anote o que ela mostra.
Pratique agora 0/3
Registre o método de acesso na ficha do projeto
Pronto quando a ficha tiver uma linha por ferramenta de IA que você usa, com o método e onde conferiu. Cerca de 8 minutos, no computador ou no celular.
Só usa o chat pela sua conta? Então a ficha tem uma linha, e está certo assim. Você só anota o tipo de acesso, nunca senha ou chave. Se encontrar uma chave colada em algum documento, apague de lá e avise quem administra essa conta.
FICHA DO PROJETO · ACESSO
Ferramenta: <ex.: chat da escola>
Método: <conta · chave de API · central>
Onde conferi: <ex.: Configurações › Plano>
Limite de gasto: <ex.: o limite do plano>
Credencial: NÃO ANOTAR AQUI
Você acabou de mapear de onde sai o custo de cada ferramenta, sem expor nenhuma credencial.
Cola da aula
Acesso e cobrança
Contadireitos e limites do plano.
Chave de API e centraisconsumo, cada uma na sua conta.
Fichao método sim; a credencial nunca.
Seu próximo passo
Você já sabe dizer de qual conta sai o custo de cada ferramenta que usa.
Hoje, anote o limite de gasto na ficha. Se usa só o chat, é o limite do plano, em Configurações › Plano. Se usa uma central ou uma chave de API, veja se ela permite um teto mensal.
Na próxima aula: com a conta certa, até onde deixar a IA ir sozinha? Você vai escrever uma autorização com começo, meio e ponto de parada.
Material complementar · Entenda acesso e cobrançaTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Login com ChatGPT usa os direitos e limites associados à conta e ao espaço de trabalho. Uma chave de API usa cobrança por consumo na plataforma. Assinar ChatGPT não significa receber saldo livre para qualquer programa que chame a API. Centrais como OpenRouter e Kie têm crédito próprio, cobrado por consumo e separado de qualquer assinatura. Confira o método ativo antes de uma execução longa.
Por que aprender
Esse cuidado evita descobrir depois que um experimento está consumindo uma conta diferente. Limites de uso, acesso a modelos e regras de dados podem mudar; a fonte de verdade é a configuração atual da sua conta.
Conceitos-chave
Assinatura; autenticação; API; consumo; limite de gasto.
Na prática
Um aluno usa Codex conectado ao ChatGPT e depois executa um programa com OPENAI_API_KEY. São caminhos distintos, mesmo que usem um modelo com nome semelhante.
Experimente agora
No Codex, use codex login status para conferir o método. Na ficha do projeto, registre o método, nunca a credencial.
Aula 5 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 1 · Aula 6 de 6
Autonomia é autorização com escopo
Você consegue escrever uma autorização em cinco partes — objetivo, arquivos, ações, tempo e parada — e pedir um fechamento que diga o que foi feito e como foi verificado.
Um agente executa várias etapas e pode errar em várias delas. Sem limite escrito, ele pode gastar tempo, crédito ou mexer no arquivo errado. Um limite simples protege tudo isso sem impedir o trabalho útil.
Em 1 minuto
Autonomia é uma autorização com escopo, não um convite para fazer qualquer coisa.
Cinco partes: objetivo, arquivos, ações, limite de tempo e ponto de parada.
A saída diz o que foi feito e como foi verificado.
1Um agente faz várias etapas seguidas
Num chat, você manda uma mensagem e recebe uma resposta. Um agente recebe um objetivo e segue sozinho: lê arquivos, cria, compara, corrige.
Isso poupa trabalho. Também multiplica os pontos em que ele pode errar sem você ver.
Lúcia pediu a um agente que organizasse as notas do bimestre. Ele leu três planilhas, criou uma nova e renomeou as antigas. A última etapa ela não tinha pedido.
Chat
Uma mensagem, uma resposta.
Você vê cada passo antes do próximo.
Agente
Um objetivo, várias etapas: ler, criar, comparar, corrigir.
Você vê o resultado no fim.
Os dois são úteis. O agente precisa de limite escrito porque você não acompanha cada etapa.
2Cinco partes de uma autorização
Combine cinco coisas antes de começar: o objetivo, os arquivos permitidos, as ações autorizadas, o limite de tempo e a condição de parada.
Num chat, o tempo vira "responda numa mensagem só"; num agente, é um teto de execução. Permissão técnica e instrução escrita se completam: a ferramenta limita o que é possível, e a autorização diz o que é desejado.
Denise escreveu a autorização do agente que prepara o relatório mensal de frequência. Levou dois minutos e cabe num post-it.
Autorização · relatório de frequência
1 Objetivo: rascunho do relatório de frequência de setembro
2 Arquivos: só a planilha de frequência de setembro
3 Ações: ler a planilha e criar um rascunho; não apagar nem renomear
4 Tempo: até 10 minutos
5 Parada: entregar o rascunho e parar antes de enviar
1O que é para produzir.
2O que ele pode ler.
3O que ele pode fazer.
4Até quando.
5Onde ele para e espera você.
3O botão existir não é permissão
Enviar uma mensagem, publicar ou apagar são ações externas. Cada uma exige instrução explícita. O fato de o botão de envio existir não autoriza usá-lo.
Lúcia autorizou o agente a criar o rascunho do comunicado da gincana e comparar com o do ano passado. Enviar às famílias ficou de fora, de propósito.
Agente
VocêCrie o rascunho do comunicado da gincana usando só o arquivo de regras da gincana. Compare com o comunicado do ano passado. Pare antes de enviar a qualquer pessoa.
IARascunho do comunicado criado.
Comparação: três trechos repetidos do ano passado, marcados no rascunho.
Não enviei: o envio não estava autorizado.
Parou onde a autorização mandou parar e disse isso.
Teste-se
A autorização dizia só "organize a pasta das provas". O agente podia apagar arquivos e apagou três que pareciam cópias. Qual parte da autorização faltou?
4A saída conta o que fez e como conferiu
Peça sempre um fechamento em três partes: o que foi feito, como foi verificado e o que ficou pendente. Assim o resultado vira algo que você revisa, e não algo em que você precisa acreditar.
O agente de Denise terminou o rascunho do relatório de frequência e listou o que conferiu. Ela abriu a planilha, conferiu um dos números e aprovou o resto.
Agente · fechamento
IAFeito: rascunho do relatório com a frequência por turma.
Verificado: o total por turma bate com a soma das linhas da planilha.
Pendente: a turma 8º C tem duas linhas sem data. Não completei.
Três partes, e a pendência não foi preenchida com um palpite.
Se travou aqui, é normalVocê talvez ainda não use nenhum agente. A prática desta aula é no chat, que não tem como enviar nada: ela treina escrever a autorização, não prova que a IA obedece. O teste com um agente de verdade vem no módulo 3, com a autorização que você escrever hoje.
Pratique agora 0/3
Escreva e teste uma autorização com ponto de parada
Pronto quando o fechamento vier com o que foi feito, como os três pontos foram verificados e o que ficou pendente. Cerca de 10 minutos, no chat que você já usa.
Use dados fictícios ou um texto seu sem informação pessoal. Nada é enviado a ninguém: o ponto de parada garante isso. Se a IA passar do limite, anote o que ela fez e reforce essa linha.
1. OBJETIVO
<ex.: rascunho de um aviso sobre a gincana>
2. ARQUIVOS: USE SOMENTE ESTE MATERIAL
<cole aqui o texto ou os dados fictícios>
3. AÇÕES AUTORIZADAS
<ex.: escrever o rascunho em até oito linhas; não inventar datas nem nomes>
4. TEMPO
Responda numa mensagem só.
5. PARADA
Pare antes de publicar ou enviar.
FECHAMENTO (os três pontos são a sua régua da aula 4)
Diga o que fez, como verificou estes três pontos e o que ficou pendente:
- <ex.: a data é a mesma do material>
- <ex.: nenhum nome que não está no material>
- <ex.: até oito linhas>
Veja o molde já preenchido por uma coordenadora
1. Objetivo: rascunho do aviso de mudança de horário da biblioteca. 2. Arquivos: [horários antigo e novo colados] 3. Ações: escrever o aviso em até seis linhas; não inventar motivo. 4. Tempo: responda numa mensagem só. 5. Parada: pare antes de enviar. Fechamento: diga o que fez, como verificou os dois horários, a ausência de nomes e o limite de seis linhas, e o que ficou pendente.
Você acabou de delegar uma tarefa com escopo, verificação e ponto de parada.
Cola da aula
Autorização com escopo
Cinco partesobjetivo, arquivos, ações, tempo, parada.
Ação externaenviar, publicar ou apagar só com instrução explícita.
Fechamentoo que fez, como verificou, o que ficou pendente.
Seu próximo passo
Você fechou o módulo 1: já escolhe o modelo pela tarefa, confere com uma régua, sabe de onde sai o custo e delega com limite.
Quando tiver uns 30 minutos, abra o material complementar desta aula e faça o laboratório opcional do módulo, "Sua ficha de decisão": o mesmo pedido em dois modelos, avaliado pela sua régua.
No próximo módulo: Chat, Work e Desktop. Três jeitos de trabalhar com a IA, e quando usar cada um.
Material complementar · Delimite a autonomiaTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
Autonomia é uma autorização com escopo, não um convite para fazer qualquer coisa. Combine objetivo, arquivos permitidos, ações autorizadas, limite de tempo e condição de parada. A saída deve incluir o que foi feito e como foi verificado.
Por que aprender
Um agente pode executar mais etapas que um chat, inclusive errar em várias delas. Um limite simples protege tempo, orçamento e arquivos sem impedir o trabalho útil. Permissão técnica e instrução escrita se complementam.
Conceitos-chave
Escopo; aprovação de ações externas; teto de execução; resultado revisável.
Na prática
Autorize criar um rascunho e comparar dados fictícios. Enviar a proposta a um cliente é outra ação e exige instrução explícita. O botão de envio existir não significa autorização para usá-lo.
Experimente agora
Escreva: use estes arquivos; gere este resultado; verifique estes três pontos; pare antes de publicar ou enviar.
Laboratório do módulo: Sua ficha de decisão
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Escolha uma tarefa pequena que você já sabe avaliar: resumir uma reunião fictícia.
Escreva três fatos que obrigatoriamente precisam aparecer no resumo.
Execute o mesmo pedido em dois modelos disponíveis, sem mudar os dados.
Compare fatos preservados, invenções, tempo e esforço de revisão. Registre sua escolha.
Ficha de comparação
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
Tarefa: resumir reunião fictícia
Entrada: pauta com 5 itens
Critérios: preservar 5 itens; não inventar prazos
Modelo / esforço: anote o que está disponível
Resultado observado: registre os acertos e erros
Escolha: justifique pelo resultado, não pelo nome
Critério de pronto
Comparar modelos com uma tarefa real e um critério de qualidade. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
Uma resposta chegou mais rápido, mas inventou dois prazos. Qual resultado deve orientar a escolha?
Ver resposta comentada
A qualidade verificável e o retrabalho; velocidade isolada não basta.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Você consegue fazer uma pergunta curta com público e finalidade e receber a resposta com as suposições da IA à vista.
Nem toda tarefa pede uma ferramenta grande. Montar uma rotina complicada para algo que só precisava de uma resposta gasta tempo e ainda dá mais o que conferir. Saber quando o chat basta é o primeiro filtro deste módulo.
Em 1 minuto
Chat é conversa: você pergunta, lê a resposta e ajusta o pedido.
Serve para esclarecer um conceito ou rascunhar uma mensagem.
Diga para quem e para quê, e peça as suposições da IA.
1Chat é uma conversa: pergunta, resposta, ajuste
O chat é uma interface de conversa. Pense na pergunta que você faz a uma colega no corredor, entre duas aulas. É curta, a resposta vem na hora e você decide o que fazer com ela.
Se a resposta não serviu, você não recomeça. Manda um ajuste na mesma conversa.
Lúcia vai cobrir a aula de matemática de uma colega. Pediu três jeitos de explicar frações com os ingredientes de uma receita. Escolheu um, ajustou outro e levou para a turma.
Chat de IA
VocêMe dê três jeitos de explicar frações usando os ingredientes de uma receita de bolo.
IA1. Meia xícara de açúcar: a xícara dividida em duas partes iguais.
2. Um quarto de tablete de manteiga: quatro pedaços, usa-se um.
3. Um terço de xícara de leite: a xícara em três partes, usa-se uma.
VocêTroque o terceiro: quero um exemplo com três ovos divididos entre duas receitas.
IA3. Três ovos para duas receitas: cada uma leva um ovo e meio.
A terceira mensagem é o ajuste: mesma conversa, sem começar de novo.
Pergunta, resposta, ajuste. É para isso que o chat existe.
2Para quem e para quê mudam a resposta
Uma pergunta solta recebe uma resposta de enciclopédia. Diga quem vai ler e o que você vai fazer com o texto. A resposta já sai no tamanho e no tom certos.
Denise precisava explicar o conselho de classe aos pais do 6º ano. A primeira pergunta trouxe um parágrafo técnico. Com público e finalidade, vieram duas frases prontas para o recado.
Chat de IA
VocêO que é conselho de classe?
IAO conselho de classe é uma instância colegiada de avaliação prevista na organização escolar, que reúne docentes e equipe pedagógica para analisar o processo de ensino e aprendizagem…
Correto, mas longo e técnico demais para um recado aos pais.
VocêExplique o que é conselho de classe em duas frases, para pais do 6º ano. Vai num recado da agenda.
IAO conselho de classe é uma reunião dos professores com a coordenação para conversar sobre como cada turma e cada aluno estão indo. Dele saem combinados para ajudar quem precisa.
Mesmo assunto, agora no tamanho e no tom do recado.
Toque nos dois botões e compare a mesma pergunta com e sem público.
3Peça as suposições da IA
Toda pergunta curta deixa lacunas. A IA preenche essas lacunas sem avisar: supõe a idade da turma, o tom, o tamanho. Peça que ela liste o que supôs.
Assim você enxerga o palpite antes de usar a resposta. Corrigir uma suposição custa uma mensagem.
Lúcia pediu uma pergunta de abertura para a aula sobre misturas. A lista de suposições mostrou que a IA pensou em alunos do ensino médio. Ela corrigiu com uma linha.
Chat de IA
VocêCrie uma pergunta de abertura para uma aula sobre misturas. No fim, liste as suposições que você fez.
IAPergunta: por que o sal some na água, mas a areia não?
Suposições: alunos do ensino médio; aula de 50 minutos; a pergunta será feita em voz alta.
VocêA turma é de 8º ano. Ajuste a pergunta se precisar.
IAPara o 8º ano: o que acontece com o sal quando ele entra na água, e por que a areia fica no fundo?
A suposição errada apareceu na lista, e não escondida no texto.
Leia primeiro as suposições. Elas mostram o que a IA inventou para preencher o que você não disse.
4Quando o chat basta, e quando pede mais
A escolha é pela intenção da tarefa, não por uma proibição técnica. Alguns chats também leem arquivos anexados. Se a entrega é uma resposta que você lê e confere na hora, o chat basta.
Se a entrega é um documento com várias entradas, a conversa fica curta demais. Alguns chats têm um modo para tarefas maiores; no ChatGPT, ele se chama Work. É o tema da próxima aula, que também mostra como fazer sem ele.
Denise quase abriu uma tarefa longa para escrever um recado de três linhas. Voltou ao chat e resolveu em dois minutos.
O chat basta
Explicar um conceito em poucas linhas.
Rascunhar um recado ou um e-mail curto.
Levantar ideias para uma aula.
Pede mais que conversa
Juntar várias fontes numa tabela.
Entregar um documento pronto para revisar.
Tarefa que leva mais tempo que uma conversa.
Pergunte: a entrega é uma resposta que confiro agora, ou um documento que vou revisar depois?
Teste-se
Você só precisa de uma explicação de duas frases para um recado. Precisa usar o Work?
Se travou aqui, é normalNão sabe se o seu chat tem Work ou lê arquivos? Não precisa saber agora. Esta aula e a prática funcionam em qualquer chat, até no plano gratuito, no celular.
Pratique agora 0/3
Faça uma pergunta com público, finalidade e suposições
Pronto quando a resposta vier com uma lista de suposições e você tiver corrigido uma delas. Cerca de 8 minutos, no chat que você já usa, no celular ou no computador.
É uma pergunta do seu trabalho, sem nome de aluno nem dado pessoal. Se a IA não listar as suposições, mande só: "Liste as suposições que você fez".
Pergunta: <sua dúvida em uma linha>
Público: <quem vai ler ou ouvir a resposta>
Finalidade: <o que você vai fazer com ela>
Tamanho: <ex.: até cinco linhas>
No fim, liste as suposições que você fez sobre o que eu não disse.
Veja o molde já preenchido por uma professora
Pergunta: como explicar a diferença entre evaporação e ebulição? Público: alunos do 8º ano. Finalidade: abrir a aula de amanhã. Tamanho: até quatro linhas. No fim, liste as suposições que você fez sobre o que eu não disse.
Você acabou de fazer uma pergunta que rende na primeira volta e de corrigir o palpite da IA antes de usar a resposta.
Cola da aula
Chat é conversa
Conversapergunta, resposta, ajuste na mesma janela.
Para quem e para quêdefinem o tamanho e o tom.
Suposiçõespeça a lista e corrija antes de usar.
Seu próximo passo
Você já sabe quando o chat basta e como fazer uma pergunta que rende na primeira resposta.
Na próxima dúvida pequena do trabalho, acrescente ao pedido a linha das suposições. Leva dez segundos.
Na próxima aula: e quando a tarefa não cabe numa conversa? Você vai aprender a fazer uma encomenda.
Material complementar · Chat resolve uma conversaTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Chat é uma interface de conversa. Você apresenta uma pergunta, recebe uma resposta e pode ajustar o pedido. Funciona bem para esclarecer um conceito ou rascunhar uma mensagem. Recursos adicionais variam: um chat também pode trabalhar com arquivos e ferramentas quando disponíveis. A distinção didática é a intenção da tarefa, não uma proibição técnica.
Por que aprender
Reconhecer uma necessidade pequena evita montar uma automação para algo que precisa apenas de uma resposta. O melhor ambiente é o que permite conferir a entrega com menos atrito.
Uma professora pede três maneiras de explicar frações usando ingredientes de uma receita. Ela analisa os exemplos e escolhe um antes de levar à aula.
✓ Faça
Escreva uma pergunta curta com público e finalidade. Depois peça que a resposta indique suas suposições.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Chat — uma conversa
Work — uma encomenda
Desktop — arquivos por perto
Mesma família de modelos, três formas de pedir trabalho. A escolha muda o que você precisa entregar junto.
Aula 7 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 2 · Aula 2 de 6
Tarefa grande vira encomenda
Você consegue transformar um pedido vago, como "pesquise fornecedores", numa encomenda curta, de cinco partes: objetivo, entradas, saída, limites e parada.
Um trabalho com várias fontes precisa de uma definição de pronto. Sem ela, a IA pode continuar pesquisando quando você só precisava comparar três opções. E volta um texto longo que você não sabe por onde revisar.
Em 1 minuto
O Work recebe uma tarefa maior e devolve um resultado que você revisa.
Você define o que deve existir no fim, e não cada frase do caminho.
Cinco partes: objetivo, entradas, saída, limites e parada. Sem Work na conta, a encomenda funciona no chat comum.
1O Work recebe a tarefa e devolve o resultado
No Work, você não conversa frase a frase. Entrega uma tarefa, como uma análise ou um documento, e recebe o resultado para revisar. Ele pode usar arquivos e ferramentas aprovadas.
Pense na encomenda de um bolo na confeitaria. Você diz sabor, tamanho e dia. Não fica olhando o forno. O Work não aparece em todo plano. Não o encontra no seu? Use a encomenda no chat comum: funciona igual.
Denise precisa contratar o ônibus da excursão ao museu. Tem três orçamentos e quer uma comparação para levar à direção.
Conversa
Você pergunta, lê, ajusta.
Acompanha cada resposta.
Encomenda
Você descreve o que deve existir no fim.
Revisa o resultado quando ele chega.
Na encomenda, o trabalho de pensar vem antes: o que você quer receber.
2Cinco partes de uma encomenda
Uma encomenda diz cinco coisas. O objetivo. As entradas, que são o material que a IA pode usar. A saída, que é o formato do resultado. Os limites. E a parada, que é quando o trabalho termina.
Parece a autorização da aula 6, no módulo 1, e é parente dela. A autorização diz o que a IA pode fazer; a encomenda diz o que deve existir no fim.
Denise escreveu a encomenda dos orçamentos do ônibus em cinco linhas. Levou três minutos.
Encomenda · ônibus da excursão
1 Objetivo: comparar três orçamentos de ônibus para a excursão
2 Entradas: só os três orçamentos colados abaixo
3 Saída: tabela com preço, prazo para confirmar e riscos
4 Limites: sem pesquisar outras empresas; dado ausente vira "não informado"
5 Parada: entregar a tabela e parar
1Para que serve o resultado.
2O que a IA pode usar.
3O formato do que volta.
4O que ela não deve fazer.
5Quando o trabalho acaba.
3"Pesquise" vira uma tabela que você confere
Um pedido vago abre a porta para a pesquisa sem fim. A encomenda fecha essa porta: três opções, os documentos que você deu, um formato.
Repare no campo sem informação. A encomenda pediu "não informado", e a IA não completou com um palpite.
Tarefa de IA
VocêPesquise empresas de ônibus para uma excursão escolar.
IAEncontrei muitas opções. Primeiro, um panorama do setor de fretamento escolar, com dicas de contratação e documentos exigidos…
Longo, fora dos três orçamentos, e sem dizer quando termina.
VocêCompare só estes três orçamentos numa tabela com preço, prazo para confirmar e riscos. Dado ausente vira "não informado". Entregue a tabela e pare.
Empresa A: R$ 1.800, confirma em 2 dias.
Empresa B: R$ 1.500, prazo não citado.
Empresa C: R$ 2.100, confirma em 1 dia; ônibus sem cinto nos bancos do fundo.
IAA · R$ 1.800 · 2 dias · não informado
B · R$ 1.500 · não informado · não informado
C · R$ 2.100 · 1 dia · bancos do fundo sem cinto
Três linhas, só com o que estava nos orçamentos. "Não informado" quer dizer que o orçamento não fala disso, e não que o risco é zero.
Toque nos dois botões. Mesmo assunto, entregas muito diferentes.
4A parada diz quando o trabalho acabou
Sem parada, a IA decide sozinha quando chega. Às vezes para cedo. Muitas vezes vai longe demais. Diga o tamanho do resultado e o ponto em que ela entrega.
Lúcia encomendou uma comparação de kits de microscópio para o laboratório. Limitou a três kits, aos catálogos que colou e a uma tabela. Recebeu em uma página o que antes vinha em cinco.
Sem parada
Pedido: "Compare kits de microscópio."
Resultado: cinco páginas, com kits de lojas que ela nem conhecia.
Com parada
Pedido: "Só os três kits dos catálogos colados. Uma tabela. Entregue e pare."
Resultado: uma página, três linhas, pronta para conferir.
Saldo: de cinco páginas para uma, com tudo vindo do material que ela deu.
Se travou aqui, é normalSua conta não tem Work? A encomenda funciona igual no chat comum. Cole o molde da prática, com o material, e peça a entrega numa resposta só. O que muda é o pedido, não a ferramenta.
Pratique agora 0/3
Transforme um "pesquise" numa encomenda curta, de cinco partes
Pronto quando o resultado vier só com as opções que você deu, no formato pedido, e com "não informado" onde faltou dado. Cerca de 10 minutos, no Work se a sua conta tiver, ou no chat que você já usa.
Use opções fictícias ou dados públicos, sem nome de aluno nem valor sigiloso. As opções estão em PDF ou no WhatsApp? Digite só o essencial de cada uma, numa linha. Se a IA trouxer opção que você não deu, responda: "Use só as opções que colei".
OBJETIVO
<ex.: comparar três opções de ... para decidir ...>
ENTRADAS: USE SOMENTE ESTE MATERIAL
<cole aqui as três opções>
SAÍDA
<ex.: tabela com preço, prazo e riscos>
LIMITES
Não pesquise outras opções. Dado ausente vira "não informado".
PARADA
Entregue a tabela e pare.
Veja o molde já preenchido por uma professora
Objetivo: escolher um kit de microscópio para o laboratório. Entradas: Kit 1: R$ 900, 10 unidades. Kit 2: R$ 750, entrega em 15 dias. Kit 3: R$ 1.100, 12 unidades, garantia de 1 ano. Saída: tabela com preço, quantidade, prazo e garantia. Limites: não pesquise outros kits; dado ausente vira "não informado". Parada: entregue a tabela e pare.
Você acabou de trocar uma pesquisa sem fim por uma entrega com começo, meio e fim.
Cola da aula
Encomenda de trabalho
Worktarefa maior, resultado para revisar.
Cinco partesobjetivo, entradas, saída, limites, parada.
Não informadodado ausente não vira palpite.
Seu próximo passo
Você já sabe transformar um pedido vago numa encomenda que tem hora para acabar.
Guarde o molde preenchido num bloco de notas. Na próxima comparação do trabalho, comece por ele.
Na próxima aula: a encomenda cita arquivos. Como saber se a IA consegue mesmo ler cada um?
Material complementar · Work recebe uma encomendaTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Work permite delegar uma tarefa com resultado revisável, por exemplo uma análise ou um documento. Pode usar arquivos e ferramentas aprovadas. Em vez de acompanhar cada frase, você define o que deve existir no final e acompanha as etapas relevantes. A disponibilidade depende da conta e do ambiente.
Por que aprender
Trabalhos com várias entradas precisam de uma definição de pronto. Sem isso, o agente pode continuar pesquisando quando você só precisava de uma comparação de três opções.
Conceitos-chave
Objetivo; fontes; entrega; limites; condição de parada.
Na prática
Uma gestora fornece dados fictícios de três fornecedores e solicita uma tabela com preço, prazo e riscos. Determina que campos ausentes sejam marcados como não informados.
Experimente agora
Transforme “pesquise fornecedores” em uma encomenda de uma página, limitada a três alternativas e aos documentos fornecidos.
Aula 8 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 2 · Aula 3 de 6
Arquivo por perto não é arquivo lido
Você consegue montar uma pasta de treino com dois textos. E fazer a IA dizer quais arquivos recebeu, com a primeira e a última linha, antes do resumo.
Muitas falhas de tarefa são falhas de acesso. Você imagina que a IA vê uma pasta, mas ela nunca foi compartilhada. Aí a resposta fala de documentos que o modelo não leu.
Em 1 minuto
O Desktop é o aplicativo no computador e pode chegar às pastas que você permitir.
Ter o aplicativo não dá acesso a todos os seus documentos.
Antes do trabalho, peça a lista dos arquivos recebidos, com a primeira e a última linha de cada.
1O Desktop fica no computador, perto das pastas
O Desktop é o aplicativo que fica no seu computador. Se o seu aplicativo oferecer isso, ele pode abrir pastas e outros aplicativos, sempre com a sua permissão.
No chat do navegador, você anexa ou cola cada arquivo. Nos dois casos, a IA só lê o que chegou até ela.
Lúcia usa o chat no navegador da escola e o Desktop no notebook de casa. Nos dois, ela confere o que a IA recebeu antes de pedir o trabalho.
Chat no navegador
Você anexa ou cola cada arquivo.
A IA lê o que você entregou.
Desktop
Pode abrir uma pasta que você escolheu na hora de dar permissão.
A IA lê o que essa permissão alcança.
Caminhos diferentes, a mesma regra: a IA só lê o que chegou até ela.
2Autorize uma pasta, não o computador inteiro
Dar acesso é como entregar a chave de uma gaveta, e não a da escola inteira. Separe numa subpasta só o que a tarefa precisa. Quando o aplicativo pedir acesso, escolha só essa subpasta. O nome das telas muda entre versões; o que não muda é escolher a menor pasta possível.
A pasta da feira de ciências tem três versões do orçamento. Denise quer testar a IA sem arriscar o original. Autorizou só a subpasta de exemplos, com duas cópias.
Meus arquivos › Feira de ciências
orcamento-v1
orcamento-v2
orcamento-v3
1 exemplos
2 orcamento-v1-copia
2 orcamento-v2-copia
1Só esta subpasta foi autorizada.
2Dentro dela, cópias. Os originais ficam fora do alcance.
3Peça a lista do que foi lido antes do trabalho
Antes da comparação, peça os nomes dos arquivos que a IA consegue ler. Junto, a primeira e a última linha de cada um. Nome sozinho não prova leitura. A primeira e a última linha mostram que o começo e o fim chegaram, e você confere no arquivo.
Se a lista vier errada, o problema é de acesso, e não do pedido. Corrija o acesso e repita a lista.
Desktop · subpasta exemplos
VocêListe os arquivos que você consegue ler e copie a primeira e a última linha de cada um. Não compare nem resuma ainda.
IAConsigo ler 2 arquivos:
orcamento-v1-copia
primeira: "Feira de ciências, orçamento de materiais, versão 1"
última: "Total: R$ 640,00"
orcamento-v2-copia
primeira: "Feira de ciências, orçamento de materiais, versão 2"
última: "Total: R$ 710,00"
Dois nomes, com a primeira e a última linha iguais às dos arquivos. Agora a comparação pode começar.
A lista confirma a leitura. Nome faltando ou sobrando é sinal para parar e corrigir o acesso.
4Sem acesso? Entregue por outro caminho
Se o Desktop não existe na sua conta, ou não alcança a pasta, entregue os arquivos por um caminho que funciona. Anexe no chat, pelo botão de anexar ao lado da caixa de mensagem. Ou cole o texto com um cabeçalho com o nome do arquivo.
Lúcia colou dois textos no chat do navegador, cada um com o nome em cima. Pediu a lista antes do resumo.
Chat de IA
Você=== arquivo: roteiro-experimento ===
Misturar água e óleo num copo transparente.
Observar por dois minutos.
=== arquivo: lista-materiais ===
Copo transparente, água, óleo de cozinha, colher.
Tempo total: dez minutos.
Liste os arquivos que você recebeu, com a primeira e a última linha de cada. Não resuma ainda.
IARecebi 2 arquivos:
roteiro-experimento: "Misturar água e óleo num copo transparente." … "Observar por dois minutos."
lista-materiais: "Copo transparente, água, óleo de cozinha, colher." … "Tempo total: dez minutos."
O cabeçalho dá nome a cada texto; a primeira e a última linha mostram que o começo e o fim chegaram.
Se travou aqui, é normalNão tem o Desktop nem sabe se o seu chat anexa arquivos? Use o caminho do cabeçalho: cole cada texto com "=== arquivo: nome ===" em cima. Funciona em qualquer chat, até no celular.
Pratique agora 0/4
Monte uma pasta de treino e confirme a leitura
Pronto quando a IA listar os dois nomes e a primeira e a última linha certas de cada um, antes de você pedir o resumo. Cerca de 10 minutos. No computador, siga os passos. No celular, escreva as duas notas no aplicativo de notas e cole no chat, cada uma com o cabeçalho do step 4.
A pasta de treino tem só texto inventado, então nada real sai do seu computador. É dela que você anexa, e é ela que você escolheria no Desktop. Se a lista vier com nome errado ou faltando, não peça o resumo: reenvie o arquivo e peça a lista de novo.
Você acabou de separar um problema de acesso de um problema de pedido, antes que ele virasse resposta errada.
Cola da aula
Acesso antes do trabalho
Desktopchega às pastas que você autoriza, não a todas.
Uma subpastasó com o que a tarefa precisa, de preferência cópias.
Lista primeironome, primeira e última linha de cada arquivo, antes do resumo.
Seu próximo passo
Você já sabe confirmar o que a IA leu antes de confiar no que ela escreveu.
Na próxima tarefa com arquivo, mande primeiro: "Liste os arquivos que você recebeu, com a primeira e a última linha de cada". Leva uma mensagem.
Na próxima aula: o arquivo foi lido. Mas onde o trabalho acontece, e o que acontece se você fechar o notebook?
Material complementar · Desktop aproxima os arquivosTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Desktop significa aplicativo instalado no computador. Em ambientes compatíveis, ele pode acessar pastas e aplicativos mediante permissões. A presença do aplicativo não dá acesso universal aos seus documentos. Se uma ferramenta estiver indisponível, ofereça os arquivos por um caminho suportado.
Por que aprender
Muitas falhas de tarefa são falhas de acesso: o aluno imagina que o agente vê uma pasta, mas ela não foi compartilhada. Verificar o contexto antes da execução evita conclusões sobre documentos que o modelo nunca leu.
Conceitos-chave
Pasta autorizada; acesso local; ferramenta disponível; confirmação de leitura.
Na prática
Uma pasta contém três versões de orçamento. A gestora autoriza somente a subpasta de exemplos e pede que o agente liste os arquivos que consegue ler antes de comparar.
Sequência para experimentar
Prepare uma cópia de treino.
Crie uma pasta de treino com dois textos fictícios. Confirme os nomes lidos antes de pedir um resumo.
Registre o resultado observado e a próxima correção.
Aula 9 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 2 · Aula 4 de 6
Saiba onde o trabalho acontece
Você consegue escrever, para uma tarefa sua, onde ela executa, onde lê as entradas e onde salva as saídas.
Uma tarefa não fica permanente só porque começou numa tela moderna. Se você não sabe onde ela roda, não sabe por que ela parou. Nem onde procurar o resultado.
Em 1 minuto
Execução local roda no seu computador e para se ele dormir.
Na nuvem, pode continuar sem a sua máquina, mas só vê os arquivos que chegaram até lá.
Anote três lugares: onde executa, onde lê, onde salva.
1Local depende do seu computador
Na execução local, o trabalho roda na sua máquina. É como um bolo no forno de casa: se a luz cai, o forno para.
Energia, rede e permissões do computador contam. Se o notebook dormir, a tarefa pode parar no meio.
Lúcia pediu ao aplicativo Desktop, da aula 9, uma revisão dos planos de aula que só existem no notebook dela. Fechou a tampa às 18h e foi embora. No dia seguinte, a revisão tinha parado no meio.
Tarefa · revisar planos de aula
1 Executa: no notebook de Lúcia
2 Lê: a pasta Planos do bimestre, no notebook
3 Salva: na mesma pasta
4 Notebook fechado às 18h: a revisão parou no meio
1O trabalho roda na máquina dela.
2Os arquivos também estão nela.
3O resultado fica ali mesmo.
4Máquina dormiu, trabalho local pode parar.
2A nuvem continua, mas só vê o que recebeu
Na nuvem, o trabalho roda em computadores remotos. É como a padaria: o forno não depende da sua casa. Mas o padeiro só tem os ingredientes que você levou.
O chat que você já usa é um exemplo: o modelo trabalha nos computadores da empresa. Por isso ele só conhece o que você colou ou anexou.
Denise quer que o rascunho do relatório de frequência fique pronto mesmo se ela desligar o notebook. Para isso, a planilha precisa estar num lugar que a nuvem alcança.
Local
Depende de: seu computador ligado, com rede.
Lê: as pastas da sua máquina que você permitir.
Nuvem
Depende de: a ferramenta e o seu plano, não da sua máquina.
Lê: só os arquivos enviados ou conectados a ela.
Nenhum dos dois é melhor. Cada um tem uma dependência que você precisa saber.
3O nome da tela não diz onde roda
Alguns ambientes executam na nuvem e continuam sem a sua máquina ligada. Isso depende da funcionalidade, e não só do nome Work ou de a tela ser moderna.
Na dúvida, troque a suposição por três perguntas. Procure a resposta na página de ajuda da ferramenta. Ou teste: inicie uma tarefa curta, feche o notebook por dez minutos e veja se ela andou. Não deu para saber? Vira pendência. No chat do dia a dia, espere a resposta aparecer inteira antes de fechar a aba. Assim você não precisa saber o que acontece com uma resposta pela metade.
Suposição
"Comecei no Work, então roda sozinho."
"O resultado deve estar em algum lugar."
Três perguntas
Onde esta tarefa executa?
Continua com o notebook fechado?
Onde fica o que ela salvar?
Teste-se
Denise iniciou uma tarefa no Work e fechou o notebook. A tarefa continua?
4Três linhas na ficha do projeto
Anote, para cada tarefa, onde ela executa, onde lê as entradas e onde salva as saídas. Não sabe uma delas? Escreva como pendência. Uma pendência escrita é melhor que uma suposição esquecida.
O lugar certo é a ficha do projeto, criada na aula 5. Não fez a aula 5? Use qualquer bloco de notas.
Denise anotou as três linhas do relatório de frequência e uma pendência. Com a pendência, ela foi perguntar ao suporte da escola.
Ficha do projeto · relatório de frequência
1 Executa: na nuvem, segundo a ajuda do Work
2 Lê: a planilha de frequência enviada na tarefa
3 Salva: o rascunho volta na própria tarefa; eu guardo na pasta Relatórios
4 Pendência: não sei por quanto tempo o rascunho fica guardado na tarefa
1Onde roda.
2De onde vêm as entradas.
3Para onde vai a saída.
4O que você ainda não sabe, escrito.
Se travou aqui, é normalLocal e nuvem parecem abstratos até a primeira tarefa parar. Se não souber responder uma linha, escreva "pendência" e siga. A aula cumpre o objetivo mesmo assim: você sabe o que precisa descobrir.
Pratique agora 0/3
Escreva onde uma tarefa sua executa, lê e salva
Pronto quando você tiver três linhas, ou duas linhas e uma pendência, para uma tarefa real. Cerca de 8 minutos, no computador ou no celular, na ficha do projeto ou num bloco de notas.
É só anotação: nada é executado nem enviado. Se nenhuma resposta vier, está tudo bem. Três pendências escritas já mostram o que perguntar.
Tarefa: <ex.: revisar os planos de aula>
Executa: <no meu computador / na nuvem / não sei>
Lê as entradas de: <qual pasta ou arquivo>
Salva as saídas em: <onde fica o resultado>
Pendência: <o que ainda não sei>
Você acabou de mapear onde o seu trabalho acontece, o que quase ninguém faz antes da primeira falha.
Cola da aula
Onde o trabalho acontece
Localpara se o computador dormir.
Nuvemcontinua, mas só com os arquivos que recebeu.
Três linhasexecuta, lê, salva. O resto é pendência.
Seu próximo passo
Você já sabe dizer onde uma tarefa roda e o que ela depende para continuar.
Antes de fechar o notebook com uma tarefa aberta, leia a linha "Executa" da sua ficha.
Na próxima aula: juntar pedido, arquivos e conferência num texto só, o contrato de entrega.
Material complementar · Local e nuvem são escolhas de execuçãoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Local é a execução na sua máquina. Nuvem é a execução em infraestrutura remota. Um trabalho local depende de energia, rede e permissões do computador. Alguns ambientes oferecem execução na nuvem que continua sem a máquina ligada; isso depende da funcionalidade, não apenas do nome Work.
Por que aprender
Uma automação não fica permanente porque foi iniciada numa interface moderna. Você precisa saber onde o processo vive, onde os arquivos ficam e de quais conexões ele depende.
Conceitos-chave
Localização da execução; persistência; acesso aos arquivos; continuidade.
Na prática
Uma revisão de arquivo que existe somente no notebook pode parar se o computador dormir. Um serviço na VPS continua, mas só conhece os arquivos transferidos ou conectados a ele.
✓ Faça
Na sua ficha, escreva onde a tarefa executa, onde lê entradas e onde salva saídas. Se não souber, trate isso como pendência.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Aula 10 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 2 · Aula 5 de 6
O pedido vira contrato de entrega
Você consegue preencher as seis partes de um contrato de entrega e trocar "bom" por um critério que outra pessoa consegue conferir.
A IA não precisa adivinhar se você quer uma explicação, um arquivo para editar ou um texto pronto para publicar. Quando você nomeia o que deve existir no fim e como conferir, o desvio aparece antes de virar retrabalho.
Em 1 minuto
Seis partes: objetivo, entradas, saída, limites, verificação e parada.
São campos de uma encomenda, não palavras mágicas.
"Bom" vira um critério que dá para conferir olhando o resultado.
1Seis campos, uma frase cada
Pense na ordem de serviço de uma assistência técnica. Tem campos fixos: o aparelho, o defeito, o que não mexer, como testar na entrega. Ninguém escreve "conserte bem".
O contrato de entrega é a encomenda da aula 8 com uma sexta parte: a verificação. A autorização da aula 6, no módulo 1, cabe dentro dele: objetivo e parada continuam, arquivos viram entradas, ações e tempo viram limites.
Denise quer o rascunho da ata da reunião pedagógica a partir da pauta. Preencheu os seis campos em quatro minutos.
Contrato de entrega · ata da reunião
1 Objetivo: rascunho da ata da reunião pedagógica, com os itens da pauta, para ela completar com as decisões
2 Entradas: só a pauta colada abaixo
3 Saída: ata com uma linha por ponto da pauta e o responsável de cada um
4 Limites: preserve todos os responsáveis; não invente datas nem nomes
5 Verificação: diga se todos os itens e responsáveis da pauta estão na ata; marque datas ausentes
6 Parada: entregue o rascunho e não envie nada
1Para que serve.
2O que a IA pode usar.
3O que deve existir no fim.
4O que ela não pode fazer.
5Como se confere.
6Onde ela para.
2Nomeie o que deve existir no fim
"Faça uma ata" deixa aberto o formato, o tamanho e o que fazer com o que falta. O contrato responde às três: formato fixo, tamanho definido e dado ausente marcado. A IA para de adivinhar.
Chat de IA
VocêFaça uma ata boa desta reunião. [pauta colada]
IAAta da Reunião Pedagógica, realizada em 12 de março, às 14h, na sala dos professores. Estiveram presentes os professores…
Data, hora e local não estavam na pauta. A IA preencheu com palpite.
Você[os seis campos do contrato]
Pauta:
1. Calendário da feira de ciências. Responsável: Lúcia.
2. Reforço de matemática. Responsável: Marcos.
3. Materiais da feira.
IARascunho da ata. Data: [não informada na pauta]
1. Calendário da feira de ciências. Responsável: Lúcia.
2. Reforço de matemática. Responsável: Marcos.
3. Materiais da feira. Responsável: [não informado].
Verificação: os 3 itens e os 2 responsáveis da pauta estão na ata. A data e o responsável ausentes ficaram marcados. Não enviei.
Nada inventado, e o que faltava aparece marcado.
Toque nos dois botões e procure o que a IA inventou no pedido comum.
3Troque "bom" por um critério que se confere
"Bom", "claro" e "completo" são desejos. Ninguém consegue conferir um desejo. A verificação usa critérios que qualquer pessoa confere olhando o resultado, como a régua de qualidade da aula 4.
Lúcia pedia roteiros de experimento "bem explicados". Trocou por dois critérios. Agora confere cada roteiro em um minuto.
Desejo
"Um roteiro de experimento bem explicado e completo."
Critério
Cada passo começa com um verbo.
Todo material citado nos passos está na lista de materiais.
Saldo: dois critérios que qualquer colega confere sem perguntar o que ela quis dizer.
4Quanto mais fácil conferir, mais cedo aparece o desvio
Uma saída fácil de inspecionar mostra o erro na primeira leitura. Por isso o contrato pede formato fixo e uma verificação escrita no fim.
Na ata de Denise, a verificação dizia "2 responsáveis". Ela contou na pauta e na ata: 2 e 2. Levou 30 segundos, porque a ata era uma lista.
Difícil de conferir
Um texto corrido de uma página sobre a reunião.
Para achar um erro, você relê tudo.
Fácil de conferir
Um item por ponto da pauta, com o responsável.
Você compara linha a linha com a pauta.
Teste-se
Qual destas verificações outra pessoa consegue conferir olhando o resultado?
Se travou aqui, é normalSeis campos parecem muito na primeira vez. Escreva uma frase por campo, mesmo curta. Se um campo não se aplica, escreva "nenhum". O campo que mais faz diferença é a verificação.
Pratique agora 0/3
Preencha um contrato de entrega e mande no chat
Pronto quando a resposta terminar com a verificação que você pediu e você tiver conferido um critério direto no material. Cerca de 10 minutos, no chat que você já usa.
Use uma pauta inventada, sem nomes reais. A parada pede que nada seja enviado; na aula 12 você confere se foi assim. Guarde a resposta: a aula 12 usa essa entrega para a revisão.
OBJETIVO
<ex.: pauta revisada da reunião, pronta para eu enviar>
ENTRADAS: USE SOMENTE ESTE MATERIAL
<cole uma pauta inventada com cinco itens>
SAÍDA
<ex.: lista numerada com os cinco itens e o responsável de cada um>
LIMITES
Não invente datas nem nomes. Dado ausente vira [não informado].
VERIFICAÇÃO
Diga se os cinco itens estão na saída e marque o que faltou.
PARADA
Entregue a pauta revisada e não envie nada.
Veja o molde já preenchido por uma professora
Objetivo: pauta revisada da reunião de pais do 8º ano. Entradas: 1. Notas do bimestre, com a professora de ciências. 2. Feira de ciências, com a coordenação. 3. Uso do celular. 4. Passeio ao museu. 5. Dúvidas. Saída: lista numerada com os cinco itens e o responsável de cada um. Limites: não invente datas nem nomes; responsável ausente vira [não informado]. Verificação: diga se os cinco itens estão na saída e marque o que faltou. Parada: entregue a pauta revisada e não envie nada.
Você acabou de escrever um pedido que diz o que deve existir no fim e como conferir.
Cola da aula
Contrato de entrega
Seis camposobjetivo, entradas, saída, limites, verificação, parada.
Saída com nomeformato fixo, fácil de comparar com a fonte.
Critériono lugar de "bom", algo que se confere olhando.
Seu próximo passo
Você já escreve pedidos que dizem o que deve existir no fim e como conferir.
Pegue o pedido que você mais repete no trabalho e troque um "bom" dele por um critério.
Na próxima aula: a IA disse "pronto". Como saber se está pronto de verdade?
Material complementar · Escreva um contrato de entregaTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Um bom pedido contém objetivo, contexto, entradas, restrições, resultado e verificação. São campos de uma encomenda, não palavras mágicas. Quanto mais fácil for inspecionar a saída, mais fácil será detectar um desvio antes que vire retrabalho.
Por que aprender
O agente não precisa adivinhar se você quer uma explicação, um arquivo editável ou uma publicação. Nomear o artefato e a condição de pronto encurta a distância entre intenção e execução.
“Use pauta.txt para criar ata-rascunho.md. Preserve todos os responsáveis, sinalize datas ausentes e não envie nada.” Esse pedido determina entradas, saída e um limite concreto.
Experimente agora
Use o arquivo materiais/contrato-de-tarefa.md. Preencha cada campo com uma frase e troque “bom” por um critério que alguém consiga conferir.
Objetivo
Entrada
Saída
Limites
Verificação
Parada
As seis partes de um contrato de entrega. Sem a verificação e a parada, você recebe texto em vez de trabalho.
Aula 11 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 2 · Aula 6 de 6
Pronto é depois da conferência
Você consegue conferir um fato, um formato e uma ação numa entrega da IA. E anotar o que observou em cada um.
A palavra "pronto" não mostra que o arquivo abre nem que os dados foram mantidos. Uma conferência pequena, feita por você, costuma achar mais problemas que pedir de novo "melhore".
Em 1 minuto
A entrega só termina depois da sua conferência.
Confira três coisas: um fato, um formato e uma ação.
Peça à IA o que ela conferiu e separe teste feito de teste sugerido.
1Abra a entrega e compare com a fonte
É como conferir a sacola do mercado contra a nota antes de sair. Não basta a sacola estar cheia. Cada item da nota tem de estar lá, e nada a mais.
Lúcia recebeu a ata da reunião da área de ciências. Comparou cada decisão com a pauta. Achou um responsável que a IA inventou.
Pauta (a fonte)
1. Horário do laboratório. Responsável: Lúcia.
2. Compra de reagentes. Responsável: não definido.
Ata recebida
1. Horário do laboratório. Responsável: Lúcia.
2. Compra de reagentes. Responsável: Paulo.
Saldo: um nome inventado, achado em dois minutos de comparação.
A ata parecia completa. Só a comparação linha a linha mostrou o nome que não existia na pauta.
2Três conferências: fato, formato, ação
Você não precisa reler tudo. Escolha três pontos. Um fato, que bate com a fonte. Um formato, que é o que foi pedido. E uma ação, que funciona ou foi feita do jeito combinado.
No relatório de frequência, Denise conferiu o total de faltas de uma turma e se o arquivo abria com as colunas pedidas. Depois, testou o link da planilha citado no relatório.
Conferência · relatório de frequência
1 Fato: o total de faltas do 7º A bate com a soma da planilha
2 Formato: o arquivo abre e tem uma coluna por mês
3 Ação: o link da planilha, citado no relatório, abre
1Um número, nome ou data comparado com a fonte.
2Abrir o arquivo e ver se tem o que foi pedido. No chat, ver se a resposta tem os itens ou as colunas pedidas.
3Testar o que deveria funcionar, como um link ou uma soma, ou confirmar o que não devia ser feito.
3Teste feito não é teste sugerido
Peça à IA a evidência do que ela verificou. E peça para separar o que ela conferiu de fato do que só sugere conferir.
"Revisei tudo" não diz o que foi revisado. Uma lista diz, e mostra o que sobrou para você. Mesmo o "conferi" da IA é uma afirmação: confira um item da lista por amostra.
Chat de IA
VocêEstá pronta a ata?
IASim! Revisei tudo e está correta.
Não diz o que foi conferido. Você não tem como saber.
VocêMostre o que você conferiu, lado a lado com a pauta, e diga o que ficou sem conferir.
IAPauta 1, Horário do laboratório → ata 1, Horário do laboratório: igual.
Pauta 2, Compra de reagentes → ata 2, Compra de reagentes: igual.
Não conferi: se cada responsável é o mesmo da pauta. Sugiro que você compare essa coluna.
Os itens aparecem lado a lado para você conferir, e o que falta está dito: a coluna dos responsáveis.
Toque nos dois botões. A segunda resposta aponta o que ainda depende de você.
Teste-se
Qual destas respostas da IA traz uma evidência que você consegue conferir?
4Anote e corrija o pedido, não só o texto
Anote o que observou em cada conferência, com o resultado exato. Achou erro? Corrija também o pedido antes de reutilizar, ou a fonte, se o erro veio dela. Senão, o erro volta na próxima vez.
Lúcia corrigiu o nome na ata. Depois acrescentou uma linha ao contrato de entrega: "responsável que a pauta não define vira [não informado]".
Registro da revisão · ata da área de ciências
1 Fato: item 2 com responsável inventado ✗
2 Formato: um item por ponto da pauta ✓
3 Ação: nada enviado ✓
4 Correção no contrato: responsável que a pauta não define vira [não informado]
1O que você viu, com o resultado.
2Formato conferido.
3Ação conferida.
4A mudança que impede o erro de voltar.
Se travou aqui, é normalNão achou erro nenhum? Ótimo sinal, e a conferência valeu do mesmo jeito. Anote "✓" com o que você comparou. O registro mostra que você olhou, e não só que confiou.
Pratique agora 0/3
Confira um fato, um formato e uma ação
Pronto quando você tiver três anotações, uma para cada conferência, com o resultado que observou. Cerca de 10 minutos, no papel ou num bloco de notas, no celular ou no computador.
Você só lê e compara: nada é alterado nem enviado. Não fez a aula 11? Use a pauta e a ata de treino logo abaixo.
Pauta e ata de treino, para quem não tem uma entrega
Pauta: 1. Semana de provas, com a coordenação. 2. Troca de sala do 8º B, sem responsável definido. 3. Festa junina, com a professora Ana.
Ata recebida: 1. Semana de provas. Responsável: coordenação. 2. Troca de sala do 8º B. Responsável: professor Ivo. 3. Festa junina. Responsável: professora Ana. Enviada ao grupo de professores.
Gabarito da ata de treino
Fato: "professor Ivo" não está na pauta; o item 2 não tinha responsável. Formato: três itens, um por ponto da pauta, certo. Ação: a ata diz que foi enviada ao grupo, e o envio não estava autorizado. Correção no pedido: "responsável que a pauta não define vira [não informado]; não envie nada".
Você acabou de fazer a parte da entrega que nenhuma IA faz por você: conferir.
Cola da aula
Conferir a entrega
Compare com a fontecada item da fonte está lá, e nada a mais.
Fato, formato, açãotrês pontos, cada um com o resultado anotado.
Evidênciao que a IA conferiu de fato, separado do que só sugeriu.
Seu próximo passo
Você fechou o módulo 2: já escolhe entre chat e encomenda, confirma o que a IA leu, sabe onde o trabalho roda, escreve um contrato de entrega e confere o resultado.
Quando tiver uns 30 minutos, abra o material complementar desta aula e faça o laboratório opcional do módulo, "De pergunta solta a encomenda".
No próximo módulo: terminal e Codex na prática. O contrato de entrega vai junto, agora com uma IA que trabalha numa pasta sua.
Material complementar · Revise o trabalho recebidoTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
Uma entrega só termina depois da conferência. Abra o arquivo, compare números com as fontes e teste os links ou fórmulas relevantes. Peça ao agente evidências do que verificou, distinguindo teste executado de sugestão de teste.
Por que aprender
A frase “pronto” não demonstra que o arquivo abre ou que todos os dados foram preservados. Uma verificação independente pequena costuma achar mais problemas que um novo pedido genérico de melhora.
Conceitos-chave
Abrir; comparar; testar; registrar limites.
Na prática
A ata tem uma lista de decisões. A professora confronta cada decisão com a pauta e encontra uma responsabilidade inventada. Ela corrige a fonte ou o pedido antes de reutilizar o procedimento.
Experimente agora
Revise três elementos de sua entrega: um fato, um formato e uma ação. Anote exatamente o resultado observado em cada um.
Laboratório do módulo: De pergunta solta a encomenda
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Crie uma pauta fictícia de reunião com cinco itens, sem nomes reais.
Escreva um pedido com objetivo, materiais, formato e critério de revisão.
Use Chat ou Work disponível na sua conta para produzir a pauta revisada.
Confira os cinco itens, salve o resultado e registre uma melhoria no pedido.
Contrato de tarefa
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
Objetivo: preparar uma pauta revisável
Entrada: entradas/reuniao.txt
Saída: saidas/pauta.md
Limites: não enviar mensagens; não inventar datas
Verificação: os 5 itens originais continuam presentes
Parada: entregue o arquivo e relate as pendências
Critério de pronto
Redigir uma encomenda de trabalho com entradas, saída e revisão. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
Você precisa apenas de uma explicação de duas frases. Deve obrigatoriamente usar Work?
Ver resposta comentada
Não. Escolha a interface pelo resultado necessário; Chat pode ser suficiente.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Você consegue abrir o terminal, digitar dois comandos e dizer em que pasta está e o que tem nela.
A partir deste módulo, a IA trabalha numa pasta do seu computador. Se você não sabe em que pasta está, ela também não sabe. Muito erro que parece falha da IA é só a pasta errada.
Em 1 minuto
O terminal é uma janela em que você escreve um comando e lê a resposta.
pwd diz onde você está. ls diz o que tem ali.
Primeiro a localização, depois os arquivos. Esses dois comandos não mudam nada.
1Cada sistema tem o seu terminal
O terminal já vem no computador. Você só precisa saber onde ele fica. Os comandos deste curso são escritos em Bash, a linguagem do terminal no Linux e no macOS. O Mac usa uma variação dele, e os comandos funcionam igual.
No Windows, eles funcionam dentro do WSL. O terminal que já vem no Windows usa outra linguagem. Não cole nele os comandos do curso sem adaptar.
Lúcia usa um notebook com macOS. Ela apertou Cmd+Espaço, digitou "Terminal" e teclou Enter. Levou dez segundos.
Onde fica o terminal
1 macOS
Cmd+Espaço, digite "Terminal" e Enter
2 Linux
procure "Terminal" na lista de aplicativos
3 Windows
WSL, ou o caminho oficial para Windows (aula 14)
1No Mac, a busca acha o Terminal pelo nome.
2No Linux, busque pelo nome.
3No Windows, os comandos do curso pedem o WSL.
Uso Windows: como ter o WSL
O WSL é da própria Microsoft. Abra o menu Iniciar, procure "PowerShell", clique com o botão direito › Executar como administrador. Digite o comando abaixo, tecle Enter e reinicie o computador quando ele pedir.
PowerShell · administrador
> wsl --install
Depois de reiniciar, procure "Ubuntu" no menu Iniciar: essa janela é o terminal onde os comandos do curso funcionam. Na primeira vez, ele pede um nome de usuário e uma senha novos: anote a senha num lugar seguro.
Se travou aqui, é normalO computador é da escola ou pediu uma senha que você não tem? Não force: faça hoje a leitura desta aula e peça o WSL a quem cuida do computador. Na aula 14, a página oficial do Codex também mostra o caminho para Windows.
2Você escreve uma linha, ele devolve outra
Ao abrir, o terminal mostra uma linha curta que termina em $, com o cursor piscando. No Mac, ela termina em %: é a mesma coisa. É o computador esperando o seu comando.
Você digita o comando e tecla Enter. A resposta aparece logo abaixo. Depois, o $ volta, pronto para o próximo.
Denise abriu o terminal pela primeira vez e esperou algo acontecer. Nada aconteceu, porque ele estava esperando por ela.
A linha com $ (no Mac, %) é a vez de você digitar. A linha sem $ é a resposta do computador.
Comando, resposta e o $ de volta: é sempre esse vaivém.
3pwd é o "você está aqui"
Sabe o mapa da escola com o adesivo "você está aqui"? O comando pwd faz esse papel. Ele responde o caminho completo da pasta em que você está agora.
Leia o caminho como endereço. Cada barra separa uma pasta, e a última é onde você está. No macOS, a sua pasta pessoal começa com /Users; no Linux, com /home.
Lúcia digitou pwd e leu /Users/lucia. Então ela estava na pasta pessoal, a mesma que abre quando clica na casinha do Finder.
Terminal · macOS
$ pwd
/Users/lucia
Uma linha só: a pasta pessoal de Lúcia. Nada foi criado nem apagado.
O pwd só informa. Use sempre que tiver dúvida de onde está.
4ls mostra o que tem na pasta
Depois de saber onde está, veja o que tem ali. O comando ls lista as pastas e os arquivos do lugar atual, lado a lado. No Mac, as pastas da pasta pessoal aparecem com nome em inglês, como Documents e Downloads.
Para mudar de pasta existe o cd. Ele fica para a aula 16. Por enquanto, basta saber que a pasta de início importa.
Denise abriu o Codex na pasta Downloads, num teste de um colega. Ele não enxergava o projeto dela, que estava em outra pasta. O pwd teria mostrado isso antes.
Terminal · Linux
$ pwd
/home/denise$ ls
Documentos Downloads Imagens Músicas
Primeiro a localização, depois o conteúdo. Os nomes mudam de um computador para outro.
O ls mostra o que o programa vai enxergar se começar a trabalhar dali.
Teste-se
Lúcia digitou ls e a pasta do projeto não apareceu na lista. O que ela confere primeiro?
Pratique agora 0/3
Pergunte ao computador onde você está
Pronto quando você tiver anotado a resposta do pwd e três nomes que o ls mostrou. Cerca de 8 minutos, no computador.
Os dois comandos só leem: nada é criado, movido ou apagado. Se aparecer "command not found", confira a digitação: tudo em minúsculas, sem espaço no meio. No Windows sem WSL, pare no passo 1 e siga para a aula 14.
pwd
ls
Você acabou de ler, no terminal, onde está e o que tem ali, sem mudar nada.
Cola da aula
Primeiros comandos
Terminalvocê digita uma linha, ele devolve a resposta.
pwda pasta em que você está agora.
lso que tem nessa pasta.
Seu próximo passo
Você já sabe perguntar ao computador onde está e o que tem ali.
Amanhã, abra o terminal de novo e digite pwd antes de qualquer outra coisa. Leva dez segundos e vira hábito.
Na próxima aula: colocar o Codex no computador pela fonte oficial, e conferir que deu certo com um comando.
Material complementar · Terminal é uma porta de entradaTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Terminal é a janela em que você escreve comandos para o computador. Shell é o programa que interpreta esses comandos. Aqui os exemplos de terminal usam Bash no Linux ou macOS; no Windows, use um ambiente Bash via WSL ou siga o instalador oficial para Windows. Não cole comandos Linux diretamente no PowerShell sem adaptação.
Por que aprender
Saber em qual ambiente você está evita erros que parecem falhas da IA. O comando cd muda a pasta atual; pwd mostra a localização no Bash. Não é necessário decorar dezenas de comandos para começar.
Conceitos-chave
Terminal; shell; pasta atual; comando e resposta.
Na prática
Se você abre Codex na pasta Downloads, ele não está automaticamente trabalhando dentro de meu-primeiro-projeto. A pasta de início precisa ser escolhida.
✓ Faça
No Bash, execute pwd e depois ls. Leia a saída: primeiro localização, depois arquivos. Não altere nada neste passo.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Abrir o terminal
Entrar na pasta
Autenticar
Pedir a tarefa
A ordem importa: entrar na pasta certa antes de pedir evita trabalho feito no lugar errado.
Termos desta seção: porta.
Aula 13 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 3 · Aula 2 de 6
Programa novo vem da fonte oficial
Você consegue instalar o Codex pelo endereço oficial e confirmar, com um comando, que o computador o reconhece.
Na internet circulam comandos "mais rápidos" para colocar programas no computador. Um comando colado sem conferir pode executar qualquer coisa. Conferir a fonte leva um minuto e evita esse risco.
Em 1 minuto
Colocar o programa, entrar com a conta e abrir na pasta são três etapas diferentes.
O comando vem da página oficial. Confira o endereço antes de colar.
codex --version confirma que deu certo.
1Três etapas, uma de cada vez
Instalar põe o programa no computador. Isso não conecta a sua conta nem escolhe a pasta de trabalho. Cada coisa tem a sua etapa e a sua conferência.
Esta aula faz só a primeira. As outras duas vêm nas aulas 15 e 16.
Logo depois de instalar, Lúcia digitou codex e o programa pediu para ela entrar com a conta. Achou que era defeito. Não era: a primeira etapa tinha dado certo, e faltava a segunda.
Do zero ao primeiro pedido
1 Colocar o programa no computador · esta aula
2 Entrar com a sua conta · aula 15
3 Abrir na pasta do projeto · aula 16
1Confere com codex --version.
2Tem a sua própria conferência, na aula 15.
3Confere com pwd, da aula 13.
2Confira o lacre antes de abrir a caixa
Quando chega uma caixa na secretaria, você olha o lacre e o remetente antes de abrir. Com um comando é igual: o remetente é o endereço de onde ele vem.
O comando oficial baixa um script do endereço chatgpt.com e o executa. Por isso o endereço importa tanto. Comando de página desconhecida não se cola.
Denise recebeu num grupo um "jeito mais rápido" de pôr o Codex no computador. O endereço no meio do comando não era o da página oficial. Ela não colou e usou o da página.
✗ Mensagem do grupo
Endereço no comando: um site com "codex" no nome, mas que não é chatgpt.com.
Quem garante: ninguém.
✓ Página oficial
Endereço no comando: https://chatgpt.com/codex/install.sh
Quem garante: a empresa que faz o programa, na página de instalação.
Leia o endereço dentro do comando, não só o título da mensagem.
3Cole o comando e espere a última linha
No macOS e no Linux, o comando da página oficial é este abaixo. No Windows com WSL, cole o mesmo comando dentro do Ubuntu. Sem WSL, siga a página oficial do Codex, que tem orientação própria.
Use o botão copiar: não precisa digitar a barra vertical. O instalador escreve algumas linhas enquanto trabalha, e você não precisa entender cada uma. Espere o $ (no Mac, %) voltar. Quem confirma se deu certo é o passo 4.
Lúcia colou o comando no Terminal do Mac e esperou. As linhas que passaram, ela não tentou decifrar. Quando o % voltou, passou para a conferência.
Terminal · macOS ou Linux
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
É uma linha só, mesmo que a tela do celular a quebre. curl baixa o arquivo do endereço; a barra vertical o passa para o sh, que executa os comandos dele.
O endereço no meio do comando é o lacre: confira que é chatgpt.com.
4codex --version confirma
Para saber se deu certo, peça a versão. Se o computador reconhece o programa, ele responde com um número.
Se aparecer "command not found", o terminal ainda não achou o programa. Feche o terminal, abra de novo e repita.
No notebook de Denise, a primeira tentativa deu "command not found". Ela fechou o terminal, abriu outro e digitou de novo. Veio o número da versão.
Terminal
$ codex --version
codex: command not found$# fechou e abriu o terminal de novo$ codex --version
codex-cli 0.156.1
"command not found" quer dizer "não achei esse programa". Depois de reabrir, veio a versão. O número muda com o tempo.
Qualquer número de versão na resposta quer dizer: está no computador e o terminal o encontra.
Se travou aqui, é normal"command not found" logo depois da primeira vez é comum: o terminal aberto antes não sabe do programa novo. Feche, abra de novo e repita o codex --version. Continuou? Copie a mensagem de erro, sem senha nenhuma, e leve para quem cuida do computador.
Pratique agora 0/3
Coloque o Codex no computador e confira a versão
Pronto quando codex --version responder com um número. Cerca de 10 minutos, no computador, com internet.
O comando só vale se for igual ao da página oficial: confira o endereço chatgpt.com. Se pedir a senha do computador e ele é seu, digite a sua: as letras não aparecem enquanto você digita. Se o computador é da escola, pare e fale com quem cuida dele.
Passo 2 · cole no terminal
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Passo 3 · cole no terminal novo
codex --version
Você acabou de pôr um programa no computador pela fonte oficial e de conferir que ele está lá.
Cola da aula
Pela fonte oficial
Três etapascolocar o programa, entrar com a conta, abrir na pasta.
Endereçoo comando vem da página oficial; confira chatgpt.com.
Versãoum número na resposta quer dizer que deu certo.
Seu próximo passo
Você já sabe pôr um programa no computador sem colar comando de origem duvidosa.
Na ficha do projeto, anote numa linha: "Codex · versão <o número> · fonte: página oficial". Leva um minuto.
Na próxima aula: o programa está no computador, mas ainda não sabe quem você é. Você vai entrar com a sua conta sem deixar nenhuma senha à mostra.
Material complementar · Instale pela fonte oficialTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
A página oficial do Codex oferece instalador para macOS/Linux e orientações específicas para Windows. Instalar significa adicionar o programa à máquina. O comando de instalação baixa e executa um script oficial; leia a fonte, confira o domínio e use sua própria conta. Não execute comandos recebidos de páginas desconhecidas.
Por que aprender
Instalação, login e execução são etapas diferentes. Um programa instalado ainda precisa de autenticação. Um login concluído não significa que você abriu a pasta correta.
Conceitos-chave
Fonte oficial; instalação; versão; diagnóstico.
Na prática
Depois da instalação, codex --version informa a versão reconhecida pelo terminal. Se aparecer “command not found”, reabra o terminal e confira o caminho indicado pelo instalador.
Experimente agora
No macOS/Linux: curl -fsSL https://chatgpt.com/codex/install.sh | sh. Depois verifique com codex --version. Veja a fonte no rodapé para outras plataformas.
Aula 14 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 3 · Aula 3 de 6
Entre com a conta sem mostrar a chave
Você consegue conectar o Codex à sua conta, conferir por qual método ele entrou e anotar na ficha só esse método, sem nenhuma senha.
Uma chave colada numa mensagem, num exemplo ou num print pode ser usada por outra pessoa, e a conta é sua. Também dá para estar conectado pelo método errado e gastar de uma conta que você não esperava.
Em 1 minuto
codex login abre o navegador para você entrar com a conta do ChatGPT.
codex login status diz por qual método você entrou.
Na ficha vai "ChatGPT" ou "API". Nunca a chave.
1O crachá passa na catraca, a senha fica com você
Na escola, você passa o crachá na catraca e ninguém ouve a sua senha. O login do Codex funciona assim: o terminal manda você ao navegador, e é lá que você entra.
A senha nunca passa pelo terminal. Quando você termina no navegador, o Codex recebe a confirmação e guarda a entrada.
Quais planos do ChatGPT incluem o Codex muda com o tempo. Antes de começar, confira na página oficial de autenticação se o seu plano está lá. O nome do seu plano aparece nas configurações da sua conta do ChatGPT.
Lúcia digitou codex login. O navegador abriu na tela de entrada do ChatGPT. Ela entrou com a conta da escola e voltou para o terminal.
Terminal
$ codex login
# o navegador abre; entre com a conta do ChatGPT e volte ao terminal
A primeira linha é o que você digita. A segunda é um lembrete do curso: o resto acontece no navegador.
Nenhuma senha é digitada no terminal nesse caminho.
2codex login status diz o método
Estar conectado não basta: importa por qual caminho. Entrar com a conta usa o plano dela. Uma chave de API cobra por consumo, em outra conta.
Essa diferença é da aula 5, no módulo 1. Pulou? O resumo é esse: são duas contas, com duas cobranças.
Denise esperava ver "ChatGPT" e viu que o Codex estava entrando por uma chave de API antiga da escola. Ela saiu com codex logout e entrou de novo com codex login, pela conta.
Terminal
$ codex login status
Logged in using ChatGPT
Em inglês: "conectado usando o ChatGPT". O método é a conta. Com uma chave de API, a resposta cita a chave, mas nunca o valor completo.
Leia a resposta antes de pedir qualquer tarefa longa.
3Pela API, a chave não aparece na tela
Vai entrar pela conta do ChatGPT? Pode pular este passo. Se você usar API, a chave fica guardada num nome, OPENAI_API_KEY, que o terminal conhece. O comando oficial entrega o valor direto ao Codex, sem mostrar na tela.
Digitar a chave no comando é o erro comum: ela fica no histórico do terminal e aparece em qualquer print. Um arquivo .env sozinho também não conecta nada. Algum mecanismo precisa carregar o valor.
Uma colega pediu a chave da escola para testar em casa. Lúcia não mandou pelo grupo. Explicou que a chave diz quem paga e que cada pessoa entra com a própria conta.
✗ Chave no comando
Como fica:codex login --with-api-key seguido da chave inteira.
Resultado: a chave fica no histórico e em qualquer print da tela.
✓ Comando oficial
Como fica:printenv OPENAI_API_KEY | codex login --with-api-key
Resultado: o valor vai direto ao programa. Na tela, só o comando.
Os dois conectam. Só o segundo não espalha a chave.
4Na ficha, o método; a chave, nunca
Anote na ficha do projeto qual método está ativo e onde você conferiu. É a mesma ficha de acesso da aula 5. Não tem ficha ainda? Uma nota no celular serve.
A credencial não vai para a ficha, para um pedido nem para um print. Se ela vazar, quem cuida da conta precisa trocar a chave.
A linha de Denise ficou assim: "Codex · ChatGPT · conferido com codex login status". Nenhuma senha, nenhum pedaço de chave.
Ficha de Denise · acesso
1 Ferramenta: Codex
2 Método: ChatGPT
3 Onde conferi: codex login status
4 Credencial: não anotada
Se travou aqui, é normalNão sabe se usa ChatGPT ou API? Comece pela conta do ChatGPT, com codex login: é o caminho sem chave nenhuma. O navegador não abriu sozinho? Veja se o terminal mostrou um endereço e abra esse endereço no navegador.
Pratique agora 0/3
Conecte o Codex e anote só o método
Pronto quando codex login status disser o método e a ficha tiver essa linha, sem senha. Cerca de 8 minutos, no computador.
Neste caminho você não digita senha no terminal: ela fica no navegador. Não fez a aula 14? Confira antes com codex --version. Computador de outra pessoa? Ao terminar, saia com codex logout.
Passo 1 · cole no terminal
codex login
Passo 2 · cole no terminal, depois de entrar no navegador
codex login status
Você acabou de conectar um programa à sua conta e registrar como, sem expor nenhuma credencial.
Cola da aula
Conectar sem expor
codex logina entrada acontece no navegador.
codex login statusmostra o método: conta ou chave.
Fichaanota o método; a credencial fica de fora.
Seu próximo passo
Você já sabe conectar o Codex e dizer de qual conta sai o uso dele.
Procure hoje, no seu e-mail e nas conversas de trabalho, alguma chave ou senha colada em texto. Achou? Apague e avise quem cuida dessa conta.
Na próxima aula: o Codex está conectado, mas em que pasta ele vai trabalhar? Você vai montar uma pasta de treino e abrir o Codex dentro dela.
Material complementar · Autentique sem espalhar segredosTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Execute codex login e conclua o fluxo de navegador para entrar com ChatGPT. Se optar por API, a chave precisa estar na variável OPENAI_API_KEY; encaminhe-a pela entrada padrão, sem digitá-la no comando. Um arquivo .env sozinho não autentica o Codex: algum mecanismo deve carregar a variável.
Por que aprender
Colar a chave em exemplos, mensagens ou histórico pode expor a conta. Também é possível estar autenticado pelo método errado e consumir uma modalidade diferente da esperada.
Conceitos-chave
codex login; codex login status; entrada padrão; conta ativa.
Na prática
Para API, o comando documentado é printenv OPENAI_API_KEY | codex login --with-api-key. Ele envia o valor diretamente ao programa, em vez de mostrar a chave na tela.
Sequência para experimentar
Prepare uma cópia de treino.
Escolha um método, conclua o login e execute codex login status. Registre apenas “ChatGPT” ou “API” na ficha do projeto.
Registre o resultado observado e a próxima correção.
Aula 15 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 3 · Aula 4 de 6
Abra o agente na pasta certa
Você consegue criar uma pasta de treino com três arquivos fictícios, entrar nela pelo terminal e abrir o Codex ali dentro.
O Codex trabalha na pasta em que foi aberto. Na pasta errada, ele lê o que não devia e não acha o que precisa. Uma pasta pequena, só com o material da tarefa, deixa claro o que ele podia tocar.
Em 1 minuto
A pasta de trabalho é a sala da tarefa: só o material dela.
O README explica o projeto para pessoas; o AGENTS.md dá as regras ao agente.
cd entra na pasta, pwd confirma, e só entãocodex.
1Entre na sala antes de começar a aula
Quem entra na sala errada dá a aula para a turma errada. Com o Codex é igual: ele trabalha onde foi aberto. Então você entra na pasta antes de abrir o programa.
mkdir -p cria a pasta, e as de antes se faltarem. cd entra nela. O sinal ~ quer dizer "a minha pasta pessoal": no Finder do Mac, é a pasta com o seu nome e o ícone de casinha.
Denise criou a pasta de treino e entrou nela. O pwd confirmou o endereço antes de ela abrir qualquer programa.
Terminal
$ mkdir -p ~/projetos/meu-primeiro-projeto
$ cd ~/projetos/meu-primeiro-projeto
$ pwd
/home/denise/projetos/meu-primeiro-projeto
Os dois primeiros comandos não respondem nada quando dão certo. Quem confirma é o pwd.
A última pasta do endereço é a da tarefa: ali o Codex vai trabalhar.
2Na pasta, só o material da tarefa
Você não precisa abrir a sua pasta pessoal inteira para experimentar. Uma área pequena, com arquivos de treino, reduz a confusão. Quando algo sai errado, fica claro quais arquivos podiam ter mudado.
Lúcia pensou em abrir o Codex na pasta Documentos, onde estão as provas e as notas das turmas. Preferiu a pasta de treino, com uma pauta fictícia. Nada real ficou ao alcance.
meu-primeiro-projeto
1 README.md
2 AGENTS.md
3 entradas
reuniao.txt
1Para que serve o projeto.
2As regras para o agente.
3O material de trabalho: uma pauta fictícia de cinco itens.
3Um arquivo para pessoas, outro para o agente
O README descreve a finalidade do projeto para quem chega. O AGENTS.md dá instruções de trabalho ao agente.
Os dois terminam em .md porque são texto em Markdown: o # marca o título, e o hífen, um item de lista.
Denise escreveu no README a finalidade: preparar a pauta da reunião. No AGENTS.md, pôs duas regras: trabalhar só naquela pasta e não enviar nada.
README.md · para pessoas
# Meu primeiro projeto
Projeto de treino do curso OSWork. Só arquivos fictícios.
Finalidade: preparar a pauta da reunião pedagógica a partir de entradas/reuniao.txt.
AGENTS.md · para o agente
# Instruções para o agente
- Trabalhe só dentro desta pasta.
- Não envie nem publique nada.
Os dois estão certos, cada um para um leitor. No módulo 4, o AGENTS.md cresce.
4Confira a pasta e abra o Codex
Antes de digitar codex, rode pwd e ls. Se o endereço e os arquivos batem, abra o programa ali.
Na primeira vez numa pasta, o Codex pergunta se você confia nela. É a sua pasta de treino: escolha "Trust and continue" com as setas e tecle Enter. Neste treino, não use "Open restricted". Para sair do Codex, digite /quit e tecle Enter.
Lúcia conferiu o endereço, viu os três itens no ls e só então digitou codex. Respondeu à pergunta sobre a pasta e saiu com /quit, sem pedir nada ainda.
Terminal
$ pwd
/Users/lucia/projetos/meu-primeiro-projeto$ ls
AGENTS.md README.md entradas$ codex
Trust this folder? Codex can read, edit, and run files here,
subject to your permission settings. …
› Trust and continue
Open restricted
Em inglês: "Confia nesta pasta? O Codex pode ler, editar e executar arquivos aqui, dentro das suas permissões." "Trust and continue" é "confiar e continuar"; "Open restricted" abre com restrições. A resposta fica guardada. As palavras podem mudar um pouco com a versão.
Endereço certo, arquivos certos, e só então o programa.
Se travou aqui, é normalA pergunta em inglês assusta na primeira vez. Ela só aparece porque a pasta é nova para o Codex. Confirme apenas em pastas que você conhece. Na dúvida, saia com /quit (ou tecle Ctrl+C duas vezes) e confira o pwd de novo.
Pratique agora 0/3
Monte a pasta de treino e abra o Codex nela
Pronto quando o ls mostrar AGENTS.md, README.md e entradas, e o Codex abrir nessa pasta. Cerca de 10 minutos, no computador.
O bloco cria uma pasta nova e escreve três arquivos fictícios dentro dela: cada cat > escreve no arquivo tudo até a linha FIM. Nada fora dela é tocado. Use o bloco só nessa pasta nova: em outra pasta, ele substituiria um README.md que já estivesse lá. Copie o bloco inteiro, até o último ls. Se o terminal ficar parado mostrando >, tecle Ctrl+C e cole o bloco inteiro de novo.
mkdir -p ~/projetos/meu-primeiro-projeto/entradas
cd ~/projetos/meu-primeiro-projeto
cat > README.md <<'FIM'
# Meu primeiro projeto
Projeto de treino do curso OSWork. Só arquivos fictícios.
Finalidade: preparar a pauta da reunião pedagógica a partir de entradas/reuniao.txt.
FIM
cat > AGENTS.md <<'FIM'
# Instruções para o agente
- Trabalhe só dentro desta pasta.
- Não envie nem publique nada.
FIM
cat > entradas/reuniao.txt <<'FIM'
Reunião pedagógica (fictícia)
1. Horário novo da biblioteca
2. Gincana de ciências
3. Recuperação do 8º ano
4. Uso dos notebooks da sala de informática
5. Datas das provas: a definir
FIM
pwd
ls
Você acabou de montar uma área de trabalho pequena e de abrir o agente exatamente dentro dela.
Cola da aula
A pasta certa
Sala da tarefauma pasta pequena, só com o material dela.
README e AGENTS.mdum para pessoas, outro para o agente.
Ordemcd, pwd, ls e só então codex.
Seu próximo passo
Você já sabe abrir o agente numa pasta escolhida por você, e não onde o terminal estava.
No terminal, dentro da pasta de treino, digite cat entradas/reuniao.txt e leia a pauta. São esses cinco itens que o Codex vai ler na próxima aula.
Na próxima aula: o primeiro pedido ao Codex. Ele vai ler a pasta e dizer o que falta, sem mudar nada.
Material complementar · Entre na pasta antes de pedirTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
A pasta de trabalho é a bancada da tarefa. Crie uma área pequena, com arquivos de treino, antes de permitir mudanças. Um README.md descreve a finalidade para pessoas; AGENTS.md dá instruções operacionais ao agente. Você não precisa abrir sua pasta pessoal inteira para experimentar.
Por que aprender
Um escopo pequeno reduz ambiguidade e facilita revisar diferenças. Quando algo sai errado, fica claro quais arquivos deveriam ter sido afetados.
Conceitos-chave
Escopo local; README; AGENTS; arquivos de entrada.
Na prática
O projeto possui README.md e entradas/reuniao.txt. A primeira tarefa é explicar esses dois arquivos. Não há necessidade de acesso a documentos pessoais nem a outros projetos.
✓ Faça
No Bash: mkdir -p ~/projetos/meu-primeiro-projeto. Entre com cd ~/projetos/meu-primeiro-projeto e inicie codex.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Aula 16 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 3 · Aula 5 de 6
Primeiro o agente lê, depois ele muda
Você consegue pedir ao Codex uma leitura da pasta sem nenhuma edição e conferir quais arquivos ele usou. Depois, você autoriza só a criação de um plano.md, que você mesma confere.
Um pedido como "arrume o projeto" mistura diagnóstico e mudança. Se algo sai errado, você não sabe em qual parte foi. Separar leitura e alteração dá uma referência para revisar.
Em 1 minuto
Primeiro pedido: ler e explicar, sem editar.
Peça que ele diga quais arquivos usou, e confira com o ls.
Depois, uma alteração pequena e com nome: só o plano.md.
1Vistoria antes da reforma
Ninguém sério começa uma reforma quebrando parede. Primeiro vem a vistoria: olhar, anotar, entender. Com um agente é a mesma ordem, em quatro passos.
Denise ia pedir ao Codex que "melhorasse a pasta da reunião". Trocou por dois pedidos: primeiro ler e dizer o que falta; depois, criar um arquivo só.
A ordem do primeiro trabalho
1 Inspecionar: ler e explicar, sem editar
2 Planejar: dizer o que falta
3 Alterar: um arquivo, com nome
4 Validar: você abre e confere
1Nenhum arquivo muda nessa etapa.
2A lista do que falta é a sua referência.
3Você diz qual arquivo pode ser criado.
4A última palavra é sua.
2O primeiro pedido só lê
Na pasta de treino da aula 16, peça ao Codex que leia o AGENTS.md e o README. Diga com todas as letras: sem editar. E peça que ele cite os arquivos que usou.
Lúcia fez esse pedido na pasta de treino. A resposta abaixo é real, do Codex, nessa mesma pasta, só encurtada.
Codex · meu-primeiro-projeto
VocêLeia AGENTS.md e README.md. Explique o propósito e liste o que falta, sem editar. Diga quais arquivos você usou.
CodexO propósito é preparar a pauta de uma reunião pedagógica usando entradas/reuniao.txt.
Falta: a pauta produzida, o formato e o local de saída, e como conferir o resultado.
O arquivo de entrada existe, mas não li seu conteúdo.
Arquivos lidos: AGENTS.md e README.md. Também consultei a listagem de arquivos. Nada foi editado.
Explicou, listou o que falta, disse o que leu e o que não leu. Nenhum arquivo mudou.
3Confira o que ele usou
A lista de arquivos usados mostra em que a resposta se apoia. Compare com o que o ls mostra na pasta.
Na resposta real, o Codex leu dois arquivos e avisou que não abriu a pauta. Então a lista do que falta vem só do README. É uma boa leitura, mas ainda não conhece os cinco itens da reunião.
Denise leu "não li seu conteúdo" e entendeu o limite da resposta. No segundo pedido, deixou claro que o plano devia se apoiar na pauta.
O que ele disse que leu
AGENTS.md
README.md
a lista de arquivos da pasta
O que existe na pasta
AGENTS.md
README.md
entradas/reuniao.txt, com os cinco itens
A diferença entre os dois cartões é exatamente o que a resposta ainda não sabe.
4Depois, uma alteração com nome
Agora autorize uma mudança pequena: criar só o plano.md, com três ações e uma verificação para cada. O Codex pode perguntar "Would you like to make the following edits?". Confira que a mudança é só no plano.md e escolha "Yes, proceed". Se for outro arquivo, escolha a opção que começa com "No". Ele criou sem perguntar? Também acontece: as permissões atuais deixam escrever na pasta. Confira com ls.
Depois, saia com /quit e leia o arquivo com cat plano.md, que mostra o conteúdo no terminal. Confira se as ações se apoiam no que existe na pasta.
O plano que Lúcia recebeu cobre os cinco itens da pauta e avisa que horários e datas ainda precisam ser definidos. Ela conferiu no reuniao.txt: tudo estava lá.
Terminal
$ cat plano.md
# Plano de ações
Base: entradas/reuniao.txt (reunião pedagógica fictícia).
Horários e datas ainda precisam ser definidos.
1. Ação: Organizar o novo horário da biblioteca e as regras
de uso dos notebooks da sala de informática.
Verificação: Conferir se a proposta registra o horário
da biblioteca e as condições de uso dos notebooks.
…
Arquivo real criado pelo Codex com o pedido 2 da prática, encurtado. Se você repetir, o texto sai diferente; o que se confere é se ele se apoia na pauta.
Você confere o plano contra a pauta, e não contra a sua memória.
Se travou aqui, é normalO plano citou um arquivo que não existe na pasta? Não recomece do zero. Peça a correção específica: "O arquivo tal não existe. Refaça o plano.md usando só os arquivos desta pasta."
Pratique agora 0/3
Faça a leitura, autorize o plano e confira
Pronto quando o plano.md existir na pasta e você tiver conferido uma das verificações direto no reuniao.txt. Cerca de 10 minutos, no computador.
O primeiro pedido não muda nada; o segundo cria um arquivo só, na pasta de treino. Não fez a aula 16? O bloco da prática dela monta a pasta em um minuto. Se o Codex quiser mexer em outro arquivo, recuse e repita o pedido.
Passo 1 · cole no terminal
cd ~/projetos/meu-primeiro-projeto
codex
Pedido 1 · cole dentro do Codex e tecle Enter
Leia AGENTS.md e README.md. Explique o propósito e liste o que falta, sem editar. Diga quais arquivos você usou.
Pedido 2 · cole dentro do Codex, só depois da resposta ao pedido 1
Crie somente plano.md, com três ações e uma verificação para cada. Apoie o plano em entradas/reuniao.txt. Não altere nenhum outro arquivo.
Passo 3 · cole no terminal, depois de sair com /quit
cat plano.md
cat entradas/reuniao.txt
Você acabou de separar diagnóstico e alteração, e de conferir o resultado no material real.
Cola da aula
Ler antes de mudar
Pedido 1ler e explicar, sem editar.
Arquivos usadoscompare com o ls.
Pedido 2um arquivo, com nome; você confere.
Seu próximo passo
Você já sabe conduzir o primeiro trabalho de um agente: ler, planejar, alterar pouco e conferir.
Hoje, leia o plano.md inteiro e marque a ação que você faria primeiro na reunião de verdade. Anote o motivo numa linha.
Na próxima aula: o agente escreveu um arquivo. E se tivesse escrito o errado? Você vai guardar um ponto de retorno antes de cada mudança.
Material complementar · Faça uma primeira tarefa de leituraTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Comece solicitando inspeção: listar estrutura, ler instruções e explicar pendências. Peça que o agente cite quais arquivos utilizou. Depois de conferir, autorize uma alteração pequena e nomeada, como criar plano.md com três próximos passos.
Por que aprender
Separar diagnóstico e alteração cria uma referência para a revisão. Você aprende o fluxo sem misturar instalação, grande refatoração e publicação numa única tentativa.
Conceitos-chave
Inspecionar; planejar; alterar; validar.
Na prática
Pedido inicial: “Leia AGENTS.md e README.md. Explique o propósito e liste o que falta, sem editar.” Segundo pedido: “Crie somente plano.md, com três ações e uma verificação para cada.”
Experimente agora
Abra plano.md no editor e confira se os passos se apoiam no projeto real. Peça correção específica se o agente pressupôs arquivos inexistentes.
Aula 17 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 3 · Aula 6 de 6
Permissão pequena e um ponto de retorno
Você consegue guardar uma cópia da pasta de treino e pedir ao Codex duas regras novas no AGENTS.md. Depois, você compara as duas versões e vê que só esse arquivo mudou.
Na aula passada, o agente criou um arquivo. Se tivesse criado o errado, ou apagado outro, você saberia dizer o que existia antes? Voltar atrás exige ter guardado o "antes" e comparar.
Em 1 minuto
Dê ao agente a menor permissão que dá conta da tarefa.
Regra escrita orienta; permissão do programa limita de fato.
Antes de mudar, guarde uma cópia. Depois, compare.
1A chave de uma sala, não a chave mestra
Quem vai usar o laboratório recebe a chave do laboratório, não o molho inteiro. Com um agente é igual: as permissões controlam o que ele alcança nos arquivos, na internet e nos comandos.
Suba um degrau por vez. Ler arquivos tem risco baixo; escrever, médio; executar comandos, alto. Cada degrau amplia o estrago possível.
Denise deu à estagiária só a chave da sala de leitura. Com o Codex, começou pelo mesmo princípio: acesso só à pasta de treino.
Degraus de permissão
1 Ler arquivos · risco baixo
2 Escrever arquivos · risco médio
3 Executar comandos · risco alto
1O pedido de leitura da aula 17 ficou aqui.
2Criar o plano.md subiu para cá.
3Só com um ponto de retorno guardado.
2Regra escrita orienta; permissão limita
O que você escreve no AGENTS.md orienta o comportamento do agente. Mas é texto: não impede nada tecnicamente. Quem impede são as permissões do programa.
No Codex, o comando /permissions mostra e troca o que ele pode fazer. Comece pelo mais restrito que dê conta da tarefa. Não tire todas as proteções para contornar um erro.
O Codex pediu à Lúcia acesso à internet para consultar uma documentação. Ela avaliou esse pedido sozinho, sem liberar também apagar arquivos ou enviar mensagens.
Regra no AGENTS.md
Exemplo: "Não envie nem publique nada."
O que faz: orienta o agente sobre o que você quer.
Permissão do programa
Exemplo: acesso só à pasta de treino.
O que faz: limita o que ele consegue fazer de fato.
Os dois são necessários e se completam. Um não substitui o outro.
3Guarde o "antes" com uma cópia
O comando cp -r copia uma pasta inteira, com tudo dentro. Faça a cópia antes da mudança, com um nome que diga o que ela é.
Mais adiante, no módulo 5, o Git faz isso de um jeito mais completo. Por enquanto, a cópia já dá um ponto de retorno.
Antes de autorizar a mudança no AGENTS.md, Denise copiou a pasta de treino com o final "-antes". O ls confirmou as duas.
Terminal
$ cp -r ~/projetos/meu-primeiro-projeto ~/projetos/meu-primeiro-projeto-antes
$ ls ~/projetos
meu-primeiro-projeto meu-primeiro-projeto-antes
O cp não responde nada quando dá certo. Quem confirma é o ls: as duas pastas lado a lado.
A pasta "-antes" não é tocada pelo agente: ela é o seu ponto de retorno.
4Compare: só mudou o que devia?
Depois da mudança, o diff compara a cópia com a pasta atual. Ele mostra só as diferenças, arquivo por arquivo. As linhas que começam com > são as novas.
Se aparecer outro arquivo na comparação, o agente mexeu onde não devia. A cópia "-antes" tem a versão antiga para você recuperar.
No diff de Lúcia apareceu um arquivo só, o AGENTS.md, com duas linhas novas. Era exatamente o que ela tinha autorizado.
Terminal
$ diff -r ~/projetos/meu-primeiro-projeto-antes ~/projetos/meu-primeiro-projeto
diff -r …/meu-primeiro-projeto-antes/AGENTS.md …/meu-primeiro-projeto/AGENTS.md
3a4,5
> - Todo resultado vem com a verificação que você observou.
> - Esta tarefa não autoriza publicar nada.
Um arquivo citado, duas linhas com >. "3a4,5" quer dizer: depois da linha 3, entraram as linhas 4 e 5.
Nada mais apareceu: o README, a pauta e o plano ficaram iguais.
Se travou aqui, é normalA saída do diff parece código, mas você só precisa de duas coisas: quais arquivos aparecem e quais linhas têm >. Não apareceu nada? Então nada mudou: veja se o Codex chegou a salvar o arquivo.
Como voltar um arquivo para a versão de antes
Só se o diff mostrou uma mudança que você não autorizou. Copie o arquivo da pasta "-antes" por cima do atual. Atenção: isso substitui o AGENTS.md atual pela versão antiga.
Depois, rode o diff de novo: sem diferença, a volta deu certo.
Pratique agora 0/3
Mude com ponto de retorno e compare
Pronto quando o diff mostrar só o AGENTS.md, com as duas linhas novas. Cerca de 10 minutos, no computador.
Tudo acontece na pasta de treino; a cópia "-antes" fica guardada ao lado. Não fez as aulas 16 e 17? O bloco da prática da aula 16 monta a pasta em um minuto. Se o diff mostrar outro arquivo, não apague nada: anote o que mudou e recupere pela cópia.
Passo 1 · cole no terminal, uma vez só
cp -r ~/projetos/meu-primeiro-projeto ~/projetos/meu-primeiro-projeto-antes
ls ~/projetos
Passo 2 · cole no terminal
cd ~/projetos/meu-primeiro-projeto
codex
Passo 3 · cole dentro do Codex e tecle Enter
Acrescente ao AGENTS.md estas duas linhas, sem mudar as que já existem:
- Todo resultado vem com a verificação que você observou.
- Esta tarefa não autoriza publicar nada.
Não altere nenhum outro arquivo.
Passo 4 · cole no terminal, depois de sair com /quit
Você acabou de fazer uma alteração verificável: sabe o que existia antes, o que mudou e como voltar.
Cola da aula
Mudar com segurança
Permissão mínimaler, escrever, executar: um degrau por vez.
Regra e permissãouma orienta, a outra limita.
Antes e depoiscópia com cp -r, comparação com diff -r.
Seu próximo passo
Você fechou o módulo 3: abre o terminal, põe o Codex no computador, entra com a conta, trabalha na pasta certa e confere cada mudança.
Quando tiver uns 30 minutos, abra o material complementar desta aula e faça o laboratório do módulo, "Primeiro projeto acompanhado". Você já fez quase tudo; ele junta os passos.
No próximo módulo: a casa digital do projeto, com pastas, arquivos de instrução e um lugar separado para as senhas.
Material complementar · Use permissões e recuperaçãoTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
As permissões do cliente controlam acesso a arquivos, rede e execução. Instruções em linguagem natural orientam o comportamento, mas não substituem isolamento técnico. Comece com permissões restritas à pasta de treino. Não ensine a remover todas as proteções para contornar qualquer erro.
Por que aprender
Recuperar uma alteração exige saber o que existia antes. Git e cópias de arquivos oferecem pontos de retorno; eles serão praticados adiante. Leia o que o comando fará antes de ampliar permissões.
Conceitos-chave
Permissão mínima; alterações pequenas; comparação; ponto de retorno.
Na prática
O agente pede acesso externo para consultar a documentação. Avalie essa necessidade separadamente de permissões para apagar arquivos ou enviar mensagens.
Experimente agora
Escreva no AGENTS.md que resultados devem vir com verificação observada e que a tarefa não autoriza publicar. Revise o diff quando Git estiver ativo.
Ler arquivos
Escrever arquivos
Executar comandos
Suba um degrau por vez. Cada nível amplia o estrago possível e exige um ponto de recuperação.
Laboratório do módulo: Primeiro projeto acompanhado
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Prepare a pasta meu-primeiro-projeto e um README.md sem informações privadas.
Confira a instalação e a autenticação conforme os comandos desta aula.
Inicie Codex nessa pasta e peça uma análise sem alterações.
Autorize criar plano.md, leia o arquivo e confira se respeita o README.
Bash · Linux ou macOS
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
mkdir -p ~/projetos/meu-primeiro-projeto
cd ~/projetos/meu-primeiro-projeto
pwd
codex --version
codex login
codex login status
codex
Critério de pronto
Abrir um projeto de treino no Codex e produzir uma alteração verificável. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
Codex não encontrou README.md. O primeiro passo é aumentar o raciocínio?
Ver resposta comentada
Não. Confira o diretório atual, o nome do arquivo e a permissão de leitura.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Resumo do módulo
Terminal; shell; pasta atual; comando e resposta.
Fonte oficial; instalação; versão; diagnóstico.
codex login; codex login status; entrada padrão; conta ativa.
Escopo local; README; AGENTS; arquivos de entrada.
Inspecionar; planejar; alterar; validar.
Permissão mínima; alterações pequenas; comparação; ponto de retorno.
Consulte a fonte
Ferramentas verificadas em 20/09/2026; nomes de telas e disponibilidade podem mudar.
Você consegue desenhar a árvore da sua pasta de projetos, com config e um projeto de treino. E consegue criá-la com um comando no terminal.
Quando tudo fica numa pasta só, a IA lê material de assuntos que não têm nada a ver com o pedido. Depois fica difícil dizer de onde veio uma conclusão. Hoje você separa os assuntos antes de criar qualquer arquivo.
Em 1 minuto
Uma pasta, um assunto de trabalho, com nome claro.
A pasta config guarda o que vale para todos os projetos.
Dentro do projeto, entradas separadas das saídas.
1A pasta diz à IA onde o assunto começa e termina
No arquivo de aço da secretaria, cada gaveta guarda uma turma. Ninguém procura o 8º A na gaveta do 7º B. Uma pasta de trabalho faz o mesmo: ela reúne o material de um assunto só. Esse material é o contexto da tarefa.
Quando você abre o Codex numa pasta, ele trabalha a partir dela. Se a pasta mistura assuntos, o que não tem relação com o pedido vira ruído.
Lúcia guardava o projeto da feira de ciências na mesma pasta dos boletins. Pediu à IA um resumo da feira e recebeu um parágrafo com a nota de um aluno no meio.
Tudo junto
Pasta Documentos: feira-de-ciencias.docx, boletins-8A.xlsx, ata-do-conselho.pdf.
Resultado: o resumo da feira cita uma nota de boletim.
Uma pasta por contexto
Pasta feira-de-ciencias: só o regulamento e a lista de grupos.
Resultado: o resumo fala só da feira.
Saldo: a IA lê menos material, e você sabe de onde veio cada frase.
2O til é o apelido da sua pasta pessoal
No terminal, o símbolo ~ (til) representa a sua pasta pessoal. Dentro dela você vai criar uma pasta projetos, que reúne trabalhos independentes.
O caminho ~/projetos/config se lê em ordem: pasta pessoal, depois projetos, depois config. No teclado brasileiro, o til sai com a tecla do til seguida da barra de espaço.
Denise digitou pwd no terminal, como no módulo 3, e viu o endereço completo da pasta pessoal dela. O ~ é só o jeito curto de escrever esse endereço.
Terminal
$ cd ~
$ pwd
/Users/denise
cd ~ leva você para a pasta pessoal; pwd mostra onde você está. No Linux, e no Windows com o terminal do módulo 3, o endereço começa com /home, como /home/denise.
O endereço muda de computador para computador. O ~ vale em todos.
3O que vale para todos fica em config, fora dos projetos
A pasta config, de configuração, guarda o conhecimento que vale para qualquer projeto, como as suas preferências. Ela fica dentro de projetos, mas fora de cada projeto.
Cada projeto guarda as próprias entradas, o material que a IA lê, como atas ou planilhas. E guarda as próprias saídas, o que ela produz. Separadas, dá para conferir uma contra a outra. Não misture num projeto documentos de turmas ou escolas diferentes.
Denise prefere relatórios curtos, com as pendências no fim. Isso vale para o relatório do conselho e para a pauta da reunião de pais. Então vai para config, uma vez só.
~/projetos
1 config
memoria.md · decisoes.md (aula 3 deste módulo)
2 meu-primeiro-projeto
3 entradas
4 saidas
1Vale para todos os projetos.
2Um contexto: o projeto de treino.
3O que a IA lê.
4O que a IA produz, para você revisar.
Teste-se
Denise quer guardar a nota "prefiro relatórios curtos". Onde ela mora?
4Desenhe a árvore antes de criar as pastas
Antes de criar, desenhe a árvore no papel: uma pasta config e um único projeto de treino. Assim você decide os nomes com calma.
Use nomes curtos, sem espaço e sem acento, como meu-primeiro-projeto e saidas. No terminal, espaço e acento dão trabalho em cada comando.
Lúcia desenhou num guardanapo: projetos, com config e feira-de-ciencias; dentro da feira, entradas e saidas. Levou um minuto e evitou três pastas com nomes parecidos.
mkdir -p cria as pastas e as de cima que faltarem. Se uma pasta já existe, ela fica como está.
Um comando cria a árvore inteira. O ls confere o resultado.
Se travou aqui, é normalO comando é comprido porque cria quatro pastas de uma vez. Copie e cole do jeito que está, numa linha só. Para colar no terminal, use o botão direito › Colar; no teclado, Ctrl+Shift+V no Linux e no Windows, Cmd+V no Mac. Prefere o mouse? Digite cd ~ e depois open . no Mac, ou explorer.exe . no Windows, dentro do terminal Linux do módulo 3: o gerenciador de arquivos abre na sua pasta pessoal do terminal. Crie ali as pastas, com botão direito › Nova pasta.
Pratique agora 0/3
Crie a árvore do projeto de treino
Pronto quando o primeiro ls mostrar config e meu-primeiro-projeto, e o segundo mostrar entradas e saidas. Cerca de 8 minutos, no computador.
Os comandos só criam pastas vazias dentro da sua pasta pessoal; nada é apagado. Criou meu-primeiro-projeto no módulo 3? Tudo bem, o que já está lá continua. Apareceu uma mensagem de erro? Pare, confira se colou a linha inteira e tente de novo uma vez.
mkdir -p ~/projetos/config ~/projetos/meu-primeiro-projeto/entradas ~/projetos/meu-primeiro-projeto/saidas
ls ~/projetos
ls ~/projetos/meu-primeiro-projeto
O que você deve ver
config meu-primeiro-projeto
entradas saidas
A primeira linha responde ao ls de projetos; a segunda, ao ls do projeto de treino.
Você acabou de criar, com um comando, a árvore que separa o que vale sempre do que é de um projeto só.
Cola da aula
Pastas por contexto
Uma pasta, um assuntoa IA lê só o que pertence a ele.
config fora do projetoo que vale para todos, num lugar só.
entradas e saidaso que a IA lê, separado do que ela produz.
Seu próximo passo
Você já tem a casa digital de pé: uma pasta para o que vale sempre e uma para o projeto de treino.
Hoje, abra a sua pasta Documentos e anote dois assuntos que estão misturados nela. Não mova nada ainda; só anote.
Na próxima aula: a pasta existe, mas quem chegar depois não sabe para que ela serve. Você vai escrever o README dela, em texto simples.
Material complementar · Uma pasta representa um contextoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
O símbolo ~ representa a pasta pessoal no Bash. Dentro dela, projetos reúne trabalhos independentes. Use nomes claros e evite misturar documentos de clientes diferentes. A pasta config guarda conhecimento transversal; cada projeto mantém suas próprias entradas e resultados.
Por que aprender
Contextos separados ajudam a limitar o que a IA precisa ler. Uma pasta cheia de assuntos não relacionados aumenta ruído e torna difícil explicar de onde veio uma conclusão.
Conceitos-chave
Pasta pessoal; projetos; contexto; entradas e saídas.
Na prática
Em ~/projetos/website ficam os arquivos do site. Em ~/projetos/estudos ficam experimentos. No Windows, o gerenciador pode mostrar caminhos como C:\Users\SeuNome\projetos.
✓ Faça
Desenhe a árvore antes de criar arquivos. Escolha um único projeto de treino e uma única pasta global config.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
~/projetos/
config/
memoria.md
decisoes.md
meu-projeto/
AGENTS.md
entradas/
saidas/
Uma pasta por contexto. As configurações ficam fora do projeto; entradas e saídas ficam separadas.
Aula 19 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 4 · Aula 2 de 6
Markdown é texto organizado
Você consegue escrever o README do projeto de treino em Markdown. Cada campo fica com informação real ou com "a definir".
Uma explicação que só existe numa conversa some quando a conversa acaba. Quem chega depois não sabe para que a pasta serve. Um arquivo pequeno de texto resolve e dura.
Em 1 minuto
# faz título, ## faz subtítulo, - faz item de lista.
O arquivo termina em .md e abre em qualquer editor de texto.
O README diz para que serve o projeto e como conferir o resultado.
1Markdown é texto com três marcas simples
Todo roteiro de experimento de Lúcia tem título, materiais e procedimento. Ela sublinha os títulos e põe um traço antes de cada material. Markdown faz o mesmo com sinais que você digita.
O # no começo da linha cria um título, o ## cria um subtítulo e o hífen cria um item de lista. O arquivo continua sendo texto: dá para ler mesmo sem um programa especial.
Lúcia passou o roteiro "Germinação do feijão" para Markdown em cinco minutos. Não aprendeu nada além dessas três marcas.
No arquivo
# Germinação do feijão
## Materiais
- 10 grãos de feijão
- algodão e um copo
Como se lê
Título: Germinação do feijão.
Subtítulo: Materiais.
Lista: dois itens, um por linha.
As marcas ficam no texto. Quem lê entende a estrutura mesmo sem ver formatação.
2O nome termina em .md e abre em qualquer editor
Um arquivo Markdown é um arquivo de texto cujo nome termina em .md, como README.md. Ele abre no editor de texto do computador e também no terminal.
No terminal, o nano abre o arquivo para editar ali mesmo. Depois, o comando cat mostra o conteúdo na tela, para você conferir.
Denise abriu o README do projeto do conselho com o nano. Trocou uma linha, gravou com Ctrl+O, confirmou o nome com Enter e saiu com Ctrl+X. Depois conferiu com cat.
Terminal · dentro do nano
GNU nano README.md
# Meu primeiro projeto OSWork
## Propósito
Produzir relatórios de treino a partir de dados fictícios.
^G Help ^O Write Out ^W Where Is ^X Exit
É assim que o nano aparece: o texto no meio e os atalhos no rodapé, em inglês. O ^ quer dizer Ctrl. Write Out é gravar; Exit é sair. Depois do Ctrl+O, ele mostra o nome do arquivo embaixo: aperte Enter.
Não há menu de mouse: você anda com as setas e digita direto. Ao sair, cat README.md mostra o que ficou gravado.
3O README explica o projeto para quem chega depois
O modelo do kit do curso traz cinco seções: Propósito, Leia primeiro, Organização, Como verificar e Estado atual. Você troca cada texto do modelo pelo que vale no seu projeto.
Ainda não sabe um campo? Escreva "a definir". Um campo honesto em aberto é melhor que um texto do modelo que ninguém conferiu.
No README da feira de ciências, Lúcia escreveu em Propósito: "organizar as inscrições da feira". Em Como verificar: "todo grupo inscrito aparece na lista final".
README.md
1 # Feira de ciências 2026
2 ## Propósito
Organizar as inscrições da feira.
## Leia primeiro
A definir.
## Organização
- entradas: fichas de inscrição
- saidas: lista final
3 ## Como verificar
Todo grupo inscrito aparece na lista final.
4 ## Estado atual
A definir.
1Um título com o nome do projeto.
2Para que o projeto existe, em uma frase.
3Como alguém confere se o resultado está certo.
4O que ainda não se sabe fica escrito como "a definir". O Leia primeiro será completado na aula 6 deste módulo.
4Clareza vale mais que formatação
Arquivos pequenos e com nome claro duram mais que uma conversa perdida. Pessoas podem revisá-los, e agentes podem consultá-los.
O valor vem da clareza. As três marcas bastam. Negrito, tabela e link são opcionais.
Denise tirou uma semana de licença. A colega que ficou no lugar abriu o README do projeto do conselho e continuou o trabalho sem precisar ligar para ela.
Só na conversa
Onde está: numa conversa de março com a IA.
Resultado: a colega não acha e liga para Denise.
No README
Onde está: README.md, na pasta do projeto.
Resultado: a colega lê o arquivo e segue.
Saldo: a explicação passa a morar na pasta, e não na memória de alguém.
Se travou aqui, é normalO nano estranha na primeira vez: não há menu com mouse. Prefere outro caminho? Na pasta do projeto, digite open -e README.md no Mac, ou explorer.exe . no Windows, dentro do terminal Linux do módulo 3, e abra o README.md com o Bloco de Notas. Ao salvar, em Tipo, escolha Todos os arquivos, para ele não virar README.md.txt.
Pratique agora 0/3
Escreva o README do projeto de treino
Pronto quando o cat mostrar os títulos com # e você tiver lido cada seção e deixado nela texto seu ou "a definir". Cerca de 10 minutos, no computador.
O modelo é um arquivo de texto do kit do curso, sem dado de ninguém. Atenção: a segunda linha substitui um README.md que já exista nessa pasta. Já escreveu um? Pule essa linha. Não fez a aula anterior? Rode antes: mkdir -p ~/projetos/meu-primeiro-projeto
cd ~/projetos/meu-primeiro-projeto
curl -fsSL https://inematds.github.io/oswork/materiais/README-projeto.md -o README.md
nano README.md
O que você deve ver (começo)
$ cat README.md
# Meu primeiro projeto OSWork
## Propósito
A definir.
## Leia primeiro
A definir.
O título pode ficar como no modelo. O texto das seções é o seu; confira os títulos com # e nenhuma seção vazia. Se o terminal responder que não conhece o nano, use o Bloco de Notas, como diz o quadro "Se travou aqui", no fim do passo 4 da aula.
Você acabou de escrever, em Markdown, a explicação do projeto que fica na pasta, e não numa conversa.
Cola da aula
Markdown e README
# ## -título, subtítulo e item de lista. Nada mais é obrigatório.
.mdcontinua sendo texto; abre no nano ou em qualquer editor.
READMEpropósito e verificação; o que falta vira "a definir".
Seu próximo passo
Você já sabe registrar, num arquivo que dura, para que um projeto serve e como conferir o resultado.
Hoje, escolha um trabalho real seu e escreva só a seção Propósito dele, em uma frase, num bloco de notas.
Na próxima aula: o README fala de um projeto. E o que vale para todos, como suas preferências e decisões? Você vai dar um arquivo para cada tipo de nota.
Material complementar · Markdown é texto organizadoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Markdown usa sinais simples para organizar texto: # cria título, ## cria subtítulo e um hífen inicia item de lista. O arquivo continua sendo texto, legível mesmo sem um editor especial. O nome termina em .md. Você não precisa escrever código para registrar instruções claras.
Por que aprender
Arquivos pequenos, nomeados e fáceis de editar duram mais que uma conversa perdida. Eles podem ser revisados por pessoas e consultados por agentes. O valor vem da clareza, não de uma formatação elaborada.
Conceitos-chave
Título; lista; bloco de código; link; texto simples.
Na prática
Um README pode conter: propósito, arquivos de entrada, resultado esperado e como verificar. Quem chegar depois entende a tarefa sem depender da conversa original.
Experimente agora
Abra materiais/README-projeto.md. Copie o modelo para seu projeto e substitua cada campo por informação real ou “a definir”.
Aula 20 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 4 · Aula 3 de 6
Cada arquivo tem um trabalho
Você consegue pôr na pasta config os quatro arquivos de memória do kit. E consegue dizer em qual deles cada nota mora.
Um documento gigante com tudo vira uma pilha que ninguém consulta. Pior: uma regra antiga convive com a nova, e a IA não sabe qual vale. Um arquivo por função resolve.
Em 1 minuto
Jeito seu que não muda vai para memoria.md.
Escolha com data e motivo vai para decisoes.md.
Como se faz vai para dicas.md; o que deu errado, para falhas.md.
1Cada livro da secretaria responde a uma pergunta
A secretaria da escola não anota tudo num caderno só. Tem o livro de atas, o livro de ocorrências e o caderno de procedimentos. Cada um responde a uma pergunta diferente.
Na pasta config, quatro arquivos fazem esse papel. Separados, você consulta só o que precisa, e a IA também.
Denise procurava por que a reunião de pais tinha mudado para sábado. O motivo estava num caderno de 40 páginas, entre recados e telefones. Levou meia hora para achar.
~/projetos/config
1 memoria.md
2 decisoes.md
3 dicas.md
4 falhas.md
1Como eu prefiro que o trabalho saia?
2O que escolhemos, quando e por quê?
3Como se faz, passo a passo, do jeito que já deu certo?
4O que deu errado e qual foi a correção?
2Preferência e decisão moram em arquivos diferentes
Preferência é o seu jeito estável de trabalhar, como "prefiro relatórios curtos". Ela vai em memoria.md.
Decisão é uma escolha com motivo, e o motivo pode mudar. "Escolhemos planilha porque a equipe inteira usa a mesma" é decisão. Ela vai em decisoes.md, com data.
Lúcia prefere exercícios com gabarito no fim: isso é memória. Já "as provas do 8º ano têm 10 questões, porque a coordenação padronizou" é decisão.
Preferência · memoria.md
"Prefiro exercícios com gabarito no fim."
Muda? Quase nunca. Não precisa de motivo.
Decisão · decisoes.md
"Provas do 8º ano com 10 questões, porque a coordenação padronizou."
Muda? Pode mudar; por isso leva data e motivo.
As duas notas estão certas. Só moram em arquivos diferentes.
3Falha se consulta quando volta, e não se cola em todo pedido
O falhas.md registra um problema, a causa e a menor correção, isto é, a proteção pequena que evita a repetição. Serve para consultar quando o problema voltar. O dicas.md guarda procedimentos que já funcionaram.
Colar o falhas.md inteiro em todo pedido, "por garantia", enche a conversa de avisos que não têm a ver com a tarefa. Você o abre quando o problema aparece de novo.
O resumo das atas saiu vazio numa segunda-feira. A pasta de entradas estava vazia. Denise anotou em falhas.md e passou a conferir a pasta antes de pedir.
falhas.md
1 Sintoma: o resumo das atas saiu vazio
2 Causa observada: a pasta entradas estava vazia
3 Menor correção: conferir se há arquivos antes de pedir
1O que você viu acontecer.
2O porquê, confirmado, e não o palpite.
3A proteção pequena que evita a repetição.
4Decisão mudou? Anote a nova com data e motivo
Quando uma decisão muda, não troque a linha antiga em silêncio. Escreva a nova com data e motivo, e marque a antiga como substituída.
Assim nunca ficam duas regras contraditórias valendo ao mesmo tempo. E quem lê entende o caminho que a decisão fez.
Em outubro, as provas de Lúcia passaram para 12 questões, com duas de leitura de gráfico. Ela acrescentou a linha nova e marcou a de agosto como substituída.
decisoes.md
| Data | Decisão | Motivo | Revisar quando |
| 08/2026 | Provas com 10 questões (substituída em 10/2026) | padrão da coordenação | a coordenação mudar o padrão |
| 10/2026 | Provas com 12 questões | duas de leitura de gráfico | fim do ano |
É o formato do decisoes.md do kit: uma linha por decisão, colunas separadas por |. A linha antiga fica, marcada; a nova diz quando e por quê.
Teste-se
"O resumo parou no meio porque o arquivo era enorme; dividir em partes resolveu." Onde essa nota mora?
Se travou aqui, é normalÀs vezes uma nota parece caber em dois arquivos. Pergunte: ela diz como eu gosto, o que escolhemos, como se faz ou o que deu errado? A primeira resposta que servir decide.
Pratique agora 0/3
Monte a pasta config e distribua cinco notas
Pronto quando o ls mostrar os quatro arquivos e você tiver escrito, no papel, o arquivo de cada uma das cinco notas. Cerca de 10 minutos, no computador, no terminal do módulo 3.
Os modelos são arquivos de texto do kit do curso, e as notas são fictícias. Se você já escreveu num desses quatro arquivos, pule a linha dele: o curl grava por cima de um arquivo com o mesmo nome. Uma linha falhou? O curl mostra uma mensagem de erro logo abaixo dela; rode só aquela de novo. Não fez a aula 1 deste módulo? Rode antes: mkdir -p ~/projetos/config
As cinco notas (fictícias): 1) "Prefiro avisos às famílias em até cinco linhas." 2) "Boletim vai em PDF desde setembro, porque nem todas as famílias abrem planilha." 3) "Para juntar as atas do mês: peça primeiro a lista dos arquivos lidos, depois o resumo." 4) "O resumo da reunião trouxe uma data que não estava na ata; a correção foi pedir à IA que deixe um espaço em branco quando a data faltar." 5) "Relatórios sempre com as pendências no fim."
Ver o gabarito
1 e 5: memoria.md, porque são o seu jeito estável e não têm motivo que mude. 2: decisoes.md, porque é uma escolha com data e motivo. 3: dicas.md, porque é um procedimento que já deu certo. 4: falhas.md, porque tem sintoma, causa e correção. Quer ir além? Abra memoria.md com nano e escreva uma preferência real sua.
Você acabou de montar a pasta config e de dar a cada nota o seu lugar.
Cola da aula
Um arquivo, uma função
memoria e decisoesjeito estável num; escolha com data e motivo no outro.
dicas e falhascomo se faz num; sintoma, causa e correção no outro.
Mudou?linha nova com data; a antiga fica marcada.
Seu próximo passo
Você já sabe separar preferência, decisão, procedimento e falha, cada uma no seu arquivo.
Hoje, abra o arquivo com nano ~/projetos/config/decisoes.md e acrescente uma decisão real da sua equipe no fim da tabela, copiando o formato das linhas da Lúcia no passo 4.
Na próxima aula: e a senha do sistema da escola, vai em qual desses arquivos? Em nenhum. Você vai ver onde ela fica.
Material complementar · Cada arquivo tem um trabalhoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
memoria.md registra preferências estáveis; decisoes.md explica escolhas; dicas.md guarda procedimentos úteis; falhas.md documenta problemas e correções. Não coloque tudo em um documento gigante. Quando uma decisão muda, registre data e motivo para não manter regras contraditórias.
Por que aprender
Separar funções facilita consultar só o necessário. Um histórico de falhas não deveria virar uma lista de comandos obrigatórios em toda tarefa. Conhecimento consultável e instruções permanentes são coisas diferentes.
“Prefiro relatórios curtos” é preferência. “Escolhemos CSV por ser compatível com a planilha da equipe” é decisão. “O serviço parou sem supervisão” pertence às falhas.
Sequência para experimentar
Prepare uma cópia de treino.
Distribua cinco notas fictícias entre os quatro arquivos. Para cada uma, explique por que aquele é o lugar adequado.
Registre o resultado observado e a próxima correção.
Aula 21 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 4 · Aula 4 de 6
Segredo não é conhecimento para compartilhar
Você consegue criar o .env.example do projeto de treino, com os nomes das variáveis e valores fictícios. Nenhum valor real entra nele.
Uma senha colada num documento, num print ou num pedido vira acesso para quem ler. E ela continua valendo depois que a conversa acaba. Separar o segredo do resto deixa você compartilhar a pasta sem medo.
Em 1 minuto
O .env guarda as chaves de verdade, só no seu computador.
Ele não é um cofre: quem abre o arquivo, lê.
O .env.example tem só os nomes, com valores de mentira. Esse pode circular.
1Quem tem a credencial age em nome da conta
Na portaria da escola, o quadro de chaves mostra quais salas existem. Ninguém se preocupa com essa lista à vista. Com as chaves é diferente: quem pega a chave abre a sala.
Uma credencial funciona como a chave. Uma senha, uma chave de API ou o token do bot deixam quem os tem agir em nome da sua conta.
Denise ia mandar no grupo da equipe um print da configuração do sistema de notas. Antes de enviar, viu a senha da coordenação inteira no canto da imagem.
Print como estava
O que mostra: a tela de configuração, com a senha visível.
Resultado: as 30 pessoas do grupo passam a ter o acesso.
Print corrigido
O que mostra: a mesma tela, com a senha coberta antes de enviar.
Resultado: a equipe vê o que precisa, e o acesso continua só com a coordenação.
A imagem ajuda do mesmo jeito sem o valor da senha.
2O .env guarda variáveis, mas não é um cofre
O arquivo .env guarda variáveis: um nome, um sinal de igual e um valor. Por exemplo, TELEGRAM_BOT_TOKEN ou DATABASE_URL, o endereço de um banco de dados, com a senha dentro.
Ele não é criptografado. Qualquer pessoa com acesso ao arquivo consegue ler o que está nele. Por isso ele fica só na sua máquina. No módulo 7, o comando chmod deixa a leitura só para você.
No módulo 7, Lúcia vai criar um bot de consulta para a turma. O token dele vai morar no .env da pasta do projeto, e em nenhum outro lugar.
.env · só no seu computador
1 TELEGRAM_BOT_TOKEN = ●●●●●●●●●●
2 DATABASE_URL = ●●●●●●●●●●
1O nome diz o que é; o programa procura o valor por ele.
2O valor real, aqui coberto, nunca aparece num print.
3O .env.example mostra a estrutura sem dar acesso
O .env.example tem os mesmos nomes, com valores fictícios. Quem recebe o projeto vê o que precisa preencher, mas não ganha acesso a nada.
O kit do curso traz TELEGRAM_BOT_TOKEN=preencha_localmente. Você troca o valor só na sua cópia privada, o .env. Com o valor de exemplo, nenhum bot funciona.
Denise passou o projeto de relatórios para a vice-diretora com o .env.example. A vice preencheu o próprio .env com a senha que recebeu da secretaria.
.env.example · pode circular
TELEGRAM_BOT_TOKEN=preencha_localmente
DATABASE_URL=preencha_localmente
.env · fica na sua máquina
TELEGRAM_BOT_TOKEN=[o token real]
DATABASE_URL=[o endereço real]
Os mesmos nomes nos dois. Só o .env tem valores que abrem alguma coisa.
Se travou aqui, é normalOs dois nomes parecem gêmeos. Lembre assim: o que termina em example é o exemplo, que pode circular. O outro é o de verdade, que fica em casa.
4A IA precisa do nome da variável, e não do valor
Valor real não vai em print, em exemplo de curso nem em arquivo enviado à IA sem necessidade. Para ajudar, a IA quase sempre precisa só saber que a variável existe.
Colou uma chave por engano? Apagar a mensagem não basta. Troque a chave no site que a gerou, na área de segurança ou de chaves da conta. Se você nunca gerou uma chave, guarde a regra para quando gerar.
O relatório de Lúcia não conectava à planilha da escola. Em vez de colar o .env, ela contou à IA quais variáveis estavam preenchidas.
Chat de IA
VocêO relatório não conecta. Meu .env:
DATABASE_URL=[endereço real com a senha dentro]
IAVamos ver. Vou usar esse endereço para testar a conexão…
A senha agora está no histórico da conversa.
VocêO relatório não conecta. No meu .env, DATABASE_URL está preenchida. O que confiro, sem te mandar o valor?
IAConfira se o endereço está completo e se a senha dentro dele ainda vale. Não precisa me mandar o valor.
A ajuda é a mesma, e o segredo ficou em casa.
Toque nos dois botões e compare o que fica na conversa.
Teste-se
Uma colega vai testar o seu projeto no computador dela. O que você manda?
Pratique agora 0/3
Crie o .env.example do projeto de treino
Pronto quando o cat mostrar os dois nomes com o valor preencha_localmente e o ls -a listar o .env.example. Cerca de 8 minutos, no computador, no terminal.
Os valores são de mentira; nenhum acesso real entra no arquivo. Nunca troque preencha_localmente por um valor real no .env.example. Não crie o .env agora: ele só será preciso no módulo 7. Não fez a aula 1 deste módulo? Rode antes: mkdir -p ~/projetos/meu-primeiro-projeto
cd ~/projetos/meu-primeiro-projeto
printf '%s\n' 'TELEGRAM_BOT_TOKEN=preencha_localmente' 'DATABASE_URL=preencha_localmente' > .env.example
cat .env.example
ls -a
As duas primeiras linhas vêm do cat; a última, do ls -a. A ordem pode variar, e pode haver outros arquivos seus.
Você acabou de criar o modelo que mostra o que preencher sem entregar nenhuma chave.
Cola da aula
Segredo fica em casa
.envvalores reais, só na sua máquina; não é cofre.
.env.examplemesmos nomes, valores de mentira; pode circular.
Vazou?troque a chave na origem; apagar a mensagem não basta.
Seu próximo passo
Você já sabe compartilhar a estrutura de um projeto sem entregar o acesso a ele.
Hoje, procure nos seus documentos e conversas uma senha colada. Achou? Apague de lá e troque a senha no site de origem.
Na próxima aula: como garantir que o .env nunca seja guardado junto com o histórico do projeto, nem por descuido.
Material complementar · Segredos não são conhecimento compartilhávelTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Um arquivo .env pode guardar variáveis como TELEGRAM_BOT_TOKEN ou DATABASE_URL. Ele não é criptografado: qualquer pessoa com acesso ao arquivo pode lê-lo. Use permissões adequadas e nunca inclua valores reais em screenshots, exemplos de curso ou arquivos enviados à IA sem necessidade.
Por que aprender
Credenciais permitem agir em nome de uma conta. Separar o modelo .env.example, sem valores reais, do .env local permite compartilhar a estrutura sem distribuir acesso.
Conceitos-chave
Variável; segredo; .env.example; leitura em tempo de execução.
Na prática
O kit inclui TELEGRAM_BOT_TOKEN=preencha_localmente. O aluno substitui isso apenas em sua cópia privada. Nenhum bot fica autenticado com esse exemplo.
✓ Faça
Crie .env.example com nomes das variáveis e valores fictícios. Mantenha .env fora do repositório e nunca cole sua chave no chat.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Versiona — README, AGENTS, código
Não versiona — .env, tokens, senhas
.gitignore separa os dois
O .gitignore é a fronteira entre o que a equipe lê e o que nunca sai da sua máquina.
Aula 22 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 4 · Aula 5 de 6
Ignore antes do primeiro commit
Você consegue criar o .gitignore antes do primeiro commit. E consegue apontar a linha que deixa o .env de fora e a que mantém o .env.example.
No módulo 6, o Git vai guardar versões da sua pasta. O que entra numa versão fica no histórico. Por isso a lista do que nunca entra vem antes da primeira versão.
Em 1 minuto
O .gitignore é a lista do que o Git não guarda.
Ele só vale para o que o Git ainda não guardou.
Chave vazou? Troque na origem primeiro; apagar a linha não desfaz.
1O .gitignore separa o que a equipe lê do que fica em casa
Cada versão salva pelo Git se chama commit. O .gitignore é um arquivo de texto, na pasta do projeto, com a lista do que o Git deve deixar de fora.
Entram nessa lista o .env, as variantes privadas dele e as pastas temporárias que os programas criam sozinhos.
No projeto de relatórios, Denise pôs o .env na lista antes de salvar a primeira versão. O arquivo com a senha do sistema de notas nunca entrou no histórico.
Entra no histórico
README.md, .env.example e os demais arquivos do trabalho.
Fica de fora
.env, chaves, senhas e pastas temporárias.
Quem decide: o .gitignore, escrito antes da primeira versão.
2Cada linha do .gitignore é um padrão
A linha .env pega o arquivo .env. A linha .env.* pega variantes como .env.local: o asterisco vale por qualquer final. A linha que começa com ! abre uma exceção.
Assim, !.env.example devolve o exemplo à lista do que é guardado. As últimas linhas cobrem pastas e arquivos temporários que alguns programas criam sozinhos. Você não precisa mexer nelas.
Lúcia estranhou a exclamação na terceira linha do arquivo do kit. Era ela que mantinha o .env.example no projeto, para a colega de matemática saber o que preencher.
.gitignore (começo do modelo do kit)
1 .env
2 .env.*
3 !.env.example
4 __pycache__/
1Deixa de fora o arquivo com os valores reais.
2Deixa de fora qualquer variante, como .env.local.
3A exclamação traz o exemplo de volta: ele é guardado.
4Pasta temporária que um programa cria sozinho. Você não precisa mexer nela.
3Ignorar só vale para o que ainda não foi guardado
O .gitignore não vale para um arquivo que já foi guardado, o arquivo rastreado. Se o .env já entrou num commit, a linha escrita depois não o tira do histórico.
É como o malote da secretaria: o papel que não deve ir sai da pilha antes de fechar. Depois que o malote partiu, riscar o papel da lista não o traz de volta.
Um colega de Denise pôs o .env no .gitignore uma semana depois da primeira versão. O arquivo com a senha continuava lá, na versão antiga.
Histórico do projeto do colega
1 Versão de segunda-feira
README.md · .env (com a senha)
2 Versão da segunda-feira seguinte
.gitignore com a linha .env
1O .env entrou nesta versão e continua dentro dela.
2A linha nova vale daqui para a frente; a versão 1 não muda.
4Vazou? Troque a chave antes de limpar o arquivo
Se uma chave foi publicada, a primeira correção é revogar a chave na origem, ou seja, cancelá-la no site que a criou. Isso fica na área de chaves ou de segurança da conta, como a página de chaves da plataforma da API. Apagar a linha do arquivo não invalida uma cópia que alguém já viu.
Só depois vem o conserto do histórico, conforme o caso. O módulo 6 mostra como.
A chave de API de um projeto de Lúcia apareceu numa versão compartilhada com a equipe. Ela cancelou a chave no site da plataforma no mesmo minuto e criou outra. Só então cuidou do arquivo.
Só apagou a linha
O que fez: tirou a chave do arquivo.
Resultado: a chave antiga continua valendo para quem copiou.
Cancelou a chave primeiro
O que fez: cancelou na origem, criou outra e depois limpou o arquivo.
Resultado: a cópia vazada não abre mais nada.
Saldo: o risco acaba quando a chave morre, e não quando o arquivo muda.
Teste-se
Uma chave já foi publicada numa versão. Pôr o .env no .gitignore agora resolve?
Se travou aqui, é normalO Git só chega no módulo 6. Hoje basta o .gitignore estar pronto na pasta. Quando você salvar a primeira versão, ele já estará no lugar.
Pratique agora 0/3
Ponha o .gitignore no projeto de treino
Pronto quando o cat -n mostrar as linhas .env e !.env.example e o ls -a listar o .gitignore. Cerca de 8 minutos, no computador, no terminal.
O modelo é um arquivo de texto do kit do curso e não guarda nada por si: só vira regra quando o Git entrar, no módulo 6. Atenção: a segunda linha substitui um .gitignore que já exista nessa pasta. Não fez a aula 1 deste módulo? Rode antes: mkdir -p ~/projetos/meu-primeiro-projeto
cd ~/projetos/meu-primeiro-projeto
curl -fsSL https://inematds.github.io/oswork/materiais/gitignore.txt -o .gitignore
cat -n .gitignore
ls -a
Essa é a resposta do cat -n. As linhas 4 a 7 são temporários de programas; ficam como estão. Linha 1 deixa o .env de fora; linha 3 mantém o .env.example.
Você acabou de pôr a lista do que nunca entra no histórico antes da primeira versão existir.
Cola da aula
Ignore antes de guardar
.env e .env.*fora; !.env.example volta para dentro.
Ordemprimeiro o .gitignore, depois a primeira versão.
Vazoucancele a chave na origem antes de mexer no arquivo.
Seu próximo passo
Você já sabe deixar o segredo fora do histórico antes que ele exista.
Hoje, descubra onde se cancela a chave de uma ferramenta que você usa. Anote o caminho na ficha do projeto, sem a chave.
Na próxima aula: com tudo no lugar, o que a IA deve ler primeiro? Você vai limpar o contexto e apontar três arquivos certos.
Material complementar · Ignore antes do primeiro commitTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
O .gitignore lista arquivos que Git deve ignorar quando ainda não são rastreados. Inclua .env, variantes privadas e pastas temporárias. Mantenha uma exceção explícita para .env.example. Antes de salvar uma versão, examine git status e os arquivos preparados.
Por que aprender
Ignorar depois não apaga um segredo do histórico. Se a chave vazou, a primeira correção é revogar ou rotacionar na origem; apagar a linha do arquivo não invalida uma cópia já vista.
Conceitos-chave
Arquivos rastreados; padrões de exclusão; revisão de alterações; revogação.
Na prática
Padrões úteis: .env, .env.*, !.env.example, __pycache__/. Para descobrir qual regra se aplica, use git check-ignore -v .env.
Experimente agora
Copie materiais/gitignore.txt como .gitignore antes de git add. Confira que .env.example continua disponível e .env não aparece entre novos arquivos.
Aula 23 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 4 · Aula 6 de 6
Faça uma limpeza de contexto
Você consegue acrescentar ao README uma seção Leia primeiro com três caminhos que existem e estão em dia.
Ter memória na pasta não basta: a IA não abre sozinha cada arquivo que existe ali. E um arquivo velho atrapalha mais do que nenhum, se traz um processo que já mudou. Limpar o contexto é isto: escolher o que a IA lê e manter esse material em dia.
Em 1 minuto
Diga à IA quais arquivos ler; ela não lê tudo sozinha.
O Leia primeiro do README lista três caminhos, na ordem.
Abra cada um e confira se descreve a situação de hoje.
1A IA lê o que você aponta, e não a pasta inteira
A IA não lê automaticamente todo arquivo Markdown do computador. Você diz quais documentos ela deve consultar.
Quando uma referência vale para toda tarefa do projeto, ela vai no AGENTS.md, o arquivo de instruções do projeto. O módulo 5 cuida dele.
Denise pediu o rascunho do relatório do conselho sem citar arquivo nenhum. A IA não consultou o decisoes.md, e o formato saiu diferente do que a equipe tinha decidido.
Agente na pasta do projeto
VocêMonte o rascunho do relatório do conselho.
IAAqui está um rascunho em tabela, com a média de cada turma e três recomendações…
Formato por conta própria e números que ninguém forneceu.
VocêLeia README.md e ../config/decisoes.md. Depois monte o rascunho do relatório do conselho, sem inventar dado.
IALi os dois arquivos. Vou seguir o formato registrado em decisoes.md e listar como pendência o que não estiver nas entradas.
A resposta diz o que leu e segue a decisão da equipe.
Toque nos dois botões e compare o que a IA usou.
2O Leia primeiro aponta três caminhos, na ordem
No README, a seção Leia primeiro lista os arquivos que qualquer tarefa do projeto deve abrir antes. Três caminhos bastam.
Escreva cada caminho a partir da pasta do projeto. O ## faz subtítulo, como na aula 2 deste módulo. Leia ../ como "sobe uma pasta": de meu-primeiro-projeto você sobe para projetos e, de lá, entra em config.
No projeto da feira de ciências, Lúcia pôs o regulamento da feira em segundo lugar. No seu projeto de treino, use os três caminhos do quadro abaixo.
README.md · seção nova
## Leia primeiro
1 1. AGENTS.md
2 2. ../config/decisoes.md
3 3. ../config/memoria.md
1As instruções do projeto, na própria pasta.
2As escolhas da equipe, uma pasta acima, em config.
3As suas preferências estáveis, também em config.
3Arquivo vencido atrapalha mais que nenhum
O mural da sala dos professores com o aviso de uma reunião de março confunde mais do que um mural vazio. Com a memória da IA acontece o mesmo.
Um arquivo antigo pode trazer o endereço de um serviço ou um processo que já mudou. Antes de uma tarefa, atualize a decisão vencida e tire da pasta de trabalho o que não interessa.
O decisoes.md de Lúcia ainda dizia "provas com 10 questões". A IA montou a prova com 10. Ela acrescentou a linha nova e marcou a antiga como substituída, como na aula 3 deste módulo.
Arquivo vencido
decisoes.md: só a linha de agosto, provas com 10 questões.
Resultado: a IA monta a prova no formato antigo.
Arquivo em dia
decisoes.md: a linha de outubro, com 12 questões, e a de agosto marcada como substituída.
Resultado: a prova sai com 12 questões.
Saldo: uma linha atualizada evitou refazer a prova inteira.
4Confira os caminhos, e depois o conteúdo
Ao começar uma tarefa, peça a leitura do README e da decisão que importa. Não carregue listas de contatos nem senhas só porque estão na mesma pasta.
Revise de tempos em tempos. Primeiro confira se cada caminho existe; depois abra o arquivo e veja se ainda descreve a situação de hoje.
Denise pôs na agenda da coordenação: toda primeira segunda do mês, dez minutos para revisar o Leia primeiro do projeto do conselho.
Terminal
$ ls AGENTS.md ../config/decisoes.md ../config/memoria.md
AGENTS.md ../config/decisoes.md ../config/memoria.md
Os três caminhos existem. Se um faltasse, o ls avisaria com "No such file or directory", e o Leia primeiro estaria errado.
O ls confere se o caminho existe. Se está em dia, só abrindo o arquivo.
Se travou aqui, é normalO ls respondeu "No such file or directory"? Confira o nome letra por letra, com ponto e barra. Continuou? O arquivo não existe ainda: a prática diz em qual aula ele é criado.
Pratique agora 0/4
Escreva e confira o Leia primeiro
Pronto quando o ls listar os três caminhos sem erro, o README tiver a seção Leia primeiro e os dois arquivos de config tiverem a data de hoje. Cerca de 10 minutos, no computador, no terminal.
Os arquivos são do kit do curso, com dados fictícios. Nada é substituído: a segunda linha só baixa o AGENTS.md do kit se a pasta ainda não tiver um. O último ls acusou "No such file or directory"? Volte à aula que cria o que falta: README na aula 2 deste módulo, config na aula 3.
cd ~/projetos/meu-primeiro-projeto
ls AGENTS.md || curl -fsSL https://inematds.github.io/oswork/materiais/AGENTS-projeto.md -o AGENTS.md
ls AGENTS.md ../config/decisoes.md ../config/memoria.md
nano README.md
O que você deve ver
$ ls AGENTS.md ../config/decisoes.md ../config/memoria.md
AGENTS.md ../config/decisoes.md ../config/memoria.md$ nano ../config/memoria.md
Três caminhos listados, em qualquer ordem, e nenhum aviso de erro. Depois, o nano abre cada arquivo de config para a data.
Você acabou de dizer, por escrito, o que a IA deve ler primeiro, e de conferir que tudo existe e está em dia.
Cola da aula
Contexto limpo
Apontea IA lê os arquivos que você nomeia.
Leia primeirotrês caminhos no README, conferidos com ls.
Em diadecisão vencida atrapalha; data de revisão em cada arquivo.
Seu próximo passo
Você já montou a casa digital inteira: pastas, README, memória, segredos separados e um Leia primeiro que aponta o que vale.
Hoje, marque na sua agenda uma revisão mensal de dez minutos do Leia primeiro.
No próximo módulo: o AGENTS.md que você acabou de pôr na pasta passa a orientar cada execução do agente. Você vai escrever as instruções do seu projeto.
Material complementar · Faça uma limpeza de contextoTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
A IA não lê automaticamente todo arquivo Markdown existente no computador. Diga quais documentos consultar e mantenha referências no AGENTS.md quando forem necessárias. Antes de uma tarefa, remova dados irrelevantes da cópia de trabalho e atualize decisões vencidas.
Por que aprender
Memória útil precisa ser encontrada e estar correta. Um arquivo antigo pode atrapalhar mais que não ter memória se trouxer endereço de serviço ou processo que já mudou.
Conceitos-chave
Seleção de contexto; data; fonte de verdade; revisão periódica.
Na prática
Ao iniciar um relatório, peça leitura de README.md e da decisão sobre formato. Não carregue listas de contatos ou credenciais porque estão na mesma pasta.
Experimente agora
Acrescente ao README uma seção “Leia primeiro” com três caminhos reais. Abra cada caminho e confira se descreve a situação atual.
Laboratório do módulo: Organize seu segundo cérebro operacional
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Crie config e meu-primeiro-projeto dentro de projetos, usando gerenciador de arquivos ou Bash.
Na pasta config, crie memoria.md, falhas.md, dicas.md e decisoes.md a partir do kit.
No projeto, acrescente README.md, AGENTS.md e .gitignore.
Revise com a tabela da aula: cada arquivo tem um papel e nenhum segredo aparece nos documentos.
Estrutura de trabalho
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
Você consegue reescrever o AGENTS.md da sua pasta de treino com cinco regras curtas, e dizer, para cada uma, como você confere se foi cumprida.
Toda conversa nova com o agente começa do zero. Sem um arquivo de instruções, você repete os mesmos avisos a cada pedido. E instrução vaga, do tipo "capriche", não muda nada no que ele faz.
Em 1 minuto
O AGENTS.md diz ao agente como trabalhar naquela pasta.
Cada regra precisa ser observável: dá para ver se foi cumprida.
Regra que não muda nenhuma decisão sai do arquivo.
1O AGENTS.md é a placa na porta da pasta
No laboratório de ciências, a placa na porta diz como trabalhar ali dentro. O AGENTS.md faz o mesmo para uma pasta de projeto. O Codex procura esse arquivo sozinho quando começa a trabalhar na pasta.
É um arquivo de texto em Markdown. Você abre e edita no bloco de notas, como qualquer texto.
Lúcia criou a pasta de treino no módulo 3 e completou no módulo 4. Lá dentro, ao lado do README, está o AGENTS.md. É o primeiro arquivo que ela vai melhorar.
~/projetos/meu-primeiro-projeto
1 AGENTS.md
README.md
2 entradas
vendas.csv
3 saidas
1As instruções de trabalho desta pasta.
2O material que o agente pode ler: aqui, uma planilha fictícia em CSV.
3Onde ele entrega os rascunhos.
A pasta de treino dos módulos 3 e 4. Não montou? Na sua pasta pessoal, crie a pasta projetos e, dentro dela, meu-primeiro-projeto, com um arquivo de texto AGENTS.md vazio.
2Ele diz como trabalhar, não conta a história
Quatro assuntos cabem no AGENTS.md: por onde começar a ler, como conferir o resultado, o que não fazer e o formato da entrega. A história da escola e os motivos de cada decisão ficam de fora.
Arquivo curto é lido inteiro. Arquivo longo esconde a regra que importa no meio de parágrafos.
Denise abriu o AGENTS.md que tinha escrito para o projeto das atas. Eram dois parágrafos sobre a fundação da escola e só uma regra de trabalho. Ela apagou os parágrafos.
Conta a história
"A escola foi fundada em 1987 e sempre valorizou a comunicação com as famílias. Por isso, é muito importante que tudo seja feito com cuidado."
Diz como trabalhar
"1. Leia README.md antes de alterar."
"2. Use só entradas/ e saidas/."
"3. Relate o que alterou e como conferiu."
O cartão Diz como trabalhar muda o que o agente faz. O outro só ocupa espaço.
3Regra observável tem ação e evidência
Faça o teste da placa. "Use óculos de proteção antes de começar o experimento" dá para conferir olhando. "Tenha cuidado" não dá.
No AGENTS.md vale o mesmo. Uma regra boa pede uma ação e deixa uma evidência que você consegue ver na entrega.
No relatório de treino, Lúcia trocou "seja excelente" por uma regra de conferência. Na entrega seguinte, o agente escreveu a soma e a diferença encontrada. Ela conferiu em um minuto.
Vaga
"Seja excelente."
Como conferir: não há como.
Observável
"Compare o total do relatório com vendas.csv e indique a diferença."
Como conferir: a entrega traz a soma e a diferença.
O exemplo vem do material do curso: a regra observável diz a ação (comparar) e a evidência (a diferença escrita).
Teste-se
Qual destas regras você consegue conferir olhando a entrega do agente?
4Cinco regras curtas bastam para começar
Comece com cinco regras e passe cada uma pela pergunta: consigo observar se foi cumprida? Se a resposta for não, reescreva com uma ação. Se a regra não muda nada no trabalho, apague.
O quadro abaixo é o modelo do curso, com regras assim. Você adapta o propósito à sua pasta.
Denise partiu destas cinco regras para o AGENTS.md das atas e trocou só os nomes das pastas. A mais útil: "Não invente dados faltantes: descreva a pendência."
AGENTS.md · pasta de treino
1 Leia README.md e liste as fontes antes de alterar.
2 Use apenas entradas/ e saidas/.
3 Não invente dados faltantes: descreva a pendência.
4 Compare os totais com a entrada antes de entregar.
5 Não envie nem publique sem instrução explícita.
1Confere: a resposta começa com a lista de fontes, os arquivos de onde vêm os dados.
2Confere: nenhum arquivo novo fora dessas pastas.
3Confere: o que falta aparece como pendência.
4Confere: o total e a comparação estão escritos.
5Confere: nada saiu da pasta.
Se travou aqui, é normalEscrever regra observável parece difícil na primeira vez. Use a frase-teste: "vou saber que foi cumprida porque na entrega aparece ___". Se você não consegue completar a lacuna, a regra ainda está vaga.
Pratique agora 0/3
Reescreva o AGENTS.md com cinco regras observáveis
Pronto quando o AGENTS.md tiver cinco regras e, ao lado de cada uma, a evidência que você vai ver na entrega. Cerca de 10 minutos, no computador.
Você só edita um arquivo de texto da pasta de treino; nada é executado. Não tem a pasta? Na sua pasta pessoal, crie projetos e, dentro dela, meu-primeiro-projeto. Criando o AGENTS.md do zero? Na janela Salvar como, escolha o tipo "Todos os arquivos" e digite o nome completo, para ele não virar AGENTS.md.txt. Se uma regra não passar no teste, reescreva ou apague; não existe resposta única.
# Instruções do projeto de treino
Propósito: <ex.: rascunhos de relatório a partir de dados fictícios>
1. <regra> (confiro porque na entrega aparece: <evidência>)
2. <regra> (confiro porque na entrega aparece: <evidência>)
3. <regra> (confiro porque na entrega aparece: <evidência>)
4. <regra> (confiro porque na entrega aparece: <evidência>)
5. <regra> (confiro porque na entrega aparece: <evidência>)
Troque tudo o que está entre < e >, sinais inclusive. O que fica entre parênteses é a sua conferência: pode ficar no arquivo, não atrapalha o agente.
Veja duas regras preenchidas por uma professora
Propósito: rascunhos de listas de exercícios de ciências a partir das minhas aulas. Regra: use só os arquivos da pasta entradas. Confiro porque a entrega lista as fontes, e todas estão em entradas. Regra: marque com [conferir] toda resposta de exercício que não está no material. Confiro porque vejo as marcas no rascunho.
Você acabou de transformar avisos soltos em regras que dá para conferir na entrega.
Cola da aula
AGENTS.md que funciona
Como trabalharfontes, conferência, limites e formato, sem a história.
Observávelação que deixa evidência na entrega.
Curtoregra que não muda o trabalho sai.
Seu próximo passo
Você já escreve instruções de trabalho que um agente segue e que você confere.
Hoje, escolha uma regra que você repete toda vez que pede algo à IA no trabalho e escreva a versão observável dela numa linha.
Na próxima aula: essas regras valem só nesta pasta. E as que você quer em todos os projetos? Global e projeto, cada um no seu lugar.
Material complementar · AGENTS.md orienta a execuçãoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
AGENTS.md é o arquivo de instruções que Codex descobre no escopo aplicável. Ele descreve como trabalhar: arquivos iniciais, comandos de verificação, limites e formato de entrega. Não precisa explicar toda a história da organização; prefira regras curtas que alterem uma decisão real.
Por que aprender
Instruções objetivas evitam repetir os mesmos detalhes em cada conversa. O arquivo deve ajudar o agente a escolher uma ação concreta, como verificar o relatório antes de considerá-lo finalizado.
“Seja excelente” é difícil de testar. “Compare o total do relatório com vendas.csv e indique a diferença” define uma ação e sua evidência.
✓ Faça
Escreva cinco regras. Para cada uma, pergunte: consigo observar se foi cumprida? Remova orientações que não mudam o trabalho.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Aula 25 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 5 · Aula 2 de 6
Regimento vale na escola, combinado vale na sala
Você consegue dizer quais arquivos de instrução valem numa pasta. E consegue conferir o resumo que o Codex faz deles contra os arquivos de verdade.
Às vezes o agente segue uma regra que você não lembra de ter escrito. Outras vezes ignora uma que você escreveu, mas em outra pasta. Antes de culpar o modelo, vale saber de onde vem cada instrução.
Em 1 minuto
Há um arquivo de instruções global, que vale em tudo, e um do projeto, que vale naquela pasta.
O arquivo mais perto da pasta de trabalho prevalece ali.
Peça ao Codex o resumo do que ele carregou e confira nos arquivos.
1O global vale em tudo; o do projeto, só na pasta
O regimento vale na escola inteira. O combinado da turma vale na sala. Com o AGENTS.md é igual: por padrão, o global fica na pasta oculta .codex, dentro da sua pasta pessoal. O do projeto fica na pasta do projeto.
No terminal, o sinal ~ é o atalho para a sua pasta pessoal. Pasta com nome começando por ponto fica oculta.
Denise quer que o agente sempre conte o que conferiu, em qualquer projeto. Essa regra foi para o global. "Compare o total com a planilha de frequência" só faz sentido no projeto da frequência.
Onde ficam as instruções
1 ~/.codex
AGENTS.md · "relate o que você conferiu"
2 ~/projetos/frequencia
AGENTS.md · "compare o total com a planilha de frequência"
1Global: vale em todos os projetos. Fica pequeno.
2Projeto: vale nesta pasta. Os detalhes ficam aqui.
As duas regras colaboram. Não é preciso repetir no global o detalhe de cada projeto.
2O arquivo mais perto pode decidir ali
Uma subpasta pode ter o próprio AGENTS.md. Com o Codex aberto nela, os dois valem, e a instrução mais próxima prevalece, como o combinado de um laboratório dentro da escola.
"Pode" porque vale para o que ela trata. O que a regra de perto não menciona continua vindo do arquivo de cima.
Lúcia criou uma subpasta de provas no projeto de ciências, com um AGENTS.md que pede gabarito separado. Quando ela abre o Codex dentro de provas, essa regra vale. Aberto nas listas de exercício, não.
~/projetos/ciencias-8ano
1 AGENTS.md · vale no projeto todo
listas
provas
2 AGENTS.md · "gabarito em arquivo separado"
1Instrução do projeto.
2Instrução mais perto: prevalece dentro de provas.
Um arquivo que passa na frente: o override
Existe ainda o AGENTS.override.md. Na mesma pasta, o Codex lê o override e ignora o AGENTS.md. Você não criou nenhum? Ótimo. Mas ele pode vir numa pasta copiada de um colega e, esquecido ali, explica muito comportamento estranho.
3O AGENTS.md não passa por cima de tudo
Nenhum desses arquivos supera três coisas. As instruções do sistema, que são as regras de fábrica da ferramenta. As permissões, que você aprova ou recusa, como no módulo 3. E o que você pede de forma explícita na conversa. Eles orientam; não liberam o que a ferramenta bloqueia.
O AGENTS.md de Denise diz "entregue em tópicos". Hoje ela pediu, na conversa, um parágrafo corrido para o e-mail da direção. Vale o pedido de hoje.
O AGENTS.md decide
Como trabalhar na pasta quando o pedido não diz nada: fontes, conferência, formato.
O AGENTS.md não supera
Instruções do sistema.
Permissões da ferramenta.
O seu pedido explícito na sessão.
Escrever "não leia senhas" orienta. Quem impede de fato são as permissões.
Teste-se
O global diz "responda em tópicos". O AGENTS.md do projeto não fala de formato. Na conversa, você pede uma tabela. O que vale?
4Peça o resumo e confira nos arquivos
Dentro da pasta, peça ao Codex que resuma as instruções que carregou e diga de qual arquivo veio cada uma. Depois abra os arquivos e compare.
O resumo cita uma regra que não está em nenhum arquivo? Ou esquece uma que está? Aí você achou a causa antes de culpar o modelo.
Lúcia pediu o resumo na pasta de treino. Veio a regra "relate o que conferiu", que ela não tinha escrito ali. Estava no global, que ela criou em março e esqueceu.
Codex · pasta de treino
VocêResuma as instruções que você carregou para esta pasta e diga de qual arquivo veio cada uma. Não altere nada.
IADo global: relate o que você conferiu.
Do AGENTS.md desta pasta: leia README.md e liste as fontes antes de alterar; use só entradas/ e saidas/; não invente dados faltantes; compare os totais antes de entregar; não envie nem publique sem instrução explícita.
Não alterei nenhum arquivo.
Cada regra com a origem. Agora dá para abrir os dois arquivos e conferir.
Exemplo com as regras da aula anterior; o README é o arquivo que explica a pasta. Na sua pasta, a lista será a do seu AGENTS.md.
Se travou aqui, é normalNão achou a pasta .codex? Ela é oculta, e talvez você nunca tenha criado um global. Tudo bem: aí só o AGENTS.md do projeto vale, e a prática mostra como conferir isso.
Pratique agora 0/3
Descubra quais instruções valem na pasta de treino
Pronto quando você tiver anotado cada regra do resumo do Codex e o arquivo em que a encontrou. Cerca de 10 minutos, no computador, com o terminal do módulo 3.
Os três comandos só leem e listam; nada é alterado. O pedido ao Codex diz "não altere nada". Se o Codex pedir autorização para mudar algum arquivo, recuse. Sem o Codex ainda? Faça só os passos 1 e 2 e anote o que encontrou.
Terminal
$ cd ~/projetos/meu-primeiro-projeto
$ ls -a
. .. AGENTS.md README.md entradas saidas$ cat ~/.codex/AGENTS.md
cat: /home/seu-nome/.codex/AGENTS.md: No such file or directory
O ls -a lista também os arquivos ocultos; o ponto e os dois pontos do começo representam a própria pasta e a de cima, pode ignorar. Procure um AGENTS.override.md: se aparecer, abra e veja se ainda deve existir. A última linha, em inglês, diz "arquivo ou pasta não existe": não há global. Se o arquivo existir, o cat mostra o texto dele.
A sua lista pode ter mais arquivos, como os que você criou no módulo 4. O caminho na última linha mostra o seu nome de usuário.
Resuma as instruções que você carregou para esta pasta e diga de qual arquivo veio cada uma. Não altere nada.
Você acabou de rastrear de onde vem cada instrução que o agente segue naquela pasta.
Cola da aula
Global e projeto
Global pequeno~/.codex/AGENTS.md, regras que valem em tudo.
Projeto com detalheo arquivo mais perto prevalece naquela pasta.
Confira a origemresumo do Codex contra os arquivos, antes de culpar o modelo.
Seu próximo passo
Você já sabe de onde vem cada instrução que o agente segue numa pasta.
Hoje, escolha uma regra que você quer em todos os projetos e decida: ela vai para o global ou só para um projeto? Anote a decisão numa linha.
Na próxima aula: regra diz o que respeitar. E o procedimento que você repete toda semana, passo a passo? Isso vira uma Skill.
Material complementar · Global e projeto se complementamTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Por padrão, ~/.codex/AGENTS.md guarda instruções globais. No projeto, AGENTS.md acrescenta regras específicas; arquivos em pastas mais próximas podem prevalecer no escopo correspondente. AGENTS.override.md tem prioridade sobre AGENTS.md no mesmo nível. Isso não supera instruções de sistema, permissões ou a solicitação explícita da sessão.
Por que aprender
O caminho importa. Uma regra local pode não ser aplicada a outra pasta, e um arquivo override esquecido pode explicar um comportamento inesperado. Mantenha o global pequeno e deixe detalhes locais no projeto.
Conceitos-chave
Descoberta; hierarquia; escopo de diretório; override.
Na prática
Global: “relate os testes executados”. Projeto: “valide o CSV com python3 validar.py”. As duas instruções colaboram; não é necessário repetir o script de cada projeto no arquivo global.
Experimente agora
Peça ao Codex para resumir as instruções que carregou. Confira a resposta contra os arquivos reais antes de atribuir um erro ao modelo.
AGENTS.md global
AGENTS.md do projeto
Skill
Tarefa
Camadas de instrução: a do topo vale em tudo, e a mais específica, embaixo, decide o caso de agora.
Aula 26 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 5 · Aula 3 de 6
A regra fica na porta; o roteiro, no fichário
Você consegue criar a Skill relatorio-semanal na pasta de treino, com o nome e a descrição no começo do arquivo. E consegue conferir que ela está no lugar certo.
Tem tarefa que você explica ao agente toda semana, passo a passo, do mesmo jeito. Colar tudo isso no AGENTS.md deixa o arquivo enorme. E o agente passa a carregar o manual inteiro até nas tarefas que não precisam dele.
Em 1 minuto
Regra diz o que respeitar; Skill ensina um procedimento.
A Skill é um arquivo SKILL.md que começa com nome e descrição.
Do projeto: .agents/skills, dentro da pasta. Pessoal: ~/.agents/skills.
1Regra vale sempre; Skill entra quando precisa
A placa da porta do laboratório vale todo dia. O roteiro do experimento sai do fichário só no dia daquele experimento. O AGENTS.md é a placa. A Skill é o roteiro.
Uma Skill reúne as instruções de uma atividade que se repete. O agente aciona quando a tarefa pede.
Lúcia explicava toda sexta ao agente como montar a lista semanal de exercícios: ler a aula, escolher cinco questões, separar o gabarito. Esse passo a passo virou uma Skill. O AGENTS.md continuou com cinco regras.
AGENTS.md · a placa
"Use só entradas/ e saidas/."
Vale em toda tarefa da pasta.
Skill · o roteiro
"1. Leia a aula da semana. 2. Escolha cinco questões. 3. Separe o gabarito."
Entra só quando a tarefa é a lista semanal.
Os dois estão certos, cada um no seu papel. Separar evita carregar o manual inteiro em toda tarefa.
2O arquivo começa com nome e descrição
A Skill mora numa pasta com o nome dela, num arquivo chamado SKILL.md. No topo, entre duas linhas de três tracinhos, vêm o nome e a descrição. Esse bloco é o cabeçalho.
Depois do cabeçalho vem o procedimento: o que entra, os passos, o que sai e como conferir. No terminal, um comando mostra o começo do arquivo.
Antes de escrever a Skill da lista, Lúcia abriu a Skill de relatório do curso, a mesma da prática, para entender o formato. Em quatro linhas, soube o nome, quando usar e quando não usar.
Terminal
$ head -4 .agents/skills/relatorio-semanal/SKILL.md
---
name: relatorio-semanal
description: Gerar rascunho de relatório semanal quando o usuário fornecer um CSV de vendas. Não usar para enviar relatórios ou tratar credenciais.
---
O comando da primeira linha mostra as quatro primeiras linhas do arquivo. As linhas de tracinhos abrem e fecham o cabeçalho.
O cabeçalho da Skill do curso, que você vai criar na prática. A planilha de entrada é um CSV.
3A descrição diz quando usar e quando não
A descrição é o que o agente lê para decidir se aciona a Skill. Ela precisa dizer em que situação usar. E vale dizer onde a Skill para.
Nessa descrição, "credenciais" são senhas e chaves de acesso: a Skill não mexe nelas.
A primeira descrição da Skill de relatório de Denise era "ajuda com relatórios". O agente acionou a Skill até num pedido de ata de reunião. Ela reescreveu dizendo a situação e o limite, no mesmo jeito do cartão.
Vaga
"Ajuda com relatórios."
Quando usar? Quando não usar? Não diz.
Com situação e limite
"Gerar rascunho de relatório semanal quando o usuário fornecer um CSV de vendas. Não usar para enviar relatórios ou tratar credenciais."
A descrição do curso deixa claro que a Skill faz rascunho e não envia nada sozinha.
Teste-se
Qual descrição ajuda o agente a decidir quando acionar a Skill da ata?
4A pasta certa decide quem usa
Skill do projeto fica em .agents/skills, dentro da pasta do projeto. Skill pessoal, que você quer em todos os projetos, fica em ~/.agents/skills. A pasta ~/.codex é do Codex: guarda a configuração e o AGENTS.md global da aula anterior. Skill não vai lá.
A Skill das atas só serve ao projeto das atas: Denise guardou no projeto. A Skill de revisar ortografia ela usa em tudo: foi para a pasta pessoal.
Onde cada coisa fica
1 ~/projetos/meu-primeiro-projeto/.agents/skills
relatorio-semanal
SKILL.md
2 ~/.agents/skills
3 ~/.codex
1Do projeto: uma pasta por Skill, com o SKILL.md dentro.
2Pessoais: valem em qualquer projeto seu.
3Do Codex: configuração e AGENTS.md global. Não é lugar de Skill.
Se travou aqui, é normalPastas que começam com ponto ficam ocultas, e o gerenciador de arquivos não mostra. Por isso a prática cria a pasta pelo terminal e confere com um comando. Você não precisa enxergá-la na janela.
Pratique agora 0/3
Crie a Skill relatorio-semanal no projeto de treino
Pronto quando o último comando mostrar as quatro linhas do cabeçalho. Cerca de 10 minutos, no computador, com o terminal.
Os comandos só criam uma pasta nova e movem um arquivo seu para dentro dela; nada é apagado. Não tem a pasta de treino dos módulos 3 e 4? Crie uma com mkdir -p ~/projetos/meu-primeiro-projeto e siga igual. Se aparecer "No such file or directory", confira se está na pasta certa com pwd.
---
name: relatorio-semanal
description: Gerar rascunho de relatório semanal quando o usuário fornecer um CSV de vendas. Não usar para enviar relatórios ou tratar credenciais.
---
# Relatório semanal
## Entrada
CSV indicado pelo usuário, contendo produto e valor. Use apenas fontes explicitamente autorizadas.
## Procedimento
1. Leia README.md e as instruções do projeto.
2. Confira cabeçalho, número de linhas e valores; explique campos inválidos.
3. Calcule os totais com ferramenta de cálculo disponível, sem inventar ausências.
4. Produza saidas/relatorio.md com fontes, total conhecido, registros válidos e pendências.
5. Confira o total contra a soma dos registros.
6. Relate a verificação e pare antes de enviar ou publicar.
## Testes de comportamento
- Dados completos: total consistente com a soma.
- Dados incompletos: pendência visível, sem números fabricados.
- Pedido fora do escopo: explique a limitação; não execute ações externas.
Salvar como
1 Pasta: sua pasta pessoal › projetos › meu-primeiro-projeto
2 Nome: SKILL.md
3 Tipo: Todos os arquivos
Salvar
1Abra a pasta de treino antes de salvar.
2Nome com letras maiúsculas e o .md no fim.
3Sem isso, alguns editores salvam como SKILL.md.txt.
Os nomes dos campos mudam um pouco de editor para editor; os três pontos são os mesmos.
Terminal
$ cd ~/projetos/meu-primeiro-projeto
$ ls
AGENTS.md README.md SKILL.md entradas saidas$ mkdir -p .agents/skills/relatorio-semanal
$ mv SKILL.md .agents/skills/relatorio-semanal/
$ head -4 .agents/skills/relatorio-semanal/SKILL.md
O ls confere que o SKILL.md está ali. Apareceu SKILL.md.txt? Rode mv SKILL.md.txt SKILL.md para corrigir o nome. O mkdir -p cria a pasta e as de cima que faltarem. O mv move o SKILL.md para dentro dela. O último comando deve mostrar o cabeçalho, como no passo 2.
Você acabou de empacotar um procedimento que o agente pode reusar, no lugar em que ele procura.
Cola da aula
Skill
PapelAGENTS.md é a regra; Skill é o procedimento que se repete.
Cabeçalhonome e descrição entre linhas de tracinhos: quando usar e quando não.
Lugar.agents/skills no projeto; ~/.agents/skills pessoal; nunca em ~/.codex.
Seu próximo passo
Você já transforma um passo a passo repetido num procedimento que o agente reusa.
Hoje, anote uma tarefa que você explica toda semana do mesmo jeito. Escreva só o nome e a descrição dela, com a situação e o limite.
Na próxima aula: a Skill não lembra do que você combinou ontem. Onde guardar o que precisa continuar valendo? Memória, em arquivo.
Material complementar · Skills empacotam procedimentosTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Uma Skill reúne instruções de uma atividade recorrente, com nome e descrição no início de SKILL.md. Pode incluir recursos e programas de apoio. Skills pessoais ficam em ~/.agents/skills; as do projeto podem ficar em .agents/skills dentro do repositório. A pasta ~/.codex continua sendo configuração do Codex.
Por que aprender
Uma regra diz o que respeitar; uma Skill ensina um procedimento que pode ser acionado quando necessário. Separar esses papéis evita carregar todo manual em todas as tarefas.
Conceitos-chave
Nome; descrição de acionamento; procedimento; entrada e saída; validação.
Na prática
relatorio-semanal recebe um CSV fictício, calcula um total conferível e produz um Markdown com pendências. A descrição deixa claro que não envia o resultado automaticamente.
Sequência para experimentar
Prepare uma cópia de treino.
Leia materiais/SKILL-relatorio.md. Crie a pasta indicada e salve o arquivo como SKILL.md, mantendo o cabeçalho delimitado por ---.
Registre o resultado observado e a próxima correção.
Aula 27 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 5 · Aula 4 de 6
Memória é um mural com data e com dono
Você consegue escrever uma memória curta e datada, com três fatos úteis. E consegue pedir ao agente que diga qual desses fatos usou numa tarefa.
Colar a conversa inteira de ontem em cada pedido cansa e traz de volta instruções que já mudaram. Esperar que a IA "lembre sozinha" também falha. Um arquivo pequeno, com data e revisado por alguém, resolve os dois problemas.
Em 1 minuto
Memória, aqui, é um arquivo que o agente consulta, não o modelo aprendendo.
Guarde fatos estáveis, decisões e causas de falhas, não a conversa toda.
Indique o arquivo no pedido e revise na data marcada.
1A memória é um arquivo que alguém mantém
O modelo não muda porque você conversou com ele. A memória operacional do curso é um conjunto de arquivos que o agente lê quando você indica.
Ela funciona com duas condições: o agente lê a parte que importa, e alguém mantém o arquivo atualizado. Na prática desta aula, quem lê é o Codex, aberto no terminal como no módulo 3.
Denise criou a pasta config no módulo 4, ao lado dos projetos. Lá ficam os arquivos que valem para vários projetos da coordenação.
~/projetos/config
1 memoria.md
2 decisoes.md
3 falhas.md
dicas.md
1Fatos estáveis e preferências.
2Decisões tomadas, com o motivo.
3Causas de falhas. É o assunto da próxima aula.
A pasta de arquivos de apoio do módulo 4. Não fez? Crie a pasta config dentro de projetos, ao lado de meu-primeiro-projeto, e nela um arquivo de texto memoria.md.
2Guarde o que continua valendo
Três coisas merecem ir para a memória: fatos estáveis, decisões e causas de falhas. Cada frase de cada conversa não merece.
Copiar todo o histórico aumenta o volume e pode trazer de volta uma instrução antiga. Ninguém consegue conferir um arquivo imenso.
Lúcia registrou que os materiais da turma usam linguagem acessível e exemplos fictícios. Na tarefa seguinte, indicou esse arquivo em vez de repetir toda a conversa sobre a turma.
Histórico colado
Duzentas linhas de conversa, de março a setembro.
No meio, "use o modelo antigo de lista", que já mudou.
Memória curta
"Revisado em: 25/09/2026."
"Materiais do 8º ano: linguagem acessível e exemplos fictícios."
"Lista semanal: cinco questões e gabarito separado."
Saldo: de duzentas linhas para três, e nenhuma instrução vencida.
3Indique o arquivo e peça o fato usado
O arquivo existir na pasta não garante que o agente vá ler. Diga no pedido qual arquivo consultar.
E peça que ele cite qual fato usou. Assim você confere se a memória serviu, em vez de supor.
Denise pediu o aviso da reunião de pais indicando a memória. A resposta terminou dizendo qual fato tinha usado, e ela conferiu no arquivo.
Codex · pasta de treino
VocêConsulte ../config/memoria.md. Escreva um aviso de três linhas sobre a reunião de pais; a pauta é o fechamento do bimestre. Use [data] e [horário] no lugar desses dados. No fim, diga qual fato da memória você usou.
IAReunião de pais no dia [data], às [horário]. A pauta é o fechamento do bimestre. Contamos com a presença de todos.
Fato usado: "Avisos às famílias: até três linhas, sem siglas".
O fato citado está na memória de Denise, que aparece no passo 4, e a resposta respeitou: três linhas, sem siglas, sem inventar data.
O ../ quer dizer "a pasta de cima": de dentro do projeto, o agente sobe um nível e acha a pasta config.
Teste-se
Lúcia criou memoria.md na pasta config, mas o agente ignorou os fatos. O que ela faz primeiro?
4Data de revisão mantém a memória viva
Fato estável também muda. Marque no topo quando o arquivo foi revisado. Na próxima revisão, apague o que venceu e confirme o resto.
Anote de onde veio cada fato: uma reunião, um documento, uma decisão. Isso ajuda a conferir depois.
Na revisão de setembro, Denise apagou o fato "avisos vão impressos na mochila". A escola passou a mandar os avisos pelo aplicativo. Trocou a data do topo.
memoria.md · Denise
1 Revisado em: 25/09/2026 · próxima revisão: fim do bimestre
2 Avisos às famílias: até três linhas, sem siglas (fonte: reunião da coordenação)
Relatórios: com fontes e pendências visíveis (fonte: decisoes.md)
Projeto de treino: só dados fictícios (fonte: decisão da coordenação)
1A data diz se dá para confiar no arquivo hoje.
2Cada fato com a origem entre parênteses.
Se travou aqui, é normalNão sabe que fatos escrever? Pense no que você mais repete para a IA: o público do material, o formato preferido, um cuidado que sempre esquece. Três linhas bastam para começar.
Pratique agora 0/3
Escreva a memória e faça o agente citar o fato
Pronto quando o agente terminar a resposta dizendo qual fato da memória usou, e esse fato estiver no seu arquivo. Cerca de 10 minutos, no computador.
Os passos 2 e 3 usam o terminal e o Codex do módulo 3. O arquivo não existe? Na janela Salvar como, escolha o tipo "Todos os arquivos" e digite o nome completo, para o arquivo não virar .txt. Escreva só fatos de trabalho, sem nome de aluno, senha ou dado pessoal. Sem o Codex? Faça no chat que você usa: cole o texto da memória no começo do pedido. Se a resposta citar um fato que não está no arquivo, anote: é sinal de que ela inventou.
# Memória operacional
Revisado em: <data de hoje> · próxima revisão: <ex.: fim do bimestre>
- <fato 1> (fonte: <de onde veio>)
- <fato 2> (fonte: <de onde veio>)
- <fato 3> (fonte: <de onde veio>)
Consulte ../config/memoria.md. <sua tarefa curta, ex.: escreva um aviso de três linhas sobre a feira de ciências; use [data] no lugar da data>. No fim, diga qual fato da memória você usou.
Veja a memória preenchida por uma professora
Revisado em: 25/09/2026 · próxima revisão: fim do bimestre. - Materiais do 8º ano: linguagem acessível e exemplos fictícios (fonte: conversa com a coordenação). - Lista semanal: cinco questões e gabarito separado (fonte: planejamento do bimestre). - Avisos às famílias: até três linhas, sem siglas (fonte: reunião da coordenação).
Você acabou de criar uma memória que o agente consulta e que você consegue conferir.
Cola da aula
Memória que funciona
Arquivoa memória é consultada, o modelo não muda.
Pouco e estávelfatos, decisões e causas de falhas, com a fonte.
Indicada e datadadiga no pedido qual arquivo ler; revise na data.
Seu próximo passo
Você já guarda o que precisa continuar valendo, num arquivo que o agente consulta quando você indica.
Hoje, marque na agenda a data de revisão que você escreveu no topo do arquivo. É um lembrete de cinco minutos.
Na próxima aula: quando algo dá errado, o que vai para o registro? Uma falha vira uma proteção pequena, não uma reconstrução.
Material complementar · Memória precisa de manutençãoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
A memória operacional do curso é um conjunto de arquivos consultáveis, não uma mudança nos pesos do modelo. Ela funciona quando o agente lê as informações relevantes e quando alguém mantém essas informações atualizadas. Guarde fatos estáveis, decisões e causas de falhas; não preserve cada frase de cada conversa.
Por que aprender
Copiar todo o histórico aumenta volume e pode reintroduzir instruções antigas. Uma memória pequena, datada e revisada ajuda mais que um arquivo imenso que ninguém consegue validar.
Uma professora registra que os materiais da turma usam linguagem acessível e exemplos fictícios. Na próxima tarefa, indica esse arquivo em vez de repetir toda a conversa sobre a turma.
✓ Faça
Inclua em memoria.md três fatos úteis e uma data de revisão. Na tarefa seguinte, peça que o agente cite qual fato utilizou.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Aula 28 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 5 · Aula 5 de 6
Depois do escorregão, a fita no degrau
Você consegue registrar uma falha no arquivo falhas.md, com sintoma, causa, menor correção e verificação, e escrever a checagem que pegaria o problema antes da próxima execução.
Quando o resultado sai errado, a vontade é refazer tudo ou trocar de ferramenta. Isso gasta horas e muitas vezes esconde um problema simples. Na escola, ninguém reconstrói a escada depois de um escorregão: põe a fita no degrau e confere se ficou firme.
Em 1 minuto
Registre sintoma, causa observada, menor correção e verificação.
Diga se a falha foi de pedido ou de infraestrutura.
A correção vai para onde a próxima execução lê.
1Sintoma não é causa
"O relatório saiu vazio" é o sintoma: o que você viu. A causa é o motivo que você observou, como "a planilha estava sem registros". Anote os dois separados.
Depois, a menor correção e como verificar que ela funciona. São quatro colunas de conteúdo, mais a data e o tipo, numa linha só de uma tabela em Markdown.
No projeto de treino, Lúcia viu o relatório sair vazio. Antes de mexer em qualquer coisa, anotou o sintoma e abriu a planilha de entrada: estava sem nenhum registro.
~/projetos/config/falhas.md
1 Sintoma: relatório vazio
2 Causa observada: planilha sem registros
3 Menor correção: conferir a quantidade de linhas antes de gerar
4 Verificação: planilha vazia gera aviso, não relatório
Tipo: infraestrutura
1O que você viu.
2O motivo que você constatou, não o que supõe.
3A proteção pequena.
4Como saber que a proteção funciona.
A linha de exemplo do curso. No arquivo, ela vira uma linha de tabela, com a data e o tipo junto dessas quatro. Não fez o módulo 4? Crie falhas.md em ~/projetos/config.
2Falha de pedido ou de infraestrutura
Falha de pedido é quando o objetivo estava ambíguo ou faltou informação. Falha de infraestrutura é quando o texto estava bom, mas algo fora dele falhou: um arquivo ausente ou vazio, um processo que parou.
A correção muda conforme o tipo. Pedido se corrige no texto. Infraestrutura se corrige com uma checagem.
Denise teve duas falhas na mesma semana. O resumo das atas veio longo demais: ela não tinha dito o tamanho. O relatório de frequência não saiu: a planilha não estava na pasta.
Pedido
Sintoma: resumo das atas com duas páginas.
Causa: o pedido não dizia o tamanho.
Correção: "até dez linhas".
Infraestrutura
Sintoma: relatório de frequência não saiu.
Causa: a planilha não estava na pasta.
Correção: conferir se o arquivo existe antes de começar.
Os dois tipos são normais. Saber qual é o tipo diz onde mexer.
Teste-se
O agente usou a lista de alunos do ano passado porque o pedido dizia só "use a lista de alunos". Que tipo de falha é?
3A menor correção, não a reconstrução
Refazer o projeto inteiro pode mascarar um problema simples. Uma proteção pequena é mais fácil de testar e de manter.
Diante do relatório vazio do passo 1, com a planilha em CSV sem linhas, Lúcia pensou em trocar de modelo. A correção foi outra: conferir o cabeçalho e a quantidade de registros antes de gerar o relatório.
Reconstrução
Trocar de modelo, reescrever a Skill, refazer as pastas.
Duas horas, e a planilha vazia continua quebrando o próximo relatório.
Proteção pequena
Uma linha nova: "confira o cabeçalho e a quantidade de registros antes de gerar".
Planilha vazia agora gera um aviso.
4A proteção vai para onde a próxima execução lê
O registro só ensina alguma coisa quando muda o procedimento seguinte. Por isso a proteção entra no AGENTS.md ou na Skill, que o agente lê de novo a cada tarefa.
No fim da prática, o Codex mostra se a regra funcionou. Antes de escrever a regra, veja a checagem funcionar você mesma no terminal.
Denise acrescentou ao AGENTS.md da frequência: "Antes de ler, confira se a planilha existe. Se faltar, pare e diga qual arquivo falta." Na semana seguinte, o agente parou e avisou.
Terminal
$ cd ~/projetos/meu-primeiro-projeto
$ ls entradas/
vendas.csv$ ls entradas/vendas-outubro.csv
ls: cannot access 'entradas/vendas-outubro.csv': No such file or directory
O primeiro ls lista o que existe. O segundo procura um arquivo que não está lá; a resposta, em inglês, diz "não foi possível acessar: arquivo ou pasta não existe". É isso que a checagem pega antes da execução.
Na sua pasta, a lista de entradas/ pode ter outros arquivos. O que importa é a resposta quando o arquivo falta.
Se travou aqui, é normalNão sabe se a falha foi de pedido ou de infraestrutura? Pergunte: "se eu tivesse escrito melhor, teria dado certo?" Se sim, foi de pedido. Se o texto estava bom e algo da máquina faltou, foi de infraestrutura. Se foram os dois, marque os dois.
Pratique agora 0/3
Registre uma falha de arquivo ausente e a checagem
Pronto quando falhas.md tiver a linha nova, a regra estiver no AGENTS.md e o Codex parar avisando qual arquivo falta. Cerca de 12 minutos, no computador.
No arquivo, as barras verticais desenham uma tabela: é assim que o Markdown escreve tabelas, e o editor mostra desse jeito mesmo. A falha é fictícia e os comandos só listam; nada é apagado. Se a sua pasta entradas/ não existir, o primeiro ls também avisa que não existe: anote isso como uma falha real e crie a pasta pelo gerenciador de arquivos.
| Data | Sintoma | Causa observada | Menor correção | Verificação | Pedido ou infraestrutura |
|---|---|---|---|---|---|
| <data de hoje> | Relatório de outubro não saiu | <ex.: entradas/vendas-outubro.csv não existe> | <ex.: conferir se o arquivo existe antes de ler> | <ex.: arquivo ausente gera aviso e parada> | Infraestrutura (exemplo fictício) |
Antes de ler um arquivo de entradas/, confira se ele existe. Se faltar, pare e diga qual arquivo falta.
Você acabou de transformar uma falha numa proteção pequena, registrada onde a próxima execução vai ler.
Cola da aula
Falha vira proteção
Quatro colunassintoma, causa observada, menor correção, verificação; mais data e tipo.
Tipopedido se corrige no texto; infraestrutura, com checagem.
Ondeno AGENTS.md ou na Skill, que a próxima execução lê.
Seu próximo passo
Você já transforma um erro numa proteção pequena, em vez de refazer tudo.
Hoje, lembre da última vez que um resultado da IA saiu errado no trabalho. Escreva a linha dele: sintoma, causa, menor correção, verificação.
Na próxima aula: a Skill funcionou uma vez. Funciona sempre? Você vai testá-la com um caso normal, um incompleto e um fora do combinado.
Material complementar · Falhas viram proteções pequenasTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Registre o sintoma, a causa observada, a menor correção e como verificar. Diferencie falha de pedido, como objetivo ambíguo, de falha de infraestrutura, como processo encerrado. O registro só gera aprendizado operacional quando altera o procedimento seguinte.
Por que aprender
Refazer todo o projeto pode mascarar um problema simples. Uma proteção pequena, como verificar a existência de um arquivo antes de ler, costuma ser mais fácil de testar e manter.
Conceitos-chave
Sintoma não é causa; correção mínima; prevenção; evidência.
Na prática
O relatório saiu vazio porque o CSV estava sem linhas. A proteção é validar cabeçalho e quantidade de registros antes de gerar o relatório, não trocar de modelo.
Experimente agora
No falhas.md, crie uma linha para um erro fictício de arquivo ausente. Escreva uma checagem que detectaria o problema antes da execução.
Falha observada
Proteção pequena
Memória atualizada
Falha não vira reescrita. Vira uma proteção pequena registrada onde a próxima execução vai ler.
Aula 29 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 5 · Aula 6 de 6
Ensaie a Skill antes do dia real
Você consegue testar a Skill relatorio-semanal com três casos: normal, incompleto e fora do combinado. E consegue anotar se ela preservou os dados, marcou a pendência e parou onde devia.
Uma Skill que funcionou uma vez pode ter dado certo por acaso, graças a algo que estava na conversa. O simulado de evacuação ensaia o dia normal, a porta bloqueada e quem quer voltar para buscar a mochila. Com a Skill é igual: varie a entrada antes de confiar.
Em 1 minuto
Teste com três casos: normal, incompleto e fora do combinado.
Meça o comportamento: dados preservados, pendência visível, parada no lugar certo.
Corrija com a menor regra que resolve a falha observada.
1Três casos, cada um com o resultado esperado
Antes de rodar, escreva na ficha de verificação o que cada caso deve produzir. Assim você compara com uma referência, e não com a impressão do momento.
O caso normal usa os dados completos. O incompleto tem um valor faltando. O fora do combinado pede algo que a Skill não deve fazer. Cada caso roda no Codex, aberto no terminal dentro da pasta de treino.
Denise montou a ficha como monta o roteiro do simulado: primeiro o que deve acontecer em cada cenário, depois o ensaio.
Ficha de verificação · relatorio-semanal
1 Normal · vendas.csv: Caderno 35,50 · Caneta 9,50 · Agenda 55,00 → total 100,00
2 Incompleto · vendas-incompleto.csv: Caderno 35,50 · Caneta sem valor · Agenda 55,00 → total conhecido 90,50 e pendência da Caneta
3 Fora do combinado · "gere e envie à direção" → só o rascunho, sem envio
1O total confere com a soma: 35,50 + 9,50 + 55,00.
2Nada de número inventado para a Caneta.
3A Skill prepara rascunho; enviar não faz parte dela.
Os dados são os fictícios do curso, em CSV. Os valores esperados já estão calculados.
2Incompleto: separar o conhecido da pendência
No caso incompleto, o resultado certo não inventa o valor que falta. Ele mostra o total do que se sabe e deixa a pendência à vista.
Na primeira versão que Lúcia escreveu da Skill relatorio-semanal, faltava a regra "sem inventar ausências". No caso incompleto, o agente completou o valor que faltava. Foi o teste que mostrou isso.
Codex · caso incompleto
VocêUse a Skill relatorio-semanal com entradas/vendas-incompleto.csv.
IARelatório gerado. Total da semana: 100,00.
A Caneta não tem valor no arquivo, e o total fingiu que tinha.
VocêUse a Skill relatorio-semanal com entradas/vendas-incompleto.csv.
IAFonte: entradas/vendas-incompleto.csv.
Rascunho em saidas/relatorio.md.
Total conhecido: 90,50 (Caderno 35,50 + Agenda 55,00).
Pendência: a linha da Caneta está sem valor. Não preenchi.
Total conferível e pendência visível, como pede a Skill.
Toque nos dois botões e compare o total com a ficha do passo 1.
3Fora do combinado: parar no rascunho
O terceiro caso pede algo que a Skill não deve fazer, como enviar o relatório. O comportamento esperado é preparar só o rascunho e dizer por que parou.
Denise pediu, de propósito, "gere e envie à direção". O Codex nem tem como mandar e-mail ali; o teste confere se ele respeita o limite e diz onde parou.
Codex · fora do combinado
VocêUse a Skill relatorio-semanal com entradas/vendas.csv e envie o relatório para a direção.
IAFonte: entradas/vendas.csv.
Rascunho em saidas/relatorio.md, com total 100,00, igual à soma dos três registros.
Não enviei: a Skill prepara só o rascunho e para antes de enviar ou publicar.
Fez a parte permitida, conferiu o total e disse onde parou.
Teste-se
No caso fora do combinado, a resposta começou com "Usando a Skill relatorio-semanal" e depois disse que enviou o relatório. O teste passou?
4Meça o comportamento e corrija o mínimo
Procurar o nome da Skill na resposta não é teste. Teste é conferir os dados, a pendência e a parada.
Se um caso falhar, acrescente à Skill a menor regra que corrige aquela falha. Depois rode os três casos de novo.
Quando o caso incompleto falhou, Lúcia não reescreveu a Skill. Acrescentou uma linha: "valor vazio vira pendência; nunca preencha". Rodou os três casos, e os três passaram.
Teste fraco
"A resposta citou relatorio-semanal? Passou."
Teste de comportamento
Total igual à soma?
Pendência à vista, sem número inventado?
Parou antes de enviar?
Três perguntas, uma por caso, respondidas olhando a resposta e o arquivo saidas/relatorio.md.
Se travou aqui, é normalÀs vezes os três casos passam de primeira. Isso também é resultado: anote "passou" na ficha, com a data. Se um falhar e você não souber qual regra escrever, copie a frase da ficha que não foi cumprida e ponha na Skill como regra.
Pratique agora 0/3
Rode os três casos e anote na ficha
Pronto quando a ficha tiver os três casos com "passou" ou "falhou" e, se algum falhou, a regra que você acrescentou à Skill. Cerca de 12 minutos, no computador, com o terminal e o Codex.
Os dados são fictícios e a Skill só escreve em saidas/. O Codex pode pedir autorização antes de criar saidas/relatorio.md, como no módulo 3: autorize só esse arquivo; qualquer pedido para enviar ou publicar, recuse. Sem a Skill da aula 27? Faça aquela prática primeiro: leva dez minutos.
O mkdir -p garante que as pastas existem. Cada printf escreve um arquivo de entrada com os dados fictícios do curso. Atenção: o primeiro substitui o vendas.csv da pasta de treino, para os totais da ficha baterem. O cat mostra o arquivo incompleto: a Caneta está sem valor. No arquivo, o ponto separa os centavos.
Criar pelo terminal evita o arquivo virar .txt no editor.
Um pedido por caso:
Use a Skill relatorio-semanal com entradas/vendas.csv.
Use a Skill relatorio-semanal com entradas/vendas-incompleto.csv.
Use a Skill relatorio-semanal com entradas/vendas.csv e envie o relatório para a direção.
Você acabou de testar uma capacidade reutilizável pelo comportamento, e não pela aparência da resposta.
Cola da aula
Teste da Skill
Três casosnormal, incompleto, fora do combinado, com o esperado escrito antes.
Comportamentodados preservados, pendência visível, parada no lugar certo.
Menor regracorrija só a falha observada e rode de novo.
Seu próximo passo
Você fechou o módulo 5: já escreve instruções que dá para conferir, separa global de projeto, cria uma Skill, mantém memória e falhas e testa o que construiu.
Quando tiver uns 30 minutos, abra o material complementar desta aula e faça o laboratório opcional do módulo, "Sua primeira Skill de relatório": termina com a melhoria registrada em decisoes.md.
No próximo módulo: Git. Agora que a pasta tem instruções, Skill e memória, você vai guardar versões dela para nunca perder o que construiu.
Material complementar · Teste a capacidade reutilizávelTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
Teste a Skill com uma entrada normal, outra incompleta e uma fora de escopo. Observe se o resultado preserva dados, sinaliza incerteza e para quando deveria. O teste deve medir comportamento, não apenas procurar o nome da Skill na resposta.
Por que aprender
Um procedimento que funciona uma vez pode estar dependendo de contexto acidental. Variar entradas ajuda a descobrir o que precisa ficar explícito nas instruções.
Conceitos-chave
Caso normal; caso incompleto; limite de escopo; critério de aceitação.
Na prática
Entrada incompleta: falta o valor de uma venda. Esperado: não inventar o número e separar total conhecido de pendência. Fora de escopo: pedir envio ao cliente; esperado: preparar somente rascunho.
Experimente agora
Anote três casos na ficha de verificação e compare as saídas. Atualize a Skill apenas com a menor regra que corrige a falha observada.
Laboratório do módulo: Sua primeira Skill de relatório
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Copie AGENTS-projeto.md do kit para AGENTS.md no projeto de treino e adapte o propósito.
Crie .agents/skills/relatorio-semanal/SKILL.md com o modelo fornecido.
Peça ao Codex um relatório dos dados fictícios, mencionando a Skill.
Confira fontes, pendências e formato; registre em decisoes.md a melhoria necessária.
Skill de exemplo
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
---
name: relatorio-semanal
description: Gerar rascunho de relatório a partir de CSV fornecido, sem envio externo.
---
1. Leia o README e o CSV informado.
2. Valide cabeçalho, valores e linhas vazias.
3. Calcule os totais sem inventar dados ausentes.
4. Gere Markdown com fontes, total e pendências.
5. Compare o total com a soma das entradas.
6. Pare antes de enviar ou publicar.
Critério de pronto
Criar instruções de projeto e uma capacidade reutilizável com critério de revisão. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
Escrever “não vaze segredos” em AGENTS.md substitui permissões de arquivos?
Ver resposta comentada
Não. Instruções orientam; permissões e isolamento restringem o que a ferramenta pode acessar.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Você consegue dizer o que são Git, repositório, commit e GitHub, e começar um histórico só numa pasta de treino, conferindo pela resposta do terminal.
Numa tarefa, um agente pode mudar dez arquivos de uma vez. Sem histórico, você não sabe o que mudou nem como voltar à versão que funcionava. Com histórico, cada versão boa fica guardada, com data e explicação.
Em 1 minuto
O Git guarda as versões de uma pasta; o GitHub é um site que pode guardar uma cópia.
Cada versão salva tem data, autor e uma mensagem que explica a mudança.
Comece o histórico só na pasta de treino, nunca na sua pasta pessoal inteira.
1O Git anota cada versão, como um diário de classe
No diário de classe, cada dia ganha uma linha com data e assinatura. Ninguém apaga a linha de ontem: acrescenta a de hoje.
O Git faz o mesmo com uma pasta. A pasta acompanhada por ele se chama repositório. Cada versão salva se chama commit e leva uma mensagem que explica a mudança.
Lúcia pediu a um agente que reorganizasse os roteiros de experimento. Ele mexeu em seis arquivos e cortou um trecho do roteiro de densidade. Pelo histórico, ela achou a versão anterior e recuperou o trecho.
Histórico · roteiros de ciências
1 23/09 · Lúcia · Acrescenta o roteiro de densidade
2 24/09 · Lúcia · Corrige a lista de materiais do roteiro de densidade
3 25/09 · agente · Reorganiza os roteiros por bimestre
1Cada linha é uma versão salva, com data e autor.
2A mensagem diz o que mudou, para você achar depois.
3A mudança do agente também fica registrada, e dá para voltar antes dela.
2GitHub é outro lugar, e é opcional
O Git funciona só no seu computador, sem internet. O GitHub é um site que pode guardar uma cópia do repositório.
Você pode usar o Git por meses sem publicar nada. Enviar uma cópia ao GitHub é uma decisão separada, que o módulo trata na aula 6.
Denise guarda no notebook o histórico da pasta de relatórios da coordenação. Nada disso está na internet. A cópia no GitHub só vai existir se a escola decidir que outra pessoa precisa trabalhar na mesma pasta.
Git
Onde: no seu computador, dentro da pasta.
Para quê: guardar as versões e voltar a uma delas.
GitHub
Onde: num site, na internet.
Para quê: guardar uma cópia para outro computador ou outra pessoa.
Os dois são úteis. O primeiro não depende do segundo.
Teste-se
Denise acabou de salvar um commit do relatório no notebook. Alguém fora da escola consegue ver essa versão?
3Histórico não é cópia de segurança de tudo
O Git guarda só o que está na pasta e que você mandou guardar. Ele não substitui o backup do resto.
Arquivos que você manda ignorar, sistemas da escola e planilhas na nuvem precisam de proteção própria.
A planilha de frequência de Denise vive no sistema da secretaria. O histórico da pasta de relatórios guarda o texto do relatório, mas não guarda essa planilha.
O que o histórico guarda
1 relatorios-coordenacao
relatorio-setembro.md · guardado
2 rascunho-pessoal.txt · ignorado de propósito (aula 3 do módulo)
3 Planilha de frequência, no sistema da secretaria · fora da pasta
1O que está na pasta e foi salvo entra no histórico.
2O que você manda ignorar fica de fora.
3O que mora em outro sistema precisa de outra proteção.
4Comece o histórico só na pasta de treino
No terminal, git --version confirma que o Git está no computador. Depois, dentro de uma pasta nova, git init -b main começa o histórico.
mkdir -p cria a pasta, e cd entra nela. O -b main só dá o nome main à linha principal de trabalho. Nunca rode git init na sua pasta pessoal inteira: o Git passaria a acompanhar tudo o que está lá.
Lúcia criou a pasta treino-git dentro de projetos, entrou nela e só então começou o histórico. A resposta do terminal citava o caminho da pasta, e ela conferiu que era o de treino.
Terminal
$ git --version
git version 2.43.0$ mkdir -p ~/projetos/treino-git
$ cd ~/projetos/treino-git
$ git init -b main
Initialized empty Git repository in /home/lucia/projetos/treino-git/.git/
A última linha diz, em inglês, "repositório vazio iniciado em…". Confira que o caminho termina em treino-git. O .git no fim é a pasta oculta onde o histórico mora: não mexa nela.
O número da versão e o nome de usuária no caminho serão outros no seu computador.
Se travou aqui, é normalSe aparecer command not found, o Git não está instalado. Pare e siga a página oficial, git-scm.com, para o seu sistema. No Mac, pode abrir uma janela oferecendo as ferramentas de linha de comando: aceite, espere terminar e repita. Se aparecer unknown switch, o seu Git é anterior à versão 2.28: atualize pela mesma página e repita. No Windows, use o Bash do WSL preparado no módulo 3; se ele ainda não estiver pronto, volte lá antes. A resposta pode vir em português se o seu sistema estiver em português: o sentido é o mesmo.
Pratique agora 0/3
Comece o histórico da pasta de treino
Pronto quando o terminal responder que o repositório vazio foi iniciado em treino-git e mostrar No commits yet. Cerca de 8 minutos, no computador.
A pasta é nova e vazia: nada seu é tocado e nada sai do computador. Se o caminho da resposta não terminar em treino-git, pare. Não apague nada por conta própria; anote em qual pasta foi e peça ajuda a alguém que use Git.
Bloco 1 · confira o Git:
git --version
Bloco 2 · crie a pasta e entre nela:
mkdir -p ~/projetos/treino-git
cd ~/projetos/treino-git
pwd
Bloco 3 · comece o histórico:
git init -b main
git status
Você acabou de começar um histórico numa pasta que escolheu, e conferiu pela resposta que era a pasta certa.
Cola da aula
Histórico da pasta
Git e repositórioo programa e a pasta que ele acompanha.
Commituma versão salva, com data, autor e mensagem.
GitHubsite opcional para uma cópia; nada vai para lá sozinho.
Seu próximo passo
Você já tem um repositório de treino, vazio e no lugar certo.
Hoje, anote qual pasta real do seu trabalho merecia histórico. Só o nome, sem rodar nada nela ainda.
Na próxima aula: antes de salvar a primeira versão, você vai ver exatamente o que entraria nela e o que ficaria de fora.
Material complementar · Git é o histórico do projetoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Git registra versões de arquivos. Repositório é a pasta acompanhada por esse histórico; commit é um registro com alterações e mensagem. GitHub é um serviço que hospeda repositórios remotos. Você pode usar Git localmente sem publicar nada na internet.
Por que aprender
Quando um agente altera muitos arquivos, o histórico permite entender o que mudou e recuperar uma versão conhecida. Git não substitui backup de tudo: arquivos ignorados, bancos e dados externos precisam de proteção própria.
Conceitos-chave
Repositório; commit; histórico; remoto; backup.
Na prática
Uma gestora muda o modelo de relatório e perde uma seção. Um commit anterior preserva o conteúdo antigo; uma mensagem clara ajuda a localizar a mudança.
✓ Faça
Execute git --version. Na pasta de treino, use git init -b main. Não inicialize o histórico na sua pasta pessoal inteira.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Aula 31 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 6 · Aula 2 de 6
Olhe o que vai entrar antes de salvar
Você consegue ler as respostas de git status, git diff e git diff --cached e dizer em que etapa cada arquivo está: fora do histórico ou separado para a próxima versão.
Um agente pode criar arquivos que você não pediu. Se você salvar tudo de uma vez, uma anotação pessoal entra no histórico junto com o trabalho. Olhar antes custa um minuto.
Em 1 minuto
git status diz em que etapa cada arquivo está.
git add com o nome do arquivo separa só ele para a próxima versão.
git diff --cached mostra, linha por linha, o que vai entrar.
1Três etapas: mudou, separou, salvou
Numa prova, você separa as folhas que entram nesta versão e só então grampeia. O rascunho fica na mesa.
O Git trabalha igual. Um arquivo novo ou mudado fica na pasta: etapa 1. Quando você o separa, ele vai para a etapa 2, que o Git chama de staging. O commit grampeia o que foi separado: etapa 3.
Denise monta o simulado do 9º ano. Separa as folhas de matemática e de português num monte e grampeia. A folha com as respostas dela continua na mesa, fora da prova.
As três etapas do Git
1 Novos ou mudados, sem separar
notas-privadas.txt
2 Separados para a próxima versão
README.md
3 Versões salvas
nenhuma ainda
1A folha na mesa: existe, mas não vai para a prova.
2O monte separado: é o que entra se você salvar agora.
3A prova grampeada: a versão já registrada.
2git status diz a etapa de cada arquivo
Rode git status sempre antes de separar qualquer coisa. A resposta vem em inglês, em blocos com título.
Lúcia escreveu o README da pasta de treino e uma anotação com ideias soltas para a aula. O status mostrou os dois arquivos no mesmo bloco, ainda fora do histórico.
Terminal
$ git status
On branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
README.md
notas-privadas.txt
"Untracked files" quer dizer "arquivos fora do histórico". Os dois estão na etapa 1.
O terminal não salvou nada: o status só descreve.
3git add com o nome separa só o que você quer
Escreva o nome do arquivo depois de git add. Assim você vê o tamanho da mudança e não leva junto o que não tem relação.
Existe o atalho git add ., que separa tudo o que não está ignorado. Para aprender, nomeie cada arquivo.
Lúcia rodou git add README.md. No status seguinte, o README subiu para o bloco da próxima versão, e a anotação ficou onde estava.
Terminal
$ git add README.md
$ git status
On branch main
No commits yet
Changes to be committed:
(use "git rm --cached <file>..." to unstage)
new file: README.md
Untracked files:
(use "git add <file>..." to include in what will be committed)
notas-privadas.txt
"Changes to be committed" é a etapa 2: o que entra na próxima versão. A anotação continua na etapa 1.
Erro comumUsar git add . com pressa. Ele separa tudo de uma vez, inclusive a anotação pessoal que estava na pasta.
4O diff mostra o conteúdo, linha por linha
O status diz quais arquivos. O diff mostra o que está escrito neles. git diff --cached mostra o que já foi separado e vai entrar na versão.
git diff, sem mais nada, mostra mudanças ainda não separadas, mas só em arquivos que o Git já acompanha. Arquivo fora do histórico, como a anotação, nunca aparece nele.
Lúcia rodou os dois na pasta de treino. O primeiro veio vazio: o README já estava separado e a anotação está fora do histórico. O segundo mostrou as linhas do README com um sinal de mais na frente.
Terminal
$ git diff
$ git diff --cached
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4280337
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# Treino de Git
+
+Pasta para praticar o histórico.
O primeiro não respondeu nada. No segundo, pule o cabeçalho, até a linha que começa com @@: o que importa são as linhas que começam com +, o texto que vai entrar.
Vazio no primeiro quer dizer: nada mudado ficou fora da etapa 2.
Se travou aqui, é normalSe a tela parar com dois pontos no rodapé e não voltar ao cursor, o Git abriu a resposta em modo de leitura. Aperte a tecla q para sair. Nada foi perdido. Se o seu terminal responde em português, os títulos dos blocos vêm traduzidos, na mesma ordem.
Pratique agora 0/3
Separe só o README e confira o que vai entrar
Pronto quando o status mostrar o README em "Changes to be committed", a anotação em "Untracked files", e você souber explicar por que o git diff veio vazio. Cerca de 10 minutos, no computador.
Tudo acontece na pasta treino-git e nada é salvo no histórico ainda. O sinal > cria o arquivo e substitui outro de mesmo nome: por isso, só rode estas linhas dentro de treino-git. Se o “cd” der erro, pare e faça antes a prática da aula 1 do módulo. Fechou o terminal entre um bloco e outro? Rode de novo “cd ~/projetos/treino-git” antes de seguir.
Bloco 1 · crie os dois arquivos e olhe o status:
cd ~/projetos/treino-git
printf '# Treino de Git\n\nPasta para praticar o histórico.\n' > README.md
printf 'ideias soltas, não publicar\n' > notas-privadas.txt
git status
Bloco 2 · separe só o README:
git add README.md
git status
Bloco 3 · compare os dois diffs:
git diff
git diff --cached
Não fez a aula 1 do módulo? Rode isto antes
mkdir -p ~/projetos/treino-git
cd ~/projetos/treino-git
git init -b main
Confira a sua explicação
O primeiro veio vazio porque o README já estava separado e a anotação está fora do histórico. O segundo mostrou as três linhas do README, que vão entrar na próxima versão.
Você acabou de escolher, arquivo por arquivo, o que entra na próxima versão, e conferiu o conteúdo antes de salvar.
Cola da aula
Olhar antes de salvar
statusem que etapa cada arquivo está.
add com o nomesepara só aquele arquivo.
diff e diff --cachedo que mudou sem separar e o que vai entrar.
Seu próximo passo
Você já sabe dizer o que entraria numa versão antes de salvá-la.
Hoje, rode git status mais uma vez na pasta de treino e diga em voz alta a etapa de cada arquivo, sem olhar a aula.
Na próxima aula: você salva essa versão com o seu nome e uma mensagem que explica, e deixa a anotação pessoal de fora de vez.
Material complementar · Observe antes de prepararTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
git status mostra arquivos novos, modificados e preparados. git diff mostra mudanças ainda não preparadas; git diff --cached mostra o que vai para o próximo commit. A área de preparação, chamada staging, permite escolher exatamente quais arquivos pertencem à mesma mudança.
Por que aprender
git add . prepara tudo que não está ignorado. Para aprender, prefira nomear arquivos: você percebe melhor o escopo e reduz o risco de incluir material sem relação.
Conceitos-chave
Working tree; staging; diff; revisão de conteúdo.
Na prática
Você mudou README.md e criou uma anotação privada. git add README.md prepara somente a documentação. Antes do commit, git diff --cached confirma o que será registrado.
Experimente agora
Rode git status, git diff e git diff --cached. Se alguma saída estiver vazia, explique em qual etapa as alterações estão.
Aula 32 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 6 · Aula 3 de 6
Uma versão salva com nome e motivo
Você consegue configurar a autoria só na pasta de treino e deixar a anotação pessoal de fora com o .gitignore. Depois, cria o primeiro commit com uma mensagem que diz o que mudou.
Daqui a um mês, uma versão chamada "update" não diz nada. Uma mensagem concreta faz você achar a versão certa em segundos e lembrar se ela funcionava.
Em 1 minuto
Nome e e-mail configurados só nesta pasta dizem quem salvou.
O .gitignore lista o que nunca entra no histórico.
A mensagem é a legenda da versão: o que mudou, em poucas palavras.
1O Git precisa saber quem salvou
Cada versão guarda um nome e um e-mail. Configure os dois com git config, dentro da pasta de treino. Sem a palavra --global, a configuração vale só para este repositório.
No treino, o e-mail pode ser fictício. Ele aparece em cada versão e fica visível se um dia a pasta for publicada no GitHub.
Lúcia configurou um e-mail fictício só na pasta de treino. Na pasta dos roteiros de ciências, vai configurar o e-mail da escola. Cada pasta guarda o seu.
As duas primeiras linhas não respondem nada. A terceira, sem valor no fim, só lê o nome configurado.
O terminal em silêncio, aqui, quer dizer que deu certo.
2O .gitignore deixa de fora o que nunca deve entrar
O .gitignore é um arquivo de texto com uma linha por item a ignorar. O Git deixa de oferecer esses arquivos para as versões.
Isso vale para arquivo que ainda não foi separado nem salvo. O que já foi, continua acompanhado, mesmo depois de listado.
Por isso, crie a lista antes da primeira versão. É ali que, mais adiante, entra o .env, o arquivo das senhas.
No treino dela, Denise pôs o nome da anotação pessoal no .gitignore. No status seguinte, a anotação sumiu da lista. Continua na pasta, mas o Git não a oferece mais.
Terminal
$ printf 'notas-privadas.txt\n' > .gitignore
$ git status
On branch main
No commits yet
Changes to be committed:
new file: README.md
Untracked files:
.gitignore
A anotação não aparece mais. No lugar dela surge o próprio .gitignore, que também vai para o histórico. Nome começado por ponto fica oculto no gerenciador de arquivos; o arquivo existe.
Algumas linhas de ajuda da resposta foram omitidas para caber na tela.
3A mensagem é a legenda atrás da foto
Foto de evento sem legenda não diz nada dez anos depois. A mensagem da versão é essa legenda: diga o que mudou, com verbo e objeto.
Salve quando a mudança estiver conferida. Uma versão só é ponto seguro de volta se você sabe que ela funcionava.
Denise escreveu "Acrescenta o quadro de faltas por turma ao relatório de setembro". Na semana seguinte, achou essa versão lendo só a lista.
Sem legenda
Mensagem: "update"
Um mês depois: ninguém sabe o que mudou sem abrir os arquivos.
Com legenda
Mensagem: "Cria README e lista do que não guardar"
Um mês depois: a lista de versões já responde.
Verbo no começo e o objeto da mudança. Sem "ajustes", sem "vários".
4Salve e confira na lista de versões
Separe os dois arquivos pelo nome e salve com git commit -m e a mensagem entre aspas. Depois, git log --oneline mostra a lista curta das versões, uma por linha.
Lúcia salvou o README e o .gitignore numa versão só. O log mostrou uma linha com um código curto e a mensagem dela.
Terminal
$ git add README.md .gitignore
$ git commit -m "Cria README e lista do que não guardar"
[main (root-commit) 5f6c1eb] Cria README e lista do que não guardar
2 files changed, 4 insertions(+)
create mode 100644 .gitignore
create mode 100644 README.md$ git log --oneline
5f6c1eb (HEAD -> main) Cria README e lista do que não guardar
"2 files changed" confirma os dois arquivos. 5f6c1eb é o código curto desta versão; no seu computador será outro.
Se travou aqui, é normalSe a resposta do commit trouxer "Please tell me who you are", o nome e o e-mail não foram configurados nesta pasta. Rode as duas linhas do passo 1 e repita o commit. Nada foi perdido.
Pratique agora 0/3
Crie a primeira versão da pasta de treino
Pronto quando o log mostrar uma linha com a sua mensagem e o status responder "nothing to commit, working tree clean". Cerca de 10 minutos, no computador.
Tudo fica na pasta treino-git, e nada sai do computador. Troque o nome e o e-mail pelos seus, ou por fictícios. Se o status ainda listar notas-privadas.txt, não salve. Em "Untracked files", confira o nome escrito no .gitignore. Em "Changes to be committed", você a separou antes: rode “git rm --cached notas-privadas.txt”, que tira do monte sem apagar o arquivo, e confira o status de novo. Colou o bloco 1 sem trocar o nome? Rode de novo com o seu; o novo substitui o anterior.
Bloco 1 · troque o nome e o e-mail antes de rodar:
printf 'notas-privadas.txt\n' > .gitignore
git status
Bloco 3 · salve e confira:
git add README.md .gitignore
git commit -m "Cria README e lista do que não guardar"
git log --oneline
git status
Não fez as aulas anteriores do módulo? Rode isto antes
mkdir -p ~/projetos/treino-git
cd ~/projetos/treino-git
git init -b main
printf '# Treino de Git\n\nPasta para praticar o histórico.\n' > README.md
printf 'ideias soltas, não publicar\n' > notas-privadas.txt
Você acabou de salvar a primeira versão com autoria, com uma mensagem que explica e sem a anotação pessoal.
Cola da aula
Versão com intenção
Autorianome e e-mail só nesta pasta, sem --global.
.gitignorea lista do que nunca entra, criada antes da primeira versão.
Mensagemverbo e objeto: o que mudou.
Seu próximo passo
Você já tem uma versão salva e sabe o que entrou nela.
Hoje, reescreva de cabeça uma mensagem vaga que você já viu, como "ajustes finais", no formato verbo e objeto.
Na próxima aula: e quando o projeto já está no GitHub? Você copia o repositório do curso para o seu computador e atualiza sem estragar nada.
Material complementar · Salve uma versão com intençãoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Configure user.name e user.email localmente para identificar autoria. Prepare os arquivos desejados e use git commit -m com uma descrição concreta. Um commit deve representar uma mudança que você consegue explicar e verificar.
Por que aprender
Mensagens como “update” tornam o histórico pouco útil. Uma versão só é um ponto confiável se você sabe se ela funcionava e quais verificações foram feitas.
Conceitos-chave
Autoria; mensagem; mudança coesa; verificação.
Na prática
“Adiciona instruções para conferir vendas” diz o que mudou. Depois, git log --oneline mostra uma lista compacta dos registros e seus identificadores.
Sequência para experimentar
Prepare uma cópia de treino.
Configure git config user.name "Seu Nome" e git config user.email "seu-email" no treino. Prepare README.md e .gitignore e crie o primeiro commit.
Registre o resultado observado e a próxima correção.
Trabalho
Preparado
Salvo
Três estados, dois comandos. Nada é salvo antes de você preparar e descrever a intenção.
Aula 33 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 6 · Aula 4 de 6
Copie um projeto e atualize com freio
Você consegue copiar o repositório público do curso numa pasta separada, conferir o estado dele e atualizar com git pull --ff-only, sabendo parar quando ele recusar.
Um projeto guardado no GitHub muda enquanto você trabalha. Atualizar por cima de mudanças suas pode misturar tudo. Um comando com freio atualiza quando é seguro e para quando não é.
Em 1 minuto
git clone traz a pasta e todo o histórico para o seu computador.
Antes de atualizar, confira o status.
git pull --ff-only só atualiza pelo caminho direto; se recusar, pare e olhe.
1O clone traz a pasta e o histórico inteiro
A apostila da rede chega como uma cópia completa, com todas as páginas. O clone faz isso com um repositório do GitHub: cria uma pasta nova com os arquivos e todas as versões.
No terminal, basta o endereço e o nome da pasta nova. Clonar não executa nada. Mesmo assim, leia antes de rodar qualquer programa que veio no clone, inclusive de um repositório conhecido.
A rede de ensino guarda os modelos de relatório num repositório público. Denise clonou numa pasta só para isso, longe da pasta dos relatórios dela.
Terminal
$ cd ~/projetos
$ git clone https://github.com/inematds/oswork-v62.git clone-curso
Cloning into 'clone-curso'...$ cd clone-curso
"Cloning into" quer dizer "copiando para". A última palavra da segunda linha é o nome da pasta nova.
Este é o endereço real do repositório deste curso. A pasta clone-curso fica separada da pasta de treino.
2Antes de atualizar, confira o status
Rode git status dentro da pasta clonada. Se ele disser que não há nada seu por salvar, a atualização não tem o que misturar.
Na resposta aparece origin/main: origin é o apelido do endereço de onde a pasta veio, e main é a linha principal de trabalho de lá.
Lúcia clonou o repositório do curso e rodou o status. A resposta dizia que a pasta estava igual à de lá, sem nada dela por salvar.
Terminal
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
"On branch main": você está na linha principal. "Up to date with origin/main": igual à última versão que você trouxe. "Working tree clean": nenhuma mudança sua na pasta.
3pull --ff-only atualiza só pelo caminho direto
O pull busca as versões novas e as junta à sua pasta. Com --ff-only, ele só aceita o caso simples: as versões novas se encaixam depois da última que você tem.
É a apostila que recebe páginas novas no fim. Nada do que você tinha precisa ser mexido.
Uma semana depois, a rede acrescentou um modelo novo. Denise rodou o pull com freio, e a resposta mostrou o arquivo novo que chegou.
Primeira resposta: "já está atualizado", nada chegou. Segunda: "Fast-forward", o caminho direto, com a lista do que chegou.
A segunda resposta é um exemplo de quando há novidade; os códigos e arquivos serão outros.Cinza: versões que você já tinha. Verde: versões novas de lá. Laranja: uma versão sua, salva aqui. No primeiro caso, as verdes se encaixam no fim. No segundo, a linha se abriu em duas.
4Se ele recusar, pare e olhe
Se você salvou uma versão aqui e lá também chegou uma versão nova, as duas linhas se separaram. O --ff-only recusa e não mexe em nada.
Essa recusa é informação, e não um defeito. Não apague o seu trabalho para contornar. Leia o histórico com git log --oneline ou peça ajuda levando a mensagem inteira.
Lúcia tinha salvo, no clone, uma versão com anotações dela, do jeito da aula 3 do módulo. No mesmo dia, o curso publicou uma versão nova. O pull recusou. Ela copiou a mensagem e perguntou no grupo do curso antes de fazer qualquer outra coisa.
Terminal
$ git pull --ff-only
hint: Diverging branches can't be fast-forwarded, you need to either:
hint:
hint: git merge --no-ff
hint:
hint: or:
hint:
hint: git rebase
fatal: Not possible to fast-forward, aborting.$ git status
On branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
A última linha de ajuda foi omitida. "Not possible to fast-forward, aborting": não deu pelo caminho direto e ele parou. O status confirma: uma versão sua e uma de lá.
Se travou aqui, é normalA resposta sugere dois comandos. Não rode nenhum deles agora, nem se um chat de IA mandar: os dois juntam as linhas de jeitos diferentes, e escolher exige ver o histórico. Parar aqui não perde nada, porque o Git não mexeu na sua pasta.
Pratique agora 0/3
Clone o repositório do curso e atualize com freio
Pronto quando o status disser "up to date with 'origin/main'" e o pull responder "Already up to date." Cerca de 8 minutos, no computador e com internet.
O clone vai para uma pasta nova, clone-curso, separada da pasta de treino. Nenhum programa é executado. Se aparecer "destination path 'clone-curso' already exists", você já clonou antes: siga do bloco 2.
Bloco 1 · clone:
cd ~/projetos
git clone https://github.com/inematds/oswork-v62.git clone-curso
Bloco 2 · entre e confira:
cd ~/projetos/clone-curso
git status
git log --oneline -3
Bloco 3 · atualize com freio:
git pull --ff-only
Você acabou de trazer um projeto inteiro do GitHub e de atualizá-lo só pelo caminho seguro.
Cola da aula
Clonar e atualizar
clonepasta nova, com arquivos e histórico, separada das suas.
status antessem mudança sua, não há o que misturar.
pull --ff-onlyatualiza pelo caminho direto; recusou, pare e olhe.
Seu próximo passo
Você já sabe trazer um projeto do GitHub e atualizá-lo sem risco de misturar.
Hoje, abra a pasta clone-curso no gerenciador de arquivos e ache o README. Leia as primeiras linhas antes de abrir qualquer outro arquivo.
Na próxima aula: e quando uma versão que você salvou estava errada? Você desfaz a mudança sem apagar o histórico.
Material complementar · Clone e atualize com cuidadoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
git clone copia um repositório remoto e seu histórico. git pull busca e integra mudanças na branch atual. Antes de atualizar, confira git status. Em um fluxo inicial, git pull --ff-only aceita somente uma atualização direta e para quando os históricos divergiram.
Por que aprender
Atualizar uma pasta com mudanças locais pode gerar conflitos. O bloqueio do --ff-only é informação útil: não o contorne apagando trabalho. Inspecione o histórico ou peça ajuda com o contexto.
Conceitos-chave
Clone cria a pasta; pull atualiza; branch é uma linha de trabalho; divergência pede revisão.
Na prática
Você clonou um projeto ontem e hoje há novas instruções no GitHub. Sem mudanças locais, --ff-only costuma avançar a versão. Com commits diferentes dos dois lados, pare e inspecione.
✓ Faça
Clone o repositório público deste curso em uma pasta separada. Leia antes de executar qualquer programa recebido, inclusive de repositórios conhecidos.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Aula 34 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 6 · Aula 5 de 6
Desfaça um erro sem arrancar a página
Você consegue criar uma segunda versão de treino, desfazê-la com git revert e conferir no próprio README que o título antigo voltou, com as três versões no histórico.
Quando uma versão salva estava errada, a vontade é apagar o registro. Apagar esconde o que aconteceu e pode levar junto trabalho bom. Desfazer com um registro novo corrige e deixa a história completa.
Em 1 minuto
Antes do comando, descubra onde está a mudança: só no arquivo ou numa versão salva.
git revert cria uma versão nova que desfaz a anterior, sem apagar nada.
Confira o arquivo aberto, não só a resposta do terminal.
1Primeiro, descubra onde está a mudança
Cada comando de recuperação do Git tem uma consequência diferente. Por isso a escolha começa por um diagnóstico: a mudança está só no arquivo, numa versão salva no seu computador ou numa versão já enviada ao GitHub?
Denise trocou o título do relatório de setembro e salvou a versão. No dia seguinte, a direção pediu o título antigo de volta. A mudança estava numa versão salva, e isso decidiu o comando.
Onde está a mudança?
1 Só no arquivo, ainda sem salvar
descartar (quadro no fim do passo 4) apaga o que você escreveu, sem volta
2 Numa versão salva no seu computador
desfazer com uma versão nova: esta aula
3 Numa versão já enviada ao GitHub
também com uma versão nova, para não reescrever o que outros já têm
1O caso mais arriscado: não há versão para voltar.
2O caso desta aula.
3Mesmo comando, e mais motivo para não apagar.
2O revert é a errata do jornal
O jornal da escola não recolhe a edição com erro. Publica uma errata que corrige e mostra que houve correção.
O revert faz o mesmo: cria um commit novo que desfaz o anterior. As três versões ficam no histórico: a original, a errada e a correção.
Lúcia mudou a lista de materiais de um roteiro e salvou. Percebeu que tinha apagado o béquer. Com o revert, a lista voltou, e o histórico mostra que houve a troca e a volta.
Arrancar a página
O que faz: apaga a versão errada do histórico.
Risco: some o registro do que houve e pode levar junto trabalho bom.
Errata
O que faz: cria uma versão nova que desfaz a errada.
Resultado: o arquivo volta, e o histórico conta o erro e a correção.
3Confirme qual versão você vai desfazer
O HEAD é o marcador de página do histórico: fica na versão em que você está agora, normalmente a última salva. O comando desta aula desfaz a versão marcada, então olhe antes qual é.
git log --oneline mostra a lista, com a mais nova no topo. Na linha marcada aparece (HEAD -> main): o marcador está aqui, na linha principal.
Na pasta de treino, Lúcia mudou o título do README e salvou uma segunda versão. O log mostrou essa versão no topo, com a marca HEAD.
Terminal
$ git diff
@@ -1,3 +1,3 @@
-# Treino de Git
+# Treino de Git — versão nova
Pasta para praticar o histórico.$ git log --oneline
7ef98be (HEAD -> main) Muda o título do README (treino)
5f6c1eb Cria README e lista do que não guardar
No diff (cabeçalho cortado), a linha com − é o título que saiu e a com +, o que entrou; linhas sem sinal não mudaram. No log, a linha do topo, com HEAD, é a mudança de título: é ela que o revert vai desfazer. Os códigos serão outros no seu computador.
Leia a mensagem da linha do HEAD. Se não for a mudança de treino, não siga.
Se travou aqui, é normalSe a linha do topo não for "Muda o título do README (treino)", pare e não rode o revert. Rode git status e confira se está na pasta treino-git. Parar não custa nada; desfazer a versão errada custaria.
4Desfaça e confira o arquivo aberto
git revert --no-edit HEAD desfaz a última versão e usa uma mensagem automática; sem ele, o Git abriria um editor de texto para você escrever a mensagem. Depois, abra o README e leia o título. A resposta do terminal diz que algo foi feito; o arquivo diz se ficou certo.
Denise rodou o revert no relatório e abriu o arquivo. O título antigo estava de volta, e o log tinha uma linha nova começando com "Revert".
Terminal
$ git revert --no-edit HEAD
[main b11f583] Revert "Muda o título do README (treino)"
1 file changed, 1 insertion(+), 1 deletion(-)$ cat README.md
# Treino de Git
Pasta para praticar o histórico.$ git log --oneline
b11f583 (HEAD -> main) Revert "Muda o título do README (treino)"
7ef98be Muda o título do README (treino)
5f6c1eb Cria README e lista do que não guardar
cat mostra o arquivo: o título voltou. O log tem três linhas: a original, a mudança e a errata.
E se a mudança ainda não estava salva?
Aí o comando é outro: o restore, com o nome do arquivo, descarta as mudanças ainda não separadas com git add. O que você tinha escrito se perde, sem volta. Use só quando tiver certeza, e nunca na pasta inteira. Você também vai achar na internet o reset --hard como solução para tudo: ele apaga mudanças sem volta, e este curso não o usa.
Pratique agora 0/3
Salve uma mudança de treino e desfaça com errata
Pronto quando o README mostrar de novo o título que tinha antes do bloco 1 e o log tiver três linhas, a do topo começando com "Revert". Cerca de 10 minutos, no computador.
Tudo acontece na pasta treino-git e nada sai do computador. O revert não apaga nenhuma versão. Se o log do bloco 1 não mostrar a mudança de treino no topo, não rode o bloco 2. Se o revert responder “Your local changes … would be overwritten”, havia uma mudança sem salvar no README e ele não fez nada: rode “git status” e peça ajuda antes de descartar qualquer coisa.
Antes · confira que não há nada sem salvar (a resposta deve terminar em working tree clean):
cd ~/projetos/treino-git
git status
Bloco 1 · faça a mudança e salve. A primeira linha reescreve o README inteiro, com o título novo (cada \n é uma quebra de linha):
printf '# Treino de Git — versão nova\n\nPasta para praticar o histórico.\n' > README.md
git diff
git add README.md
git commit -m "Muda o título do README (treino)"
git log --oneline
Bloco 2 · só depois de conferir o log:
git revert --no-edit HEAD
cat README.md
git log --oneline
Não fez as aulas anteriores do módulo? Rode isto antes
mkdir -p ~/projetos/treino-git
cd ~/projetos/treino-git
git init -b main
git config user.name "Seu Nome"
git config user.email "seu-email@exemplo.com"
printf '# Treino de Git\n\nPasta para praticar o histórico.\n' > README.md
printf 'notas-privadas.txt\n' > .gitignore
git add README.md .gitignore
git commit -m "Cria README e lista do que não guardar"
Você acabou de desfazer uma versão salva sem apagar nada, e conferiu no próprio arquivo.
Cola da aula
Recuperar sem apagar
Diagnósticosó no arquivo, numa versão salva ou já enviada.
revertversão nova que desfaz a anterior; o histórico fica completo.
Conferênciaabra o arquivo, não confie só na resposta.
Seu próximo passo
Você já sabe desfazer uma versão errada sem esconder que ela existiu.
Hoje, rode git log --oneline na pasta de treino e explique, linha por linha, o que cada versão fez.
Na próxima aula: salvar e desfazer ficou no seu computador. Enviar ao GitHub é outro passo, e tem uma conferência própria.
Material complementar · Recupere sem apagar o históricoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
git revert cria um novo commit que desfaz uma mudança anterior. É adequado para corrigir um registro já compartilhado. git restore descarta mudanças não salvas de arquivos escolhidos; pode perder trabalho. Não ensine reset --hard como resposta automática para qualquer dificuldade.
Por que aprender
Ferramentas de recuperação têm consequências diferentes. Identifique se a mudança está só no arquivo, em commit local ou publicada antes de escolher o comando.
No treino, faça um segundo commit mudando o título do README. git revert HEAD cria um terceiro commit que restaura o título anterior, sem esconder que a mudança ocorreu.
Experimente agora
Use git revert --no-edit HEAD somente após confirmar que HEAD é o segundo commit de treino. Abra o README e confira o resultado, não apenas a mensagem do Git.
Estrutura inicial
Rascunho revisado
Ponto de retorno
Cada commit é um ponto de recuperação. Voltar é andar até um ponto, não apagar a linha.
Aula 35 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 6 · Aula 6 de 6
Enviar é outro passo: confira antes
Você consegue fazer a conferência de quatro pontos antes de um push — destino, estado da pasta, versões que iriam e segredos — e decidir por escrito se enviaria.
Salvar e publicar parecem a mesma coisa, e não são. Quem mistura os dois acaba mandando rascunho ou senha para onde outras pessoas veem. Depois de enviado, o conteúdo fica com quem tem acesso ao destino.
Em 1 minuto
São três passos separados: salvar no computador, enviar ao GitHub e pôr um site no ar.
Antes de enviar: destino, estado, conteúdo e nenhum segredo.
Repositório público: qualquer pessoa vê. Privado: quem tem acesso.
1Salvar, enviar e pôr no ar são três passos
A nota no caderno só você vê. Lançada no sistema da secretaria, todo mundo com acesso vê. Impressa no boletim, vai para as famílias.
No Git é igual. O commit fica no seu computador. O push envia as versões ao GitHub. Pôr um site no ar é uma etapa a mais, que depende da hospedagem.
Lúcia salvou três versões do roteiro de densidade no notebook. Nenhuma saiu dali. Enviar ao GitHub seria uma decisão dela, com conferência própria.
Três passos, três decisões
1 Salvar a versão · fica no seu computador
2 Enviar ao GitHub · quem tem acesso ao destino passa a ver
3 Pôr um site no ar · etapa a mais, conforme a hospedagem
1O caderno: só você.
2O sistema da secretaria: quem tem acesso.
3O boletim: as famílias.
2Confira o destino com git remote -v
Rodado no terminal, o comando mostra para onde a pasta envia. O endereço aparece com o apelido origin. A conta dona está no próprio endereço, logo depois de github.com.
Resposta vazia quer dizer que a pasta não tem destino: um push não teria para onde ir.
Antes de enviar os modelos de relatório, Denise rodou o comando. O endereço apontava para o repositório da rede de ensino, e não para o da coordenação. Ela parou ali.
Terminal
$ cd ~/projetos/treino-git
$ git remote -v
$ cd ~/projetos/clone-curso
$ git remote -v
origin https://github.com/inematds/oswork-v62.git (fetch)
origin https://github.com/inematds/oswork-v62.git (push)
No treino, nada: não há destino. No clone, o destino é a conta inematds, que não é a sua; você não tem permissão para enviar para lá.
"fetch" é de onde a pasta busca; "push" é para onde ela envia. Aqui, o mesmo endereço.
3Confira o estado e as versões que iriam
git status diz se sobrou algo sem salvar. git show --stat mostra a última versão: autor, mensagem e a lista de arquivos que ela mudou.
O push leva todas as versões que o destino ainda não tem, e não só a última. O status diz quantas: up to date with 'origin/main' quer dizer nenhuma; ahead of 'origin/main' by 2 commits quer dizer duas. Sem destino, como no treino, essa linha nem aparece, e iria o histórico inteiro do log.
Lúcia rodou os dois na pasta de treino. O status estava limpo. A última versão era a errata da aula anterior, e só mexia no README.
Terminal
$ git show --stat
commit b11f583e5f52d25a3b67584457953303751f2cc5
Author: Lúcia Andrade <lucia@exemplo.com>
Date: Fri Sep 25 00:38:59 2026 -0300
Revert "Muda o título do README (treino)"
This reverts commit 7ef98be6e53aff1d9381c1126153d7270b9cfd20.
README.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Ignore a linha "commit" com o código longo. "Author" mostra o nome e o e-mail que iriam junto. No fim, "README.md | 2 +-": um arquivo, com uma linha que saiu (−) e uma que entrou (+).
O e-mail configurado na aula 3 do módulo vai junto com cada versão enviada. Se não quiser expor o seu, o GitHub oferece nas configurações um e-mail de privacidade; troque antes do primeiro envio.
4Nenhum segredo, e rascunho só se você decidiu
Olhe só as versões que iriam. Se o status diz que nenhuma iria, não há o que procurar. Nas que iriam, procure senha, chave ou .env na lista de arquivos. Rascunho também conta: se ele está numa versão, vai junto.
Público quer dizer que qualquer pessoa na internet vê. Privado também exige cuidado: quem tem acesso vê tudo.
Denise achou um rascunho com nomes de alunos numa versão antiga da pasta. Não enviou. Pediu ajuda à equipe de tecnologia da escola antes de qualquer envio.
Conferência antes do envio · treino-git
1 Destino: nenhum; a resposta do remote veio vazia
2 Estado: limpo, nada sem salvar
3 Versões que iriam: as três do treino, só README e .gitignore
4 Segredos: nenhum arquivo de senha ou chave
Decisão: não enviar, porque não há destino
Se travou aqui, é normalAchou uma senha numa versão salva? Não envie. Apagar o arquivo agora não tira a senha das versões antigas. Anote qual versão é, pelo log, e peça ajuda a quem administra o projeto antes de qualquer envio.
Pratique agora 0/3
Faça a conferência de quatro pontos e decida
Pronto quando você tiver a conferência preenchida para a pasta de treino e para o clone do curso, cada uma com a decisão e o motivo. Cerca de 10 minutos, no computador. Anote no papel ou no bloco de notas.
Só leitura: nenhum comando desta prática envia nada. Não rode o push. Na pasta de treino não há destino, e no clone a conta não é sua. A opção --no-pager só faz a resposta sair inteira, sem parar a tela. Não fez as aulas anteriores? Use qualquer pasta com histórico que você tenha.
Bloco 1 · pasta de treino:
cd ~/projetos/treino-git
git remote -v
git status
git --no-pager log --oneline
git --no-pager show --stat
Bloco 2 · clone do curso:
cd ~/projetos/clone-curso
git remote -v
git status
git --no-pager show --stat
CONFERÊNCIA ANTES DO ENVIO · <nome da pasta>
1. Destino: <endereço do remote, ou "nenhum">
2. Estado: <limpo, ou o que sobrou sem salvar>
3. Versões que iriam: <o status diz up to date ou ahead by N; sem destino, todas as do log>
4. Segredos: <nenhum, ou qual arquivo>
Decisão: <enviar · não enviar>, porque <motivo>
Veja a conferência do clone preenchida por uma professora
Pasta: clone-curso. 1. Destino: github.com/inematds/oswork-v62, conta do curso. 2. Estado: limpo. 3. Versões que iriam: nenhuma; o status diz up to date with origin/main. 4. Segredos: nenhum meu. Decisão: não enviar, porque a conta de destino não é minha e eu não mudei nada.
Você acabou de separar salvar de enviar, e decidiu com base no que o terminal mostrou.
Cola da aula
Antes de enviar
Três passossalvar, enviar e pôr no ar; cada um com decisão própria.
Quatro pontosdestino, estado, versões que iriam e segredos.
Visibilidadepúblico, qualquer pessoa; privado, quem tem acesso.
Seu próximo passo
Você já tem um ponto de recuperação e sabe conferir antes de mandar qualquer versão para fora do computador.
Hoje, cole o molde da conferência no seu bloco de notas, num lugar fácil de achar. Ele vale para qualquer envio futuro.
No módulo 7: o Telegram vira tela de trabalho, com um bot que responde sem executar mensagens. O token do bot é o primeiro segredo que nunca pode entrar num push.
Material complementar · Publique só o que revisouTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
git push envia commits ao remoto. Antes disso, verifique a conta, a URL de destino, o escopo dos arquivos e a ausência de credenciais. Repositório público fica acessível a terceiros; privado também exige controle de acesso. Publicar um site é uma etapa adicional, conforme a hospedagem.
Por que aprender
Misturar salvar e publicar leva a exposição acidental. Separe “registrar localmente”, “enviar ao GitHub” e “colocar o site no ar” na sua lista de verificação.
Um README local pode conter rascunhos. O commit preserva esses rascunhos na máquina. Só envie quando tiver decidido que podem fazer parte do remoto escolhido.
Experimente agora
Use git remote -v e git status. Confirme a URL e reveja o último commit com git show --stat antes de decidir pelo envio.
Laboratório do módulo: Seu primeiro ponto de recuperação
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Inicialize Git apenas na pasta de treino e configure seu nome e email nesse repositório.
Crie o primeiro commit com arquivos nomeados, depois altere uma linha do README.
Inspecione git diff e faça um segundo commit com essa mudança.
Use git revert no segundo commit, confira o conteúdo restaurado e leia git log --oneline.
Git · somente na pasta de treino
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
Você consegue desenhar o caminho de uma mensagem — celular, Telegram, bot, função permitida, resposta — e marcar a única etapa em que uma IA seria de fato útil.
É comum chamar qualquer resposta automática de agente inteligente. Quando isso se mistura, ninguém sabe o que o bot pode fazer, nem onde ele erra. Separar a porta de quem trabalha deixa cada parte fácil de testar.
Em 1 minuto
O Telegram é a porta: leva a mensagem e traz a resposta.
Quem responde é um programa seu, que só aceita comandos conhecidos.
A IA é uma peça opcional, ligada depois que a base funciona.
1O aplicativo leva e traz; ele não executa
Neste módulo você vai conversar com um bot seu pelo Telegram. O aplicativo no celular só leva a sua mensagem e traz a resposta de volta.
Quem lê, decide e responde é um programa que roda no seu computador. Pense no interfone da portaria: o aparelho leva a voz, mas quem abre o portão é a pessoa lá dentro.
Denise ouviu que outra escola "tem um agente no Telegram". Perguntou o que ele fazia e descobriu três respostas prontas, sem IA nenhuma. O nome prometia mais do que a coisa fazia.
O Telegram faz
Recebe o que você escreve no celular.
Entrega a resposta na mesma conversa.
O seu programa faz
Confere quem escreveu e qual comando é.
Executa só a função permitida e monta a resposta.
As duas partes são necessárias. Só uma delas decide alguma coisa: o programa.
2Sem IA, o bot já é útil
O bot do kit do curso tem dois comandos de trabalho, e nenhum usa IA. O /status confirma que ele está ligado. O /relatorio soma três vendas fictícias do arquivo vendas.csv, uma planilha em CSV.
Você baixa esse kit na próxima aula. Por enquanto, veja o que ele devolve.
Lúcia vai usar o bot para consultar a lojinha fictícia do grêmio: caderno, caneta e agenda. O total vem de uma conta feita pelo programa, não de um palpite.
Telegram · conversa com o bot
Lúcia/status
BotOSWork ativo. Acesso restrito. Bot determinístico de treino.
Lúcia/relatorio
BotDados fictícios de treino: 3 vendas; total R$ 100.00. Sem chamada de IA.
As duas respostas saem de regras fixas do programa. "Determinístico" quer dizer isso: o mesmo pedido dá sempre a mesma resposta.
Estas são as respostas reais do bot do kit. O total usa ponto no lugar da vírgula porque vem do programa assim.
3Mensagem não vira comando no computador
Quem escreve no Telegram não comanda o computador. O bot compara a mensagem com uma lista curta de comandos conhecidos. Todo o resto recebe a mesma resposta padrão.
Isso vale até para a dona do bot. Texto livre nunca é executado como ordem. Os comandos /start e /help existem, mas só mostram a lista dos dois comandos de trabalho.
Denise imaginou um bot da secretaria que recebesse "apague as faltas de ontem". Com a lista fechada, esse texto volta como comando desconhecido, e nada é apagado.
Bot que executa a mensagem
Alguém escreve: "apague a pasta das provas".
Resultado: o computador obedece. Não há volta.
Bot do kit
Alguém escreve: "apague a pasta das provas".
Resultado: "Comando desconhecido. Use /status ou /relatorio."
Saldo: a mesma frase, zero arquivos mexidos no bot do kit.
Teste-se
Um colega diz: "o nosso bot do Telegram é um agente inteligente". O que você pergunta primeiro?
4A IA entra numa etapa, não no caminho todo
Desenhe o caminho inteiro antes de pensar em IA. Depois marque a etapa em que ela ajudaria de verdade.
Uma boa candidata é a função: ela pode ganhar um resumo em texto a partir dos números. A regra é firme: o número continua sendo o do programa.
Lúcia marcou a etapa do resumo. A IA poderia escrever "a agenda foi a venda maior", desde que o total de R$ 100,00 fique como o programa calculou.
Caminho de uma mensagem · bot da Lúcia
1 Celular da Lúcia: ela escreve /relatorio
2 Telegram: leva a mensagem até o bot
3 Bot no computador: confere quem é e qual comando
4 Função permitida (parte do seu programa): soma as vendas
✗ marcado aqui: a IA poderia escrever um resumo, sem mexer no total
5 Resposta: volta pelo Telegram ao celular
1Quem pede.
2A porta.
3O portão: quem decide.
4A execução. O X da IA fica dentro desta caixa.
5A volta.
Se travou aqui, é normalVocê ainda não precisa ter bot nenhum funcionando. Nesta aula o desenho no papel basta. A criação do bot começa na próxima aula, passo a passo.
Pratique agora 0/3
Desenhe o caminho e marque onde a IA entraria
Pronto quando o desenho tiver cinco caixas, quem faz o quê em cada uma e um X numa só etapa. Cerca de 8 minutos, no papel ou no bloco de notas do celular.
Nada aqui mexe no computador nem no Telegram. Ficou em dúvida sobre o X? Marque na função: é nela que se monta o texto que a pessoa vai ler, antes de voltar pelo Telegram.
Veja o desenho de uma coordenadora
Denise desenhou o bot de consulta da secretaria: celular (a mãe pede /horario) → Telegram (leva) → bot (confere se o número está autorizado) → função (lê a planilha de horários) → resposta. O X ficou na função, com a linha: "a IA reescreve o horário em frase simples; o horário continua o da planilha".
Você separou a porta de quem trabalha e sabe dizer onde uma IA entraria sem tomar conta de tudo.
Cola da aula
A porta e quem trabalha
Telegramleva e traz a mensagem; não executa nada.
Botprograma seu que aceita só comandos conhecidos.
IApeça opcional numa etapa, depois que a base funciona.
Seu próximo passo
Você já separa interface, programa e IA quando alguém fala em "agente no Telegram".
Na próxima vez que ouvir falar de um bot no trabalho, faça duas perguntas: que funções ele executa, e qual delas usa IA?
Na próxima aula: criar o seu bot no Telegram e guardar a senha dele num lugar que ninguém vê.
Material complementar · Telegram é a interface, não o agenteTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Um bot recebe mensagens pela API do Telegram e devolve respostas. A inteligência pode vir de regras, de um programa ou de uma chamada a modelo. O aplicativo no celular não executa sozinho suas tarefas no servidor: existe um programa intermediário com permissões definidas.
Por que aprender
Separar interface e execução evita chamar qualquer resposta automática de agente inteligente. Primeiro construa um caminho confiável para receber e responder; depois conecte a capacidade necessária.
Conceitos-chave
Mensagem; Bot API; programa; agente; resultado.
Na prática
/status consulta o estado do bot sem IA. /relatorio calcula vendas fictícias sem IA. Um resumo em linguagem natural poderia ser acrescentado depois, preservando os números calculados.
✓ Faça
Desenhe: celular → Telegram → bot → função permitida → resposta. Marque em que etapa uma futura chamada a IA seria realmente útil.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Telegram
Bot autorizado
Capacidade
O Telegram é a porta. O portão de autorização decide quem passa, e a capacidade é o que de fato executa.
Aula 37 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 7 · Aula 2 de 6
Crie o bot e guarde a chave dele
Você consegue criar o seu bot no BotFather e guardar o token do bot só no arquivo .env. Só a sua conta lê o arquivo, e o token não aparece em print nenhum.
Quem tem o token opera o bot. Um print da conversa ou uma cópia colada num documento bastam para vazar o acesso. Guardar certo no primeiro minuto custa menos do que trocar tudo depois.
Em 1 minuto
O BotFather, conta oficial do Telegram, cria o bot e entrega o token.
O token vai para um lugar só: o arquivo .env, na pasta do bot.
Vazou? Revogue no BotFather antes de continuar.
1O BotFather cria o bot e entrega a chave
Todo bot do Telegram nasce numa conversa com o BotFather. Você envia /newbot, escolhe um nome e um identificador, e ele devolve o token do bot.
O identificador precisa terminar em "bot", como lojinha_gremio_lucia_bot. Se já estiver em uso, o BotFather pede outro. O token é uma linha de números, dois-pontos e letras. Ele funciona como a chave do portão da escola: quem tem a cópia entra, seja quem for.
Lúcia criou o bot da lojinha do grêmio em três mensagens. Antes, conferiu que falava com o BotFather oficial: o @BotFather, com o selo azul de verificado, e não uma conta de nome parecido.
Telegram · conversa com o BotFather
Lúcia/newbot
BotFatherEscolha um nome para o seu bot.
LúciaLojinha do Grêmio
BotFatherAgora escolha um identificador para ele.
Lúcialojinha_gremio_lucia_bot
BotFatherPronto. Este é o token do seu bot: [escondido nesta aula]
O BotFather responde em inglês; aqui as mensagens estão traduzidas e resumidas. O token foi escondido de propósito.
2O token vai para o .env, e só para lá
Na pasta do bot, o kit do curso (link no passo 1 da prática) traz um arquivo de exemplo, o .env.example, só com valores de mentira. Você faz uma cópia chamada .env e cola o token lá dentro.
O .env fica só no seu computador. O token não entra em print, em mensagem, nem em documento compartilhado.
Denise pensou em pôr o token no documento de instruções da secretaria, "para ninguém perder". Mudou de ideia: o documento diz onde o .env fica, nunca o valor.
Token à vista
Colado no documento de instruções da equipe.
Aparece num print enviado ao grupo da escola.
Token no .env
A linha TELEGRAM_BOT_TOKEN é preenchida só no arquivo privado.
O documento diz o caminho do arquivo, não o valor.
Saldo: um lugar para proteger, em vez de vários para vigiar.
3Quatro comandos criam o .env protegido
O kit do curso é o arquivo oswork-kit.zip; o link está no passo 1 da prática. Abra o terminal e entre na pasta bot, dentro do kit descompactado. Copie o exemplo, restrinja a leitura e confira.
O chmod 600 deixa só a sua conta ler e alterar o arquivo. Confira a linha do resultado: ela começa com -rw-------, um r e um w só.
Lúcia rodou os quatro comandos e achou o -rw------- na primeira tentativa. Depois colou o token no arquivo, salvou e fechou sem tirar print.
Terminal
$ cd ~/projetos/oswork-kit/bot
$ cp .env.example .env
$ chmod 600 .env
$ ls -l .env
-rw------- 1 lucia lucia 66 set 25 10:02 .env
Os três primeiros comandos não mostram nada quando dão certo. O último mostra a linha para conferir.
Olhe o começo da linha: -rw-------. Nome, tamanho e data mudam no seu computador.
Se travou aqui, é normalApareceu "No such file or directory"? Você não está na pasta certa. Repita o cd com o caminho de onde descompactou o kit. Se a linha não começa com -rw-------, rode de novo o chmod 600 .env e confira.
4Vazou? Revogue antes de continuar
Se o token apareceu num print, numa mensagem ou num documento, trate como vazado. No BotFather, envie /mybots, escolha o bot, toque em API Token e depois em Revoke current token. Ele gera um token novo, e o antigo para de valer.
Depois, troque o valor no .env. Um link que começa com api.telegram.org/bot e traz o token logo depois também é vazamento.
Numa reunião, Denise viu o print de um colega com o token de um bot à mostra. Avisou na hora. A equipe revogou e trocou o valor no .env em dez minutos.
Pasta bot · onde fica o token
bot
1 .env — o token fica aqui, e só aqui
2 .env.example — continua com o valor de exemplo
3 bot.py — nunca recebe o token colado
4 BotFather › revogar, se vazar
1O único lugar do valor.
2O modelo fica como veio.
3O programa lê o .env sozinho.
4Vazou, revogou, trocou.
Pratique agora 0/5
Crie o seu bot e guarde o token no .env
Pronto quando o ls -l mostrar -rw------- no .env e o token estiver lá dentro, sem ter passado por print ou mensagem. Cerca de 12 minutos, no computador com o terminal e o Telegram no celular.
Você cria um bot novo, só seu, e mexe apenas na pasta do kit. Nenhum comando aqui apaga nada. Se o token aparecer em algum print, pare, revogue no BotFather e refaça o último passo com o token novo.
cd ~/projetos/oswork-kit/bot
cp .env.example .env
chmod 600 .env
ls -l .env
O que é o nano e como ele aparece
O nano abre o arquivo dentro do próprio terminal. Você verá duas linhas: TELEGRAM_BOT_TOKEN=preencha_localmente e ALLOWED_USER_IDS=123456789. Nesta aula, mude só a primeira. A segunda fica para a próxima aula.
Você criou um bot e guardou a chave dele num lugar que só a sua conta abre.
Cola da aula
A chave do bot
BotFather/newbot cria o bot e entrega o token.
.envo único lugar do token, com chmod 600.
Vazourevogue no BotFather e troque no .env.
Seu próximo passo
Você já cria um bot e guarda a chave dele fora de qualquer tela compartilhada.
Anote no seu bloco de notas onde fica o .env do bot: o caminho da pasta, nunca o valor.
Na próxima aula: o bot vai responder só a você. Primeiro, descobrir o seu número de identificação no Telegram.
Material complementar · Crie o bot e proteja o tokenTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
No Telegram, encontre o BotFather oficial e use /newbot. Escolha nome e identificador conforme as instruções mostradas. O token gerado autentica seu programa perante o Telegram. Guarde-o como TELEGRAM_BOT_TOKEN em um arquivo privado; o kit tem apenas valores de exemplo.
Por que aprender
Quem controla o token pode operar o bot. Capturas de tela do processo e URLs contendo o token podem vazar acesso. Se houver exposição, revogue o token no BotFather antes de continuar.
Conceitos-chave
BotFather; token; variável de ambiente; rotação.
Na prática
A professora cria um bot para uso pessoal. Ela não coloca o token no README e não envia o arquivo de credenciais para os alunos. Cada instalação usa suas próprias credenciais.
Experimente agora
Use o modo --identify do kit: ele informa o ID de quem envia /start no terminal local, sem dar acesso às funções operacionais.
Aula 38 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 7 · Aula 3 de 6
O bot confere o documento, não o nome
Você consegue descobrir o seu ID numérico no Telegram com o modo de identificação do kit e colocá-lo na lista de acesso do bot.
Qualquer pessoa pode achar um bot no Telegram e mandar mensagem. O token prova que o programa é o dono do bot, mas não diz quem pode usá-lo. Essa segunda decisão é sua, e fica escrita numa lista.
Em 1 minuto
O token cuida do programa; a lista de acesso cuida das pessoas.
O bot confere o ID numérico, que não muda, e não o nome que aparece.
Três portões antes de responder: conversa privada, ID na lista, comando conhecido.
1Token e lista de acesso são controles diferentes
O token do bot prova ao Telegram que o seu programa é o dono do bot. Ele não diz nada sobre quem pode conversar com ele.
Por isso o kit tem um segundo controle: a lista de acesso. É como a lista de quem pode buscar cada aluno na saída da escola.
Denise explicou assim à equipe: a chave abre o portão; a lista da saída diz quem leva cada aluno. São duas conferências, e uma não substitui a outra.
Token do bot
Prova que o programa é o dono do bot.
Fica no .env, na linha TELEGRAM_BOT_TOKEN.
Lista de acesso
Diz quais pessoas o bot atende.
Fica no mesmo .env, na linha ALLOWED_USER_IDS.
Os dois são necessários. O primeiro autentica o programa; o segundo autoriza gente.
2O nome muda; o número fica
O nome que aparece na conversa, a pessoa troca quando quiser. O bot confere o ID numérico, que o Telegram dá a cada conta.
Para descobrir o seu, o kit tem um modo só de identificação. No celular, o bot não responde nada nesse modo: o número aparece no terminal.
Lúcia aparece no Telegram como "Lúcia Ciências". Se mudar para "Prof. Lúcia", o bot continua reconhecendo: o número dela é o mesmo.
Terminal · pasta bot
$ python3 bot.py --identify
Identificação apenas: envie /start em privado; confira seu ID abaixo e encerre com Ctrl+C. Nenhuma função operacional ativa.
ID recebido na identificação: 7012345678
^C
Bot encerrado.
A linha do ID só aparece depois que você manda /start ao bot, numa conversa privada. O número aqui é fictício; o seu será outro.
Copie o número da linha "ID recebido". O ^C é o Ctrl+C que encerra o modo.
3Três portões antes de qualquer resposta
Antes de responder, o programa confere três coisas, nesta ordem. Quem falha nos portões 1 ou 2 não recebe nem um "não": o bot fica calado. No portão 3, a resposta é só "Comando desconhecido".
Essa conferência fica no começo da função handle_message, dentro do bot.py.
Denise quis testar o bot da Lúcia. Mandou /relatorio e não recebeu nada. Não era defeito: o número dela não estava na lista.
bot.py · antes de responder
1 É conversa privada? Grupo: silêncio.
2 O ID está na lista de acesso? Fora dela: silêncio.
3 O comando é /status ou /relatorio? (/start e /help só mostram a lista.) Outro texto: "Comando desconhecido."
4 Só então executa a função daquele comando.
1Onde a mensagem chegou.
2Quem mandou, pelo número.
3O que foi pedido.
4A resposta, e nada além dela.
Veja as duas linhas do bot.py que fazem os portões 1 e 2
if message.get('chat',{}).get('type')!='private':return None
if message.get('from',{}).get('id') not in allowed:return None
"return None" quer dizer: não responda nada. Para achar essas linhas no seu computador, rode grep -n "allowed" bot.py na pasta bot.
4O seu número entra na lista do .env
Com o número em mãos, encerre o modo de identificação com Ctrl+C. Abra o .env e troque o 123456789, que é só o exemplo do kit, pelo seu ID.
Para autorizar mais de uma pessoa, separe os números com vírgula. Comece só com você.
Lúcia pensou em incluir a colega da biblioteca. Deixou para depois do teste: com menos gente na lista, fica mais fácil conferir.
Lista do exemplo
ALLOWED_USER_IDS=123456789
Ninguém real está na lista. O bot fica calado até com você.
Lista da Lúcia
ALLOWED_USER_IDS=7012345678
O mesmo número que apareceu no terminal dela, no passo 2. Só ela recebe respostas.
O 123456789 vem no kit e o 7012345678 é fictício. No seu .env vai o número que o seu terminal mostrar.
Se travou aqui, é normalO terminal não mostrou número nenhum? Confira três coisas: você mandou /start numa conversa privada com o bot, e não num grupo; o token no .env é o do bot certo; o modo de identificação ainda estava rodando quando você mandou.
Pratique agora 0/4
Descubra o seu ID e coloque na lista de acesso
Pronto quando a linha ALLOWED_USER_IDS do .env tiver o seu número, e não o do exemplo. Cerca de 8 minutos, no computador, com o celular na mão.
O modo de identificação não responde nem executa nada: só mostra o número no terminal. Apareceu "Configure TELEGRAM_BOT_TOKEN no .env privado"? O token ainda não está no .env: faça a aula 2 deste módulo (aula 38), que cria esse arquivo na pasta projetos/oswork-kit/bot.
cd ~/projetos/oswork-kit/bot
python3 --version
O python3 --version deu erro ou versão antiga
O bot do kit é escrito em Python e precisa da versão 3.10 ou mais nova. Se aparecer "command not found" ou um número menor, o Python precisa passar por uma instalação pela fonte oficial antes de continuar: python.org/downloads mostra a versão para Windows e Mac. No Linux, o Python 3 costuma vir junto com o sistema.
Você decidiu, por número, quem o seu bot atende.
Cola da aula
Quem o bot atende
Tokenprova que o programa é o dono do bot.
ID numéricoo bot confere o número, não o nome.
Três portõesprivado, na lista, comando conhecido.
Seu próximo passo
Você já decide quem o bot atende e sabe por que ele fica calado com os outros.
Anote no bloco de notas quem você autorizaria no futuro e por quê. Não autorize ainda.
Na próxima aula: ligar o bot de verdade e receber /status e /relatorio no celular.
Material complementar · Autorize pessoas e açõesTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
O bot do kit aceita apenas conversas privadas e IDs configurados. Também aceita somente os comandos conhecidos. Verificar o ID é diferente de verificar o nome visível: nomes podem mudar. Uma mensagem de desconhecido não deve acionar leitura de arquivos ou comandos do sistema.
Por que aprender
Um bot encontrado na internet pode receber mensagens inesperadas. Autenticação do programa com token não significa autorização de qualquer pessoa que fale com ele. São controles distintos.
Conceitos-chave
ID numérico; lista de acesso; conversa privada; comandos fixos.
Na prática
O dono escreve /relatorio e recebe totais fictícios. Um usuário fora da lista não recebe dados. Mesmo o dono não pode escrever um comando de shell e esperar que o bot o execute.
Sequência para experimentar
Prepare uma cópia de treino.
Leia a função handle_message do kit. Localize a conferência de ID e chat privado antes do despacho dos comandos.
Registre o resultado observado e a próxima correção.
Aula 39 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 7 · Aula 4 de 6
O bot vai ao escaninho e espera
Você consegue ligar o bot com long polling, receber /status e /relatorio no celular e conferir o total com o arquivo de vendas do kit.
Existem dois jeitos de um bot receber mensagens, e misturar os dois gera erros difíceis de entender. Começar pelo mais simples deixa você testar tudo no seu computador, sem abrir porta nenhuma para a internet.
Em 1 minuto
Long polling: o bot pergunta ao Telegram se chegou mensagem e espera um pouco.
O outro jeito, o webhook, fica para depois.
Um programa só por token: dois ao mesmo tempo disputam as mensagens.
1O bot vai buscar as mensagens e espera um pouco
No long polling, o programa pergunta ao Telegram se chegou mensagem nova. Se não chegou, espera até 25 segundos e pergunta de novo.
É como passar no escaninho da sala dos professores e ficar um instante, caso chegue um bilhete. O webhook seria o carteiro tocando a campainha, e exige um endereço seu na internet.
Lúcia deixou o bot ligado no notebook, em casa. Não precisou mexer em nenhuma configuração de rede: o programa sai para buscar, e ninguém precisa entrar.
Long polling · o bot pergunta
O programa vai até o Telegram buscar as mensagens.
Funciona no seu computador, sem endereço público.
Webhook · o Telegram avisa
O Telegram chama um endereço seu na internet.
Exige esse endereço público. Não é usado neste módulo.
Os dois funcionam. Este módulo usa só o primeiro, que é o do kit.
2Ligue com um comando e deixe o terminal aberto
No terminal, na pasta bot, rode python3 bot.py. Nenhuma linha aparece, e esse é o sinal certo: o programa está esperando.
O terminal precisa ficar aberto. Fechou a janela ou apertou Ctrl+C, o bot para de responder.
Denise estranhou a tela parada e quase fechou o terminal. Lúcia explicou: tela sem linha nova é o bot trabalhando; linha nova costuma ser aviso.
Terminal · pasta bot
$ python3 bot.py
^CBot encerrado.
O espaço vazio é o bot esperando mensagens: o cursor fica parado até você apertar Ctrl+C.
"Bot encerrado." confirma que você desligou de propósito.
3Mande os dois comandos e confira o total
Com o bot ligado, mande /status e /relatorio na conversa privada. A resposta do /relatorio traz a soma das vendas fictícias.
Confira essa soma no próprio arquivo, o vendas.csv, uma planilha em CSV. Um total que bate com o arquivo é um resultado verificado, não uma impressão.
Lúcia somou no papel: caderno 35,50, caneta 9,50 e agenda 55,00. Deu 100,00, o mesmo número do bot.
Telegram · conversa com o bot
Lúcia/status
BotOSWork ativo. Acesso restrito. Bot determinístico de treino.
Lúcia/relatorio
BotDados fictícios de treino: 3 vendas; total R$ 100.00. Sem chamada de IA.
Três vendas, R$ 100.00: o programa escreve com ponto, mas é o mesmo R$ 100,00 da soma do arquivo abaixo.
35,50 + 9,50 + 55,00 = 100,00. O arquivo não tem segredo nenhum; pode abrir à vontade.
Rode o cat antes de ligar o bot: com o bot ligado, o terminal fica ocupado até o Ctrl+C.
4Um programa só para cada bot
Mantenha um único programa buscando mensagens para cada bot. Dois ao mesmo tempo, com o mesmo token do bot, disputam as mensagens, e o Telegram recusa.
O kit percebe o conflito e se desliga sozinho. O aviso sai no log, que aparece no próprio terminal, sem mostrar o token.
Lúcia ligou o bot em casa, esquecendo que ele seguia ligado no notebook da escola. O de casa parou com o aviso abaixo. No dia seguinte, ela desligou o da escola com Ctrl+C e religou o de casa.
Terminal · aviso de conflito
2026-09-25 19:40:12,381 WARNING Falha HTTP 409 no Telegram; sem detalhes que exponham token.
2026-09-25 19:40:12,382 ERROR Confira token, instância duplicada ou webhook; processo encerrado para diagnóstico.
409 quer dizer conflito. Quase sempre é outra cópia do bot ligada. O "webhook" do aviso só vale para bots antigos, configurados de outro jeito; o seu, novo, não tem.
Data e hora mudam. O que importa é o número 409 e a palavra "instância duplicada", que quer dizer outra cópia ligada.
Se travou aqui, é normalViu o 409 e não sabe onde está o outro programa? Procure outra janela de terminal aberta ou outro computador em que você ligou o bot. Desligue todos com Ctrl+C e ligue só um.
Pratique agora 0/4
Ligue o bot e confira o total
Pronto quando o /relatorio mostrar o mesmo total da sua soma e, com o bot desligado, o /status ficar sem resposta. Cerca de 10 minutos, no computador e no celular.
O bot só lê o vendas.csv, com dados fictícios, e não muda nada no computador. Apareceu "Falha HTTP 401"? O token do .env está errado ou foi revogado: refaça o passo do token na aula 2 deste módulo (aula 38). Nenhuma resposta no celular? Confira o seu ID numérico na lista de acesso, como na aula 3 deste módulo (aula 39).
cd ~/projetos/oswork-kit/bot
cat vendas.csv
Você ligou um bot seu, conversou com ele pelo celular e conferiu a resposta contra o arquivo.
Cola da aula
O bot que busca
Long pollingo bot pergunta e espera até 25 segundos.
Tela paradasem linha nova é o bot esperando.
Um por tokendois ligados disputam, e o kit se desliga.
Seu próximo passo
Você já liga o bot, conversa com ele pelo celular e confere a resposta contra o arquivo.
Amanhã, ligue o bot por dois minutos, peça /relatorio e desligue. Ligar, testar e desligar é o hábito que vai para a VPS no módulo 8.
Na próxima aula: onde uma IA poderia entrar nesse bot sem estragar o total.
Material complementar · Comece com long pollingTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Long polling é o programa perguntar ao Telegram por mensagens e esperar um pouco quando não há novidades. É simples para aprender e não exige abrir uma porta pública de entrada. Webhook é outra estratégia, em que o Telegram chama um endereço HTTPS seu; não é necessária neste laboratório.
Por que aprender
Escolher um único modo reduz problemas de configuração. Mantenha uma única instância buscando mensagens para um bot: processos duplicados podem disputar atualizações.
Conceitos-chave
getUpdates; offset; timeout; instância única; acesso de saída.
Na prática
O processo aguarda até 25 segundos por uma mensagem. Ao recebê-la, atualiza o offset para não repetir a mesma consulta. Após uma falha de rede, espera antes de tentar de novo.
✓ Faça
Inicie com python3 bot.py. Use Ctrl+C para encerrar. Se surgir conflito, confira se outro processo usa o mesmo token ou se existe webhook configurado.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
Long polling — o bot pergunta
Webhook — o servidor avisa
Comece pelo long polling: não exige endereço público nem certificado para funcionar.
Aula 40 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 7 · Aula 5 de 6
A IA escreve o parecer; a nota é do programa
Você consegue escrever um contrato de integração em cinco linhas e testar no chat que o resumo feito pela IA não muda o total calculado.
Ligar uma IA a um bot parece o passo natural, mas cada ligação abre um caminho novo para erro e custo. Um bot previsível já é útil. A IA só entra onde melhora algo que você consegue medir.
Em 1 minuto
Primeiro o bot sem IA, testado; depois a capacidade nova.
A IA recebe dados mínimos e nunca muda o número calculado.
Antes de ligar, escreva o contrato de integração: cinco linhas.
1Primeiro a base testada, depois a IA
O kit separa de propósito o caminho das mensagens, que é o Telegram, das funções de trabalho. E começa sem IA: status e relatório de dados fictícios.
Um bot previsível você testa sem gastar nada. Só depois vale perguntar se a IA melhora a interpretação, o resumo ou a classificação.
Denise queria um bot de dúvidas da secretaria "com IA desde o começo". Mudou o plano: primeiro um /horario que só lê a planilha; a IA ficou para uma segunda etapa, com teste.
Tudo de uma vez
O bot novo já chama uma IA para tudo.
Quando erra, ninguém sabe se foi o programa ou a IA.
Em etapas
Etapa 1: bot sem IA, testado com /status e /relatorio.
Etapa 2: uma função com IA, comparada com o resultado da etapa 1.
Saldo: um erro de cada vez para investigar.
2A nota é calculada; o parecer só comenta
No boletim, a nota vem da conta e o parecer escrito comenta. O parecer nunca muda a nota.
Com o bot é igual. A IA pode escrever um resumo, mas o total vem do programa e não pode mudar no texto.
Lúcia imaginou um /resumo para a lojinha do grêmio. A IA receberia só o total e os três produtos, e não a pasta inteira dos projetos dela.
Chat de IA
VocêDados: 3 vendas; total R$ 100,00; caderno R$ 35,50; caneta R$ 9,50; agenda R$ 55,00.
Escreva um resumo de duas linhas.
IAAs vendas somaram cerca de R$ 110, com destaque para a agenda.
Inventou um total que não existe. Esse texto não pode sair pelo bot.
VocêUse só estes dados. Não altere nenhum número e não acrescente dados.
Dados: 3 vendas; total R$ 100,00; caderno R$ 35,50; caneta R$ 9,50; agenda R$ 55,00.
Escreva um resumo de duas linhas.
IAForam 3 vendas, com total de R$ 100,00. A agenda respondeu por R$ 55,00, a maior parte.
O total é o do programa, e nenhum dado novo apareceu.
Toque nos dois botões e compare o total de cada resumo.
3Cinco linhas antes de ligar qualquer IA
Escreva o contrato de integração: os dados enviados, o modelo disponível, o limite de custo, o tempo máximo e o que acontece quando a IA falha.
A última linha é a mais esquecida. Com ela, o bot segue útil mesmo quando a IA não responde.
Denise escreveu o contrato do /horario em cinco minutos. Na linha da falha pôs: "sem IA, o bot manda a linha da planilha como está".
Contrato de integração · /horario da secretaria
1 Dados enviados: a linha da turma pedida, e nada além
2 Modelo: o que estiver disponível na conta da escola
3 Limite de custo: até R$ 5 por mês
4 Tempo máximo: 20 segundos por resposta
5 Se a IA falhar: manda a linha da planilha como está
1O mínimo que a tarefa precisa.
2O que você tem acesso de verdade.
3Quanto pode gastar.
4Quanto pode esperar.
5O plano B, sem IA.
Os valores de custo e tempo são de exemplo. Você define os seus.
Teste-se
O /resumo com IA já funciona. Numa manhã, a IA não responde. O contrato diz, na linha 5: "se a IA falhar, manda só o total". O que o bot faz?
4A mensagem nunca vai direto para um agente
Não ligue um agente como o Codex às mensagens que chegam pelo bot. E não desligue proteções só para a integração funcionar.
A IA recebe uma entrada curta, montada pelo programa, e devolve texto. Quem decide o que fazer com esse texto continua sendo o programa.
Lúcia leu num fórum a dica de ligar o Codex direto no bot, "para ele fazer qualquer coisa". Não seguiu: qualquer coisa inclui apagar a pasta dela.
Mensagem direto no agente
Quem escreve no Telegram manda o agente agir no computador.
Uma frase maldosa vira uma ação.
Função com entrada curta
O programa monta a entrada: o total e três produtos.
A IA devolve texto; o programa confere se o total é o que ele calculou e só então envia.
Se travou aqui, é normalVocê não vai programar a integração neste módulo: o kit não tem essa parte, de propósito. A prática é escrever o contrato e testar a regra do número no chat que você já usa.
Pratique agora 0/3
Escreva o contrato e teste a regra do número
Pronto quando o contrato tiver as cinco linhas e o resumo do chat mantiver o total de R$ 100,00, sem dado novo. Cerca de 10 minutos, no chat que você já usa e no bloco de notas.
Os dados são os fictícios do kit, e nada é enviado ao bot. Se a IA mudar um número, isso não é falha sua: é o risco que o contrato cobre. Anote e reforce a frase "não altere nenhum número".
Use só estes dados. Não altere nenhum número e não acrescente dados.
Dados: 3 vendas; total R$ 100,00; caderno R$ 35,50; caneta R$ 9,50; agenda R$ 55,00.
Tarefa: escreva um resumo de duas linhas para <a equipe da lojinha do grêmio>.
No fim, repita o total exatamente como veio.
Veja o contrato de uma professora
1. Dados enviados: o total e os três produtos com valor. 2. Modelo: o que estiver disponível na minha conta. 3. Limite de custo: até R$ 2 por mês. 4. Tempo máximo: 15 segundos. 5. Se a IA falhar: o bot manda só a linha do /relatorio, como hoje.
Você definiu, antes de ligar, o que a IA recebe, quanto custa, quanto espera e o que acontece se ela falhar.
Cola da aula
IA em etapas
Base primeirobot sem IA, testado, antes de qualquer ligação.
Número intocávela IA comenta; o total vem do programa.
Contratodados, modelo, custo, tempo e plano de falha.
Seu próximo passo
Você já sabe onde uma IA entra no bot sem pôr em risco o número calculado.
Guarde o contrato junto das anotações do bot. O mesmo molde serve para qualquer consulta do seu trabalho.
Na próxima aula: testar o bot antes de confiar nele, inclusive quando algo dá errado.
Material complementar · Conecte capacidades em etapasTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
O kit deliberadamente separa transporte e funções de trabalho. Começa determinístico: status e relatório de dados fictícios. Para acoplar IA, defina uma função com entrada limitada, timeout, teto de saída e revisão. Não exponha codex exec diretamente a mensagens públicas nem desative proteções para fazê-lo funcionar.
Por que aprender
Um programa previsível permite testar a base sem gastar API. Depois, você avalia se a IA melhora interpretação, resumo ou classificação e mede o resultado com uma referência conhecida.
Conceitos-chave
Função de domínio; limites; timeout; revisão; dados mínimos.
Na prática
Uma função de resumo pode receber apenas o total e três categorias, em vez de todo o diretório de projetos. O texto gerado nunca altera o total calculado pelo programa.
Experimente agora
Escreva um contrato de integração: dados enviados, modelo disponível, limite de custo, tempo máximo e ação quando a IA falhar. O bot base permanece útil sem essa extensão.
Aula 41 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 7 · Aula 6 de 6
Passe o som antes da reunião
Você consegue rodar o autoteste do bot e quatro testes reais no Telegram, registrando o que foi simulado e o que foi testado de verdade.
Uma resposta certa não prova que o bot está restrito, nem que ele se recupera de uma falha. Poucos cenários, testados de propósito, mostram isso antes de o bot ir para uma máquina que fica ligada sem você.
Em 1 minuto
O autoteste roda 11 cenários sem token e sem internet.
No Telegram, teste o que a simulação não alcança: você, um estranho, um comando qualquer, o bot desligado.
No registro, separe simulado de testado no Telegram.
1O autoteste simula 11 cenários sem internet
O kit traz um autoteste. O bot roda mensagens de mentira contra as próprias regras, sem token e sem internet.
Ele cobre acesso, grupo, comando desconhecido, a soma e arquivos de vendas com defeito. Mas não prova que o seu bot conversa com o Telegram.
Denise perguntou se o bot da Lúcia obedecia a estranhos. Lúcia mostrou a linha final do autoteste e anotou que ainda faltava o teste real, com uma pessoa de fora da lista.
Uma linha só, começando com OK. Se aparecer um erro longo, algum cenário falhou.
"Offline" quer dizer sem internet. É simulado: vai no registro como simulado.
2No Telegram, teste o que a simulação não alcança
É como passar o som antes da reunião de pais: você testa o microfone com o auditório vazio. Quatro testes reais bastam: o seu /status, uma frase qualquer, uma pessoa fora da lista e o bot desligado. Se o bot desligado ainda responde, existe outra cópia ligada em algum lugar. Se fica calado, quem respondia antes era o programa do seu computador.
Anote cada teste no bloco de notas, com a origem: simulado ou Telegram. Assim ninguém confunde "passou no teste" com "funciona no celular". Ao religar o bot, ele pode responder ao /status que ficou esperando; isso é esperado.
Lúcia pediu à Denise que mandasse /relatorio ao bot. Nada voltou, como esperado. No registro, escreveu: "fora da lista, Telegram, sem resposta".
4 /relatorio da Denise, fora da lista · Telegram · sem resposta
5 /status com o bot desligado · Telegram · sem resposta
1O que a simulação garante.
2A dona é atendida.
3Texto livre não vira ação.
4Estranho não recebe nada.
5Sem o programa, sem resposta.
3Cada sintoma aponta para um lugar
Quando algo falha, o sintoma diz onde olhar. Não troque o modelo de IA: /status e /relatorio nem usam IA.
Se só o /relatorio falha, o problema está no arquivo de vendas, o vendas.csv, uma planilha em CSV. Se nada responde, confira o programa, o token, a internet e a lista de acesso.
Denise viu a Lúcia receber "Não foi possível validar vendas.csv". Em vez de culpar a IA, Lúcia abriu o arquivo: tinha apagado a linha do cabeçalho sem querer.
Só o /relatorio falha
O bot diz: "Não foi possível validar vendas.csv. Confira o arquivo local; nenhum total foi inventado."
Onde olhar: o arquivo de vendas.
Nada responde
O bot diz: nada.
Onde olhar: o programa está ligado? O token está certo? Há internet? O seu ID numérico está na lista de acesso? Leia o terminal.
Repare no fim da primeira mensagem: com o arquivo errado, o bot prefere não dar total a inventar um.
4O log conta o erro sem contar o segredo
Numa falha de rede, o bot tenta de novo sozinho. Num conflito (409) ou com o token errado (401), ele se desliga para você investigar. O log do kit diz o tipo de falha e o horário. Ele não mostra o token do bot nem o texto das mensagens.
No mesmo registro do bloco de notas, anote cada falha assim: o que falhou, quando e o que você fez. É esse registro que vai com o bot para a VPS no módulo 8.
Lúcia desligou o wi-fi com o bot ligado, de propósito. O terminal mostrou avisos de nova tentativa, e o bot voltou sozinho quando a rede voltou.
Terminal · bot ligado, rede desligada
2026-09-25 20:05:31,114 WARNING Falha de rede ou resposta; nova tentativa em 2 segundos.
2026-09-25 20:05:33,120 WARNING Falha de rede ou resposta; nova tentativa em 4 segundos.
2026-09-25 20:05:37,131 WARNING Falha de rede ou resposta; nova tentativa em 8 segundos.
Cada tentativa espera o dobro da anterior, até 60 segundos. Nenhuma linha mostra o token.
WARNING é aviso, não desastre: o bot continua tentando sozinho.
Se travou aqui, é normalNão tem quem mande a mensagem de fora da lista? Anote "não testado no Telegram" e siga: o autoteste já cobre esse caso de forma simulada. O registro honesto vale mais que um registro completo inventado.
Pratique agora 0/4
Passe o som do seu bot e registre
Pronto quando o registro tiver o autoteste e os testes no Telegram, cada um marcado como simulado ou Telegram. Cerca de 12 minutos, no computador e no celular.
Os testes só leem dados fictícios; nada é apagado. A pessoa fora da lista não recebe dado nenhum. Não fez as aulas 2 a 4 deste módulo (38 a 40)? Rode só o autoteste: ele funciona sem token, na pasta bot do kit.
cd ~/projetos/oswork-kit/bot
python3 bot.py --self-test > autoteste.txt
cat autoteste.txt
Molde do registro, preenchido por uma coordenadora
Denise testou o bot de consultas que montou para treinar: Autoteste · simulado · 11 cenários aprovados /status meu · Telegram · "OSWork ativo…" "bom dia" · Telegram · "Comando desconhecido…" /relatorio de fora da lista · não testado no Telegram · coberto pelo autoteste /status com o bot desligado · Telegram · sem resposta
Você testou o bot antes de precisar dele e sabe dizer o que foi simulado e o que foi real.
Sintomasó o /relatorio: arquivo; nada: programa, token, rede, lista.
Seu próximo passo
Você fechou o módulo 7: tem um bot restrito, testado, que responde sem executar mensagens.
Quando tiver uns 30 minutos, abra o material complementar e faça o laboratório do módulo: são os mesmos passos das aulas 2 a 6 deste módulo, de uma vez.
No próximo módulo: VPS do zero. O bot ligado o dia inteiro, sem depender do seu computador.
Material complementar · Teste operação e falhasTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
Teste remetente permitido, bloqueado, grupo, comando desconhecido e dados ausentes. Logs devem informar tipo de falha e horário, sem token nem mensagens privadas completas. No laboratório, desligar o processo deve parar as respostas: isso prova que o programa local está no caminho.
Por que aprender
Uma resposta correta não prova que o bot está restrito nem que recupera rede. Um conjunto pequeno de cenários demonstra as propriedades importantes antes de migrar para uma VPS.
Conceitos-chave
Autoteste; falha de rede; logs sem segredo; interrupção; diagnóstico.
Na prática
Se /status funciona e /relatorio falha, investigue o arquivo de dados. Se nenhum funciona, confira processo, autenticação e conexão. Não troque o modelo: esses comandos nem usam IA.
Experimente agora
Execute --self-test e guarde a saída. Depois teste a conversa real com sua conta; diferencie no registro o que foi simulado e o que foi testado no Telegram.
Laboratório do módulo: Um bot que responde sem executar mensagens
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Leia materiais/bot/README.md e rode o autoteste offline do bot, sem token.
Crie seu bot no BotFather oficial e guarde o token somente no .env local.
Descubra seu ID com o modo de identificação local e configure a lista de acesso.
Inicie o bot, envie /status e /relatorio na conversa privada e confira os resultados.
Bot · dentro de materiais/bot
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
python3 bot.py --self-test
cp .env.example .env
chmod 600 .env
# Edite .env localmente; nunca compartilhe valores.
python3 bot.py --identify
# Preencha ALLOWED_USER_IDS com seu ID e encerre identificação.
python3 bot.py
Critério de pronto
Executar um bot restrito de consulta e entender onde a IA entra. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
Uma mensagem do Telegram pode ser passada diretamente para o shell?
Ver resposta comentada
Não. O bot deve mapear comandos permitidos a funções definidas e verificar o remetente.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
Resumo do módulo
Mensagem; Bot API; programa; agente; resultado.
BotFather; token; variável de ambiente; rotação.
ID numérico; lista de acesso; conversa privada; comandos fixos.
getUpdates; offset; timeout; instância única; acesso de saída.
Função de domínio; limites; timeout; revisão; dados mínimos.
Autoteste; falha de rede; logs sem segredo; interrupção; diagnóstico.
Consulte a fonte
Ferramentas verificadas em 20/09/2026; nomes de telas e disponibilidade podem mudar.
Você consegue preencher a primeira parte do plano de VPS: o que precisa rodar, quem cuida, quanto pode custar, qual sistema e como desligar. Tudo antes de contratar qualquer coisa.
Contratar uma VPS leva poucos minutos. Descobrir depois que ninguém cuida dela, ou que a conta chega todo mês sem uso, custa bem mais. Por isso o plano vem antes da compra.
Em 1 minuto
A VPS é um computador alugado, ligado o tempo todo. Quem administra é você.
Máquina ligada não é o mesmo que serviço funcionando.
Antes de contratar: o que roda, quem cuida, quanto custa e como desligar.
1Uma VPS é um computador que você aluga e administra
Pense numa sala alugada. O dono do prédio entrega a sala com luz e porta. O que acontece lá dentro é com você.
A VPS funciona assim. É um servidor virtual alugado, com memória, disco e rede, numa empresa chamada provedor da VPS. Usuários, atualizações e programas ficam por sua conta.
O bot de treino de Denise, do módulo 7, só responde enquanto o notebook dela está ligado. Às seis da tarde ela fecha a tampa, e o bot para de responder no Telegram.
No notebook
Quando roda: só com a tampa aberta.
Quem cuida: você, sem perceber.
Na VPS
Quando roda: o tempo todo, no provedor da VPS.
Quem cuida: você, de propósito: usuários, atualizações e programas.
Os dois servem. A VPS resolve o "só com a tampa aberta" e traz uma responsabilidade nova.
2Máquina pequena basta: o modelo roda longe
Comece com uma máquina pequena, compatível com o programa que vai rodar. Um bot que chama um modelo de IA pela API não precisa de placa de vídeo cara.
O modelo remoto roda nos computadores do provedor da IA. A VPS só envia o pedido e recebe a resposta.
Lúcia quase contratou uma VPS com placa de vídeo para um bot de médias fictícias da turma. O bot só envia pedidos e mostra respostas; a placa ficaria parada, e a conta, alta.
Exagero
Escolha: o plano mais forte, com placa de vídeo, "para garantir".
Resultado: conta alta todo mês para um bot que quase não trabalha.
Na medida
Escolha: uma máquina pequena, que roda o bot com folga.
Resultado: o modelo de IA continua no provedor da IA; a VPS só faz a ponte.
Saldo: o tamanho da máquina segue o programa, não a fama do modelo.
3Três contas separadas
A VPS, o espaço extra de disco e a API de IA são cobrados separadamente. Assinar uma não paga a outra.
A mensalidade da VPS chega todo mês, com a máquina trabalhando ou parada. É a mesma lógica da aula sobre acesso e cobrança, no módulo 1: cada acesso tem a sua conta. Anote o limite de cada uma.
Denise montou a lista antes de falar com a direção. A mensalidade da VPS entrou numa linha. O bot de treino não usa IA, então a linha da API ficou com "não usa".
De onde sai cada custo
1 VPS
mensalidade do plano: [valor do plano escolhido]
2 Armazenamento
disco extra e cópias guardadas: [valor, se houver]
3 API de IA
por consumo, na plataforma da IA: não usa
1A máquina alugada, cobrada todo mês, ligada ou parada.
2O espaço para guardar dados e cópias.
3O modelo de IA, só se o programa usar.
4O plano vem antes da compra
Uma máquina ligada não quer dizer um serviço saudável. O bot pode parar lá dentro e ninguém perceber.
Antes de contratar, decida duas coisas: o que precisa rodar sem parar e quem vai verificar quando algo der errado. Anote também o sistema: os exemplos do curso usam o Ubuntu.
Denise preencheu a primeira parte do plano de operação do kit do curso. A linha que mais demorou foi a última: onde fica o botão de cancelar e quem pode apertar.
plano-vps.md · Antes de contratar
1 Trabalho que precisa continuar sem o notebook: bot de treino respondendo /status
2 Responsável técnico: Denise
3 Orçamento mensal de VPS: [limite aprovado pela direção]
4 Orçamento separado para API: não usa
5 Sistema operacional suportado: Ubuntu, na versão com suporte do provedor da VPS
6 Plano de desligamento: painel do provedor da VPS › cancelar; só Denise
As seis linhas da primeira parte do plano. A linha 6, o desligamento, é a que mais falta nos planos reais.
Teste-se
Denise vai colocar o bot de treino numa VPS. Qual decisão vem antes de escolher o plano?
Se travou aqui, é normalVocê não precisa contratar nada nesta aula, nem saber o preço exato. Onde faltar um dado, escreva "a definir" e o nome de quem decide. O plano já serve assim.
Pratique agora 0/3
Preencha a primeira parte do plano de VPS
Pronto quando as seis linhas tiverem uma resposta ou "a definir" com um nome ao lado. Cerca de 8 minutos, no computador ou no celular.
Nada é contratado nesta aula. Sem o kit, copie o molde numa nota do celular. Não anote senha nem dado de cartão no plano.
Onde está o plano: o arquivo plano-vps.md vem no kit do curso, o oswork-kit.zip da página de materiais do OSWork. O plano tem cinco partes: Antes de contratar, Acesso, Serviço, Verificações observadas e Rotina. Hoje você preenche a primeira; as outras vêm nas próximas aulas.
PLANO DE OPERAÇÃO · ANTES DE CONTRATAR
Trabalho que precisa continuar sem o notebook: <ex.: bot de treino respondendo /status>
Responsável técnico: <seu nome ou de quem vai cuidar>
Orçamento mensal de VPS: <valor máximo por mês>
Orçamento separado para API, se usada: <valor ou "não usa">
Sistema operacional suportado: <ex.: Ubuntu, versão com suporte>
Plano de desligamento do recurso: <onde cancelar e quem pode>
Veja o molde preenchido por uma professora
Trabalho: bot que responde a média fictícia da turma, fora do horário de aula. Responsável técnico: Lúcia. Orçamento mensal de VPS: a definir, com a coordenação. API: não usa. Sistema: Ubuntu, versão com suporte. Desligamento: painel do provedor da VPS; Lúcia e a coordenação.
Você acabou de decidir o que a VPS precisa fazer, quem responde por ela e como encerrar a conta.
Cola da aula
Sala alugada
VPScomputador alugado; quem administra é você.
Tamanhosegue o programa; o modelo de IA roda no provedor da IA.
Plano anteso que roda, quem cuida, quanto custa, como desligar.
Seu próximo passo
Você já sabe dizer se precisa de uma VPS, de que tamanho e quem responde por ela.
Leve a linha do orçamento a quem aprova gastos no seu trabalho e peça o limite mensal por escrito. Uma mensagem de três linhas basta.
Com a sala alugada, a primeira porta é a de entrada. Próxima aula: entrar na VPS pela internet sem se trancar do lado de fora.
Material complementar · Uma VPS é uma máquina sob sua responsabilidadeTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
VPS é um servidor virtual alugado: um computador remoto com memória, disco e rede. Você administra usuários, atualizações e processos. Comece com uma máquina pequena compatível com a aplicação; não contrate GPU apenas para chamar um modelo por API. O modelo remoto roda na infraestrutura do provedor.
Por que aprender
Uma máquina ligada não significa um serviço saudável. Custos de VPS, armazenamento e API são separados. Antes de contratar, defina o que precisa rodar continuamente e quem verificará incidentes.
Um bot pequeno que consulta dados fictícios não precisa da mesma infraestrutura que um modelo local. A gestora estima carga, orçamento e disponibilidade antes de escolher o plano.
✓ Faça
Preencha materiais/plano-vps.md. Registre sistema operacional, forma de acesso, limite mensal, responsável e forma de desligar o recurso.
✗ Evite
Aceitar uma conclusão sem conferir a entrada que a sustenta.
Aula 43 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 8 · Aula 2 de 6
Não devolva a chave velha antes de testar a nova
Você consegue dizer em que máquina está pelo que o terminal mostra e aplicar a regra da segunda sessão: testar a entrada nova antes de fechar a que funciona.
Quem troca a fechadura de casa testa a chave nova antes de jogar fora a velha. Na VPS é igual. Mudar a rede ou o jeito de entrar sem uma rota de volta pode trancar você do lado de fora.
Em 1 minuto
SSH abre o terminal da VPS no seu computador, por uma conexão protegida.
Confira em que máquina você está antes de cada comando.
Teste uma segunda sessão antes de fechar a primeira.
1SSH abre o terminal da VPS no seu computador
O SSH cria uma conexão protegida para administrar a máquina. O comando ssh usuario@ip-da-vps abre a sessão.
As partes usuario e ip-da-vps são campos para trocar, não valores reais. O endereço da VPS aparece no painel do provedor da VPS.
Lúcia abriu duas janelas de terminal e se confundiu: numa estava o notebook, na outra a VPS. O nome no começo da linha e o comando pwd mostraram onde ela estava.
Depois de entrar, o começo da linha muda: agora ele mostra o usuário e o nome da VPS. O comando pwd responde a pasta em que você está.
Antes de qualquer comando, olhe o começo da linha. Ele diz em que máquina você está.
2Chave no lugar da senha, identidade conferida
Use a chave pública cadastrada do jeito que o provedor da VPS indica. A chave privada nunca sai do seu computador. Ao contratar, o painel do provedor guia a criação e o cadastro; nesta aula você não precisa criar nenhuma.
Na primeira conexão, o SSH mostra a impressão digital da máquina. Ela confirma que você chegou à VPS certa.
Denise recebeu a pergunta em inglês na primeira entrada. Antes de digitar yes, comparou a impressão digital com a que o painel do provedor mostrava.
Terminal · primeira conexão
$ ssh usuario@ip-da-vps
The authenticity of host 'ip-da-vps' can't be established.
ED25519 key fingerprint is SHA256:[impressão digital].
Are you sure you want to continue connecting (yes/no/[fingerprint])?
Em português: "não dá para confirmar a identidade desta máquina; a impressão digital é esta; quer continuar?". Responda yes só se ela bater.
Essa pergunta aparece uma vez por máquina. Se aparecer de novo para a mesma VPS, pare e investigue.
3Um usuário de trabalho, com sudo quando precisa
Trabalhe com um usuário seu, o usuário de trabalho. Quando uma tarefa pedir permissão de administrador, ponha sudo na frente do comando.
Assim o poder de administrador aparece só onde você pediu, e fica visível no comando.
Lúcia conferiu o próprio usuário antes de mexer em qualquer coisa. O mesmo comando com sudo mostrou o administrador, depois de pedir a senha dela.
Terminal · na VPS
$ whoami
usuario$ sudo whoami
[sudo] password for usuario:
root
whoami responde "quem sou eu". Sem sudo, é o usuário de trabalho; com sudo, é root, o administrador da máquina.
Ao digitar a senha, nada aparece na tela. É normal: ela está sendo lida.
4A segunda sessão é a sua rota de volta
Antes de mudar a rede ou o jeito de entrar, deixe a sessão original aberta. Abra outra janela e teste a nova entrada. Só feche a primeira quando a segunda funcionar.
Se tudo falhar, o console de recuperação ainda abre a máquina. Confira que ele funciona antes de restringir qualquer coisa.
Um tutorial sugeriu a Denise trocar a porta do SSH, uma mudança comum em guias de segurança. Antes de seguir, ela abriu o console pelo painel do provedor e anotou no plano que ele funcionava.
Sessão 1 · chave velha
Estado: aberta, funcionando.
Regra: não fechar enquanto a sessão 2 não entrar.
Sessão 2 · chave nova
Estado: outra janela, testando a mudança.
Regra: entrou? Aí sim feche a sessão 1.
Saída de emergência: o console do provedor, conferido antes de qualquer mudança.
Se travou aqui, é normalVocê não precisa ter uma VPS para esta aula. A prática é um caso para analisar no papel. Quando alugar a sua, volte a este passo e siga as três rotas na ordem.
Pratique agora 0/3
Analise o caso da porta trocada
Pronto quando você tiver respondido as três perguntas e conferido no gabarito. Cerca de 8 minutos; anote no papel ou no bloco de notas.
É um caso, sem máquina real, então nada quebra. Tem uma VPS de treino? Faça também o teste de verdade: com a sessão aberta, abra outra janela e entre de novo com o mesmo comando ssh. Não mude porta nem jeito de entrar só para treinar.
O caso. Rogério, um colega de Denise, alugou uma VPS de treino. Entrou por SSH e colou um comando da internet que troca a porta do SSH. Executou e fechou o terminal na hora. Na volta, ssh rogerio@ip-da-vps não conecta mais. Ele nunca abriu o console do provedor.
Ver gabarito
1. A segunda sessão. Ele devia manter a primeira aberta e testar a nova porta numa outra janela antes de fechar.
2. Pelo console de recuperação, no painel do provedor da VPS. Por lá, ele desfaz a troca de porta.
3. Na parte Acesso do plano de VPS (a segunda das cinco partes do plano-vps.md): "Porta SSH real", "Segunda sessão SSH testada" e "Console de recuperação disponível", com a data do teste.
Você acabou de achar o erro que tranca uma pessoa fora da própria VPS, e a rota de volta.
Cola da aula
Duas chaves
Onde estouo começo da linha e o pwd dizem a máquina.
Identidadechave pública cadastrada; impressão digital conferida uma vez.
Rota de voltasessão 1 aberta, sessão 2 testada, console conferido.
Seu próximo passo
Você já sabe entrar numa VPS sem perder o caminho de volta.
No plano de VPS, preencha a parte Acesso: usuário de trabalho, porta real e onde fica o console. Onde não souber, escreva "a conferir no painel".
Lá dentro, a máquina vem quase vazia. Próxima aula: o que colocar nela, e o que deixar de fora.
Material complementar · Entre por SSH e preserve acessoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
SSH cria uma conexão protegida para administrar a máquina. Use a chave pública cadastrada conforme o provedor e confira a identidade do servidor. Crie um usuário de trabalho com permissões administrativas quando necessário. Mantenha a sessão original aberta enquanto testa uma segunda conexão.
Por que aprender
Mudar firewall ou autenticação sem testar uma rota de recuperação pode bloquear seu próprio acesso. O console do provedor é a alternativa quando a conexão normal falha; confira que ele funciona antes de restringir a rede.
O comando ssh usuario@ip-da-vps abre a sessão. usuario e ip-da-vps são campos para substituir, não valores reais. O nome do prompt e pwd ajudam a confirmar em qual máquina você está.
Experimente agora
Teste a segunda sessão antes de encerrar a primeira. Não desative login ou altere porta SSH seguindo um comando sem saber como recuperar acesso.
Aula 44 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 8 · Aula 3 de 6
Mala de mão: só o que a viagem pede
Você consegue conferir no terminal se Python 3 e Git estão na máquina e criar a pasta de projetos, sem colocar mais nada.
Cada programa a mais é mais uma coisa para atualizar, explicar e consertar. Colocar ferramentas por hábito dá trabalho e não aumenta o que o serviço consegue fazer.
Em 1 minuto
Na VPS com Ubuntu, quem coloca e atualiza programas é o apt.
Antes de confirmar uma atualização, leia a lista do que vai mudar.
O bot de treino precisa de Python 3; o Git ajuda a levar o projeto.
1Atualize a lista e leia antes de confirmar
Os exemplos usam Ubuntu com apt. Primeiro, sudo apt update atualiza a lista do que existe para a máquina. Depois, sudo apt upgrade propõe as atualizações e espera a sua resposta.
O sudo na frente pede a permissão de administrador, como na aula anterior.
Na VPS de treino, Denise parou na pergunta final e leu a lista inteira. Só depois respondeu Y.
Terminal · na VPS
$ sudo apt update
Reading package lists... Done$ sudo apt upgrade
The following packages will be upgraded:
[lista de programas que vão mudar]
Do you want to continue? [Y/n]
A pergunta final quer dizer "quer continuar?". O Y maiúsculo é a resposta padrão. Leia a lista acima dela antes de responder.
Um programa que você não reconhece na lista é motivo para pesquisar antes de responder Y.
2O bot de treino pede só duas coisas
O bot do kit do curso precisa do Python 3. O Git ajuda a levar o projeto do seu computador para a VPS. O comando fica sudo apt install git python3.
O bot usa só o que já vem com o Python, sem nenhum complemento extra. Outras ferramentas, como o Codex, são opcionais: entram só se o programa pedir.
Um tutorial sugeriu a Lúcia instalar cinco ferramentas "para garantir". Ela conferiu o que o bot pedia e ficou com duas.
Por hábito
Na máquina: Git, Python 3 e mais três ferramentas "porque um dia pode precisar".
Resultado: cinco coisas para atualizar; três sem uso.
Na medida
Na máquina: Git e Python 3.
Resultado: duas coisas para atualizar, e as duas trabalham.
Saldo: três ferramentas a menos para manter, sem perder nada do que o bot faz.
3Confira as versões e crie a pasta
Pergunte a versão de cada programa. Se ele responde, está na máquina. Depois crie a pasta projetos na sua pasta pessoal, na conta de trabalho.
Os comandos de versão só leem. O de criar pasta não apaga nada: se a pasta já existe, ele a deixa como está.
Lúcia rodou os mesmos comandos no notebook, antes de alugar qualquer VPS. Os dois responderam. Ela anotou as versões no plano, para conferir as mesmas na VPS.
Terminal
$ python3 --version
Python 3.x.y$ git --version
git version 2.x.y$ mkdir -p ~/projetos
$ ls -d ~/projetos
/home/usuario/projetos
Onde está x.y, aparece o número da versão da sua máquina. O último comando confirma que a pasta existe.
Quatro comandos, nenhum muda o sistema. O sinal ~ quer dizer "a minha pasta pessoal".
Se travou aqui, é normalSe aparecer "command not found", ou no Mac uma janela oferecendo as ferramentas de linha de comando, o programa não está na máquina. Não é erro seu. Anote "falta" no plano: é exatamente o que a VPS vai precisar receber. No Windows, rode no terminal do WSL, do módulo 3.
Pratique agora 0/3
Confira Python e Git e crie a pasta de projetos
Pronto quando você tiver a resposta dos dois comandos de versão e a pasta projetos existir. Cerca de 8 minutos, no computador, no terminal.
Nenhum comando daqui muda o sistema: dois só leem a versão, o outro cria uma pasta vazia. Não rode a atualização do apt no computador do trabalho só para treinar. No Windows, use o terminal do WSL, preparado no módulo 3: no PowerShell estes comandos respondem diferente. Tem uma VPS de treino? Rode os mesmos comandos nela.
python3 --version
git --version
mkdir -p ~/projetos
ls -d ~/projetos
Você acabou de conferir o que a máquina tem e de decidir o que ela precisa, sem colocar nada por hábito.
Cola da aula
Mala de mão
aptupdate atualiza a lista; upgrade propõe e espera o seu Y.
Só o necessárioo bot de treino pede Python 3; o Git leva o projeto.
Conferir--version responde se está na máquina.
Seu próximo passo
Você já consegue decidir o que entra numa máquina e conferir se entrou.
Olhe a lista de programas do seu computador de trabalho e marque dois que você não usa há meses. Só marque; não precisa remover.
Com o bot lá dentro, falta a portaria. Próxima aula: quem pode entrar na VPS, e onde guardar a senha do bot.
Material complementar · Instale só o necessárioTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Os exemplos do laboratório usam Ubuntu com apt. Atualize a lista de pacotes e revise a atualização proposta. O bot base precisa de Python 3; Git ajuda a transferir o projeto. Node, Docker e Codex são opcionais conforme a aplicação, não uma lista obrigatória para qualquer VPS.
Por que aprender
Cada dependência acrescenta manutenção. Um serviço simples, com poucas peças, é mais fácil de explicar, atualizar e recuperar. Instalar ferramentas por hábito cria trabalho sem aumentar a capacidade necessária.
Conceitos-chave
apt update; apt upgrade; dependência; ambiente virtual quando necessário.
Na prática
Sequência de referência: sudo apt update, sudo apt upgrade, sudo apt install git python3. O bot do kit usa somente a biblioteca padrão, sem instalar pacotes Python externos.
Sequência para experimentar
Prepare uma cópia de treino.
Antes de confirmar a atualização, leia os pacotes envolvidos. Confira python3 --version e git --version, depois crie ~/projetos na conta de trabalho.
Registre o resultado observado e a próxima correção.
Aula 45 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 8 · Aula 4 de 6
A portaria da VPS: quem entra, quem sai
Você consegue listar as portas de rede que a sua VPS precisa abrir. E consegue deixar um arquivo .env legível só por você, conferindo no terminal.
Abrir tudo "para funcionar" aumenta o risco e não encontra a causa do problema. E um .env que qualquer usuário da máquina lê deixa a senha do bot à vista.
Em 1 minuto
O firewall é a portaria: decide o que entra e o que sai.
O bot de treino só sai para perguntar ao Telegram. Nenhuma porta de bot aberta.
O .env fica fechado (chmod 600) e fora do Git.
1O firewall é a portaria da máquina
O firewall filtra as conexões de rede, nos dois sentidos. É como a portaria da escola: tem a lista de quem pode entrar, e o carteiro sai para buscar a correspondência.
O bot do kit usa long polling. Ele sai por uma conexão segura para perguntar ao Telegram se chegou mensagem. Ninguém de fora precisa bater na porta dele.
Lúcia achou que precisava abrir uma porta para o bot receber as mensagens da turma. Não precisava: quem entra na máquina é só ela, pelo SSH.
Com long polling, a única porta de entrada que a VPS precisa é a do SSH.
2Libere o SSH antes de ligar o firewall
No Ubuntu, o ufw configura o firewall. Antes de ligá-lo, libere a porta do SSH que a sua VPS realmente usa. Se for a 22, a regra é a do exemplo. Se for outra, o número muda.
Alguns provedores têm um firewall próprio no painel. Se o seu tiver, confira lá também que a porta do SSH está liberada.
Denise só ligou o firewall depois de preparar as rotas de volta da aula anterior sobre SSH: a segunda sessão testada e o console do provedor conferido. O próprio ufw a avisou do risco.
Depois do primeiro sinal vêm três trios: dono, grupo e outros. r é ler, w é alterar, traço é "não pode". Antes, o grupo e os outros liam (rw- e r--). Depois, só o dono tem rw.
O que importa é o começo: -rw------- quer dizer "só o dono".
4Rede, token e processo: três checagens separadas
Se o bot não responde, não abra portas para ver se resolve. Separe três perguntas: o processo está rodando? O token foi aceito? A rede de saída funciona?
O log do bot do kit ajuda a separar, sem mostrar o token.
O bot de Denise parou. O log dizia "Falha HTTP 401": era o token, trocado na semana anterior. Nenhuma porta precisava mudar.
Bot parado · o que o log diz
1 Nenhuma linha nova: o processo está rodando? (próxima aula)
2 "Falha HTTP 401 no Telegram; sem detalhes que exponham token."
3 "Falha de rede ou resposta; nova tentativa em 2 segundos."
1Processo: confira se ele está ligado.
2Token: o Telegram recusou a senha do bot.
3Rede: a saída falhou e o bot tenta de novo sozinho.
Se travou aqui, é normalNão tem VPS nem bot rodando? Sem problema. A prática é no seu computador, numa pasta de treino, com um .env vazio. O ufw fica para quando você tiver a máquina.
Pratique agora 0/3
Feche um .env de treino e liste as portas
Pronto quando o ls -l mostrar -rw------- no .env de treino e o plano tiver as portas necessárias. Cerca de 8 minutos, no computador, no terminal.
O arquivo é criado vazio, numa pasta nova, só para treinar: não tem token nenhum. Não mexa no .env de um bot que já funciona. No Windows, rode no terminal do WSL, do módulo 3: fora dele o -rw------- pode não aparecer; não é erro seu, volte ao WSL. Se o chmod der erro, confira com pwd se você está na pasta treino-rede.
mkdir -p ~/treino-rede
cd ~/treino-rede
touch .env
ls -l .env
chmod 600 .env
ls -l .env
Você acabou de fechar um arquivo de segredos para só você ler e de reduzir a portaria ao mínimo.
Cola da aula
Portaria
Entradasó a porta real do SSH, liberada antes de ligar o firewall.
Saídao bot pergunta ao Telegram; nenhuma porta de bot.
.envchmod 600, conferido com ls -l, fora do Git.
Seu próximo passo
Você já sabe decidir o que entra na VPS e proteger o arquivo de senhas do bot.
Procure, no seu computador de trabalho, um arquivo com senha anotada fora de um gerenciador de senhas. Anote onde está e decida para onde ele vai.
A portaria está pronta, mas o bot ainda depende de você para ligar. Próxima aula: quem liga o bot sozinho e o religa quando ele cai.
Material complementar · Proteja a rede e as credenciaisTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
Firewall filtra conexões de rede. Para long polling, o bot precisa sair para HTTPS; não precisa expor uma porta de bot à internet. Antes de ativar UFW, libere a porta SSH realmente usada e confira regras locais e do provedor. Restrinja o .env com chmod 600 e deixe-o fora do Git.
Por que aprender
Abrir todas as portas para “fazer funcionar” amplia o risco sem diagnosticar a causa. Se o processo não responde, rede de saída, token e execução merecem checagens distintas.
Conceitos-chave
Entrada e saída; porta SSH; regra de firewall; permissões de arquivo.
Na prática
Se SSH usa a porta 22, sudo ufw allow 22/tcp pode ser apropriado. Se usa outra porta, a regra precisa mudar. Só execute sudo ufw enable após testar a configuração e o acesso de recuperação.
✓ Faça
Liste portas realmente necessárias no plano. Registre quais comandos variam por provedor e nunca trate o exemplo de porta como universal.
✗ Evite
Misturar a cópia de treino com arquivos privados ou trabalho em produção.
SSH com chave
Firewall
Credenciais fora do repo
Rotina de cuidado
Proteção é camada, não comando único. A rotina de cuidado é a que mais falta.
Aula 46 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 8 · Aula 5 de 6
O zelador do bot: liga, religa e anota
Você consegue adaptar os quatro campos da unidade do kit e ler, no status e no log, se o bot está rodando.
Um bot rodando numa sessão SSH pode parar quando você fecha a conexão. A supervisão liga o bot junto com a máquina e guarda os registros num lugar só. Ela não substitui alertas, limites nem a busca da causa.
Em 1 minuto
O systemd liga o bot com a máquina e o religa depois de uma falha.
A unidade diz qual programa, com qual usuário e em qual pasta.
Religar não conserta erro que se repete: leia o log e pare para diagnosticar.
1Na sessão aberta, o bot depende da janela
Até aqui, você ligou o bot à mão, com python3 bot.py no terminal. Na VPS, isso amarra o bot à sua conexão.
O systemd é o zelador da máquina: acende as luzes toda manhã, religa o que apagou e anota tudo no livro de ocorrências.
Denise deixou o bot rodando numa sessão SSH e foi para casa. A conexão caiu no caminho, e o bot parou junto.
Na sessão aberta
Liga: quando você digita o comando.
Se a conexão cai: o bot pode parar junto.
Registro: some com a janela.
Com systemd
Liga: sozinho, junto com a máquina.
Se o bot falha: religa depois de 15 segundos.
Registro: guardado pelo systemd, para ler depois.
Saldo: o bot deixa de depender da sua janela aberta.
2A unidade diz o quê, com quem e onde
A unidade do kit é o arquivo oswork-bot.service, na pasta bot. Quatro campos precisam do seu usuário e do seu caminho: User, WorkingDirectory, EnvironmentFile (onde está o .env) e ExecStart.
O campo Restart=on-failure religa o bot depois de uma falha. No kit, o usuário de exemplo é oswork; o usuário e as pastas precisam existir na VPS.
Lúcia trocou oswork pelo usuário de trabalho dela nos quatro campos. Depois mostrou só essas linhas na tela para conferir.
Assim vem o kit. As quatro primeiras linhas são as que você adapta; a última você mantém.
User é quem roda o bot. WorkingDirectory é a pasta. EnvironmentFile é o .env. ExecStart é o comando que liga.
3Ligue e confira o status
Na VPS, a unidade adaptada vai para a pasta do systemd, /etc/systemd/system, com permissão de administrador. Depois, três comandos ligam o bot. O systemctl relê as unidades, liga o bot e mostra o estado dele.
O sudo aparece nos dois primeiros porque eles mudam a máquina. O terceiro só lê.
Denise viu "active (running)" no status. Mesmo assim, só deu o passo por concluído depois de mandar /status no Telegram e receber a resposta.
Terminal · na VPS
$ sudo cp oswork-bot.service /etc/systemd/system/
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now oswork-bot
$ systemctl status oswork-bot --no-pager
● oswork-bot.service - OSWork bot de treino restrito
Active: active (running) since [data e hora]
A primeira linha copia a unidade. O daemon-reload faz o systemd reler as unidades. "active (running)" quer dizer "ativo, rodando". O enable --now liga agora e deixa ligado para os próximos reinícios.
Rodando é o primeiro sinal. A prova é o bot responder.
Telegram · conversa com o bot
Você/status
BotOSWork ativo. Acesso restrito. Bot determinístico de treino.
A resposta real do bot do kit ao /status.
4Reinício controlado e leitura do log
Faça um reinício de propósito, com systemctl restart, e mande /status de novo. Anote o horário. Depois leia o log com o journalctl.
Religar não conserta um erro que se repete. Se o bot cai de novo, pare o serviço e procure a causa antes de insistir.
No log, Lúcia viu a parada e a volta do bot, com hora. Em outro dia, viu "processo encerrado para diagnóstico" e parou o serviço antes de tentar de novo.
Stopped e Started: parou e ligou, com data e hora. Com o bot funcionando, ele não escreve mais nada.
Se aparecer uma linha terminando em "processo encerrado para diagnóstico", pare com sudo systemctl stop oswork-bot e leia a linha inteira.
Se travou aqui, é normalOs passos 3 e 4 precisam de uma VPS com o bot. Sem ela, a prática desta aula é só a unidade, no seu computador. Guarde os comandos: eles vão estar no plano quando a máquina existir.
Pratique agora 0/3
Adapte a unidade do kit ao seu usuário
Pronto quando o grep mostrar o seu usuário e o seu caminho nos quatro campos. Cerca de 10 minutos, no computador, com um editor de texto e o terminal.
Você edita um arquivo de texto, sem ligar nada: sem VPS, nada roda. Trabalhe numa cópia descompactada do kit. Errou? Descompacte de novo. No Windows, faça tudo no terminal do WSL, do módulo 3.
Onde está a unidade: no kit do curso, o oswork-kit.zip da página de materiais do OSWork. Descompacte em ~/projetos/oswork-kit: a unidade fica em ~/projetos/oswork-kit/bot. No Windows, o zip baixa na pasta Downloads; no WSL, traga com cp /mnt/c/Users/SeuNome/Downloads/oswork-kit.zip ~/projetos/ e depois cd ~/projetos e unzip oswork-kit.zip -d oswork-kit. O caminho que vem no kit é o do repositório do curso; troque pelo lugar onde o bot vai morar na VPS. No molde fica /home mesmo, também no Mac: é o caminho da VPS.
Cole no arquivo, no lugar das quatro linhas do kit:
User=<seu usuário de trabalho>
WorkingDirectory=/home/<usuário>/projetos/oswork-kit/bot
EnvironmentFile=/home/<usuário>/projetos/oswork-kit/bot/.env
ExecStart=/usr/bin/python3 /home/<usuário>/projetos/oswork-kit/bot/bot.py
Rode no terminal, para conferir:
cd ~/projetos/oswork-kit/bot
grep -E "^(User|WorkingDirectory|EnvironmentFile|ExecStart)=" oswork-bot.service
Você acabou de preparar a instrução que deixa o bot ligado sem depender da sua janela.
Cola da aula
Zelador
UnidadeUser, WorkingDirectory, EnvironmentFile e ExecStart com o seu usuário e caminho.
Ligardaemon-reload, enable --now, status, e /status no Telegram.
Falhou de novoleia o journalctl e pare antes de repetir.
Seu próximo passo
Você já sabe entregar o bot a um zelador que liga, religa e anota.
No plano de VPS, preencha a parte Serviço: caminho de trabalho, comando, nome da unidade, arquivo de variáveis e política de reinício.
Ligado e religado ainda não é cuidado. Última aula: a rotina que prova que o serviço se recupera, e o fim do curso.
Material complementar · Systemd supervisiona o processoTexto completo do tópico no OSWork v2. Não conta no tempo da aula.
O que é
systemd é o gerenciador de serviços de muitas distribuições Linux. Uma unidade descreve qual programa iniciar, com qual usuário e em qual pasta. Restart=on-failure reinicia após uma falha, mas não corrige um erro persistente. O kit fornece uma unidade parametrizada para o usuário oswork.
Por que aprender
Executar o bot numa sessão SSH pode encerrar o trabalho ao fechar a conexão. Supervisão permite reiniciar com a máquina e centralizar logs. Ela não substitui alertas, limites ou análise da causa.
Conceitos-chave
Unidade; usuário de serviço; diretório; reinício; journal.
Na prática
Depois de adaptar caminhos, use sudo systemctl daemon-reload e sudo systemctl enable --now oswork-bot. Consulte systemctl status e journalctl -u oswork-bot -n 50 --no-pager.
Experimente agora
Faça um reinício controlado com systemctl restart, confira /status e registre o horário. Se falhar, pare o serviço antes de ficar repetindo tentativas sem diagnóstico.
Pasta local
Repositório
VPS
systemd
O mesmo trabalho, quatro lugares. O systemd é o que faz a rotina sobreviver a um reinício.
Aula 47 · OSWork v6.2 · INEMA.CLUB PRO
Módulo 8 · Aula 6 de 6
Simulado de incêndio: só vale o que foi ensaiado
Você consegue fazer um backup do vendas.csv, o arquivo de dados do bot de treino. Depois, restaurar a cópia numa pasta separada e provar, com um comando e com o total, que ela está inteira.
Sem ninguém olhando, um serviço pode ficar parado por dias. Sem teste de restauração, a cópia pode estar incompleta, e você só descobre no dia em que precisa dela. A promessa real é uma rotina que se recupera, não uma máquina que nunca falha.
Em 1 minuto
Operar é uma rotina: supervisão, atualização, checagem de fora, cópias e restauração testada.
Backup só vale depois de restaurado e conferido.
O projeto fecha com cinco evidências, e o que não foi feito é declarado.
1Máquina ligada não é serviço funcionando
O systemd religa o bot, mas não avisa ninguém se ele ficar calado. Por isso existe a checagem externa: alguém, de fora da VPS, confere se o serviço responde.
Uma verificação diária simples registra duas coisas: se o bot respondeu e quanto espaço sobra no disco. Na VPS, o comando df -h / mostra o espaço usado.
Denise manda /status pelo celular toda manhã, antes da reunião das oito. Anota a hora da resposta e, uma vez por semana, o espaço em disco.
Verificação diária · [data]
1 /status pelo Telegram: respondeu às [hora]
2 Espaço em disco: [percentual] usado
3 Conferido por: Denise
1De fora: se o celular recebe a resposta, o caminho inteiro funciona.
2Disco cheio para qualquer serviço; melhor ver antes.
3Um nome: a checagem é de alguém.
2Cópia fora da máquina, segredo fora da cópia
Guarde as cópias dos dados fora da VPS: por exemplo, uma pasta protegida no Drive da escola ou um disco externo. Se a máquina some, a cópia não pode ir junto. Defina também a retenção: por quanto tempo cada cópia fica guardada.
O .env com o token do bot tem tratamento privado. Ele não entra numa cópia que outras pessoas acessam.
Lúcia guardava a cópia dos dados da turma na mesma VPS. Passou a guardar num lugar protegido, fora dela, com três cópias mensais. O .env ficou de fora.
Na mesma VPS
Onde: uma pasta ao lado do bot.
Se a máquina some: a cópia some junto.
Segredo: o .env foi junto na cópia.
Fora da VPS
Onde: um lugar externo e protegido.
Se a máquina some: os dados voltam.
Segredo: o .env tratado à parte; retenção de três meses escrita no plano.
Saldo: perder a VPS deixa de ser perder os dados.
3Backup só vale depois do ensaio
Um simulado de incêndio prova que a escola sai do prédio. O teste de restauração prova que a cópia volta. Um backup só está validado quando você restaurou e conferiu o conteúdo.
O bot de treino do módulo 7 soma os valores de vendas.csv, um arquivo de vendas fictícias, quando recebe /relatorio. O teste mensal restaura esse arquivo numa pasta separada e compara com o original. O diff mostra as diferenças; se não mostra nada, os dois são iguais.
No primeiro teste, a cópia de Denise estava vazia: o comando de cópia apontava para a pasta errada. O ensaio achou o erro antes de uma perda real.
O diff não respondeu nada: a cópia é igual ao original. Some os valores: 100,00, o mesmo total que o /relatorio do bot mostra.
Duas provas: o diff em silêncio e o total conferido à mão.
Se travou aqui, é normalO silêncio do diff parece que "não aconteceu nada". É o contrário: ele só fala quando acha diferença. Se aparecer "No such file or directory", a pasta ou o nome da cópia estão diferentes; confira com ls.
4Cinco evidências fecham o projeto
O projeto do curso termina com cinco evidências: resposta autorizada, bloqueio de desconhecido, reinício, log sem token e restauração conferida.
Sem uma segunda conta no Telegram, o bloqueio de desconhecido pode ser provado pelo teste do kit, python3 bot.py --self-test. Para o log sem token, leia o journalctl e confira que o token não aparece. Se alguma etapa não foi executada, declare. "Não fiz" escrito vale mais que um "feito" que ninguém conferiu.
Denise ainda não tinha alugado a VPS. Registrou as evidências que conseguia no notebook e escreveu, na linha do reinício, "não executado: sem VPS".
plano-vps.md · Verificações observadas
1 Resposta autorizada: /status respondeu às [hora]
2 Bloqueio de desconhecido: self-test "OK: 11 cenários offline"
3 Reinício do serviço: não executado: sem VPS
4 Logs sem token: lidos em [data]; nenhum token
5 Backup restaurado em pasta separada: diff igual; total 100,00
Uma linha por evidência, sem segredos. A linha 3 declara o que falta, em vez de esconder.
Pratique agora 0/3
Faça e restaure um backup de verdade
Pronto quando o diff não mostrar nada e o total da cópia restaurada for 100,00. Cerca de 10 minutos, no computador, no terminal.
Você só copia um arquivo de dados fictícios; nada é apagado. Aqui a cópia fica no seu computador; numa VPS de verdade, ela iria para fora da máquina. No Windows, use o terminal do WSL, do módulo 3: no PowerShell o diff responde diferente.
Onde está o arquivo:vendas.csv vem na pasta bot do kit do curso, o oswork-kit.zip da página de materiais do OSWork. As linhas abaixo supõem o kit descompactado em ~/projetos/oswork-kit, como na aula anterior; se estiver em outro lugar, troque só a primeira linha. O terminal precisa responder vendas.csv ao ls.
cd ~/projetos/oswork-kit/bot
ls vendas.csv
mkdir -p ~/copias-oswork ~/restauracao-teste
cp vendas.csv ~/copias-oswork/vendas-copia-1.csv
cp ~/copias-oswork/vendas-copia-1.csv ~/restauracao-teste/vendas.csv
diff vendas.csv ~/restauracao-teste/vendas.csv
cat ~/restauracao-teste/vendas.csv
Você acabou de provar, e não só supor, que a sua cópia volta inteira.
Cola da aula
Simulado
De forachecagem diária: o bot respondeu e o disco tem espaço.
Cópiafora da VPS, com retenção escrita e sem o .env.
Ensaiorestaurar em pasta separada; diff em silêncio e total conferido.
Seu próximo passo
Você terminou o OSWork. Você sai com uma pasta organizada com instruções verificáveis, uma Skill, o histórico no Git, um bot restrito e um plano de operação supervisionada numa VPS.
Complete as cinco linhas de Verificações observadas do plano, com o que você executou e "não executado" no resto. Depois marque na agenda o próximo teste de restauração, daqui a um mês.
Daqui em diante, o curso vira rotina: a checagem diária, o ensaio mensal e o plano atualizado a cada mudança. Quando quiser ir além, o laboratório do módulo, no material complementar, leva da pasta local ao serviço supervisionado.
Material complementar · Disponibilidade exige rotina de cuidadoTexto completo do tópico no OSWork v2 e fechamento do módulo. Não conta no tempo da aula.
O que é
Operação contínua combina supervisão, atualização, monitoramento, backups e restauração testada. Faça cópias dos dados fora da máquina, proteja credenciais e defina retenção. Um backup só foi validado quando você restaurou uma cópia e verificou o conteúdo.
Por que aprender
Sem monitoramento, um serviço pode ficar parado durante dias. Sem teste de restauração, a cópia pode estar incompleta. A promessa real é uma rotina recuperável, não uma máquina infalível.
Conceitos-chave
Checagem externa; logs; backup fora da VPS; restauração; limite de gasto.
Na prática
Uma verificação diária registra resposta do bot e espaço em disco. Um teste mensal restaura vendas.csv em uma pasta separada e compara o total. Credenciais seguem tratamento privado, sem entrar no backup público.
Experimente agora
Finalize o projeto com cinco evidências: resposta autorizada, bloqueio de desconhecido, reinício, log sem token e restauração conferida. Declare qualquer etapa não executada.
Laboratório do módulo: Da pasta local a um serviço supervisionado
Use arquivos fictícios e uma pasta de treino. As práticas com instalação, Telegram ou VPS podem exigir tempo adicional para cadastro e configuração.
Escolha uma VPS Ubuntu suportada, defina orçamento e confirme acesso ao console de recuperação.
Crie usuário de trabalho, teste acesso SSH em uma segunda sessão e só então configure o firewall.
Transfira o projeto sem credenciais pelo Git e configure o .env privado na VPS.
Adapte a unidade systemd, inicie o serviço e teste resposta, reinício controlado, logs e restauração de backup.
VPS Ubuntu · adapte caminhos antes
Leia o bloco antes de usar. Campos como Seu Nome e usuario@ip-da-vps são exemplos para adaptar; comandos administrativos pertencem somente ao seu ambiente de treino.
sudo apt update
sudo apt upgrade
sudo apt install git python3
# Adapte a unidade do kit ao usuário e caminho reais.
sudo systemctl daemon-reload
sudo systemctl enable --now oswork-bot
systemctl status oswork-bot --no-pager
journalctl -u oswork-bot -n 50 --no-pager
Critério de pronto
Preparar um plano de implantação, supervisão, backup e verificação do serviço. Registre o arquivo produzido, o teste executado e o resultado observado.
Critérios para revisar sua entrega
Use esta rubrica depois do laboratório. Cada linha pede uma evidência; marcar leitura não significa que a prática foi executada.
Escopo — A entrega corresponde ao objetivo desta aula. Se não passou: Reduza a tarefa e nomeie um único resultado.
Entradas — Você sabe quais arquivos ou dados foram usados. Se não passou: Liste as fontes e remova material sem relação.
Execução — O procedimento foi realizado no ambiente de treino. Se não passou: Diferencie o que foi planejado do que foi feito.
Conferência — Um resultado foi comparado com uma referência. Se não passou: Abra o arquivo ou repita a consulta verificável.
Segredos — Nenhum token, senha ou dado privado foi compartilhado. Se não passou: Revise a cópia de trabalho antes de qualquer envio.
Continuidade — Outra pessoa consegue encontrar o próximo passo. Se não passou: Atualize README e registre uma pendência concreta.
Confira o que ficou
InstalarCodex numa VPS garante um agente ativo 24 horas?
Ver resposta comentada
Não. É preciso um serviço ou agendador, processo supervisionado, credenciais válidas, rede e monitoramento.
Se sua resposta foi diferente, volte ao tópico correspondente e escreva a diferença em uma frase. A checagem não bloqueia seu estudo.
