Setup Local de Agentes de IA

Este guia organiza o uso local de agentes e plugins de IA em repos da MIDDAG. Esses arquivos normalmente são estado de execução, instalação por desenvolvedor ou cache de ferramenta; por isso, ficam no .gitignore.

Política

• Não versionar estado local de agentes.
• Não versionar logs, sessões, caches, chaves ou configurações pessoais.
• Não copiar diretórios de um dev para outro.
• Versionar apenas arquivos de configuração compartilhados quando houver decisão explícita do projeto.
• Documentar no repo quando uma ferramenta for obrigatória para desenvolver, testar ou publicar.

Ferramentas conhecidas

Ferramenta	Uso típico	Ignorar no Git
AIOX	Instalação/runtime local de agentes via aiox-core.	.aiox-core/, .aiox-core/local/, .aiox/install-log.txt
Ralph	Estado de sessão, contadores, logs e progresso de agente/plugin.	.ralph/.call_count, .ralph/logs/, .ralph/status.json, .ralph/docs/generated/
GStack	Estado local de orquestração ou stack de agentes.	.gstack/
Caveman	Instalação local de skills/agentes para uso no ambiente do dev.	.agents/, .claude/skills/, skills-lock.json
Claude/Codex local	Preferências, skills e ajustes por máquina.	.claude/settings.local.json, .claude/skills/

Setup recomendado

1. Instale a ferramenta pelo método oficial do projeto ou plugin.
2. Execute a instalação dentro do repo somente quando a ferramenta exigir estado local.
3. Confira git status --short após instalar.
4. Se aparecerem arquivos novos de runtime, cache ou sessão, adicione a regra ao .gitignore antes de continuar.
5. Se aparecerem arquivos de configuração que parecem úteis para toda a equipe, valide antes de versionar.

AIOX

Quando um repo usar AIOX, a instalação local pode criar .aiox-core/, .aiox-core/local/ e .aiox/install-log.txt. Esses arquivos são específicos do ambiente do dev e não devem ser versionados.

npx aiox-core install

Ralph

Ralph gera arquivos de sessão, progresso, logs e controle de execução. Esses arquivos ajudam a ferramenta localmente, mas não representam código, documentação aprovada ou configuração compartilhada.

Se algum artefato gerado pelo Ralph for útil como documentação, mova o conteúdo revisado para docs/ ou docs-site/ em vez de versionar .ralph/docs/generated/.

GStack

.gstack/ deve ser tratado como estado local de orquestração. Não use esse diretório como fonte de configuração operacional do projeto.

Caveman, Claude e skills locais

Skills instaladas em .claude/skills/ ou .agents/ são instalação local. Para padronizar uma skill na equipe, documente a necessidade no guia do projeto e prefira uma fonte instalável ou um procedimento claro, em vez de commitar a instalação local inteira.

Quando versionar algo

Versione apenas quando o arquivo for:

• necessário para build, teste, lint ou deploy;
• seguro para publicação no repositório;
• estável entre máquinas;
• revisado como configuração compartilhada.

Em caso de dúvida, mantenha local e registre a decisão em um guia ou ADR.