IA e Claude Code¶

Como a X-Adm usa IA no trabalho com os repositórios e a documentação. A norma está na constituição §6; esta página é o detalhe operacional: o que é o Claude Code, as regras que a IA segue aqui, as skills disponibilizadas pela plataforma e como instalar tudo num repo.

O que é o Claude Code¶

O Claude Code é o assistente de programação da Anthropic: roda no terminal (ou na IDE), lê o repositório, executa comandos e segue as instruções do arquivo CLAUDE.md na raiz do repo. Na X-Adm ele é usado para escrever e migrar documentação, fazer releases e manter os repos aderentes ao padrão da plataforma — sempre sob as regras abaixo.

Regras de governança¶

Todo repo que usa Claude Code (ou outra IA) abre o seu CLAUDE.md com o bloco canônico de regras (templates/claude-regras.md):

A IA não decide sozinha. Havendo ambiguidade ou mais de um caminho possível, ela apresenta as opções com uma recomendação e confirma com o usuário antes de implementar. Decisão às cegas é a forma mais rápida de divergir do padrão.
A IA não faz commit nem push sozinha. Nunca. Única exceção: a skill /xadm-release, que é um comando explícito de commit + tag + push. Fora isso, a IA pode sugerir o commit e a mensagem — quem executa é o usuário. Isso inclui skills de execução que commitam por padrão (ex. ACT act-workflow-work): invoque-as sempre com a flag de não-commitar (--do-not-commit ou equivalente).

E uma restrição de segurança que não está em template porque não admite exceção: fonte ZIM do ERP nunca é lido nem enviado para IA externa — veto explícito da direção. A IA trabalha livremente em documentação, templates, CI e infraestrutura; em repos de aplicação Java/Flutter, só com autorização da direção para aquele repo.

Skills disponibilizadas¶

Skill é um comando (/nome) que o usuário invoca dentro do Claude Code para executar um fluxo padronizado. As skills da plataforma vivem como templates no repo central e são copiadas para .claude/skills/<nome>/SKILL.md em cada repo de aplicação — se o fluxo mudar, muda primeiro o template no central e as cópias se re-derivam na migração oportunista.

Fluxo de trabalho X-Adm (modelado no ACT 1.0, fine-tune da casa): desenhar → definir → refinar → planejar → implementar → documentar. As skills de workflow são stack-aware — detectam a stack (app.json/repo) e seguem a base de conhecimento da casa daquela stack (a página de Engenharia: java-micronaut, flutter, java...); as x-* carregam ainda references/<stack>.md com os concerns por estágio. O x-documentar realimenta essa base (loop §6). x-implementar não commita (REGRA Nº 2); commit é do dev / /xadm-release.

Skill	O que faz	Template canônico
`/x-desenhar`	Entrevista a feature e grava o prompt (`.ia/NNN-*-prompt.md`) com o rastro L#	`templates/x-desenhar/`
`/x-definir`	Escreve a spec (`.ia/NNN-*-spec.md`) referenciando os L#, no idioma da stack	`templates/x-definir/`
`/x-refinar`	Revisão adversarial da spec (7 dimensões, inclui over-engineering)	`templates/x-refinar/`
`/x-planejar`	Plano de fases → tarefas (`.ia/NNN-*-plan.md`), verify = gate da stack	`templates/x-planejar/`
`/x-implementar`	Executa o plano fase/tarefa a tarefa (não commita; destila o andaime)	`templates/x-implementar/`
`/x-documentar`	Destila a sessão p/ `docs/` + audita lacuna de doc/teste, refina a base (§6)	`templates/x-documentar/`
`/xadm-meta-audit-work`	Audita um run da `/x-implementar` (confere não-commit, gate, fechamento)	`templates/xadm-meta-audit-work-skill.md`
`/xadm-release`	Release do app no contrato do padrão	`templates/xadm-release-skill.md`
`/xadm-docs`	Confere e migra a doc/skills do repo vs constituição	`templates/xadm-docs-skill.md`
`/xadm-setup`	Configura as funcionalidades da Central de Apps (provisiona e grava no `app.json`)	`templates/xadm-setup-skill.md`
`/xadm-docx` (opcional)	Exporta pré-projeto/livro para `.docx` no padrão X-Adm	`templates/xadm-docx-skill.md`

Fluxo recomendado de desenvolvimento auxiliado por IA¶

O caminho padrão da casa para uma feature não-trivial — andaime em .ia/ (§1.9), um passo de cada vez, com pontos de revisão humana:

Avaliar .ia/ — ver o que já existe (specs/planos abertos, numeração).
Escrever a definição em .ia/NNN-descricao-prompt.md — o pedido em prosa, o insumo do qual a spec nasce. NNN é o id da linhagem (a feature), não uma sequência global de arquivos: os estágios de uma mesma linha — -prompt, -spec, -plan — compartilham o mesmo NNN e o mesmo slug, mudando só o sufixo. Uma feature nova recebe o próximo NNN e slug próprio. Ex.: 001-definicao-prompt → 001-definicao-spec → 001-definicao-plan; depois 002-exportar-projeto-docx-prompt. Segredo não entra no .ia/ (é versionado): se o pedido tem credencial, troque por placeholder (<TOKEN>, ${VAR}) e aponte onde o valor real vive — vazou, rotacione (constituição §1.9).
/x-desenhar entrevista e grava a definição .ia/NNN-*-prompt.md (o passo 2 pode ser feito por ela, ou à mão). /x-definir → gera .ia/NNN-*-spec.md referenciando os L#.
Avaliar a spec; se algo está torto, corrigir o prompt (volta ao passo 2//x-desenhar) e re-rodar — é mais barato ajustar o pedido que remendar a spec.
/x-refinar (revisão adversarial) → aplicar os achados.
Avaliar; ajustar a spec se necessário.
/x-planejar → gera .ia/NNN-*-plan.md de fases → tarefas (Fase 1 costuma de-riscar).
/x-implementar fase/tarefa a tarefa (--single-phase/--single-task) — não pular o gate. Ao concluir o plano, NÃO entrega o commit — aponta pro /x-documentar (o ciclo fecha lá).
/x-documentar fecha o ciclo → revisão geral + destila o durável p/ docs/ + audita lacuna de doc e de teste (§6) + apaga o andaime + entrega a mensagem de commit do ciclo.

Regra da IA ao executar (/x-implementar): conforme roda cada fase, atualiza o plan.md — marca os checkbox do que executou, quando, o que ficou faltando e por quê, e o que é decisão ou operação humana (release, deploy, validação visual, infra). O plano vira o retrato vivo do andamento; o humano revê nos pontos marcados.

/xadm-release¶

Executa uma release inteira no contrato de versionamento, sem esquecer passo: lista os commits desde a última tag, sugere o bump SemVer (Conventional Commits), atualiza o manifesto da stack (gradle.properties, pubspec.yaml, package.json ou VERSION), monta a entrada do CHANGELOG.md (Keep a Changelog, pt-BR), faz o commit chore(release): vX.Y.Z, a tag anotada vX.Y.Z e o push — confirmando cada decisão com o usuário ao longo do fluxo. É a única situação em que a IA commita e pusha.

/xadm-docs¶

Compara a versão-base da constituição registrada no docs/app.json do repo (campo constituicao:) com a vigente publicada neste site (/toolchain/constituicao-versao.txt). Se houver defasagem, baixa o texto vigente, lista objetivamente o que está em desacordo (estrutura de pastas, frontmatter, nomenclatura legada, convenções) e migra só com aprovação do usuário, atualizando o campo no app.json e o CLAUDE.md juntos.

Hook de sessão (não é skill, mas acompanha)¶

O .claude/checa-constituicao.sh é um hook SessionStart: ao abrir o Claude Code no repo, compara a versão-base com a vigente e, se estiver defasada, avisa e sugere rodar /xadm-docs. Sem rede ou sem app.json, fica em silêncio — nunca trava a sessão.

Como adotar num repo¶

Cole o bloco de regras de IA no topo do CLAUDE.md do repo.
Copie todas as skills do conjunto core — a lista mecânica é o manifesto.json menos as opcionais (as 6 x-* de workflow + xadm-meta-audit-work, xadm-docs, xadm-release, xadm-setup). Não pare em docs+release (erro real de bootstrap) — o passo a passo com as adaptações por skill está no checklist de app novo.
Copie o hook de constituição para .claude/checa-constituicao.sh e registre-o no .claude/settings.json (snippet no cabeçalho do script).
Registre a versão-base no docs/app.json (campo constituicao:) e repita a informação no CLAUDE.md.

O checklist de app novo cobre esses passos junto com o restante da adoção do padrão.

Otimização de custo de tokens¶

A disciplina de tokens do agente tem página própria de engenharia com o detalhe e a receita por stack: Trabalho com agentes de IA. O essencial:

Input frugal — ferramentas nativas de arquivo/busca em vez de cat/sed/grep com pipe jogando texto no contexto; reporter de teste enxuto (verboso só sob falha); e o rtk, proxy que resume a saída de CLI antes do contexto — recomendado da casa, com install/config e regras por stack em Ferramentas de token (rtk).
Output terso + carve-out (recomendado, via hook SessionStart do repo) — estilo terso corta ~65–75% dos tokens de output; o carve-out verbatim protege os deliverables da casa (mensagem de commit, linha §6, código, tabelas de dado, .ia/) da compressão.

Comportamento do agente: aplique o estilo terso por default, sem sacrificar clareza — prosa normal em avisos de segurança, ações irreversíveis ou quando o usuário está confuso. O rtk é install de máquina de dev (global, não por-repo): quando presente, use-o certo (comando bare, o pipe fura o hook); ausente, o agente pode oferecer e guiar o setup (REGRA Nº 1: oferecer, não impor), nunca assumir que o dev o tem.

Quando a IA encontra brecha no padrão¶

A regra da constituição §6 vale dobrado com IA: ambiguidade ou lacuna no padrão não se contorna localmente. Peça ao Claude do repo um texto descrevendo o problema e cole-o numa sessão do Claude Code no repo central documentacao — é esse loop que evolui a constituição e os templates para todos.