Quali convenzioni di directory e stili di codice seguono bene Codex e Claude Code?
Codex e Claude Code non preferiscono intrinsecamente un particolare linguaggio di programmazione, framework, ampiezza di indentazione o layout delle cartelle. Gli ambienti che possono seguire con relativa affidabilità sono quelli in cui le convenzioni esistenti del repository sono coerenti, l'ambito delle regole richieste è chiaro e le modifiche possono essere convalidate automaticamente. L'obiettivo, quindi, non è inventare una struttura che possa piacere a un'IA, ma rendere le convenzioni del progetto brevi, comprensibili e verificabili per le persone e per i nuovi contributori. openai.comcode.claude.com
Qui, Codex e Claude Code indicano strumenti di agenti di coding in grado di leggere file in un repository, consultare istruzioni, modificare codice o eseguire comandi. Questi strumenti ricavano molti indizi dal codice stesso, ma non sempre possono dedurre con precisione la terminologia del dominio di prodotto, le modifiche vietate, i controlli pre-distribuzione o le regole di eccezione per cartelle specifiche. Struttura del repository, file di istruzioni e procedure di convalida eseguibili colmano questa lacuna. cdn.openai.com
Perché la coerenza è più importante della “struttura di cartelle giusta”?
Per esempio, un team potrebbe organizzare src/payments/ e src/users/ per funzionalità, mentre un altro potrebbe organizzare src/controllers/, src/services/ e src/repositories/ per livello. Non esiste una base per affermare in modo conclusivo che uno dei due approcci sia automaticamente migliore per Codex o Claude Code. Ciò che conta è che responsabilità dello stesso tipo abbiano posizioni simili all'interno di un repository, che i nuovi file siano collocati secondo gli stessi criteri e che test e stili di importazione seguano i pattern esistenti.
Lo stesso vale quando un agente aggiunge una nuova funzionalità di pagamento. Se il modulo dei pagamenti esistente mostra come sono disposti convalida delle richieste, gestione degli errori, accesso ai dati e test, proseguire con quel pattern è più sicuro. Al contrario, se ogni nuova funzionalità introduce nuovi nomi di file e livelli, oppure se una singola cartella mescola codice di dominio con artefatti di build e file temporanei, sia gli agenti sia le persone avranno difficoltà a stabilire dove apportare modifiche e su cosa tali modifiche incidono.
Le convenzioni di directory non sono quindi semplici regole estetiche. Sono un sistema di navigazione che indica dove trovare il codice, cosa modificare insieme e quale convalida eseguire. Quanto più stabili sono nomi e confini, tanto minore è la necessità di ripetere lunghe spiegazioni nei file di istruzioni.
Dove dovrebbe risiedere la guida di base del repository?
In Codex, AGENTS.md svolge generalmente il ruolo di file di istruzioni del progetto. Le istruzioni su stile del codice, struttura, denominazione e test contenute in questo file si applicano alla directory che lo contiene e al relativo sottoalbero, mentre istruzioni in posizioni più profonde possono costituire una guida più specifica in caso di conflitti. Sono supportate anche istruzioni per l'ambiente personale e override tramite AGENTS.override.md. openai.com
In Claude Code, CLAUDE.md o .claude/CLAUDE.md può fungere da centro per la memoria e la guida del progetto. Un CLAUDE.md in un percorso padre può essere fornito come contesto all'avvio, mentre i file nelle sottodirectory vengono caricati quando necessario durante la gestione dei file in tali percorsi. Puoi inoltre usare CLAUDE.local.md per impostazioni per utente e file a livello della directory home. code.claude.com
Benché i due file abbiano nomi simili, il loro comportamento di individuazione automatica non è lo stesso. In particolare, non presumere che Claude Code legga automaticamente AGENTS.md come istruzioni condivise. Quando usi entrambi gli strumenti, importa il file condiviso in CLAUDE.md con @AGENTS.md, oppure definisci esplicitamente un collegamento adatto al modello operativo del team. code.claude.com
È preferibile che il file di guida nella radice assomigli più a una mappa di accesso che a un'enciclopedia che descrive a lungo l'intero repository. È sufficiente mostrare i comandi di cui un nuovo contributore ha bisogno per primi, la struttura di livello superiore, le principali invarianti e le posizioni della documentazione dettagliata. Un file di istruzioni unico e lungo consuma contesto che dovrebbe essere usato per il codice effettivo e i requisiti dell'attività e può rendere più difficili da notare i vincoli critici. Un esempio relativo a OpenAI Codex presenta anch'esso una combinazione di un breve file simile a una mappa, di circa 100 righe, e documentazione separata. openai.com
Cosa dovrebbero includere AGENTS.md e CLAUDE.md?
Le buone istruzioni non duplicano ampiamente fatti già evidenti dal codice. Danno invece priorità alle informazioni difficili da apprendere dal solo codice o costose da dedurre in modo errato. I materiali relativi a Codex identificano convenzioni di denominazione, linguaggio di dominio, vincoli e dipendenze noti, nonché procedure di build e test, come informazioni che vale la pena inserire in AGENTS.md. cdn.openai.com
Le istruzioni nella radice possono rispondere in modo conciso a domande come:
- Quali comandi eseguono formattazione, analisi statica, controllo dei tipi e test dopo una modifica iniziale?
- Dove si trovano codice sorgente, test, documentazione di progettazione e documentazione operativa?
- Quali convenzioni per nomi di file, importazioni, gestione degli errori e test vanno seguite quando si estende un modulo esistente?
- I file generati, gli artefatti di build, i file di lock e i segreti possono essere modificati o inclusi nel repository?
- Le aree ad alto rischio richiedono un piano, una revisione aggiuntiva o test specifici?
- Quali documenti contengono procedure dettagliate di progettazione e operative?
Al contrario, affermazioni generiche come “scrivi codice pulito”, “dai priorità alla sicurezza” o “fai del tuo meglio” sono difficili da trasformare in regole eseguibili. Un'affermazione come “usa il modulo di convalida esistente per l'input esterno e aggiungi il corrispondente test di integrazione per ogni nuova route API” è più utile perché può essere osservata e verificata. La guida di Claude Code sottolinea allo stesso modo l'importanza di scrivere concretamente regole specifiche del progetto e di rivedere e organizzare periodicamente le istruzioni man mano che crescono. code.claude.com
Le istruzioni dovrebbero essere una registrazione compressa dei criteri decisionali, non un documento che detta ogni dettaglio di implementazione. La conoscenza lunga e soggetta a cambiamenti, ad esempio come usare una particolare libreria, i contratti API o l'ordine di risposta agli incidenti, è più facile da mantenere se spostata in un documento appropriato sotto docs/, mentre le istruzioni nella radice ne indicano posizione e condizioni d'uso.
Quando servono regole per singole sottodirectory?
Le regole per sottodirectory non sono file da aggiungere meccanicamente a ogni cartella. Dove sono sufficienti regole condivise nella radice, file separati possono invece aumentare il sovraccarico di navigazione e la possibilità di conflitti. È preferibile riservarli a confini che si discostano chiaramente dalle regole generali o nei quali gli errori hanno conseguenze significative.
Per esempio, src/payments/ può documentare come esprimere i calcoli monetari, come usare i mock per provider di pagamento esterni e quale comando specifico per i test di integrazione eseguire. infra/ può richiedere un piano prima delle modifiche, controlli prima di applicarle e limiti sui file specifici dell'ambiente che possono essere modificati. generated/ può dichiarare che le modifiche dirette sono vietate e identificare la sorgente e il comando di generazione. Lo scopo di queste regole non è far apparire speciale la cartella, ma fornire con precisione nel contesto di lavoro i vincoli effettivi di quell'area.
Per Codex, un AGENTS.md annidato si applica al di sotto della propria directory e file più profondi possono fornire regole più specifiche. Claude Code può analogamente accumulare più file CLAUDE.md come contesto, perciò è più sicuro che i file annidati aggiungano condizioni concrete necessarie solo in quell'area, invece di fare dichiarazioni ambigue che annullano i file padre. openai.comcode.claude.com
Per esempio, la radice potrebbe dire “Esegui i test per il pacchetto che hai modificato”, mentre la cartella dei pagamenti dice “Se il contratto di pagamento cambia, esegui sia i test unitari sia quelli di integrazione”. Al contrario, scrivere “I test devono essere sempre eseguiti” nella radice e “Non eseguire test” in una sottocartella lascia incerti non solo gli strumenti, ma anche le persone, su quale regola seguire.
Come andrebbero suddivise le .claude/rules/ di Claude Code?
In Claude Code, puoi inserire le regole globali sempre necessarie in CLAUDE.md e suddividere le regole con argomenti distinti o comportamento dipendente dal percorso in piccoli file sotto .claude/rules/. I file di regole possono essere organizzati ricorsivamente e le condizioni di percorso possono applicare regole solo a file o aree specifici. code.claude.com
Il criterio di suddivisione non è il numero di file, bensì la coesione delle regole che cambiano insieme. Per esempio, i comandi di test e i principi relativi ai dati di test possono andare in testing.md; le eccezioni per importazioni, denominazione e formattazione possono andare in code-style.md; i vincoli relativi a segreti, richieste esterne e autorizzazioni possono andare in security.md. Ogni file dovrebbe trattare un unico argomento e il suo titolo dovrebbe chiarire quando va letto.
Il vantaggio di questo approccio è che le istruzioni non necessarie non devono essere lette integralmente ogni volta. Per esempio, se le regole complete sulle migrazioni del database restano mescolate al lavoro che modifica solo la documentazione, possono oscurare le istruzioni principali. Tuttavia, suddividere le regole in modo troppo granulare rende difficile trovare dove si trovano. Un approccio equilibrato consiste nel presentare brevemente nella radice CLAUDE.md i principali gruppi di regole e i loro scopi, mantenendo però il contenuto effettivo in file specifici per argomento.
Dopo aver separato le regole, evita di copiare lo stesso obbligo in più file. Le copie divergono facilmente nel tempo. Mantenere i principi condivisi in un solo punto e registrare solo eccezioni e condizioni aggiuntive nei file specifici per percorso riduce i conflitti.
Come dovrebbe essere specificato lo stile del codice?
Uno “stile del codice adatto all'IA” non significa una scelta universale, come tabulazioni anziché spazi o programmazione funzionale anziché orientata agli oggetti. Il criterio più importante è se le convenzioni locali del repository possono essere riprodotte. Revisioni e manutenzione diventano più semplici quando un nuovo modulo segue i pattern dei moduli esistenti per nomi di file, stile di esportazione, ordine delle importazioni, percorsi di gestione degli errori e struttura dei test.
Vale particolarmente la pena documentare ogni scelta del progetto che differisce dalle convenzioni comuni del linguaggio. La documentazione di Claude Code usa come esempi di stile di codice specifico del progetto i moduli ES o il destrutturamento delle importazioni con nome. In altre parole, anziché riscrivere ogni regola predefinita di un linguaggio, è più efficiente descrivere “ciò che il nostro progetto fa diversamente dal valore predefinito”. code.claude.com
La tabella seguente fornisce criteri semplici per decidere le indicazioni sullo stile.
| Area | Più facile lasciare a codice e strumenti | Meglio dichiarare nelle istruzioni |
|---|---|---|
| Formattazione | La configurazione del formatter è nel repository e il comando è definito | Alcuni tipi di file richiedono eccezioni al formatter |
| Importazioni | I file esistenti seguono un pattern uniforme | Esistono regole particolari, come vietare le esportazioni predefinite o usare alias interni |
| Gestione degli errori | I tipi di errore condivisi e i flussi di gestione sono coerenti | Esistono vincoli di dominio, come vietare i tentativi ripetuti o separare i messaggi per gli utenti |
| Test | Posizioni e nomi dei test sono coerenti | Alcune modifiche richiedono test contrattuali o test di integrazione |
| Denominazione | I termini di dominio sono usati con coerenza nel codice | Esistono nomi ufficiali o termini vietati per concetti facilmente confondibili |
Formatter, linter e controllori dei tipi rendono lo stile verificabile meccanicamente invece di imporlo tramite prosa. Pertanto, è meglio che le istruzioni specifichino i comandi effettivi da eseguire e la gestione prevista dei fallimenti, anziché dire “formatta bene le cose”. Le best practice di Claude Code raccomandano anche istruzioni di progetto chiare e flussi di sviluppo verificabili. code.claude.com
Con quale struttura di directory puoi iniziare?
Quello che segue è un esempio utilizzabile quando si considerano insieme Codex e Claude Code. Non è uno standard obbligatorio, ma un possibile punto di partenza che separa istruzioni condivise, documentazione dettagliata ed eccezioni specifiche per area.
repo/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── ARCHITECTURE.md
├── docs/
│ ├── design-docs/
│ ├── product-specs/
│ ├── runbooks/
│ └── generated/
├── src/
│ ├── feature-a/
│ └── feature-b/
├── tests/
└── .claude/
├── rules/
│ ├── testing.md
│ ├── code-style.md
│ └── security.md
└── settings.json
Qui, README.md può contenere le informazioni necessarie alle persone per iniziare a lavorare con il repository, ARCHITECTURE.md può descrivere i principali confini e la struttura del sistema e docs/ può ospitare conoscenza di progettazione, prodotto e operativa dettagliata e di ampia estensione. Il layout effettivo di src/ e tests/ dovrebbe seguire principalmente la struttura già esistente del progetto. .claude/rules/ è una posizione per regole specifiche per argomento o percorso per Claude Code. code.claude.com
Se temi di avere molti file nella radice, la questione chiave non è il numero di nomi dei file, ma la separazione delle responsabilità. Se un unico file assume contemporaneamente il ruolo di introduzione al progetto, progettazione del sistema, risposta operativa, convenzioni API dettagliate e regole di stile, diventa difficile sapere quali informazioni siano essenziali per l'attività corrente. Al contrario, una breve guida nella radice che rimanda ai documenti dettagliati necessari consente ai contributori di approfondire solo quanto serve.
Lo stesso principio si applica all'inserimento di file di istruzioni in cartelle specifiche per funzionalità. Non aggiungerne uno se la funzionalità non ha regole dedicate; aggiungine uno solo quando esiste un motivo chiaro, come la gestione di dati sensibili o un processo di generazione automatizzato. La proliferazione frequente di file di regole può complicare la struttura stessa invece di spiegarla.
Come puoi ridurre le regole duplicate usando entrambi gli strumenti?
Un'opzione consiste nel mantenere le convenzioni di sviluppo condivise canoniche in AGENTS.md, importarlo dalla radice CLAUDE.md e aggiungere quindi solo il contenuto necessario a Claude Code. Per esempio:
@AGENTS.md
## Claude Code only
- Present a plan before changing `src/payments/`.
- Follow the path-specific rules in `.claude/rules/`.
Questa configurazione riduce la necessità di mantenere ripetutamente comandi di test, regole comuni di denominazione e principi relativi ai file generati in entrambi i file. Allo stesso tempo, conserva regole specifiche di Claude Code e una configurazione basata su .claude/rules/. Tuttavia, come indicato sopra, Claude Code non legge automaticamente AGENTS.md come istruzioni condivise, quindi devi effettivamente configurare un'importazione o un collegamento equivalente. code.claude.com
La posizione del file condiviso può dipendere dall'uso relativo degli strumenti da parte del team e dalle convenzioni esistenti del repository. Se Codex è usato più spesso, AGENTS.md è una fonte canonica semplice; se le operazioni ruotano attorno al sistema di regole di Claude Code, può invece essere CLAUDE.md la fonte canonica. Indipendentemente dalla scelta, il punto essenziale è designare un originale autorevole per ciascuna regola e lasciare nell'altro file solo riferimenti o aggiunte specifiche dello strumento.
È preferibile separare le preferenze individuali dalle convenzioni del team. Gli alias dei comandi in un ambiente personale, le scelte di strumenti locali e le abitudini di lavoro personali possono appartenere a file di override personali. Al contrario, procedure di test, vincoli di sicurezza e struttura del codice che tutti coloro che clonano il repository devono conoscere dovrebbero restare nelle istruzioni di progetto sotto controllo di versione. Sia Codex sia Claude Code supportano configurazioni di istruzioni a livello di progetto e personale. openai.comcode.claude.com
Perché i comandi di convalida dovrebbero essere centrali nelle istruzioni?
Le proposte o le modifiche di un agente di coding possono sembrare plausibili, ma non garantiscono automaticamente correttezza, compatibilità o sicurezza. La guida relativa a Codex spiega inoltre che sono ancora necessarie revisione umana e convalida dell'output. openai.com
Per questo motivo, le buone istruzioni per il repository spiegano non solo “come scrivere codice”, ma anche “come controllarlo”. Dove possibile, elenca i comandi di formattazione, linting, controllo dei tipi, test unitari, test di integrazione e build in forme che possano essere realmente eseguite. Per repository grandi, nei quali richiedere la convalida completa per ogni attività non è pratico, puoi distinguere la convalida minima in base alla posizione della modifica dalle condizioni che richiedono una convalida completa.
Per esempio, gli aggiornamenti della documentazione potrebbero richiedere soltanto il controllo dei collegamenti o una build della documentazione, mentre le modifiche a un contratto API pubblico potrebbero richiedere sia test unitari sia test di integrazione. Le modifiche difficili da annullare, come schemi di database o configurazione dell'infrastruttura, potrebbero richiedere una fase di revisione aggiuntiva. L'importante non è aspettarsi che lo strumento valuti magicamente il rischio, ma registrare esplicitamente nel repository i percorsi di convalida che il team già conosce.
Anche il codice generato e gli artefatti di build dovrebbero essere distinti chiaramente dal punto di vista della convalida. Se i file non devono essere modificati direttamente, documentane la posizione sorgente e la procedura di generazione; se è consentita la modifica di un artefatto, indica quale comando lo aggiorna. È inoltre più sicuro chiarire il principio secondo cui segreti e impostazioni personali specifiche dell'ambiente non appartengono al repository, la posizione dei file di esempio e i passaggi di convalida richiesti.
Quali sono i malintesi e i modelli di fallimento comuni?
Il primo malinteso è che “più istruzioni portano a una migliore conformità”. In pratica, documenti lunghi possono seppellire le regole più importanti. Se le istruzioni sono diventate troppo lunghe, rimuovi spiegazioni duplicate, regole già automatizzate ed eccezioni non più valide, quindi sposta la conoscenza dettagliata in documenti separati. code.claude.comopenai.com
Il secondo è che “ogni cartella necessita di un file di istruzioni”. Le istruzioni annidate sono utili solo dove esistono vincoli speciali. Un file annidato senza specificità aggiunge semplicemente un altro file da leggere e può rendere poco chiaro il suo rapporto con le regole padre.
Il terzo è che “basta rispettare le regole di stile”. Anche se la formattazione è coerente, una modifica non è necessariamente buona se i test non sono stati eseguiti, sono state violate regole di dominio o sono stati modificati direttamente file generati. Automazione dello stile e procedure di test e revisione non sono sostituti; sono salvaguardie che lavorano insieme.
Il quarto è che “lo strumento risolverà autonomamente le contraddizioni nella documentazione”. Quando istruzioni padre e figlie, oppure istruzioni condivise e specifiche dello strumento, sono in conflitto, il risultato diventa difficile da prevedere. Mantieni la stessa regola in un solo punto e chiarisci l'ambito e le condizioni aggiuntive delle regole figlie. Poiché anche la configurazione della memoria di Claude Code gestisce istruzioni gerarchiche, è importante progettare le regole in modo da evitare conflitti. code.claude.com
Infine, evita di trattare un file di istruzioni come una garanzia di qualità. Le istruzioni forniscono contesto che supporta il giudizio di agenti e persone; non sono meccanismi che garantiscono correttezza, sicurezza o superamento dei test del codice generato. La revisione delle modifiche e l'esecuzione della convalida necessaria restano essenziali. openai.com
Cosa dovremmo applicare per primo nel nostro repository?
Non devi riprogettare l'intera struttura delle cartelle fin dall'inizio. È più realistico iniziare con piccoli miglioramenti basati sulle confusioni ricorrenti nel repository corrente. Per esempio, se i nuovi contributori non riescono a trovare il comando di test, aggiungilo alle istruzioni nella radice. Se gli stessi errori si ripetono nel modulo dei pagamenti, aggiungi regole specifiche solo per quel percorso. Se i documenti di progettazione sono mescolati al codice e difficili da esplorare, distingui innanzitutto i tipi di documento all'interno di docs/.
Puoi usare una sequenza di valutazione come questa:
- Identifica le convenzioni di collocazione dei file, denominazione e test che ricorrono realmente nella base di codice corrente.
- Organizza i comandi e le condizioni di errore per formatter, linter, controlli dei tipi e test.
- Identifica vincoli di dominio, aree non modificabili e procedure di generazione difficili da comprendere dal solo codice.
- Scrivi in modo conciso solo il contenuto più importante nel
AGENTS.mdoCLAUDE.mddella radice. - Aggiungi istruzioni annidate o regole specifiche per percorso solo alle aree sensibili che le regole generali non possono spiegare.
- Designa una fonte originale per le regole condivise e lascia nei file dell'altro strumento solo riferimenti e regole specifiche dello strumento.
- Verifica regolarmente se le istruzioni sono state utili nel lavoro reale e se contengono affermazioni non necessarie o contraddittorie.
In questo processo, non devi trattare “facile da comprendere per gli strumenti” e “facile da mantenere per le persone” come obiettivi contrapposti. Documentazione breve e accurata, confini prevedibili dei moduli e convalida eseguibile automaticamente aiutano entrambi. Al contrario, cercare di compensare una struttura difficile da spiegare anche per le persone usando solo file di istruzioni rischia di rendere la documentazione ingombrante.
Conclusione: quali convenzioni dovresti scegliere?
La chiave per convenzioni di directory e stili di codice adatti a Codex e Claude Code non è adottare una particolare struttura di tendenza. Un approccio pratico consiste nel mantenere con coerenza le convenzioni della base di codice esistente, conservare una guida breve nella radice, separare la conoscenza dettagliata in documenti appropriati e aggiungere regole con ambito ristretto solo dove necessario.
Per Codex, puoi usare AGENTS.md; per Claude Code, CLAUDE.md e, quando necessario, .claude/rules/. Se usi entrambi gli strumenti, designa una fonte unica per le regole condivise e collega esplicitamente il file condiviso in Claude Code per ridurre le duplicazioni. Soprattutto, combina le istruzioni con formatter, linter, controlli dei tipi, test e revisione umana. Poiché l'interpretazione delle istruzioni specifiche del prodotto può cambiare a seconda della versione, è consigliabile mantenere le regole piccole e chiare verificando al contempo la documentazione ufficiale degli strumenti che utilizzi effettivamente. openai.comcode.claude.com