Progettare prodotti che gli agenti usano davvero: 5 lezioni da Accordo

In breve. Un agente usa davvero solo ciò che può ispezionare prima di toccare. Progettando la superficie agent-facing di Accordo ho fissato cinque regole: ispezione prima di tutto, comandi invece di path, valore nella CLI e non nell'harness, scrittura stretta con dry-run, superficie budgettata con degraded mode dichiarato. Le definizioni stanno nell'hub MCP; qui racconto le scelte di progettazione. Pubblicato il 6 ottobre 2026.

Il fallimento che ha fissato le regole

La domanda che mi ha guidato è scritta nella pagina sulle istruzioni per l'agente: "come faccio a farmi usare davvero dal mio agente?" — e, più utile: "cosa deve saper fare il mio harness prima di riuscirci?"

Il fallimento che volevo evitare è preciso. Una skill che dice "leggi prima ARCHITECTURE.md e la guida di dominio" si comporta in due modi: dentro il mio repository funziona; installata nel progetto di uno sconosciuto si attiva, non trova quei file e produce istruzioni sicure su un codebase che non ha mai letto. L'utente vede una skill che ha risposto, non una che ha fallito — ed è peggio che non spedirla. Da lì le cinque regole.

1. Ispezionabile prima di tutto

Ogni skill spedita apre con lo stesso blocco di orientamento, identico al byte: lancia l'ispezione dell'applicazione, leggi valid, poi problems[], poi limitations[], e tratta ogni limitazione come confine rigido su ciò che puoi affermare. Il blocco è uguale in tutte di proposito: un agente non deve imparare un preambolo diverso per skill.

Un comando dice all'agente cosa l'applicazione è davvero — package, capability, risorse, azioni, policy — letto dal sorgente versionato, in un unico report JSON deterministico. Deterministico sul serio: stesso input, stesso report, senza path assoluti dentro. Un report si può cachare, diffare, committare, e una differenza significa sempre che il progetto è cambiato.

2. Comandi, non path

La cura per il fallimento sopra è raggiungere il progetto via comando invece che via path. La skill non nomina file che potrebbero non esistere: dichiara nel frontmatter un tier, l'unico command che la rende portabile, le superfici di cui ha bisogno e degradesTo — una frase che dice a cosa degrada quando la superficie repository manca. Una skill che non sa dichiarare il proprio degraded mode non ha pensato a cosa significa essere installata.

Dodici skill vivono sotto .claude/skills/, specchiate byte per byte sotto .agents/skills/; undici sono pubblicate nel sottoinsieme distribuibile. Quella trattenuta è la skill di review, che giudica le PR contro documenti che non esistono fuori dal repository — e spedirla sarebbe di nuovo il fallimento numero uno.

3. Il valore nella CLI, non nell'harness

Ciò che un harness deve fornire è una lista di quattro cose: lanciare un comando e leggerne lo stdout, leggere l'exit code, parsare JSON, leggere e scrivere file nel repository. Fine: Node 22 e un checkout. Ciò che non serve: server MCP, rete, credenziali, database, processi longevi, formati specifici per agenti.

È il punto architetturale che ripaga di più: il valore vive nella CLI e nei suoi contratti JSON, non in un'integrazione specifica. Un adattatore può cambiare dove vive un file e come viene annunciato, ma mai cosa dicono le istruzioni — altrimenti due harness smettono di essere lo stesso prodotto. Stesso motivo per cui nessun server MCP è obbligatorio: skill e MCP sono due consegne delle stesse istruzioni. E per cui Gemini non riceve niente, per scelta: un file scritto indovinando le sue convenzioni sembrerebbe supportato e non si caricherebbe mai, in silenzio. Lo stesso fallimento, in un'altra forma.

4. Scrittura stretta, dry-run, umano che approva

I tool di scrittura restano stretti e tutto ciò che genera codice o distrugge stato è dry-run a meno che apply non sia esplicitamente vero. Le mutazioni via MCP non scavalcano mai servizi o workflow, e la mutazione remota resta vincolata a lavoro di produzione che non esiste.

Gli exit code sono identici sulle due superfici — 0 valido, 1 problemi con report completo comunque stampato, 2 illeggibile — così anche un harness che distingue solo zero da non-zero si comporta bene. E la portabilità non è autorizzazione: una skill nel progetto di uno sconosciuto gira con piena autorità di quell'utente, e l'ispezione importa ed esegue la composizione del progetto. Isolamento, non sandbox. Le approvazioni consequenziali restano umane, come nel resto di Accordo.

5. Superficie budgettata, con tetti che rompono la build

La superficie che un agente deve imparare ha un budget, e il budget è applicato: dodici skill, una decina di tool always-on, undici comandi distinti. Ogni tetto ha una ragione scritta — una dozzina di skill è dove le descrizioni iniziano a competere invece di dividersi, una decina di tool è dove un namespace consuma contesto prima ancora di lavorare. Uno script di controllo fallisce la build quando la superficie sfora, così alzare un tetto è una modifica deliberata con un argomento allegato, non una deriva silenziosa.

Fatti e limiti, separati

Fatti, con provenance (pagine verificate il 6 ottobre 2026):

• La domanda di progetto e il fallimento della skill fuori sede (istruzioni per l'agente).
• Blocco di orientamento identico al byte, degradesTo, dodici skill specchiate, nessuna skill per Gemini (stessa pagina).
• Contratto harness in quattro voci, exit code 0/1/2, nessun path assoluto nei report (stessa pagina).
• Ogni comando documentato cita cosa stampa e cosa il report non prova (contratti CLI e MCP).
• Nove tool, cinque risorse, due prompt sul server applicativo stdio; server documentazione anche read-only via HTTP (docs/MCP.md e pagina installazione).

Limiti, dalle stesse fonti:

• Niente autenticazione spedita, niente tenancy su database condiviso, niente worker gestito: la lista completa sta alla pagina dei limiti, non qui.
• Portabilità non è autorizzazione: stesso confine per skill e MCP.
• Cinque regole da un caso costruito — Accordo — non uno standard di mercato.

Domande frequenti

Da dove comincio a rendere agent-accessibile il mio prodotto?

Da un comando di ispezione che stampa JSON deterministico: cosa contiene il progetto, cosa non va, quali sono i limiti. Prima che l'agente tocchi, deve poter leggere valid, problems[] e limitations[].

Skill o MCP?

Sono due consegne delle stesse istruzioni, e il valore resta nei comandi. Parti dalla CLI con contratti JSON; aggiungi skill e MCP come adattatori che non cambiano mai cosa dicono le istruzioni.

Quanti tool devo esporre?

Meno di quelli che pensi, e con un tetto scritto: in Accordo una decina di tool always-on e dodici skill, con un controllo che rompe la build oltre il budget. Ogni voce in più consuma contesto prima ancora di lavorare.