parkjangwon/make-harness

O que make-harness faz?

Use esta habilidade quando o usuário quiser configurar, auditar, atualizar ou reparar um harness local de projeto no repositório atual.

Esta habilidade é o ponto de entrada de inicialização e manutenção. O contrato real do projeto deve residir nos arquivos locais do projeto-alvo, não na habilidade em si.

O que esta habilidade gerencia

Criar, atualizar ou reparar estes arquivos locais do projeto:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• PROJECT_HARNESS.md
• harness-contract.json
• harness-runtime.json

Os modelos de origem estão em assets/templates. Use tools/apply-harness.py para regenerar deterministicamente os arquivos de projeção a partir do par contrato/runtime. Use tools/check-harness-done.py como o gate de conclusão antes de tratar um harness como finalizado. Use tools/check-sensitive-change.py quando CI, hooks ou revisores precisarem de uma verificação determinística e leve baseada em caminhos para saber se o diff atual toca em áreas sensíveis.

Comportamento principal

1. Inspecione primeiro o repositório atual e quaisquer arquivos de harness existentes.
2. Trate /make-harness como um único comando de entrada: bootstrap quando nenhum harness existir, update quando um harness saudável já existir e repair quando houver deriva ou quebra detectada.
3. Mantenha o contrato durável do projeto em PROJECT_HARNESS.md e harness-contract.json.
4. Mantenha o progresso da entrevista, metadados de sincronização e dicas de detecção de idioma apenas em harness-runtime.json.
5. Se o harness estiver incompleto ou sem defaults duráveis, inicie uma entrevista curta antes de tratar qualquer default como final.
6. Execute a entrevista interativamente, uma pergunta de cada vez.
7. Detecte o idioma provável de colaboração a partir de sinais do repositório primeiro; confirme-o quando não estiver claro, em vez de forçar uma abertura em inglês primeiro.
8. Após cada resposta, reflita o progresso do runtime em harness-runtime.json e as respostas duráveis em harness-contract.json.
9. Confirme apenas defaults duráveis do projeto, guardrails de segurança locais do projeto e guardrails de execução.
10. Registre a intenção mínima de aplicação em rule_strengths para que o contrato possa distinguir regras consultivas, guiadas e aplicadas.
11. Mantenha AGENTS.md, CLAUDE.md e GEMINI.md enxutos. Coloque o contrato durável em PROJECT_HARNESS.md e mantenha os arquivos de entrada como ponteiros e regras resumidas.
12. Valide que os arquivos de harness gerenciados concordam com o contrato confirmado. Se for detectada deriva, repare-a antes de finalizar.
13. Execute o gate de conclusão antes de declarar sucesso: a auditoria deve passar, o estado do runtime deve estar saudável, os campos compartilhados validados devem estar completos e as projeções determinísticas devem corresponder aos arquivos versionados.
14. Quando o diff atual tocar em áreas sensíveis, use a verificação de guardrail leve baseada em caminhos para que CI/hooks possam falhar deterministicamente quando guardrails aplicados forem acionados.
15. Para integração com hooks, prefira verificações de arquivos staged em vez de palpites HEAD~1..HEAD, use MAKE_HARNESS_HOOK_MODE em vez de resquícios de nomenclatura entre projetos e permita um pequeno modo de alternância strict / warn / off em vez de um único comportamento codificado.
16. Registre uma entrada de histórico de alterações concisa sempre que o contrato durável do projeto mudar.
17. Não armazene tipos de trabalho por requisição, como bugfix, feature, maintenance ou refactor, como estado permanente do harness.
18. Não armazene preferências de orquestração de framework como estado permanente do harness.

Classificação de execução

Leia harness-contract.json e harness-runtime.json se existirem.

• Se nenhum harness existir, faça bootstrap.
• Se o harness existir e estiver saudável, entre no modo de atualização.
• Se o harness existir mas estiver divergente ou quebrado, repare primeiro e só continue com atualização se necessário.
• Se bootstrap_status for pending_interview, o harness ainda não está configurado.
• Se bootstrap_status for interview_in_progress, retome a partir do estado do runtime registrado.

Fluxo de entrevista interativa

• Faça exatamente uma pergunta de cada vez.
• Este é um fluxo de configuração única, portanto a precisão é mais importante que minimizar a quantidade de perguntas.
• Para um repositório existente, use o comportamento de entrevista primeiro-repositório: inspecione e infira primeiro, depois confirme apenas o que ainda não estiver claro.
• Para um projeto em branco, mude para o comportamento de entrevista de descoberta de configuração: faça apenas o pequeno conjunto de perguntas iniciais necessárias para escolher stack, runtime, gerenciador de pacotes e comandos principais.
• Siga a ordem fixa de perguntas de references/interview-protocol.md.
• Prefira perguntas de confirmação em vez de perguntas abertas sempre que o repositório já fornecer uma resposta provável.
• Prefira inspecionar o repositório em vez de perguntar por metadados que geralmente são inferíveis.
• Use a seleção de idioma detecte-primeiro:
  • procure pelo idioma do README, documentação raiz existente, comentários e padrões de nomenclatura de arquivos
  • se um idioma for fortemente implícito, comece por ele com um tom de confirmação
  • se os sinais forem fracos ou mistos, faça a pergunta do idioma em inglês simples
• Respeite o orçamento de perguntas da entrevista do protocolo:
  • alvo de 5 ou menos perguntas explícitas para repositórios comuns
  • trate 8 como um teto flexível que exige justificativa
• Normalize respostas simples do usuário em valores armazenados canônicos antes de escrever o estado.
• Use as tabelas de normalização canônicas em references/interview-protocol.md para project_type, change_posture, approval_policy, verification_policy e communication_tone.
• Use os modelos de perguntas voltados ao usuário de references/interview-protocol.md em vez de expor nomes internos de esquema diretamente.
• Escolha a redação da matriz de modelos de três níveis do protocolo com base na confiança (alta, média, baixa).
• Quando a entrevista for em inglês, use os modelos complementares em inglês do protocolo em vez de traduções ad-hoc.
• Adapte por resposta, não por rótulo de pessoa: alterne entre modo de precisão, modo de esclarecimento e modo de default seguro com base no padrão de resposta real do usuário.
• Mantenha pending_fields e confirmed_fields normalizados como conjuntos não sobrepostos.
• Trate palpites derivados do repositório como inferência temporária até que sejam confirmados.
• Se bootstrap_status for interview_in_progress, retome a partir do interview_step registrado em vez de reiniciar.
• Se uma nova resposta do usuário criar uma contradição com o estado durável ou sinais fortes do repositório, confirme antes de sobrescrever o contrato.
• Apenas defina bootstrap_status como configured quando todos os defaults duráveis necessários estiverem confirmados.

Arquivos de saída

Após bootstrap, atualização ou reparo, o projeto-alvo deve ter:

• um AGENTS.md enxuto
• um CLAUDE.md enxuto
• um GEMINI.md enxuto
• um PROJECT_HARNESS.md legível por humanos
• um harness-contract.json durável legível por máquina
• um harness-runtime.json volátil legível por máquina

Recursos

• Modelos: assets/templates
• Coexistência: docs/coexistence.md
• Guia de entrevista: references/interview-guide.md
• Protocolo de entrevista: references/interview-protocol.md
• Guia de reparo e validação: references/repair-validation-guide.md
• Fixtures de validação: assets/fixtures
• Planejador de entrevista: tools/interview_planner.py — auxiliar determinístico que fixa descoberta de projeto em branco, confirmação primeiro-repositório, ordem de retomada e adaptação de modo de resposta em testes e fixtures
• Playbook de reparo: assets/repair-playbook.md
• Checklist de saúde: assets/healthy-checklist.md
• Exemplo de saída: assets/examples
• Ferramenta de auditoria local: tools/audit-harness.py — verifica arquivos gerenciados, estrutura de PROJECT_HARNESS.md, espessura dos arquivos de entrada e invariantes do runtime
• Gerador de projeção determinística: tools/apply-harness.py — regenera PROJECT_HARNESS.md, AGENTS.md, CLAUDE.md e GEMINI.md a partir dos arquivos canônicos de contrato/runtime
• Gate de conclusão: tools/check-harness-done.py — exige sucesso na auditoria, estado saudável do runtime, campos compartilhados totalmente validados e deriva de projeção zero antes de tratar o harness como concluído
• Verificador de guardrail sensível a diffs: tools/check-sensitive-change.py — verificação leve baseada em caminhos para diffs que tocam em autenticação / permissões / segredos / pagamentos / criptografia / API pública; bloqueia apenas quando as forças de regra relevantes estiverem aplicadas
• Posicionamento: docs/positioning.md
• Contribuição: CONTRIBUTING.md
• Metadados opcionais de UI: agents/openai.yaml, agents/gemini.yaml