@fontdata/ai-commands

O harness de engenharia com IA da Fontdata (slash commands do Claude Code) para qualquer projeto — novo ou existente. Você pode rodar os comandos direto na pasta do projeto, sem instalar nada, ou instalá-los em .claude/commands/ quando quiser versioná-los junto com o código.

Foco exclusivo em Claude Code.

Modo 1 — rodar sem instalar (recomendado)

Na pasta do projeto, chame o comando pelo nome. O Claude Code abre já executando aquele prompt, e o pacote é carregado como plugin só daquela sessão — nenhum arquivo é escrito no repositório.

# npm / npx
npx @fontdata/ai-commands harness
npx @fontdata/ai-commands resolver-bug "login 500 no refresh token"
npx @fontdata/ai-commands versao minor

# yarn
yarn dlx @fontdata/ai-commands harness

# pnpm
pnpm dlx @fontdata/ai-commands harness

Durante a sessão, todos os 36 comandos ficam disponíveis com o prefixo do plugin — /ai-commands:gerar-spec, /ai-commands:criar-agents etc. — assim como a skill lgpd-checker. É isso que faz o /harness, que encadeia 14 comandos, funcionar sem instalação prévia.

O texto depois do nome do comando vira o $ARGUMENTS daquele prompt. Tudo depois de -- é repassado ao Claude Code:

npx @fontdata/ai-commands harness -- --model claude-opus-5
npx @fontdata/ai-commands auditar-seguranca -- -p     # headless, para CI

Use run <comando> quando o nome puder colidir com uma palavra reservada do CLI:

npx @fontdata/ai-commands run git-commit-push

Requisito: o Claude Code precisa estar no PATH (npm i -g @anthropic-ai/claude-code).

Modo 2 — instalar como plugin global

Se você usa os comandos com frequência e não quer o npx a cada vez, registre o marketplace uma vez:

claude plugin marketplace add fontdata-tecnologia/ai-commands
claude plugin install ai-commands@fontdata

Os comandos passam a existir em qualquer sessão do Claude Code como /ai-commands:<comando>.

Modo 3 — instalar no projeto (init)

Quando você quer os comandos versionados junto com o repositório, em .claude/commands/:

# npm / npx
npx @fontdata/ai-commands init

# yarn
yarn dlx @fontdata/ai-commands init

# pnpm
pnpm dlx @fontdata/ai-commands init

Ou instale o CLI globalmente uma vez:

npm i -g @fontdata/ai-commands
fontdata-ai-commands init

Instalados assim, os comandos são invocados sem prefixo: /harness, /gerar-spec, etc.

Outros comandos do CLI

npx @fontdata/ai-commands list     # lista todos os comandos do catálogo
npx @fontdata/ai-commands --help   # ajuda

O que o init faz

Fluxo interativo:

1. Pergunta a pasta do projeto (padrão: pasta atual).
2. Detecta se o projeto é novo ou existente (manifestos de stack, arquivos .sln/.csproj, pastas de código com conteúdo) e avisa o que isso muda na seleção manual.
3. Pergunta o que instalar: Conjunto recomendado, Tudo ou Escolher manualmente (seleção por categoria).
   • Em Escolher manualmente, projeto novo já vem com os comandos recomendados marcados; projeto existente vem vazio (ideal para cadastrar comandos avulsos).
4. Pergunta se quer o comando-mestre /harness (conduz a sequência de setup em ordem). Se escolhido, o init inclui automaticamente os comandos que o /harness depende, mesmo que não tenham sido marcados. O mesmo vale para dependências entre comandos (campo requires no catálogo): ao instalar um comando que depende de outro, o dependente entra junto automaticamente.
5. Pergunta se deve criar/atualizar o CLAUDE.md base na raiz (com opção de .bak se já existir).
6. Copia os comandos para .claude/commands/ e mostra um resumo. Em caso de conflito, pergunta se sobrescreve ou pula.
7. Instala em .claude/skills/ as skills exigidas pelos comandos escolhidos (campo requiresSkills no catálogo) — hoje, /auditar-seguranca puxa a skill lgpd-checker.

Skills instaláveis

Algumas skills acompanham comandos e são instaladas junto com eles, em .claude/skills/<id>/.

| Skill | Vem com | O que faz | |---|---|---| | lgpd-checker | /auditar-seguranca | Analisa conformidade com a LGPD (Lei nº 13.709/2018) em 11 categorias, com checklist, artigos de referência e template de relatório. |

A skill lgpd-checker é uma cópia vendorizada de bittencourtthulio/lgpd-checker; veja templates/skills/lgpd-checker/ORIGEM.md para créditos e instruções de atualização.

Modelo de arquivos do harness

| Arquivo | Local | Papel | |--------|-------|-------| | SPEC.md | raiz | Definição principal e completa do projeto (única). | | CLAUDE.md | raiz | Context file lido em toda sessão. | | docs/specs/AAAA-MM-DD-*.md | docs/specs/ | Specs complementares: o start inicial e cada nova tarefa. | | docs/plans/AAAA-MM-DD-*.md | docs/plans/ | Plano de implementação de cada spec complementar. | | docs/bugs/AAAA-MM-DD-<slug>.md | docs/bugs/ | Plano de correção de bugs (via /resolver-bug). |

Comandos instaláveis

⭐ = incluído no Conjunto recomendado.

Setup inicial

• /validar-ideia ⭐ — valida se a ideia cabe em ~4h com multi-agents
• /gerar-spec ⭐ — entrevista e gera o SPEC.md principal na raiz
• /gerar-claude-md ⭐ — gera o CLAUDE.md a partir do SPEC
• /gerar-ignore — gera .claudeignore e .gitignore
• /scaffold ⭐ — estrutura inicial, rota /health e testes de smoke

O plano do start inicial é gerado pelo /nova-tarefa (veja Slash commands & dia a dia).

Orquestração & implementação

• /executar-plan ⭐ — orquestra a execução do plano com sub-agents em paralelo
• /configurar-orquestrador — configura o agente orquestrador no CLAUDE.md
• /corrigir-review — organiza correções em sprints/fases/tasks com TDD
• /review-por-task — enforça implementação → review isolado → correção

Harness (agents/skills/hooks/rules)

• /criar-skill — cria skills do projeto em .claude/skills/
• /criar-agents — cria agents especializados em .claude/agents/
• /criar-hooks — cria hooks por agent em .claude/hooks/
• /criar-rules — cria rules em .claude/rules/
• /configurar-comentarios ⭐ — instala o padrão de comentários em três camadas: a rule .claude/rules/comentarios.md (orçamento duro e contra-exemplos), o bloco autossuficiente no CLAUDE.md e o hook PostToolUse bloqueante com catraca sobre o código legado — em qualquer linguagem, inclusive Delphi/Pascal
• /criar-code-reviewer ⭐ — cria o agent code-reviewer (somente leitura)

Slash commands & dia a dia

• /resolver-bug ⭐ — investiga, planeja em docs/bugs e corrige um bug
• /nova-tarefa ⭐ — gera spec+plano em docs/ (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador

Qualidade & manutenção de código

• /gerar-testes — detecta cobertura faltante e escreve testes seguindo TDD (RED→GREEN)
• /refatorar — refatora usando os testes como rede de segurança, sem mudar comportamento
• /codigo-morto — varre o projeto em busca de código morto e propõe remoção segura
• /atualizar-deps — atualiza dependências em lotes, testando a cada passo

Documentação & onboarding

• /sincronizar-claude-md — aponta onde o CLAUDE.md/SPEC.md divergiu do código
• /diagrama — gera diagramas Mermaid de arquitetura/fluxo a partir do código
• /onboarding — gera um guia de onboarding (rodar, entender e contribuir) em docs/
• /gerar-env — monta o .env.example a partir das variáveis lidas no código

Avançado

• /criar-rag — sistema de RAG (SQLite + sqlite-vec) para capturar aprendizados
• /auditar-ui — navega a app via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y)
• /design-system — cria o agent de design system com skills e rules
• /auditar-performance — audita gargalos de performance (queries, bundle, renders)
• /auditar-seguranca — auditoria defensiva (segredos, deps, inputs, configs) + conformidade LGPD via skill lgpd-checker

Manutenção & validação

• /validar-commands — audita .claude: valida models dos agents, aponta redundâncias e sugere novos commands

Utilitário

• /git-commit-push ⭐ — gera mensagem (PT-BR, Conventional Commits) e faz add/commit/push
• /versao ⭐ — detecta o versionamento da stack atual (React+Vite/Next, Node, Delphi, .NET, Flutter…) e aplica o bump de versão + changelog + commit de release (gate de aprovação, sem push). Autossuficiente: gera o changelog amigável dos commits internamente, sem depender de outros comandos.
• /configurar-auto-tag ⭐ — detecta o padrão de versionamento (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na main. Separa versionar (/versao, humano) de taguear/deployar (automático). Documenta a pegadinha GITHUB_TOKEN × RELEASE_PAT.
• /revisar-pr — revisa um PR ou o diff atual, classificando os achados

Comando-mestre

• /harness — conduz a sequência de setup em ordem, validando entre etapas

Fluxo recomendado

A forma mais simples é rodar o comando-mestre /harness, que conduz toda a sequência abaixo em ordem, parando para validar entre as etapas. Ele pergunta logo no início se o projeto é novo ou existente e ajusta o fluxo.

Projeto novo — sequência completa:

/validar-ideia → /gerar-spec → /gerar-claude-md → /gerar-ignore
→ /nova-tarefa (plano do start) → /scaffold
→ /configurar-comentarios → /criar-skill → /criar-agents → /criar-code-reviewer → /criar-rules → /criar-hooks → /configurar-orquestrador
→ /executar-plan

As skills vêm antes dos agents (os agents dependem delas).

Projeto existente — documenta e monta o harness sobre o código que já existe, pulando validação de ideia, plano do start, scaffold e execução:

/gerar-spec → /gerar-claude-md → /gerar-ignore
→ /configurar-comentarios → /criar-skill → /criar-agents → /criar-code-reviewer → /criar-rules → /criar-hooks → /configurar-orquestrador

No dia a dia: /nova-tarefa, /resolver-bug, /git-commit-push e /versao (para publicar uma nova versão).

Desenvolvimento

npm install
node bin/cli.js list
node bin/cli.js harness                    # roda na pasta atual, com o plugin local
node bin/cli.js init ./caminho-de-teste
claude plugin validate .                   # valida o manifesto do plugin

Os templates ficam em templates/ (commands/*.md + skills/ + CLAUDE.md + catalog.json). Para adicionar um comando: crie o .md em templates/commands/ e registre-o em templates/catalog.json.

A raiz do pacote também é um plugin do Claude Code: .claude-plugin/plugin.json aponta commands e skills para dentro de templates/, então não há duplicação de arquivos — a mesma pasta serve o init (cópia) e o modo sem instalação (--plugin-dir). Ao subir a versão, atualize version no package.json e no plugin.json.