Claude HADS Skill

Versão 1.0.0 · Padrão de Documentação Humano-IA · 2026 · HADS 1.0.0

INSTRUÇÃO DE LEITURA DA IA

Esta skill ensina o Claude a ler, gerar e validar documentos HADS. Leia todos os blocos [SPEC] antes de responder a qualquer solicitação relacionada a HADS. Leia os blocos [NOTE] se precisar de contexto sobre intenção ou casos extremos.

1. O QUE É HADS

[SPEC]

• HADS = Padrão de Documentação Humano-IA (Human-AI Document Standard)
• Convenção para documentação técnica em Markdown
• Quatro tipos de blocos: **[SPEC]**, **[NOTE]**, **[BUG]**, **[?]**
• Todo documento HADS requer: título H1, declaração de versão, manifesto da IA
• O manifesto da IA aparece antes da primeira seção de conteúdo, informa à IA o que ler/ignorar
• Extensão de arquivo: .md — Markdown padrão, nenhuma ferramenta necessária

2. TIPOS DE BLOCOS

[SPEC]

**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
**[NOTE]**   Human context, history, examples. AI may skip.
**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.
**[?]**      Unverified / inferred. Lower confidence. Always flagged.

Regras de tags de bloco:

• Negrito, em sua própria linha: **[SPEC]**
• O conteúdo segue imediatamente (sem linha em branco entre a tag e o conteúdo)
• Múltiplos blocos de tipos diferentes permitidos por seção
• Blocos BUG com título permitidos: **[BUG] Short description**
• Sem aninhamento de blocos dentro de blocos

3. ESTRUTURA DE DOCUMENTO REQUERIDA

[SPEC]

# Document Title
**Version X.Y.Z** · Author · Date · [metadata]

---

## AI READING INSTRUCTION

Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.

---

## 1. First Section

**[SPEC]**
...

Elementos necessários em ordem:

1. Título H1
2. **Version X.Y.Z** no cabeçalho (primeiras 20 linhas)
3. Seção de manifesto da IA antes da primeira seção de conteúdo
4. Seções de conteúdo (H2), subseções (H3)

4. COMO O CLAUDE LÊ HADS

[SPEC] Ao encontrar um documento HADS:

1. Encontre e leia o manifesto da IA primeiro
2. Leia todos os blocos [SPEC] — esta é a verdade fundamental
3. Leia todos os blocos [BUG] — sempre, antes de gerar qualquer código ou configuração
4. Leia os blocos [NOTE] apenas se [SPEC] for insuficiente para responder à consulta
5. Trate o conteúdo [?] como hipótese — observe a incerteza na resposta

Otimização de tokens: para documentos grandes, escaneie primeiro os títulos das seções e, em seguida, leia apenas os blocos [SPEC] e [BUG] nas seções relevantes.

5. COMO O CLAUDE GERA HADS

[SPEC] Quando solicitado a escrever documentação no formato HADS:

1. Comece com o bloco de cabeçalho (título, versão, metadados)
2. Adicione o manifesto da IA — sempre inclua, nunca pule
3. Organize o conteúdo em seções H2 numeradas
4. Para cada fato: escreva como [SPEC] — conciso, lista ou tabela ou código
5. Para cada "porquê" ou contexto: escreva como [NOTE]
6. Para cada modo de falha conhecido com correção confirmada: escreva como [BUG]
7. Para cada afirmação não verificada: escreva como [?]
8. Termine com a seção de changelog

Regras de conteúdo para [SPEC]:

• Prefira listas com marcadores a prosa
• Prefira tabelas para fatos com múltiplos campos
• Prefira blocos de código para sintaxe, formatos, exemplos
• Máximo de 2 frases de prosa — se precisar de mais, mova para [NOTE]

Regras de conteúdo para [BUG]:

• Sempre inclua: sintoma, causa, correção
• Opcional: versões afetadas, solução alternativa
• Título na mesma linha: **[BUG] Short description**

[NOTE] Ao converter documentação existente para HADS: extraia fatos para [SPEC], mova narrativa e histórico para [NOTE], apresente todos os problemas conhecidos como [BUG]. Não duplique conteúdo entre os tipos de bloco.

6. REGRAS DE VALIDAÇÃO

[SPEC] Um documento HADS válido deve ter:

• Título H1
• **Version X.Y.Z** nas primeiras 20 linhas
• Manifesto da IA antes da primeira seção de conteúdo
• Todas as tags de bloco em negrito: **[SPEC]** não [SPEC] não [SPEC]
• Blocos [BUG] contêm no mínimo sintoma + correção

Validador: (planejado — ainda não incluído nesta versão)

7. EXEMPLOS DE INTERAÇÕES

[SPEC]

Usuário: "Escreva a documentação HADS para esta API REST" → Gere o documento HADS completo: cabeçalho, manifesto, seções com blocos [SPEC]/[NOTE]/[BUG]

Usuário: "Converta este README para o formato HADS" → Reestruture o conteúdo existente em blocos HADS, preserve todos os fatos, adicione o manifesto

Usuário: "Este documento é HADS válido?" → Verifique: título H1, versão, manifesto, formatação de tag de bloco, completude do bloco BUG

Usuário: "Resuma este documento HADS" → Leia apenas os blocos [SPEC] e [BUG], retorne um resumo estruturado

Usuário: "O que esta API faz?" (documento HADS fornecido)

…