Travailler avec des agents de codage depuis le terminal
Un agent de codage de terminal tel que Claude Code ou Codex peut prendre une carte Kanera du ramassage à la fin : lire la carte, annoncer qu'elle fonctionne, signaler la progression, signaler quand elle a besoin d'une personne et marquer la carte comme complète. Ce guide définit cette boucle avec le Kanera CLI, qui fonctionne pour tout agent pouvant exécuter des commandes shell.
Installer et se connecter
Installez la CLI une fois sur la machine sur laquelle l'agent s'exécute. Il nécessite le nœud 22 ou une version plus récente.
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login imprime un lien et un code et ouvre le lien dans votre navigateur. Approuvez la demande après avoir vérifié les correspondances de code, et la CLI stocke une connexion qui se renouvelle. Pour un agent qui s'exécute sans surveillance, comme dans CI, utilisez kanera auth login --with-api-key avec une clé de Paramètres du profil -> Clés API à la place, et choisissez Lecture seule si cela ne change rien. Confirmez ensuite ce que l'agent pourra faire :
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
Pour une tâche sandbox ou CI, ignorez le profil stocké et définissez KANERA_API_KEY à la place. Voir Kanera CLI pour les profils nommés et les adresses auto-hébergées.
Lecture seule ou écriture
Choisissez la portée de la clé pour le travail, pas pour des raisons de commodité.
- Lecture seule convient à un agent qui n'a besoin que de trouver et de lire du travail : trier, résumer une fiche avant de commencer ou répondre « qu'est-ce qu'il y a dans mon assiette ? Kanera refuse toute modification de l'API, quelles que soient les tentatives de l'agent.
- Écrire est nécessaire pour tout le reste sur cette page : ouvrir une course, commenter et compléter des cartes. Kanera vérifie toujours votre rôle sur chaque tableau, donc l'agent ne peut pas modifier un tableau sur lequel vous êtes observateur.
Une écriture refusée se termine avec du code 4, distinct d'un échec ordinaire, afin que l'agent puisse s'arrêter et vous en informer plutôt que de réessayer. Sécurité des agents explique comment étendre l'accès d'un agent.
Instructions d'installation de l'agent
kanera setup écrit des instructions qui apprennent à l'agent comment utiliser la CLI en toute sécurité : vérifiez d'abord la portée de la clé, découvrez les commandes avec kanera commands --json au lieu de deviner, utilisez --quiet ou --json lors de l'analyse de la sortie, et traitez les outils destructeurs comme nécessitant une requête explicite.
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 claudeinstalle la compétence d'agent de Kanera, que Claude Code charge lorsque Kanera apparaît. Il n'écrasera pas un existantSKILL.md; relancer avec--forcepour le remplacer après la mise à niveau de la CLI.setup codexcréeAGENTS.mds'il n'existe pas, ou ajoute une courte section Kanera. Il est possible de réexécuter le fichier en toute sécurité : lorsque le fichier documente déjà Kanera, cela ne change rien.kanera setup agentsfait de même, pour tout agent qui litAGENTS.md.
Les deux cibles de configuration incluent la boucle de travail : lorsqu'il est invité à exécuter une carte, l'agent démarre une exécution, garde la progression visible, commente son résultat et déplace la carte vers la liste appropriée avant sa réponse finale. Les questions en lecture seule, les plans exploratoires, les demandes en brouillon uniquement et les limites explicites n'autorisent pas ces écritures. Les installations existantes conservent leurs anciennes instructions : après mise à niveau, actualisez la compétence Claude avec --force, ou mettez à jour la section Kanera existante dans AGENTS.md en utilisant le courant kanera skill sortie. Adapter le instructions du projet ci-dessous pour votre flux de travail.
La boucle de travail
Chaque étape ci-dessous est une commande exécutée par l'agent. Les arguments de la carte acceptent une clé telle que MKT-42, un identifiant de carte ou une URL de carte.
1. Récupérez le travail
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 est utile lorsque vous conservez un À suivre file d'attente : l'agent peut prendre la première carte plutôt que de choisir lui-même.
2. Ouvrir une course
Avant un travail de fond, lisez les commentaires pertinents et la configuration de la carte, vérifiez que personne d'autre n'est sur la carte, puis ouvrez une exécution. Reprenez votre propre exécution en direct pour la même tâche ; signaler l'exécution en direct d'un autre agent avant d'effectuer un travail qui se chevauche :
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)
La vignette de la carte affiche désormais une puce active indiquant que l'agent travaille, et les détails de la carte montrent l'exécution avec son titre et sa note de progression. --externalUrl est facultatif ; donnez-lui la demande d'extraction, la branche ou le journal de session qu'une personne peut ouvrir. Voir Exécutions et attribution des agents pour ce que tout le monde voit.
Enregistrez l'ID de liste d'origine de la carte, son nom et la signification du flux de travail avant de la déplacer. Utiliser kanera card move pour le placer dans la liste disponible qui représente le travail actif dans le flux de travail de ce tableau. Les courses ne déplacent pas les cartes. Résolvez la liste à partir de la configuration du tableau et ignorez le déplacement s'il est déjà là ; kanera help cards.move décrit les arguments d'ancrage requis. Ne présumez pas que chaque tableau utilise le modèle Agent Workflow.
3. Signaler les progrès
Mettez à jour le parcours au fur et à mesure que le travail avance. Chaque mise à jour est également un battement de cœur, et une exécution qui dure quinze minutes sans aucune est marquée bloqué, donc pour les tâches longues, l'agent doit se mettre à jour au moins toutes les dix minutes.
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
Le résumé d'exécution est une ligne d'état que chaque mise à jour remplace. Pour tout ce que l'équipe doit conserver, commentez la carte :
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
Donnez à chaque commentaire prévu ou relancez la création --idempotencyKey UUID et réutilisez-le uniquement lorsque vous réessayez cette écriture après un échec ambigu. Si une réponse a été perdue sans clé, vérifiez la carte avant de réessayer pour éviter les doublons.
4. Signaler un bloqueur
Lorsque l'agent a besoin d'une décision, d'une approbation ou d'un accès qu'il n'a pas, marquez la course blocked et dites ce dont il a besoin :
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."
La puce devient orange et les détails de la carte s'affichent Je t'attends. Marquer une course bloquée n'informe personne en soi, c'est pourquoi le commentaire est important : il atteint les observateurs et les destinataires de la carte. Choisissez une liste qui reflète le bloqueur dans le flux de travail de ce forum. Lorsque l'agent reprend, il définit le retour sur --status running et replace la carte dans la liste active.
Si une autre carte est le prérequis, créez également un dépendance à la carte: kanera card block API-42 WEB-18 signifie que l'API-42 bloque WEB-18. Une exécution bloquée décrit le statut de l'agent ; cela ne crée pas cette relation. Utiliser kanera work --filters.blockedOnly true pour trouver des cartes d'attente, et kanera deps WEB-18 pour lire ses prérequis directs et sa chaîne transitive amont/aval.
5. Terminer
Avant la réponse finale, publiez un commentaire sur le résultat durable avec ce qui a changé ou a été trouvé, la vérification et ses résultats (y compris les échecs ou les vérifications ignorées), les liens PR/commit/artefact pertinents et le travail ou les décisions restants. Marquez uniquement les éléments de la liste de contrôle réellement terminés. Terminez ensuite l'exécution et acheminez la carte :
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
Le résumé de clôture de la course devient un fini ramer en activité; il ne remplace pas le commentaire du résultat, ne déplace pas la carte et ne la complète pas. Une exécution réussie peut couvrir seulement une partie d'une carte. Remplissez la carte uniquement lorsque le flux de travail convenu le permet et que ses critères sont remplis.
Avant de déplacer la carte, relisez-la ainsi que son plateau. Considérez la liste originale, les listes actuellement disponibles et leurs significations, ce qui a été complété et ce qui reste. Choisissez la liste qui représente le mieux l'état réel de la carte dans le flux de travail de ce tableau. Le retour à la liste originale peut être approprié, mais n'est pas automatique. Ne supposez pas les noms de liste et ne choisissez pas uniquement dans l'ordre de la liste ou dans les paramètres en cours. Expliquez le choix dans le commentaire du résultat.
Si le travail assigné n'a pas pu être terminé, expliquez ce qui reste et terminez l'exécution avec --status failed ou --status cancelled. Garder blocked seulement en attendant réellement de reprendre ; ne laissez pas le travail arrêté en cours. Une exécution terminée ne peut pas être modifiée ; si le travail reprend plus tard, démarrez une nouvelle exécution.
Vérifiez la liste de cartes résultante, le commentaire du résultat et l'état d'exécution à partir des résultats d'écriture et d'une nouvelle lecture. Tenez compte des automatisations et des mouvements intermédiaires d'un coéquipier. Si aucune destination n'est claire, laissez la liste actuelle inchangée, enregistrez les mises à jour d'exécution/commentaires possibles et demandez uniquement le choix de routage manquant. Si une écriture est refusée, signalez la restriction et les étapes de suivi qui ne sont pas enregistrées ; n'implique pas le succès. La réponse finale doit lier la carte et indiquer la liste résultante et l'état d'exécution.
À qui l’œuvre est-elle attribuée
La façon dont la CLI connectée décide de la façon dont le travail de l'agent est étiqueté :
| Informations d'identification | Commentaires et changements de cartes | Exécuter l'étiquette de puce |
|---|---|---|
Connectez-vous au navigateur avec --agent (kanera auth login --agent "Claude Code") | Comme toi, via Claude Code (Kanera CLI sur le nom de l'ordinateur) | Claude Code (Kanera CLI sur le nom de l'ordinateur) |
Connexion au navigateur sans --agent | Comme toi, via Kanera CLI (nom de l'ordinateur) | Kanera CLI (nom de l'ordinateur) |
| Clé API personnelle | Comme toi, sans via insigne | Client API |
| Clé API de l'espace de travail ou du tableau | Comme le nom de la clé | Le nom de la clé |
Une connexion au navigateur est une connexion à un appareil OAuth. Le travail de l'agent comporte donc un via badge, regroupé séparément dans vos notifications et séparé de votre propre travail dans Work Done, de la même manière que dans MCP. Kanera ne voit que la CLI, alors nommez l'agent lorsque vous vous connectez avec --agent (ou KANERA_AGENT_NAME). Le nom est fixe pour cette connexion ; donner à chaque agent le sien profil si plusieurs partagent une machine. Sur MCP, l'agent se nomme ; voir Mettre en place Claude ou Configurer le Codex. kanera mcp, le serveur MCP local de la CLI, utilise les mêmes informations d'identification stockées et donc la même attribution que la CLI.
Ajoutez-le aux instructions de votre projet
Le courant kanera setup claude et kanera setup codex les instructions incluent cette boucle. Pour rendre explicite la politique d'acceptation de votre projet, adaptez cette section en 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.
Associez-le à une clé d’écriture. Avec une clé en lecture seule, conservez uniquement les étapes de lecture.