Trabalhe com agentes de codificação do terminal
Um agente de codificação de terminal como Claude Code ou Codex pode levar um cartão Kanera da coleta até a conclusão: ler o cartão, anunciar que está funcionando, relatar o progresso, sinalizar quando precisa de uma pessoa e marcar o cartão como completo. Este guia configura esse loop com o Kanera CLI, que funciona para qualquer agente que possa executar comandos shell.
:::dica As ferramentas MCP conectadas vêm em primeiro lugar Se o seu agente puder se conectar ao servidor MCP hospedado do Kanera, use-o. Cole o prompt de configuração de Conecte Kanera ao seu agente de IA e o agente obtém as mesmas ferramentas pelo OAuth, com seu trabalho rotulado via <agente>. A CLI é a rota para um agente que possui um shell, mas não possui conexão MCP. O loop abaixo é o mesmo de qualquer maneira; apenas o transporte muda. :::
Instale e faça login
Instale a CLI uma vez na máquina em que o agente é executado. Precisa do Nó 22 ou mais recente.
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login imprime um link e um código e abre o link no seu navegador. Aprove a solicitação depois de verificar se o código corresponde, e a CLI armazena um login que se renova. Para um agente que funciona de forma autônoma, como em CI, use kanera auth login --with-api-key com uma chave de Configurações de perfil -> Chaves de API em vez disso, e escolha Somente leitura se não deveria mudar nada. Em seguida, confirme o que o agente poderá fazer:
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
Para um trabalho de sandbox ou CI, ignore o perfil armazenado e defina KANERA_API_KEY em vez disso. Ver Kanera CLI para perfis nomeados e endereços auto-hospedados.
Somente leitura ou gravação
Escolha o escopo da chave para o trabalho, não por conveniência.
- Somente leitura adequado para um agente que só precisa encontrar e ler o trabalho: fazer triagem, resumir um cartão antes de começar ou responder "o que está no meu prato?". Kanera recusa todas as alterações na API, independentemente do que o agente tente.
- Escreva é necessário para todo o resto desta página: abrir uma corrida, comentar e preencher cartões. Kanera ainda verifica sua função em cada quadro, portanto o agente não pode alterar um quadro onde você é um Observador.
Uma gravação recusada sai com código 4, diferente de uma falha comum, para que o agente possa parar e informar você em vez de tentar novamente. Segurança do agente aborda como definir o escopo do acesso de um agente.
Instale as instruções do agente
kanera setup escreve instruções que ensinam ao agente como usar a CLI com segurança: verifique primeiro o escopo da chave, descubra comandos com kanera commands --json em vez de adivinhar, use --quiet ou --json ao analisar a saída e tratar as ferramentas destrutivas como necessitando de uma solicitação explícita.
kanera setup claude # writes .claude/skills/kanera/SKILL.md in the current directory
kanera setup claude --global # writes ~/.claude/skills/kanera/SKILL.md for every project
kanera setup codex # adds a Kanera section to AGENTS.md in the current directory
kanera skill # prints the skill document, for any other agent
setup claudeinstala a habilidade de agente de Kanera, que Claude Code carrega quando Kanera aparece. Não substituirá um existenteSKILL.md; reexecutar com--forcepara substituí-lo após atualizar a CLI.setup codexcriaAGENTS.mdse não existir, ou anexa uma pequena seção Kanera. É seguro executar novamente: quando o arquivo já documenta Kanera, nada muda.kanera setup agentsfaz o mesmo, para qualquer agente que leiaAGENTS.md.
Ambos os objetivos de configuração incluem o ciclo de trabalho: quando solicitado a executar um cartão, o agente inicia uma execução, mantém o progresso visível, comenta seu resultado e move o cartão para a lista apropriada antes de sua resposta final. Perguntas somente leitura, planos exploratórios, solicitações somente rascunhos e limites explícitos não autorizam essas gravações. As instalações existentes mantêm as instruções antigas: após a atualização, atualize a habilidade de Claude com --forceou atualize a seção Kanera existente em AGENTS.md usando a corrente kanera skill saída. Adapte o instruções do projeto abaixo para o seu fluxo de trabalho.
O ciclo de trabalho
Cada etapa abaixo é um comando que o agente executa. Os argumentos do cartão aceitam uma chave como MKT-42, um ID de cartão ou um URL de cartão.
1. Pegue o trabalho
kanera work --json # your assigned work across every board
kanera work --filters.q "checkout" --json # narrowed by card text
kanera priorities --json # your ranked Up next queue
kanera card MKT-42 --json # the card itself: description, checklists, fields
kanera card history MKT-42 --json # its activity and comments
kanera priorities é útil quando você mantém um A seguir fila: o agente pode pegar a carta do topo em vez de escolher por si mesmo.
2. Abra uma corrida
Antes do trabalho substantivo, leia os comentários relevantes e a configuração do quadro, verifique se não há mais ninguém no cartão e, em seguida, abra uma execução. Retome sua própria execução ao vivo para a mesma tarefa; reportar a execução ao vivo de outro agente antes de realizar trabalho sobreposto:
kanera comments MKT-42 --json
kanera board <boardId> --json # lists and their actual IDs
kanera runs MKT-42 --json
RUN_ID=$(kanera run start MKT-42 "Fixing the checkout rounding bug" \
--externalUrl "https://github.com/acme/shop/pull/318" \
--quiet | jq -r .id)
O bloco do cartão agora mostra um chip ativo informando que o agente está trabalhando, e os detalhes do cartão mostram a execução com seu título e nota de progresso. --externalUrl é opcional; forneça a solicitação pull, branch ou log de sessão que uma pessoa pode abrir. Veja Execuções e atribuição de agentes pelo que todo mundo vê.
Registre o ID da lista original, o nome e o significado do fluxo de trabalho do cartão antes de movê-lo. Usar kanera card move para colocá-lo na lista disponível que representa o trabalho ativo no fluxo de trabalho deste quadro. As corridas não movem cartas. Resolva a lista da configuração do tabuleiro e pule a movimentação se ela já estiver lá; kanera help cards.move descreve os argumentos âncora necessários. Não presuma que todos os quadros usam o modelo de fluxo de trabalho do agente.
3. Relate o progresso
Atualize a execução à medida que o trabalho avança. Cada atualização também é um batimento cardíaco, e uma execução que dura quinze minutos sem uma é marcada parado, portanto, em tarefas longas, o agente deverá atualizar pelo menos a cada dez minutos.
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
O resumo da execução é uma linha de status que cada atualização substitui. Para qualquer coisa que a equipe deva manter, comente no card:
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
Dê a cada comentário pretendido ou execute a criação uma nova --idempotencyKey UUID e reutilizá-lo somente ao tentar novamente a gravação após uma falha ambígua. Se uma resposta foi perdida sem chave, verifique o cartão antes de tentar novamente para evitar duplicatas.
4. Sinalize um bloqueador
Quando o agente precisar de uma decisão, uma aprovação ou acesso que não possui, marque a execução blocked e diga o que precisa:
kanera run update "$RUN_ID" --status blocked \
--summary "Need a decision: round half up or half even?"
kanera comment MKT-42 "Blocked: should order totals round half up or half even? Both are drafted in PR 318."
O chip fica âmbar e os detalhes do cartão são exibidos Esperando por você. Marcar uma corrida como bloqueada não notifica ninguém por si só, por isso o comentário é importante: ele chega aos observadores e destinatários do cartão. Escolha uma lista que reflita o bloqueador no fluxo de trabalho deste quadro. Quando o agente retoma, ele define a execução de volta para --status running e move o cartão de volta para a lista ativa.
Se outro cartão for o pré-requisito, crie também um dependência de cartão: kanera card block API-42 WEB-18 significa que API-42 bloqueia WEB-18. Uma execução bloqueada descreve o status do agente; não cria esse relacionamento. Usar kanera work --filters.blockedOnly true para encontrar cartões em espera e kanera deps WEB-18 para ler seus pré-requisitos diretos e cadeia transitiva upstream/downstream.
5. Concluir
Antes da resposta final, poste um comentário de resultado durável com o que mudou ou foi encontrado, verificação e seus resultados (incluindo falhas ou verificações ignoradas), links relevantes de PR/commit/artefato e trabalho ou decisões restantes. Marque apenas os itens da lista de verificação realmente concluídos. Em seguida, encerre a execução e encaminhe o cartão:
kanera comment MKT-42 "Rounding is now per order. Focused regression checks pass; full suite not run. PR 318 is ready for review; merge and deployment remain."
kanera run done "$RUN_ID" "Implementation ready for review in PR 318"
kanera card move MKT-42 <destinationListId> --anchor '{"side":"after","id":null}'
kanera card MKT-42 --json
O resumo final da corrida torna-se um terminou linha em atividade; ele não substitui o comentário do resultado, não move o cartão nem o completa. Uma execução bem-sucedida pode cobrir apenas parte de uma carta. Preencha o cartão somente quando o fluxo de trabalho acordado permitir e seus critérios forem atendidos.
Antes de mover o cartão, releia-o e ao seu tabuleiro. Considere a lista original, as listas atualmente disponíveis e seus significados, o que foi concluído e o que resta. Escolha a lista que melhor representa o estado real do cartão no fluxo de trabalho deste quadro. Voltar à lista original pode ser apropriado, mas não é automático. Não assuma nomes de listas nem escolha apenas a ordem da lista ou a configuração em andamento. Explique a escolha no comentário do resultado.
Se o trabalho atribuído não puder ser concluído, explique o que resta e termine a execução com --status failed ou --status cancelled. Mantenha blocked somente quando estiver genuinamente esperando para retomar; não deixe o trabalho parado em execução. Uma execução finalizada não pode ser alterada; se o trabalho for retomado mais tarde, inicie uma nova execução.
Verifique a lista de cartões resultante, o comentário do resultado e o status da execução a partir dos resultados da gravação e de uma nova leitura. Considere as automações e o movimento de intervenção de um colega de equipe. Se nenhum destino estiver claro, deixe a lista atual inalterada, salve as atualizações de execução/comentário que puder e solicite apenas a opção de rota ausente. Caso uma gravação seja recusada, informe a restrição e quais etapas de rastreamento permanecem não salvas; não implica sucesso. A resposta final deve vincular o cartão e indicar a lista resultante e o status da execução.
A quem a obra é atribuída
A forma como a CLI conectada decide como o trabalho do agente é rotulado:
| Credencial | Comentários e alterações de cartão | Execute a etiqueta do chip |
|---|---|---|
Login do navegador com --agent (kanera auth login --agent "Claude Code") | Como você, via Claude Code (Kanera CLI no nome do computador) | Código Claude (Kanera CLI no nome do computador) |
Login do navegador sem --agent | Como você, via Kanera CLI (nome do computador) | Kanera CLI (nome do computador) |
| Chave de API pessoal | Como você, sem através de distintivo | Cliente API |
| Chave de API do espaço de trabalho ou quadro | Como o nome da chave | O nome da chave |
O login do navegador é uma conexão de dispositivo OAuth, portanto, o trabalho do agente carrega um através de crachá, agrupa-se separadamente em suas notificações e é mantido separado de seu próprio trabalho em Trabalho concluído, da mesma forma que no MCP. Kanera vê apenas a CLI, então nomeie o agente ao entrar com --agent (ou KANERA_AGENT_NAME). O nome é fixo para esse login; dê a cada agente o seu próprio perfil se vários compartilham uma máquina. No MCP o agente se nomeia; veja Configure Cláudio ou Configurar o Codex. kanera mcp, o servidor MCP local da CLI, usa a mesma credencial armazenada e, portanto, a mesma atribuição que a CLI.
Adicione-o às instruções do seu projeto
O atual kanera setup claude e kanera setup codex as instruções incluem este loop. Para tornar explícita a política de aceitação do seu projeto, adapte esta seção em CLAUDE.md ou AGENTS.md:
## Kanera card work
Use connected Kanera MCP tools when available, otherwise the Kanera CLI.
When asked to carry out a card, keep it updated as part of the assignment:
- Read the card, relevant comments and board lists; record the original list ID/name/meaning and check for another live agent run.
- Start a run before substantive work and move to the board's active list.
- Keep progress current at milestones and at least every ten minutes.
- When blocked, update the run, comment what you need and move to the waiting list.
- Before the final reply, comment changes, checks/results, relevant links and remaining work.
- End the run appropriately. Re-read the card and board; consider the original list, available lists
and their meanings, completed work and remaining work. Choose the list that reflects the card's
actual state in this board's workflow, without assuming names or automatically restoring its
original list. Explain the choice in the comment. If unclear, leave the list unchanged and ask.
Complete the card only when the agreed workflow permits it and its criteria are met.
- Verify the saved comment, run status and card list; report any tracking writes that failed.
- Read-only or exploratory requests cause no tracking writes; explicit user limits win.
Combine-o com uma chave de gravação. Com uma chave somente leitura, mantenha apenas as etapas de leitura.