Shikhu: transforme sua base de código em simulados e acompanhe sua cobertura de conhecimento

Para quem é

Você herdou uma base de código que não consegue terminar de ler, ou alguém no time sempre pergunta: «quem realmente usa isso?». Se o seu objetivo é fazer um agente de programação com IA praticar repetidamente sobre o seu próprio código e transformar «quanto eu realmente entendo?» em um número que você possa acompanhar, a abordagem do Shikhu se encaixa melhor do que uma troca pontual de perguntas: ela transforma o aprendizado em geração de perguntas e respostas, a ferramenta extrai perguntas do repositório e registra quais você acertou e errou, e as skills que acompanham o pacote conduzem você pelos pontos-chave dos arquivos que você indicar. É para quem estiver disposto a deixar um agente praticar por alguns rounds em código real e aceitar que «o modelo vai ler o seu código».

Seu primeiro teste em 3 minutos

O caminho oficial é único, e começa instalando a ferramenta de linha de comando:

uv tool install shikhu

Depois de instalado, shikhu fica no PATH e roda em um ambiente isolado, então não briga com as dependências do seu projeto.

Existem dois pré-requisitos: uv disponível no ambiente e uma chave de API da OpenRouter — colocada em um .env na raiz do repositório (carregado automaticamente) ou exportada no shell como OPENROUTER_API_KEY, porque todas as chamadas a modelos passam pela OpenRouter.

Depois, execute na raiz do código que você quer aprender:

shikhu init

Esta etapa realmente grava arquivos, então confirme antes de rodar: ela escreve o banco de dados local coverage.db (entra automaticamente no .gitignore), gera o .quizignore (usado como .gitignore, para excluir arquivos de configuração ou documentação do conjunto de questões) e instala as duas skills no diretório de skills do seu agente.

Onde a instalação acontece: as skills vão para .claude/skills/ e/ou .agents/skills/ se esses diretórios já existirem no repositório (depende de qual família o seu agente usa); se nenhum dos dois existir, ambos são criados. Para reinstalar depois ou instalar globalmente, use shikhu install-skill, com --global para o escopo global.

Na primeira ativação, escolha algo somente de leitura e reversível: em um agente de programação com suporte a skills, rode /shikhu-study apontando para um arquivo pequeno, ou use /shikhu-inquiry para fazer uma pergunta que envolva apenas uma função. Antes de perguntar, confirme que essa pergunta vai gerar uma chamada a um modelo externo (via OpenRouter, consumindo cota) e só então envie.

Três sinais de sucesso observáveis: nas respostas do agente aparecem nomes de arquivos, funções e relações de chamada que existem de fato no seu repositório, em vez de tutoriais genéricos; as perguntas que você fez viram sementes de simulado e podem reaparecer quando novas questões forem geradas; e coverage.db e .quizignore aparecem na raiz do projeto.

Casos de uso

Caso um: autoestudo direcionado a um módulo.

Primeiro, construa o índice:

shikhu summarize

Ele grava para cada arquivo rastreado um resumo gerado por modelo e guardado em cache; uma chamada de modelo por arquivo, e arquivos cujo conteúdo não mudou não são reprocessados. As skills e o shikhu map se apoiam nesses resumos para decidir «quais arquivos eu devo olhar para esta pergunta?». Com o índice pronto, rode /shikhu-study no agente indicando o arquivo ou diretório a estudar, e o agente percorre um a um guiado pelas localizações apontadas nos resumos.

Caso dois: transformar perguntas do dia a dia em sementes de simulado.

No agente, use /shikhu-inquiry para perguntar algo sobre o seu próprio código — por exemplo, de onde vêm os parâmetros de um endpoint ou por que um trecho de lógica foi escrito assim. Ele responde e, ao mesmo tempo, registra a pergunta como semente de simulado; depois, quando a ferramenta gerar simulados a partir do código, essas sementes entram na conta, e seus acertos e erros são acompanhados como cobertura de conhecimento. Para concentrar as questões no código de verdade, use .quizignore para excluir arquivos de configuração e documentação.

Limites de uso

• É preciso fornecer a sua própria chave de API da OpenRouter; sem ela, nenhuma etapa que envolva geração por modelos pode ser executada.
• shikhu summarize é cobrado por arquivo: quanto maior o repositório, mais lenta e cara é a primeira indexação; apenas arquivos cujo conteúdo mudou são reprocessados.
• Onde as skills ficam depende de quais diretórios de skills já existem no repositório; se nenhum existir, os dois são criados ao mesmo tempo.
• coverage.db é gravado no projeto, mas entra automaticamente no .gitignore, não é sincronizado com o controle de versão, e nem a cobertura nem o histórico de respostas são compartilhados entre as pessoas do time.
• A fonte explica o uso, os comandos e os locais de instalação da ferramenta de linha de comando e das duas skills; mas não diz quais linguagens de programação têm suporte, como a cobertura é calculada exatamente nem como os níveis de dificuldade são definidos — não deduza isso do comportamento habitual de outras ferramentas de teste.