Trelloを「工数計測の黒箱」に変える：Toggl APIとCLIによる計測自動化の極意
多くのチームがTrelloを導入して「進捗の可視化」に成功したと錯覚している。だが、真のプロフェッショナルは知っている。「チケットが動いた」ことと「そこにいくら投資したか」は全く別のレイヤーの話だ。
Trelloの標準機能や中途半端なPower-Upに頼るな。あれらは「なんとなく計測している風」を装うだけの、生産性のブラックホールだ。今回は、Toggl（現Toggl Track）のAPIを叩き、Trelloのタスクライフサイクルと同期させる、計測自動化の深淵へ招待する。
—
1. 思想：なぜ「手動ボタン」では失敗するのか
人間が計測ボタンを押すことに依存したシステムは、必ず崩壊する。エンジニアは実装に集中し、計測ボタンを押し忘れる。これが現実だ。
我々が目指すべきは「認知負荷ゼロの計測」である。TrelloのカードIDをキーとして、CLIツールやWebhookでトリガーを自動発行し、Togglのタイムログをバックエンドで確定させる。このアーキテクチャこそが、嘘のないプロジェクトコストの算出を可能にする。
—
2. 実装：Toggl APIとTrelloの「同期パイプライン」
Trelloのカードを開くたび、あるいは特定のリストへ移動させるたびに計測が走る仕組みを作る。ここでは、Node.jsを用いたCLIスクリプトによる自動計測の核となるロジックを提示する。
API連携の要諦
Toggl TrackのAPI（v9）を叩く際、最も重要なのは`pid`（プロジェクトID）と`wid`（ワークスペースID）の紐付けだ。Trelloのカード説明欄に隠しメタデータ（例: `[TogglID: 123456]`）を埋め込み、それをパーサーで抽出する。
/
- Trello-Toggl Sync Engine (Snippet)
- Trelloのカード説明からTogglのプロジェクトIDを抽出し、計測を開始する
/
const axios = require(‘axios’);
async function startTogglTimer(cardId, description, projectId) {
const TOGGL_API_TOKEN = process.env.TOGGL_API_TOKEN;
const auth = Buffer.from(`${TOGGL_API_TOKEN}:api_token`).toString(‘base64’);
try {
await axios.post(‘https://api.track.toggl.com/api/v9/workspaces/{wid}/time_entries’, {
description: `[Trello:${cardId}] ${description}`,
pid: parseInt(projectId),
created_with: “Trello-Automation-Script”,
start: new Date().toISOString()
}, {
headers: { ‘Authorization’: `Basic ${auth}`, ‘Content-Type’: ‘application/json’ }
});
console.log(`[Success] Tracking started for card: ${cardId}`);
} catch (err) {
console.error(`[Critical] Failed to sync with Toggl: ${err.message}`);
}
}
—
3. 上級編：Webhookによる「完全自動化」の罠と最適化
TrelloのWebhookを使って「カードが移動した瞬間に計測開始」を実現する場合、「無駄なイベント発行」によるAPIレート制限に注意が必要だ。
アーキテクチャの最適化ハック
1. デバウンス処理の実装: カードを連続でドラッグ＆ドロップした際、一瞬で複数のWebhookが飛ぶ。これをミドルウェア層で500ms〜1sのデバウンス処理を噛ませ、確定した状態のみをAPIへ流すこと。
2. イベントフィルタリング: `listAfter` が「進行中（In Progress）」のIDと一致する場合のみトリガーするようにし、完了（Done）への移動時は自動でストップAPIをコールする。
3. Webhookのレスポンス速度: TrelloのWebhookは非常に高頻度で飛ぶ。受信側のサーバーは非同期（Queue）処理を用い、Webhook受領は最短で `200 OK` を返して切断する。
—
4. プロダクトオーナーへ：生産性メトリクスの抽出
計測データが溜まったら、BIツールに流す前の「クリーニング」が不可欠だ。
- コンテキストスイッチの検知: 1枚のカードに対する計測が短時間に細切れになっていないか？（これは作業が分断されているシグナルだ）
- 見積もり乖離の特定: `Trelloのストーリーポイント` vs `Togglの計測時間`。この相関を可視化することで、チームの「見積もりの甘さ」を数学的に証明せよ。
—
5. 伝説のコーチからの提言
ツールは魔法の杖ではない。TrelloとTogglを連携させる真の目的は、「作業時間の正確な把握」を通じて、「自分たちが何に時間を奪われているか」というボトルネックを外科手術のように切除するためにある。
自動化した計測データを見て「今日は忙しかった」と満足するな。そのデータを使って、MTGを減らし、開発環境を改善し、フロー効率を最大化する。それこそが、この記事を読んでいる君たちのようなアーキテクトが成すべき、唯一の仕事だ。
さあ、スクリプトを書いてサーバーを立てろ。生産性の向こう側で会おう。