Diamo ticket reali agli agenti di coding ogni giorno, e quasi sempre rilasciano qualcosa che funziona. Non è mai stata quella la preoccupazione. La preoccupazione è come lavorano: un nuovo helper accanto a tre che fanno già il lavoro, un’astrazione nuova per un solo chiamante, un fix che rattoppa l’unico percorso nominato dal ticket e lascia quattro fratelli rotti, un finding che è “probabilmente un bug” senza alcuna prova né in un senso né nell’altro. Ogni modifica è localmente ragionevole. Nell’insieme sono entropia.
TL;DR: Su cinque pull request Tier-3 nel nostro core di orchestrazione degli agenti, tre skill componibili —
ponytail(sottrai),grain(allinea) ereview-proof(dimostra) — hanno rimosso 821 righe mentre rilasciavano cinque funzionalità, hanno intercettato una rottura silenziosa di contratto che la sola plausibilità avrebbe fatto unire, e hanno mantenuto ogni modifica in linea con la vena dell’architettura esistente. Ecco cosa fa ciascuna, con i diff reali a supportarlo.
Togli i guardrail e un agente di coding è un generatore velocissimo di passività dall’aspetto plausibile. Perciò ci appoggiamo a tre piccole skill che spingono nella direzione opposta — un istinto ciascuna: sottrai, allinea, dimostra.
ponytail— scrivi la cosa più pigra che funzioni davvero. Cancella prima di aggiungere. (Questa non l’abbiamo scritta noi: è una skill open source di Dietrich Gebert che abbiamo adattato al nostro stack.)grain/grain-review— mettilo dove il codebase ha già deciso che va. Non inventare un secondo modo.review-proof— non credere a un finding finché non si riproduce come test che fallisce.
grain e review-proof le abbiamo costruite con lo stesso spirito di ponytail, tarate sulla nostra architettura. Ognuna delle cinque PR qui sotto tocca il nostro core di orchestrazione degli agenti — il punto più costoso del repo in cui essere sciatti — e ognuna è classificata Tier 3: copertura di test extra e review umana oltre al reviewer automatico, senza eccezioni.
Le tre skill a colpo d’occhio: ponytail sottrae, grain allinea, review-proof dimostra.
Parte 1 · WHAT — l’entropia è il default
Ecco la cosa che nessuno ti avverte quando affidi un repo agli agenti AI: ogni agente ottimizza localmente e non ricorda nulla. Vede il ticket, non i mesi di convenzioni su cui il tuo team si è assestato. Non ha motivo di preferire il tuo servizio email esistente a uno nuovo, nessuna memoria del fatto che l’insieme degli status di redirect è già definito tre file più in là, nessun istinto che dice “il fix va nella funzione condivisa, non in questo singolo chiamante”. Lasciati correre, N agenti producono N modi leggermente diversi di fare la stessa cosa. Non è un problema di qualità del codice che puoi eliminare con un linter: è un drift strutturale che si accumula.
Le tre skill colpiscono ciascuna un asse di quel drift.
ponytail — la cosa più pigra che funziona
Ponytail è uno sviluppatore senior che è stato svegliato alle 3 di notte per l’astrazione ingegnosa di qualcun altro e si rifiuta di scrivere la prossima. Segue una scala e si ferma al primo gradino che regge: questa cosa deve esistere davvero (YAGNI) → è già in questo codebase → la fa la standard library → la fa una feature nativa della piattaforma → la fa una dipendenza già installata → può essere una riga sola → solo allora, il codice minimo che funziona.
Il gradino che conta di più per gli agenti è “è già in questo codebase?” Reimplementare ciò che sta a pochi file di distanza è la forma più comune di sciatteria degli agenti. E la regola di ponytail sui bug fix tiene onesti i diff: correggi la causa alla radice, non il sintomo. Fai un grep su ogni chiamante della funzione che stai per toccare; una guardia nella funzione condivisa è un diff più piccolo di una guardia in ogni chiamante — e non lascia i fratelli rotti.
grain / grain-review — vai con la vena
Se ponytail governa quanto poco scrivi, grain governa dove va e che forma prende. La sua unica regola: trova l’esempio esistente più vicino, copiane la forma, dai un nome a ciò che hai copiato. Il nuovo codice dovrebbe leggersi come se l’avesse scritto anche la persona che ha scritto il file accanto.
Grain è anche il luogo in cui l’architettura viene fatta rispettare. Il nostro backend è un layout abbastanza standard vertical-slice + esagonale: presentation chiama application chiama domain, l’infrastruttura dipende verso l’interno e il domain non si protende mai di nuovo verso l’esterno. Un finding come “questa route salta il suo controller e prende il service direttamente” non è pedanteria: è la differenza tra un codebase che un agente riesce a navigare il mese prossimo e uno che non riesce. grain-review dà la caccia esattamente a queste cose: helper duplicati, confini di layer attraversati, accesso agli interni di un’altra feature, una seconda convenzione per qualcosa che è già fatto in un modo solo.
review-proof — guadagnati il finding
La review del codice AI standard produce finding plausibili. Alcuni sono reali; altri sono sciocchezze sicure di sé; dall’esterno sono identici. review-proof si rifiuta di fidarsi di se stessa: fa la review, poi obbliga ogni finding di correttezza a riprodursi come test che fallisce davvero o come repro eseguibile, e scarta tutto ciò che non ci riesce. Chiude con un pass di grain-review per l’aderenza strutturale. Ciò che viene rilasciato è una review in cui ogni voce arriva con prove eseguibili — non con una sensazione.
Cosa dovremmo vedere se questo funziona
- H1 — La cancellazione si vede nelle PR di funzionalità. Se ponytail + grain funzionano, aggiungere una funzionalità dovrebbe spesso rimuovere struttura netta, non solo aggiungerne.
- H2 — I fix arrivano una volta sola, nel posto condiviso. I fix alla causa radice dovrebbero far collassare molti call site su una sola guardia, non spargere guardie per chiamante.
- H3 — La review intercetta rotture di contratto che un umano scorre senza vedere. Una review supportata da prove dovrebbe far emergere bug che la review “sembra a posto” si perde — specialmente quelli silenziosi.
Parte 2 · SO WHAT — cinque PR, un istinto ciascuna
Cinque modifiche reali al nostro core di agenti. Teniamo gli interni volutamente vaghi — il repo è privato — ma i numeri sono calcolati dai diff reali e la parte trasferibile sono le lezioni.
Sottrai: una guardia per una dozzina di siti di fetch
Una famiglia di step di flusso recuperava URL forniti dall’utente senza un controllo di sicurezza che risolvesse il DNS, quindi un hostname che risolveva verso un indirizzo interno poteva raggiungere i metadata del cloud dal backend. Il fix allettante aggiunge un controllo in ciascuno dei dodici e più siti di fetch. La risposta di Ponytail era l’opposto: un unico helper di fetch condiviso e protetto, usato ovunque — e abbiamo cancellato una tabella di reti private scritta a mano che un trucco di DNS wildcard aggirava senza problemi, più tre loop di redirect duplicati e un controllo di rete copiato e incollato in diversi file.
Il diff ha aggiunto l’helper condiviso e rimosso ~90 righe di duplicazione su 22 file. Quella cancellazione è la storia: questo è H2 in carne e ossa — il fix alla radice ha instradato ogni chiamante attraverso una sola guardia invece di rattoppare l’unico percorso nominato dal ticket.
Il fix alla radice: una dozzina di siti di fetch ad hoc collassano su un unico helper condiviso e protetto. Il fix pigro e il fix sicuro sono lo stesso fix.
Sottrai + dimostra: una guardia di forma, provata sul runtime reale
Il nostro runtime dei worker persiste il risultato di una run come stringa serializzata, a volte avvolta in una lista a un solo elemento. I consumer che si aspettavano un oggetto semplice andavano in crash. Il fix sbagliato sparpaglia controlli di tipo difensivi su ogni consumer. Invece: un piccolo helper di normalizzazione della forma, e ogni consumer reindirizzato su di esso — un’aggiunta quasi pura di una guardia che sostituisce le N ad hoc che un agente meno disciplinato avrebbe scritto (+558 / −24, 7 file).
La parte che rende questa una storia da review-proof è il test. Invece di fare asserzioni su una forma di serializzazione presunta, abbiamo eseguito un workflow reale attraverso il runtime e lo storage effettivi — nessun mock — e abbiamo dimostrato la forma che il runtime effettivamente persiste. La domanda aperta nel ticket era letteralmente cosa serializza il runtime qui? — e l’unica risposta onesta è una che puoi eseguire.
Dimostra: la review ha intercettato una rottura silenziosa di contratto
Funzionalità: un modello di fallback per nodo, così un flusso vincolato a un solo provider degrada con grazia durante un’interruzione. Il primo taglio ovvio avvolgeva il modello nel combinatore di fallback integrato nel framework.
Funzionava nel percorso felice. Ma disattivava silenziosamente due feature del provider che dipendono dal tipo concreto del modello tramite isinstance — un oggetto avvolto non è più quel tipo, quindi sia l’output strutturato nativo sia il prompt caching si spegnevano in silenzio. Nessun errore. Nessun test del percorso felice che fallisse. Esattamente il tipo di cosa che una review umana scorre senza vedere e che un agente “sembra a posto” approva.
review-proof non l’ha approvata — ha riprodotto entrambe le rotture come test che falliscono, il che ha forzato il redesign: applicare il fallback più in basso, al momento dell’esecuzione, così ogni modello resta del suo tipo concreto e le feature vincolate al tipo continuano a funzionare. H3, confermata in modo decisivo: la prova ha intercettato un bug che la plausibilità avrebbe rilasciato.
Allinea: un picker, non due copie
Aggiungere un secondo canale di notifica significava che la UI di selezione del canale aveva ora due case — un wizard di creazione e un modal di impostazioni. La mossa di default dell’agente aggiunge il nuovo ramo a entrambe, facendo crescere due copie della stessa macchina a stati. grain ha detto: c’è già un modo in cui questa cosa dovrebbe essere strutturata — rendila condivisa. Abbiamo estratto un unico hook picker e pilotato entrambe le schermate attraverso di esso, inserito il nuovo canale nell’unione di configurazione esistente e riutilizzato il servizio email esistente invece di aggiungere nuova macchineria di invio.
+1.735 / −340 su 24 file. Una funzionalità di questa dimensione che rimuove 340 righe è H1 resa visibile: la deduplicazione di due copie del picker in una sola ha pagato una buona parte del nuovo canale.
Allinea + dimostra: riusa l’endpoint, rispecchia il percorso
Permettere agli utenti di allegare file alla creazione di un issue poteva significare un nuovo endpoint di upload, un nuovo meccanismo di dispatch, un nuovo percorso di prompt. grain ha instradato quasi tutto su binari esistenti: l’endpoint di upload esistente, una accept-list frontend che rispecchia esattamente la whitelist del backend e un fix del dispatch differito che ha riutilizzato il meccanismo di eleggibilità già usato dal lavoro schedulato. È stata rilasciata con fix supportati da prove, incluso un vero bug di isolamento delle transazioni che avrebbe perso dati sotto upload paralleli. +1.776 / −218 su 27 file — una grande funzionalità che ha comunque trovato 218 righe da rimuovere unendosi a slice esistenti invece di inventarne di nuove.
Il tabellone
Cinque PR Tier-3: cosa ha aggiunto ciascuna, cosa ha rimosso e l’istinto dietro.
Cinque PR di funzionalità e fix sul core degli agenti hanno rimosso 821 righe — non facendo di meno, ma rifiutandosi di duplicare ciò che esisteva già e di tenere rattoppi ai sintomi che un fix alla radice aveva reso superflui.
Trasparenza totale
- Queste sono skill, non uno studio. Non è un esperimento controllato con un braccio di controllo; sono cinque PR reali in cui la disciplina è stata applicata. Il controfattuale — cosa avrebbe rilasciato lo stesso agente senza le skill — è una stima informata, non una misurazione. La storia della rottura silenziosa di contratto è l’evidenza più pulita, perché abbiamo visto la review riprodurre il bug prima del redesign.
- I conteggi di righe sono proxy. Il −821 è un numero reale preso dai diff, ma “righe rimosse” sta per “duplicazione e flessibilità morta evitate”. Una skill che convince un agente a non scrivere 200 righe speculative non lascia alcuna traccia in un diff — le vittorie più grandi qui sono invisibili.
- I risparmi di token sono indicativi. Diff più piccoli, meno file toccati e strutture riutilizzate significano meno token spesi per generare, fare review e rifare review — ma non stiamo citando un delta di token per PR preciso.
ponytailnon è nostra. È una skill open source di Dietrich Gebert ; l’abbiamo adattata.grainereview-proofsono nostre, costruite con lo stesso spirito. Tutte e tre girano come skill di progetto locali su Claude Code: prompt e procedura, non un binario da installare.
Pronto a far crescere il tuo business?
Inizia oggi la tua prova gratuita e vedi i risultati in pochi giorni.
Parte 3 · NOW WHAT
Cosa è stato rilasciato. Tre skill componibili. ponytail e grain girano mentre scrivi; ponytail-review, grain-review e review-proof girano su un diff. review-proof concatena grain-review come sua fase finale, quindi una singola review provata ottiene gratis anche un pass strutturale.
Cosa puoi fare lunedì — non ti servono le nostre skill esatte:
- Metti “riusa” al secondo gradino, non al decimo. Prima che un agente scriva un helper, fagli fare un grep per trovarne uno esistente. “È già in questo codebase?” va sopra “riesco a scriverlo in modo pulito?”
- Correggi alla radice, dimostralo con la lista dei chiamanti. Richiedi che ogni bug fix nomini ogni chiamante della funzione toccata. Una guardia nella funzione condivisa batte una guardia per chiamante — ed è un diff più piccolo.
- Dai al nuovo codice un fratello più vicino da copiare. “Trova l’esempio esistente più vicino e rispecchiane la forma” trasforma l’architettura da un documento che nessuno legge in un default che l’agente segue.
- Fai rispettare i confini tra layer in CI, non a sensazione. Un ratchet che fallisce solo su import cross-layer nuovi ti permette di tenere la linea senza far bollire l’oceano del debito esistente.
- Non rilasciare un finding che non riesci a riprodurre. Fai scrivere all’agente prima il test che fallisce. Se non riesce a far riprodurre il bug, non è un bug — è un’opinione. Scartala.
- Lascia che la review cancelli. Punta un pass di review specificamente sull’over-engineering — “cosa possiamo tagliare” — separatamente dalla correttezza. Il miglior esito di un diff è che diventi più corto.
Provalo, soprattutto se per te non funziona. Se usi agenti di coding su un codebase reale, l’entropia sta già accadendo — semplicemente non l’hai misurata. Trasforma una di queste cose in un pass di review sulle tue prossime dieci PR fatte da agenti e conta le cancellazioni. Se sottrai-allinea-dimostra non riduce i tuoi diff o non intercetta una rottura silenziosa, ci piacerebbe davvero saperlo. Correzioni e controesempi sono particolarmente benvenuti.
Un agente aggiunge. Il lavoro consiste nel far guadagnare all’agente ogni riga.
