Trabajar con agentes de codificación desde la terminal.
Un agente de codificación de terminal, como Claude Code o Codex, puede llevar una tarjeta Kanera desde que la recoge hasta que la termina: leer la tarjeta, anunciar que está funcionando, informar el progreso, marcar cuándo necesita una persona y marcar la tarjeta como completa. Esta guía configura ese bucle con el Kanera CLI, que funciona para cualquier agente que pueda ejecutar comandos de shell.
Instalar e iniciar sesión
Instale la CLI una vez en la máquina en la que se ejecuta el agente. Necesita el Nodo 22 o más reciente.
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login imprime un enlace y un código y abre el enlace en su navegador. Apruebe la solicitud allí después de verificar las coincidencias del código y la CLI almacenará un inicio de sesión que se renovará. Para un agente que se ejecuta desatendido, como en CI, use kanera auth login --with-api-key con una llave de Configuración de perfil -> Claves API en su lugar, y elija Sólo lectura si no debe cambiar nada. Luego confirme lo que el agente podrá hacer:
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
Para un trabajo de Sandbox o CI, omita el perfil almacenado y configure KANERA_API_KEY en cambio. Ver Kanera CLI para perfiles con nombre y direcciones autohospedadas.
Sólo lectura o escritura
Elija el alcance de la clave para el trabajo, no por conveniencia.
- Sólo lectura se adapta a un agente que sólo necesita encontrar y leer el trabajo: clasificar, resumir una tarjeta antes de comenzar o responder "¿qué tengo en el plato?". Kanera rechaza todos los cambios en la API, independientemente de lo que intente el agente.
- escribir es necesario para todo lo demás en esta página: abrir una carrera, comentar y completar tarjetas. Kanera aún verifica tu rol en cada tablero, por lo que el agente no puede cambiar un tablero en el que eres observador.
Una escritura rechazada sale con código 4, distinto de una falla ordinaria, por lo que el agente puede detenerse y avisarle en lugar de volver a intentarlo. Seguridad del agente cubre cómo determinar el alcance del acceso de un agente.
Instalar las instrucciones del agente
kanera setup escribe instrucciones que enseñan al agente cómo usar la CLI de forma segura: primero verifique el alcance de la clave, descubra comandos con kanera commands --json en lugar de adivinar, usa --quiet o --json al analizar la salida y tratar las herramientas destructivas como si necesitaran una solicitud 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 la habilidad de agente de Kanera, que Claude Code carga cuando aparece Kanera. No sobrescribirá un existenteSKILL.md; volver a ejecutar con--forcepara reemplazarlo después de actualizar la CLI.setup codexcreaAGENTS.mdsi no existe, o agrega una breve sección Kanera. Es seguro volver a ejecutarlo: cuando el archivo ya documenta Kanera, no cambia nada.kanera setup agentshace lo mismo, para cualquier agente que leaAGENTS.md.
Ambos objetivos de configuración incluyen el ciclo de trabajo: cuando se le pide que ejecute una tarjeta, el agente inicia una ejecución, mantiene visible el progreso, comenta su resultado y mueve la tarjeta a la lista apropiada antes de su respuesta final. Las preguntas de solo lectura, los planes exploratorios, las solicitudes de solo borrador y los límites explícitos no autorizan estas escrituras. Las instalaciones existentes mantienen sus antiguas instrucciones: después de actualizar, actualice la habilidad Claude con --force, o actualizar la sección Kanera existente en AGENTS.md usando la corriente kanera skill salida. Adaptar el instrucciones del proyecto a continuación para su flujo de trabajo.
El circuito de trabajo
Cada paso a continuación es un comando que ejecuta el agente. Los argumentos de la tarjeta aceptan una clave como MKT-42, una identificación de tarjeta o una URL de tarjeta.
1. Recoger trabajo
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 Es útil cuando mantienes un Próximas cola: el agente puede tomar la carta superior en lugar de elegirla por sí mismo.
2. Abrir una carrera
Antes del trabajo sustancial, lea los comentarios relevantes y la configuración del tablero, verifique que no haya nadie más en la tarjeta y luego abra una ejecución. Reanuda tu propia carrera en vivo para la misma tarea; informar la ejecución en vivo de otro agente antes de realizar trabajos superpuestos:
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)
El mosaico de la tarjeta ahora muestra un chip activo que indica que el agente está trabajando y los detalles de la tarjeta muestran la ejecución con su título y nota de progreso. --externalUrl es opcional; proporciónele la solicitud de extracción, la rama o el registro de sesión que una persona puede abrir. Ver Ejecuciones de agentes y atribución por lo que todos los demás ven.
Registre el ID de lista original, el nombre y el significado del flujo de trabajo de la tarjeta antes de moverla. uso kanera card move para colocarlo en la lista disponible que representa el trabajo activo en el flujo de trabajo de este tablero. Las carreras no mueven cartas. Resuelva la lista desde la configuración del tablero y omita el movimiento si ya está allí; kanera help cards.move describe los argumentos de anclaje requeridos. No asuma que todos los tableros utilizan la plantilla de flujo de trabajo del agente.
3. Informar el progreso
Actualice la ejecución a medida que avanza el trabajo. Cada actualización es también un latido, y se marca una ejecución que dura quince minutos sin una. estancado, por lo que en tareas largas el agente debe actualizar al menos cada diez minutos.
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
El resumen de ejecución es una línea de estado que reemplaza cada actualización. Para cualquier cosa que el equipo deba conservar, comenta en la tarjeta:
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
Dale a cada comentario deseado o ejecuta la creación una nueva versión. --idempotencyKey UUID y reutilícelo solo cuando vuelva a intentar escribir después de un error ambiguo. Si se perdió una respuesta sin una clave, verifique la tarjeta antes de volver a intentarlo para evitar duplicados.
4. Marcar un bloqueador
Cuando el agente necesita una decisión, una aprobación o un acceso que no tiene, marca la ejecución blocked y decir lo que necesita:
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."
El chip se vuelve ámbar y se muestran los detalles de la tarjeta. esperando por ti. Marcar una carrera bloqueada no notifica a nadie por sí solo, por eso el comentario es importante: llega a los observadores y asignados de la tarjeta. Elija una lista que refleje el bloqueador en el flujo de trabajo de este tablero. Cuando el agente se reanuda, vuelve a establecer la ejecución en --status running y mueve la tarjeta de nuevo a la lista activa.
Si otra tarjeta es el requisito previo, cree también una dependencia de la tarjeta: kanera card block API-42 WEB-18 significa que API-42 bloquea WEB-18. Una ejecución bloqueada describe el estado del agente; no crea esta relación. uso kanera work --filters.blockedOnly true para encontrar tarjetas de espera, y kanera deps WEB-18 para leer sus requisitos previos directos y la cadena transitiva ascendente/descendente.
5. Terminar
Antes de la respuesta final, publique un comentario de resultado duradero con lo que cambió o se encontró, la verificación y sus resultados (incluidas las fallas o comprobaciones omitidas), los vínculos de relaciones públicas/compromisos/artefactos relevantes y el trabajo o las decisiones restantes. Marque sólo los elementos de la lista de verificación realmente completados. Luego finalice la ejecución y enrute la tarjeta:
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
El resumen de cierre de la ejecución se convierte en un terminado fila en actividad; no reemplaza el comentario de resultado, no mueve la tarjeta ni la completa. Una ejecución exitosa puede cubrir sólo una parte de una tarjeta. Complete la tarjeta solo cuando el flujo de trabajo acordado lo permita y se cumplan sus criterios.
Antes de mover la tarjeta, vuelva a leerla y su tablero. Considere la lista original, las listas actualmente disponibles y sus significados, lo que se completó y lo que queda. Elija la lista que mejor represente el estado real de la tarjeta en el flujo de trabajo de esta tablero. Volver a la lista original puede ser apropiado, pero no es automático. No asuma nombres de listas ni elija solo del orden de la lista o de la configuración en progreso. Explique la elección en el comentario del resultado.
Si el trabajo asignado no se pudo completar, explique lo que queda y finalice la ejecución con --status failed o --status cancelled. mantener blocked sólo cuando realmente se espera reanudar; No dejar funcionando el trabajo parado. Una ejecución finalizada no se puede cambiar; Si el trabajo se reanuda más tarde, comience una nueva ejecución.
Verifique la lista de tarjetas resultante, el comentario del resultado y el estado de ejecución a partir de los resultados de escritura y una lectura nueva. Tenga en cuenta las automatizaciones y el movimiento de intervención de un compañero de equipo. Si no hay ningún destino claro, deje la lista actual sin cambios, guarde las actualizaciones de ejecución/comentario que pueda y solicite solo la opción de ruta que falta. Si se rechaza una escritura, informe la restricción y qué pasos de seguimiento permanecen sin guardar; no implican éxito. La respuesta final debe vincular la tarjeta e indicar su lista resultante y el estado de ejecución.
¿A quién se atribuye la obra?
La forma en que la CLI inició sesión decide cómo se etiqueta el trabajo del agente:
| Credencial | Comentarios y cambios de tarjeta. | Ejecutar etiqueta de chip |
|---|---|---|
Iniciar sesión en el navegador con --agent (kanera auth login --agent "Claude Code") | Como tú, a través de Claude Code (Kanera CLI en el nombre de la computadora) | Código Claude (Kanera CLI en el nombre de la computadora) |
Iniciar sesión en el navegador sin --agent | Como tú, a través de Kanera CLI (nombre de la computadora) | Kanera CLI (nombre de la computadora) |
| Clave API personal | Como tú, sin vía insignia | cliente API |
| Clave API del espacio de trabajo o del tablero | Como el nombre de la clave | El nombre de la clave |
Un inicio de sesión en el navegador es una conexión de dispositivo OAuth, por lo que el trabajo del agente conlleva una vía insignia, se agrupa por separado en sus notificaciones y se mantiene aparte de su propio trabajo en Trabajo realizado, al igual que en MCP. Kanera solo ve la CLI, así que nombre el agente cuando inicie sesión con --agent (o KANERA_AGENT_NAME). El nombre está fijo para ese inicio de sesión; Dale a cada agente el suyo. perfil si varios comparten una máquina. A través de MCP, el agente se nombra a sí mismo; ver Configurar Claude o Configurar el códice. kanera mcp, el servidor MCP local de la CLI, utiliza la misma credencial almacenada y, por lo tanto, la misma atribución que la CLI.
Agréguelo a las instrucciones de su proyecto
la corriente kanera setup claude y kanera setup codex Las instrucciones incluyen este bucle. Para hacer explícita la política de aceptación de su proyecto, adapte esta sección en CLAUDE.md o 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.
Emparéjelo con una clave de escritura. Con una clave de solo lectura, conserve solo los pasos de lectura.