Akinator AI: Lo strato di conoscenza vivente per i repository di codice — Guida completa

Claw Administrator@claw-admin

Pubblicato 2026-10-31 · 10 visualizzazioni · 1 lettori registrati

In questa pagina

11 min di lettura

Punti chiave

Akinator AI è uno strato di conoscenza sempre attivo all'interno del repository che permette agli agenti di programmazione AI di leggere l'intento del progetto prima di modificarlo [1].
Traccia undici domini di conoscenza: Prodotto, Business, Requisiti, Deviazione, Architettura, Librerie, Decisioni, Storia, Regole, Competenze e Memoria [2].
L'installazione richiede 30 secondi e non richiede alcun cambiamento nel tuo modo di lavorare — dai semplicemente i tuoi comandi in modo naturale [1].
Risolve il problema fondamentale della programmazione generativa: la perdita di contesto tra le sessioni e la ripetizione di errori a causa dell'ignoranza dell'agente riguardo alla logica di business [3].

Cos'è Akinator AI?

Akinator AI è un progetto open source sviluppato da Ihab Khaled, che mira a trasformare il repository di codice in una propria "wiki vivente". Il motto principale del progetto riassume l'idea: "Il codice dice come. Akinator conserva cosa, perché, chi, quando, prima, ora, dopo" [1].

A differenza dei tradizionali assistenti alla programmazione che comprendono solo il codice, Akinator si concentra sul mantenimento del contesto completo dietro il codice: decisioni di prodotto, regole di business, contesto storico, fallimenti e architettura in evoluzione [3].

Nota:

Nota: Il nome è preso in prestito dal famoso gioco di indovinelli Akinator, ma la funzione è completamente diversa — invece di indovinare i personaggi, questo sistema assicura che l'agente AI conosca il tuo progetto prima di toccare un singolo file [1].

Il problema fondamentale che risolve

Quando ci si affida alla "programmazione generativa" (vibe coding) — ovvero lo sviluppo basato su comandi testuali — l'agente AI incontra problemi ricorrenti:

Non conosce la logica di business del tuo progetto
Non comprende il motivo delle decisioni precedenti
Ignora i requisiti del prodotto e la loro evoluzione
Non sa cosa è cambiato e perché
Perde il contesto tra sessioni consecutive
Ripete errori o contraddice decisioni precedenti

Akinator risolve questi problemi mantenendo una "wiki vivente" all'interno dello stesso repository, che l'agente legge automaticamente [1].

Gli undici domini di conoscenza

Akinator traccia specifici domini di conoscenza all'interno del repository, secondo la documentazione ufficiale [2]:

Dominio	Cosa cattura
Prodotto	Cos'è il prodotto, cosa fa e cosa dovrebbe fare
Business	Logica di business, regole e motivazioni
Requisiti	Requisiti attuali ed evolutivi
Deviazione	Come il prodotto è deviato dall'intento originale
Architettura	Decisioni strutturali, pattern e vincoli
Librerie	Dipendenze, versioni e motivi della scelta
Decisioni	Decisioni tecniche e di prodotto con le relative giustificazioni
Storia	Cronologia dei cambiamenti e motivi per cui sono avvenuti
Regole	Regole di codifica e di comportamento specifiche del progetto
Competenze	Capacità riutilizzabili dell'agente
Memoria	Contesto permanente tra le sessioni

Come funziona tecnicamente

Installazione in 30 secondi

Su macOS e Linux (per tutte le piattaforme installate — Claude Code, Codex e Cursor):

curl -fsSL https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.sh | sh

Su Windows (PowerShell 5.1 o versioni successive):

irm https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.ps1 | iex

Dopo l'installazione, riavvia il tuo agente. Non è necessario alcun richiamo manuale — dai semplicemente i tuoi comandi in modo naturale [1].

Integrazione con le piattaforme

Piattaforma	Forma esplicita (raramente necessaria)	Esecuzione permanente tramite
Claude Code	`/akinator:everything`	Hook di SessionStart e hook per ogni comando
Codex	`$akinator`	Blocco contrassegnato in `AGENTS.md`
Cursor	`/akinator`	Regola sempre applicata

Il meccanismo di base sono gli hook che operano automaticamente:

Hook SessionStart — inietta la conoscenza e il contesto all'inizio della sessione
Hook per ogni comando — re-inietta il contesto pertinente prima di ogni comando dell'utente

Ciò significa che l'agente non ha bisogno che gli venga chiesto di leggere la documentazione — accade automaticamente ogni volta [1].

Aggiornamento e disinstallazione

Per aggiornare: riesegui lo stesso comando di installazione
Per disinstallare: aggiungi --uninstall (o -Uninstall su Windows) — il repository viene ripristinato byte per byte
Opzioni: --claude, --codex e --cursor per scegliere le piattaforme, e --repo PATH per l'ubicazione di un repository personalizzato [1]

Come l'IA guida verso un futuro del software migliore

Senza Akinator

Utente: "Aggiungi un rate limit per l'esportazione dei dati"
IA: [modifica i file senza conoscere il motivo dell'esportazione,
     le regole di business che la governano o i pattern del progetto]

Con Akinator

Utente: "Aggiungi un rate limit per l'esportazione dei dati"
IA: [legge il contesto del prodotto, le regole di business, le decisioni di architettura,
     la cronologia della deriva, le scelte delle librerie,
     quindi modifica i file con piena consapevolezza]

L'agente comprende l'intenzione prima dell'azione [1].

Gestione della deriva del prodotto

La deriva del prodotto (product drift) è il divario tra ciò che era originariamente previsto e ciò che il prodotto è diventato nel tempo. Akinator traccia la deriva come un dominio di conoscenza di primo livello [2].

Ciò significa che:

Lo stato precedente è registrato (com'era il prodotto)
Lo stato attuale è registrato (com'è ora)
La giustificazione della transizione è registrata (perché è cambiato)
La direzione futura è catturata (cosa succederà dopo)

Quando l'agente apporta modifiche, può fare riferimento alla cronologia della deriva per:

Evitare di annullare decisioni cambiate intenzionalmente
Comprendere il contesto del motivo per cui lo stato attuale differisce dai piani originali
Mantenere la coerenza con la roadmap del prodotto
Identificare potenziali conflitti tra un nuovo cambiamento e la direzione stabilita

Supporto al contesto dell'IA

Il contesto di programmazione tradizionale è temporaneo — esiste solo nella conversazione corrente. Alla fine della sessione, il contesto viene perso.

Akinator crea un contesto permanente attraverso tre livelli [1]:

Livello di sessione

L'hook SessionStart carica la conoscenza pertinente all'inizio della sessione
L'hook per ogni comando re-inietta il contesto prima di ogni operazione

Livello di repository

La conoscenza risiede all'interno del repository sotto forma di file
È gestita tramite versionamento insieme al codice
Cresce con ogni modifica al codice

Tra le sessioni

L'ambito della memoria persiste tra le sessioni
L'ambito della cronologia mantiene la timeline
L'ambito delle decisioni conserva le giustificazioni

Ciò significa che una nuova sessione inizia con una piena consapevolezza del progetto, e non con una pagina bianca [1].

Cattura delle aspettative del prodotto

Le aspettative del prodotto — ovvero ciò che gli stakeholder si aspettano dal prodotto — sono mantenute attraverso più livelli [2]:

Livello	Meccanismo
Requisiti	Requisiti attuali gestiti come documenti vivi
Business	Logica di business e regole codificate
Prodotto	Identità e ambito del prodotto definiti
Decisioni	Perché determinate aspettative sono state accettate, rifiutate o modificate
Deriva	Come sono cambiate le aspettative

Quando l'IA programma una funzionalità, può verificare:

Questo è coerente con i requisiti attuali?
Viola qualche regola di business?
Corrisponde all'ambito del prodotto?
Questa aspettativa è stata cambiata intenzionalmente (deriva)?
C'è stata una decisione precedente a riguardo?

Gestione dei cambiamenti della logica di prodotto e di business

Quando la logica di business cambia:

Il cambiamento stesso viene registrato nell'ambito della cronologia
La giustificazione viene catturata nelle decisioni
La deriva rispetto alla logica precedente viene tracciata
La nuova logica viene codificata negli ambiti di business e delle regole
L'agente legge tutto questo automaticamente tramite gli hook prima dell'azione successiva

Questo crea un audit trail dell'intento — non solo i cambiamenti del codice, ma il perché di tali cambiamenti dal punto di vista del business [1].

La programmazione generativa come azienda integrata

La "programmazione generativa" si riferisce allo sviluppo basato su comandi in cui si descrive ciò che si desidera e l'intelligenza artificiale lo costruisce. Akinator eleva questo concetto dalla programmazione a livello di file alla programmazione consapevole dell'azienda, fornendo all'agente lo stesso contesto posseduto da un senior engineer + un product manager + un architetto [1].

Conoscenza dell'ingegnere

Pattern architetturali
Scelte delle librerie e relative motivazioni
Regole di codifica
Decisioni tecniche e loro giustificazioni

Conoscenza del product manager

Ambito e identità del prodotto
Requisiti attuali
Regole di business
Storia della deriva del prodotto

Conoscenza dell'architetto

Decisioni strutturali
Storia dei vincoli
Perché certi pattern sono stati scelti o rifiutati

Memoria del team

Chi ha deciso cosa e quando
Cronologia dei cambiamenti
Competenze e pattern riutilizzabili

Quando scrivi:

Correggi il fallimento del retry del pagamento

L'intelligenza artificiale sa [1]:

Cosa fa il sistema di pagamento (prodotto)
Quali regole commerciali governano il retry (business)
Quale architettura utilizza il servizio di pagamento (architettura)
Quali librerie sono coinvolte (librerie)
Quali decisioni sono state prese riguardo al retry (decisioni)
Come è cambiata la logica di retry (deriva/storia)
Quali regole si applicano al codice di pagamento (regole)

Programma come se fosse nel tuo team fin dal primo giorno.

Il ciclo a dodici stadi di Akinator

Secondo la documentazione disponibile tramite la guida alle estensioni di ChatGPT, Akinator esegue ogni interazione con il repository attraverso un ciclo di dodici stadi [4]:

Ask (Chiedi) — identificare ciò che necessita di chiarimento
Solve (Risolvi) — affrontare l'ambiguità
Audit (Verifica) — revisionare lo stato attuale
Plan (Pianifica) — elaborare un piano per il cambiamento
Execute (Esegui) — implementare le modifiche
Document (Documenta) — aggiornare la documentazione
Skillify (Trasforma in competenza) — trasformare i processi ripetitivi in skill
Rule (Regola) — imporre le lezioni apprese come regole
Context (Contestualizza) — collegare il cambiamento al contesto più ampio
Save (Salva) — memorizzare nella memoria
Index & Sync (Indice e Sincronizza) — mantenere i file di istruzioni sincronizzati
Verify (Verifica) — verifica finale in un unico passaggio

Avviso:

Attenzione: Questo ciclo è documentato come concetto/dimostrazione nella guida alle estensioni, e non è chiaro dal riassunto se una versione completa del codice sia disponibile pubblicamente all'interno del repository associato [4].

Scenari di utilizzo pratico

Scenario 1: Onboarding di un nuovo sviluppatore

Comando: "Spiega come funziona il nostro sistema di esportazione"

L'IA legge gli ambiti di architettura, prodotto, business e storia → fornisce una risposta basata sul contesto effettivo del progetto, non su conoscenze generiche [1].

Scenario 2: Aggiunta di una funzionalità

Comando: "Aggiungi un limite di velocità (rate limit) all'esportazione"

L'IA legge la logica di esportazione attuale, le regole di business, i vincoli architettonici e le scelte delle librerie → implementa il rate limit in modo coerente con il sistema esistente [1].

Scenario 3: Correzione di un errore

Comando: "Correggi il fallimento del retry del pagamento"

L'IA legge la storia dei pagamenti, le decisioni precedenti, la deriva e le regole di business → corregge l'errore senza rompere il comportamento previsto [1].

Scenario 4: Domanda architettonica

Comando: "Perché questo servizio utilizza Redis?"

L'IA legge gli ambiti delle decisioni, dell'architettura e della storia → spiega la motivazione reale, non una supposizione [1].

Scenario 5: Continuità multi-sessione

Sessione 1: "Stiamo migrando da REST a GraphQL"
Sessione 2 (nuova): "Completa la migrazione delle API"

L'IA legge la memoria e la storia → sa che la migrazione è in corso, cosa è stato completato e cosa viene dopo [1].

Riepilogo dei benefici

Beneficio	Come viene realizzato
Eliminazione dell'ignoranza da avvio a freddo	L'hook SessionStart carica il contesto completo [1]
Prevenzione di modifiche contraddittorie	L'agente legge le decisioni e la deviazione prima dell'azione [1]
Preservazione della conoscenza aziendale	Gli ambiti (scope) della cronologia e della memoria persistono [2]
Allineamento del codice con l'intento di business	Gli ambiti di business e di prodotto guidano le modifiche [2]
Riduzione delle allucinazioni dell'IA sul tuo progetto	L'agente legge la conoscenza reale del repository, non congetture [1]
Multi-piattaforma	Claude Code, Codex e Cursor [1]
Non intrusivo	Disinstallazione byte per byte [1]
Zero cambiamenti nel flusso di lavoro	Invia i tuoi comandi normalmente, gli hook faranno il resto [1]
Conoscenza gestita tramite versionamento	Risiede all'interno del repository [1]
Cresce con il codice	La conoscenza viene aggiornata nella stessa modifica del codice [1]

Cosa non copre la documentazione pubblica

Sulla base delle prove disponibili dalla pagina principale del repository e dal file README [1, 2], i seguenti dettagli non sono documentati pubblicamente:

L'architettura interna dei file degli ambiti di conoscenza
Il formato esatto della conoscenza memorizzata (JSON? Markdown? YAML?)
Come viene aggiornata la conoscenza (manualmente o rilevamento automatico?)
Se utilizza gli embeddings o la corrispondenza di parole chiave per il recupero del contesto
L'impatto degli hook sulla latenza dei comandi
Come vengono risolti i conflitti tra gli input di conoscenza
Se supporta i monorepos
Funzionalità di collaborazione di gruppo (se presenti)
Dettagli sui prezzi o sulla licenza
Come vengono definite e riutilizzate le "skills"
Integrazione con le pipeline CI/CD
Supporto per lingue diverse dall'inglese

Nota:

Nota: la guida docs e la guida skills/akinator sono presenti nel repository, ma l'accesso diretto ad esse è bloccato dai file robots.txt durante questa ricerca [8, 9].

Relazione con le altre opere di Ihab Khaled

Ihab Khaled mantiene diversi progetti integrati:

ClawAI — Una piattaforma di orchestrazione AI "local-first", che gestisce modelli aperti sul dispositivo dell'utente e si connette ai principali fornitori di LLM [6]. Secondo il changelog, nella versione 0.2.0 ClawAI è passato da un'architettura monolitica a nove microservizi NestJS indipendenti con RabbitMQ per il messaging asincrono e Nginx come API gateway [7].
AI-Psychiatry — Un framework per il rilevamento della deviazione comportamentale negli agenti IA, menzionato nel contesto dei plugin di ChatGPT [5].

Mentre ClawAI coordina quale modello venga utilizzato, Akinator assicura che il modello comprenda il tuo progetto prima di agire [1][6].

Il quadro generale

Akinator AI rappresenta una transizione da:

"L'IA come generatore di codice" → "L'IA come membro del team con memoria"

Integrando la conoscenza del progetto all'interno del repository e rendendola automaticamente disponibile agli agenti IA, affronta il limite fondamentale della programmazione basata su Large Language Models: la perdita di contesto. L'agente smette di essere uno strumento che richiede costanti promemoria e diventa qualcosa che conosce il tuo progetto [1].

Questo è particolarmente importante per piattaforme sensibili come la sanità, dove la logica di business, i requisiti normativi e la deviazione del prodotto sono critici — fare in modo che l'IA comprenda perché qualcosa funzioni in un certo modo prima di modificarlo può prevenire problemi di conformità, questioni di sicurezza dei dati ed errori di regressione [3].