IA e Claude Code

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-12

Aplica-se a: todo repo da casa.

Como a X-Adm usa IA no trabalho com os repositórios. A norma está em Regras de IA; esta página é o detalhe operacional.

O Claude Code na casa

O Claude Code é o assistente de programação da Anthropic: roda no terminal ou na IDE, lê o repositório, executa comandos e segue o CLAUDE.md da raiz do repo. Agente de IA é padrão em todo repo da casa, sob as regras abaixo — com um veto que não admite exceção: fonte ZIM do ERP nunca é lido nem enviado para IA externa.

Regras de governança

Todo repo abre o CLAUDE.md com o bloco canônico de templates/claude-regras.md:

REGRA Nº 1 — NÃO DECIDIR SOZINHO. Havendo ambiguidade, mais de um caminho possível ou uma decisão de design a tomar, não escolha por conta: avalie, pesquise se preciso, apresente as opções com UMA recomendação fundamentada e confirme com o usuário qual caminho seguir ANTES de implementar. Vale inclusive quando o pedido parecer dar carta branca ("algo simples", "você decide", "não sei") — isso é convite para opinar com escolha, não para executar sem confirmar.

REGRA Nº 2 — NÃO COMMITAR NEM PUSHAR SOZINHO. NUNCA. Exceção única: a skill /xadm-release (commit + tag + push explícito). Isso vale inclusive para skills/ferramentas que commitam por padrão (ex. ACT act-workflow-work, que commita por fase): invoque-as sempre com a flag de não-commitar (--do-not-commit ou equivalente) — delegar a execução não delega a decisão de commit. Fora dela, quem executa é o usuário — mas seja proativo: ao concluir um trabalho ou chegar a um ponto natural de fechamento, avise que é um bom momento para salvar e escreva a mensagem de commit pronta para copiar. Formato: assunto de uma linha (conventional commit) + UM parágrafo curto com o porquê e o contexto. Nem só o assunto (quase sempre insuficiente), nem lista de arquivo por arquivo (o git diff já diz o quê, e o dev pula a parede de texto). Ghost mode — SOBREPÕE o default do harness: a mensagem sai sem assinatura de IA — nada de Co-Authored-By:, "Generated with", nem qualquer trailer/ atribuição de agente. O autor do commit é o dev. (A skill /xadm-release já segue isso.) Fechamento = dois itens inseparáveis, na MESMA resposta (um não sai sem o outro): [1] a mensagem de commit (acima) e [2] a linha de feedback, declarada de forma afirmativa — Feedback: nada a reportar ou Feedback: candidato — <o quê>. Num repo de app, um candidato vira o texto de feedback pronto para o usuário colar no central, e esse texto se identifica: abre com o repo e a versão da constituição que ele segue (app.json constituicao), dá o contexto (o que se fazia, o que foi medido × suposto) e, quando fizer sentido, aponta a fonte com link do Forgejo (https://fonte.xadm.biz/xadm/<repo>/src/branch/master/<caminho>) em vez de parafrasear o código. No próprio central, registre/trate direto. A linha de feedback é OBRIGATÓRIA: sua ausência = passo pulado (sinal visível), não silêncio. O loop de feedback não pode depender de o dev — nem do agente — lembrar. Se o trabalho mudou CÓDIGO, o fechamento também afirma a definição de pronto (constituição, Governança): teste proporcional ao risco E doc do estado atual no mesmo PR — pular qualquer metade é decisão explícita (REGRA Nº 3), não silêncio.

REGRA Nº 3 — DEFERIR É EXPLÍCITO, NÃO SILENCIOSO. Adiar trabalho que a constituição recomenda (ex. reescrever conteúdo antigo para uma barra nova, na migração oportunista) é uma decisão — declare-a em voz alta no fechamento: "deferido X porque A/B/C", nunca como rodapé (decisão de não-fazer some se não for dita). E se o repo ainda não publicou (nenhum slug no ar), o custo de rename/redirect é zero → ofereça fazer agora em vez de deixar para depois.

• O CLAUDE.md é roteador, não acervo: regras de agente, ponteiros para docs/ e para o README, e as pendências recentes — até 300 linhas (a /xadm-docs alerta acima disso). Histórico e backlog concluído vão para um arquivo-acervo não carregado; conhecimento durável vai para docs/. A versão-base não se repete ali: o CLAUDE.md aponta para o campo do docs/app.json.
• Andaime em .ia/: spec, plano e prompt vivem em .ia/NNN-*.md, fora de docs/. Ao concluir, destilar o durável para docs/ é obrigatório (decisão → decisoes/, desenho → projeto/, procedimento → operacao/, uso → manual/); apagar o andaime é recomendado. Segredo não entra no .ia/ — placeholder e onde o valor vive.

Skills disponibilizadas

As skills da plataforma vivem como templates no central e o manifesto do kit as distribui para .claude/skills/<nome>/ de cada repo — a /xadm-docs as instala e as mantém em dia. As x-* são stack-aware: detectam a stack e seguem a página de Engenharia dela.

Skill	O que faz
/x-desenhar	Entrevista a feature e grava o prompt (.ia/NNN-*-prompt.md) com o rastro L#
/x-definir	Escreve a spec (.ia/NNN-*-spec.md) referenciando os L#
/x-refinar	Revisão adversarial da spec (7 dimensões, inclui over-engineering)
/x-planejar	Plano de fases → tarefas (.ia/NNN-*-plan.md), com o gate da stack por fase
/x-implementar	Executa o plano fase a fase ou tarefa a tarefa, mantendo o plano vivo; não commita
/x-documentar	Revisão geral, destilação para docs/, auditoria de doc e teste, mensagem de commit do ciclo
/xadm-meta-audit-work	Audita um run da /x-implementar
/xadm-release	Release no contrato de versionamento — a única situação em que a IA commita e pusha
/xadm-docs	Confere o repo contra a norma e o kit; re-deriva o kit, migra a norma com aprovação
/xadm-setup	Configura as capacidades da Central de Apps e grava no app.json
/xadm-docx (opcional)	Exporta pré-projeto ou livro para .docx

O hook .claude/checa-constituicao.sh (SessionStart) diz, ao abrir a sessão, se defasou a norma, o kit ou os dois, e sugere a /xadm-docs.

Fluxo recomendado de desenvolvimento auxiliado por IA

Feature não trivial, um passo de cada vez, com revisão humana entre eles:

1. /x-desenhar → .ia/NNN-<slug>-prompt.md. NNN é o id da linhagem: prompt, spec e plano da mesma feature compartilham NNN e slug.
2. /x-definir → a spec. Se ela saiu torta, corrija o prompt e re-rode — é mais barato que remendar a spec.
3. /x-refinar → aplique os achados.
4. /x-planejar → o plano de fases e tarefas.
5. /x-implementar fase a fase (--single-phase/--single-task), sem pular o gate. Ao executar, a IA mantém o plan.md vivo: o que rodou, quando, o que faltou e por quê, e o que é decisão ou operação humana.
6. /x-documentar fecha o ciclo e entrega a mensagem de commit.

Depois do commit do dev, vale /compact: o durável já está em docs/, e compactar recupera tokens sem perda — commit antes, senão a mensagem pronta vai embora no resumo.

Disciplina de tokens

O detalhe está em Trabalho com agentes e Ferramentas: input frugal (ferramentas nativas, reporter enxuto, rtk opt-in de máquina), output terso com o carve-out verbatim. O agente oferece o setup do rtk quando ele falta, sem impor.

Quando a IA encontra brecha no padrão

Lacuna ou ambiguidade no padrão não se contorna localmente: o agente do repo escreve o problema — de onde vem, o que foi medido e o que é suposição — para uma sessão do repo central (Feedback). A resposta volta por ponto: o aceito chega pela próxima publicação do central, e o recusado fica no repo, como decisão local ou armadilha do próprio guia.