harness-bootstrap

Instala um harness completo e pronto para equipe em qualquer repositório git: arquivos de entrada (CLAUDE.md / AGENTS.md), documentação de arquitetura e confiabilidade, scripts de verificação em camadas, regras de arquitetura executáveis, uma lista de tarefas cujo status só um verificador pode alterar, arquivos de handoff e progresso locais (gitignorados), um checklist de estado limpo, um avaliador independente e verificações de integridade que garantem tudo. Funciona com qualquer agente de codificação (Claude Code, Codex, Cursor, Copilot, Devin, Pi e outros).

O que é harness-bootstrap?

Este skill, harness-bootstrap, transforma qualquer repositório git em um ambiente onde agentes de IA podem trabalhar de forma consistente e confiável, resolvendo cinco perguntas essenciais apenas com o conteúdo do repositório: o que é, como está organizado, como executar, como verificar e onde parou. Ele instala um contrato (arquivos de configuração, regras, scripts de verificação) que a equipe commit e skills de ciclo de vida (harness-start, harness-handoff, harness-cleanup, harness-evaluate) que ficam dentro do repositório, garantindo que cada membro da equipe receba as mesmas ferramentas ao clonar, independentemente do agente de codificação utilizado (Claude Code, Codex, Cursor, Copilot, Devin, Pi e outros). O processo é executado uma vez por repositório e inclui etapas como confirmação do destino (deve ser um repositório git), inventário de arquivos existentes, descoberta de como o projeto é executado, perguntas direcionadas para preencher lacunas, cópia do scaffold, preenchimento de especificações do projeto (configuração, regras de arquitetura, documentação), configuração do arquivo de entrada, mesclagem de configurações (como .gitignore e hooks do Claude Code) e uma verificação final. O skill garante que nenhum arquivo existente seja sobrescrito sem permissão e que toda a configuração seja ajustada às particularidades do projeto, resultando em um ambiente onde o estado das tarefas é gerenciado localmente (não commitado) e as decisões de 'pronto' são baseadas em scripts, não na opinião do agente.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Boostrap do Harness

Transforme um repositório em um lugar onde qualquer sessão de agente nova, em qualquer máquina de desenvolvedor, consiga responder cinco perguntas a partir apenas do repositório: o que é isso, como está organizado, como executar, como verificar e onde paramos. Depois, faça com que "pronto" seja algo que um script decide, não o agente.

Este skill é executado uma vez por repositório. Ele instala um contrato que a equipe commit, e skills de ciclo de vida (harness-start, harness-handoff, harness-cleanup, harness-evaluate) que vivem dentro do repositório para que cada colega os receba ao clonar, independentemente do agente de codificação que usam.

Os caminhos neste arquivo (scripts/, references/, assets/) são relativos ao diretório que contém este SKILL.md. Onde esse diretório está depende do agente e de como o skill foi instalado, então resolva-o a partir da localização de onde você carregou este arquivo; nunca assuma um caminho fixo como ~/.claude/skills/.

Leia references/principles.md se precisar da lógica por trás de qualquer artefato (por exemplo, para explicá-lo ao usuário ou para adaptá-lo a um repositório incomum).

O modelo que você está instalando

CamadaOndeComitado?Propósito
Arquivo de entradaCLAUDE.md e/ou AGENTS.mdsimMapa resumido: o quê, como executar, como verificar, regras rígidas, links
Documentaçãodocs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/simConhecimento que o agente não pode inferir do código
Contratoharness/ (config, regras, checklist, rubrica, documento de qualidade, modelos, README)simMesmas regras para todos, alteradas apenas por PR
Verificaçãoscripts/harness/siminit.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh
Ciclo de vida.agents/skills/harness-*, espelhado para agentes que leem outra pastasimIniciar, passar adiante, limpar, avaliar
AdaptadoresPor agente, por exemplo .claude/agents/, .claude/hooks/ para Claude CodesimExtras opcionais: subagente, hooks
Estado da tarefa.harness/tasks/<TASK-ID>/nãoLista de funcionalidades, contrato, progresso, handoff, logs de execução de uma tarefa

O estado da tarefa é local porque muda a cada sessão e pertence ao branch de uma pessoa. Comitá-lo causa conflitos de merge e permite que o estado obsoleto de um desenvolvedor engane o agente de outro desenvolvedor. É um cache: tudo durável é promovido para código, testes, documentação, PR ou rastreador de issues antes do fim da tarefa. harness/README.md explica isso à equipe.

Fluxo de trabalho

1. Confirmar o destino

Execute git rev-parse --show-toplevel no diretório que o usuário quer. Se não for um repositório git, pare e informe: o isolamento de worktree e as verificações de branch base dependem do git. Anote se a árvore de trabalho está suja; sugira fazer o bootstrap em seu próprio branch para que possa ser revisado como um único PR.

2. Inventariar o que já existe

Olhe antes de escrever. Encontre e leia:

  • Arquivos de instrução: AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, GEMINI.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules
  • Documentação: README*, docs/, pastas ADR, CONTRIBUTING*
  • Peças de harness existentes: feature_list.json, progress.md, init.sh, Makefile, harness/, scripts/harness/, .harness/
  • Configuração e skills do agente: .agents/skills/, .claude/ (settings.json, skills/, agents/, hooks/), .devin/, .cursor/, .github/, .worktreeinclude
  • .gitignore

O conteúdo existente vence. Você o estende; nunca substitui um arquivo que a equipe escreveu sem perguntar.

3. Descobrir como o projeto é executado

Siga references/discovery.md. O objetivo é uma lista verificada de comandos para cada camada de verificação, cada um com o local onde você o encontrou (a configuração de CI é a evidência mais forte, porque é o que a equipe realmente confia). Identifique também as camadas ou módulos do código e as direções de dependência entre eles; eles se tornam regras de arquitetura.

4. Perguntar apenas pelas lacunas

Agrupe as perguntas que você não conseguiu responder a partir do repositório em uma única chamada de pergunta estruturada se seu ambiente tiver uma, caso contrário, em uma única mensagem. Lacunas típicas:

  • Limites de arquitetura que você inferiu, mas não tem certeza ("ui/ tem permissão para importar db/?")
  • O comando end-to-end ou smoke, se nenhum existir
  • Branch base e convenção de nomenclatura de branch, se não documentado
  • Quais agentes de codificação a equipe usa (Claude Code, Codex, Cursor, Copilot, Devin, Pi, outros). Isso decide o arquivo de entrada e quais adaptadores de agente instalar.
  • Se a equipe usa Claude Code: se deve instalar seus hooks (recomendado; eles exibem o estado da tarefa no início da sessão e bloqueiam edições manuais do estado da tarefa antes que aconteçam)

Não pergunte sobre coisas com um padrão convencional; escolha e mencione no relatório final.

5. Copiar o scaffold

bash <diretório deste skill>/scripts/install.sh <raiz-do-repo> --agents <ids>

--agents recebe os agentes da equipe da etapa 4 como ids separados por vírgula, os mesmos ids que a CLI npx skills usa (claude-code, codex, cursor, github-copilot, gemini-cli, opencode, pi, devin, windsurf, kiro-cli, ...; --help os lista).

O script copia assets/project/ para o repositório, incluindo os skills de ciclo de vida em .agents/skills/, que a maioria dos agentes lê diretamente. Para agentes que leem outra pasta (claude-code, devin, windsurf, kiro-cli) ele adiciona links simbólicos relativos para esses skills, e para agentes com um adaptador em assets/adapters/<id>/ ele copia os arquivos do adaptador. Passe --copy para cópias em vez de links simbólicos quando a equipe tiver checkouts do Windows sem suporte a links simbólicos; init.sh então relata cópias que divergem. O script nunca sobrescreve um caminho existente, marca scripts como executáveis e imprime CREATED / LINKED / SKIPPED por caminho. Use --dry-run primeiro se o repositório já tiver peças de harness. Para cada caminho SKIPPED, leia o arquivo existente e mescle as ideias ausentes manualmente, em vez de forçar o modelo.

Se o script relatar caminhos FAILED, o sandbox do seu agente provavelmente protege uma pasta como .agents/ ou .claude/ (o Codex faz isso com .agents/ por padrão). Reexecute o mesmo comando com a permissão que seu ambiente oferece, ou peça ao usuário para executá-lo. Nunca realoque os skills para outra pasta para contornar isso: os agentes descobrem skills apenas nas pastas que leem, então skills realocados param silenciosamente de funcionar.

6. Preencher as especificidades do projeto

Tudo o que o scaffold não pode saber é por sua conta escrever, com base no que você leu nas etapas 2-4:

  1. harness/config.sh: um comando por linha para cada camada (setup, estática, teste, smoke, e2e), o branch base e os padrões de debug para a stack. Deixe uma camada vazia apenas se ela realmente não existir; verify.sh relata camadas obrigatórias vazias como UNVERIFIED em vez de aprovadas. Nunca preencha uma camada com um comando que outra camada já executa (por exemplo, os testes de integração como "e2e"): cada camada deve adicionar evidências que as outras não fornecem. Veja references/discovery.md.
  2. harness/architecture-rules.json: uma regra por limite, seguindo references/architecture-rules.md. Cada regra precisa de why e fix escritos para um agente, porque a mensagem de erro é o ciclo de feedback.
  3. Documentação: crie docs/ARCHITECTURE.md, docs/PRODUCT.md, docs/RELIABILITY.md apenas quando o repositório não tiver equivalente, começando de assets/docs-skeletons/. Escreva a partir do código que você leu, mantenha cada um com cerca de ~150 linhas e marque qualquer coisa que você não pôde confirmar como TODO(confirm): ... em vez de adivinhar. Se equivalentes existirem em outro lugar, link para eles em vez de duplicar.
  4. Registros de decisão: o scaffold adiciona docs/decisions/. Se o repositório já mantiver ADRs em outro lugar (doc/adr/, docs/adr/), remova a nova pasta e aponte harness/README.md, os skills de handoff e cleanup, e os modelos para o existente.
  5. harness/quality-document.md: liste os módulos reais com uma nota inicial honesta, ou unknown onde você não tiver evidências. Nunca avalie por intuição.

7. Configurar o arquivo de entrada

Insira a seção de assets/snippets/entry-section.md no arquivo de entrada, perto do topo ou do final (os modelos lembram melhor das bordas de arquivos longos do que do meio). Mantenha o arquivo de entrada como um roteador: se ele crescer além de ~200 linhas, mova os detalhes para docs/ e link para eles.

AGENTS.md é o arquivo de entrada canônico: a maioria dos agentes de codificação o lê diretamente. Outros agentes recebem um ponteiro fino para ele, nunca uma segunda cópia das regras, para que os arquivos não possam divergir.

SituaçãoFaça isso
Nem AGENTS.md nem CLAUDE.md existemCrie AGENTS.md a partir do que você aprendeu, mais a seção.
Apenas AGENTS.md existeAdicione a seção a AGENTS.md.
Apenas CLAUDE.md existe, a equipe usa apenas Claude CodeAdicione a seção a CLAUDE.md.
Apenas CLAUDE.md existe, a equipe usa outros agentes tambémPergunte antes de movê-lo: proponha mover seu conteúdo para AGENTS.md e deixar @AGENTS.md em CLAUDE.md. Se a equipe recusar, adicione a seção a CLAUDE.md e crie AGENTS.md com a seção e um link para CLAUDE.md.
Ambos existemAdicione a seção a AGENTS.md, e certifique-se de que CLAUDE.md o importe com @AGENTS.md.

Em seguida, adicione o ponteiro para cada agente que a equipe usa e que não lê AGENTS.md por padrão:

AgentePonteiro
Claude CodeCLAUDE.md contendo @AGENTS.md. Por padrão, o Claude Code lê AGENTS.md apenas quando não existe nenhum CLAUDE.md ou CLAUDE.local.md, então um repositório com ambos descarta silenciosamente o AGENTS.md sem a importação.
Gemini CLIGEMINI.md contendo @AGENTS.md, ou "contextFileName": "AGENTS.md" em .gemini/settings.json.
Qualquer agente com seu próprio arquivo de regras já no repositório (.github/copilot-instructions.md, .cursor/rules/, .windsurfrules)Uma linha nesse arquivo dizendo para ler AGENTS.md, que contém as regras.

Verifique o comportamento atual de um agente sobre o qual você não tem certeza em sua própria documentação, em vez de adivinhar; os agentes mudam quais arquivos leem.

8. Mesclar a configuração

  • .gitignore: acrescente as linhas de assets/snippets/gitignore.txt que estiverem faltando.
  • Apenas Claude Code, .claude/settings.json: mescle os hooks de assets/adapters/claude-code/settings-hooks.json. Leia o arquivo existente, acrescente aos arrays existentes hooks.SessionStart / hooks.PreToolUse em vez de substituí-los, e mantenha o JSON válido. Se a equipe recusou os hooks, pule isso e exclua o .claude/hooks/ que o adaptador copiou. O harness não depende de hooks: feature.py sela o estado da tarefa e se recusa a funcionar após uma edição manual, e o arquivo de entrada diz a todos os agentes para executar init.sh no início da sessão.
  • Apenas Claude Code, .worktreeinclude: se o projeto precisar de arquivos gitignorados, como .env, para executar, liste-os para que cada worktree que o Claude Code criar receba uma cópia. Para git worktree add simples, mencione esses arquivos em harness/README.md para que as pessoas os copiem.

9. Provar uma vez

Execute bash scripts/harness/init.sh e python3 scripts/harness/check_architecture.py e relate o resultado real. Se algo falhar por causa do projeto (não do harness), diga isso claramente e deixe como a primeira entrada no relatório; não afrouxe uma regra nem exclua um comando para torná-lo verde. Em seguida, faça o teste de sessão nova de references/principles.md: responda às cinco perguntas usando apenas os arquivos e corrija qualquer uma que você não conseguir responder.

10. Relatar

Diga ao usuário, resumidamente:

  • O que foi criado, o que foi mesclado e o que foi ignorado porque já existia
  • Os comandos por camada e de onde cada um veio
  • Cada TODO(confirm) e cada suposição que você fez
  • O resultado da inicialização/verificação, incluindo falhas
  • Se este skill em si foi instalado no repositório (.agents/skills/harness-bootstrap/ ou outra pasta de skills do agente, mais skills-lock.json), informe: a equipe não precisa dele após o bootstrap, e ele pode ser removido ou mantido para ser executado novamente mais tarde. Não o remova você mesmo.
  • Próximo passo: revisar e commitar o bootstrap em um branch, depois iniciar uma tarefa com o skill harness-start (em agentes com comandos de barra, /harness-start <TASK-ID>)

Não commit nem faça push a menos que o usuário peça.

Regras de design para adaptar o scaffold

  • Prefira as ferramentas existentes do projeto. Se o repositório tiver um Makefile com make check, coloque make check em config.sh em vez de listar novamente suas partes.
  • Mantenha as dependências de tempo de execução em bash, git e python3 (apenas biblioteca padrão). Não adicione pacotes ao projeto para o harness.
  • Mensagens de erro de qualquer script do harness dizem o que falhou, por que e como corrigir.
  • Nada destrutivo nos scripts. Cleanup apenas relata; humanos ou agentes agem com base no relatório.
  • Torne o harness menor quando puder. Um componente que não altera o comportamento do agente neste repositório é overhead; diga isso em vez de instalá-lo por completeza.

Habilidades Relacionadas