Desenvolvimento local

As tarefas de um Playbook rodam na sua máquina, no Claude Code, com o mesmo plugin de instrumentação de produção. Fora do Kadu esse plugin entra sozinho em modo de simulação (dry-run): tudo o que iria para o console é só impresso no terminal.

Preparar

Pré-requisitos: Claude Code, jq e curl no PATH, e credenciais de teste dos sistemas externos.

1. Secrets de teste. Copie o modelo versionado e preencha:

   cp sandbox/.env.example sandbox/.env    # sandbox/.env fica fora do git
   set -a; source sandbox/.env; set +a

   Não exporte GITHUB_ACTIONS: a ausência dela é o que mantém a simulação ligada.

2. Plugins, no Claude Code. Instale o kadu (instrumentação) e os plugins do seu Playbook:

   /plugin marketplace add Kadu-Kobs/kadu-kobs-core
   /plugin install kadu@kadu-kobs-core
   
   /plugin marketplace add <dono>/<seu-repositorio>
   /plugin install finance@<nome-do-marketplace>

   O kadu-kobs-core é um repositório da Kobana. Se o marketplace add não o encontrar, peça acesso ao suporte Kobana. O que vai depois do @ é o name do marketplace.json, e não o nome do repositório. Para iterar no código local, adicione o marketplace pelo caminho (/plugin marketplace add ./ na raiz do repositório).

Rodar uma tarefa

Dispare pelo wrapper, como em produção:

/kadu:agent-run-task finance:task-baixar-pagamentos

Ou chame a skill direto (/finance:pagarme-atualizar-cadastro).

O que observar:

• Instrumentação simulada: cada evento, log, pendência e o resultado aparecem no stderr com o prefixo [dry-run POST ...] e são acumulados em $AGENT_MOCK_LOG (padrão /tmp/kadu_dryrun.ndjson), uma linha JSON por chamada:

  jq . /tmp/kadu_dryrun.ndjson

• Chamadas externas são reais. ERP, gateway, emissor de nota: nada disso passa pela simulação. Use credenciais de teste.

:::note Skill nova não aparece na sessão em que foi escrita O Claude Code lê o catálogo de plugins no início da sessão. Uma skill recém criada responde Unknown skill mesmo com o SKILL.md no disco. Reinicie a sessão, ou siga o corpo do SKILL.md à mão, que é o mesmo conteúdo. :::

Testar como CI

A simulação exercita o raciocínio da skill. Não exercita o encanamento de uma execução de verdade: o runner, a resolução do plugin pelo skill_slug, a entrega dos secrets da lista de permissão, o envio HTTP da instrumentação e o mascaramento.

O repositório da Kobana tem um sandbox de CI para isso (sandbox/ci/), que vale copiar: ele roda o workflow de execução localmente com o act e aponta a instrumentação para um mock da API de ingestão dentro do próprio job.

./sandbox/ci/run.sh smoke finance:task-baixar-pagamentos
./sandbox/ci/run.sh live  finance:task-baixar-pagamentos

	smoke	live
Chama o modelo de IA	não	sim (gasta tokens)
Executa a skill	não (um corpo de teste fixo)	sim
Efeito externo	nenhum	real
Prova	runner, plugin, lista de permissão, envio HTTP, mascaramento	a skill de ponta a ponta

:::danger O mock é obrigatório O plugin kadu decide entre simulação e envio real pela variável GITHUB_ACTIONS, e o act a define. Um act ingênuo, apontado para o console de produção, grava execução, eventos e pendências de verdade a partir de um teste local. O sandbox aborta se a URL do console não for localhost. :::

O smoke reprova o job quando chega uma chamada para uma rota que a ingestão não tem, quando falta autenticação, quando não chega nenhum evento, e quando um valor de secret aparece no que o mock recebeu (o canário do mascaramento).

O ciclo até produção

#	Etapa	Onde	Comando	O que prova
1	Escrever a skill	branch local	—	—
2	Simulação	Claude Code	/kadu:agent-run-task <plugin>:<skill>	o corpo da skill
3	Lint do workflow	terminal	actionlint	o shell dos blocos run:
4	Smoke de CI	terminal	./sandbox/ci/run.sh smoke <plugin>:<skill>	runner, plugin, secrets, envio, mascaramento
5	Live de CI	terminal	./sandbox/ci/run.sh live <plugin>:<skill>	a skill de ponta a ponta, com efeitos externos reais
6	Merge em main	GitHub	—	deploy do código
7	Sincronização	automática, ou Sincronizar	—	tarefa criada ou atualizada pelo frontmatter
8	Secrets	Configurações → Secrets	—	a execução recebe as variáveis de required_secrets
9	Primeiro disparo	console	Executar agora	histórico, logs, pendências e resultado aparecem como esperado

Os passos 2 e 4 se complementam, e nenhum substitui o outro: a simulação exercita a skill sem rede para o console; o smoke exercita o encanamento sem modelo de IA.