Pokayoke: Come Proteggere il Tuo Repository dagli Errori con Controlli "Agent-Friendly"

Negli anni '60, il pioniere giapponese della manifattura Shigeo Shingo ha introdotto il concetto di pokayoke. L'idea risolve un problema che tutti gli sviluppatori conoscono fin troppo bene: come rendere gli errori impossibili, o almeno immediatamente visibili.

Il principio è semplice. Invece di contare sulla perfezione umana, si progettano sistemi che intercettano le deviazioni in automatico. Una spina che si inserisce in un solo modo. Un sensore che ferma la linea quando qualcosa non quadra. Nella produzione, questo evita che i difetti arrivino ai clienti. Nel software, impedisce che la deriva dalle convenzioni raggiunga la produzione.

Pokayoke.codes porta questa filosofia nei repository con uno strumento pensato per l'era dello sviluppo assistito dall'AI.

Oltre il Linting: La Policy come Documentazione

La maggior parte dei team ha già strumenti di linting. ESLint segnala le variabili inutilizzate. Prettier enforceda la formattazione. TypeScript coglie gli errori di tipo. Fanno il loro lavoro bene, ma non catturano il sapere implicito che risiede nella testa del team—convenzioni che tutti conoscono ma nessuno ha mai formalizzato.

Forse i tuoi endpoint API seguono un pattern di naming specifico. Magari hai regole su quali pacchetti sono accettabili in certi contesti. O forse esiste un accordo tra colleghi sull'organizzazione dei file che non è enforcedato da nessuna parte.

Questo è il vuoto che pokayoke colma. Permette di codificare invarianti specifiche del repository che cadono fuori dallo scope del linting tradizionale ma contano tanto quanto per la consistenza del codice.

Agent-First di Progettazione

Ecco cosa rende pokayoke genuinamente interessante: è costruito per gli agenti AI prima di tutto.

I moderni coding assistant possono navigare il tuo codebase, scrivere nuove funzionalità, fare refactoring. Ma mantenerli allineati alle convenzioni del team? Quello è ancora un processo manuale. Puoi aggiungere regole al system prompt, ma gli agenti dimenticano, allucinano, o semplicemente non sanno cosa consideri importante.

Pokayoke risolve questo trattando le regole di policy come cittadini di prima classe che gli agenti possono leggere, capire e seguire. Il comando pokayoke agent SKILL.md fa partire gli agenti in autonomia, e le regole stesse sono progettate per essere scritte e manutenute dall'AI—non solo per gli sviluppatori umani.

Se stai costruendo un workflow di Vibe Coding dove l'AI gestisce il lavoro pesante, pokayoke ti dà un modo per comunicare i tuoi standard in un formato che effettivamente resta.

Convive con il Tuo Stack

Una preoccupazione quando aggiungi nuovo tooling è il rischio di frammentazione. Hai già ESLint, Prettier, Husky e una dozzina di altri strumenti che tengono in riga il codebase. Aggiungere pokayoke non significa sostituire niente di tutto questo—significa estendere la pipeline esistente.

La documentazione sottolinea che pokayoke è unopinionated. Non gli importa della formattazione (quello è il lavoro di Prettier) né della qualità generale del codice (lascia che sia ESLint a occuparsene). Si concentra invece sugli invarianti specifici del progetto che solo il tuo team conosce.

Le regole TypeScript sono locali al tuo repo e verificano i vincoli che contano per il tuo setup particolare. Pensalo come un layer di validazione custom costruito sopra il tooling standard.

Come Iniziare

Pronto a proteggere il tuo repository dagli errori? L'installazione è immediata:

npx skills add rorz/pokayoke

Da lì puoi definire regole che catturano le convenzioni del tuo team. Le regole sono progettate per essere auto-documentanti—sia umani che agenti possono leggerle per capire quali policy sono in vigore e perché.

Il Quadro Più Ampio

Pokayoke rappresenta uno shift interessante nel modo in cui pensiamo agli strumenti per la qualità del codice. I linter tradizionali enforcedano sintassi e stile. Gli analizzatori statici colgono bug. Ma mentre i coding assistant AI diventano collaboratori primari, servono nuove categorie di strumenti che comunichino intenzione in modi che gli agenti possano effettivamente consumare e seguire.

Non si tratta più solo di catturare errori. Si tratta di rendere i tuoi standard machine-readable, agent-friendly, e difficili da violare—che il codice provenga da uno sviluppatore umano o da un assistant AI.

In questo senso, pokayoke potrebbe essere uno dei primi strumenti costruiti apposta per come scriveremo tutti codice tra qualche anno. Vale la pena tenerlo d'occhio.