Kanbino - Agente de IA - Switch Kanban

O que é o Kanbino?

Kanbino é um agente de IA integrado ao Switch Kanban que automatiza tarefas de desenvolvimento usando Claude Code da Anthropic. Ele recebe uma tarefa, planeja a implementação, executa o código e cria Pull Requests automaticamente no seu repositório.

Para habilitar essa funcionalidade entre em contato com o time comercial

Como funciona

O Kanbino opera em duas fases:

1. Planejamento (Plan)

Analisa a tarefa solicitada
Examina o contexto do projeto
Gera um plano de implementação detalhado
Identifica arquivos e mudanças necessárias

2. Execução (Execute)

Implementa o código seguindo o plano
Cria/modifica arquivos necessários
Executa testes e validações
Cria Pull Request com as mudanças

Modos de Execução

O Kanbino suporta dois modos de execução:

Kubernetes

Executa em containers isolados no cluster da Switch

GitHub Actions

Executa diretamente no repositório do cliente via workflows

Kubernetes (Padrão)

Onde roda: Cluster kubernetes gerenciado pelo Switch Kanban
Vantagens: Controle total, isolamento, não requer configuração no cliente
Requisitos: Nenhum setup adicional no repositório do cliente
Desvantagens: Não é possível customizar o ambiente em qual a AI será executada

GitHub Actions

Onde roda: Runners do GitHub Actions no repositório do cliente
Vantagens: Execução no ambiente do cliente, transparência total, sem dependências externas
Requisitos: Workflow e secrets configurados no repositório
Desvantagens: Requer configuração no repositório do cliente

O modo GitHub Actions elimina a necessidade de infraestrutura externa, executando tudo dentro do próprio repositório do cliente usando a action oficial da Anthropic.

Arquitetura GitHub Actions

Switch Kanban → Dispara workflow → GitHub Actions
                                          ├─ Callbacks (nosso)
                                          ├─ Claude Code (Anthropic oficial)
                                          └─ Create PR (community)

A nossa Kanbino Action funciona como wrapper sobre a action oficial da Anthropic, adicionando:

✅ Callbacks integrados ao Switch Kanban
✅ Criação automática de Pull Requests
✅ Sincronização de status em tempo real

Fluxo de Trabalho

Criação da Tarefa: Desenvolvedores criam uma tarefa no Switch Kanban
Acionamento: Usuário clica em “Executar Kanbino” na interface
Planejamento: Kanbino analisa e gera o plano de implementação
Revisão: Time revisa o plano gerado
Execução: Após aprovação, Kanbino implementa as mudanças
Pull Request: PR é criado automaticamente com as alterações
Code Review: Time revisa o código como em qualquer PR normal

Configuração

Para Modo Kubernetes

Nenhuma configuração adicional é necessária. O Kanbino já está pronto para uso.

Para Modo GitHub Actions

API Keys

Obtenha duas chaves:

Switch Kanban API Key: Gerada em Configurações da Empresa → API
Claude Code OAuth Token: Obtida em console.anthropic.com → API Keys → Create Key (selecione “Claude for GitHub”)

Use Claude Code OAuth Token ao invés de API Key regular para melhor integração com GitHub Actions.

GitHub Secrets

Configure no repositório em Settings → Secrets and variables → Actions:

SWITCH_KANBAN_API_KEY - Token da sua empresa no Switch Kanban
CLAUDE_CODE_OAUTH_TOKEN - OAuth token do Claude Code (recomendado)

Alternativamente, você pode usar KANBINO_API_KEY com uma API key regular da Anthropic, mas o OAuth token é preferível.

Workflow

Crie .github/workflows/kanbino.yml com o seguinte conteúdo mínimo:

name: Kanbino Agent

on:
  workflow_dispatch:
    inputs:
      mode:
        required: true
        type: choice
        options: [plan, execute]
      task_execution_id:
        required: true
        type: string
      callback_url:
        required: true
        type: string
      task_prompt:
        required: true
        type: string

jobs:
  kanbino:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      # Configure o ambiente do seu projeto aqui
      # Exemplos: instalar dependências, setup de Ruby/Node, etc.

      - uses: SwitchDreams/kanbino-action@latest
        with:
          mode: ${{ inputs.mode }}
          task_execution_id: ${{ inputs.task_execution_id }}
          callback_url: ${{ inputs.callback_url }}
          task_prompt: ${{ inputs.task_prompt }}
          switch_kanban_api_key: ${{ secrets.SWITCH_KANBAN_API_KEY }}
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          # Altamente recomendado: permita que o Kanbino execute ferramentas do seu projeto
          additional_allowed_tools: 'Bash(npm:*),Bash(bundle exec:*),Bash(pytest:*)'

Configuração de Ambiente: É altamente recomendado configurar o ambiente do seu projeto antes de executar o Kanbino. Isso inclui:

Instalar dependências (npm install, bundle install, pip install, etc.)
Configurar linguagens (Ruby, Node, Python, etc.)
Setup de banco de dados (se necessário para testes)

Isso permite que o Kanbino execute linters, testes e outras ferramentas do seu projeto durante a implementação.

Permissões

Certifique-se que o workflow tem as permissões necessárias:

contents: write - Para fazer commits
pull-requests: write - Para criar PRs

Essas permissões já estão incluídas no template acima.

Segurança: NUNCA exponha API keys em código ou logs. Use exclusivamente GitHub Secrets para credenciais sensíveis.

Ferramentas Adicionais (Altamente Recomendado)

O parâmetro additional_allowed_tools permite que o Kanbino execute comandos específicos do seu projeto, melhorando significativamente a qualidade das implementações.

Por que configurar?

Sem ferramentas adicionais, o Kanbino tem acesso limitado apenas a comandos básicos de Git e leitura de arquivos. Ao configurar additional_allowed_tools, você permite que ele:

✅ Execute linters e formatadores do seu projeto
✅ Rode testes automatizados
✅ Valide o código antes de criar o PR
✅ Execute builds e verificações de tipo
✅ Use ferramentas específicas do seu stack

Exemplos por Stack

Rails
Node/React
Python
Go

additional_allowed_tools: 'Bash(bundle exec rubocop:*),Bash(bundle exec rspec:*),Bash(rails:*)'

Permite executar Rubocop (linter), RSpec (testes) e comandos Rails.

additional_allowed_tools: 'Bash(npm:*),Bash(yarn:*),Bash(pnpm:*),Bash(npx eslint:*)'

Permite executar gerenciadores de pacotes e ESLint.

additional_allowed_tools: 'Bash(pytest:*),Bash(pylint:*),Bash(black:*),Bash(mypy:*)'

Permite executar pytest (testes), pylint/black (linting/formatação) e mypy (type checking).

additional_allowed_tools: 'Bash(go:*),Bash(gofmt:*),Bash(golint:*)'

Permite executar comandos Go, formatação e linting.

Sintaxe

O formato é uma lista separada por vírgulas: 'Bash(comando:*),Bash(outro:*)'

Bash(npm:*) - Permite qualquer comando npm (npm install, npm test, etc.)
Bash(bundle exec rubocop:*) - Permite rubocop via bundle exec
Bash(pytest:*) - Permite executar pytest

Segurança: Use wildcards (*) com cuidado. Configure apenas comandos seguros e conhecidos do seu projeto. Evite permissões muito amplas como Bash(*:*).

Exemplo Completo (Rails + Node)

- uses: ruby/setup-ruby@v1
  with:
    ruby-version: 3.3.0
    bundler-cache: true

- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'

- run: npm install
- run: bundle install

- uses: SwitchDreams/kanbino-action@latest
  with:
    mode: ${{ inputs.mode }}
    task_execution_id: ${{ inputs.task_execution_id }}
    callback_url: ${{ inputs.callback_url }}
    task_prompt: ${{ inputs.task_prompt }}
    switch_kanban_api_key: ${{ secrets.SWITCH_KANBAN_API_KEY }}
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    additional_allowed_tools: 'Bash(bundle exec rubocop:*),Bash(bundle exec rspec:*),Bash(npm:*),Bash(npx:*)'

Casos de Uso

O Kanbino é ideal para:

✅ Implementar features bem definidas
✅ Corrigir bugs específicos
✅ Refatorações planejadas
✅ Adicionar testes automatizados
✅ Atualizar documentação técnica

Melhores resultados: Tarefas claras e bem descritas geram implementações melhores. Inclua contexto, requisitos e exemplos na descrição da tarefa.

Limitações

Requer descrição clara da tarefa
Funciona melhor com mudanças focadas e específicas
Não substitui revisão humana de código
Consome créditos da API da Anthropic
Timeout padrão de 30 minutos por execução

Troubleshooting

Action não inicia

Problema: Workflow não dispara ou falha imediatamente. Verificações:

Confirme que os secrets estão configurados corretamente em Settings → Secrets and variables → Actions
Confirme que o workflow tem as permissões necessárias (contents: write, pull-requests: write)
Verifique se o workflow está usando SwitchDreams/kanbino-action@latest (não a pasta local .github/actions/kanbino)

Claude Code falha

Problema: Action oficial da Anthropic retorna erro. Verificações:

Verifique se o CLAUDE_CODE_OAUTH_TOKEN está válido e não expirou
Confirme que você tem créditos disponíveis na sua conta Anthropic
Revise os logs detalhados no GitHub Actions para mensagens de erro específicas

Callbacks não chegam

Problema: Switch Kanban não recebe atualizações de status. Verificações:

Confirme que SWITCH_KANBAN_API_KEY está correto
Verifique se a URL do callback está acessível (tente fazer um curl de teste)
Revise os logs do step “Send callback” no workflow

Pull Request não é criado

Problema: Execução completa mas PR não aparece. Verificações:

Confirme que o modo foi execute (modo plan não cria PR)
Verifique se houve mudanças no código (no-changes não gera PR)
Revise permissões do workflow: contents: write e pull-requests: write
Veja os logs do step “Create Pull Request”

Recursos Adicionais

📚 Repositório da Kanbino Action - Código-fonte e documentação técnica
🤖 Claude Code Base Action - Action oficial da Anthropic
📖 Documentação do Claude Code - Guias e referências

Suporte

Para problemas ou dúvidas:

Verifique os logs detalhados no GitHub Actions
Consulte a seção de Troubleshooting acima
Entre em contato com o suporte do Switch Kanban
Abra uma issue no repositório da Kanbino Action

Essenciais

Integrações

Kanbino - Agente de IA

O que é o Kanbino?

Como funciona

1. Planejamento (Plan)

2. Execução (Execute)

Modos de Execução

Kubernetes

GitHub Actions

Kubernetes (Padrão)

GitHub Actions

Arquitetura GitHub Actions

Fluxo de Trabalho

Configuração

Para Modo Kubernetes

Para Modo GitHub Actions

Ferramentas Adicionais (Altamente Recomendado)

Por que configurar?

Exemplos por Stack

Sintaxe

Exemplo Completo (Rails + Node)

Casos de Uso

Limitações

Troubleshooting

Action não inicia

Claude Code falha

Callbacks não chegam

Pull Request não é criado

Recursos Adicionais

Suporte

Essenciais

Integrações

​O que é o Kanbino?

​Como funciona

​1. Planejamento (Plan)

​2. Execução (Execute)

​Modos de Execução

Kubernetes

GitHub Actions

​Kubernetes (Padrão)

​GitHub Actions

​Arquitetura GitHub Actions

​Fluxo de Trabalho

​Configuração

​Para Modo Kubernetes

​Para Modo GitHub Actions

​Ferramentas Adicionais (Altamente Recomendado)

​Por que configurar?

​Exemplos por Stack

​Sintaxe

​Exemplo Completo (Rails + Node)

​Casos de Uso

​Limitações

​Troubleshooting

​Action não inicia

​Claude Code falha

​Callbacks não chegam

​Pull Request não é criado

​Recursos Adicionais

​Suporte

O que é o Kanbino?

Como funciona

1. Planejamento (Plan)

2. Execução (Execute)

Modos de Execução

Kubernetes (Padrão)

GitHub Actions

Arquitetura GitHub Actions

Fluxo de Trabalho

Configuração

Para Modo Kubernetes

Para Modo GitHub Actions

Ferramentas Adicionais (Altamente Recomendado)

Por que configurar?

Exemplos por Stack

Sintaxe

Exemplo Completo (Rails + Node)

Casos de Uso

Limitações

Troubleshooting

Action não inicia

Claude Code falha

Callbacks não chegam

Pull Request não é criado

Recursos Adicionais

Suporte