Akinator AI: Capa de Conocimiento Vivo para Repositorios de Código — Guía Completa

Claw Administrator@claw-admin

Publicado 2026-10-31 · 10 vistas · 1 lectores con sesión

En esta página

12 min de lectura

Puntos Clave

Akinator AI es una capa de conocimiento persistente dentro del repositorio que hace que los agentes de programación de IA lean la intención del proyecto antes de modificarlo [1].
Rastrea once dominios cognitivos: Producto, Negocio, Requisitos, Desviación, Arquitectura, Librerías, Decisiones, Historia, Reglas, Habilidades y Memoria [2].
La instalación tarda 30 segundos y no requiere ningún cambio en tu forma de trabajar; simplemente da tus órdenes de manera natural [1].
Resuelve el problema fundamental de la programación generativa: la pérdida de contexto entre sesiones y la repetición de errores debido al desconocimiento del agente sobre la lógica de negocio [3].

¿Qué es Akinator AI?

Akinator AI es un proyecto de código abierto desarrollado por Ihab Khaled, que tiene como objetivo convertir el repositorio de código en su propia "wiki viva". El eslogan principal del proyecto resume la idea: "El código dice cómo. Akinator mantiene qué, por qué, quién, cuándo, antes, ahora, siguiente" [1].

A diferencia de los asistentes de programación tradicionales que solo entienden el código, Akinator se centra en mantener el contexto completo detrás del código: decisiones de producto, reglas de negocio, contexto histórico, fallos y arquitectura evolutiva [3].

Nota:

Nota: El nombre está inspirado en el famoso juego de adivinanzas Akinator, pero la función es completamente diferente: en lugar de adivinar personajes, este sistema se asegura de que el agente de IA conozca tu proyecto antes de tocar un solo archivo [1].

El Problema Fundamental que Resuelve

Cuando dependes de la "programación generativa" (vibe coding) — es decir, el desarrollo basado en comandos de texto — el agente de IA enfrenta problemas recurrentes:

No conoce la lógica de negocio de tu proyecto.
No entiende el motivo de las decisiones previas.
Desconoce los requisitos del producto y su evolución.
No sabe qué ha cambiado y por qué.
Pierde el contexto entre sesiones consecutivas.
Repite errores o contradice decisiones anteriores.

Akinator aborda estos problemas manteniendo una "wiki viva" dentro del mismo repositorio que el agente lee automáticamente [1].

Los Once Dominios Cognitivos

Akinator rastrea dominios cognitivos específicos dentro del repositorio, según la documentación oficial [2]:

Dominio	Qué Captura
Producto	Qué es el producto, qué hace y qué debería hacer
Negocio	Lógica de negocio, reglas y motivaciones
Requisitos	Requisitos actuales y evolutivos
Desviación	Cómo se ha desviado el producto de la intención original
Arquitectura	Decisiones estructurales, patrones y restricciones
Librerías	Dependencias, versiones y motivos de su elección
Decisiones	Decisiones técnicas y de producto con sus justificaciones
Historia	Línea de tiempo de los cambios y las razones de los mismos
Reglas	Reglas de codificación y comportamiento específicas del proyecto
Habilidades	Capacidades reutilizables del agente
Memoria	Contexto persistente a través de las sesiones

Cómo Funciona Técnicamente

Instalación en 30 Segundos

En macOS y Linux (para todas las plataformas que tengas instaladas: Claude Code, Codex y Cursor):

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

En Windows (PowerShell 5.1 o posterior):

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

Después de la instalación, reinicia tu agente. No es necesario ningún comando manual; simplemente da tus órdenes de manera natural [1].

Integración con Plataformas

Plataforma	Forma Explícita (Rara vez necesaria)	Ejecución Permanente a través de
Claude Code	`/akinator:everything`	Hooks de SessionStart y hooks por comando
Codex	`$akinator`	Bloque etiquetado en `AGENTS.md`
Cursor	`/akinator`	Regla siempre aplicada

El mecanismo básico son los hooks que funcionan automáticamente:

Hook SessionStart — inyecta el conocimiento y el contexto al inicio de la sesión
Hook por comando — reinyecta el contexto relevante antes de cada comando del usuario

Esto significa que el agente no necesita que se le pida leer la documentación; esto sucede automáticamente cada vez [1].

Actualización y Desinstalación

Para actualizar: vuelve a ejecutar el mismo comando de instalación
Para desinstalar: añade --uninstall (o -Uninstall en Windows); el repositorio se restaura byte por byte
Opciones: --claude, --codex y --cursor para elegir las plataformas, y --repo PATH para una ubicación de repositorio personalizada [1]

Cómo orientar la IA hacia un futuro de programación mejor

Sin Akinator

Usuario: "Añade una limitación de tasa para la exportación de datos"
IA: [modifica los archivos sin saber por qué existe la exportación,
     las reglas de negocio que la rigen o los patrones del proyecto]

Con Akinator

Usuario: "Añade una limitación de tasa para la exportación de datos"
IA: [lee el contexto del producto, las reglas de negocio, las decisiones de arquitectura,
     el historial de desviación, la elección de librerías,
     y luego modifica los archivos con total conciencia]

El agente entiende la intención antes de la acción [1].

Gestión de la desviación del producto

La desviación del producto es la brecha entre lo que se pretendía originalmente y en lo que se convirtió el producto con el tiempo. Akinator rastrea la desviación como un dominio de conocimiento de primer nivel [2].

Esto significa que:

El estado anterior está registrado (cómo era el producto)
El estado actual está registrado (cómo es ahora)
La justificación de la transición está registrada (por qué cambió)
La dirección futura está capturada (qué es lo siguiente)

Cuando el agente realiza cambios, puede recurrir al historial de desviación para:

Evitar revertir decisiones que fueron cambiadas deliberadamente
Comprender el contexto de por qué el estado actual difiere de los planes originales
Mantener la coherencia con la trayectoria del producto
Identificar conflictos potenciales entre un cambio nuevo y la dirección establecida

Soporte de contexto para la IA

El contexto de programación tradicional es temporal: solo existe en la conversación actual. Cuando la sesión termina, el contexto se pierde.

Akinator crea un contexto permanente a través de tres niveles [1]:

Nivel de Sesión

El hook SessionStart carga el conocimiento relevante al iniciar la sesión
El hook por comando reinyecta antes de cada comando

Nivel de Repositorio

El conocimiento vive dentro del repositorio como archivos
Gestionado mediante versiones junto con el código
Crece con cada cambio en el código

A través de Sesiones

El dominio de la memoria persiste a través de las sesiones
El dominio del historial mantiene la línea de tiempo
El dominio de las decisiones guarda las justificaciones

Esto significa que una nueva sesión comienza con una conciencia total del proyecto, y no con una página en blanco [1].

Captura de expectativas del producto

Las expectativas del producto — es decir, lo que los stakeholders esperan del producto — se mantienen a través de múltiples capas [2]:

Capa	Mecanismo
Requerimientos	Requerimientos actuales gestionados como documentos vivos
Negocio	Lógica de negocio y reglas codificadas
Producto	Identidad y alcance del producto definidos
Decisiones	Por qué se aceptaron, rechazaron o cambiaron ciertas expectativas
Desviación	Cómo evolucionaron las expectativas

Cuando la IA programa una funcionalidad, puede verificar:

¿Es esto compatible con los requerimientos actuales?
¿Viola alguna regla de negocio?
¿Se ajusta al alcance del producto?
¿Se cambió esta expectativa deliberadamente (desviación)?
¿Hubo una decisión previa al respecto?

Manejo de cambios en la lógica del producto y del negocio

Cuando la lógica de negocio cambia:

El cambio mismo se registra en el dominio del historial
La justificación se captura en las decisiones
La desviación de la lógica anterior es rastreada
La nueva lógica se codifica en los dominios de negocio y reglas
El agente lee todo esto automáticamente a través de los hooks antes de la siguiente acción

Esto crea una pista de auditoría de intención — no solo los cambios de código, sino por qué ocurrieron esos cambios desde una perspectiva de negocio [1].

La Programación Generativa como una empresa integrada

La "Programación Generativa" se refiere al desarrollo basado en prompts donde describes lo que quieres y la IA lo construye. Akinator eleva esto de una programación a nivel de archivos a una programación consciente de la empresa, otorgando al agente el mismo contexto que posee un ingeniero senior + un gerente de producto + un arquitecto [1].

Conocimiento del Ingeniero

Patrones de arquitectura
Elecciones de librerías y sus motivos
Reglas de codificación
Decisiones técnicas y sus justificaciones

Conocimiento del Gerente de Producto

Alcance e identidad del producto
Requisitos actuales
Reglas de negocio
Historial de desviación del producto

Conocimiento del Arquitecto

Decisiones estructurales
Historial de restricciones
Por qué se eligieron o rechazaron ciertos patrones

Memoria del Equipo

Quién decidió qué y cuándo
Historial de cambios
Habilidades y patrones reutilizables

Cuando escribes:

أصلح فشل إعادة محاولة الدفع

La IA sabe [1]:

Qué hace el sistema de pagos (producto)
Qué reglas de negocio rigen el reintento (negocio)
Qué arquitectura utiliza el servicio de pagos (arquitectura)
Qué librerías están involucradas (librerías)
Qué decisiones se tomaron sobre el reintento (decisiones)
Cómo cambió la lógica de reintento (desviación/historial)
Qué reglas se aplican al código de pagos (reglas)

Programa como si estuviera en tu equipo desde el primer día.

El ciclo de doce estaciones de Akinator

Según la documentación disponible en la guía de plugins de ChatGPT, Akinator ejecuta cada interacción con el repositorio a través de un ciclo de doce estaciones [4]:

Preguntar — Identificar lo que necesita aclaración
Resolver — Abordar la ambigüedad
Auditar — Revisar el estado actual
Planificar — Establecer un plan de cambio
Ejecutar — Implementar las modificaciones
Documentar — Actualizar la documentación
Convertir en habilidad — Transformar procesos repetitivos en habilidades
Regla — Imponer las lecciones como reglas
Contexto — Vincular el cambio con el contexto más amplio
Guardar — Almacenar en la memoria
Indexar y sincronizar — Mantener los archivos de routing sincronizados
Verificar — Verificación final en un solo paso

Advertencia:

Advertencia: Este ciclo está documentado como un concepto/demostración en la guía de plugins; no está claro a partir del resumen si una versión de código completa está disponible públicamente dentro del repositorio vinculado [4].

Escenarios de uso práctico

Escenario 1: Onboarding de un nuevo desarrollador

الأمر: "اشرح كيف يعمل نظام التصدير لدينا"

La IA lee los dominios de arquitectura, producto, negocio e historial $\rightarrow$ ofrece una respuesta basada en el contexto real del proyecto, no en conocimientos generales [1].

Escenario 2: Añadir una funcionalidad

الأمر: "أضف تحديد معدل للتصدير"

La IA lee la lógica de exportación actual, las reglas de negocio, las restricciones de arquitectura y las elecciones de librerías $\rightarrow$ implementa la limitación de tasa (rate limiting) de acuerdo con el sistema existente [1].

Escenario 3: Corregir un error

الأمر: "أصلح فشل إعادة محاولة الدفع"

La IA lee el historial de pagos, las decisiones previas, la desviación y las reglas de negocio $\rightarrow$ corrige el error sin romper el comportamiento previsto [1].

Escenario 4: Pregunta arquitectónica

الأمر: "لماذا تستخدم هذه الخدمة Redis؟"

La IA lee los dominios de decisiones, arquitectura e historial $\rightarrow$ explica la justificación real, no una suposición [1].

Escenario 5: Continuidad multi-sesión

الجلسة 1: "نحن نهاجر من REST إلى GraphQL"
الجلسة 2 (جديدة): "أكمل ترحيل API"

La IA lee la memoria y el historial $\rightarrow$ sabe que la migración está en curso, qué se ha completado y qué es lo siguiente [1].

Resumen de Beneficios

Beneficio	Cómo se logra
Eliminación de la ignorancia del arranque en frío	El hook SessionStart carga el contexto completo [1]
Prevención de cambios contradictorios	El agente lee las decisiones y la desviación antes de actuar [1]
Mantenimiento del conocimiento institucional	Los ámbitos de historial y memoria persisten [2]
Alineación del código con la intención del negocio	Los ámbitos de negocio y producto guían los cambios [2]
Reducción de las alucinaciones de la IA sobre tu proyecto	El agente lee el conocimiento real del repositorio, no suposiciones [1]
Multiplataforma	Claude Code, Codex y Cursor [1]
No intrusivo	Se desinstala byte por byte [1]
Cero cambios en el flujo de trabajo	Dirige tus comandos de forma natural y los hooks se encargan del resto [1]
Conocimiento gestionado por versiones	Reside dentro del repositorio [1]
Crece con el código	El conocimiento se actualiza en el mismo cambio de código [1]

Lo que no cubre la documentación pública

Basándose en la evidencia disponible de la página principal del repositorio y el archivo README [1, 2], los siguientes detalles no están documentados públicamente:

La estructura interna de los archivos de dominios de conocimiento
El formato exacto del conocimiento almacenado (¿JSON? ¿Markdown? ¿YAML?)
Cómo se actualiza el conocimiento (¿manualmente o mediante detección automática?)
Si utiliza embeddings o coincidencia de palabras clave para recuperar el contexto
El impacto de los hooks en el tiempo de respuesta de los comandos
Cómo se resuelven los conflictos entre las entradas de conocimiento
Si soporta monorepos (repositorios múltiples)
Características de colaboración grupal (si existen)
Detalles de precios o licencias
Cómo se definen y reutilizan las "skills" (habilidades)
Integración con pipelines de CI/CD
Soporte para idiomas distintos al inglés

Nota:

Nota: El manual docs y el manual skills/akinator se encuentran en el repositorio, pero el acceso directo a ellos está bloqueado por archivos robots.txt durante esta búsqueda [8, 9].

Relación con otros trabajos de Ihab Khaled

Ihab Khaled mantiene varios proyectos integrados:

ClawAI — una plataforma de orquestación de IA prioritariamente local, que gestiona modelos abiertos en el dispositivo del usuario y se conecta con los proveedores de LLM líderes [6]. Según el registro de cambios, ClawAI en la versión 0.2.0 pasó de una arquitectura monolítica a nueve microservicios independientes de NestJS con RabbitMQ para la mensajería asíncrona y Nginx como API Gateway [7].
AI-Psychiatry — un marco para detectar la desviación conductual en agentes de IA, mencionado en el contexto de los complementos de ChatGPT [5].

Mientras que ClawAI orquestra cualquier modelo utilizado, Akinator garantiza que el modelo entienda tu proyecto antes de actuar [1][6].

La imagen general

Akinator AI representa una transición de:

"La IA como generador de código" → "La IA como miembro del equipo con memoria"

Al integrar el conocimiento del proyecto dentro del repositorio y hacerlo disponible automáticamente para los agentes de IA, aborda la limitación fundamental de la programación basada en LLMs: la pérdida de contexto. El agente deja de ser una herramienta que necesita recordatorios constantes para convertirse en algo que conoce tu proyecto [1].

Esto es especialmente importante para plataformas sensibles como la salud, donde la lógica de negocio, los requisitos regulatorios y la desviación del producto son críticos; hacer que la IA entienda por qué algo funciona de cierta manera antes de cambiarlo puede prevenir problemas de cumplimiento, cuestiones de seguridad de datos y errores de regresión [3].