~/studies/work 2026-11-20 · published 2026-11-21
Um centro, três satélites
Por que a forma de trabalhar da equipe vive em um repositório e cada outro harness tem o seu, incorporado como submódulo em vez de conteúdo copiado.
- harness
- architecture
- git
- submodules
- ~/project/versatile-sh
O problema de uma pasta grande
Nossa configuração para trabalhar com agentes de IA começou como uma pilha de instruções. Regras, padrões, registros de projetos, notas de infraestrutura e pesquisa ficavam todos juntos, e cada sessão carregava o que estivesse mais perto. Cresceu até ninguém conseguir dizer qual arquivo era dono de qual fato.
O harness da equipe (`versatile-sh/.claude`) mergeou os pull requests #166 a #178 em 2026-11-20, entre eles o que restringiu os repositórios da equipe a conhecimento do Versatile apenas (#169). É o dia pelo qual data este post. Ele descreve o formato que saiu daí, não um resultado medido: não tenho números de antes e depois, e não vou inventar nenhum.
O formato
O centro é `.claude`. Ele guarda só como trabalhamos: o arquivo router, os guias de `docs/work/`, skills, agentes, comandos, as ferramentas de `bin/` e os hooks. Nunca guarda uma regra de engenharia, um fato de projeto, um handoff nem um log pessoal.
Todo outro harness é um satélite com seu próprio repositório:
| Repositório | Guarda |
|---|---|
| versatile-harness | A base de conhecimento de engenharia (premises, rules, patterns, standards, lints, design) e o lar de registros de cada projeto |
| hosting-harness | Infraestrutura e a configuração de deploy de cada app |
| research-harness | O engine de pesquisa: método, estudos, estado |
| <domain>-media | A cópia canônica de toda imagem, vídeo e fonte de design |
O centro carrega os três primeiros como submódulos git sob `harness/`. Nada é copiado. Uma sessão lê `harness/versatile-harness/` do mesmo jeito que lê qualquer outro arquivo, e o conteúdo é o que o `main` daquele satélite disser.
Por que repositórios separados
A premissa está escrita na base de conhecimento como um arquivo curto, e o núcleo dela é uma única frase: um harness pode ser reduzido, substituído e iterado por si só, então nunca é embutido no centro nem em outro harness.
- Ritmos de mudança diferentes. A base de conhecimento recebe muitos pull requests pequenos por dia. A forma de trabalhar muda raramente e afeta todo mundo. Misturar os dois faz toda revisão tratar de duas coisas.
- Públicos diferentes. A configuração de deploy nunca deve viajar com o repositório de um produto. Mantê-la em um repositório próprio faz dessa fronteira uma fronteira de repositório em vez de uma convenção.
- Substituibilidade. Se o engine de pesquisa se mostrar errado, pode ser reescrito sem tocar no resto.
- Uma regra para coisas novas. Algo parecido com um harness sem repositório ainda é proposto como um novo `<name>-harness`. Não é dobrado em um existente.
As regras que o mantêm honesto
- A verdade de um satélite é o `main` dele no GitHub. A pasta sob `harness/` é uma cópia de leitura.
- Nunca edite sob `harness/`. Mude a cópia de trabalho irmã, em uma branch, por um pull request.
- O que uma sessão aprende sobre o Versatile vai para um lar compartilhado por um pull request, nunca só para a memória. O que ela aprende sobre qualquer outro projeto fica local, em uma pasta `local/` ignorada.
A segunda e a terceira regra são o motivo de a separação compensar. Um fato tem exatamente um lar, e uma busca que cai no repositório errado não acha nada em vez de uma cópia obsoleta.
O que custa
Três coisas ficam mais difíceis. Uma mudança que abrange o centro e um satélite precisa de dois pull requests. Os ponteiros que registram qual commit de cada satélite o centro lê podem ficar para trás. E uma pessoa precisa saber qual repositório é dono de um assunto. A tabela de routing no arquivo router do centro existe para o último. O próximo post cobre a ferramenta que cuida do segundo.
Acho que a troca é certa, mas isso é um julgamento de dias de uso por uma equipe pequena, não uma medição. Se os pull requests de ponteiros começarem a virar ruído, a resposta será automatizá-los mais, não juntar os repositórios de novo.