Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configura il tuo ambiente e AGENTS.md

Lezione 3 di 20 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Prepara il tuo progetto per Codex
  2. Passaggio 1: Il tuo accesso a Codex
  3. Passaggio 2: Installa l’estensione dell’editor
  4. Passaggio 3: Installa la CLI
  5. Il file AGENTS.md: la guida del tuo progetto
  6. Migliori pratiche per AGENTS.md
  7. Punti chiave

Aggiornato il 3 novembre 2026 sulla base della documentazione di Codex (Codex CLI, Autenticazione, Estensione IDE di Codex, Istruzioni personalizzate con AGENTS.md): il pacchetto @openai/codex-cli e il comando codex auth login non esistono (usa npm install -g @openai/codex e codex login); l’identificativo dell’estensione è openai.chatgpt; l’indirizzo codex.openai.com e i piani “Team, Enterprise o API” sono sostituiti con i metodi di accesso attuali; e l’ordine di lettura di AGENTS.md è chiarito (radice del progetto → directory corrente). Fonti: Codex CLI · Autenticazione · AGENTS.md · Prezzi.

Prepara il tuo progetto per Codex

Prima del tuo primo compito, devono essere pronti due elementi: il tuo accesso a Codex (il tuo account e la connessione a GitHub) e il tuo progetto stesso, definito tramite il file AGENTS.md che guiderà l’agente. La prima parte richiede circa 15 minuti ed è una configurazione una tantum. La seconda determina la qualità di tutto ciò che otterrai da Codex, distinguendo i team soddisfatti da quelli che lo trovano deludente.

Passaggio 1: Il tuo accesso a Codex

Puoi usare Codex con un account ChatGPT o una chiave API. I piani Free e Go forniscono accesso, a seconda dell’attuale distribuzione, a GPT-6 Luna nell’app desktop. A partire dal piano Plus, Codex è disponibile sul web, nella CLI, nell’estensione dell’editor e su iOS, con integrazioni cloud come la revisione automatica del codice. Una chiave API funziona per l’automazione in ambienti condivisi come la CI, utilizzando la CLI, l’SDK o l’estensione, anche se alcune funzionalità potrebbero non essere disponibili. Dettagli e limiti d’uso sono nella pagina dei prezzi di Codex.

Per lavorare nel cloud sui tuoi repository, connetti GitHub quando crei il tuo primo ambiente Codex Cloud (Lezione 2). Quando concedi i permessi, mantienili al minimo: limita l’accesso solo ai repository di cui hai effettivamente bisogno.

Passaggio 2: Installa l’estensione dell’editor

In VS Code e nei suoi derivati (Cursor, Windsurf), installa l’estensione Codex dal marketplace: il suo identificativo è openai.chatgpt:

code --install-extension openai.chatgpt

Quindi apri Codex tramite la sua icona o attraverso la tavolozza dei comandi con Codex: Open Codex Sidebar, ed effettua il login. Xcode e gli IDE JetBrains hanno le loro integrazioni: in JetBrains, apri AI Chat e seleziona Codex.

Passaggio 3: Installa la CLI

# Installazione (macOS e Linux), oppure npm install -g @openai/codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Verifica l'installazione
codex --version

# Effettua il login (browser) o controlla lo stato della connessione
codex login
codex login status

codex login apre il flusso di accesso nel tuo browser. Per una chiave API, passala tramite input standard (printenv OPENAI_API_KEY | codex login --with-api-key). Codex memorizza nella cache le credenziali in un file di testo semplice, ~/.codex/auth.json, o nel portachiavi di sistema, a seconda dell’impostazione cli_auth_credentials_store (file, keyring, auto o ephemeral). Se viene usato il file, trattalo come una password: contiene token di accesso, quindi non committarlo mai. La CLI e l’estensione condividono questa cache.

Il file AGENTS.md: la guida del tuo progetto

AGENTS.md è centrale per usare Codex in modo efficace. È un semplice file Markdown posizionato alla radice del tuo repository che raccoglie istruzioni, convenzioni e comandi specifici del tuo progetto. Quando Codex clona il repo, legge questo file per primo: pensalo come un onboarding automatico per l’agente, esattamente ciò che spiegheresti oralmente a un nuovo membro del team.

L’impatto è immediato. Senza AGENTS.md, se chiedi un test unitario su un progetto che usa Vitest, c’è un’alta probabilità che Codex ti fornisca Jest, perché è la scelta più comune nell’ecosistema. Una singola riga di convenzione è sufficiente per ottenere Vitest giusto al primo colpo, risparmiandoti di dover correggere lo stesso errore cento volte. Ecco la struttura di un file base per un progetto SaaS di gestione fatture.

# AGENTS.md

## Contesto del progetto
Applicazione SaaS per la gestione delle fatture.
Stack: Next.js 15, TypeScript, Prisma, PostgreSQL.

## Convenzioni di codice
- Usa componenti funzionali React (niente classi)
- Nomina i file in kebab-case
- Tipi TypeScript in file .types.ts separati
- Test con Vitest, file .test.ts accanto al codice

## Comandi utili
- `npm run dev` — server di sviluppo
- `npm run test` — esegui i test
- `npm run lint` — controlla il linting
- `npm run build` — build di produzione

## Struttura del progetto
    src/
      app/          → Pagine Next.js (App Router)
      components/   → Componenti React riutilizzabili
      lib/          → Logica di business e utility
      prisma/       → Schema DB e migrazioni

## Regole rigorose
- NON modificare MAI lo schema Prisma senza una migrazione
- NON committare MAI file .env
- Usa sempre le Server Actions per le mutazioni

Come Codex trova i file AGENTS.md

Un singolo file nella radice diventa rapidamente troppo generico. Codex ti permette di sovrapporre le istruzioni in un ordine preciso che devi conoscere:

  1. Livello globale: Nella tua cartella Codex (~/.codex, a meno che CODEX_HOME non lo sovrascriva), Codex legge AGENTS.override.md se esiste, altrimenti AGENTS.md.
  2. Livello di progetto: Partendo dalla radice del progetto (solitamente la radice Git), Codex scende fino alla directory corrente e legge, in ogni cartella attraversata, AGENTS.override.md o, in mancanza, AGENTS.md.
  3. Unione: I file vengono concatenati dalla radice fino alla directory corrente; quelli più vicini alla directory corrente arrivano per ultimi e quindi sovrascrivono le istruzioni più generali.
my-project/
  AGENTS.md              → Istruzioni del progetto
  src/
    api/
      AGENTS.md          → "Le route API usano Zod per la validazione"

Conseguenza pratica: src/api/AGENTS.md viene letto solo se Codex sta lavorando da src/api o da una delle sue sottodirectory, non quando viene lanciato dalla radice. I file vuoti vengono ignorati e la concatenazione si ferma a 32 KiB per impostazione predefinita (project_doc_max_bytes). Se il tuo repo usa già un altro nome, come TEAM_GUIDE.md, aggiungilo a project_doc_fallback_filenames in ~/.codex/config.toml.

Per verificare cosa ha effettivamente caricato Codex, chiedi semplicemente: codex --ask-for-approval never "Riassumi le istruzioni attuali.". Codex ricostruisce la catena di istruzioni ad ogni avvio: se hai dubbi, riavvialo nella directory corretta.

Migliori pratiche per AGENTS.md

Il principio guida è l’esplicitezza. “Usa Vitest, non Jest” è meglio di “Usa il nostro framework di test”, che presuppone una conoscenza che l’agente non ha. Includi sempre i comandi: senza di essi, Codex non saprà come eseguire i tuoi test, il linter o la build, e fornirà codice che non potrebbe verificare. Documenta la struttura come un albero di directory, il che gli impedisce di esplorare alla cieca e creare file nel posto sbagliato.

Infine, elenca i divieti. Le regole scritte come “MAI” sono le più convenienti nel file, perché bloccano errori costosi difficili da correggere: committare un file .env, modificare uno schema senza una migrazione. La disciplina più difficile è mantenere il file aggiornato. Un AGENTS.md che descrive il progetto dell’anno scorso indirizza attivamente Codex verso convenzioni abbandonate: molto peggio che non avere alcun file, poiché l’errore diventa allora sistematico.

Punti chiave

  • La configurazione iniziale richiede un account OpenAI e una connessione GitHub
  • L’estensione IDE e la CLI si installano in pochi minuti
  • AGENTS.md è il file più importante per un uso efficace di Codex
  • Contiene convenzioni, comandi e regole specifiche del tuo progetto
  • I file AGENTS.md nelle sottodirectory abilitano istruzioni contestuali