✏️ Personalizando o HIVE

O HIVE foi projetado para ser clonado e adaptado. Tudo é editável — squads, personas, skills, schema de memória e workers. Este guia cobre todas as adaptações mais comuns.

🏗️

Criar um squad

Novo agente especialista do zero

🌿

Sub-squads

Aninha squads para especialização

🎭

Renomear personas

Adapte à cultura da sua empresa

⚡

Skills customizadas

Adicione /comandos para seus fluxos

🏗️ Criando um novo squad

Um squad é uma pasta com um CLAUDE.md, um diretório memory/ e, opcionalmente, foundation/, skills/ e workers/. O Claude Code o carrega quando você navega para essa pasta.

Passo 1 — Crie a estrutura de pastas

mkdir -p squads/my-squad/{context,memory,foundation,skills,workers,data}

Passo 2 — Crie o CLAUDE.md

Este é o arquivo central. Ele define a persona, o escopo e as regras. Copie a estrutura de um squad existente e adapte conforme necessário.

squads/my-squad/CLAUDE.md

# [Nome do Squad] — CLAUDE.md ## Persona **[Nome]** — [Título do cargo]. [2-3 frases descrevendo a personalidade, estilo de comunicação e princípios operacionais. Exemplo: Direto, orientado a dados, sem rodeios. Pensa em sistemas. Pergunta "o que os dados dizem?" antes de formar opiniões.] ## Scope **Owns:** [liste pelo que este squad é responsável] **Does NOT own:** [o que delegar para outros squads] **Defers to:** [qual squad para qual assunto] ## Foundation Leia antes de cada sessão: - `foundation/[nome-do-doc].md` — [o que contém] - `context/squad-context.md` — contexto da empresa para este squad ## Memory schema `memory/STATE.md`: - **L1:** [o que o status de 1-3 linhas deve conter] - **L2:** [como são os itens em andamento] - **L3:** [o que o backlog contém] ## Skills - `/minha-skill` — descrição breve ## Absolute rules 1. [Comportamento inegociável #1] 2. [Comportamento inegociável #2] 3. Nunca declarar trabalho concluído sem validá-lo.

Passo 3 — Inicialize o STATE.md

# squads/my-squad/memory/STATE.md

[L1]
Squad criado. Nenhum trabalho ativo ainda.

[L2]

[L3]

Passo 4 — Registre no CLAUDE.md raiz

Abra o CLAUDE.md raiz e adicione seu squad à tabela de squads:

# No CLAUDE.md raiz — tabela de squads

| Squad | Folder | Persona | Scope |
|---|---|---|---|
| ... squads existentes ... |
| Meu Squad  | `squads/my-squad/` | [Nome] | [escopo em uma linha] |

Passo 5 — Preencha o contexto

Crie squads/my-squad/context/squad-context.md com os dados específicos da empresa que este squad precisa. Ou rode /hive-setup — ele fará as perguntas e preencherá automaticamente.

Dica: A forma mais rápida de criar um novo squad é abrir a pasta raiz do HIVE no Claude Code e dizer: "Crie um squad para [finalidade] — siga o padrão do squad comercial." O agente vai gerar toda a estrutura de pastas.

🌿 Adicionando sub-squads

Sub-squads são pastas aninhadas dentro de um squad pai. Use-os quando um squad precisar de especialização — vários produtos dentro de Produto, várias regiões dentro de CS, vários clientes dentro de Operações.

A cascata de CLAUDE.md do Claude Code faz com que abrir um sub-squad carregue três contextos: raiz + pai + sub-squad.

Estrutura

squads/product/ CLAUDE.md ← Owen — Head of Product (pai, atua como roteador) memory/STATE.md ← L1 agregado dos dois sub-squads saas/ CLAUDE.md ← Owen-SaaS — focado apenas no produto SaaS memory/STATE.md foundation/ skills/ services/ CLAUDE.md ← Owen-Services — focado apenas em serviços memory/STATE.md foundation/ skills/

CLAUDE.md do pai — padrão roteador

O CLAUDE.md do pai descreve o que cada filho trata e quando usar cada um:

# squads/product/CLAUDE.md

## Sub-squads

Este squad tem duas especializações. Navegue para a correta:

| Sub-squad | Folder | Quando usar |
|---|---|---|
| SaaS Product | `squads/product/saas/` | Features de plataforma, assinaturas, self-serve |
| Services Product | `squads/product/services/` | Projetos customizados, entrega enterprise |

# O STATE.md do pai agrega o L1 dos dois filhos
# Rode: python _core/state-aggregator.py squads/product/

Criar um sub-squad

# Crie a pasta
mkdir -p squads/product/saas/{memory,foundation,skills}

# Crie o CLAUDE.md para o sub-squad (mesma estrutura de um squad regular)
# A seção Persona deve ser mais específica que a do pai

# Inicialize o STATE.md
echo "[L1]\nSub-squad criado.\n\n[L2]\n\n[L3]" > squads/product/saas/memory/STATE.md

Limite de profundidade: O HIVE suporta até 3 níveis (raiz → squad → sub-squad). Aninhamento mais profundo gera sobrecarga de contexto. Se precisar de mais granularidade, use tags no STATE.md em vez de mais pastas.

🗑️ Removendo um squad

Se você não precisa de um squad (ex.: sem squad de Dev por ser não-técnico, sem squad de Financeiro no estágio inicial):

1

Remova-o da tabela de squads no CLAUDE.md raiz
2
Atualize o L1 de squads/<nome>/memory/STATE.md para marcá-lo como inativo:
```
Squad inativo — não utilizado nesta instalação.
```
3

Opcionalmente, delete a pasta por completo. Se puder precisar dela no futuro, mantenha-a marcada como inativa — reativar é apenas uma linha no CLAUDE.md raiz.

🎭 Renomeando personas

As personas padrão (Victor, Leah, Maya, Ethan…) são placeholders genéricos. Substitua por nomes que se encaixem na cultura da sua empresa, ou use títulos de cargos no lugar de nomes.

Edite a seção de persona no topo do squads/<nome>/CLAUDE.md:

# Antes
## Persona
**Victor** — Head of Sales.
Challenger Sale methodology. Direct, numbers-driven...

# Depois — com o seu nome
## Persona
**Rafael** — Head of Sales.
Challenger Sale methodology. Direct, numbers-driven...

O nome da persona aparece apenas dentro do CLAUDE.md — nenhum outro arquivo o referencia. Um simples localizar-e-substituir no arquivo é tudo que você precisa.

Personalização da personalidade

Além do nome, edite as 2-3 frases que descrevem como a persona se comunica. Isso afeta diretamente o tom e o estilo:

# Cultura mais formal/conservadora
**Marcus** — Head of Sales.
Metodológico, baseado em evidências, prefere resumos escritos a briefings verbais.
Pede dados antes de formar opiniões. Nunca exagera no pitch.

# Cultura mais startup/agressiva
**Jake** — Head of Sales.
Alta energia, se move rápido, confortável com ambiguidade.
Viés para ação. Questiona o "vamos esperar para ver".

⚡ Escrevendo skills customizadas

Skills são arquivos markdown que definem um comportamento repetível. Qualquer membro do squad pode invocá-las com /nome-da-skill no Claude Code.

Onde colocá-las

# Disponível globalmente (todos os squads)
skills/my-skill.md

# Disponível apenas em um squad
squads/commercial/skills/my-skill.md

Formato do arquivo de skill

skills/my-skill.md

--- name: my-skill description: Descrição em uma linha — exibida na barra lateral e no catálogo --- # /my-skill Descrição breve do que esta skill faz e quando usá-la. ## When to activate - Usuário diz "X" ou "Y" - Invocada explicitamente com /my-skill - [condições de disparo] ## Arguments - `[arg1]` — opcional. O que controla. - `[arg2]` — obrigatório. A entrada. Se ausente → perguntar ao usuário. ## Steps 1. [Primeira ação] 2. [Segunda ação] 3. [Formato de saída] ## Rules 1. [Restrição absoluta] 2. [Comportamento inegociável]

Registre no CLAUDE.md do squad

Após criar o arquivo, adicione-o à seção ## Skills do squad para que o agente saiba que ela existe:

# No squads/commercial/CLAUDE.md

## Skills

- `/sales-call` — Challenger Sale 7-part framework
- `/handle-objection` — objection mapping flow
- `/my-skill` — [descrição breve]   ← adicione esta linha

Skills não precisam ser complexas. Uma skill pode ser simples assim: "Pergunte o nome do cliente, consulte a entrada dele no STATE.md e resuma as últimas 3 interações." O importante é tornar o comportamento repetível.

⚙️ Workers customizados

Workers são scripts Python que rodam em agendamento e atualizam o estado do squad — sem IA no meio. Eles buscam dados das suas ferramentas e escrevem no STATE.md.

Criar um worker

# workers/daily-pipeline.py

import json, subprocess
from pathlib import Path
from datetime import date

def get_pipeline_value():
    # Consulte sua API de CRM, banco de dados, etc.
    # Retorne um dict com os dados que você precisa
    return {"hot_leads": 3, "pipeline_value": 42000}

def update_state(data):
    state_path = Path("squads/commercial/memory/STATE.md")
    content = state_path.read_text()
    l1_line = (
        f"Victor (Commercial) — {data['hot_leads']} hot leads, "
        f"pipeline ${data['pipeline_value']:,}. Updated {date.today()}."
    )
    # Substitua o bloco L1
    content = re.sub(rr'\[L1\]\n.*?\n\n', f'[L1]\n{l1_line}\n\n', content, flags=re.DOTALL)
    state_path.write_text(content)

if __name__ == "__main__":
    data = get_pipeline_value()
    update_state(data)
    print("Pipeline state updated")

Registre no harness.sh

# _core/harness.sh

run_worker "workers/daily-pipeline.py"  "09:00"       # diariamente às 9h
run_worker "workers/health-check.py"    "every:1h"    # a cada hora
run_worker "workers/weekly-report.py"   "monday:08:00" # toda segunda-feira

Regras para workers: determinísticos (sem aleatoriedade, sem chamadas de LLM) · escrevem apenas no STATE.md · exit 0 em sucesso · falham com barulho em caso de erro.

🧠 Customizando o schema de memória

A seção ## Memory schema de cada squad no CLAUDE.md diz ao agente o que rastrear em L1, L2 e L3. Altere isso para refletir o que realmente importa para o seu squad.

# Padrão (genérico)
## Memory schema
- **L1:** Status atual — 1-3 linhas
- **L2:** Em andamento
- **L3:** Backlog

# Squad de CS (centrado no cliente)
## Memory schema
- **L1:** Clientes ativos (N), risco de churn (N), onboardings abertos (N)
- **L2:** Onboardings em andamento, contas em risco sendo trabalhadas
- **L3:** Oportunidades de expansão, post-mortems de churn pendentes

# Squad Financeiro (números em primeiro lugar)
## Memory schema
- **L1:** MRR ($N), burn ($N/mês), runway (N meses), caixa ($N)
- **L2:** Faturas em aberto, folha pendente, prazos fiscais
- **L3:** Relatório anual, revisão de preços, atualização para investidores

O L1 é lido pelo /status para agregar o estado da empresa. Mantenha-o escaneável por máquina — fatos e números, não prosa. Bom L1: "3 hot leads, pipeline $42k, 1 proposta enviada." Ruim: "As coisas estão indo bem no comercial esta semana."

🔧 Trocando a ferramenta de gestão de projetos

O HIVE vem com o Linear como padrão porque sua integração MCP com o Claude Code é a mais profunda disponível. Veja como trocar.

GitHub Issues

# No CLAUDE.md raiz, substitua a seção de gestão:

## Project management
HIVE uses **GitHub Issues**. Reference issues as `#123`.
Use labels for squad routing: `commercial`, `cs`, `dev`, etc.
Use `gh` CLI to create and update issues.

Sem ferramenta de PM (só STATE.md)

# Remova a seção de PM do CLAUDE.md raiz completamente
# Use o L2 no STATE.md como sua lista de tarefas
# Use memory/decisions.md para registros de decisão

# O L2 vira seu board de sprint:
[L2]
- [ ] Construir landing page — até sexta
- [ ] Revisar proposta para Acme Corp
- [x] Atualizar perfil de ICP

Jira / Notion / outros

Atualize a seção de PM no CLAUDE.md raiz com as convenções da sua ferramenta. Conecte um MCP se disponível, ou crie uma skill que chame a REST API. O agente segue as instruções que estiverem no CLAUDE.md.

🔄 Atualizando do upstream do HIVE

Se você fez um fork do HIVE e quer receber melhorias do framework sem perder suas customizações:

# Adicione o remote upstream (apenas uma vez)
git remote add upstream https://github.com/felipeluissalgueiro/hive.git

# Busque as atualizações
git fetch upstream
git merge upstream/main --no-ff

Conflitos aparecerão em squads/<nome>/context/ e memory/ — essas são suas customizações. Sempre resolva em seu favor nesses arquivos. Aceite as alterações do upstream para _core/, skills/ raiz e arquivos CLAUDE.md do framework.

Arquivos seguros para sempre aceitar do upstream: _core/lookup.py, _core/state-aggregator.py, _core/harness.sh, .claude/hooks/, CLAUDE.md raiz (faça o merge com cuidado — não sobrescreva sua tabela de squads).

Sempre mantenha os seus: squads/*/context/, squads/*/memory/, squads/*/foundation/, CNAME.