agkan完全ガイド：AI Agentと協働するCLIタスク管理ツールの使い方【2026年版】

2026年2月23日

AIコーディングツール（Claude Code、Cursor、Windsurf等）を使い始めると、避けられない問題に直面する。「AIにタスクを渡したが、前のセッションで何をやっていたか覚えていない」「複数のタスクを並行していると状態管理が追いつかない」という問題だ。

この記事では、まさにその課題のために設計されたCLIツール agkan の使い方を解説する。インストールから基本操作、親子関係・ブロック依存管理、JSON出力を使ったAI連携まで、実際に動かしながら確認した内容をそのまま紹介する。

本記事のコマンド例はすべてDocker環境で実行・検証済みだ。

前提条件

このガイドを進める前に、以下の環境が必要だ。

OS: Linux / macOS / Windows（Node.js が動く環境ならOK）
必要なツール: Node.js 18以上、npm 9以上

# Node.js バージョン確認
node --version
# 期待する出力: v18.x.x 以上（v22系推奨）

npm --version
# 期待する出力: 9.x.x 以上

Windows の場合: WSL2 上で動かすのが最もスムーズだ。PowerShell でも動作するが、日本語表示には Windows Terminal の使用を推奨する。

全体の流れ

このガイドは以下の5ステップで構成されている。

インストール — 2分
基本的な使い方（タスクCRUD） — 10分
親子関係・ブロック依存管理 — 10分
タグ・メタデータ管理 — 5分
JSON出力とAI連携 — 5分

agkanとは

agkan（エージカン）は、AI Agentとの協働を前提に設計されたTypeScript製のCLIタスク管理ツールだ。v1.3.2（2024年現在）では以下の機能を提供している。

機能	概要
カンバン管理	7種類のステータスでタスクを管理
親子関係	タスクの階層構造・ツリー表示
ブロック依存	タスク間の依存関係（循環参照を自動検出）
タグ管理	タスクの分類・フィルタリング
メタデータ	優先度・工数等のカスタムデータ
JSON出力	9コマンドがJSONに対応。スクリプト連携が容易

7種類のステータスは以下のとおりだ。

ステータス	意味
`icebox`	いつかやるかもしれないが、今は実行しない。ストック置き場
`backlog`	タスク作成時のデフォルト。実装待ちの積み上げ
`ready`	実装準備が整い、着手できる状態
`in_progress`	実装中
`review`	レビュー中
`done`	タスク完了
`closed`	実行しないと決めてクローズ。`icebox`（保留）との違いは「やらないと確定した」点

データはローカルの SQLite（.agkan/data.db）に保存されるため、外部サービスへの依存がなく、プロジェクトのリポジトリに含めることも可能だ。

ステップ1: インストール {#step1}

npm でグローバルインストールするだけで使い始められる。

npm install -g agkan

インストール後、バージョンを確認しよう。

agkan --version

1.3.2

実際に試したところ、インストールは30秒程度で完了した。

✅ ステップ1完了の確認: agkan --version でバージョン番号が表示されればOK。

ステップ2: 基本的な使い方 {#step2}

タスクを作成する

agkan task add でタスクを作成する。第1引数がタイトル、第2引数がボディ（説明）だ。

agkan task add 'バックエンドAPI実装' 'REST APIエンドポイントを実装する'

✓ Task created successfully

ID: 1
Title: バックエンドAPI実装
Status: backlog
Created: 2026/2/23 4:27:48

作成時にステータスを指定することもできる。

agkan task add 'フロントエンド実装' 'ReactでUIを実装する' --status in_progress

✓ Task created successfully

ID: 2
Title: フロントエンド実装
Status: in_progress
Created: 2026/2/23 4:27:53

--status で指定できる値は icebox（保留ストック）/ backlog（デフォルト）/ ready（着手可能）/ in_progress（実装中）/ review（レビュー中）/ done（完了）/ closed（実行しないと確定）の7種類だ。

タスク一覧を表示する

agkan task list

Found 6 task(s):

────────────────────────────────────────────────────────────────────────────────

[7] テスト作成
  Status: backlog
  Created: 2026/2/23 4:36:24
  ────────────────────────────────────────────────────────────────────────────

[6] フロントエンド実装
  Status: in_progress
  Created: 2026/2/23 4:36:20
  ────────────────────────────────────────────────────────────────────────────

[5] バックエンドAPI実装
  Status: backlog
  Created: 2026/2/23 4:36:15
  ────────────────────────────────────────────────────────────────────────────

ステータスでフィルタリングすることもできる。

agkan task list --status in_progress

Found 2 task(s):

[6] フロントエンド実装
  Status: in_progress

[2] フロントエンド実装
  Status: in_progress
  Metadata: priority: high

タスクの詳細を確認する

agkan task get 1

Task #1
════════════════════════════════════════════════════════════════════════════════
Title: バックエンドAPI実装
Status: done
Created: 2026/2/23 4:27:48
Updated: 2026/2/23 4:28:10

Body:
────────────────────────────────────────────────────────────────────────────────
REST APIエンドポイントを実装する
────────────────────────────────────────────────────────────────────────────────

ステータスを更新する

agkan task update 1 status done

✓ Task updated successfully

ID: 1
Title: バックエンドAPI実装
Status: done
Updated: 2026/2/23 4:36:37

Task Count by Status:
  icebox: 0
  backlog: 4
  ready: 0
  in_progress: 2
  review: 0
  done: 1
  closed: 0

ステータス更新と同時に全ステータスの件数が表示されるので、進捗の把握が容易だ。

タスクを検索する

キーワードでタスクを検索できる。デフォルトでは done / closed のタスクは除外される。

agkan task find 'API'

Found 3 task(s) matching "API" (excluding done/closed):

[8] APIエンドポイント設計
  Status: backlog

[5] バックエンドAPI実ecraft
  Status: backlog

[4] APIエンドポイント設計
  Status: backlog

✅ ステップ2完了の確認: agkan task list でタスクが一覧表示されればOK。

ステップ3: 親子関係・ブロック依存管理 {#step3}

親子関係（サブタスク）

大きなタスクを親とし、その配下に子タスクを作成できる。--parent オプションで親タスクのIDを指定する。

agkan task add 'APIエンドポイント設計' 'OpenAPI仕様を書く' --parent 2

✓ Task created successfully

ID: 4
Title: APIエンドポイント設計
Status: backlog
Parent: #2 - フロントエンド実装
Created: 2026/2/23 4:28:20

--tree フラグでツリー形式の一覧表示ができる。

agkan task list --tree

Found 7 task(s) in tree view:

────────────────────────────────────────────────────────────────────────────────
├── [7] テスト作成 (backlog)
├── [6] フロントエンド実装 (in_progress)
├── [5] バックエンドAPI実装 (backlog)
├── [3] テスト作成 (backlog)
└── [2] フロントエンド実装 (in_progress)
    Metadata: priority: high
    ├── [4] APIエンドポイント設計 (backlog)
    └── [8] APIエンドポイント設計 (backlog)

ブロック依存関係

「タスクAが完了するまでタスクBに着手できない」という依存関係を agkan task block で管理できる。

# タスク2がタスク3をブロックする（タスク2が完了するまでタスク3に着手できない）
agkan task block add 2 3

依存関係を確認する。

agkan task block list 2

Blocking Relationships for Task #2
════════════════════════════════════════════════════════════════════════════════
Title: フロントエンド実装
Status: in_progress

Blocked By: (none)

Blocking: 1 task(s)
  • [3] テスト作成 (backlog)

agkan は循環参照を自動検出する。「A→B→C→A」のような循環依存を設定しようとするとエラーが返るため、誤った依存関係の設定を防げる。

✅ ステップ3完了の確認: agkan task list --tree でツリー表示が確認できればOK。

ステップ4: タグ・メタデータ管理 {#step4}

タグ管理

タグコマンドは agkan tag（agkan task tag ではない点に注意）。

# タグを作成
agkan tag add 'backend'

# タスクにタグを付与
agkan tag attach 2 'backend'

# タスクのタグを確認
agkan tag show 2

Tags for Task #2
════════════════════════════════════════════════════════════════════════════════
Title: フロントエンド実装
Status: in_progress

Tags: 1 tag(s)
  • [1] backend

タグでフィルタリングした一覧表示もできる。

agkan task list --tag backend

メタデータ管理

優先度・工数など、任意のキーバリューペアをタスクに紐付けられる。

agkan task meta set 2 priority high
agkan task meta set 2 estimated_hours 8

✓ Metadata set successfully

Key: priority
Value: high

メタデータ一覧を確認する。

agkan task meta list 2

✓ Metadata for task #2

[priority] high

応用編：JSON出力とAI連携 {#advanced}

JSON出力でAI Agentにコンテキストを渡す

agkan の真価は JSON出力 にある。--json フラグを付けると、コマンドの出力がJSON形式になる。

agkan task list --json

{
  "totalCount": 7,
  "filters": {
    "status": null,
    "author": null,
    "tagIds": [],
    "rootOnly": false
  },
  "tasks": [
    {
      "id": 8,
      "title": "APIエンドポイント設計",
      "body": "OpenAPI仕様を書く",
      "status": "backlog",
      "parent_id": 2,
      "parent": {
        "id": 2,
        "title": "フロントエンド実装",
        "status": "in_progress"
      },
      "tags": [],
      "metadata": []
    }
  ]
}

このJSON出力をAI Agentのプロンプトに渡せば、現在のタスク状況をAIに正確に伝えられる。

Claude Code × agkan のワークフロー

実際に筆者がClaude Codeと組み合わせて使っているワークフローを紹介する。

1. セッション開始時にコンテキストを渡す

# 現在の全タスク状況をJSONで取得
agkan task list --json > /tmp/tasks.json

# Claude Codeのプロンプトに渡す
echo "現在のタスク状況: $(cat /tmp/tasks.json)" | claude

2. AIが作業を完了したらステータスを更新

agkan task update 3 status done

3. agkan agent-guide で操作ガイドをAIに渡す

agkan には agent-guide というコマンドがあり、AI Agent向けの操作ガイドを出力する。

agkan agent-guide

このガイドをAIのシステムプロンプトに含めることで、AIが自律的にagkanを操作してタスク管理を行えるようになる。

タスク数のカウント

agkan task count

Task Count by Status:

  icebox: 0
  backlog: 5
  ready: 0
  in_progress: 2
  review: 0
  done: 1
  closed: 0

--json を付けるとJSONで取得でき、CI/CDパイプラインでの進捗チェックにも使える。

トラブルシュート

症状	原因	解決策
`agkan: command not found`	グローバルインストールされていないか、PATHが通っていない	`npm install -g agkan` を再実行。`npm bin -g` でパスを確認
`EACCES: permission denied`	npmのグローバルインストール権限がない	`sudo npm install -g agkan` または npmの権限設定を見直す
タグコマンドがエラーになる	`agkan task tag` は存在しない	`agkan tag add` / `agkan tag attach` を使う（`task` は不要）
データが消えた	DBパスが変わった	`.agkan.yml` の `path` 設定か `AGENT_KANBAN_DB_PATH` 環境変数を確認

まとめ

このガイドでは agkan v1.3.2 について、以下の手順で解説した。

インストール: npm install -g agkan の1コマンドで完了
基本操作: タスクのCRUD・7ステータス管理・ステータスフィルタ・キーワード検索
階層管理: --parent で親子関係、--tree でツリー表示、block add でブロック依存
タグ・メタデータ: agkan tag コマンドでタグ管理、agkan task meta でカスタムデータ
AI連携: --json 出力でAI Agentにコンテキストを渡す、agent-guide でAI向けガイド提供

AI Agentと一緒に開発するスタイルが普及する中、「AIとの会話をまたいだタスク状態の管理」は今後ますます重要になる。agkan はその課題に対して最小限の依存関係（ローカルSQLiteのみ）でシンプルに解決してくれるツールだ。

まずは npm install -g agkan で試してみてほしい。

ツール,開発

Posted by GENDOSU

Home

Developer Experienceとは

コメント一覧

まだ、コメントがありません