Executando a Primeira Tarefa

📚 Navegação da Série: O artigo anterior 05 · Conectando Modelos Nacionais e o DeepSeek explicou como configurar endpoints alternativos na CLI. Esta seção inicializa a aplicação prática das ferramentas — orientando a primeira modificação física de código conduzida pelo Codex, cobrindo da instrução inicial à auditoria dos diffs gerados. No próximo artigo 07 · Funcionalidades do Aplicativo Desktop, apresentaremos os recursos da versão gráfica.

Vale compartilhar um erro comum que cometi logo no início de uso do Codex.

Na primeira noite após configurar a CLI do Codex, decidi testar suas habilidades em um repositório corporativo legado com centenas de arquivos. Sem delimitar o escopo, enviei o prompt: "Refatore o módulo de gerenciamento de usuários". O Codex analisou os arquivos por alguns segundos e gerou alterações espalhadas por múltiplos diretórios. Confiando no resultado, aprovei o plano proposto sem revisar os detalhes.

O resultado foi que a refatoração quebrou assinaturas de métodos não relacionados e causou falhas críticas de compilação. Gastei quase uma hora revisando e revertendo as edições manualmente. A lição principal desse evento foi a importância crítica de auditar os diffs antes de consolidar qualquer tarefa.

Este artigo guiará o leitor na criação de uma rotina de desenvolvimento segura. Utilizaremos um script simples de testes para percorrer o pipeline interativo de ponta a ponta: instrução inicial → gravação de código no sandbox → análise de diffs de auditoria → aceitação ou descarte das alterações — garantindo o controle total sobre as edições. Demonstraremos as rotas gráfica e de linha de comando.

Ao terminar de ler este artigo, você terá:

• O passo a passo detalhado para inicializar e validar a primeira tarefa no terminal ou aplicativo
• A rotina de revisão de diffs consolidada no fluxo de trabalho (o divisor de águas de segurança de código)
• Instruções guiadas para as duas interfaces de uso, com as saídas esperadas para validação
• Métodos de ajustes de prompts sob retornos indesejados e procedimentos rápidos de rollback

⚠️ Observação: Comandos, parâmetros de execução e políticas de Sandbox baseiam-se na documentação oficial do Codex; recursos de modelos e leiaute visual de interfaces mudam conforme a versão instalada no seu sistema.

---

01 Crie um repositório temporário de testes

Regra fundamental de início: evite realizar os testes iniciais diretamente em projetos de produção; crie um diretório isolado de testes.

Mapear grandes bases de código expõe a sessão a um volume complexo de arquivos, dificultando a revisão manual das modificações feitas pela IA e aumentando a chance de aceitar edições indesejadas por engano. Em um diretório controlado de teste, qualquer alteração pontual é visível e facilmente depurável.

Analogia: aprender a guiar veículos em ruas vazias. Ninguém inicia o aprendizado no tráfego de vias expressas. Treinar em um ambiente isolado protege o sistema e permite dominar os comandos do terminal e as reações do sandbox sem riscos de perdas de dados.

Perfis indicados a seguir este roteiro:

• Usuários iniciantes na linha de comando: a quantidade de logs exibida na leitura de arquivos da CLI pode parecer complexa no primeiro contato.
• Desenvolvedores migrando do Claude Code: a dinâmica de Sandbox e as políticas de aprovação do Codex possuem particularidades de funcionamento descritas nos artigos 02 e 05.
• Equipes com prazos curtos: validar o pipeline técnico da CLI de forma simples antes de processar demandas críticas evita desperdício de tempo.

Abra a janela do seu terminal (Terminal no macOS ou PowerShell no Windows) e rode os comandos de criação:

mkdir hello-codex
cd hello-codex

A instrução mkdir cria a pasta de trabalho hello-codex e cd altera o foco do console local para o escopo criado.

Gere um script simples em Python (macOS/Linux):

echo 'def add(a, b):
    return a + b' > main.py

No Windows PowerShell, crie o arquivo main.py salvando as instruções a seguir no diretório:

def add(a, b):
    return a + b

💡 Resumo em uma frase: Inicie a prática em um diretório temporário simples para monitorar com facilidade as escritas de arquivos da IA.

---

02 Estruturando Prompts no Ciclo de Trabalho

Alinhe a instrução de prompt antes de chamar a CLI. O Codex opera sob a mecânica de agente autônomo.

Os retornos dependem diretamente da qualidade dos prompts. Conforme detalhado no Artigo 02, o Codex funciona executando tarefas no ciclo pensar → agir → observar até que o pipeline seja finalizado.

Analogia: a delegação de tarefas de obras. Pedir para "dar uma geral na sala" abre margem para desvios estéticos indesejados. Especificar as metas ("pintar a parede de branco, instalar duas luminárias pretas e finalizar até sexta-feira") dá clareza ao plano de trabalho. O Codex atua de forma mais precisa sob regras objetivas. A documentação oficial de Prompting destaca duas regras de ouro:

• Definição de validações de conformidade: Inclua rotinas de testes locais, lint ou verificadores nos prompts para orientar as checagens do agente.
• Modularização de escopos: Divida refatorações longas em etapas menores e revisáveis. Em tarefas complexas, solicite primeiro um plano descritivo (plan) antes da escrita de código.

Exemplos de refinações de prompts:

❌ Prompts ineficientes	✅ Prompts recomendados
"Melhore a legibilidade desta função"	"Adicione tipagem estática e lance um erro TypeError caso os parâmetros informados não sejam numéricos"
"Ajuste os testes do repositório"	"Execute a suíte do pytest, localize a falha no log e rode os testes novamente para certificar a correção"
"Refatore o projeto"	"Liste uma proposta técnica detalhada de refatoração para este módulo. Reter as escritas locais até a minha aprovação"

Soluções estruturais demandam validação do plano. Solicitar propostas descritivas no prompt inicial protege a base de código contra alterações em massa não controladas.

💡 Resumo em uma frase: Delinear metas explícitas e métricas de aceitação nos prompts evita desvios. Para escopos maiores, comece pedindo um plano lógico de refatoração.

---

03 Leitura Estática de Contexto (Auditoria Inicial)

A tarefa inicial de testes deve focar em consultas de leitura de código para validação de contexto.

Consultas passivas validam a conexão e a indexação de diretórios do assistente sem alterar arquivos locais. O processo é seguro e confirma que o agente está acessando o repositório correto.

Analogia: o onboarding de engenheiros recém-contratados. Não se delega a refatoração do banco de dados na primeira hora de trabalho do desenvolvedor. A prática recomendada é pedir que ele estude e descreva a arquitetura do repositório para certificar seu alinhamento com a base de código.

Envie a seguinte instrução no console local:

解释 main.py 这个文件在做什么，用新手能听懂的话说

Ao processar a instrução, o Codex localiza e lê o arquivo main.py de forma autônoma (sem exigir anexo manual de arquivos). A resposta detalhará que o script define o método add que soma dois parâmetros numéricos.

A resposta correta confirma duas frentes: o setup técnico do Codex está operacional e as chaves de API têm visibilidade dos diretórios da máquina.

Tipos comuns de instruções:

Classe de prompt	Finalidade	Escrita de arquivos	Riscos associados
Auditorias (Leitura)	Compreensão e análise de lógica	❌ Nenhuma escrita local	Custo nulo de I/O, seguro para testes
Refatoração (Escrita)	Modificações de sintaxe	✅ Escrita em arquivos existentes	Requer auditoria fina de diffs
Geração (Criação)	Geração de arquivos auxiliares ou testes	✅ Gravação de novos arquivos	Requer auditoria fina de diffs

Adote o hábito de consultar a arquitetura do repositório antes de realizar mudanças de sintaxe para validar o status da conexão da IA.

💡 Resumo em uma frase: Inicie com instruções de apenas leitura para validar o mapeamento de arquivos locais. Tarefas de escrita exigem acompanhamento de diffs.

---

04 Auditoria e Revisão de Diffs de Escrita

Iniciaremos o teste prático de gravação física. A etapa de auditoria é indispensável para a integridade do código.

Envie o prompt a seguir na CLI:

给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理

Nota técnica sobre permissões padrão: no perfil recomendado de desenvolvimento, edições em arquivos locais da pasta ativa do repositório ocorrem de forma direta, sem emitir janelas de confirmação para cada alteração. Conforme detalhado no Artigo 02, o perfil de Sandbox workspace-write integrado à política on-request considera a gravação no diretório ativo como ação segura. Confirmações manuais são disparadas apenas ao extrapolar o sandbox. O pipeline de escrita segue o fluxo:

1. O agente localiza o arquivo (main.py), gravando as modificações diretamente na pasta ativa.
2. Exibição do Diff: As modificações são apresentadas em formato diff na janela de console, e ficam disponíveis para checagem via git diff no repositório.
3. Auditoria manual: O desenvolvedor revisa as diferenças no console, persistindo as edições de interesse ou descartando as alterações indesejadas por Git.

A auditoria de diffs no terminal atua como o validador do fluxo. As edições permanecem na pasta temporária sem indexação, permitindo a reversão de código simples por meio do Git local. O Sandbox otimiza o desenvolvimento sem remover a palavra final do desenvolvedor.

⚠️ Mapeamento Git: Os atalhos de git diff e rollback exigem que a pasta de trabalho seja inicializada como repositório Git local. Sem o .git configurado, o utilitário não conseguirá traçar históricos de alterações locais. Realizaremos o git init no passo a passo prático para criar um ponto de restauração.

Analogia: revisões de Pull Requests em branches isoladas. O desenvolvedor envia as edições em uma branch paralela sem travar a branch principal. O revisor audita a entrega no painel de diffs: mesclando a entrega sob sucesso ou rejeitando as alterações caso identifique falhas.

⚠️ Para forçar confirmações de alteração antes da gravação de arquivos locais, ative o modo read-only via comando /permissions, ou exija explicitly no prompt inicial a exibição de um plano de código antes de qualquer gravação.

Estrutura básica de leitura de um Diff

Os logs de diff mostram a comparação de linhas adicionadas e removidas:

• Linhas precedidas pelo sinal - (sinalização vermelha): sintaxe removida do arquivo original.
• Linhas precedidas pelo sinal + (sinalização verde): sintaxe adicionada pelo agente.
• Linhas sem sinalizações extras: trecho estático original mantido para localização contextual.

O código original no seu arquivo main.py:

def add(a, b):
    return a + b

Será refatorado para uma lógica semelhante a esta:

def add(a: float, b: float) -> float:
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("a e b devem ser números")
    return a + b

A refatoração insere as tipagens estáticas e o tratamento de exceção. Ao auditar o diff, valide estes três pontos:

1. As edições estão restritas ao escopo solicitado? (O agente não deve ter editado métodos não relacionados).
2. A lógica implementada atende aos padrões do projeto?
3. Sintaxes originais importantes foram mantidas no arquivo final?

A aprovação valida o código localmente. Se identificar inconsistências, solicite os ajustes via prompt ou execute a reversão via Git (detalhado a seguir). Esta auditoria é indispensável.

Interrupções automáticas de Sandbox

Na política de Sandbox padrão, edições internas no diretório não emitem avisos. Os alertas de confirmação manual (Yes/No) são disparados quando o Codex cruza as restrições lógicas do escopo local:

Ações mapeadas pelo Sandbox	Comportamento padrão (Auto)	Comportamento no terminal
Leitura e gravação no diretório de trabalho	Executado de forma direta	Sem interrupções de confirmação; exibe diff ao final
Execução de comandos no diretório de trabalho (ex: run tests)	Executado de forma direta	Executado de forma direta
Execução de instaladores ou conexões de rede locais	Alerta de confirmação disparado	Exige autorização manual (Yes/No)
Escrita em diretórios do sistema fora do workspace	Alerta de confirmação disparado	Exige autorização manual (Yes/No)

Recomenda-se manter as políticas de aprovação ativas em sua máquina principal. Desabilitar as contenções do sandbox (configurando acessos irrestritos e desativando alertas) aumenta o risco de escritas acidentais em arquivos globais do sistema. Conserve as travas padrões ativas.

💡 Resumo em uma frase: No modo padrão, o Codex edita os arquivos do diretório de forma direta exibindo o painel de diffs; alertas ocorrem apenas em saídas de escopo. Audite os diffs antes de salvar.

O diagrama ilustra o processamento interno: ações no repositório ocorrem diretamente (linha verde); conexões ou acessos de sistema acionam confirmações (linha vermelha). Os resultados passam pela auditoria de diffs, permitindo commits ou rollbacks locais.

---

05 Iterações e Ajustes em Conversa Ativa

Rejeitar um plano proposto ou solicitar alterações em um diff não exige inicializar a sessão do zero.

O Codex opera sob sessões de conversas ativas (Threads). O histórico de logs e os caminhos de arquivos permanecem carregados no contexto do diálogo, permitindo enviar feedbacks em linguagem natural para que a IA corrija as sintaxes apresentadas.

Analogia: correções em restaurantes. Se o prato for entregue com temperos inadequados, você não precisa ir a outro estabelecimento. Basta apontar ao atendente o ponto de melhoria ("este molho está com muito sal; refaça com menos condimento") para que a cozinha execute o prato sob nova diretriz.

Exemplo de feedback de prompt para correções de diff:

别引第三方库，用 Python 标准库 functools.lru_cache 实现就行

O agente interpretará o escopo da restrição, removendo as dependências externas e reimplementando a lógica com as bibliotecas nativas, agilizando o desenvolvimento.

Postura de iteração recomendada:

Conceito equivocado ❌	Postura recomendada ✅
Rejeitar um diff encerra a tarefa e exige nova sessão	Rejeitar permite fornecer correções específicas na conversa
Falhas de gravação exigem correções manuais no editor	Aponte as inconsistências em linguagem natural para a IA reescrever
Limites de cotas impedem múltiplos testes	Sessões ativas mantêm o contexto carregado, otimizando o envio de tokens

💡 Resumo em uma frase: Rejeitar caminhos propostos abre oportunidades de correção de prompt na sessão. Envie as diretrizes do ajuste no chat e a IA refatorará o código.

---

06 Restaurações de Código por Git

Caso confirme uma gravação de arquivo incorreta no diretório, utilize o Git local como ponto de restauração.

A documentação oficial recomenda: "O Codex realiza modificações diretas na estrutura do repositório. Sempre estabeleça pontos de checagem com Git antes e depois de cada tarefa para reverter edições locais sob demanda".

Analogia: arquivos de saves em jogos. Salvar o progresso antes de batalhas críticas permite recarregar a sessão no exato ponto anterior caso o personagem perca a rodada. O git commit atua como esse salvamento local de segurança de software.

Passo a passo recomendado antes de inicializar o Codex (rode git init apenas se o repositório for novo):

git init
git add -A && git commit -m "codex 动手前的存档点"

Para reverter as edições e retornar ao estado do commit anterior:

git restore .

⚠️ Atenção: O comando git restore . descarta permanentemente todas as edições pendentes de gravação da pasta ativa. Use este atalho estritamente para rollbacks totais da sessão.

Se quiser ajustar trechos específicos, envie o prompt de correção na conversa ativa do terminal:

刚才那次改动我不满意，帮我退回到改之前的样子

Opções de restauração:

Método de rollback	Sintaxe / Instrução	Cenário indicado	Particularidades
Comando de chat	"Desfaça a última alteração efetuada"	Ajustes simples em sessões ativas	Depende da interpretação contextual do agente
Rollback via Git	git restore .	Descarte de gravações locais inconsistentes	Exige commit de segurança prévio; limpa todas as gravações pendentes

Mantenha a rotina de commitar os status de desenvolvimento antes de liberar o Codex no repositório. O processo de restauração local por Git é rápido e protege o código.

💡 Resumo em uma frase: Rollbacks seguros consomem o Git local: salve o status antes do prompt e use git restore . se necessário. Feedbacks de chat ajudam em revisões secundárias.

---

07 Prática 1: Execução via Terminal CLI

Siga as etapas abaixo para criar o arquivo e validar as escritas no terminal local.

Passo 1: Crie o diretório de testes e configure o Git (macOS / Linux)

mkdir hello-codex && cd hello-codex
echo 'def add(a, b):
    return a + b' > main.py
git init && git add -A && git commit -m "初始版本"

Windows: Crie a pasta e salve as linhas de Python no arquivo main.py antes de rodar a sequência de comandos Git no PowerShell.

Saída esperada: O diretório hello-codex conterá o script main.py inicializado e com status commitado no histórico local do Git.

Passo 2: Inicialize o Codex no diretório ativo

codex

Saída esperada: Inicialização do console interativo do Codex. Se necessário, conclua os fluxos de login detalhados no Artigo 03.

⚠️ Nota crítica de escopo: Inicialize o binário codex estritamente na pasta raiz do seu projeto. O Codex adota o diretório ativo no terminal como a pasta de trabalho principal para leituras e edições.

Passo 3: Solicite a análise estática do arquivo

解释 main.py 这个文件在做什么，用新手能听懂的话说

Saída esperada: O Codex interpretará o script main.py, descrevendo que a função soma os parâmetros de entrada. O retorno correto valida as permissões de leitura.

Passo 4: Solicite a refatoração e revise o diff

给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理

Saída esperada: No perfil de Sandbox padrão, o arquivo local será editado e o diff será exibido no console. Revise o log de alterações comparando as linhas verdes (+) e vermelhas (-). Se a IA tentar rodar comandos fora do escopo, aprove a requisição na CLI.

Passo 5: Valide a gravação no diretório

Encerre a CLI (via /exit ou Ctrl + C) e leia os arquivos modificados:

cat main.py

(Windows PowerShell: use type main.py).

Saída esperada: O arquivo exibirá a lógica de validação e a tipagem estática inseridas no script local.

Para auditar o status das edições pelo Git local, execute:

git diff

Saída esperada: O Git registrará as modificações exatas apresentadas na CLI, confirmando a consistência do sistema de arquivos.

💡 Resumo em uma frase: O teste básico na CLI segue: inicializar pasta com Git → rodar codex → pedir leitura passiva → solicitar escrita de código com revisão de diff → auditar edições com git diff.

---

08 Prática 2: Execução via Aplicativo Desktop

Usuários de macOS e Windows podem realizar as mesmas etapas pela interface gráfica do aplicativo desktop.

O aplicativo oferece a mesma mecânica de Sandbox e checagem, fornecendo controles visuais no painel lateral:

1. Acesse o aplicativo desktop do Codex e conclua o login (ChatGPT ou Chave de API).
2. Mapeie a pasta de trabalho selecionando o diretório hello-codex criado nos testes.
3. Ative a chave de conexões Local no canto inferior esquerdo para autorizar a leitura e escrita local de arquivos.
4. Envie o prompt de leitura no chat:

解释 main.py 这个文件在做什么，用新手能听懂的话说

Conclua enviando a diretriz de escrita:

给 main.py 里的 add 函数加上类型注解，并补充基本的错误处理

Saída esperada: O Codex alterará o arquivo local e exibirá o diff gráfico de alterações no painel lateral de revisão (review pane). O review pane agrupa modificações pendentes no Git, permitindo commits ou rollbacks visuais rápidos pelos botões da interface gráfica.

As extensões e CLI dependem de chamadas git no shell; a interface do aplicativo integra ferramentas visuais nativas de commit e descarte de modificações de código.

Comparação de usabilidade das interfaces:

Indicador	Terminal CLI	Aplicativo Desktop
Plataformas compatíveis	✅ macOS / Windows / Linux	❌ macOS / Windows
Curva de aprendizado	Exige afinidade com comandos de console	✅ Interface intuitiva amigável
Visualização de diffs	Exibição de logs em formato texto no shell	✅ Painel visual com realce de sintaxe colorido
Gerenciamento de repositórios	Janelas separadas de console por projeto	✅ Alternância fluida no painel de conexões
Pipeline básico	Instrução → Alteração → Auditoria de diff	Idêntico (altera apenas os controles manuais)

A CLI atende a fluxos rápidos de console; a visualização de diffs em lotes de arquivos no aplicativo desktop é recomendada por concentrar o histórico de alterações no review pane.

💡 Resumo em uma frase: O aplicativo desktop simplifica a gestão de repositórios locais (macOS/Windows). Valide a opção Local na interface e use o review pane para auditar e commitar as modificações de código.

---

09 O Fluxo de Trabalho Completo

A sequência abaixo consolida as fases recomendadas para qualquer interface:

O ponto central reside no fluxo de aprovação das ações de escrita do sandbox: alterações ocorrem apenas sob confirmação do usuário.

💡 Resumo em uma frase: A rotina de desenvolvimento baseia-se em: prompt de metas → escrita do agente → auditoria do diff → commit ou rollback. A checagem manual de diffs evita falhas críticas.

---

10 Resumo

Este guia prático cobriu a execução do primeiro fluxo de escrita de código com o Codex, detalhando as rotinas de leitura de diretório, refatoração de sintaxe e rollbacks locais.

Fases essenciais revisadas:

Fase operacional	Ação recomendada	Observações
Ambiente de testes	mkdir → script de exemplo → git commit	Use repositórios temporários; crie pontos de restauração antes de rodar prompts
Alinhamento do prompt	Linguagem direta e metas específicas	Em escopos complexos, exija exibição prévia do plano de refatoração
Auditoria estática	"Explique a finalidade do arquivo main.py"	Testes passivos validam visibilidade e caminhos da CLI
Execução de refatoração	"Adicione tipagem de variáveis"	Modificações internas no diretório ocorrem diretamente no sandbox
Revisão de Diffs	Checagem de linhas adicionadas (+) e removidas (-)	Etapa crítica de segurança de código; evite pular
Rollback de arquivos	git restore .	Descarte de gravações locais inconsistentes

Com essa prática, você dominou a inicialização da CLI, envio de parâmetros visuais, validação de Sandboxes de I/O locais e manutenções de arquivos por diffs e rollbacks.

Esse ciclo de prompts, revisões e commits fundamenta o uso avançado do Codex. Outras ferramentas de automação construídas na CLI herdam a mesma lógica de Sandbox e auditoria manual.

💡 Resumo em uma frase: A rotina de desenvolvimento baseia-se em: instruir a IA → escrita no sandbox → auditoria de diff → aceitação ou rollback local. Mantenha os checkpoints do Git ativos por segurança.

---

O próximo artigo 07 · Funcionalidades do Aplicativo Desktop aprofundará os recursos da interface gráfica do Codex: isolamento de worktrees, navegadores embarcados e gerenciamento de tarefas automáticas em múltiplos projetos locais.

---

Leituras Recomendadas

• Modo Não-Interativo codex exec: Execução automatizada e pipelines de CI
• Codex em Nuvem (Cloud): Executando tarefas remotas em sandboxes temporárias
• Guia de Inicialização del Terminal CLI