rafaelcmm

Uma configuração só para Claude Code, Copilot e Cursor

Minhas regras, skills e instruções de agente ficam num repositório só. Uma CLI em Rust instala tudo em três ferramentas de IA sem mexer nos meus arquivos.

Teclado preto iluminado diante de dois monitores com código, em sala escura com luz alaranjada
  • ai-agents
  • claude-code
  • github-copilot
  • cursor
  • rust
  • dotfiles

São três ferramentas de IA no mesmo computador, e cada uma lê regras, skills e instruções de agente da própria pasta. Eu guardo uma cópia só de tudo isso num repositório, e uma CLI pequena que escrevi em Rust, o ai-dotfiles, instala no Claude Code, no GitHub Copilot e no Cursor.

Copiar os arquivos é simples. O que deu trabalho foi atualizar e apagar depois sem levar junto o que eu editei à mão. Quem resolve isso é o manifesto, mais abaixo.

Três ferramentas, três pastas

O ai-dotfiles cuida de ~/.claude, ~/.copilot e ~/.cursor. Cada pasta recebe os mesmos dois arquivos na raiz:

  • AGENTS.md, o contrato comum: ordem de prioridade, como o trabalho é verificado, regras de segurança.
  • CLAUDE.md, que importa o @AGENTS.md e acrescenta o que vale só para uma ferramenta.

As regras e as definições de agentes também ficam em cada pasta. A CLI ainda grava arquivos iniciais de hooks e de servidores MCP: ~/.claude/settings.json, ~/.copilot/hooks/hooks.json, ~/.cursor/hooks.json, ~/.cursor/mcp.json e ~/.copilot/mcp.json. Ela também mescla os servidores dela no mcp.json do VS Code e, se um nome coincidir, continua valendo o servidor que eu mesmo configurei.

O Cursor é o ponto fora da curva. Ele guarda as regras globais numa tela de configurações chamada User Rules, e não num arquivo que dê para instalar. Por isso a CLI instala um modelo em ~/.cursor/instructions/user-rules-template.md, e depois de cada instalação ou atualização eu colo o conteúdo lá à mão.

Cada skill existe uma vez só

As skills são instaladas uma vez, em ~/.claude/skills. O Copilot consegue ler as skills do Claude nesse caminho, então não existe segunda cópia para manter em dia.

O binário traz 53 pastas de skills próprias, e um arquivo chamado external-skills.toml declara outras 124, de outros repositórios. Cada fonte externa fica fixada num SHA de commit completo, nunca numa branch ou tag, e pode ter um checksum SHA-256 do SKILL.md. Se o download de uma fonte falha durante uma atualização, a CLI avisa e mantém a cópia que já estava instalada, então a skill continua lá.

Parte das skills e regras é adaptada do trabalho de outras pessoas, principalmente do obra/superpowers (MIT) e do flutter/agent-plugins (BSD-3-Clause). Os commits de origem e as licenças ficam num NOTICE.md que é instalado junto com as skills.

Três comandos e um manifesto

ai-dotfiles install
ai-dotfiles update
ai-dotfiles debloat

Eu também edito essas pastas à mão, e é por isso que update e debloat não tentam adivinhar nada. Cada pasta ganha um arquivo _meta.md, e o front matter YAML dele registra a versão e todos os arquivos e diretórios que a CLI gravou. Os dois comandos tratam essa lista como a fonte da verdade.

O update calcula quais arquivos a versão atual deve instalar e apaga os arquivos rastreados que saíram dessa lista. Depois grava só o que é novo ou mudou e reescreve o _meta.md por último, para que o manifesto descreva o que de fato está no disco. O debloat remove tudo o que o manifesto lista e, no fim, o próprio manifesto.

Um arquivo que eu criei não está no manifesto, então nenhum dos dois comandos mexe nele. A limpeza nunca entra em diretório que seja link simbólico. E o install se recusa a rodar por cima de uma instalação que já existe: ele manda rodar update.

Cada versão do binário é uma versão da configuração

Os arquivos de static/ são embutidos no binário durante o build. Por isso a v3.2.2 instala exatamente as regras e skills que estavam no repositório quando essa tag foi criada. Fixar uma versão é um comando:

cargo install --locked --git https://github.com/rafaelcmm/ai-dotfiles.git --tag v3.2.2 ai-dotfiles

Antes de sincronizar os arquivos, o update procura uma versão mais nova no GitHub. Se encontra, baixa o binário da minha plataforma e confere se o SHA256SUMS da release lista esse arquivo. Depois instala e roda o update de novo, já na versão nova. Um erro de rede nessa etapa não impede a sincronização.

Toda release passa pelo scripts/release.sh. O script recusa árvore de trabalho suja e qualquer branch que não seja a main. Depois roda cargo fmt --check, cargo clippy tratando aviso como erro, os testes offline e os testes de integração que usam a rede. Só então muda a versão e cria a tag. A v3.2.2 é a 53ª tag de versão desde o primeiro commit, em abril de 2026.

O hook que segura os agentes dentro do repositório

A CLI também instala alguns scripts de hook. Um deles, o guard-paths.sh, bloqueia escrita de agente fora do repositório atual. São quatro exceções, e todas vêm de como o Claude Code funciona:

  • um arquivo Markdown direto na pasta de memória por projeto do Claude Code;
  • um arquivo Markdown direto na pasta de planos dele;
  • qualquer arquivo no scratchpad da sessão;
  • a pasta onde a sessão começou. Ela precisa ficar dentro da minha home sem ser a própria home, não ter pasta oculta no caminho abaixo da home e conter o diretório de trabalho.

Os caminhos são resolvidos antes da comparação, então .. e links simbólicos não ampliam nenhuma dessas exceções.

O que as regras pedem aos agentes

As regras que o ai-dotfiles instala definem como os agentes trabalham comigo. Eles planejam antes de construir, mostram evidência antes de dizer que terminaram e nunca enviam nada em meu nome. Conto como elas funcionam em Spec-first com IA: o que delego e o que fica comigo.

O código tem licença MIT e está público em github.com/rafaelcmm/ai-dotfiles. Se for abrir uma pasta só, abra a static/: é ali que está a configuração.