Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Configurar o seu ambiente e o ficheiro AGENTS.md

Aula 3 de 20 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Prepare o seu projeto para o Codex
  2. Passo 1: O seu acesso ao Codex
  3. Passo 2: Instalar a extensão do editor
  4. Passo 3: Instalar a CLI
  5. O ficheiro AGENTS.md — o guia do seu projeto
  6. Melhores práticas para o AGENTS.md
  7. Pontos-chave

Atualizado a 3 de novembro de 2026 com base na documentação do Codex (Codex CLI, Autenticação, Extensão IDE do Codex, Instruções personalizadas com AGENTS.md): o pacote @openai/codex-cli e o comando codex auth login não existem (utilize npm install -g @openai/codex e codex login); o identificador da extensão é openai.chatgpt; o endereço codex.openai.com e os planos “Team, Enterprise, or API” foram substituídos pelos métodos de acesso atuais; e a ordem de leitura do AGENTS.md foi clarificada (raiz do projeto → diretório atual). Fontes: Codex CLI · Authentication · AGENTS.md · Pricing.

Prepare o seu projeto para o Codex

Antes da sua primeira tarefa, duas coisas devem estar prontas: o seu acesso ao Codex — a sua conta e a ligação ao GitHub — e o próprio projeto, definido através do ficheiro AGENTS.md que irá guiar o agente. A primeira parte demora cerca de 15 minutos e é uma configuração única. A segunda determina a qualidade de tudo o que obtém do Codex, separando as equipas satisfeitas daquelas que ficam desapontadas.

Passo 1: O seu acesso ao Codex

Pode utilizar o Codex com uma conta ChatGPT ou uma chave de API. Os planos Free e Go fornecem acesso, dependendo da implementação atual, ao GPT-6 Luna na aplicação de desktop. A partir do plano Plus, o Codex está disponível na web, na CLI, na extensão do editor e no iOS, com integrações na nuvem como a revisão automática de código. Uma chave de API funciona para automação em ambientes partilhados como CI, utilizando a CLI, o SDK ou a extensão — embora algumas funcionalidades possam não estar disponíveis. Os detalhes e limites de uso encontram-se na página de preços do Codex.

Para trabalhar na nuvem nos seus repositórios, ligue o GitHub quando criar o seu primeiro ambiente Codex Cloud (Lição 2). Ao conceder permissões, mantenha-as mínimas: limite o acesso apenas aos repositórios de que realmente necessita.

Passo 2: Instalar a extensão do editor

No VS Code e nos seus derivados (Cursor, Windsurf), instale a extensão Codex a partir do marketplace — o seu identificador é openai.chatgpt:

code --install-extension openai.chatgpt

Em seguida, abra o Codex através do seu ícone ou através da paleta de comandos com Codex: Open Codex Sidebar, e inicie sessão. O Xcode e as IDEs JetBrains têm as suas próprias integrações: no JetBrains, abra AI Chat e selecione Codex.

Passo 3: Instalar a CLI

# Instalação (macOS e Linux), ou npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Verificar instalação
codex --version

# Iniciar sessão (navegador) ou verificar estado da ligação
codex login
codex login status

O comando codex login abre o fluxo de autenticação no seu navegador. Para uma chave de API, passe-a via entrada padrão (printenv OPENAI_API_KEY | codex login --with-api-key). O Codex guarda as credenciais em cache num ficheiro de texto simples, ~/.codex/auth.json, ou no chaveiro do sistema, dependendo da definição cli_auth_credentials_store (file, keyring, auto ou ephemeral). Se for utilizado o ficheiro, trate-o como uma palavra-passe: contém tokens de acesso, por isso nunca o coloque no repositório. A CLI e a extensão partilham este cache.

O ficheiro AGENTS.md — o guia do seu projeto

O AGENTS.md é central para utilizar o Codex de forma eficaz. É um simples ficheiro Markdown colocado na raiz do seu repositório que reúne instruções, convenções e comandos específicos do seu projeto. Quando o Codex clona o repositório, lê este ficheiro em primeiro lugar: pense nisso como uma integração automática para o agente, exatamente aquilo que explicaria oralmente a um novo membro da equipa.

O impacto é imediato. Sem o AGENTS.md, se pedir um teste unitário num projeto que utiliza Vitest, há uma grande probabilidade de o Codex lhe fornecer Jest, porque essa é a escolha mais comum no ecossistema. Uma única linha de convenção é suficiente para acertar no Vitest à primeira, poupando-lhe a correção repetida centenas de vezes. Eis a estrutura de um ficheiro básico para um projeto SaaS de gestão de faturas.

# AGENTS.md

## Project context
SaaS invoice management application.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Code conventions
- Use React functional components (no classes)
- Name files in kebab-case
- TypeScript types in separate .types.ts files
- Tests with Vitest, .test.ts files next to code

## Useful commands
- `npm run dev` — development server
- `npm run test` — run tests
- `npm run lint` — check linting
- `npm run build` — production build

## Project structure
    src/
      app/          → Next.js pages (App Router)
      components/   → Reusable React components
      lib/          → Business logic and utilities
      prisma/       → DB schema and migrations

## Strict rules
- NEVER modify Prisma schema without a migration
- NEVER commit .env files
- Always use Server Actions for mutations

Como o Codex encontra os ficheiros AGENTS.md

Um único ficheiro na raiz torna-se rapidamente demasiado genérico. O Codex permite empilhar instruções numa ordem precisa que deve conhecer:

  1. Nível global: Na sua pasta Codex (~/.codex, a menos que CODEX_HOME substitua), o Codex lê AGENTS.override.md se existir, caso contrário lê AGENTS.md.
  2. Nível do projeto: A partir da raiz do projeto (geralmente a raiz Git), o Codex desce até ao diretório atual e lê, em cada pasta percorrida, AGENTS.override.md ou, na falta deste, AGENTS.md.
  3. Fusão: Os ficheiros são concatenados da raiz até ao diretório atual; os mais próximos do diretório atual vêm por último e, portanto, substituem instruções mais gerais.
my-project/
  AGENTS.md              → Project instructions
  src/
    api/
      AGENTS.md          → "API routes use Zod for validation"

Consequência prática: o src/api/AGENTS.md só é lido se o Codex estiver a trabalhar a partir de src/api ou de um dos seus subdiretórios, não quando lançado a partir da raiz. Ficheiros vazios são ignorados e a concatenação para nos 32 KiB por padrão (project_doc_max_bytes). Se o seu repositório já utilizar outro nome, como TEAM_GUIDE.md, adicione-o a project_doc_fallback_filenames em ~/.codex/config.toml.

Para verificar o que o Codex carregou efetivamente, basta perguntar: codex --ask-for-approval never "Summarize the current instructions.". O Codex reconstrói a cadeia de instruções em cada arranque: se tiver dúvidas, reinicie-o no diretório correto.

Melhores práticas para o AGENTS.md

O princípio orientador é a explicitação. “Utilize Vitest, não Jest” é melhor do que “Utilize o nosso framework de testes”, o que pressupõe um conhecimento que o agente não tem. Inclua sempre comandos: sem eles, o Codex não saberá como executar os seus testes, o linter ou a compilação, e entregará código que não pôde verificar. Documente a estrutura como uma árvore de diretórios, o que impede que explore às cegas e crie ficheiros no local errado.

Por fim, liste as proibições. As regras escritas como “NUNCA” são as mais rentáveis no ficheiro, porque bloqueiam erros dispendiosos e difíceis de corrigir: colocar um ficheiro .env no repositório, modificar um esquema sem uma migração. A disciplina mais difícil é manter o ficheiro atualizado. Um AGENTS.md que descreve o projeto do ano passado orienta ativamente o Codex para convenções abandonadas — muito pior do que não ter ficheiro nenhum, já que o erro se torna então sistemático.

Pontos-chave

  • A configuração inicial requer uma conta OpenAI e uma ligação ao GitHub
  • A extensão da IDE e a CLI instalam-se em minutos
  • O AGENTS.md é o ficheiro mais importante para um uso eficaz do Codex
  • Contém convenções, comandos e regras específicas do seu projeto
  • Os ficheiros AGENTS.md em subdiretórios permitem instruções contextuais