Akinator AI: Camada de Conhecimento Vivo para Repositórios de Código — Guia Abrangente

11 min de leitura

Pontos Principais

• Akinator AI é uma camada de conhecimento persistente dentro do repositório que faz com que os agentes de programação de IA leiam a intenção do projeto antes de modificá-lo [1].
• Rastreia onze domínios de conhecimento: Produto, Negócios, Requisitos, Desvio (Drift), Arquitetura, Bibliotecas, Decisões, Histórico, Regras, Habilidades e Memória [2].
• A instalação leva 30 segundos e não requer nenhuma mudança na sua forma de trabalhar — apenas direcione seus comandos normalmente [1].
• Resolve o problema fundamental da programação generativa: a perda de contexto entre sessões e a repetição de erros devido ao desconhecimento da lógica de negócio por parte do agente [3].

O que é Akinator AI?

Akinator AI é um projeto de código aberto desenvolvido por Ihab Khaled, que visa transformar o repositório de código em sua própria "wiki viva". O slogan principal do projeto resume a ideia: "O código diz como. O Akinator guarda o quê, por que, quem, quando, antes, agora, próximo" [1].

Ao contrário dos assistentes de programação tradicionais que entendem apenas o código, o Akinator foca em manter o contexto completo por trás do código: decisões de produto, regras de negócio, contexto histórico, falhas e a evolução da arquitetura [3].

Nota:

Nota: O nome é inspirado no famoso jogo de adivinhação Akinator, mas a função é completamente diferente — em vez de adivinhar personagens, este sistema garante que o agente de IA conheça seu projeto antes de tocar em um único arquivo [1].

O Problema Fundamental que Resolve

Quando você depende da "programação generativa" (vibe coding) — ou seja, o desenvolvimento baseado em comandos de texto — o agente de IA enfrenta problemas recorrentes:

• Não conhece a lógica de negócio do seu projeto
• Não entende o motivo de decisões anteriores
• Desconhece os requisitos do produto e sua evolução
• Não sabe o que mudou e por quê
• Perde o contexto entre sessões consecutivas
• Repete erros ou contradiz decisões anteriores

O Akinator resolve esses problemas mantendo uma "wiki viva" dentro do próprio repositório que o agente lê automaticamente [1].

Os Onze Domínios de Conhecimento

O Akinator rastreia domínios de conhecimento específicos dentro do repositório, de acordo com a documentação oficial [2]:

Como Funciona Tecnicamente

Instalação em 30 Segundos

No macOS e Linux (para todas as plataformas instaladas — Claude Code, Codex e Cursor):

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

No Windows (PowerShell 5.1 ou superior):

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

Após a instalação, reinicie o seu agente. Não é necessário nenhum comando manual — apenas direcione seus comandos normalmente [1].

Integração com Plataformas

O mecanismo principal são os hooks que funcionam automaticamente:

• Hook SessionStart — injeta conhecimento e contexto no início da sessão
• Hook por comando — reinjeta o contexto relevante antes de cada comando do usuário

Isso significa que o agente não precisa que lhe seja pedido para ler a documentação — isso acontece automaticamente todas as vezes [1].

Atualização e Desinstalação

• Para atualizar: execute novamente o mesmo comando de instalação
• Para desinstalar: adicione --uninstall (ou -Uninstall no Windows) — o repositório é restaurado byte a byte
• Opções: --claude, --codex e --cursor para escolher as plataformas, e --repo PATH para a localização de um repositório personalizado [1]

Como a IA orienta para um futuro de programação melhor

Sem Akinator

Usuário: "Adicione rate limiting para a exportação de dados"
IA: [modifica os arquivos sem saber por que a exportação existe,
     ou as regras de negócio que a regem, ou os padrões do projeto]

Com Akinator

Usuário: "Adicione rate limiting para a exportação de dados"
IA: [lê o contexto do produto, regras de negócio, decisões de arquitetura,
     histórico de desvio, escolhas de bibliotecas,
     e então modifica os arquivos com total consciência]

O agente entende a intenção antes da ação [1].

Tratando o Desvio do Produto

O desvio do produto (product drift) é a lacuna entre o que foi originalmente pretendido e o que o produto se tornou ao longo do tempo. O Akinator rastreia o desvio como um domínio de conhecimento de primeira classe [2].

Isso significa que:

• O estado anterior está registrado (como o produto era)
• O estado atual está registrado (como ele é agora)
• A justificativa da transição está registrada (por que mudou)
• A direção futura é capturada (o que vem a seguir)

Quando o agente faz alterações, ele pode recorrer ao histórico de desvio para:

1. Evitar reverter decisões que foram alteradas deliberadamente
2. Entender o contexto de por que o estado atual difere dos planos originais
3. Manter a consistência com a trajetória do produto
4. Identificar conflitos potenciais entre uma nova alteração e a direção decidida

Suporte ao Contexto da IA

O contexto de programação tradicional é temporário — existe apenas na conversa atual. Quando a sessão termina, o contexto é perdido.

O Akinator cria um contexto permanente através de três níveis [1]:

Nível de Sessão

• O hook SessionStart carrega o conhecimento relevante no início da sessão
• O hook por comando reinjeta antes de cada comando

Nível de Repositório

• O conhecimento vive dentro do repositório como arquivos
• Gerenciado por versões lado a lado com o código
• Cresce com cada alteração no código

Entre Sessões

• O escopo da memória persiste entre sessões
• O escopo do histórico mantém a linha do tempo
• O escopo de decisões salva as justificativas

Isso significa que uma nova sessão começa com plena consciência do projeto, e não com uma página em branco [1].

Capturando Expectativas do Produto

As expectativas do produto — ou seja, o que os stakeholders esperam do produto — são mantidas através de múltiplas camadas [2]:

Quando a IA programa uma funcionalidade, ela pode verificar:

• Isso está em conformidade com os requisitos atuais?
• Isso viola qualquer regra de negócio?
• Isso corresponde ao escopo do produto?
• Esta expectativa foi alterada deliberadamente (desvio)?
• Houve alguma decisão anterior a respeito disso?

Lidando com Mudanças na Lógica do Produto e de Negócio

Quando a lógica de negócio muda:

1. A mudança em si é registrada no escopo do histórico
2. A justificativa é capturada nas decisões
3. O desvio da lógica anterior é rastreado
4. A nova lógica é codificada nos escopos de negócio e regras
5. O agente lê tudo isso automaticamente via hooks antes da próxima ação

Isso cria uma trilha de auditoria de intenção — não apenas as alterações de código, mas por que essas alterações ocorreram sob a perspectiva de negócios [1].

Programação Generativa como uma Empresa Integrada

“Programação Generativa” significa o desenvolvimento baseado em prompts, onde você descreve o que deseja e a IA o constrói. O Akinator eleva isso de programação em nível de arquivo para programação consciente da empresa, concedendo ao agente o mesmo contexto que um engenheiro sênior + gerente de produto + arquiteto possuem [1].

Conhecimento do Engenheiro

• Padrões de arquitetura
• Escolhas de bibliotecas e seus motivos
• Regras de codificação
• Decisões técnicas e suas justificativas

Conhecimento do Gerente de Produto

• Escopo e identidade do produto
• Requisitos atuais
• Regras de negócio
• Histórico de derivação (drift) do produto

Conhecimento do Arquiteto

• Decisões estruturais
• Histórico de restrições
• Por que certos padrões foram escolhidos ou rejeitados

Memória da Equipe

• Quem decidiu o quê e quando
• Histórico de alterações
• Habilidades e padrões reutilizáveis

Quando você escreve:

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

A IA sabe [1]:

• O que o sistema de pagamento faz (Produto)
• Quais regras de negócio regem a tentativa de repetição (Negócio)
• Qual arquitetura o serviço de pagamento utiliza (Arquitetura)
• Quais bibliotecas estão envolvidas (Bibliotecas)
• Quais decisões foram tomadas sobre a tentativa de repetição (Decisões)
• Como a lógica de repetição mudou (Derivação/Histórico)
• Quais regras se aplicam ao código de pagamento (Regras)

Ele programa como se estivesse na sua equipe desde o primeiro dia.

O Ciclo de Doze Estações do Akinator

De acordo com a documentação disponível no guia de extensões do ChatGPT, o Akinator executa cada interação com o repositório através de um ciclo de doze estações [4]:

1. Perguntar — Identificar o que precisa de esclarecimento
2. Resolver — Tratar a ambiguidade
3. Auditar — Revisar o estado atual
4. Planejar — Elaborar um plano de mudança
5. Executar — Implementar as modificações
6. Documentar — Atualizar a documentação
7. Converter em habilidade — Transformar processos repetitivos em habilidades
8. Regra — Impor as lições como regras
9. Contexto — Vincular a mudança ao contexto mais amplo
10. Salvar — Armazenar na memória
11. Indexar e Sincronizar — Manter os arquivos de roteamento sincronizados
12. Verificar — Verificação final em uma única etapa

Aviso:

Aviso: Este ciclo está documentado como um conceito/demonstração no guia de extensões, e não está claro a partir do resumo se uma versão completa do código está disponível publicamente no repositório vinculado [4].

Cenários de Uso Prático

Cenário 1: Onboarding de um novo desenvolvedor

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

A IA lê os domínios de arquitetura, produto, negócios e histórico → fornece uma resposta baseada no contexto real do projeto, e não em conhecimento geral [1].

Cenário 2: Adição de funcionalidade

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

A IA lê a lógica de exportação atual, as regras de negócio, as restrições de arquitetura e as escolhas de bibliotecas → implementa a limitação de taxa (rate limiting) de forma compatível com o sistema existente [1].

Cenário 3: Correção de erro

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

A IA lê o histórico de pagamentos, as decisões anteriores, a derivação e as regras de negócio → corrige o erro sem quebrar o comportamento pretendido [1].

Cenário 4: Pergunta arquitetural

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

A IA lê os domínios de decisões, arquitetura e histórico → explica a justificativa real, e não uma suposição [1].

Cenário 5: Continuidade multissessão

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

A IA lê a memória e o histórico → sabe que a migração está em andamento, o que foi concluído e o que vem a seguir [1].

Resumo dos Benefícios

O que a documentação pública não cobre

Com base nas evidências disponíveis na página principal do repositório e no arquivo README [1, 2], os seguintes detalhes não estão documentados publicamente:

• A estrutura interna dos arquivos de escopos de conhecimento
• O formato exato do conhecimento armazenado (JSON? Markdown? YAML?)
• Como o conhecimento é atualizado (manualmente ou detecção automática?)
• Se utiliza embeddings ou correspondência de palavras-chave para recuperar o contexto
• O impacto dos hooks na latência dos comandos
• Como são resolvidos os conflitos entre as entradas de conhecimento
• Se suporta monorepos
• Recursos de colaboração em grupo (se houver)
• Detalhes de preços ou licenciamento
• Como as "skills" são definidas e reutilizadas
• Integração com pipelines de CI/CD
• Suporte para outros idiomas além do inglês

Nota:

Nota: Os diretórios docs e skills/akinator estão presentes no repositório, mas o acesso direto a eles foi bloqueado por arquivos robots.txt durante esta pesquisa [8, 9].

Relação com outros trabalhos de Ihab Khaled

Ihab Khaled mantém vários projetos integrados:

• ClawAI — Uma plataforma de orquestração de IA local-first, que gerencia modelos abertos no dispositivo do usuário e se conecta aos principais provedores de LLM [6]. De acordo com o changelog, o ClawAI na versão 0.2.0 mudou de uma arquitetura monolítica para nove microserviços NestJS independentes com RabbitMQ para mensagens assíncronas e Nginx como API gateway [7].
• AI-Psychiatry — Um framework para detecção de desvio comportamental em agentes de IA, mencionado no contexto de extensões do ChatGPT [5].

Enquanto o ClawAI orquestra qualquer modelo utilizado, o Akinator garante que o modelo entenda o seu projeto antes de agir [1][6].

A Visão Geral

O Akinator AI representa uma transição de:

"IA como gerador de código" → "IA como membro da equipe com memória"

Ao incorporar o conhecimento do projeto dentro do repositório e torná-lo automaticamente disponível para agentes de IA, ele resolve a limitação fundamental da programação baseada em grandes modelos de linguagem: a perda de contexto. O agente deixa de ser uma ferramenta que precisa de lembretes constantes e torna-se algo que conhece o seu projeto [1].

Isso é especialmente importante para plataformas sensíveis, como a saúde, onde a lógica de negócio, os requisitos regulatórios e o desvio do produto são críticos — fazer com que a IA entenda por que algo funciona de determinada maneira antes de alterá-lo pode evitar problemas de conformidade, questões de segurança de dados e erros de regressão [3].

Fontes

• 1
• 2
• https://www.linkedin.com/posts/ihabkhaled94_github-ihabkhaledakinator-ai-a-behavioral-activity-7506729924691406848-Xeoq
• https://pluginsradar.com/chatgpt/plugins/akinator-788ea07d
• https://pluginsradar.com/chatgpt/developers/ihab-khaled
• https://github.com/ihabkhaled/ClawAI
• https://github.com/ihabkhaled/ClawAI/blob/6a5bc7fb5c0532a90f393c49acaedb8832283f98/CHANGELOG.md
• 8
• 9