Scrivere codice con Codex
In questa pagina
Dall’idea al codice in un’unica istruzione
Scrivere codice è il compito che affiderai a Codex più spesso ed è proprio qui che la differenza tra Codex e un semplice generatore di snippet diventa più evidente. L’agente non si limita a produrre un frammento di codice isolato che dovrai poi adattare. Al contrario, legge il tuo codebase, deduce le tue convenzioni e scrive qualcosa che si integra perfettamente nella tua architettura esistente. Il tuo lavoro, quindi, consiste meno nel descrivere il codice e più nel descrivere una posizione all’interno di un sistema.
Creare un nuovo file o modulo
Quando generi codice completamente nuovo, la precisione conta tanto per il contesto quanto per la funzionalità attesa.
"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 legge auth.service.ts per comprendere il pattern corrente, analizza le importazioni e le dipendenze del progetto, crea il file con la stessa struttura, aggiunge i tipi TypeScript appropriati ed esporta le funzioni secondo le convenzioni del progetto. Il risultato appare così:
// 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
}
Un dettaglio merita attenzione: nessuno ha richiesto la validazione Zod. Codex l’ha aggiunta perché ha notato che il progetto utilizza Zod ovunque altrove. Ecco perché fare riferimento a un file modello ripaga: una frase di dieci parole ti risparmia un intero paragrafo di specifiche.
Aggiungere funzionalità al codice esistente
Gli agenti offrono il massimo valore sul codice esistente, non perché scrivere le righe sia difficile, ma perché rispettare tutto ciò che le circonda lo è.
"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 analizza le route vicine, identifica il middleware effettivamente in uso, prende nota del formato di risposta corrente e aggiunge quindi l’endpoint in modo coerente. Questo lavoro di ricognizione ti richiederebbe molto più tempo della vera e propria scrittura del codice, ed è esattamente la parte che le persone tendono a trascurare quando hanno fretta.
Generare codice da una specifica
Per funzionalità complesse, alza il livello e scrivi una specifica vera e propria. Ogni punto diventa un requisito che l’agente tratta come tale.
"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"
Questa specifica fornisce valori numerici, il nome dell’header, il codice di stato HTTP, l’infrastruttura disponibile e la posizione del file. Ogni dettaglio rimuove una decisione arbitraria che Codex avrebbe altrimenti preso al posto tuo: una decisione che scopriresti solo durante la revisione del codice.
Lavorare con più file
Un singolo compito può legittimamente abbracciare più livelli dell’applicazione, a patto che tu elenchi i deliverable.
"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 tutti e quattro i file in modo coerente: il servizio si basa sul modello Prisma, le route chiamano il servizio e i test coprono le route. Ottenere questa coerenza verticale è difficile se spezzi la richiesta in quattro compiti separati, dove ogni passo deve riscoprire ciò che il precedente ha deciso, contraddicendolo talvolta.
Consigli per risultati ottimali
Innanzitutto, ricorda il potere di fare riferimento al codice esistente: «come in auth.service.ts» trasmette in cinque parole un pattern che ti richiederebbe una pagina per essere descritto. Nomina esplicitamente le librerie: «usa Zod per la validazione» invece di «aggiungi validazione», e specifica il formato di output quando conta, come un oggetto uniforme { success, data, error } in tutta la tua API. Menziona i casi limite che ti preoccupano, come «gestisci il caso in cui l’utente non esiste»: lasciato a se stesso, l’agente gestisce il percorso felice (happy path) e lascia a te la scoperta del resto. Infine, tutto ciò che ripeti da un compito all’altro appartiene ad AGENTS.md, mantenendo così le tue istruzioni brevi.
Punti chiave
- Codex comprende il tuo codebase e rispetta le tue convenzioni esistenti
- Fai riferimento a file esistenti per guidare stile e pattern
- Specifiche dettagliate producono risultati più precisi
- Codex può creare e modificare più file in un singolo compito
- AGENTS.md integra le tue istruzioni con regole permanenti