Il coding agentivo sta cambiando a velocità senza precedenti, anche per gli standard del mondo tech. I tutorial e le risorse disponibili online coprono per lo più funzionalità individuali in scenari greenfield semplici.

Durante lo sviluppo di Bob e nell'interazione con innumerevoli professionisti sul campo provenienti da un'ampia gamma di settori, è emersa una serie di concetti che aiutano a migliorare l'efficacia e l'esperienza d'uso di Bob.

Questi concetti si applicano anche a progetti complessi che utilizzano tecnologie non mainstream.

Concetto 1: Il ciclo — esplora, pianifica, implementa, verifica

Il ciclo esplora, pianifica, implementa, verifica, con un loop esterno per il miglioramento continuo di guide e sensori

Il fallimento più comune nell'ingegneria del software agentiva è l'assenza di struttura. La coerenza conversazionale si maschera da struttura e siamo tentati di comprimere tutti i passaggi di un'implementazione in un'unica conversazione. Le sessioni sembrano produttive, ma il costo si rivela solo in fase di revisione.

Scrivere codice a mano imponeva una struttura propria. L'implementazione era costosa, quindi pianificare prima di implementare sembrava ragionevole intuitivamente. La comprensione si accumulava mentre si digitava, e le assunzioni errate tendevano a emergere durante quel processo. Gli agenti AI eliminano quel attrito. Il codice è economico ora, e questo ha anche rimosso la nostra intuizione per la struttura. La struttura che un tempo era un sottoprodotto della lentezza deve ora essere deliberata.

Usare questo ciclo deliberatamente può fornire la struttura necessaria:

Esplorare produce comprensione
Pianificare produce decisioni
Implementare produce codice
Verificare produce evidenze.

Seguire questo ciclo ti aiuta a rimanere concentrato, strutturato e a raggiungere i tuoi obiettivi più rapidamente e in modo più consistente.

Un singolo passaggio attraverso il ciclo può richiedere venti minuti o tre giorni. Un passaggio può contenere sotto-cicli, e come il tempo si divide tra le fasi varia notevolmente con il compito.

Una guida dettagliata del ciclo si trova più avanti in Approfondimento: Esegui il Ciclo.

Concetto 2: La finestra di contesto è la risorsa scarsa

Essere deliberati riguardo alla finestra di contesto è l'abitudine con il rendimento più elevato.

Cos'è la finestra di contesto?

I modelli sono stateless. Una chat non è una sessione attiva con una memoria: ogni turno reinvia tutti i messaggi precedenti e aggiunge la nuova risposta alla fine. La finestra di contesto è la quantità massima di input che un modello può accettare in uno di quei turni. In Bob V2 sono 270k token (gestione della finestra di contesto).

La finestra si riempie prima del primo messaggio:

Caricato in anticipo: il system prompt di Bob, la descrizione della modalità attiva, l'agents.md del repository e una descrizione di ogni tool Model Context Protocol (MCP) connesso (MCP in Bob).
Aggiunto durante la sessione, in modo invisibile: letture di file, risultati dei tool, file di skill che Bob carica, output dei subagent.

La finestra di contesto si riempie e viene compattata in un riassunto

Quando la finestra si riempie, Bob compatta la conversazione. Bob sostituisce la conversazione fino a quel momento con un riassunto, e il lavoro continua. Questo mantiene la sessione attiva, ed è lossy by design. Bob decide automaticamente quali dettagli sopravvivono, e nulla segnala quelli che non sopravvivono. Una sessione che ha subito due compattazioni sta girando su un riassunto di un riassunto.

Una singola chiamata MCP può restituire decine di migliaia di token, e una sequenza di letture di file diluisce ciò che era stato discusso in precedenza nella sessione. Le descrizioni di modalità, i file di regole e i server MCP lo fanno più lentamente e meno visibilmente. Bob suddivide la finestra per fonte, e vale la pena aprire di nuovo quel dettaglio man mano che la configurazione cresce.

L'indicatore della finestra di contesto di Bob, espanso per mostrare la sessione corrente suddivisa per fonte

I Bobcoin vengono calcolati principalmente su base per-token. Quindi il costo di una conversazione cresce in modo quadratico rispetto alla sua lunghezza. Le conversazioni più lunghe costano molti più Bobcoin rispetto a quelle brevi! (Documentazione Bobcoin)

Lavora con la finestra di contesto invece che contro di essa

Suddividi il lavoro in conversazioni separate. Un compito, una sessione. È lo stesso ragionamento della responsabilità singola nel codice. Una conversazione dovrebbe avere un solo motivo di esistere, come "disegna un diagramma dell'architettura del componente X" o "crea un piano di implementazione per la funzionalità Y." Tutto ciò che è nella finestra di contesto influenza ciò che verrà dopo, compresi gli approcci che non hanno funzionato. Una sessione bloccata tende a restare bloccata, perché i tentativi falliti sono ancora lì, e il modello li legge come evidenze su come appare questo compito (context poisoning).
Fai rollback invece di discutere con Bob. Quando una conversazione deriva verso comportamenti indesiderati, fai rollback all'ultimo messaggio corretto, modifica il messaggio e continua da lì. Questo annulla anche tutte le modifiche che Bob ha fatto localmente, mantenendo la finestra di contesto piccola e pulita (rollback).
Conserva tutto ciò che vale la pena conservare in un file, non nella chat. Piani, scoperte e decisioni appartengono a un file. Un collega può revisionare un documento markdown e passarlo a una sessione nuova; un log della chat non lo permette.
I subagent mantengono il lavoro massiccio fuori dalla finestra di contesto. Bob decide quando eseguirne uno, e solo i risultati tornano indietro. Chiederne uno direttamente funziona anche bene, quando un compito produrrà output che nessuno ha bisogno di leggere (subagents).
Sii consapevole di ciò che entra nella finestra di contesto e se aggiunge valore. Controlla regolarmente guide e sensori, come trattato nell'argomento seguente, e dedica tempo a migliorarli.

Concetto 3: Due tipi di mattoni fondamentali — guide e sensori

Nel corso di un progetto lungo, se il codebase migliora o peggiora dipende meno da Bob che da ciò che guida il suo lavoro e controlla il suo output. Ci sono molti mattoni fondamentali disponibili: regole, skill, modalità, hook, subagent, linter esterni e review agent. Quasi tutti svolgono uno di due compiti.

Le guide guidano Bob prima o durante il lavoro (Feedforward). Regole, skill e modalità sono tutte guide.
I sensori riportano dopo che Bob ha agito (Feedback). Test, linter, type checker, sessioni browser interattive e review agent sono tutti sensori.

Un essere umano a un laptop punta una freccia verso Bob, e Bob punta una freccia verso il codice. Una freccia etichettata "guide" entra in Bob dall'alto, annotata con regole, skill e modalità. Una freccia etichettata "sensori" torna dal codice a Bob, annotata con test, linter e review agent.

1. Guide

Tutto ciò che viene fornito a Bob per guidare il lavoro è una guida. Ci sono tre principali mattoni fondamentali che ti aiutano in questo, e funzionano inserendo testo nella finestra di contesto in aggiunta al prompt che hai digitato. Si differenziano per quando quel testo arriva e cosa lo attiva.

Le regole sono sempre attive, le modalità sono attivate dall'utente, le skill sono attivate da Bob

Le regole sono sempre attive. agents.md nella root del repository è quella principale, e il consiglio principale è di tenerla breve. Ogni riga compete per l'attenzione ad ogni singolo turno, quindi un file di regole lungo rende Bob peggiore nel seguire qualsiasi singola regola (rules).
Le modalità sono attivate dall'utente. Le modalità integrate sono: Ask è in sola lettura. Plan lavora attraverso un processo di pianificazione e passa il risultato ad Agent, che prende azione. Le modalità personalizzate possono essere aggiunte facilmente (modes, aggiungere una modalità personalizzata).
Le skill vengono attivate da Bob quando le giudica rilevanti. Solo una breve descrizione della skill è sempre attiva. Il corpo principale della skill viene caricato nel contesto solo su richiesta. Questo rende le skill molto efficienti in termini di token (skills).

Tutto ciò che è nel file di regole usa token ad ogni turno, indipendentemente dal fatto che questo turno ne avesse bisogno, quindi tienilo minimale e lascia che il resto aspetti finché non si applica.

2. Sensori

Tutto ciò che fornisce a Bob un feedback sul lavoro prodotto è un sensore. Quali segnali sono utili dipende dal codebase e dallo stack, quindi l'insieme da avere differisce da progetto a progetto e richiede vero lavoro per essere assemblato. I sensori più preziosi sono eseguibili dalla macchina e vengono eseguiti da Bob durante la fase di implementazione. I sensori si dividono in due categorie.

I sensori computazionali sono deterministici: test, linter, type checker, compilatori. I verdetti sono esatti e ripetibili, abbastanza economici da eseguire frequentemente per Bob. La copertura è limitata dai sistemi che un team ha costruito e mantiene.
I sensori basati su AI sono flessibili e non deterministici. Un review agent legge per l'intento, e per le cose per cui un linter non ha regole. L'output è un giudizio, non una misurazione. Varia tra le esecuzioni e il costo e la durata limitano la frequenza con cui può essere utilizzato (code reviews).

Collegarli ha diverse opzioni, in ordine approssimativo di attrito:

Gli hook sono l'opzione deterministica con meno attrito. Un controllo viene eseguito in un punto fisso, ogni volta, indipendentemente dal fatto che Bob lo ritenesse rilevante. Vedi la documentazione degli hook.
Le skill sono spesso usate come guide, ma una skill che esegue una revisione è un sensore, ed è il modo con meno attrito per aggiungere un controllo non deterministico. Vedi la documentazione delle skill.
La continuous integration (CI) mette un review agent nella pipeline, su ogni pull request, per l'intero team piuttosto che per un singolo sviluppatore. Vedi il PR review agent in azione.

Approfondimento: Esegui il Ciclo

I confini di fase sono anche confini di contesto, che è la ragione pratica per mantenerli distinti: il chiacchiericcio esplorativo non ha motivo di essere nella conversazione in cui viene scritto il codice.

1. Esplora

L'esplorazione varia notevolmente a seconda del ruolo e del compito in questione. Può significare integrarsi in un nuovo codebase o stimare il raggio d'azione di un refactoring importante. Alcuni esempi:

Fai produrre a Bob un diagramma dell'architettura del sistema esistente prima di modificarlo. Vedi il tutorial per generare diagrammi di architettura, o la stessa cosa in video.
Chiedi una guida introduttiva personalizzata da due angolazioni, una come utente che si muove attraverso il prodotto e una come sviluppatore che si muove attraverso il codice. Fornire informazioni sulla tua esperienza e sul compito aiuta a personalizzare il documento (ispezione di un codebase).
Su IBM Z e IBM i, usa le opzioni specifiche della piattaforma. Il problema dell'esplorazione su quei sistemi è diverso e beneficia enormemente degli strumenti specializzati forniti nei pacchetti premium. Vedi Premium Package for Z (docs) e il Premium Package for IBM i (docs).

L'esplorazione può anche includere la costruzione di cose che intendi eliminare. L'implementazione è economica ora, quindi un prototipo ristretto è il modo più rapido per scoprire se un approccio sopravvive al contatto con il codebase. Kent Beck lo chiamava spike implementation venticinque anni fa, e la disciplina è la stessa: costruiscilo per imparare qualcosa, conserva l'apprendimento, butta via il codice.

L'implementazione economica aumenta il valore dell'architettura e della qualità del codice piuttosto che abbassarlo. È ora facile produrre una grande quantità di codice che funziona ma è sbagliato.

2. Pianifica

La fase di pianificazione è quella con la leva maggiore. Tutto ciò che il piano fa bene paga due volte: una volta nell'implementazione, e di nuovo quando il cambiamento lascia le mani dell'autore e un collega deve revisionarlo.

Cosa serve a un buon piano:

Breve e preciso, entrambi. I piani devono essere letti.
Esplicito sul risultato atteso, compresi i punti incerti. Sapere cosa è sconosciuto è la maggior parte del lavoro, e scoprirlo è il resto.
In un file. I piani non dovrebbero vivere in una sessione di chat.

Ci sono molti modi per creare un piano, ma la modalità Plan integrata è il posto più semplice da cui iniziare (come in questo tutorial). La modalità Plan è progettata per essere accomodante e tende a riempire le lacune. Sebbene questo consenta iterazioni veloci in molti casi, a volte è necessario più rigore. Potrebbe costruire un piano competente attorno a un'assunzione sbagliata senza mettere in discussione l'assunzione. Una skill dedicata che mette in discussione il piano — grill-me di Matt Pocock per esempio — è il modo più economico per ottenere scrutinio prima che l'assunzione diventi codice.

Sullo spec-driven development (SDD). Il termine copre molto terreno ed è ancora in evoluzione. Le persone lo trattano come una decisione sì-o-no, ma è più vicino a uno spettro:

Spec-first: il piano viene prima dell'implementazione. Questo è quasi non negoziabile.
Spec-anchored: la spec rimane dopo l'implementazione, come documentazione e come standard che le implementazioni devono rispettare.
Spec-as-source: la spec è il file sorgente. L'essere umano modifica la spec; l'essere umano non modifica il codice.

Quale livello sia adatto dipende dal team, dalla criticità/maturità del codebase e dal settore. Il sovraccarico derivante dai livelli più alti di SDD può essere doloroso per un'iterazione rapida. In automotive, dove lo spec-driven development precede l'AI di decenni, l'SDD si adatta molto bene alle pratiche esistenti.

3. Implementa

L'implementazione è la fase diretta, e Bob gestisce quasi tutto.

Osservare Bob mentre lavora e interrompere per chiarire è opzionale e spesso utile. Tratta la frequenza come un segnale: le interruzioni costanti significano che il problema è nel piano, e la soluzione è tornare indietro piuttosto che continuare a correggere.

Non essere riluttante a buttare via un'intera implementazione e tornare alla modalità Plan. Il codice è la parte economica.

4. Verifica

La verifica si suddivide in due categorie distinte: verifica automatizzata e verifica manuale.

La verifica automatizzata è guidata dai sensori che Bob ha disponibili o che vengono applicati tramite hook. Vengono eseguiti frequentemente durante la fase di implementazione senza intervento umano. Le principali categorie con alcuni esempi comuni sono:

Validità: Compila, passa il typecheck, viene parsato?
- Misurato: pass/fail, copertura dei tipi
- Strumenti: tsc, mypy, cargo check, javac
Comportamento: Fa la cosa giusta?
- Misurato: tasso di superamento, copertura dei branch
- Unit test, Integration test, End-to-end test
- Strumenti: pytest, Jest, Playwright, Stryker
Manutenibilità: Vale la pena mantenere questo codice?
- Misurato: complessità, duplicazione, violazioni dei confini
- Strumenti: ESLint, Ruff, Lizard, ArchUnit
Sicurezza: Questo codice è sicuro?
- Misurato: risultati per gravità, CVE
- Strumenti: Semgrep, CodeQL, gitleaks, npm audit

Permettono a Bob di rilevare i propri errori e migliorare la qualità durante la fase di implementazione. Una buona copertura dei test è una protezione essenziale contro le regressioni: garantisce che Bob non abbia rotto nulla.

In questo ciclo, la verifica è elencata come una fase separata alla fine del loop, che si riferisce principalmente alla verifica manuale. La verifica manuale inizia eseguendo il cambiamento e confrontando il comportamento osservato con il comportamento specificato nel piano. Una discrepanza si riduce principalmente a una di due cause:

L'implementazione si è discostata dal piano. La soluzione è nel codice.
Il piano non riflette ciò che intendevi costruire. Il piano deve essere raffinato. Questo è di gran lunga più comune.

L'ispezione manuale quindi testa il piano e l'implementazione allo stesso tempo.

La verifica aggiuntiva dovrebbe avvenire nelle pipeline CI/CD. Questa è una pratica ben consolidata nell'ingegneria del software, ma può essere migliorata usando headless coding agent. Un esempio: una revisione automatizzata su ogni pull request, eseguita tramite Bob Shell, integra i revisori umani anziché sostituirli. Vedi il video del PR review agent in azione e la documentazione per eseguire Bob Shell in modo non interattivo.

Lavorare in team

Tutto ciò che è descritto nelle sezioni precedenti descrive il loop interno di un singolo sviluppatore. Il loop esterno inizia quando i cambiamenti entrano nella coda di revisione. Ogni diff ora arriva più velocemente e con meno del suo ragionamento allegato, mentre il revisore ha più da leggere e meno contesto in cui leggerlo.

Le evidenze devono viaggiare con il lavoro. Il perché conta più di prima, rispetto al come, perché il come non è più la parte costosa da produrre.

In pratica questo significa che il piano viaggia con il cambiamento: i team lo allegano alla pull request o lo aggiungono di nuovo all'issue originale insieme alla revisione. Il meccanismo dipende dagli strumenti.

Ciò che il loop esterno fa al processo di un team è un argomento a sé, e sarà trattato in un post successivo.

Alcune riflessioni sul prompting

Negli anni passati, c'era grande enfasi sul prompting corretto degli LLM, con un'intera categoria lavorativa come "prompt engineer" che ne emergeva. A questo punto, gran parte del prompting è gestito all'interno del harness. L'importanza delle tecniche specializzate di prompting è diminuita a favore di un approccio metodologico. Ecco alcune linee guida:

Iterare batte il prompting. Quando Bob fa qualcosa di diverso da quello che hai chiesto, fai rollback e riscrivi il messaggio che lo ha causato. Correggere in avanti lascia la risposta sbagliata, il reclamo al riguardo e il nuovo tentativo tutti nella finestra.
La metodologia batte il prompting. Un prompt è limitato a una sessione. Un file di regole, o un controllo che Bob può eseguire da solo, continua a funzionare in ogni sessione successiva a quella che lo ha prodotto, che è l'unico tipo di investimento qui che si accumula.
Dai a Bob il brief che riceverebbe un ingegnere senior. Un collega competente a cui viene assegnato un compito vago chiederà cosa conta come fatto e cosa è autorizzato a toccare; Bob non chiederà, quindi metti entrambi nel messaggio.
Di' cosa fare, non cosa non fare. "Non usare class component" esclude un'opzione e lascia aperto il resto dello spazio, quindi Bob sceglie da ciò che rimane, che è un'altra supposizione. Nominare il target invece — function component con hook — lo chiude in un turno.
Qualsiasi istruzione data più di due volte appartiene a un file. Questo è lo scopo di agents.md e delle skill.
Istruzioni di prompting più dettagliate si trovano nel tutorial per scrivere prompt efficaci.

Punti chiave

L'assenza di struttura è il problema più grande. Seguire il ciclo Esplora → Pianifica → Implementa → Verifica ti aiuta a rimanere concentrato e a raggiungere i tuoi obiettivi più rapidamente e in modo più consistente.
Il contesto è la risorsa scarsa, e le fasi sono confini di contesto. Non portare il chiacchiericcio esplorativo nell'implementazione.
Il piano è l'artefatto di revisione. Revisionare un piano batte revisionare un diff, per l'autore e per il revisore.
Tutto ciò che vale la pena conservare lascia la chat. Piani, decisioni e scoperte appartengono a un file. Puoi fare diff, revisionare, versionare e passare un file a un altro agente.
La verifica dovrebbe essere eseguibile dalla macchina, il che significa che devi progettarla durante la pianificazione, non scoprirla in seguito.

Fonti e approfondimenti

Simon Willison, Agentic engineering patterns
Birgitta Böckeler, Harness engineering

Documentazione e tutorial di IBM Bob: