【ITニュース解説】Teaching an AI agent what’s blocking the sprint: a ClickUp connector for cognee

多くの開発チームでは、プロジェクトの進行を妨げる「ブロック要因」がなぜ発生しているのか、その理由が複数の場所に散らばっているという共通の課題を抱えている。例えば、あるタスクの状態、カスタムフィールドに記録された情報、過去のコメント、あるいは数週間前に作成されたドキュメントといった具合だ。これらの情報を毎日、朝礼前に全て読み込んで状況を正確に把握することは非常に難しい。

この問題に対し、AIエージェントがこれらの散らばった情報を自律的に収集し、理解できるようにする解決策が開発された。それは、ClickUpという人気のプロジェクト管理ツールと、AIエージェントの「記憶層」として機能するオープンソースのツール「cognee」を連携させるための「ClickUpコネクタ」である。このコネクタは、ClickUp内のタスク、コメント、ドキュメントといった様々な情報をAIエージェントが問い合わせ可能な「記憶」へと変換する役割を担う。さらに、ClickUpワークスペース内の情報が更新された際には、AIエージェントの記憶も自動的に同期され、常に最新の状態が保たれる仕組みだ。

このコネクタ開発の目的は、AIエージェントが「どのタスクがブロックされており、何がそれを待っているのか？」といった質問に対し、人間が時間をかけて情報を探すことなく、瞬時に正確な答えを導き出せるようにすることにある。実際に利用する際は、ClickUpのパーソナルAPIトークンを使って認証を行い、どのスペース、フォルダ、リストの情報をAIエージェントの記憶に取り込むかを指定するだけでよい。一度設定すれば、次回以降は変更があったデータだけが効率的に取得されるようになっている。

しかし、このコネクタを信頼性の高いものにするためには、ClickUpのAPI（アプリケーション・プログラミング・インターフェース）が持ついくつかの癖や制約を乗り越える必要があった。特に大きな課題の一つは、ClickUpのデータ構造が「ワークスペース」から始まり、「スペース」「フォルダ」「リスト」を経て「タスク」へと深く階層化されている点だ。もし、この階層構造を一つずつ順にたどってタスク情報を取得しようとすると、タスクを見る前に多くのAPIリクエストが発生してしまう。特に大規模なワークスペースでは、これがClickUp APIの1分あたりのリクエスト数制限（100件）の大半を消費してしまう恐れがあった。

この問題への解決策として採用されたのは、GET /team/{team_id}/taskという、チーム内の全タスクをフィルタリングして取得できる特別なAPIエンドポイントだ。このエンドポイントは、ワークスペース内の全てのリストから一度に最大100件のタスクをページ単位で取得できる上、date_updated_gtというフィルターを使って、指定した日時以降に更新されたタスクだけを効率的に取得できる。各タスク情報には、すでに所属するリスト名とフォルダ名が含まれているため、残る課題はスペース名の取得だけだった。コネクタはスペース名を一度だけ取得し、その情報をキャッシュ（一時保存）しておき、新しいタスクがこれまで認識していなかったスペースに属している場合にのみ、改めてスペース名を取得する仕組みとした。これにより、初回同期時以外はスペース名の取得にかかるAPIリクエストをほぼゼロに抑えることに成功し、大幅な効率化が実現した。

次に直面したのは、ClickUpの「カスタムフィールド」に関する課題だ。チームがタスクの重要度や担当者といった重要な情報を管理するためにカスタムフィールドを多用しているが、APIが返すカスタムフィールドの値は、人間が理解できる形式とは異なる場合が多い。例えば、ドロップダウンメニューの選択肢がAPIからは単なる数字として返されたり、担当者フィールドがユーザーIDのリストとして返されたりする。これらの値をそのままAIエージェントの記憶に渡してしまうと、「重要度は2」といった意味不明な情報として学習されてしまう。そこでコネクタは、フィールドの種類ごとの設定情報（type_config）を利用して、これらの抽象的な値を「重要度: 高」や「担当者: [ユーザー名]」といった、人間が読める意味のある形式に解決してから記憶として保存するようにした。日付、チェックボックス、通貨、評価、場所、進捗状況といった多様なカスタムフィールドタイプにも対応している。これにより、AIエージェントはより正確で有用な情報を基に判断できるようになる。

開発プロセスでは、モックデータを使ったテスト（実際のAPIを使わず、ダミーデータでテストすること）では問題なく動作したコードが、実際のClickUpワークスペースに接続した際に予期せぬ挙動を見せるという事態も発生した。二つの主要な問題点が発覚したのだ。一つ目は、増分同期に利用するdate_updated_gtというフィルターが、厳密に「指定した日時より新しい」タスクのみを返すわけではないことだ。実際には、指定した日時と「同じ」タイムスタンプを持つタスクも返されることがあり、その結果、最新のタスクが同期のたびに何度も再取得されてしまう現象が起きた。この問題を解決するため、コネクタは、タイムスタンプがカーソル（前回の同期日時）と同じで、かつ既に処理済みであることが確認されたタスクについてはスキップし、そのミリ秒単位で本当に新しいタスクが作成された場合にのみ取得するように修正された。

二つ目は、ClickUpでコメントが削除されても、タスク自体のdate_updated（更新日時）が変化しないという重要な発見だった。新しいコメントが追加されるとdate_updatedは更新されるため、これを基にした増分同期は新しいコメントを正しく取得できる。しかし、コメントが削除されてもタスクの更新日時が変わらないため、削除されたコメントがAIエージェントの記憶の中に永遠に残ってしまうという問題が発生する。この問題を解決するため、コネクタには「コメントの再チェック」機能が導入された。これはデフォルトで1日1回実行され、対象範囲内のタスクのコメントを再取得し、前回保存したコメントの「フィンガープリント」（コメント内容を表す一意の識別子）と比較する。コメントに変更があったタスクのみを再処理することで、削除されたコメントはAIエージェントの記憶から正しく除去されるようになった。

これらの同期プロセスにかかるコストについても検証が行われた。筆者のテストワークスペース（12タスク、1ドキュメント）では、初回同期には主にコメントの取得で17リクエストが発生した。変更がない状態での再同期は4リクエストで済んだ。これは、ワークスペース情報の検索、増分タスクリストの取得、削除チェック、ドキュメントリストの取得にそれぞれ1リクエストずつ消費されるためだ。日次のコメント再チェックは、タスク1件あたり約1リクエストのコストがかかるため、毎回の同期ではなく、毎日1回実行される設計となっている。

AIエージェントの記憶から情報を「忘れる」ことも重要だ。ClickUpには、削除されたアイテムを通知する仕組みがないため、コネクタは同期のたびにタスクやドキュメントのIDリストを再取得し、以前に存在していたが今回取得できなかったアイテムを「削除済み」としてマークする。そして、その情報に基づいてcogneeがAIエージェントの知識グラフやベクトルストアから該当する情報を除去する。また、万が一の事態に備えて安全策も講じられている。例えば、同期時にリストが空で返ってきた場合でも、システムが以前にデータが存在していたことを知っていれば、それを一時的な障害と判断してデータの削除をスキップする。また、処理が途中でクラッシュした場合でも、コネクタは処理が完全に成功するまで進行状況を保存しないため、次回実行時に最初からやり直すことでデータの整合性が保たれる。

現時点では、コメントのスレッド化された返信や添付ファイルのダウンロード、そしてドキュメントのスコープ設定の一部にはまだ対応していない。しかし、今回の開発を通じて得られた最大の教訓は、モックを使ったテストだけでは不十分であり、実際のAPIの振る舞いを理解し、それに基づいてテストケースを修正することの重要性だった。モック環境では問題なくパスしたバグが、実際の環境で顕在化し、その修正によってテスト環境も実際の挙動を反映するように改善された。この経験は、システム開発における現実世界のテストの価値を改めて浮き彫りにした。