Primeiras sessões com o Codex: gerando código a partir de instruções

Nos capítulos anteriores você entendeu o ciclo do agente e deixou o Codex instalado e autenticado. Agora vamos usá-lo de verdade. Ao final deste capítulo você será capaz de abrir uma sessão dentro de uma pasta de projeto, pedir a criação de um pequeno programa, ler o plano e o diff propostos, aceitar ou recusar as mudanças, pedir ajustes e encerrar a sessão com segurança. O foco aqui é a mecânica da ferramenta, ou seja, quais teclas você aperta e o que cada coisa na tela significa. A arte de escrever pedidos bem formulados fica para o capítulo cinco.

Abrindo a sessão no lugar certo

O Codex trabalha a partir da pasta em que você o iniciou. Essa pasta é a raiz do espaço de trabalho do agente, e é dentro dela que ele lê arquivos e aplica mudanças. Por isso, o primeiro passo nunca é digitar o comando, é escolher o diretório.

Crie uma pasta vazia para praticar, entre nela, inicialize o repositório com o Git e só então chame o Codex.

mkdir contador-palavras
cd contador-palavras
git init
codex

O Git não é obrigatório, mas é altamente recomendável. Logo depois do git init, registre um commit inicial, mesmo que vazio, com git commit --allow-empty -m "estado inicial"; se o Git reclamar, configure antes seu nome e seu e-mail com git config --global user.name e git config --global user.email. Só a partir desse primeiro commit existe um ponto de retorno, e aí sim cada alteração do agente aparece como diferença em relação ao último commit. Vale lembrar que arquivos criados do zero entram como não rastreados: para voltar ao estado anterior você precisa de git restore . nos arquivos já versionados e de git clean -fd para remover os novos, e esse último comando apaga de vez, sem lixeira, então rode antes git clean -nd para ver o que seria removido. Trabalhar sem controle de versão é como editar arquivos sem ter o botão de desfazer.

Depois de iniciar, o Codex mostra um cabeçalho com informações da sessão: o modelo em uso, o nível de raciocínio, a pasta de trabalho e o modo de aprovação ativo. Vale a pena olhar esse cabeçalho todas as vezes. Ele é o equivalente ao painel de instrumentos antes de dar a partida.

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

O primeiro pedido

Com o cursor no campo de mensagem, descreva a tarefa em linguagem natural e pressione Enter. Um pedido simples para começar:

Crie um script em Python chamado contador.py que receba o caminho de um arquivo de texto como argumento e imprima as dez palavras mais frequentes, ignorando maiúsculas e minúsculas. Adicione um README curto explicando como rodar.

A partir daí o agente começa a trabalhar e você acompanha tudo em tempo real. É importante entender as quatro coisas que aparecem na tela:

• Raciocínio resumido: linhas curtas indicando o que o agente está pensando ou decidindo. É um resumo, não o pensamento completo.
• Leituras de arquivos: cada arquivo que ele abre ou procura é listado. Em um projeto vazio, essa lista é curta. Em um projeto existente, ela mostra exatamente qual parte do código o agente considerou.
• Comandos executados: qualquer comando de terminal aparece antes ou junto do resultado, com a saída correspondente. É assim que você vê o agente rodando testes, instalando algo ou listando pastas.
• Alterações em arquivos: as edições são apresentadas como diff, com as linhas adicionadas e removidas.

Em tarefas maiores, o Codex costuma anunciar um plano antes de mexer em qualquer coisa: uma lista de passos numerados que ele pretende seguir, com o passo atual marcado. Leia esse plano com atenção. É o momento mais barato para corrigir o rumo, porque nada foi escrito em disco ainda. Se o plano incluir algo indesejado, como instalar uma biblioteca pesada ou reorganizar pastas, interrompa e diga o que quer diferente.

Lendo o diff e decidindo

Quando o agente propõe uma edição, você vê um bloco parecido com este:

contador.py (novo arquivo)
+ import sys
+ from collections import Counter
+
+ def principais_palavras(caminho, limite=10):
+     with open(caminho, encoding="utf-8") as arquivo:
+         texto = arquivo.read().lower()
+     return Counter(texto.split()).most_common(limite)

As linhas com sinal de mais são acréscimos e as linhas com sinal de menos são remoções. Dependendo do modo de aprovação configurado, o Codex pode pedir sua confirmação antes de gravar. Nesse caso surge uma pergunta com opções: aprovar esta mudança, aprovar e não perguntar mais nesta sessão, ou recusar. Escolha com as setas e confirme com Enter. Se recusar, o agente não aplica a edição e você pode explicar o motivo em texto, por exemplo pedindo que ele use uma expressão regular em vez de dividir por espaços. Os modos de autonomia e o funcionamento do sandbox são o assunto do próximo capítulo, então aqui basta saber que a pergunta existe e que recusar é sempre seguro.

Depois de várias trocas, use o comando de sessão que começa com barra e a palavra diff, escrito /diff, para ver o conjunto acumulado de mudanças desde o início. É a revisão final antes de commitar.

Pedindo ajustes

A sessão é uma conversa contínua. O agente lembra do que já foi feito, então os pedidos seguintes podem ser curtos:

• Adicione tratamento para arquivo inexistente, com mensagem amigável e código de saída um.
• Rode o script com um arquivo de exemplo para provar que funciona.
• Prefiro que o limite de palavras seja um argumento opcional na linha de comando.

Note o segundo pedido. Pedir ao próprio agente que execute o que escreveu é o hábito mais valioso desta fase. Código que nunca rodou é apenas uma hipótese.

Como interromper e como encerrar

Às vezes o agente toma um caminho errado e você percebe no meio da execução. Pressione a tecla Escape para interromper o turno em andamento. Ele para, mantém o que já foi feito e devolve o controle para você. Como a interrupção pode acontecer no meio de uma edição ou de um comando, confira em seguida com git status e git diff se algum arquivo ficou pela metade antes de dar o próximo pedido. Os atalhos ativos aparecem sempre no rodapé da interface, porque mudam entre versões, então confie no rodapé mais do que na memória.

Para encerrar a sessão, use o comando de saída oferecido pela interface ou pressione Control mais C duas vezes. Antes de sair, faça duas coisas: revise as mudanças com o Git e registre um commit. Assim:

git status
git add .
git diff --staged
git commit -m "contador de palavras inicial"

A ordem importa: o git diff sozinho não mostra arquivos novos, porque eles ainda não são rastreados pelo Git. Por isso adicionamos primeiro e revisamos com git diff --staged. E leia a lista do git status antes do git add ., para não versionar sem querer arquivos de ambiente, chaves de API ou pastas de dependências.

Se quiser recomeçar do zero sem fechar o programa, o comando de nova conversa limpa o histórico do contexto e mantém você na mesma pasta. Isso é útil quando a sessão ficou longa e cheia de assuntos misturados.

O mesmo fluxo na extensão do editor

Na extensão para o VS Code e editores compatíveis, tudo acontece em um painel lateral. As diferenças práticas são três. Primeiro, a pasta de trabalho é a que você abriu no editor, não é preciso navegar pelo terminal. Segundo, você pode selecionar um trecho de código no arquivo e pedir a alteração daquele trecho, sem descrever a localização por escrito. Terceiro, e mais importante, os diffs aparecem na visão de comparação lado a lado do próprio editor, com botões para aceitar ou descartar arquivo por arquivo.

O restante é idêntico: plano, leituras, comandos, diff, aprovação. Muita gente usa a extensão para revisar mudanças, porque ler diffs é mais confortável com cores e navegação do editor, e usa o terminal para tarefas longas que envolvem rodar muitos comandos.

Código novo versus mudança em código existente

Esses dois tipos de pedido acionam comportamentos bem diferentes do agente, e reconhecer a diferença evita frustração.

Quando você pede código novo em uma pasta praticamente vazia, o agente tem liberdade quase total. Ele escolhe nomes de arquivos, estrutura de pastas, bibliotecas e estilo. Isso é rápido, mas também é onde ele mais inventa convenções que você não queria. A forma de conduzir é dizer antecipadamente o essencial: linguagem, versão, onde os arquivos devem ficar e se pode ou não instalar dependências.

Quando você pede alteração em código existente, o trabalho do agente começa por entender o que já está lá. Você vai notar muito mais leituras de arquivos e buscas antes da primeira edição, e isso é bom sinal. O critério de sucesso também muda: não basta funcionar, a mudança precisa respeitar o padrão do projeto e não quebrar o que já existia. Por isso, em código existente vale sempre pedir duas coisas a mais: que o agente mostre o plano antes de editar e que rode os testes ou o comando de verificação depois. Mudanças pequenas e revisáveis, uma por vez, produzem resultados muito melhores do que um pedido gigante.

Um roteiro para suas próximas sessões

1. Entre na pasta do projeto e confirme que o Git está limpo.
2. Inicie o Codex e confira o cabeçalho da sessão.
3. Faça um pedido por vez, começando pelo menor passo útil.
4. Leia o plano e interrompa com Escape se ele estiver errado.
5. Leia cada diff antes de aprovar e recuse sem medo.
6. Peça ao agente que execute o código ou os testes.
7. Revise com o Git, commite e encerre.

Recapitulando

Você aprendeu que o Codex opera dentro da pasta onde foi aberto e que o Git é a sua rede de segurança. Viu que a tela mostra quatro tipos de informação, raciocínio resumido, arquivos lidos, comandos executados e diffs, e que o plano é o melhor momento para corrigir o rumo. Aprendeu a aprovar, recusar, pedir ajustes em pedidos curtos, interromper com Escape e encerrar revisando as mudanças. Viu que a extensão do editor segue o mesmo ciclo com diffs lado a lado e seleção de trechos. E entendeu por que criar código novo e alterar código existente exigem posturas diferentes: liberdade com restrições explícitas no primeiro caso, contexto e verificação no segundo.