A Sua Primeira Tarefa no Codex
Nesta página
Atualizado em 3 de novembro de 2026 com base na referência de comandos do Codex (CLI 0.166.0): as opções
--show-diffe--applynão existem. Localmente, o Codex modifica ficheiros diretamente na sua área isolada (sandbox); reveja as alterações utilizando/diffougit diff. O comando da extensão “Codex: New Task” foi substituído por Codex: Open Codex Sidebar. Fontes: Developer commands · Codex IDE extension.
Inicie a Sua Primeira Tarefa
A sua conta está configurada, o GitHub está ligado e o ficheiro AGENTS.md está no lugar: chegou a hora de ver o agente em ação. Eis uma regra de ouro para qualquer nível de competência: comece por uma tarefa cuja resposta correta já conhece. Não aprenderá muito a ver o Codex resolver um problema que não consegue avaliar, mas aprenderá imenso ao observá-lo a operar em terreno familiar.
A Partir do Codex Cloud
Na web ou na aplicação de ambiente de trabalho, escolha Work in › Cloud, selecione o ambiente publicado para o seu repositório (Lição 2) e escreva a sua tarefa no campo de entrada. Algo deliberadamente modesto funciona perfeitamente bem.
Task: "Add a .gitignore file suitable for a Node.js/TypeScript
project if one doesn't already exist."
Esta formulação inclui uma condição — “se ainda não existir” — que é exatamente o que torna a observação interessante. No Codex Cloud, a tarefa é executada no ambiente que publicou para este repositório: o Codex verifica se existe um .gitignore, confirma que cobre Node.js e TypeScript caso exista, cria ou atualiza o ficheiro conforme necessário e, em seguida, mostra-lhe o resultado como um diff. O registo de execução é transmitido em tempo real: é aqui que verá se o agente respeitou a condição ou se substituiu o seu ficheiro existente.
A Partir do IDE
Abra o seu projeto no VS Code (ou Cursor, Windsurf) e inicie o Codex através do seu ícone ou da Paleta de Comandos:
Ctrl+Shift+P → "Codex: Open Codex Sidebar"
De seguida, formule um pedido que aproveite o contexto local, nomeando o ficheiro específico:
"Add email validation to the contact form
in src/components/ContactForm.tsx"
A extensão apresenta um resumo e as linhas modificadas ao lado do código; mantém as alterações que deseja e solicita acompanhamentos dentro da mesma conversa. A documentação recomenda criar um ponto de controlo (checkpoint) no Git antes e depois da tarefa, para que possa reverter se necessário.
A Partir da CLI
# Navigate to the project directory
cd my-project
# Start a session with an initial instruction
codex "Add a README.md with the project description, installation instructions, and available commands"
Localmente, o Codex modifica ficheiros diretamente no seu diretório de trabalho, dentro dos limites da área isolada (sandbox) e da política de aprovação: pede permissão antes de realizar ações que a exijam. Para rever o que mudou antes de fazer o commit, escreva /diff na sessão: o comando apresenta o diff do Git, incluindo ficheiros não rastreados. O comando /review solicita ao Codex que reveja a sua própria árvore de trabalho. Para utilização em scripts, codex exec executa a mesma tarefa sem interação (Lição 14) — nesse caso, cabe ao Git e ao seu pipeline decidir o que é mantido.
Anatomia de um Resultado do Codex
Independentemente do ponto de entrada, uma tarefa concluída devolve sempre os mesmos quatro elementos. Reveja-os nesta ordem: o diff indica o que mudou, o registo explica o porquê, os testes indicam se é seguro e as ações devolvem-lhe o controlo.
| Elemento Entregue | O Que Contém |
|---|---|
| Diff de alterações | Todas as linhas adicionadas, modificadas ou eliminadas, ficheiro por ficheiro |
| Registo de execução | Todos os passos: ficheiros lidos, comandos executados, raciocínio do agente |
| Resultados dos testes | Se existirem testes, o Codex executa-os para verificar se nada foi quebrado |
| Ações disponíveis | Aprovar, modificar, criar um PR ou voltar a executar com instruções diferentes |
Os iniciantes negligenciam frequentemente o registo de execução, contudo, é o elemento que lhe ensina a formular as suas tarefas. Ao ver quais os ficheiros que o Codex abriu antes de tomar uma decisão, descobre o que ele procurava mas não encontrou — muitas vezes uma convenção que deveria estar no AGENTS.md.
Escrever Boas Instruções
A qualidade do resultado depende diretamente da qualidade das instruções, e a diferença entre as duas formulações abaixo é muito maior do que a diferença entre dois modelos.
"Improve the code"
"In src/lib/auth.ts, replace manual JWT handling
with the jose library. Keep the same public interface
(signToken, verifyToken). Update the corresponding tests."
A segunda versão funciona porque responde a quatro perguntas que o agente faz a si mesmo de qualquer forma. Especifica os ficheiros envolvidos, poupando-o de explorar e visar o local errado. Define o resultado esperado — comportamento, interface, formato — para que saiba quando parar. Estabelece restrições, aqui preservando a interface pública, o que impede que “melhore” as coisas quebrando quem as chama; noutros contextos, isto poderia ser “não quebre os testes”. E quando os riscos o justificam, adiciona contexto de negócio: especificar “isto é um formulário de pagamento, a segurança é crítica” altera genuinamente as suas compensações (trade-offs).
Para tornar isto seu, pegue num projeto existente e encadeie três tarefas de naturezas diferentes: uma análise sem modificação, “List all TypeScript files that lack associated tests”; uma geração direcionada, “Generate a unit test for this file”; uma correção de âmbito limitado, “Fix ESLint warnings in src/utils/”. Para cada uma, anote o que deveria ter especificado desde o início: esta lista de lamentações é o seu primeiro rascunho do AGENTS.md.
Pontos-chave
- Inicie as suas primeiras tarefas com pedidos simples e direcionados
- O Codex fornece um registo de execução completo para cada tarefa
- A qualidade do resultado depende da precisão das suas instruções
- Mantém sempre o controlo: aprove, modifique ou rejeite
- Comece por tarefas de baixo risco antes de avançar para alterações críticas