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

Escrever Código com o Codex

Aula 5 de 20 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Da Ideia ao Código numa Única Instrução
  2. Criar um Novo Ficheiro ou Módulo
  3. Adicionar Funcionalidades a Código Existente
  4. Gerar Código a Partir de uma Especificação
  5. Trabalhar com Múltiplos Ficheiros
  6. Dicas para Resultados Ótimos
  7. Pontos-chave

Da Ideia ao Código numa Única Instrução

Escrever código é a tarefa que mais frequentemente irá atribuir ao Codex e é onde a diferença entre o Codex e um simples gerador de fragmentos de código se torna mais evidente. O agente não produz apenas um fragmento de código isolado que terá depois de adaptar. Em vez disso, lê a sua base de código, infere as suas convenções e escreve algo que se integra perfeitamente na sua arquitetura existente. O seu trabalho, portanto, consiste menos em descrever código e mais em descrever um lugar dentro de um sistema.

Criar um Novo Ficheiro ou Módulo

Ao gerar código inteiramente novo, a precisão é tão importante para o contexto como para a funcionalidade esperada.

"Create a service at src/services/notification.service.ts that handles 
sending notifications via email and webhook. Use the same pattern as 
src/services/auth.service.ts. The service must expose sendEmail(to, subject, body) 
and sendWebhook(url, payload)."

O Codex lê auth.service.ts para compreender o padrão atual, analisa as importações e dependências do projeto, cria o ficheiro com a mesma estrutura, adiciona os tipos TypeScript adequados e exporta as funções de acordo com as convenções do projeto. O resultado é o seguinte:

// src/services/notification.service.ts
import { z } from "zod";
import { logger } from "@/lib/logger";
import { env } from "@/lib/env";

const emailSchema = z.object({
  to: z.string().email(),
  subject: z.string().min(1),
  body: z.string().min(1),
});

export async function sendEmail(
  to: string, 
  subject: string, 
  body: string
): Promise<void> {
  const validated = emailSchema.parse({ to, subject, body });
  // ... implementation
}

export async function sendWebhook(
  url: string, 
  payload: Record<string, unknown>
): Promise<Response> {
  // ... implementation
}

Um detalhe merece atenção: ninguém pediu validação com Zod. O Codex adicionou-a porque detetou que o projeto utiliza Zod em todo o lado. É por isso que referenciar um ficheiro modelo compensa: uma frase de dez palavras poupa-lhe um parágrafo inteiro de especificação.

Adicionar Funcionalidades a Código Existente

Os agentes oferecem o maior valor em código existente, não porque escrever as linhas seja difícil, mas porque respeitar tudo o que as rodeia o é.

"In src/api/routes/users.ts, add a GET /users/:id/activity endpoint 
that returns the user's last 50 actions. Use the same authentication 
middleware as the other routes."

O Codex analisa as rotas vizinhas, identifica o middleware atualmente em uso, regista o formato de resposta atual e, em seguida, adiciona o endpoint de forma consistente. Este trabalho de reconhecimento levar-lhe-ia muito mais tempo do que a própria codificação e é exatamente a parte que as pessoas negligenciam quando estão com pressa.

Gerar Código a Partir de uma Especificação

Para funcionalidades complexas, suba um nível e escreva uma especificação adequada. Cada ponto torna-se num requisito que o agente trata como tal.

"Implement a rate limiting system for the API:
- Maximum 100 requests per minute per IP
- Maximum 1000 requests per hour per authenticated user
- Return an X-RateLimit-Remaining header
- Return 429 Too Many Requests when the limit is reached
- Store counters in Redis (already configured in the project)
- Create the middleware in src/middleware/rate-limit.ts"

Esta especificação fornece valores numéricos, o nome do cabeçalho, o código de estado HTTP, a infraestrutura disponível e a localização do ficheiro. Cada detalhe remove uma decisão arbitrária que o Codex tomaria por si — uma decisão que só descobriria durante a revisão de código.

Trabalhar com Múltiplos Ficheiros

Uma única tarefa pode legitimamente abranger várias camadas da aplicação, desde que liste os entregáveis.

"Add an in-app notification system:
1. Prisma model Notification (id, userId, type, message, read, createdAt)
2. Service at src/services/notification.service.ts
3. CRUD API routes in src/api/routes/notifications.ts
4. Tests in src/api/routes/notifications.test.ts"

O Codex produz os quatro ficheiros de forma coerente: o serviço baseia-se no modelo Prisma, as rotas chamam o serviço e os testes cobrem as rotas. Alcançar esta consistência vertical é difícil se dividir o pedido em quatro tarefas separadas, onde cada passo tem de redescobrir o que o anterior decidiu — e por vezes contradizê-lo.

Dicas para Resultados Ótimos

Em primeiro lugar, lembre-se do poder de referenciar código existente: «como em auth.service.ts» transmite em cinco palavras um padrão que levaria uma página a descrever. Nomeie as bibliotecas explicitamente — «use Zod para validação» em vez de «adicione validação» — e especifique o formato de saída quando for relevante, como um objeto uniforme { success, data, error } em toda a sua API. Mencione os casos limite que lhe preocupam, como «trate o caso em que o utilizador não existe»: se deixado à sua sorte, o agente trata apenas do cenário ideal e deixa-o a si descobrir o resto. Por fim, tudo o que repetir de tarefa para tarefa pertence ao AGENTS.md, mantendo as suas instruções curtas.

Pontos-chave

  • O Codex compreende a sua base de código e respeita as suas convenções existentes
  • Referencie ficheiros existentes para orientar o estilo e os padrões
  • Especificações detalhadas produzem resultados mais precisos
  • O Codex pode criar e modificar múltiplos ficheiros numa única tarefa
  • O AGENTS.md complementa as suas instruções com regras permanentes