Arbeiten Sie mit Codierungsagenten vom Terminal aus
Ein Terminal-Coding-Agent wie Claude Code oder Codex kann eine Kanera-Karte von der Abholung bis zur Fertigstellung begleiten: die Karte lesen, ankündigen, dass sie funktioniert, den Fortschritt melden, kennzeichnen, wenn eine Person benötigt wird, und die Karte als abgeschlossen markieren. In diesem Leitfaden wird die Schleife mit dem festgelegt Kanera CLI, was für jeden Agenten funktioniert, der Shell-Befehle ausführen kann.
:::Tipp: Verbundene MCP-Tools stehen an erster Stelle. Wenn Ihr Agent eine Verbindung zum gehosteten MCP-Server von Kanera herstellen kann, verwenden Sie diesen stattdessen. Fügen Sie die Setup-Eingabeaufforderung ein Verbinden Sie Kanera mit Ihrem KI-Agenten und der Agent erhält über OAuth dieselben Tools, wobei seine Arbeit gekennzeichnet ist über <agent>. Die CLI ist die Route für einen Agenten, der über eine Shell, aber keine MCP-Verbindung verfügt. Die Schleife unten ist in beiden Fällen gleich; Nur der Transport ändert sich. :::
Installieren und anmelden
Installieren Sie die CLI einmal auf dem Computer, auf dem der Agent ausgeführt wird. Es benötigt Knoten 22 oder neuer.
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login druckt einen Link und einen Code und öffnet den Link in Ihrem Browser. Genehmigen Sie die Anfrage dort, nachdem Sie die Codeübereinstimmungen überprüft haben, und die CLI speichert eine Anmeldung, die sich selbst erneuert. Für einen Agenten, der unbeaufsichtigt ausgeführt wird, z. B. in CI, verwenden Sie kanera auth login --with-api-key mit einem Schlüssel von Profileinstellungen -> API-Schlüssel stattdessen, und wählen Schreibgeschützt wenn es nichts ändern sollte. Bestätigen Sie dann, was der Agent tun kann:
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
Überspringen Sie für einen Sandbox- oder CI-Job das gespeicherte Profil und legen Sie es fest KANERA_API_KEY stattdessen. Sehen Kanera CLI für benannte Profile und selbst gehostete Adressen.
Nur lesen oder schreiben
Wählen Sie den Umfang des Schlüssels für die Aufgabe aus, nicht aus Bequemlichkeit.
- Schreibgeschützt eignet sich für einen Agenten, der nur Arbeit finden und lesen muss: Sortieren, eine Karte zusammenfassen, bevor Sie beginnen, oder antworten: „Was liegt auf meinem Teller?“. Kanera lehnt jede Änderung an der API ab, was auch immer der Agent versucht.
- Schreiben wird für alles andere auf dieser Seite benötigt: Öffnen eines Laufs, Kommentieren und Vervollständigen von Karten. Kanera überprüft weiterhin Ihre Rolle in jedem Board, sodass der Agent ein Board, in dem Sie Beobachter sind, nicht ändern kann.
Ein abgelehnter Schreibvorgang wird mit Code beendet 4Dies unterscheidet sich von einem gewöhnlichen Fehler, sodass der Agent anhalten und Sie informieren kann, anstatt es erneut zu versuchen. Agentensicherheit behandelt, wie der Zugriff eines Agenten eingeschränkt wird.
Installieren Sie die Agentenanweisungen
kanera setup schreibt Anweisungen, die dem Agenten beibringen, wie er die CLI sicher verwenden kann: Überprüfen Sie zuerst den Gültigkeitsbereich des Schlüssels und entdecken Sie Befehle mit kanera commands --json Anstatt zu raten, verwenden Sie --quiet oder --json beim Analysieren der Ausgabe und behandeln Sie destruktive Tools so, als ob sie eine explizite Anfrage erfordern.
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 claudeInstalliert Kaneras Agentenfähigkeit, die Claude Code lädt, wenn Kanera auftaucht. Eine vorhandene wird nicht überschriebenSKILL.md; erneut ausführen mit--forceum es nach dem Upgrade der CLI zu ersetzen.setup codexschafftAGENTS.mdwenn es nicht existiert, oder fügt einen kurzen Kanera-Abschnitt hinzu. Eine erneute Ausführung ist sicher: Wenn die Datei Kanera bereits dokumentiert, ändert sich nichts.kanera setup agentsmacht das Gleiche für jeden Agenten, der liestAGENTS.md.
Beide Setup-Ziele umfassen die Arbeitsschleife: Wenn der Agent aufgefordert wird, eine Karte auszuführen, startet er einen Lauf, hält den Fortschritt sichtbar, kommentiert das Ergebnis und verschiebt die Karte vor ihrer endgültigen Antwort in die entsprechende Liste. Nur-Lese-Fragen, Sondierungspläne, reine Entwurfsanfragen und explizite Einschränkungen autorisieren diese Schreibvorgänge nicht. Bestehende Installationen behalten ihre alten Anweisungen: Aktualisieren Sie nach dem Upgrade den Claude-Skill mit --force, oder aktualisieren Sie den vorhandenen Kanera-Abschnitt in AGENTS.md unter Verwendung des Stroms kanera skill Ausgabe. Passen Sie die an Projektanweisungen unten für Ihren Workflow.
Die Arbeitsschleife
Jeder Schritt unten ist ein Befehl, den der Agent ausführt. Kartenargumente akzeptieren einen Schlüssel wie MKT-42, eine Karten-ID oder eine Karten-URL.
1. Arbeit aufnehmen
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 ist nützlich, wenn Sie eine behalten „Als Nächstes“ Warteschlange: Der Agent kann die oberste Karte nehmen, anstatt selbst eine zu wählen.
2. Öffnen Sie einen Lauf
Lesen Sie vor der eigentlichen Arbeit die relevanten Kommentare und die Board-Konfiguration, überprüfen Sie, ob sich niemand anderes auf der Karte befindet, und starten Sie dann einen Lauf. Setzen Sie Ihren eigenen Live-Lauf für dieselbe Aufgabe fort; Melden Sie den Live-Lauf eines anderen Agenten, bevor Sie sich überschneidende Arbeiten ausführen:
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)
Die Kartenkachel zeigt jetzt einen Live-Chip, der angibt, dass der Agent arbeitet, und im Kartendetail wird der Lauf mit Titel und Fortschrittsnotiz angezeigt. --externalUrl ist optional; Geben Sie ihm die Pull-Anfrage, den Zweig oder das Sitzungsprotokoll, das eine Person öffnen kann. Siehe Agentenläufe und Zuschreibung für das, was alle anderen sehen.
Notieren Sie die ursprüngliche Listen-ID, den Namen und die Workflow-Bedeutung der Karte, bevor Sie sie verschieben. Benutzen kanera card move um es in die verfügbare Liste aufzunehmen, die die aktive Arbeit im Workflow dieses Boards darstellt. Bei Läufen werden keine Karten verschoben. Lösen Sie die Liste aus der Konfiguration des Boards auf und überspringen Sie die Verschiebung, wenn sie bereits vorhanden ist. kanera help cards.move beschreibt die erforderlichen Ankerargumente. Gehen Sie nicht davon aus, dass jedes Board die Agent-Workflow-Vorlage verwendet.
3. Fortschritt melden
Aktualisieren Sie den Lauf, während sich die Arbeit bewegt. Jedes Update ist auch ein Herzschlag, und ein Lauf, der fünfzehn Minuten ohne einen solchen dauert, wird markiert ins Stocken geratenDaher sollte der Agent bei langen Aufgaben mindestens alle zehn Minuten aktualisiert werden.
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
Die Laufzusammenfassung ist eine Statuszeile, die jedes Update ersetzt. Für alles, was das Team behalten sollte, kommentieren Sie die Karte:
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
Geben Sie jedem beabsichtigten Kommentar oder jeder laufenden Erstellung eine neue Note --idempotencyKey UUID und verwenden Sie sie nur wieder, wenn Sie den Schreibvorgang nach einem mehrdeutigen Fehler wiederholen. Wenn eine Antwort ohne Schlüssel verloren gegangen ist, überprüfen Sie die Karte, bevor Sie es erneut versuchen, um Duplikate zu vermeiden.
4. Markieren Sie einen Blocker
Wenn der Agent eine Entscheidung, eine Genehmigung oder einen Zugriff benötigt, über den er nicht verfügt, markieren Sie die Ausführung blocked und sagen, was es braucht:
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."
Der Chip wird bernsteinfarben und Kartendetails werden angezeigt Ich warte auf dich. Durch das Markieren eines Laufs als blockiert wird niemand benachrichtigt, weshalb der Kommentar wichtig ist: Er erreicht die Beobachter und Beauftragten der Karte. Wählen Sie eine Liste, die den Blocker im Workflow dieses Boards widerspiegelt. Wenn der Agent fortfährt, setzt er die Ausführung wieder auf --status running und verschiebt die Karte zurück in die aktive Liste.
Wenn eine andere Karte die Voraussetzung ist, erstellen Sie auch eine Kartenabhängigkeit: kanera card block API-42 WEB-18 bedeutet, dass API-42 WEB-18 blockiert. Eine blockierte Ausführung beschreibt den Status des Agenten; es schafft diese Beziehung nicht. Benutzen kanera work --filters.blockedOnly true Wartekarten finden und kanera deps WEB-18 um seine direkten Voraussetzungen und die transitive Upstream-/Downstream-Kette zu lesen.
5. Fertig
Veröffentlichen Sie vor der endgültigen Antwort einen dauerhaften Ergebniskommentar mit den Änderungen oder Feststellungen, der Überprüfung und ihren Ergebnissen (einschließlich Fehlern oder übersprungenen Prüfungen), relevanten PR-/Commit-/Artefakt-Links und verbleibenden Arbeiten oder Entscheidungen. Markieren Sie nur tatsächlich erledigte Checklistenpunkte. Dann den Lauf beenden und die Karte weiterleiten:
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
Die abschließende Zusammenfassung des Laufs wird zu einem fertig Reihe in der Aktivität; Es ersetzt nicht den Ergebniskommentar, verschiebt die Karte nicht und vervollständigt sie nicht. Ein erfolgreicher Lauf deckt möglicherweise nur einen Teil einer Karte ab. Füllen Sie die Karte nur aus, wenn der vereinbarte Arbeitsablauf dies zulässt und seine Kriterien erfüllt sind.
Bevor Sie die Karte bewegen, lesen Sie sie und ihre Tafel noch einmal durch. Berücksichtigen Sie die ursprüngliche Liste, die derzeit verfügbaren Listen und ihre Bedeutung, was vervollständigt wurde und was noch übrig ist. Wählen Sie die Liste aus, die den tatsächlichen Status der Karte im Workflow dieses Boards am besten widerspiegelt. Eine Rückkehr zur ursprünglichen Liste mag angebracht sein, erfolgt aber nicht automatisch. Gehen Sie nicht von Listennamen aus und wählen Sie nicht nur aus der Listenreihenfolge oder der Einstellung „In Bearbeitung“ aus. Erklären Sie die Wahl im Ergebniskommentar.
Wenn die zugewiesene Arbeit nicht abgeschlossen werden konnte, erklären Sie, was noch übrig ist, und beenden Sie den Lauf damit --status failed oder --status cancelled. Behalten blocked nur, wenn man wirklich darauf wartet, wieder fortzufahren; Lassen Sie gestoppte Arbeiten nicht laufen. Ein beendeter Lauf kann nicht geändert werden; Wenn die Arbeit später fortgesetzt wird, starten Sie einen neuen Lauf.
Überprüfen Sie die resultierende Kartenliste, den Ergebniskommentar und den Laufstatus anhand der Schreibergebnisse und eines neuen Lesevorgangs. Berücksichtigen Sie Automatisierungen und die dazwischenliegende Bewegung eines Teamkollegen. Wenn kein Ziel klar ist, lassen Sie die aktuelle Liste unverändert, speichern Sie die Lauf-/Kommentaraktualisierungen, die Sie können, und fragen Sie nur nach der fehlenden Routing-Auswahl. Wenn ein Schreibvorgang abgelehnt wird, melden Sie die Einschränkung und welche Nachverfolgungsschritte nicht gespeichert werden; bedeuten keinen Erfolg. Die endgültige Antwort sollte die Karte verknüpfen und die resultierende Liste und den Ausführungsstatus angeben.
Wem das Werk zugeschrieben wird
Wie sich die CLI anmeldet, entscheidet darüber, wie die Arbeit des Agenten gekennzeichnet wird:
| Ausweis | Kommentare und Kartenänderungen | Chipetikett ausführen |
|---|---|---|
Browser-Anmeldung mit --agent (kanera auth login --agent "Claude Code") | Wie du, über Claude Code (Kanera CLI auf Computername) | Claude Code (Kanera CLI für Computernamen) |
Browser-Anmeldung ohne --agent | Wie du, über Kanera CLI (Computername) | Kanera CLI (Computername) |
| Persönlicher API-Schlüssel | Wie du, mit Nein über Abzeichen | API-Client |
| Arbeitsbereichs- oder Board-API-Schlüssel | Als Name des Schlüssels | Der Name des Schlüssels |
Bei einer Browser-Anmeldung handelt es sich um eine OAuth-Geräteverbindung, daher erfolgt die Arbeit des Agenten über Abzeichen, gruppiert separat in Ihren Benachrichtigungen und wird von Ihrer eigenen Arbeit in Work Done getrennt gehalten, genau wie über MCP. Kanera sieht nur die CLI. Benennen Sie daher den Agenten, wenn Sie sich mit anmelden --agent (oder KANERA_AGENT_NAME). Der Name ist für diese Anmeldung festgelegt. Geben Sie jedem Agenten seinen eigenen Profil wenn sich mehrere eine Maschine teilen. Über MCP benennt sich der Agent; siehe Richte Claude ein oder Codex einrichten. kanera mcp, der lokale MCP-Server der CLI, verwendet dieselben gespeicherten Anmeldeinformationen und damit dieselbe Zuordnung wie die CLI.
Fügen Sie es Ihren Projektanweisungen hinzu
Der Strom kanera setup claude und kanera setup codex Anweisungen enthalten diese Schleife. Um die Akzeptanzrichtlinien Ihres Projekts explizit zu machen, passen Sie diesen Abschnitt an CLAUDE.md oder 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.
Koppeln Sie es mit einem Schreibschlüssel. Behalten Sie bei einem schreibgeschützten Schlüssel nur die Leseschritte bei.