Como se trabalha
17 · Agentes de IA
As stacks da Hibex são desenvolvidas com agentes de IA. As regras para eles moram no
AGENTS.md — formato aberto, lido por qualquer agente. O CLAUDE.md só o
importa. O que dá para impor por máquina é imposto por hooks; o resto é regra
escrita, revisada pelo mantenedor.
Onde as regras moram
Por que AGENTS.md e não CLAUDE.md: a regra pertence ao repositório, não a uma
ferramenta. Qualquer agente (Claude Code, Codex, outro) encontra o mesmo texto; trocar de
ferramenta não exige reescrever as regras.
O CLAUDE.md importa o AGENTS.md com a linha @AGENTS.md, em vez de pedir que o agente o
leia: o Claude Code carrega o arquivo importado no começo de toda sessão, e as regras ficam no
contexto sem depender de o agente decidir abrir o arquivo.
A forma do AGENTS.md de uma stack
O modelo traz o AGENTS.md com todas as seções; as marcadas ✱ têm lacunas que a
Fase 1 preenche.
# <repositório> — instruções para agentes de IA
## Fase atual ← muda ao longo da vida
Fase 1 — definindo a stack. NÃO escreva código: preencha docs/stack.md
e as ADRs pré-escritas (guia: docs/guias/definir-a-stack.md).
## O que é este projeto ✱
## Antes de trabalhar, leia
## Regras invioláveis
### Git e GitHub são exclusivos do mantenedor (hook)
### Nunca toque em infraestrutura real
### Segredos jamais no repositório
### Toda mudança por OpenSpec
### Teste primeiro (TDD)
### Versões fixas, nada flutuante
### Decisão técnica → ADR (nasce proposta)
## Idioma
## Stack e estrutura ✱ ← tabela da ficha + diretórios
## Interface: design system ← aponta para vendor/hibex/agentes/AGENTS.md
## Testes ← comandos das três camadas
## Como rodar local ✱
## Protocolo de entrega
## O que o agente NÃO deve fazerA seção "Fase atual"
É a primeira coisa que o agente lê, e muda o comportamento dele:
| Fase | O agente… |
|---|---|
| 1 — Definição | O agente…: só conversa, preenche a ficha e as ADRs; recusa pedidos de código e diz por quê |
| 2 — Fundação | O agente…: trabalha nas changes de fundação, na ordem; recusa change de produto antes de a fundação terminar |
| 3/4 — Produto/Operação | O agente…: ciclo normal de changes |
O que o agente faz e não faz
Protocolo de entrega
Toda entrega de change termina do mesmo jeito, porque o mantenedor valida cada change olhando o sistema no ar.
Formato do resumo por tela:
### Gestão (http://localhost:8081, ana.souza/ana)
| Tela | Onde | O que mudou | O que conferir |
|---|---|---|---|
| Extrato global | menu Extrato | filtro por tipo com "Limpar" | filtrar por Estorno; "Limpar" some sem filtro |Hooks
| Hook | Evento | O que faz | De onde vem |
|---|---|---|---|
block-git-writes.py | Evento: antes de todo comando de shell | O que faz: nega Git de escrita (incluindo mv, restore, checkout, stash, worktree) e gh de escrita (criar PR, issue, release; gh api com escrita), deixa leitura passar; tem teste próprio | De onde vem: modelo (.claude/hooks/) |
block-vendor-hibex.py | Evento: antes de editar arquivo | O que faz: nega edição em vendor/hibex/ | De onde vem: cópia do design system |
block-infra.py | Evento: antes de todo comando de shell | O que faz: nega kamal (fora de version, help, docs, init), ssh/scp/rsync para fora da máquina, bws e bw, clientes de banco e de identidade e curl em rota administrativa de host real, e docker com daemon remoto; tem teste próprio | De onde vem: modelo (.claude/hooks/) |
Os dois hooks do modelo leem o comando inteiro, não só o começo: cada linha, cada &&, ; e
|, bash -c '…', $(…), xargs, find -exec e os prefixos (sudo, env, timeout). O
corpo de um heredoc fica de fora, por ser dado. A leitura mora em .claude/hooks/shell_commands.py,
e a CI roda os testes dos dois.
Regra: se um hook barra uma leitura legítima, ajusta-se o hook (com teste); nunca se contorna.
Skills e comandos
| O quê | Origem | Observação |
|---|---|---|
/opsx:* e skills openspec-* | Origem: openspec init (versão fixa) | Observação: regenerados ao atualizar o OpenSpec, por change |
skill hibex-ui | Origem: cópia do design system | Observação: aponta para vendor/hibex/agentes/ |
| skills próprias da stack | Origem: .claude/skills/ | Observação: só se repetirem um procedimento de verdade |
Memória do agente
Agentes com memória persistente (como o Claude Code) guardam preferências e aprendizados entre sessões. Regra: o que vale para todas as stacks não fica na memória do agente — vira regra aqui. Exemplos de preferências que viraram regra do modelo: "entrega com ambiente no ar e resumo por tela", "atualizar o design system é change", "acervo só com as telas afetadas", "perguntas de escopo em lista numerada".
Conversa com o mantenedor
- respostas em pt-BR;
- perguntas de escopo agrupadas numa mensagem, numeradas, com opções e a recomendada primeiro;
- progresso de tarefas longas: avisar no fim e em erro, não a cada passo;
- números concretos na entrega (quantos testes, quantos casos, quanto tempo), nunca "tudo certo" sem prova.