CLAUDE.md e AGENTS.md: insegnare le regole al tuo agente

Panoramica

CLAUDE.md e AGENTS.md sono semplici file markdown posti nel tuo repository, che l'agente legge automaticamente all'inizio di ogni sessione. Contengono i tuoi assiomi, la tua stack, le tue convenzioni, le tue regole di sicurezza e il tuo tono. Scriverne uno buono fa la differenza tra correggere in eterno i soliti cinque errori e un agente che semplicemente capisce il tuo progetto. L'idea piu profonda che si accumula e trattare il file come una skills library viva: ogni trappola che incontri migra una volta in un file markdown e non ti costa mai piu niente.

Cosa imparerai

Imparerai esattamente cosa deve andare in un file di regole di progetto, come formulare le regole in assiomi netti che l'agente segue davvero, la differenza tra un CLAUDE.md radice e l'AGENTS.md che Codex e altri harness leggono, e come fare del file un sistema in apprendimento continuo dove ogni correzione ripetuta diventa una regola permanente. Alla fine, avrai un vero file da inserire gia oggi nel tuo progetto.

Prerequisiti

Un setup Claude Code funzionante e la lezione di prompt engineering del Corso 1, perche gli assiomi che vi hai scritto migrano direttamente in questo file. Devi anche avere un progetto sotto version control dal Corso 1, perche il file di regole vive nel repo ed e committato accanto al tuo codice, cosicche tutto il progetto condivide gli stessi standard.

Il problema

Correggi l'agente. Usa il gestore di pacchetti sbagliato, lo correggi. Inserisce un em-dash, lo correggi. Salta il test, lo correggi. Sessione seguente, contesto nuovo, i tre stessi errori. Paghi token e attenzione per riapprendere le stesse lezioni ancora e ancora, perche niente di cio che hai detto e sopravvissuto. L'agente non e stupido, semplicemente non ha memoria tra le sessioni. Un file di regole e questa memoria. Senza di esso, il tuo agente comincia ogni giorno amnesico e tu sei il suo sorvegliante a tempo pieno.

Cos'e realmente un file di regole

CLAUDE.md e un file markdown che Claude Code carica automaticamente e tratta come un'istruzione permanente per tutta la sessione. Ponilo alla radice del tuo repo per regole a livello di progetto. Puoi anche tenerne uno personale sotto ~/.claude/CLAUDE.md per regole che ti seguono su ogni progetto, e Claude Code li fonde. AGENTS.md e il file equivalente che Codex e un numero crescente di altri harness leggono, quindi un team multi-strumento tiene spesso entrambi, o le vere regole in uno e un breve rinvio nell'altro. Tutto cio che altrimenti riscriveresti in ogni prompt ha il suo posto qui: linguaggio, framework, gestore di pacchetti, politica di test, regole di sicurezza, convenzioni di nomenclatura e tono.

• CLAUDE.md radice: regole di progetto, committata nel repo, condivisa da tutti quelli che ci lavorano.
• ~/.claude/CLAUDE.md personale: le tue preferenze inter-progetto, non committata.
• AGENTS.md: lo stesso ruolo per Codex e altri harness, perche i setup multi-strumento restino costanti.
• E caricata a ogni turno, quindi tienila serrata - un file di regole gonfio mangia lo stesso context window di cui il tuo compito ha bisogno.

Scrivere le regole in assiomi

Un agente segue molto meglio un assoluto netto che un paragrafo pieno di sfumature. Formula ogni regola in "Sempre...", "Mai..." o "Ogni... deve...". Raggruppale per tema perche il file resti scansionabile. Ecco un vero CLAUDE.md compatto che potresti depositare oggi in un progetto. Nota che copre le cose che correggi di continuo, non tutto l'immaginabile. Corto e seguito batte lungo e ignorato.

# Project Rules

## Stack
- TypeScript only. No plain JavaScript files.
- Package manager is bun. Never use npm or yarn.
- Framework is Astro for marketing pages, React for the app.

## Conventions
- Use rounded-sm for border-radius on everything.
- Never use em dashes. Use a normal "-" instead.
- Components are PascalCase, files are kebab-case.

## Quality
- Every new feature ships with a test.
- Before you say a task is done, run: bun run lint && bun run typecheck && bun run test.

## Security
- Secrets live in .env, which is gitignored. Never write a key into committed code.
- Default new repos to private.

## Tone
- Direct and concise. No filler, no apologising, no "as an AI".

La filosofia della skills library

E la parte che trasforma un file di configurazione in un vantaggio competitivo. Tratta CLAUDE.md come una biblioteca crescente di sapere duramente conquistato, non come un setup unico. Ogni volta che l'agente fa un errore che si ripetera, non lo correggi solo sul momento - lo scrivi come una regola. L'agente ha scelto la cartella sbagliata per i test? Aggiungi una regola. Ha frainteso il funzionamento del tuo flusso di auth? Aggiungi una nota. Nel giro di qualche settimana, il file diventa un modello preciso del modo in cui il tuo progetto funziona davvero, pieno di trappole che nessun modello generico potrebbe conoscere. L'agente ha allora bisogno di sempre meno guida a mano, perche il sapere istituzionale vive nel repo, non nella tua testa.

• L'innesco e la ripetizione: ogni correzione che puoi immaginare di rifare due volte diventa una regola gia la prima volta.
• Annota le trappole, non solo lo stile: "il Convex Dev Server deve girare prima dei test" vale piu di una regola di nomenclatura.
• Puoi delegarlo all'agente: "Aggiungi una regola nel CLAUDE.md per non rifare mai piu questo errore" funziona ed e un'abitudine da coltivare.
• Il file e condiviso e committato, quindi una trappola che hai scoperto e ormai risolta per ogni sessione futura e ogni membro del team.

Tenerlo vivo, non stantio

Un file di regole marcisce se ti limiti ad aggiungere. Rivedilo dopo i grossi compiti. Cancella le regole che non valgono piu perche la stack e cambiata. Promuovi un'istruzione occasionale utile che incolli di continuo a regola permanente. Spezza un file enorme in sotto-file collegati quando diventa ingestibile, perche puoi rinviare dal CLAUDE.md verso altri file markdown e tenere la radice leggera. L'investimento si ripaga nel modo piu soddisfacente: ogni compito futuro parte da una base piu intelligente, e lo scarto tra te e qualcuno che pilota un agente nudo cresce ogni settimana. E lo stesso ciclo di apprendimento continuo che attraversa il resto del corso - annota la lezione una volta, approfittane per sempre.

Errori frequenti

Gli errori comuni: scrivere un file di regole di 500 righe che seppellisce le regole importanti e mangia il tuo context window; formulare le regole in suggerimenti morbidi ("sarebbe bello se...") che l'agente tratta come opzionali; metterlo in atto una volta e non aggiornarlo mai, cosicche deriva lentamente dal vero progetto; e duplicare le regole tra CLAUDE.md e AGENTS.md finche non si contraddicono. Tienilo serrato, tienilo assoluto, tienilo aggiornato e tieni una sola fonte di verita.

ROI business

Un buon file di regole e l'upgrade di qualita e costanza meno caro che comprerai mai. Trasforma il tuo sapere personale in un asset che vive nel repo, cosicche una nuova sessione d'agente - o una nuova assunzione, o un freelance - e immediatamente produttiva e allo standard, invece di esserlo dopo una settimana di correzioni. Per un fondatore, e il modo di smettere di essere il collo di bottiglia. Il sapere istituzionale che una volta viveva solo nella tua testa e usciva dalla porta a ogni fine sessione ora si accumula in un file che tutto il tuo business condivide. E una leva che tieni per sempre.

Checklist

Sei pronto ad andare avanti quando ognuno di questi punti e vero. Non saltare i punti sul file vivo - e li che c'e il vero valore.

• Hai committato un CLAUDE.md radice nel tuo progetto, con regole su stack, convenzioni, qualita e sicurezza.
• Le tue regole sono formulate in assoluti, non in suggerimenti.
• Hai annotato almeno una vera trappola che prima correggevi a mano.
• Sai come chiedere all'agente di aggiungere una nuova regola quando sbaglia.

Risorse

Tieni nei preferiti la documentazione ufficiale sulla memoria di Claude Code e CLAUDE.md per il comportamento esatto di caricamento e fusione, perche i dettagli evolvono. Gli assiomi che hai salvato nella lezione di prompting del Corso 1 sono il seme di questo file - inseriscili come tue prime regole. Il template di brief di compito d'agente nella libreria di risorse si accorda bene con un file di regole: le regole coprono gli standard costanti, il brief copre le specificita per compito.

La tua missione

Crea un CLAUDE.md alla radice di un vero progetto. Riempilo della tua stack, di tre convenzioni che correggi di continuo, del tuo comando di quality gate e della tua regola di gestione dei segreti. La prossima volta che l'agente fa un errore, non correggerlo solo, incaricalo di aggiungere una regola perche non si ripeta mai. Guarda il file crescere verso qualcosa che solo il tuo progetto potrebbe avere.

Prossima lezione

Con le regole in atto, l'agente conosce i tuoi standard. La prossima lezione impacchetta i tuoi workflow reali: skill e slash command che trasformano un processo multi-passo collaudato in un unico innesco riutilizzabile, perche il lavoro corrente si svolga ogni volta allo stesso modo, senza riscrivere il brief.