kkh2114/claude-skills-public

Harness Designer v4

Princípio: "Dê um mapa ao agente, não um manual de 1000 páginas." — OpenAI Harness Engineering Princípio: "Não deixe o gerador avaliar seu próprio trabalho." — Anthropic GAN-Inspired Harness

Os 5 Pilares do Design de Harness

Todo workspace gerado por este skill deve atender aos seguintes 5 pilares:

Pilar	Pergunta Central	Princípio
Progressive Disclosure	O agente consegue ver apenas o necessário?	Sumário (~100 linhas) → Ponteiro → Documento detalhado
Mechanical Enforcement	As regras são aplicadas mecanicamente?	Apenas documentar não mantém a consistência
Feedback Loop	Em caso de falha, é possível uma melhoria estrutural?	Não "se esforce mais", mas "qual capacidade está faltando"
Session Continuity	O handoff entre sessões é limpo?	progress + feature-status + git
Entropy Management	A estrutura se mantém ao longo do tempo?	Limpeza periódica, verificação de frescor dos documentos

---

Relação das Duas Camadas

┌─────────────────────────────────────────────────────┐
│  CAMADA 1: Meta (papel deste skill)                   │
│                                                     │
│  Planner ──→ Generator ──→ Evaluator                │
│     ↑         (sequencial unidirecional, sem referência reversa)  │
│     └──── Feedback se insuficiente ──────────────────┘    │
│                                                     │
│  Propósito: Projetar, gerar e validar a estrutura do workspace│
└─────────────────────────┬───────────────────────────┘
                          │ Estrutura concluída após aprovação
                          ▼
┌─────────────────────────────────────────────────────┐
│  CAMADA 2: Operacional (papel do workspace concluído)    │
│                                                     │
│  ┌ Initializer (somente na primeira execução) → Configuração de ambiente │
│  │                                                  │
│  └ Operating Agent (execução repetida):                      │
│    Agent-A ─┐                                       │
│    Agent-B ─┼──→ Chairman Síntese ──→ Produto final       │
│    Agent-C ─┘  (paralelo independente, sem interação entre si)            │
│                                                     │
│  Propósito: Executar tarefas reais (análise, tomada de decisão, relatórios, etc.)        │
└─────────────────────────────────────────────────────┘

---

CAMADA 1: Meta — Processo de Design de Harness

3 Agentes L1 (Sequencial Unidirecional, Sem Referência Reversa)

O produto é passado na ordem Planner → Generator → Evaluator. Cada agente recebe apenas o produto da etapa anterior e não vê o resultado da próxima etapa.

Planner (Agente de Planejamento)

Analisa a intenção do usuário e projeta a estrutura do harness.

• Input: Requisitos do usuário (coletados por meio de perguntas)
• Output: Proposta de composição de agentes + esboço da estrutura de pastas + proposta de critérios de avaliação
• Restrição: Projeta antes de ver os resultados do Generator e do Evaluator

Generator (Agente de Construção)

Transforma o plano do Planner em arquivos reais.

• Input: Plano aprovado pelo Planner
• Output: Arquivos .md/.json reais (lista completa de produtos na Fase 2)
• Restrição: Constrói sem ver antecipadamente os critérios do Evaluator

Evaluator (Agente de Avaliação)

Valida de forma independente os produtos do Generator.

• Input: Arquivos gerados pelo Generator + critérios de avaliação do Planner
• Output: Pontuação baseada nos 5 pilares + resultados de validação funcional + feedback de melhoria
• Restrição: Analisa apenas o resultado final, sem considerar a intenção do Generator

---

L1 Fase 0: Pattern Match — Referência harness-100 (Novo v4.1)

"99% de um bom design já foi feito por alguém. Encontre e adapte."

Antes de entrar no Discovery, encontre o exemplar mais semelhante entre os exemplares validados do harness-100 (https://github.com/revfactory/harness-100, Apache-2.0) e use-o como referência. Para não desenvolvedores, oriente a mudar para o skill harness-starter-workspace.

Exemplares Alvo (73 Domínios de Workspace)

• Content #01–15, Business #43–55, Education #56–65, Legal #66–72, Lifestyle #73–80, Docs #81–88, Operations #89–95, Specialized #96–100

Procedimento da Fase 0

1. Extraia palavras-chave de domínio da solicitação de 1 a 2 frases do usuário
2. Apresente os 3 principais candidatos dentre os 73 acima + confirmação do usuário
3. Registre o número do exemplar selecionado no campo reference_exemplar em _workspace/00_input.md
4. Similaridade de correspondência < 0,5 → Fallback para modo de design livre (prossiga para a Fase 1 existente)

Reflita o Resultado da Fase 0 nas Etapas Seguintes

• Planner: Use a composição de 4 a 5 especialistas + Revisor do exemplar como base
• Generator: Estrutura esqueleto do exemplar, imponha a convenção de numeração _workspace/NN_*.md
• Evaluator: Use os 8 Quality Standards do exemplar (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) como rubrica

Pattern Fidelity (Avaliação Qualitativa, Apenas na Fase 0)

Não está incluído na pontuação automática dos 5 pilares. Avalie qualitativamente ao corresponder ao exemplar na Fase 0.

Verifique os 8 Quality Standards do exemplar harness-100 selecionado na Fase 0 (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries) separadamente da pontuação do Evaluator.

• Momento de aplicação: 1 vez na Fase 0 (seleção do exemplar), 1 vez ao relatar após PASS do Evaluator
• Sem pontuação: Não incluído na pontuação dos 22 itens dos 5 pilares
• pillar-weight: Apenas o ajuste de peso dos 5 pilares é possível. Pattern Fidelity não é alvo de peso.

Revisor Obrigatório

A camada operacional deve incluir um agente Revisor (função de validação cruzada). Adicione uma etapa de validação cruzada do Revisor ao modelo de síntese do Chairman existente.

Trigger Boundaries (should + NOT)

O Planner/Generator deve incluir uma seção should-NOT trigger no skill.md do orquestrador gerado.

Injeção de Frameworks de Domínio

Injete automaticamente frameworks validados por categoria:

• Content: AIDA, Pattern Interrupt, CURVE formula
• Business: BMC, TAM/SAM/SOM, Porter's 5 Forces, RICE, Van Westendorp PSM
• Education: Bloom's Taxonomy, ADDIE, CEFR, SM-2, Toulmin Model
• Legal: IRAC, MQM, GDPR/PIPA, IPC/CPC
• Lifestyle: BMR/TDEE, ACSM Guidelines, Compound Interest
• Docs: Diataxis, PREP, STAR, MADR, SemVer
• Operations: SIPOC/RACI, 4C Framework, SMART, NPS/CSAT, BARS
• Specialized: GHG Protocol, Cap Rate/IRR, IMRaD, Georgia-Pacific, Double Materiality

---

L1 Fase 1: Discovery — Operação do Planner

O Discovery consiste em 4 etapas de perguntas. Proceda cada etapa em ordem, com perguntas de acompanhamento ramificando com base nas respostas do usuário. Aguarde a resposta de uma etapa antes de passar para a próxima. Não pergunte tudo de uma vez.

1-1. Stage 1 — Propósito e Contexto (POR QUÊ / QUEM)

Entenda o motivo da existência deste workspace, não a estrutura.

P1. Qual é o problema que este workspace pretende resolver?
    (Que decisão/análise/julgamento não está funcionando bem atualmente?)

P2. Quem o utiliza?
    (Apenas agentes / Agentes + Humanos / Humanos consomem o resultado)
    → Acompanhamento: Qual é o nível de especialização no domínio do usuário?

P3. Qual é o critério de sucesso para este workspace?
    (Que resultado indicaria que foi "bem construído"?)

P4. Existe um processo existente semelhante?
    (É uma substituição / É algo novo)
    → Acompanhamento [Substituição]: Qual é o maior problema do processo existente?
    → Acompanhamento [Novo]: Existe algum sistema de referência?

Ramificação de perguntas de acompanhamento:

• P2 "Humanos consomem o resultado" → "Qual é o cargo/função da pessoa que recebe o resultado? Que formato eles preferem?"
• P3 Resposta vaga → "Especificamente, que produto final indicaria sucesso?"

1-2. Stage 2 — Produtos e Estrutura (O QUÊ)

O que está sendo criado, quais perspectivas são necessárias.

S1. Qual é o produto final?
    (Relatório / Registro de decisão / Relatório de análise / Proposta)

S2. Qual é o padrão de trabalho principal que se repete?
    (Input → Análise → Decisão → Registro → Acúmulo de conhecimento)

S3. Quantas perspectivas/papéis são necessários? Qual é a natureza de cada um?
    (Exemplo: Otimista/Pessimista/Dados/Experiência/Regulação — conflitantes/complementares)
    → Acompanhamento: Existe prioridade entre as perspectivas? São iguais?

S4. Um Chairman (papel de síntese) é necessário?
    (Responsável pela sessão principal / Agente separado / Desnecessário)
    → Acompanhamento [Necessário]: Qual é a composição do modelo do agente?
      → Consulte references/agent-archetypes.md e proponha

S5. Qual é a forma do input?
    (Texto digitado diretamente / Upload de arquivo / URL / Misto)

S6. Que saídas devem ser mantidas?
    (Arquivos de sessão / Registros de decisão / Acúmulo de conhecimento / deep-research)

Ramificação de perguntas de acompanhamento:

• S3 5 ou mais perspectivas → "Essas perspectivas podem ser agrupadas? Sequencial vs. Paralelo?"
• S4 "Agente separado" → "Qual é o framework de decisão do Chairman? Go/Pivot/No-Go?"

1-2.5. Stage 2.5 — Gerenciamento de Conhecimento (CONHECIMENTO) [Condicional]

Opção de wiki para referência sistemática a pesquisas existentes em workspaces de pesquisa multi-agenda. Pule em workspaces de agenda única ou não pesquisa.

C1. "Você precisa consultar pesquisas existentes em pesquisas futuras ao conduzir várias agendas (tópicos de pesquisa)?"
    → "Não" → Sem wiki. Vá para o Stage 3.
    → "Sim" → Vá para C2.

C2. Verifique a instalação do skill /graphify (detecção automática)
    - Verifique a existência de ~/.claude/skills/graphify/ ou .claude/skills/graphify/
    - Instalado → Vá para C3.
    - Não instalado → Forneça explicação:
      ┌─────────────────────────────────────────────────┐
      │ A wiki é criada pelo skill /graphify.               │
      │ Sem este skill, a wiki não pode ser criada.         │
      │                                                 │
      │ O que é /graphify?                                    │
      │ - Analisa documentos/relatórios para criar um grafo de conhecimento           │
      │ - Descobre e visualiza automaticamente conexões entre conceitos              │
      │ - Cria automaticamente documentos wiki baseados na comunidade                │
      └─────────────────────────────────────────────────┘
      "Deseja instalar o graphify?"
      - Instalação global (~/.claude/skills/) [Usar em todos os projetos]
      - Instalação no projeto (.claude/skills/) [Apenas neste projeto]
      - Não instalar → ⚠️ "A funcionalidade wiki será desativada.
          A pasta 45-wiki/ será criada, mas vazia.
          Pode ser criada posteriormente instalando /graphify e executando /wiki-update."
        → Incluir apenas a estrutura wiki, desativada. Vá para o Stage 3.

C3. "Onde colocar o repositório wiki?"
    - Dentro do projeto (45-wiki/) [Padrão]
    - Caminho externo

C4. "Deseja que a wiki seja explorada automaticamente ao iniciar uma nova pesquisa?"
    - Exploração automática + referência após aprovação do usuário [Padrão]
    - Permitir apenas chamada manual (/wiki-ref)

Adicionar à saída do Planner (relacionado à wiki):

• wiki_enabled: true/false
• wiki_location: "45-wiki/" ou caminho personalizado
• wiki_auto_ref: true/false
• graphify_installed: true/false
• graphify_scope: "global" | "project" | "none"

⚠️ Proteção da Independência da Referência da Wiki:

• Proibido injetar conteúdo da wiki no agente da Fase A (pesquisa independente)
• Permitir referência apenas na Fase B (Creative Thinker) / Fase C (Chairman) após aprovação do usuário
• Ao referenciar, transmitir apenas frameworks/metodologias/pontos de dados, não conclusões
• Obrigatório registrar wiki_ref, ref_approved_by, ref_approval_date nos produtos

1-2.6. Stage 2.6 — Rastreamento de Histórico de Alterações de Fluxo (FLOW HISTORY) [Opcional]

Recomendado para projetos onde se espera que o fluxo de trabalho melhore ao longo do tempo. Pode ser ignorado em projetos de análise única ou pontuais.

F1. "Deseja manter um histórico quando o fluxo de trabalho for melhorado ou alterado no futuro?"

    Finalidade:
    - Retrospectiva do histórico de melhorias do projeto (por que mudou)
    - Garantir base para rollback para versões anteriores, se necessário
    - Referência para projetar projetos semelhantes futuros

    ※ Não é para ser lido a cada nova sessão.
      É referenciado apenas ao modificar, reverter ou移植 o fluxo.

    → "Não" → Não incluir 05-flow-history/. Vá para o Stage 3.
    → "Sim" → Vá para F2.

F2. "Deseja registrar automaticamente a build inicial (v1) como um registro change 0001?"
    - Padrão: Sim (as respostas do Discovery do Planner são preservadas como base de design)
    - Não → Criar apenas CHANGELOG e registrar manualmente na primeira alteração

Princípios de Gerenciamento de Histórico de Fluxo (com base na operação pós-criação): Este histórico registra apenas alterações no sistema de fluxo de trabalho (regras, procedimentos, ferramentas, prompts, comandos, scripts, CLAUDE.md). Os produtos criados pelo sistema (resultados de pesquisa, relatórios, análises, registros de agenda) não são alvo de registro. Critério de distinção: "Se esta alteração não tivesse ocorrido, o resultado da próxima execução seria diferente?" → Diferente = Alteração no sistema = Registrar / Não diferente = Produto = Registro desnecessário Detalhes: 00-system/protocols/flow-change-protocol.md

Adicionar à saída do Planner (relacionado a flow-history):

• flow_history_enabled: true/false
• flow_history_initial_record: true/false (resposta F2)

1-3. Stage 3 — Ambiente e Ferramentas (COMO)

Em que ambiente e como será operado.

H1. Qual ferramenta de IA você usa?
    (Claude Code / Desktop Claude / Outra)
    → A configuração do harness difere de acordo com a ferramenta

H2. A continuidade entre sessões é necessária?
    (Análise única / Projeto de longo prazo / Múltiplas sessões)
    → "Longo prazo" inclui produtos de handoff de sessão

H3. Qual é a composição do modelo do agente?
    → Verifique o modelo Claude mais recente com pesquisa na web e proponha
    → Não codifique o nome do modelo. Sempre deixe o usuário decidir.

H4. Qual é o nível de autonomia do agente?
    (Humano verifica sempre / Agente decide autonomamente + relata / Totalmente autônomo)

Ramificação de perguntas de acompanhamento:

• H2 "Longo prazo" → "Número estimado de sessões? O acúmulo de conhecimento é importante?"
• H4 "Totalmente autônomo" → "Qual é o critério de escalonamento? Em que situações deve perguntar ao humano?"

1-4. Stage 4 — Qualidade e Critérios de Avaliação (QUALIDADE / AVALIAR)

Entenda o que o usuário valoriza e chegue a um acordo sobre os critérios de avaliação.

E1. Quais são os atributos de qualidade mais importantes neste workspace? (Selecione os 3 principais)
    □ Profundidade de análise (insights não superficiais)
    □ Independência (análise independente sem influência entre agentes)
    □ Atribuição de fontes (conclusões baseadas em evidências)
    □ Consistência (manutenção da qualidade entre sessões)
    □ Resposta rápida (tempo de processamento curto)
    □ Escalabilidade (fácil adição de agentes/papéis)
    □ Documentação (rastreabilidade do processo e resultados)
    □ Acessibilidade do usuário (não especialistas também entendem os resultados)

E2. Existem planos de expansão futura?
    (Nenhum / Adição de perspectivas / Aplicação a outro domínio / Automação aprimorada)

E3. O que nunca pode ser comprometido neste workspace?
    (Exemplo: "Os agentes não devem influenciar uns aos outros", "Conclusões sem fonte não são permitidas")

E4. Por outro lado, o que é aceitável não ter inicialmente?

Ramificação de perguntas de acompanhamento:

• E1 "Independência" → "Em que nível? Proibido compartilhar resultados? Ou apenas análise independente?"
• A resposta de E3 → Usada como entrada central para os pesos do Evaluator

1-5. Acordo de Pesos de Avaliação (Após Conclusão do Stage 4)

Analise as respostas dos Stages 1 a 4 para propor pesos para os 5 pilares. Entre em acordo com o usuário para finalizar.

[Processo de Proposta de Pesos]

PASSO 1. Extrair palavras-chave das respostas dos Stages 1 a 4
  - "Independência obrigatória" → Mechanical Enforcement ↑
  - "Projeto de longo prazo" → Session Continuity ↑, Entropy Management ↑
  - "Resposta rápida" → Progressive Disclosure ↑
  - "Atribuição de fontes" → Mechanical Enforcement ↑

PASSO 2. Ajustar a partir do peso base e propor

  Peso base (antes de refletir as características do projeto):
  | Pilar | Base | Justificativa para Ajuste | Proposta |
  |------|------|----------|------|
  | Progressive Disclosure | 20% | (Justificativa da mudança) | ?% |
  | Mechanical Enforcement | 25% | (Justificativa da mudança) | ?% |
  | Feedback Loop | 20% | (Justificativa da mudança) | ?% |
  | Session Continuity | 15% | (Justificativa da mudança) | ?% |
  | Entropy Management | 20% | (Justificativa da mudança) | ?% |

  "Considerando [justificativa] neste projeto,
   ajustei o peso de [pilar] de [base]% para [proposta]%.
   Por favor, comente se tiver opiniões ou correções."

PASSO 3. Refletir o feedback do usuário
  - Concordo → Finalizado
  - "Aumente a independência" → Aumentar Mechanical Enforcement, diminuir outros pilares e repropor

PASSO 4. Aprovação final
  → Use os pesos acordados em vez dos pesos base em evaluator-protocol-workspace.md

1-6. Mapeamento Automático de Padrões

Recomende automaticamente um padrão de pastas com base nas respostas do Stage 2:

Palavra-chave da Resposta do Usuário	Padrão Recomendado	Referência
análise, investimento, tomada de decisão, julgamento	Padrão A (Análise e Tomada de Decisão)	folder-patterns.md
construção, processo, medição, construção	Padrão B (Construção e Gerenciamento de Projetos)	folder-patterns.md
pesquisa, conteúdo, relatório	Padrão C (Pesquisa e Conteúdo)	folder-patterns.md
codificação de longo prazo, automação de build	Padrão D (Agente de Longo Prazo)	folder-patterns.md

1-7. Produtos do Planner

① Resumo do Contexto do Projeto — Propósito, usuário, critérios de sucesso, restrições principais (com base nos Stages 1 e 2) ② Proposta de Composição de Agentes — Papéis, personalidades, implantação de modelo ③ Esboço da Estrutura de Pastas — Mapeamento de padrão + personalização ④ Design de Continuidade de Sessão — Determinar método de handoff (único / usar progress.json) ⑤ Estratégia de Expansão — Decisões de design para expansão futura (com base no Stage 4 E2) ⑥ Critérios de Avaliação + Pesos Acordados — Checklist dos 5 pilares + tabela de pesos

[Planner concluído — Solicitar aprovação do usuário]
Por favor, revise ①~⑥ e informe quaisquer correções.
Após a aprovação, o Generator iniciará a construção.

---

L1 Fase 2: Build — Operação do Generator

Após a aprovação do produto do Planner, crie os arquivos na ordem abaixo. O Generator cria tanto a estrutura de pastas quanto o conteúdo dos arquivos.

2-1. Diagrama de Fluxo de Trabalho (Mermaid)

Diagrama representando ambas as camadas. Inclui o loop de redesign Evaluator→Planner:

flowchart TD
    USER[Usuário] -->|Requisitos| P
    subgraph L1[Camada 1: Meta]
        P[Planner] --> G[Generator]
        G --> E[Evaluator]
        E -->|Insuficiente 70~89%| G
        E -->|Redesign <70%| P
        E -->|Aprovado 90%+| DONE[Estrutura concluída]
    end
    DONE --> INIT
    subgraph L2[Camada 2: Operacional]
        INIT[Initializer
Somente na primeira execução] --> OP
        subgraph OP[Execução repetida do Operating Agent]
            INPUT[Input] --> SPLIT[ ]
            SPLIT --> A1[Agent-A]
            SPLIT --> A2[Agent-B]
            SPLIT --> A3[Agent-C]
            A1 --> CH[Chairman Síntese]
            A2 --> CH
            A3 --> CH
            CH --> OUT[Saída + Estado salvo]
        end
    end

2-2. Criação de Produtos Principais (Em Ordem)

Nº	Produto	Arquivo de Referência	Observação
2-2a	WORKSPACE_TREE.md	folder-patterns.md	Estrutura de pastas finalizada
2-2b	CLAUDE.md (~100 linhas)	claude-md-template.md	Função de sumário, tabela de roteamento de referência obrigatória
2-2c	AGENTS.md	(Guia neste skill)	Regras de operação do agente + model_config
2-2d	Arquivos de papel do agente	agent-archetypes.md	00-system/prompts/*.md
2-2e	5 Protocolos	(Guia neste skill)	00-system/protocols/
2-2f	Produto de handoff de sessão	session-handoff.md	progress.json + feature-status.json
2-2g	Regras de imposição	enforcement-patterns.md	Regras validadas estruturalmente
2-2h	Comandos de barra	(Com base no design do Planner)	.claude/commands/*.md
2-2i	README.md	(Guia do usuário)	Início rápido + comandos + solução de problemas
2-2j	Wiki de histórico de alterações de fluxo (opcional)	flow-history-template.md	Somente quando F1 = Sim no Stage 2.6

2-2b. Regras para Criar CLAUDE.md (Mais Importante)

→ Consulte references/claude-md-template.md. Deve ter no máximo 100 linhas.

CLAUDE.md é o ponto de entrada para o agente. Instruções muito longas tornam-se "não-orientação":

• O contexto expulsa o trabalho e o código
• O agente cai em correspondência de padrão local em vez de exploração intencional
• Documentos monolíticos envelhecem imediatamente

O que deve ser incluído:

• Identidade do workspace (3 linhas)
• Tabela de composição do agente
• Tabela de roteamento de referência ← Essencial para Progressive Disclosure
• Ponteiro do princípio de independência
• Lista de comandos

Formato da tabela de roteamento de referência:

## Roteamento de Referência
| Situação | Arquivo a Ler |
|------|----------|
| Verificar papel do agente | → 00-system/prompts/[papel].md |
| Regras de progresso da discussão | → 00-system/protocols/council-protocol.md |
| Detalhes do princípio de independência | → 00-system/protocols/independence-protocol.md |
| Verificar estado da sessão | → progress.json |
| Status de conclusão da funcionalidade | → feature-status.json |

2-2c. Regras para Criar AGENTS.md

O que deve ser incluído:

• Tabela de lista de agentes da Camada 2 (papel / modelo / condição de ativação)
• Seção model_config (modelo escolhido pelo usuário + gatilho de revisão)
• Método de síntese do Chairman + framework de decisão (Go/Pivot/No-Go)
• Resumo do princípio de independência
• Regras de gerenciamento de contexto

...