Guida introduttiva a Codex: best practice per risultati migliori

Se sei nuovo a @OpenAI Codex o agli agenti di codifica in generale, questa guida ti aiuterà a ottenere risultati migliori più rapidamente. Copre le abitudini fondamentali che rendono Codex più efficace in tutta la CLI, le estensioni IDE e l'app Codex, dalla scrittura dei prompt e la pianificazione alla validazione, MCP, competenze e automazioni.

Codex funziona meglio quando lo tratti meno come un assistente usa-e-getta e più come un compagno di squadra che configuri e migliori nel tempo.

Un buon modello mentale è: inizia con il giusto contesto del task, usa AGENTS.md per linee guida durevoli, configura Codex in base al tuo flusso di lavoro, connetti sistemi esterni con MCP, trasforma il lavoro ripetitivo in competenze e automatizza i flussi di lavoro stabili.

1. Prepara Codex per un primo utilizzo efficace con contesto e prompt chiari

Codex è già abbastanza potente da essere utile anche quando il tuo prompt non è perfetto. Spesso puoi affidargli un problema complesso con una configurazione minima e ottenere comunque un buon risultato. Una scrittura chiara dei prompt non è obbligatoria per trarre valore, ma rende i risultati più affidabili, specialmente in codebase di grandi dimensioni o task ad alta posta in gioco.

Se lavori in un repository grande o complesso, la svolta più grande è solitamente dare a Codex il giusto contesto del task e una struttura chiara di ciò che vuoi realizzare.

Una buona impostazione predefinita è includere quattro elementi nel prompt:

• Obiettivo: cosa vuoi cambiare o costruire?
• Contesto: quali file, cartelle, documenti, esempi o errori sono rilevanti per questo task? Puoi menzionare determinati file come contesto con @.
• Vincoli: quali standard, architettura, requisiti di sicurezza o convenzioni deve seguire Codex?
• Completato quando: cosa deve essere vero prima che il task sia completo, ad esempio test che passano, comportamento che cambia o un bug che viene risolto?

Questo aiuta Codex a rimanere concentrato, fare meno supposizioni e produrre un lavoro più facile da revisionare e validare.

Scegli un livello di ragionamento in base alla difficoltà del task e testa cosa funziona meglio per il tuo flusso di lavoro. Utenti e task diversi traggono vantaggio da impostazioni diverse.

• Basso per task più veloci e ben definiti
• Medio o Alto per modifiche più complesse o debug
• Molto Alto per task lunghi, agentici e con molto ragionamento

Consiglio per i nuovi utenti

: La maggior parte delle persone prende confidenza più velocemente iniziando con qualche piccolo successo, come fare domande a Codex sul codebase o usarlo per una piccola correzione mirata. Consiglio vivamente di usare la dettatura vocale nell'app Codex per accelerare le iterazioni.

Livelli di ragionamento di Codex

2. Riduci gli errori nei task difficili chiedendo a Codex di pianificare prima

Se il task è complesso, ambiguo o difficile da descrivere chiaramente, chiedi a Codex di pianificare prima di iniziare a scrivere codice.

Ci sono alcuni buoni modi per farlo:

Usa la modalità Piano: Per la maggior parte degli utenti, questa è l'opzione più semplice ed efficace. La modalità Piano permette a Codex di raccogliere contesto, fare domande di chiarimento e costruire un piano più solido prima dell'implementazione. Attivala con /plan o Maiusc+Tab.

Chiedi a Codex di intervistarti: Se hai un'idea approssimativa di ciò che vuoi ma non sei sicuro di come descriverla bene, chiedi a Codex di farti prima delle domande. Digli di mettere in discussione le tue supposizioni e trasformare l'idea vaga in qualcosa di concreto prima di scrivere codice.

Usa un template PLANS.md: Per flussi di lavoro più avanzati, puoi configurare Codex per seguire un template PLANS.md o di piano di esecuzione per lavori più lunghi o multi-step. Per maggiori dettagli, consulta la nostra guida ai piani di esecuzione.

Modalità Piano

3. Rendi le linee guida di successo riutilizzabili con AGENTS.md

Una volta che un modello di prompt funziona, il passo successivo è smettere di ripeterlo manualmente. È qui che entra in gioco AGENTS.md.

Pensa ad AGENTS.md come a un README per agenti. È un formato semplice e aperto che viene caricato automaticamente nel contesto ed è il posto migliore per codificare come vuoi che Codex lavori in un repository.

Un buon AGENTS.md di solito copre:

• La struttura del repo e le directory importanti
• Come eseguire il progetto
• Comandi per build, test e lint
• Convenzioni di ingegneria e aspettative per le PR
• Vincoli e regole da non fare
• Cosa significa "completato" e come verificare il lavoro

Il comando slash /init nella CLI è il comando rapido per creare uno starter AGENTS.md nella directory corrente. È un ottimo punto di partenza, ma dovresti modificare il risultato per adattarlo a come il tuo team costruisce, testa, revisiona e pubblica il codice.

Puoi creare file AGENTS.md a più livelli: un AGENTS.md globale per le impostazioni personali che si trova in ~/.codex, un file a livello di repo per gli standard condivisi e file più specifici in sottodirectory per regole locali. Se c'è un file più specifico più vicino alla tua directory corrente, quelle linee guida hanno la precedenza.

Mantienilo pratico. Un AGENTS.md breve e accurato è più utile di un file lungo pieno di regole vaghe. Inizia con le basi, poi aggiungi nuove regole solo dopo aver notato errori ripetuti.

Se AGENTS.md inizia a diventare troppo grande, mantieni il file principale conciso e fai riferimento a file markdown specifici per task come pianificazione, revisione del codice o architettura.

Consiglio

: Quando Codex commette lo stesso errore due volte, chiedigli una retrospettiva e aggiorna AGENTS.md. Le linee guida rimangono pratiche e basate su problemi reali.

Sito web di AGENTS.md

4. Ottieni un comportamento più coerente configurando Codex per adattarlo al tuo flusso di lavoro

La configurazione è uno dei modi principali per rendere il comportamento di Codex più coerente tra sessioni e superfici. Ad esempio, puoi impostare valori predefiniti per la scelta del modello, lo sforzo di ragionamento, la modalità sandbox, la politica di approvazione, i profili e la configurazione MCP.

Un buon schema di partenza è:

• Mantieni le impostazioni personali in ~/.codex/config.toml (Impostazioni → Configurazione → Apri config.toml dall'app Codex)
• Mantieni il comportamento specifico del repo in .codex/config.toml
• Usa override da riga di comando solo per situazioni occasionali (se usi la CLI)

Config.toml è dove definisci preferenze durevoli come server MCP, profili, configurazione multi-agente e funzionalità sperimentali. Puoi modificarlo direttamente o chiedere a Codex di aggiornarlo per te.

Codex include un sandboxing a livello di sistema operativo e ha due controlli chiave che puoi gestire. La modalità di approvazione determina quando Codex chiede il tuo permesso per eseguire un comando, e la modalità sandbox determina se Codex può leggere o scrivere nella directory e quali file l'agente può accedere.

Se sei completamente nuovo agli agenti di codifica, il consiglio è di iniziare in modo conservativo con autorizzazioni predefinite. Mantieni approvazione e sandboxing stretti per impostazione predefinita, poi allenta le autorizzazioni solo per repo fidati o flussi di lavoro specifici quando la necessità è chiara.

Nota che la CLI, l'IDE e l'app Codex condividono tutti gli stessi livelli di configurazione. Scopri di più nella nostra pagina di documentazione sulla configurazione di esempio.

Consiglio

: Configura Codex per il tuo ambiente reale fin dall'inizio. Molti problemi di qualità sono in realtà problemi di configurazione, come la directory di lavoro sbagliata, mancanza di permessi di scrittura, impostazioni di modello errate o strumenti e connettori mancanti.

5. Migliora l'affidabilità chiedendo a Codex di testare, validare e revisionare il lavoro

Non fermarti a chiedere a Codex di fare una modifica. Chiedigli di creare test quando necessario, eseguire i controlli pertinenti, validare il risultato e revisionare il lavoro prima di accettarlo.

Codex può fare questo ciclo per te, ma solo se sa cosa significa "buono". Quelle linee guida possono venire dal prompt o da AGENTS.md.

Questo può includere:

• Scrivere o aggiornare i test per la modifica
• Eseguire le giuste suite di test
• Controllare lint, formattazione o type check
• Confermare che il comportamento finale corrisponda alla richiesta
• Revisionare il diff per bug, regressioni o pattern rischiosi

Consiglio:

Attiva il pannello diff nell'app Codex per

revisionare le modifiche localmente. Clicca su una riga specifica per fornire feedback che verrà inserito come contesto per il turno successivo di Codex.

Un'opzione utile qui è il comando slash /review, che ti offre diversi modi per revisionare il codice:

• Revisione rispetto a un branch base per una revisione in stile PR
• Revisione delle modifiche non committed
• Revisione di un commit
• Utilizzo di istruzioni di revisione personalizzate

Se tu e il tuo team avete un file code_review.md a cui si fa riferimento in AGENTS.md, Codex può seguire quelle linee guida anche durante la revisione. Questo è un modello efficace per i team che vogliono che il comportamento di revisione rimanga coerente tra repository e contributori.

Codex non dovrebbe solo generare codice. Con le giuste istruzioni, può anche aiutare a testarlo, validarlo e revisionarlo.

Se usi GitHub Cloud, puoi facilmente configurare Codex per eseguire code review per le tue PR. In OpenAI, facciamo revisionare il 100% delle PR da Codex. Hai la possibilità di abilitare revisioni automatiche o far sì che Codex revisioni in modo reattivo quando menzioni @Codex.

/review in Codex CLI

6. Porta strumenti esterni e contesto live in Codex con gli MCP

Usa gli MCP quando il contesto di cui Codex ha bisogno si trova al di fuori del repo. Permette a Codex di connettersi agli strumenti e ai sistemi che già usi, così non devi continuare a copiare e incollare informazioni live nei prompt.

Il Model Context Protocol, o MCP, è uno standard aperto per connettere Codex a strumenti e sistemi esterni.

Usa MCP quando:

• Il contesto necessario si trova al di fuori del repo
• I dati cambiano frequentemente
• Vuoi che Codex usi uno strumento invece di basarsi su istruzioni incollate
• Hai bisogno di un'integrazione ripetibile tra utenti o progetti

Codex supporta sia server STDIO che Streamable HTTP con OAuth.

Nell'app Codex, vai su Impostazioni → Server MCP per vedere server personalizzati e consigliati. Spesso Codex può aiutarti a installare i server necessari. Devi solo chiedere. Puoi anche usare il comando codex mcp add nella CLI per aggiungere i tuoi server personalizzati con un nome, un URL e qualsiasi informazione aggiuntiva.

Consiglio

: Aggiungi strumenti solo quando sbloccano un vero flusso di lavoro. Non iniziare collegando tutti gli strumenti che usi. Inizia con uno o due strumenti che chiaramente rimuovono un loop manuale che fai già spesso, poi espandi da lì.

Gestione dei server MCP

7. Trasforma i flussi di lavoro ripetitivi in competenze riutilizzabili

Una volta che un flusso di lavoro diventa ripetibile, smetti di fare affidamento su prompt lunghi o continui scambi. Usa una Competenza per impacchettare le istruzioni in un file SKILL.md, contesto e logica di supporto che Codex dovrebbe applicare in modo coerente. Le competenze funzionano in CLI, nell'estensione IDE e nell'app Codex.

Mantieni ogni competenza strettamente focalizzata su un singolo compito. Inizia con 2 o 3 casi d'uso concreti, definisci input e output chiari e scrivi la descrizione in modo che dica chiaramente cosa fa la competenza e quando usarla. Includi il tipo di frasi trigger che un utente direbbe effettivamente.

Non cercare di coprire ogni caso limite in anticipo. Inizia con un task rappresentativo, fallo funzionare bene, poi trasforma quel flusso di lavoro in una competenza e miglioralo da lì. Includi script o asset extra solo quando migliorano significativamente l'affidabilità.

Una buona regola pratica: se continui a riutilizzare lo stesso prompt o a correggere lo stesso flusso di lavoro, probabilmente dovrebbe diventare una competenza.

Le competenze sono particolarmente utili per lavori ricorrenti come:

• Triage dei log
• Bozze di note di rilascio
• Revisione PR basata su una checklist
• Pianificazione della migrazione
• Riepiloghi di telemetria o incidenti
• Flussi di debug standard

La competenza $skill-creator è il posto migliore per iniziare a creare la prima versione di una competenza e usare la competenza $skill-installer per installarla localmente. Una delle parti più importanti di una competenza è la descrizione. Dovrebbe dire chiaramente cosa fa la competenza e quando usarla.

Consiglio

: Le competenze personali sono memorizzate in

$HOME /.agents/skills, e le competenze condivise del team possono essere inserite in .agents/skills all'interno di un repository. Questo è particolarmente utile per l'onboarding di nuovi membri del team.

Creazione e installazione delle competenze

Interfaccia utente delle competenze nell'app Codex

8. Risparmia tempo sui lavori ricorrenti con le automazioni

Una volta che un flusso di lavoro è stabile, puoi programmare Codex per eseguirlo in background per te. Nell'app Codex, le automazioni ti permettono di scegliere il progetto, il prompt, la cadenza e l'ambiente di esecuzione per un task ricorrente.

Una volta che un task diventa ripetitivo per te, puoi facilmente creare un'automazione nella scheda Automazioni dell'app Codex. Puoi scegliere in quale progetto viene eseguita, il prompt che esegue (puoi invocare competenze) e la cadenza di esecuzione. Puoi anche scegliere se l'automazione viene eseguita in un worktree git dedicato o nel tuo ambiente locale. Scopri di più sui git worktree.

Buoni candidati includono:

• Riepilogare i commit recenti
• Scansionare bug probabili
• Bozze di note di rilascio
• Controllare i fallimenti della CI
• Produrre riepiloghi per gli standup
• Eseguire flussi di lavoro di analisi ripetibili su base programmata

Una regola utile è che le competenze definiscono il metodo, le automazioni definiscono la cadenza. Se un flusso di lavoro ha ancora bisogno di molto controllo, trasformalo prima in una competenza. Una volta che è prevedibile, l'automazione diventa un moltiplicatore di forze.

Consiglio

: Usa le automazioni per riflessione e manutenzione, non solo per l'esecuzione. Rivedi le sessioni recenti, riepiloga gli attriti ripetuti e migliora prompt, istruzioni o configurazione del flusso di lavoro nel tempo.

Creazione di automazioni nell'app Codex

9. Mantieniti organizzato nei lavori di lunga durata con i controlli delle sessioni

Le sessioni di Codex non sono solo cronologia chat. Sono thread di lavoro che accumulano contesto, decisioni e azioni nel tempo, quindi gestirli bene ha un grande impatto sulla qualità.

Gestire più thread è più semplice nell'interfaccia dell'app Codex, con la possibilità di fissare thread e creare worktree. Ma se usi la CLI, questi comandi slash sono particolarmente utili:

• /experimental per attivare/disattivare funzionalità sperimentali e aggiungerle al tuo config.toml
• /resume per riprendere una conversazione salvata
• /fork per creare un nuovo thread preservando la trascrizione originale
• /compact quando il thread diventa lungo e vuoi una versione riassuntiva del contesto precedente. Nota che Codex compatta automaticamente le conversazioni per te
• /agent quando esegui più agenti e vuoi passare al thread dell'agente attivo
• /theme per scegliere un tema di syntax highlighting
• /apps per usare le app ChatGPT direttamente in Codex
• /status per ispezionare lo stato corrente della sessione

Mantieni un thread per ogni unità di lavoro coerente. Se il lavoro fa ancora parte dello stesso problema, rimanere nello stesso thread è spesso meglio perché preserva la traccia di ragionamento. Fai un fork solo quando il lavoro si dirama veramente.

Consiglio:

Usa i flussi di lavoro

multi-agente di Codex per delegare lavoro delimitato dal thread principale. Mantieni l'agente principale concentrato sul problema centrale e usa sotto-agenti per compiti come esplorazione, test o triage.

10. Errori comuni da evitare

Alcuni errori comuni da evitare quando usi Codex per la prima volta:

• Sovraccaricare il prompt con regole durevoli invece di spostarle in AGENTS.md o in una competenza
• Non far vedere all'agente il suo lavoro non fornendo dettagli su come eseguire al meglio i comandi di build e test
• Saltare la pianificazione su task multi-step e complessi
• Dare a Codex il permesso completo sul computer prima che il flusso di lavoro sia compreso
• Eseguire più thread live sugli stessi file senza usare git worktree
• Trasformare un task ricorrente in un'automazione prima che sia affidabile manualmente
• Usare Codex in parallelo con il proprio lavoro invece di trattarlo come qualcosa da monitorare passo dopo passo

Checklist per iniziare

1. Dai a Codex il giusto obiettivo, contesto, vincoli e condizione di completamento
2. Per task difficili, chiedi a Codex di pianificare prima
3. Crea un AGENTS.md iniziale
4. Spiega a Codex come buildare, testare, validare e revisionare
5. Imposta le impostazioni predefinite di configurazione che corrispondono al tuo flusso di lavoro
6. Aggiungi MCP per strumenti esterni di alto valore
7. Trasforma i flussi di lavoro ripetitivi in competenze
8. Usa le automazioni una volta che un flusso di lavoro è stabile

Più trasformi il tuo flusso di lavoro, standard e contesto in qualcosa che Codex può usare, più vedrai cosa l'agente può realmente fare. Inizia oggi stesso!