Escrever Código com o Codex
Nesta página
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