hanzhangzzz/agent-skills-zh

/harness

Mínima prática de Engenharia de Arnês (Harness Engineering). Use três restrições (Inspector, Worker, Reviewer) para manter a criatividade da IA nos trilhos certos, impulsionando a melhoria contínua por meio de um quadro compartilhado TODO.md. Inspirado na metodologia Harness Engineering: com uma estrutura de processo leve, mas determinística, transforme o agente de IA de 'livre arbítrio' em 'entrega previsível de resultados de alta qualidade'.

Condições de Ativação

Execução Imediata

• Usuário digita /harness — ciclo completo (Inspector + Worker + Reviewer)
• Usuário digita /harness inspect — apenas Inspector
• Usuário digita /harness work — apenas Worker + Reviewer (uma vez)
• Usuário digita /harness loop — executa Worker + Reviewer continuamente até não haver tarefas pendentes

O usuário pode incluir instruções em linguagem natural após o comando, como contexto extra para o ciclo atual. Por exemplo:

• /harness Esta rodada deve focar em perda silenciosa de dados
• /harness work Corrija primeiro a detecção de variáveis de ambiente P0
• /harness inspect Apenas recalibre os objetivos do esqueleto, não execute o Worker

Agendamento (Cron)

Use as ferramentas internas CronCreate/CronDelete/CronList do Claude Code, com isolamento natural de sessão—crons de sessões diferentes não interferem entre si.

Comando	Descrição
/harness cron "*/30 * * * *"	Executa ciclo completo a cada 30 minutos
/harness cron "*/30 * * * *" inspect	Executa apenas Inspector a cada 30 minutos
/harness cron "0 */2 * * *" work	Executa Worker+Reviewer a cada 2 horas
/harness cron "*/15 * * * *" loop	Consome tarefas continuamente a cada 15 minutos
/harness cron list	Lista todos os crons harness da sessão atual
/harness cron stop <job_id>	Remove um cron específico
/harness cron stop	Remove todos os crons harness da sessão atual (confirmação interativa antes de deletar um a um)

Limitações:

• O cron job só funciona enquanto a sessão atual do Claude Code estiver ativa; fecha o terminal, perde o efeito.
• Jobs recorrentes expiram automaticamente após 7 dias.
• Só é acionado quando o REPL está ocioso, não interrompe conversas em andamento.

Protocolo de Três Papéis

Princípio Central: Verificar a Saída

Cada função deve verificar sua própria saída, não apenas 'terminar' e passar adiante.

• Inspector: Após criar uma tarefa, verifique se a descrição é clara o suficiente e se a dica (hint) é acionável.
• Worker: Após modificar o código, execute as verificações definidas na documentação do projeto (AGENTS.md, CLAUDE.md, TODO.md, README, etc.). Se o projeto define validações de ponta a ponta ou de fluxo real, execute-as e registre os resultados.
• Reviewer: Durante a revisão, confirme se o Worker executou os comandos de verificação relacionados à alteração. Se o projeto define validações de ponta a ponta ou de fluxo real e a alteração afeta esse caminho, o revisor deve rejeitar ou solicitar verificação complementar se o Worker não a executou.

Verificação ponta a ponta não é opcional. Se o projeto não tem uma validação E2E/fluxo real específica, ou se é impossível executá-la devido à indisponibilidade de dependências externas, o motivo deve ser registrado explicitamente.

Inspector (Planejador)         — Decide direção, descobre tarefas
  ↓ Escreve em TODO.md
TODO.md (Quadro Compartilhado)
  ↓
Worker (Corretor)              — Pega tarefa, modifica código
  [Aguardando] → [Em Andamento] → [Aguardando Revisão]
  ↓
Reviewer (Revisor)             — Revisa código, decide se aprova ou rejeita conforme regras do projeto
  Aprovado → Done Log + (apenas se permitido) git commit
  Rejeitado → [Rejeitado] + instruções de correção
  ↓
Worker pega novamente [Rejeitado]...

Máquina de Estados da Tarefa

Marcador	Significado	Quem pode alterar
[Aguardando]	Não foi pega	Inspector pode adicionar/modificar, Worker pode pegar
[Em Andamento]	Worker está executando	Worker define ao pegar, outros não mexem
[Aguardando Revisão]	Worker terminou	Worker define ao terminar, Reviewer revisa
[Rejeitado]	Reviewer rejeitou	Reviewer define ao rejeitar, Worker pode pegar novamente

Passos de Execução

Passo 1 — Interpretar o Comando do Usuário

Extrair do input do usuário:

1. Modo cron: Se o input contém a palavra-chave cron
2. Modo: cron / inspect / work / loop / full (padrão)
3. Contexto extra: O texto em linguagem natural após o comando (se houver)

Se for modo cron, vá para o Passo 5. Caso contrário, continue para o Passo 2.

Salvar o contexto extra em um arquivo temporário:

echo "Instrução extra do usuário: <linguagem natural do input>" > /tmp/harness-context.txt
#   Ciclo de vida: no modo full, tanto o Inspector quanto o Worker+Reviewer lerão;
#   o arquivo é deletado apenas ao final da submissão real do worker-reviewer (se não houver tarefas, mantém-se)

Se não houver contexto extra, crie um arquivo vazio (o subprocesso detecta vazio e não injeta).

Passo 2 — Confirmar Ambiente do Projeto

# Confirmar que está na raiz do projeto
test -f TODO.md || echo "NOT_HARNESS_PROJECT"
# Confirmar que os scripts existem (relativos ao diretório do skill)
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"

Se o ambiente estiver incorreto, pare e informe o usuário.

Exemplo de execução:

cd <projeto> && bash ~/.codex/skills/harness/inspector.sh
cd <projeto> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh

Se TODO.md não existir, crie um modelo mínimo:

# Quadro de Melhoria do Projeto

## Fase Atual: Inicialização

## Metas
- [ ] A serem preenchidas após a primeira inspeção do Inspector

## Registro de Concluídos

Passo 3 — Executar de Acordo com o Modo

Modo: inspect

cd <diretório do projeto> && bash <diretório do skill>/inspector.sh

Modo: work

cd <diretório do projeto> && bash <diretório do skill>/worker-reviewer.sh

Modo: loop

cd <diretório do projeto> && bash <diretório do skill>/worker-reviewer.sh --loop

Modo: full (padrão)

# Fase 1: Inspeção do Inspector
cd <diretório do projeto> && bash <diretório do skill>/inspector.sh

# Fase 2: Ciclo Worker+Reviewer
cd <diretório do projeto> && bash <diretório do skill>/worker-reviewer.sh --loop

Passo 4 — Reportar Resultados

Após a conclusão, reporte ao usuário:

Ciclo Harness concluído

Inspector:
  - Meta atual: ...
  - Julgamento de arquitetura: ...
  - Tarefas adicionadas/ajustadas: N

Worker+Reviewer:
  - Tarefas concluídas: N
  - Tarefas rejeitadas: N
  - Restantes Aguardando: N

Próximo ciclo: digite /harness para continuar

Passo 5 — Modo Cron (usando CronCreate/CronDelete/CronList integrados)

5.1 Criar tarefa agendada: /harness cron "<expressão cron>" [modo]

1. Interpretar a expressão cron e o modo opcional (inspect / work / loop / full)
2. Construir o conteúdo do prompt com base no modo:
   • full: "Executar ciclo completo do harness. Execute sequencialmente: 1. cd <caminho do projeto> && bash <caminho do skill>/inspector.sh 2. bash <caminho do skill>/worker-reviewer.sh --loop. Relatar resultados após a conclusão."
   • inspect: "Executar inspeção do harness. Execute cd <caminho do projeto> && bash <caminho do skill>/inspector.sh. Relatar resultados após a conclusão."
   • work: "Executar trabalho do harness. Execute cd <caminho do projeto> && bash <caminho do skill>/worker-reviewer.sh. Relatar resultados após a conclusão."
   • loop: "Executar loop do harness. Execute cd <caminho do projeto> && bash <caminho do skill>/worker-reviewer.sh --loop. Relatar resultados após a conclusão."
3. Chamar CronCreate, com parâmetros:
   • cron: expressão cron fornecida pelo usuário
   • prompt: o prompt construído acima
   • recurring: true
4. Confirmar ao usuário a criação bem-sucedida, retornando o job_id

5.2 Listar tarefas agendadas: /harness cron list

1. Chamar CronList para obter todos os jobs cron da sessão atual
2. Filtrar jobs cujo prompt contenha a palavra-chave "harness"
3. Exibir em formato de tabela: job_id | expressão cron | modo | data de criação (se disponível)
4. Se não houver crons harness, indicar "Nenhuma tarefa cron harness nesta sessão"

5.3 Deletar tarefa agendada: /harness cron stop [job_id]

• Com job_id: Chamar CronDelete para deletar o job especificado, confirmar sucesso
• Sem job_id:
  1. Chamar CronList, filtrar jobs relacionados ao harness
  2. Mostrar ao usuário todos os jobs que serão deletados
  3. Após confirmação do usuário, chamar CronDelete para cada um, um por um
  4. Reportar o resultado da exclusão

Mecanismo de Entrada para Subprocessos

Cada subprocesso (Inspector / Worker / Reviewer) é iniciado via claude -p, e a entrada é composta por três partes:

1. Prompt da função — <diretório do skill>/prompts/inspector.md, etc.
2. Documentação do projeto — O script concatena automaticamente o conteúdo de arquivos como AGENTS.md, CLAUDE.md, README, TODO.md
3. Contexto extra do usuário — Lido de /tmp/harness-context.txt, injetado ao final do prompt

As três partes são concatenadas e passadas para claude -p, garantindo que o subprocesso tenha tanto a visão geral do projeto quanto a intenção específica do usuário nesta rodada.

Por padrão, o script considera o diretório de trabalho atual ao chamar o script (pwd -P) como o diretório do projeto. Se precisar chamar de outro local, use HARNESS_PROJECT_DIR=/abs/path/to/project para substituir explicitamente. O diretório de instalação do skill é usado apenas para localizar scripts e prompts, não é tratado como diretório do projeto.

Lista de Arquivos

Arquivo	Responsabilidade
prompts/inspector.md	Prompt da função Inspector
prompts/worker.md	Prompt da função Worker
prompts/reviewer.md	Prompt da função Reviewer
inspector.sh	Script de execução do Inspector
worker-reviewer.sh	Script de execução do Worker + Reviewer
TODO.md	Quadro de tarefas compartilhado (na raiz do projeto)