Escribir código con Codex
En esta página
De la idea al código en una sola instrucción
Escribir código es la tarea que asignarás a Codex con más frecuencia y donde la diferencia entre Codex y un simple generador de fragmentos se hace más evidente. El agente no se limita a producir un fragmento de código aislado que luego tengas que adaptar. En su lugar, lee tu base de código, infiere tus convenciones y escribe algo que encaje perfectamente en tu arquitectura existente. Por tanto, tu trabajo consiste menos en describir código y más en describir un lugar dentro de un sistema.
Crear un nuevo archivo o módulo
Al generar código completamente nuevo, la precisión es tan importante para el contexto como para la funcionalidad 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)."
Codex lee auth.service.ts para entender el patrón actual, analiza las importaciones y dependencias del proyecto, crea el archivo con la misma estructura, añade los tipos de TypeScript apropiados y exporta las funciones según las convenciones del proyecto. El resultado es este:
// 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 });
// ... implementación
}
export async function sendWebhook(
url: string,
payload: Record<string, unknown>
): Promise<Response> {
// ... implementación
}
Un detalle merece atención: nadie pidió validación con Zod. Codex la añadió porque detectó que el proyecto usa Zod en todas partes. Por eso merece la pena referenciar un archivo modelo: una frase de diez palabras te ahorra un párrafo entero de especificación.
Añadir funcionalidades a código existente
Los agentes aportan el mayor valor sobre código existente, no porque escribir las líneas sea difícil, sino porque respetar todo lo que las rodea sí lo es.
"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."
Codex analiza las rutas vecinas, identifica el middleware real en uso, toma nota del formato de respuesta actual y añade el punto de acceso de forma coherente. Este trabajo de reconocimiento te llevaría mucho más tiempo que la propia codificación, y es exactamente la parte que la gente suele hacer mal cuando tiene prisa.
Generar código a partir de una especificación
Para funcionalidades complejas, sube un nivel y escribe una especificación adecuada. Cada punto se convierte en un requisito que el 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 especificación proporciona valores numéricos, el nombre de la cabecera, el código de estado HTTP, la infraestructura disponible y la ubicación del archivo. Cada detalle elimina una decisión arbitraria que Codex tomaría por ti; una decisión que solo descubrirías durante la revisión del código.
Trabajar con múltiples archivos
Una única tarea puede legítimamente abarcar varias capas de la aplicación, siempre que enumeres los entregables.
"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"
Codex produce los cuatro archivos de forma coherente: el servicio se basa en el modelo de Prisma, las rutas llaman al servicio y las pruebas cubren las rutas. Lograr esta consistencia vertical es difícil si divides la solicitud en cuatro tareas separadas, donde cada paso debe redescubrir lo que decidió el anterior y, a veces, contradecirlo.
Consejos para obtener resultados óptimos
En primer lugar, recuerda el poder de referenciar código existente: «como en auth.service.ts» transmite en cinco palabras un patrón que te llevaría una página describir. Nombra las bibliotecas explícitamente («usa Zod para la validación» en lugar de «añade validación») y especifica el formato de salida cuando importe, como un objeto uniforme { success, data, error } en toda tu API. Menciona los casos límite que te preocupen, como «gestiona el caso en que el usuario no existe»: si lo dejas a su aire, el agente gestionará el camino feliz y te dejará a ti descubrir el resto. Por último, todo aquello que repitas de tarea en tarea pertenece a AGENTS.md, lo que mantendrá tus instrucciones breves.
Puntos clave
- Codex entiende tu base de código y respeta tus convenciones existentes
- Referencia archivos existentes para guiar el estilo y los patrones
- Las especificaciones detalladas producen resultados más precisos
- Codex puede crear y modificar múltiples archivos en una sola tarea
- AGENTS.md complementa tus instrucciones con reglas permanentes