Perché tre file Markdown

Nel 23 ottobre 2026 Google Cloud ha pubblicato su X, tramite il canale Google Cloud Tech, una proposta che definisce tre pattern di architettura Markdown per aumentare la produttività degli agenti. L’idea centrale è chiara: separare le istruzioni per gli agenti in file dedicati anziché sovraccaricare un unico prompt. Questo approccio riduce la quantità di token consumati, migliora la coerenza delle operazioni e limita i rischi di derivazione o di invocazioni non richieste.

Un agente di codice (Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot) è un programma basato su un modello di linguaggio che analizza il codice di un progetto, suggerisce modifiche, esegue test e scrive file al posto del sviluppatore. Il Markdown, con titoli preceduti da “#”, elenchi con “-” e nessun formato speciale, è ormai la lingua comune con cui gli agenti comunicano.

Come funziona la separazione

    • AGENTS.md: descrive l’ambiente del repository, comandi di installazione, compilazione e test, cartelle da non modificare e convenzioni operative.
    • DESIGN.md: fissa lo stile grafico e le linee guida di progettazione visuale.
    • SKILL.md: contiene procedure specifiche invocate solo quando necessario.

AGENTS.md: il README per gli agenti

AGENTS.md è collocato nella radice del repository e funge da “README per gli agenti”. Pubblicato originariamente da OpenAI nell’agosto 2025, è stato poi adottato dalla Agentic AI Foundation (AAIF), una fondazione sotto la Linux Foundation per standard aperti. Il file è progettato per essere breve – circa 12 righe – poiché ogni riga aggiuntiva comporta costi token in ogni turno.

Il contenuto tipico include:

    • Comandi precisi (es. npm ci, npm test).
    • Limiti di modifica (es. “non modificare src/generated/”).
    • Regole di stile (es. “rimani nel perimetro della task, senza refactoring non richiesti”).
    • Riferimenti a SKILL.md per procedure dettagliate.

Esempio di AGENTS.md per Node.js

AGENTS.md


Setup


  • Usa npm, non pnpm né yarn:
    • 

  npm ci

  • Test:
    • 

  npm test

(ejecuta antes npm run pretest)


  • Lint dopo ogni cambio:
    • 

  npm run lint

Limiti


  • Non modificare src/generated/ (file generati)
    • 

  • Non toccare scripts/postinstall.js
    • 

  • Niente build di produzione se non richiesto
    • 

Stile


  • Rimani nel perimetro della task, senza refactor non richiesti
    • 

  • Procedure dettagliate in .agents/skills/
    •

DESIGN.md e SKILL.md: design e procedure

DESIGN.md fissa le linee guida grafiche del progetto, includendo palette di colori, tipografia, layout e best practice di UI/UX. È un file di riferimento per gli agenti che generano componenti visivi o documentazione.

SKILL.md, invece, contiene script e macro invocabili su richiesta. Queste “skill” sono tipicamente piccole funzioni o comandi shell che l’agente può chiamare, ad esempio per eseguire una migrazione di dipendenze o aggiornare una configurazione.

Installazione e utilizzo

Le skill ufficiali di Google e la specifica DESIGN.md sono disponibili su GitHub sotto licenza Apache 2.0. Per usarle con npx è necessario Node.js e un agente compatibile (Gemini CLI, Antigravity, Claude Code). Non è richiesto alcun account Google Cloud per leggere i file.

Impatto sui token e sulla produttività

Google Cloud ha citato uno studio della AAIF pubblicato a luglio 2026. In test con estensioni VS Code, l’inclusione di un AGENTS.md di 12 linee ha ridotto:

    • Dimensione dei cambi: ‑26 %
    • Tempo di esecuzione: ‑27 %
    • Consumo di token: ‑25 %

Le prove, condotte su cinque esecuzioni per condizione, hanno mostrato una differenza significativa nelle code di distribuzione: senza AGENTS.md, due esecuzioni hanno speso tempo in ricerca di contesto o hanno avviato build di produzione non richieste, mentre con il file nessun errore è stato riscontrato.

Limiti consigliati

    • Cursor suggerisce max 500 linee per AGENTS.md.
    • Claude Code raccomanda meno di 200 linee.
    • Codex trunca il file oltre 32 KiB (parametro projectdocmax_bytes).

Applicazioni pratiche e consigli

Per i monorepos è possibile inserire AGENTS.md nelle sottocartelle, ma solo dove le regole differiscono da quelle della radice. Questo mantiene il contesto pertinente e ottimizza il consumo di token.

Quando si redige un AGENTS.md, è fondamentale:

    • Essere precisi nei comandi e nei percorsi.
    • Evitare consigli generici (“segui le buone pratiche”).
    • Limitare il file a circa 12 righe per progetti di dimensioni moderate.

Conclusioni

La proposta di Google Cloud di utilizzare AGENTS.md, DESIGN.md e SKILL.md rappresenta una svolta nella gestione degli agenti di codice. Separando responsabilità, riducendo token e fornendo istruzioni contestuali, questi file migliorano l’efficienza, la coerenza e la sicurezza dei flussi di lavoro automatizzati. Con il crescente utilizzo dei modelli di linguaggio come assistenti di sviluppo, adottare questi standard aperti potrebbe diventare una pratica di riferimento per team di ogni dimensione.