Communitygithub.com

afrizzal/ratchet

Loops de engenharia retomáveis para Claude Code — audite um código-fonte em um backlog com portões de aceitação e execute-o um commit verificado por vez.

O que é ratchet?

A habilidade Ratchet transforma o Claude Code em um executor disciplinado de backlogs, garantindo que cada mudança seja verificada e comprometida antes de passar para a próxima. Ela opera por meio de um arquivo de backlog, que é a única fonte de estado, tornando o executor sem estado e seguro para reinicialização. Em sua fase de pré-voo, valida a estrutura do backlog, exige uma árvore de trabalho limpa (com uma exceção para o estado do loop), recupera-se de falhas anteriores e estabelece uma linha de base verde executando verificações globais. A habilidade suporta backlogs de versão 1 (v1) e versão 2 (v2), onde o v2 introduz pistas para execução paralela segura, permitindo que múltiplos agentes ou sessões trabalhem no mesmo repositório sem conflitos de escrita. Itens de backlog com tags como `[USER-DECISION]` ou de alto risco (por exemplo, que tocam em autenticação, pagamentos ou migrações de banco de dados) são automaticamente estacionados para revisão humana, prevenindo erros caros. O executor também respeita um arquivo `NEXT.md` para atribuições de verificação supervisionadas ou seniores, garantindo que mudanças críticas recebam escrutínio adequado. Uma execução típica começa com `/ratchet-loop`, que pode ser direcionada por pista (`--lane`), limitada por número de itens (`--max-items`), focada em IDs específicos (`--only`) ou executada em modo de simulação (`--dry-run`) para planejamento sem efeitos colaterais. O executor se comunica claramente por meio de planos anunciados, registros diários e require paradas quando as condições não são atendidas, fornecendo ações acionáveis ​​como sugerir `recomendar` ou `auditar`.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add afrizzal/ratchet

Perguntar na sua IA favorita

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

Documentação

Loop Ratchet — o executor

Você está executando um backlog de catraca. Seu contrato é apenas movimento para frente: um item está ou feito-verificado-comprometido, ou não está feito e o Livro-Razão diz exatamente por quê. Nada no meio sobrevive à sua execução.

O arquivo de backlog é a única fonte de estado. Você é sem estado; trate cada execução como se um agente diferente tivesse feito a anterior (geralmente é verdade). Tudo que você aprende e que importa vai para o arquivo, não na sua cabeça.

Carregue as regras do executor primeiro. Leia executor-rules.md do próprio diretório desta habilidade (a pasta onde este SKILL.md vive) antes de tocar em qualquer item — 13 regras vinculativas e exatas, destiladas de execuções de campo. Quando uma regra e seu instinto discordarem, siga a regra.

Invocação

/ratchet-loop [caminho] [--lane NOME] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
  • caminho — arquivo de backlog. Padrão: ratchet/BACKLOG.md, senão BACKLOG.md na raiz do repositório. Se nenhum existir, diga isso e sugira /ratchet-audit ou /ratchet-backlog create. O caminho resolvido é o arquivo de backlog em toda parte abaixo, e seu diretório contêiner é o diretório de estado do loop (padrão ratchet/).
  • --lane NOME — apenas backlogs v2 (erro em arquivo v1): restrinja a elegibilidade a itens com Lane: NOME e escreva o estado apenas em lanes/NOME.md. Este é o modo seguro para paralelismo — veja "backlogs v2 — pistas" abaixo. --lane é um seletor de estado, não roteamento: nunca satisfaz o requisito --only da comporta de alto risco.
  • --max-items N — pare após N itens atingirem um estado terminal nesta execução.
  • --only — restrinja a elegibilidade aos IDs listados (dependências ainda respeitadas). Também o sinal de roteamento explícito que a comporta de alto risco exige — veja abaixo.
  • --verify — modo de verificação, veja "Modos de verificação" abaixo. Padrão inline.
  • --dry-run — faça apenas a Fase 0: valide, relate o plano de execução e qualquer recuperação que uma execução real faria, não escreva nem faça commit de nada.

O arquivo de estado. Em toda parte abaixo, suas escritas de livro-razão e diário vão para o arquivo de estado: no v1 esse é o próprio arquivo de backlog; no v2 é o arquivo da sua pista, lanes/<pista>.md, e o arquivo de backlog é somente leitura para você.

Fase 0 — Pré-voo (nunca pule, nunca reordene)

  1. Leia o arquivo de backlog por completo e valide sua estrutura: o marcador de versão próximo ao topo — exatamente <!-- ratchet:v1 --> ou exatamente <!-- ratchet:v2 --> (um marcador contendo :lane significa que você foi apontado para um arquivo de pista, não para um backlog — recuse e aponte para o backlog real); para v1, todas as quatro seções (## Itens, ## Livro-Razão, ## Diário, opcionalmente ## Verificações globais); para v2, ## Pistas + ## Itens (+ opcional ## Verificações globais), sem Livro-Razão/Diário no backlog, mais as verificações estruturais v2 em "backlogs v2 — pistas" abaixo; IDs correspondendo a [A-Z]+-\d+ e únicos; cada item tem uma Especificação e ≥1 critério de Aceitação; uma linha no Livro-Razão por item (v2: no arquivo da pista que seu Lane: nomeia) com um status do conjunto legal (todo / em-andamento / done / bloqueado / precisa-humano / pulado). Estruturalmente quebrado → PARE, relate os problemas exatos, sugira /ratchet-backlog validate. Nunca adivinhe em um arquivo malformado. Defeitos por item que não quebram a estrutura — evidência desatualizada, critérios inexequíveis em um item sem comporta — são tratados posteriormente estacionando aquele item, não recusando o arquivo. (Contrato completo: docs/backlog-format.md no repositório ratchet; as verificações que você precisa são as listadas aqui.)

  2. Exija uma árvore de trabalho limpa — com a exceção do estado do loop. git status não deve mostrar alterações staged ou unstaged em arquivos rastreados. Classifique qualquer sujeira que encontrar:

    • Seu próprio estado — v1: o arquivo de backlog e o diretório de estado. v2: apenas seu arquivo de pista. Não rastreado → não é sujeira do usuário; será comprometido no passo 3 (no v1, é assim que o backlog recém-escrito do curador entra no histórico). Sujo mas rastreado → estado deixado por uma execução anterior (uma falha, ou um preenchimento de sha não sincronizado); registre uma linha no diário e deixe o passo 3 comprometê-lo.
    • Apenas v2 — o que não é seu nunca é seu para limpar. BACKLOG.md é somente leitura para você, então nunca é "estado de execução anterior": sujo rastreado → uma edição humana fora da janela ou detritos de merge → PARE e relate. Não rastreado (backlog ou arquivos de pista) → a saída do curador nunca foi comprometida; isso é aceitável apenas no branch de integração, onde o passo 3 o compromete como ratchet: adicionar backlog exatamente como no v1. Em um branch de pista, estado não rastreado significa que você foi lançado antes de o backlog ser comprometido → PARE ("comprometa o backlog no branch de integração primeiro"). O arquivo de outra pista, sujo ou segurando uma linha em-andamento: uma segunda execução pode estar usando esta árvore de trabalho → PARE ("possível execução paralela ativa — dê a cada pista sua própria árvore de trabalho"). Nunca comprometa nenhum, nunca recupere nenhum. Um NEXT.md sujo ou não rastreado em uma árvore de trabalho de pista: deixe exatamente como está (nunca stage, nunca comprometa — é apenas para branch de integração) e anote no relatório.
    • Caminhos fonte sujos que pertencem a um item do Livro-Razão em-andamento são detritos de falha, tratados no passo 3 — atribua-os por meio da cauda do Diário e da Evidência/Especificação do item; se a atribuição for ambígua, PARE e pergunte.
    • Qualquer outro arquivo rastreado sujo → PARE e pergunte ao usuário (o trabalho deles não é seu para guardar). Esta invariante é o que torna sua recuperação de falha segura.
    • v2 — decida a vivacidade da sua pista agora, antes de qualquer escrita. Leia o marcador de execução da sua pista — aquela que --lane nomeia, ou no modo sequencial a primeira pista que você trabalhará (veja "backlogs v2 — pistas"). Fechada → esta é uma execução nova. Aberta, nomeando seu branch atual → detritos de falha; você continua sob o marcador existente. Aberta, nomeando um branch diferente → a pista pode estar ativa em outro lugar: PARE. Então, se esta é uma execução de pista padrão ou uma execução sequencial sem --lane, verifique as pré-condições de barreira — todas as outras pistas fechadas e mescladas — e recuse aqui se elas não forem mantidas. Toda recusa neste passo acontece antes de o passo 3 escrever qualquer coisa, então uma execução que não deve começar não deixa nenhum marcador para trás.
  3. Recupere, então comprometa a recuperação uma vez. Uma linha do Livro-Razão presa em em-andamento é detrito de uma execução que falhou — no v2, apenas linhas no seu próprio arquivo de pista; o em-andamento de outra pista pode ser uma execução paralela ativa e nunca é seu para tocar. Para cada linha: reverta exatamente os caminhos fonte atribuídos a ela no passo 2 (regra do executor 9) se algum permanecer; registre no diário encontrado em-andamento de uma execução que falhou — redefinido para todo; defina a linha de volta para todo. Este é o único movimento de status para trás que um executor pode fazer, e apenas no pré-voo. Em seguida, faça um commit cobrindo tudo que os passos 2–3 tocaram — estado da primeira execução (ratchet: adicionar backlog) ou recuperação (ratchet: recuperar estado). No v2, esse mesmo commit também carrega a linha de abertura do diário da sua pista, que depende do que o passo 2 encontrou: uma pista nova recebe - <data> execução iniciada (pista <nome>, branch <branch>); uma pista que você encontrou aberta em seu próprio branch recebe - <data> encontrada execução aberta de <data> — presumido falha, recuperando e nenhum segundo execução iniciada (o existente ainda é seu marcador de abertura de pista, e seu execução encerrada o equilibrará). Se não houver mais nada para comprometer, comprometa essa linha sozinha como ratchet(<pista>): execução aberta. No v1, se os passos 2–3 não encontraram nada, não há nada para comprometer.

  4. Leia o Livro-Razão e o Diário inteiro — no v2, isso significa o livro-razão e o diário de cada arquivo de pista, não apenas o seu (você escreve uma pista; você lê todos eles). O Diário é sua herança — tentativas anteriores, armadilhas conhecidas, hipóteses falhas. Não tente novamente algo que o Diário diz que falhou sem uma nova razão.

  5. Estabeleça a linha de base verde. Execute cada comando sob ## Verificações globais uma vez, em sua forma determinística — frio, sem cache incremental, sem depender de tipos gerados por um servidor de desenvolvimento em execução (um tsc --noEmit quente pode relatar verde enquanto a mesma verificação executada fria, como o CI a executa, é vermelha). Se uma verificação global parece sensível a cache e o backlog não a fixou, execute a forma fria você mesmo e anote a discrepância no Diário. Linha de base vermelha → PARE e relate (você não pode avançar com a catraca de um estado inicial quebrado) — a menos que um item marcado com [LINHA_DE_BASE] exista e seja seu para executar (v1: sempre; v2: seu Lane: corresponde ao seu --lane, ou nenhum --lane foi dado), caso em que esse item é sua primeira escolha obrigatória, antes da ordem do arquivo. Em uma execução v2 --lane X onde o item [LINHA_DE_BASE] pertence a outra pista, PARE e relate: "bloqueado pela linha de base por <ID> na pista <Y> — execute essa pista primeiro, mescle, então relance". Esperar é uma parada, nunca uma escrita em outra pista.

  6. Detecte a convenção de commit do repositório a partir de git log --oneline -15 (commits convencionais? frases simples? prefixos de escopo?). Você a corresponderá.

  7. Verifique o branch. Se você está no branch padrão do repositório e o repositório é baseado em PR ou push-to-deploy, proponha criar um branch de trabalho (ratchet/<escopo-ou-data>) antes do primeiro commit — /ratchet-ship abre o PR depois. Proceda no branch padrão apenas com o OK explícito do usuário. Em uma execução v2 --lane X o branch não é uma escolha: retome ratchet/X se existir, senão crie-o a partir do topo do branch de integração, e mescle o branch de integração se você estiver atrás dele — veja "backlogs v2 — pistas".

  8. Leia NEXT.md (no diretório de estado) se existir. É o plano roteado de /ratchet-recommend: honre suas atribuições de verificação por item — um item que ele roteia como SUPERVISIONADO ou SÊNIOR requer --verify fresh. Se fresh não estiver em vigor, estacione apenas os itens SUPERVISIONADOS/SÊNIORES que de outra forma seriam executados nesta execução (eles passam na elegibilidade e correspondem a --only); itens fora do escopo desta execução são deixados intocados — seus comandos de onda já carregam as bandeiras corretas. Se NEXT.md antecede a última mudança no Livro-Razão (v2: a última mudança no seu arquivo de pista), diga que está desatualizado e sugira regenerá-lo — v1: no diretório de estado, como de costume; v2: no branch de integração, nunca em uma árvore de trabalho de pista. Bandeiras explícitas do invocador substituem NEXT.md. Somente leitura no v2: você nunca escreve, stage ou compromete NEXT.md.

  9. Anuncie o plano: itens elegíveis em ordem, itens estacionados com razões, o branch, as condições de parada em vigor. Em --dry-run, pare aqui — e como uma execução a seco não escreve nada, relate os commits que os passos 2–3 teriam feito em vez de fazê-los. Uma execução a seco, portanto, nunca abre uma pista: nenhum marcador de execução iniciada é escrito ou comprometido, então não deixa nenhuma pista aberta atrás de si.

Elegibilidade

Um item é elegível quando TODOS valem: status do Livro-Razão todo · sem tag de comporta humana ([DECISÃO-USUÁRIO], [OPS], [ARISCADO]) · todo Depende: ID é done (v2: uma dependência entre pistas conta apenas como uma linha done visível em sua árvore de trabalho — feita e mesclada) · corresponde a --only se dado · corresponde a --lane se dado. Pegue itens elegíveis na ordem do arquivo. Se todo ID --only existe mas nenhum carrega o Lane: da pista invocada, isso é um erro ("SEC-01 está na pista ui — execute novamente com --lane ui ou regenere NEXT.md"), nunca um silencioso "backlog seco". Itens todo com comporta humana: defina seu status no Livro-Razão para precisa-humano com a tag como a nota (uma vez), e siga em frente. Itens estacionados permanecem estacionados até que um humano os desestacione — status de volta para todo, tag de comporta removida, decisão registrada no diário (procedimento de "Transições humanas" do formato); você nunca faz isso sozinho.

Comporta de alto risco (mecânica). Um item é de alto risco quando sua Especificação ou Evidência toca qualquer item da lista de gatilhos (literal da regra do executor 1): autenticação/permissões, limites de inquilino (companyId / escopo de propriedade), pagamentos ou matemática financeira, lançamento contábil/diário, migrações de banco de dados, segredos/ambiente, exclusão de arquivos ou linhas, ou tratamento de sessão/cookie. Um item de alto risco sem comporta é executável apenas quando ambos valem: (a) --verify fresh está em vigor, e (b) o invocador o listou explicitamente em --only — ou seja, um humano ou o roteamento NEXT.md o escolheu para esta execução. --lane nunca conta como (b). Caso contrário, estacione-o como precisa-humano (nota: "alto risco; roteie via /ratchet-recommend"). Exceção: um item [LINHA_DE_BASE] é isento do requisito --only — sua tag é o roteamento humano, e a execução não pode prosseguir sem ele — mas use verificação fresh para ele quando tocar a lista de gatilhos e fresh estiver disponível. Sem autoavaliação sobre qual modelo você é — as bandeiras decidem. Um "verde" errado em autenticação ou dinheiro é a falha mais cara que Ratchet existe para prevenir; o custo de uma olhada humana é sempre menor.

Backlogs v2 — pistas

Um backlog v2 (<!-- ratchet:v2 -->) divide o estado por pista: o backlog contém ## Pistas + ## Itens (cada item carrega Lane: <nome>), e o Livro-Razão + Diário de cada pista vivem em lanes/<pista>.md — escritor único, então agentes paralelos nunca escrevem o mesmo arquivo. Contrato completo: docs/backlog-format.md §5 no repositório ratchet; tudo que um executor precisa está abaixo.

Verificações estruturais v2 (adições ao passo 1 do pré-voo). PARE em qualquer um dos seguintes: sem ## Pistas; o Escopo da primeira pista não é literal (resto), ou uma segunda pista também reivindica (resto) (exatamente uma pista padrão); escopos de pistas nomeadas sobrepostos; um item sem Lane: ou nomeando uma pista não declarada; uma pista declarada cujo lanes/<pista>.md está faltando ou cujo marcador <!-- ratchet:v2:lane <nome> --> não corresponde ao nome do arquivo e à declaração; um item sem nenhuma linha de livro-razão em lugar nenhum, uma linha no arquivo da pista errada ou linhas duplicadas entre arquivos. Você nunca cria arquivos de pista — esse é o trabalho do curador (/ratchet-backlog). Escopo de recusa em uma execução --lane X: defeitos no backlog, em lanes/X.md ou na residência de linhas dos próprios itens de X são PARADAS; danos internos confinados ao arquivo de outra pista são um AVISO alto — relate, nunca toque.

Marcadores de execução (o sinal de vivacidade). Uma pista está aberta quando, escaneando seu diário de baixo para cima, o primeiro marcador de execução encontrado é execução iniciada. Uma execução abre a pista que está prestes a trabalhar anexando - <data> execução iniciada (pista <nome>, branch <branch>) e comprometendo-a (passo 3 do pré-voo, ou ratchet(<pista>): execução aberta) — a menos que a pista já estivesse aberta (recuperação de falha), caso em que o marcador existente permanece e nenhum novo é adicionado. Uma execução fecha sua pista anexando - <data> execução encerrada (pista <nome>, itens: N, sucesso: S, falha: F, novo: C) e comprometendo como ratchet(<pista>): execução encerrada. Execuções paralelas na mesma pista são impossíveis por construção — um marcador de execução aberta impede o segundo executor de começar. Limpeza de pista abandonada: um executor arrombador remove o marcador de execução ("pista parecia aberta, nenhuma atividade recente — resetando") e compromete como ratchet(<pista>): resetar pista abandonada; um executor normal recusa.

Entrada de pista e mesclagem. Um executor --lane sempre cria ratchet/X a partir do topo do branch de integração se o branch não existir; uma execução sequencial padrão usa o branch de integração (se for PR-based, cria um branch de trabalho). O executor mescla a integração em seu branch se estiver atrás. Ele nunca empurra — esse é o trabalho de /ratchet-ship. A mesclagem da pista de volta é externa (PR manual ou /ratchet-ship). O executor não mescla outras pistas; a integração já as contém.

Modos de verificação

  • inline (padrão): execute os critérios de Aceitação do item e registre a Evidência no Livro-Razão, tudo dentro da mesma execução. Sem chamada externa. Rápido, barato, mas o modelo pode ficar complacente com seu próprio trabalho.
  • fresh: antes de marcar como done, faça uma segunda passada independente — re-leia o Spec, re-execute os critérios do zero, e se o item é de alto risco, re-examine os arquivos tocados com foco nos pontos de gatilho. Comporte-se como um revisor separado que não viu o código sendo escrito. Marque a Evidência como verified: fresh.

O modo é definido uma vez por execução (--verify) e pode ser sobrescrito por item via NEXT.md (itens SUPERVISIONADOS/SÊNIORES). A comporta de alto risco exige fresh para execução.

Itens, Livro-Razão, Diário

Formato do item (no backlog):

### SEC-01: Breve título

**Spec:** O que este item faz.
**Evidência:** (opcional, preenchido pelo executor quando feito)
**Critérios de Aceitação:**
1. Critério um.
2. Critério dois.
**Depende:** SEC-00
**Marcação:** [LINHA_DE_BASE] (opcional)

Formato do Livro-Razão (v1: no backlog; v2: no arquivo da pista):

| ID | Status | Notas | Evidência |
|----|--------|-------|-----------|
| SEC-01 | todo | | |
| SEC-02 | done | commit abc123 | evidência: ... |
| SEC-03 | precisa-humano | [ARISCADO] precisa de revisão | |
| SEC-04 | bloqueado | esperando por SEC-02 | |

Formato do Diário (v1: no backlog sob ## Diário; v2: no arquivo da pista sob ## Diário):

- 2025-01-15 10:00 execução iniciada (pista padrão, branch ratchet/jan-15)
- 2025-01-15 10:05 SEC-01: critério 2 falhou — o campo de e-mail aceitava inválido
- 2025-01-15 10:10 SEC-01: critério 2 corrigido, feito commit abc123
- 2025-01-15 10:15 SEC-02: pulado — dependência SEC-01 não resolvida
- 2025-01-15 10:20 execução encerrada (pista padrão, itens: 3, sucesso: 1, falha: 0, novo: 0)

O diário é anexado apenas (nunca edite entradas passadas). O executor escreve entradas do diário para: abertura/fechamento da execução, transições de status do item (com razões), pulos, estacionamentos e qualquer anomalia encontrada.

Condições de parada

O executor para após:

  • O número especificado de --max-items atingiu um estado terminal (done, bloqueado, precisa-humano, pulado).
  • Nenhum item elegível restante.
  • O arquivo de backlog especificado não foi encontrado (após sugerir comandos alternativos).
  • Uma árvore de trabalho suja com alterações não atribuíveis ao estado do loop.
  • Linha de base vermelha sem item de linha de base para consertar.
  • Modo de execução a seco após anunciar o plano (Fase 0, passo 9).
  • O usuário interrompe (SIGINT).

O executor nunca para por fadiga; ele processará até que uma condição de parada seja atingida.

Notas gerais

  • Estado e persistência: O executor é sem estado. O arquivo de backlog (v1) ou arquivo de pista (v2) contém todo o estado: status do item, evidência, diário. Toda execução começa lendo o estado atual e escrevendo de volta. Falhas (crashes, reinicializações) são seguras: o executor recupera itens em-andamento e compromete a recuperação.
  • Convenção de commit: Combine o estilo do repositório (commits convencionais, linhas de assunto, etc.). Prefixo padrão: ratchet: (v1) ou ratchet(<pista>): (v2). Se o repositório usa commits convencionais, use feat(ratchet): ... ou fix(ratchet): ... conforme apropriado.
  • Respeito pelo trabalho humano: Nunca sobrescreva edições humanas em arquivos de estado. Itens estacionados (precisa-humano) nunca são tocados até que um humano os desestacione. A comporta de alto risco garante que itens críticos obtenham revisão humana ou verificação fresh.
  • Limpeza e segurança: O executor nunca remove arquivos. Ele nunca modifica arquivos fonte além de reverter alterações de itens em-andamento durante a recuperação. Ele nunca faz push para remoto — aquele é o trabalho do comando separado /ratchet-ship.

Resumo de comandos

  • /ratchet-loop — Executa o backlog (esta habilidade).
  • /ratchet-audit — Audita a base de código em um backlog.
  • /ratchet-backlog — Cria ou valida um arquivo de backlog.
  • /ratchet-ship — Abre um PR ou mescla mudanças (separado).
  • /ratchet-recommend — Gera NEXT.md com roteamento de verificação.

Habilidades Relacionadas