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
| Camada | Onde | Comitado? | Propósito |
|---|---|---|---|
| Arquivo de entrada | CLAUDE.md e/ou AGENTS.md | sim | Mapa resumido: o quê, como executar, como verificar, regras rígidas, links |
| Documentação | docs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/ | sim | Conhecimento que o agente não pode inferir do código |
| Contrato | harness/ (config, regras, checklist, rubrica, documento de qualidade, modelos, README) | sim | Mesmas regras para todos, alteradas apenas por PR |
| Verificação | scripts/harness/ | sim | init.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh |
| Ciclo de vida | .agents/skills/harness-*, espelhado para agentes que leem outra pasta | sim | Iniciar, passar adiante, limpar, avaliar |
| Adaptadores | Por agente, por exemplo .claude/agents/, .claude/hooks/ para Claude Code | sim | Extras opcionais: subagente, hooks |
| Estado da tarefa | .harness/tasks/<TASK-ID>/ | não | Lista 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 importardb/?") - 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:
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.shrelata 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. Vejareferences/discovery.md.harness/architecture-rules.json: uma regra por limite, seguindoreferences/architecture-rules.md. Cada regra precisa dewhyefixescritos para um agente, porque a mensagem de erro é o ciclo de feedback.- Documentação: crie
docs/ARCHITECTURE.md,docs/PRODUCT.md,docs/RELIABILITY.mdapenas quando o repositório não tiver equivalente, começando deassets/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 comoTODO(confirm): ...em vez de adivinhar. Se equivalentes existirem em outro lugar, link para eles em vez de duplicar. - 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 aponteharness/README.md, os skills de handoff e cleanup, e os modelos para o existente. harness/quality-document.md: liste os módulos reais com uma nota inicial honesta, ouunknownonde 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ção | Faça isso |
|---|---|
Nem AGENTS.md nem CLAUDE.md existem | Crie AGENTS.md a partir do que você aprendeu, mais a seção. |
Apenas AGENTS.md existe | Adicione a seção a AGENTS.md. |
Apenas CLAUDE.md existe, a equipe usa apenas Claude Code | Adicione a seção a CLAUDE.md. |
Apenas CLAUDE.md existe, a equipe usa outros agentes também | Pergunte 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 existem | Adicione 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:
| Agente | Ponteiro |
|---|---|
| Claude Code | CLAUDE.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 CLI | GEMINI.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 deassets/snippets/gitignore.txtque estiverem faltando.- Apenas Claude Code,
.claude/settings.json: mescle os hooks deassets/adapters/claude-code/settings-hooks.json. Leia o arquivo existente, acrescente aos arrays existenteshooks.SessionStart/hooks.PreToolUseem 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.pysela 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 executarinit.shno 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. Paragit worktree addsimples, mencione esses arquivos emharness/README.mdpara 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, maisskills-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
Makefilecommake check, coloquemake checkemconfig.shem vez de listar novamente suas partes. - Mantenha as dependências de tempo de execução em
bash,gitepython3(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.