ターミナルからコーディング エージェントを操作する
Claude Code や Codex などの端末コーディング エージェントは、Kanera カードの受け取りから完了までを行うことができます。つまり、カードを読み取り、機能していることをアナウンスし、進捗状況を報告し、担当者が必要なときにフラグを立て、カードに完了のマークを付けます。このガイドでは、そのループを次のように設定します。 Kanera CLIこれは、シェル コマンドを実行できるすべてのエージェントで機能します。
インストールしてサインインする
エージェントが実行されているマシンに CLI を 1 回インストールします。 Node 22 以降が必要です。
npm install --global @kanera/cli
kanera auth login --agent "Claude Code" # use your agent's own product name
kanera auth login リンクとコードを出力し、ブラウザでリンクを開きます。コードの一致を確認した後、そこでリクエストを承認すると、CLI はそれ自体を更新するサインインを保存します。 CI などで無人で実行されるエージェントの場合は、次を使用します。 kanera auth login --with-api-key 次の場所で発行したキーを使用します： プロファイル設定 -> API キー 代わりに、選択してください 読み取り専用 何も変わらないはずなのに。次に、エージェントが実行できることを確認します。
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
サンドボックスまたはCIジョブの場合、保存されているプロファイルをスキップして設定します。 KANERA_API_KEY 代わりに。見る Kanera CLI 名前付きプロファイルとセルフホスト アドレスの場合。
読み取り専用または書き込み
利便性のためではなく、ジョブに合わせてキーのスコープを選択してください。
- 読み取り専用 トリアージをしたり、開始前にカードを要約したり、「何が予定されていますか?」に答えたりするなど、仕事を見つけて読むだけでよいエージェントに適しています。 Kanera は、エージェントがどのような変更を試みても、API でのすべての変更を拒否します。
- 書く このページの他のすべての操作 (ランを開く、コメントする、カードを完成させる) に必要です。 Kanera は引き続き各ボードであなたの役割をチェックするため、エージェントはあなたがオブザーバーであるボードを変更することはできません。
拒否された書き込みはコードとともに終了します 4、通常の失敗とは異なるため、エージェントは再試行するのではなく、停止して通知することができます。 エージェントのセキュリティ エージェントのアクセス範囲を設定する方法について説明します。
エージェントのインストール手順
kanera setup エージェントが安全にCLIを使うための手順を書きます。まずキーのスコープを確認し、次を使ってコマンドを調べます： kanera commands --json 推測する代わりに使用します --quiet または --json 出力を解析する場合。破壊的なツールには明示的な依頼が必要と扱ってください。
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 claudeKanera のエージェント スキルをインストールします。Kanera が起動するとクロード コードがロードされます。既存のものは上書きされませんSKILL.md;で再実行します--forceCLIのアップグレード後に置き換えます。setup codex作成しますAGENTS.md存在しない場合は、短いKaneraセクションを追加します。再実行しても安全です。ファイルがすでにKaneraを文書化している場合は、何も変更されません。kanera setup agentsを読み取るエージェントに対しても同じことを行います。AGENTS.md.
どちらのセットアップ ターゲットにもワーク ループが含まれています。カードの実行を求められると、エージェントは実行を開始し、進行状況を表示し続け、結果にコメントを付けて、最終応答の前にカードを適切なリストに移動します。読み取り専用の質問、探索的な計画、下書きのみのリクエスト、および明示的な制限では、これらの書き込みは許可されません。既存のインストールでは古い手順が保持されます。アップグレード後、次のコマンドでクロード スキルを更新します。 --force、または既存のKaneraセクションを更新します。 AGENTS.md 現在の次の項目を使用します： kanera skill 出力。適応させる 以下のプロジェクト手順 ワークフローに合わせて。
作業ループ
以下の各ステップは、エージェントが実行するコマンドです。カードの引数は次のようなキーを受け入れます。 MKT-42、カード ID、またはカード URL。
1.仕事をピックアップ
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 を保管するときに便利です。 次にやること キュー: エージェントは自分でカードを選ぶのではなく、一番上のカードを受け取ることができます。
2. 実行を開く
実質的な作業を行う前に、関連するコメントとボード構成を読み、カード上に他に誰もいないことを確認してから実行を開きます。同じタスクに対する独自のライブ実行を再開します。重複する作業を行う前に、別のエージェントのライブ実行をレポートします。
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)
カード タイルには、エージェントが動作していることを示すライブ チップが表示され、カードの詳細には、タイトルと進行状況のメモとともに実行が表示されます。 --externalUrl はオプションです。ユーザーが開くことができるプル リクエスト、ブランチ、またはセッション ログを指定します。参照 エージェントの実行と帰属 他の人が見ているもののために。
カードを移動する前に、カードの元のリスト ID、名前、およびワークフローの意味を記録します。使用する kanera card move このボードのワークフローで進行中を表すリストに配置します。実行自体はカードを移動しません。ボードの設定から対象リストを特定し、すでにそのリストにある場合は移動を省略します。 kanera help cards.move 必要なアンカー引数について説明します。すべてのボードがエージェント ワークフロー テンプレートを使用すると想定しないでください。
3. 進捗状況の報告
作業が進むにつれて実行を更新します。すべての更新はハートビートでもあり、ハートビートなしで 15 分間続いた実行にはマークが付けられます。 停滞したしたがって、長いタスクの場合、エージェントは少なくとも 10 分ごとに更新する必要があります。
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
実行概要は、更新ごとに置き換えられるステータス行です。チームが保持する必要があるものについては、カードにコメントしてください。
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
意図したコメントをそれぞれ追加するか、作成を新しく実行します --idempotencyKey UUID を取得し、あいまいな失敗後に書き込みを再試行する場合にのみそれを再利用します。キーなしで応答が失われた場合は、重複を避けるために再試行する前にカードを確認してください。
4. ブロッカーにフラグを立てる
エージェントが決定、承認、または自分にはないアクセス権を必要とする場合、実行をマークします。 blocked そして必要なことを言います:
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."
チップがオレンジ色に変わり、カードの詳細が表示されます お待ちしています。実行をブロック済みとしてマークしても、それ自体は誰にも通知されません。だからこそコメントが重要です。コメントはカードの監視者や担当者に届きます。このボードのワークフローのブロッカーを反映するリストを選択してください。エージェントが再開すると、実行は次のように設定されます。 --status running そしてカードをアクティブリストに戻します。
別のカードが前提条件である場合は、 カード依存性: kanera card block API-42 WEB-18 API-42 が WEB-18 をブロックすることを意味します。ブロックされた実行はエージェントのステータスを表します。この関係は生まれません。使用する kanera work --filters.blockedOnly true 待機中のカードを検索し、 kanera deps WEB-18 直接の前提作業と、連鎖する上流・下流の関係を読み取ります。
5. 仕上げ
最終返信の前に、変更内容または見つかった内容、検証とその結果 (失敗またはスキップされたチェックを含む)、関連する PR/コミット/アーティファクトのリンク、残りの作業または決定事項を記載した永続的な結果コメントを投稿します。実際に完了したチェックリスト項目のみにマークを付けます。次に、実行を終了し、カードをルーティングします。
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
実行の最終概要は次のようになります。 終わった アクティビティ内の行。結果のコメントを置き換えたり、カードを移動したり、カードを完成させたりするものではありません。実行が成功すると、カードの一部のみがカバーされる場合があります。合意されたワークフローで許可され、その基準が満たされている場合にのみ、カードに記入してください。
カードを移動する前に、カードとそのボードをもう一度読んでください。元のリスト、現在利用可能なリストとその意味、何が完成し、何が残っているのかを考えてみましょう。このボードのワークフローにおけるカードの実際の状態を最もよく表すリストを選択してください。元のリストに戻ることが適切な場合もありますが、自動的には戻りません。リスト名を想定したり、リストの順序や進行中の設定のみから選択したりしないでください。結果のコメントで選択内容を説明します。
割り当てられた作業を完了できなかった場合は、何が残っているかを説明し、次のように実行を終了します。 --status failed または --status cancelled。キープする blocked 本当に再開を待っている場合のみ。停止した作業を実行したままにしないでください。終了した実行は変更できません。後で作業が再開される場合は、新しい実行を開始してください。
結果のカードリスト、結果コメント、書き込み結果と新規読み取りからの実行ステータスを確認します。自動化とチームメイトの介入を考慮します。明確な宛先がない場合は、現在のリストを変更しないで、可能な限り実行/コメントの更新を保存し、欠落しているルーティングの選択肢のみを尋ねます。書き込みが拒否された場合は、制限と保存されていない追跡ステップを報告します。成功を意味するものではありません。最終応答では、カードをリンクし、その結果のリストと実行ステータスを説明する必要があります。
作品の帰属先は誰なのか
CLI のサインイン方法によって、エージェントの作業のラベル付け方法が決まります。
| 資格情報 | コメントとカードの変更 | ランチップラベル |
|---|---|---|
ブラウザでのサインイン --agent (kanera auth login --agent "Claude Code") | あなたと同じように、 Claude Code経由（コンピューター名上のKanera CLI） | Claude Code (コンピュータ名上のKanera CLI) |
ブラウザーサインインなし --agent | あなたと同じように、 Kanera CLI経由（コンピューター名） | Kanera CLI (コンピュータ名) |
| 個人用APIキー | あなたのように、何もせずに 経由 バッジ | APIクライアント |
| ワークスペースまたはボードの API キー | キーの名前としては | 鍵の名前 |
ブラウザーのサインインは OAuth デバイス接続であるため、エージェントの作業には 経由 バッジ、通知内で個別にグループ化され、MCP と同様に、「作業完了」で自分の作業とは別に保持されます。 Kanera には CLI のみが表示されるため、サインインするときにエージェントに名前を付けます。 --agent (または KANERA_AGENT_NAME）。名前はそのサインインに対して固定されています。各エージェントに独自のエージェントを与える プロフィール 複数人がマシンを共有している場合。 MCP を介して、エージェントは自分自身に名前を付けます。参照してください クロードをセットアップする または コーデックスをセットアップする. kanera mcp、CLI のローカル MCP サーバーは、同じ保存された資格情報を使用するため、CLI と同じ属性を使用します。
プロジェクトの指示に追加してください
現在の kanera setup claude そして kanera setup codex 命令にはこのループが含まれています。プロジェクトの受け入れポリシーを明示するには、このセクションを次のとおりに調整します。 CLAUDE.md または 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.
書き込みキーとペアリングします。読み取り専用キーを使用すると、読み取りステップのみが保持されます。