Pular para o conteúdo
  1. fael.tech
  2. Estudos
  3. AIKM

AIKM.

Um gerenciador do ambiente de agentes de cada projeto: declaro as peças uma vez, e o AIKM gera os arquivos que cada ferramenta lê.

Tipo
Projeto
Estado
Open source em breve
Publicado em
Atualizado em

O problema

Trabalho em muitos repositórios com quatro ferramentas de agentes: Claude Code, Codex, GitHub Copilot e Antigravity. Cada projeto deveria dar aos seus agentes um conjunto próprio de skills, contexto e servidores MCP. Na prática, esses conjuntos eram copiados à mão ou instalados para a máquina inteira. Com o tempo eles se desatualizam, se duplicam, e fica difícil responder o que o agente de um projeto enxerga e de onde aquilo veio.

O AIKM parte de uma hipótese: declarar o ambiente de agentes de um projeto uma vez, num formato neutro, e gerar os arquivos nativos de cada ferramenta sai mais barato e é mais confiável do que manter os arquivos de cada ferramenta à mão.

Catálogo, manifesto e sync

As peças reutilizáveis ficam num catálogo, que é um repositório git próprio. Cada projeto declara no aikm.yaml quais peças usa e para quais ferramentas. O aikm sync escreve os arquivos que cada ferramenta lê e registra no aikm.lock o commit do catálogo usado, o digest de cada peça e os arquivos que passou a controlar.

Cada skill é escrita uma vez em .agents/skills/, que Codex, Copilot e Antigravity leem. Para o Claude Code, .claude/skills/ aponta para essa pasta com um link simbólico. Quando uma ferramenta precisa de algo diferente, a peça pode levar uma versão nativa só para ela.

Hoje as peças são skills. Contexto (AGENTS.md e CLAUDE.md) e servidores MCP do projeto são os próximos tipos de peça.

visibility: public # public | private
harnesses: [claude-code, codex, copilot, antigravity]
pieces: [tdd, opinions, github]
O manifesto de um projeto: a visibilidade, as ferramentas e as peças do catálogo que ele usa.

Fontes externas

Uma skill do catálogo pode trazer o conteúdo de outro repositório git, fixado num commit. O sync busca só as peças que o projeto declara e só usa o conteúdo quando o digest bate com o que está registrado na peça. O commit de cada fonte fica no aikm.lock, e uma segunda execução lê do cache, sem rede.

Por enquanto, as fontes precisam ser legíveis sem credenciais, então só repositórios públicos entram.

Garantias

O sync falha fechado. Com uma entrada inválida, ele sai sem escrever nada no projeto e diz o que fazer em seguida. Todas as checagens rodam antes da primeira escrita.

Uma peça privada nunca chega a um repositório público. O AIKM não confia só na visibilidade declarada no manifesto: pergunta ao GitHub, pelo gh, se cada remoto do projeto é privado, e recusa se algum não for.

Além do aikm.lock, ele só escreve e apaga caminhos que o lock diz que são dele. Não executa scripts das skills e não toca nas configurações de usuário das ferramentas. Rodar o sync de novo sem mudanças não gera diff, então o git diff mostra exatamente o que ele fez.

Repositório do AIKMOpen source em breve

Atualizações

  1. O AIKM passou a gerenciar o ambiente de agentes de cada projeto, e o estudo foi reescrito para descrever o catálogo, o manifesto, o sync, as fontes externas e as garantias.
  2. Primeira publicação.
← Todos os estudos