進捗管理ダッシュボード

タスク管理ツール（Linear）のデータを自動で取得し、AIが健康度を判定、HTMLダッシュボードを生成してSlackに画像付きで通知するツールです。

┌──────────────────────────────────────────────────────────────┐
│  📊 マガジン進捗管理ダッシュボード                              │
│                                                              │
│  💊 進捗健康度                                                │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐               │
│  │ 企画案  │ │ 構成   │ │ 原稿   │ │ 動画   │               │
│  │  🟢    │ │  🟡   │ │  🟢   │ │  🔴   │               │
│  │  順調   │ │  注意  │ │  順調  │ │  危険  │               │
│  └────────┘ └────────┘ └────────┘ └────────┘               │
│                                                              │
│  🤖 AIからの提案                                              │
│  🔥 優先度：高 ─ 動画編集が3日遅延...                          │
│  🧭 優先度：中 ─ 原稿の引き継ぎを...                           │
│  🌱 優先度：低 ─ ナレッジを蓄積...                             │
│                                                              │
│  📋 マガジン別ステータス / 📅 カレンダー                        │
└──────────────────────────────────────────────────────────────┘

Slackにはこのダッシュボードのスクリーンショットが3枚届きます。ブラウザで詳細も確認できます。

一人でも使えます。自分のLinearにタスクを登録すればダッシュボードが動きます。チームメンバーがいなくても問題ありません。

---

料金について

このツールで使う外部サービスはすべて無料枠で利用できます。

サービス	用途	料金
Linear	タスク管理（データの取得元）	Free プランで十分
Gemini API	AIによる改善提案の生成	無料枠あり
Surge	ダッシュボードHTMLの公開	無料
Slack	ダッシュボード画像の通知先	無料ワークスペースで可
GitHub Actions	定期自動実行（オプション）	毎月 2,000 分無料

---

このツールの4パーツ

第3回講義で学んだ「4パーツ」が、このツールではどのファイルに対応しているかを示します。

┌─────────────┐
│  トリガー     │  .github/workflows/run-dashboard.yml
│  （いつ動く） │  → 毎朝9時 or 手動実行
└──────┬──────┘
       ▼
┌─────────────┐
│  ソース元    │  scripts/fetch-data.js
│  （データ）  │  → Linear API からタスクデータを取得
└──────┬──────┘
       ▼
┌─────────────┐  scripts/calculate-health.js    ← 健康度を計算
│  処理する場所 │  scripts/generate-ai-suggestions.js ← AIが提案を生成
│  （加工）    │  scripts/generate-dashboard.js  ← HTMLを組み立てる
└──────┬──────┘
       ▼
┌─────────────┐  scripts/deploy-to-surge.js  → ウェブに公開
│  届ける先    │  scripts/take-screenshot.js → 画像に変換
│  （配信）    │  scripts/post-to-slack.js   → Slack に通知
└─────────────┘

---

セットアップ

準備するもの

• Node.js 18 以上（持っていない場合は AI に「Node.jsをインストールして」と依頼）
• Linear アカウント（持っていない場合は Part B で作成します）
• Google アカウント（持っていない場合は Part C の前に作成してください）
• Slack ワークスペース（持っていない場合は Part D で作成します）

Part A: リポジトリを開く

1. Giteaからリポジトリをクローンする
2. Cursorでフォルダを開く
3. ターミナルを開いて依存関係をインストールする

ターミナルの開き方: Cursor/VSCode のメニュー「Terminal」→「New Terminal」、またはキーボードで Ctrl + `（バッククォート）を押す。

npm install

Part B: Linear API キーを取得する

Linear はタスク管理ツールです。このツールのデータ取得元になります。

1. Linear にアカウントを作成する（または既存のワークスペースを使う）

アカウント作成中に GitHub 連携・メンバー招待・メール通知の設定画面が表示されますが、すべてスキップ（「I'll do this later」）して問題ありません。後からいつでも設定できます。

2. Settings → 左メニューの「Account」→「Security & Access」→ Personal API keys で新しいキーを作成する

「Settings → API」で見つからない場合は、画面左メニューの「Account」セクションの下にある「Security & Access」を探してください。

APIキーは作成時の一度だけ表示されます。 コピーし忘れて画面を閉じてしまった場合は、古いキーを削除して新しく作り直せば大丈夫です。

3. .env ファイルを作成し、キーを設定する

cp .env.example .env

.env を開いて以下を設定:

MAGAZINE_LINEAR_API_KEY=lin_api_ここにコピーしたキーを貼る
MAGAZINE_LINEAR_TEAM_KEY=あなたのチームキー

MAGAZINE_LINEAR_TEAM_KEY は Linear のチーム設定画面の URL に含まれるキー（例: MYTEAM）です。

チェックポイント: 以下のコマンドでデータが取得できることを確認:

node scripts/fetch-data.js

data/linear-data.json にデータが保存されれば成功です。

:::info Linear のラベル設定 このツールは Linear のラベルグループを使って進捗を判定します。初期設定では「マガジン作成ステータス（イシュー）」というラベルグループを参照します。自分のプロジェクトに合わせて config/settings.js のラベル名を変更してください。 :::

Part C: Gemini API キーを取得する

Gemini は Google の AI です。健康度データから改善提案を自動生成します。APIキーの発行は Google AI Studio という管理画面で行います（Gemini を直接使うのではなく、API キーだけをここで取得します）。

Google アカウントが必要です。持っていない場合は先に作成してください。

1. Google AI Studio にアクセスする
2. 「Get API key」→「Create API key」でキーを作成する（既にキーがある場合はそれを使っても OK）
3. .env に追記する

MAGAZINE_GEMINI_API_KEY=ここにコピーしたキーを貼る

チェックポイント: 以下のコマンドで提案が生成されることを確認:

npm run calculate-health
npm run ai-suggestions

「生成されたAI提案」が3件表示されれば成功です。Gemini API が使えない場合も、フォールバック機能で提案は自動生成されます。

Part D: Slack Bot を作成する

Slack にダッシュボードの画像を投稿するための Bot を作ります。

Slack アカウントとワークスペースを持っていない場合は、先に Slack でワークスペースを作成してください。

1. Slack API にアクセスし「Create New App」→「From scratch」
2. 左メニューの「OAuth & Permissions」を開き、「Scopes」セクションまでスクロールする
3. 「Bot Token Scopes」の「Add an OAuth Scope」ボタンをクリックし、検索ボックスに入力して以下の2つを追加する:
   • chat:write
   • files:write
4. ページ上部の「Install to Workspace」（または左メニューの「Install App」）をクリックしてインストールする
5. インストール後に表示される「Bot User OAuth Token」（xoxb- で始まる文字列）をコピーする

トークンが見つからない場合は、左メニューの「OAuth & Permissions」を開くと「OAuth Tokens for Your Workspace」セクションに表示されています。

6. 投稿先チャンネルで /invite @あなたのBot名 を実行
7. チャンネル ID を取得（チャンネル名を右クリック → 「チャンネル詳細を表示」の最下部）
8. .env に追記する

MAGAZINE_SLACK_BOT_TOKEN=xoxb-ここにトークンを貼る
MAGAZINE_SLACK_CHANNEL_ID=C0ここにチャンネルIDを貼る

Part E: Surge アカウントを準備する

Surge はHTMLを無料で公開できるサービスです。ダッシュボードをウェブで見られるようにします。

1. 以下のコマンドでアカウントを作成する

npx surge login

メールアドレスとパスワードの入力を求められます。初回はアカウントが自動作成されます。 既存のアカウントにログインするのではなく、好きなパスワードを新しく設定してください。

ターミナルでのパスワード入力について: パスワードを入力しても画面には何も表示されません（**** も出ません）。これはセキュリティ上の仕様です。そのまま入力してEnterを押せば反映されます。

2. トークンを取得する

npx surge token

3. .env に追記する

MAGAZINE_SURGE_LOGIN=あなたのメールアドレス
MAGAZINE_SURGE_TOKEN=ここにトークンを貼る
MAGAZINE_SURGE_DOMAIN=あなたのプロジェクト名-dashboard.surge.sh

MAGAZINE_SURGE_DOMAIN は好きな名前を設定できます（例: my-team-dashboard.surge.sh）。

Part F: 動作確認

すべての環境変数が設定できたら、動作確認に進みます。

まず、スクリーンショット撮影に必要な Playwright のブラウザをインストールします:

npx playwright install chromium

次に、全パイプラインを実行します:

npm run run-all

成功すると:

• output/dashboard.html にダッシュボードが生成される
• Surge にデプロイされてブラウザで見られる
• Slack にスクリーンショット3枚が投稿される

ここまでで手動実行は完了です。毎朝自動でダッシュボードを更新してSlackに届くようにしたい場合は、次の「自動実行の設定（GitHub Actions）」に進んでください。

---

自動実行の設定（GitHub Actions）

GitHub Actions を使うと、毎朝自動でダッシュボードを更新してSlackに投稿できます。手動で毎朝コマンドを打つ必要がなくなります。

GitHub アカウントを持っていない場合は、先に GitHub でアカウントを作成してください。

設定手順

1. GitHub にリポジトリを作成し、コードをプッシュする

Gitea からクローンした場合、GitHub は別のリモートとして追加します。AIに「このリポジトリを GitHub にもプッシュしたい」と相談すれば手順を案内してもらえます。

npm ci のエラーについて: GitHub Actions のワークフローは npm ci を使って依存関係をインストールします。package-lock.json がコミットされていないと失敗するので、プッシュ前に package-lock.json が含まれていることを確認してください。

2. Settings → Secrets and variables → Actions で以下のシークレットを追加:

シークレット名	値
MAGAZINE_LINEAR_API_KEY	Linear API キー
MAGAZINE_LINEAR_TEAM_KEY	Linear チームキー
MAGAZINE_GEMINI_API_KEY	Gemini API キー
MAGAZINE_SLACK_BOT_TOKEN	Slack Bot トークン
MAGAZINE_SLACK_CHANNEL_ID	Slack チャンネル ID
MAGAZINE_SURGE_LOGIN	Surge メールアドレス
MAGAZINE_SURGE_TOKEN	Surge トークン
MAGAZINE_SURGE_DOMAIN	Surge ドメイン

3. .github/workflows/run-dashboard.yml の schedule 行のコメントを外す

  schedule:
    - cron: '0 0 * * 1-5'  # 毎朝9時（JST）、平日のみ

4. Actions タブで「ダッシュボード更新」を手動実行して動作を確認する

:::info 企画案ストック判定の制限 GitHub Actions では実行ごとにワークスペースがリセットされるため、企画案ストックの週次判定は正確に機能しません（毎回初回扱いになります）。正確な判定が必要な場合は、data/stock-tracker.json を永続化する設計を追加してください。 :::

---

カスタマイズの手順

Linear のラベル構造を変更する

config/settings.js を開いて、あなたの Linear ワークスペースのラベル名に合わせて変更してください。

export const LABEL_GROUPS = {
  parentStatus: 'あなたのラベルグループ名',
  subIssueStatus: 'あなたのサブイシューラベルグループ名',
};

export const STATUS_LABELS = {
  stock: '1.企画案ストック',      // あなたのラベル名に変更
  composition: '2.構成作成中',    // あなたのラベル名に変更
  manuscript: '3.原稿執筆中',     // あなたのラベル名に変更
  video: '4.動画編集中',          // あなたのラベル名に変更
};

担当者名を変更する

config/mappings.js の ASSIGNEE_MAPPINGS_INCLUDE と ASSIGNEE_MAPPINGS_STARTS_WITH を編集して、チームメンバーの Linear ユーザー名と表示名の対応を設定してください。

健康度の閾値を調整する

config/health-thresholds.yaml を編集します。コードを変更する必要はありません。

stock:
  healthy: 8      # ≥8本で順調（🟢）
  warning: 5      # 5-7本で注意（🟡）
delay:
  healthy: 0      # 遅延なしで順調
  warning: 1      # 1日遅延で注意

AI提案のプロンプトを調整する

config/ai-prompts/unified.md を編集します。{{CONTEXT}} の部分に健康度データが自動で挿入されます。

見た目（CSS）を変更する

config/dashboard-styles.css を編集します。ダッシュボードのデザインを自由に変更できます。

---

仕組みの解説

このツールは7つのスクリプトがパイプラインとして順番に実行されます。

npm run run-all

  ① fetch-data         Linear API からタスクデータを取得 → data/linear-data.json
  ② calculate-health   健康度を計算                      → data/health-data.json
  ③ ai-suggestions     Gemini で改善提案を生成            → data/ai-suggestions.json
  ④ generate-dashboard HTML ダッシュボードを組み立て       → output/dashboard.html
  ⑤ deploy             Surge にデプロイ                   → data/deployed-url.txt
  ⑥ screenshot         Playwright でスクリーンショット     → output/screenshot-*.png
  ⑦ post-slack         Slack に画像とサマリーを投稿

各スクリプトは独立しており、個別に実行できます:

npm run fetch-data          # ①だけ実行
npm run calculate-health    # ②だけ実行
npm run ai-suggestions      # ③だけ実行
npm run generate-dashboard  # ④だけ実行
npm run deploy              # ⑤だけ実行
npm run screenshot          # ⑥だけ実行
npm run post-slack          # ⑦だけ実行

設定ファイルの役割

ファイル	役割
config/settings.js	Linear のチームキー・ラベル名など、プロジェクト固有の設定
config/mappings.js	担当者名の変換ルール
config/health-thresholds.yaml	健康度判定の閾値（コード変更不要で調整可能）
config/ai-prompts/unified.md	AI提案生成のプロンプト
config/dashboard-styles.css	ダッシュボードの見た目

---

セキュリティについて

• .env ファイルには API キーやトークンが含まれます。Git にコミットしてはいけません
• .gitignore で .env は除外済みです
• .env.example はキーの形式だけを示したテンプレートで、実際のキーは含まれていません

⚠️ API キーやパスワードを AI チャットに貼り付けないでください。 Cursor のチャットやその他の AI ツールに API キーを送ると、外部サーバーに送信される可能性があります。キーの設定は .env ファイルへの直接入力で行い、チャット欄には貼らないようにしてください。

---

困ったときは

つまずいたときは、以下の順で相談してください。

1. AIに聞く — エラー文やスクリーンショットを貼って質問する
2. Slackのチームホームチャンネルで相談する — 「AIにこう聞いたけど解決しなかった」と経緯を添える
3. 問い合わせフォームから運営に連絡する — 試したことを一緒に書く

よくあるトラブル

症状	対処
fetch-data.js でデータが0件	Linear のラベルグループ名が settings.js と一致しているか確認
Gemini API エラー	フォールバック機能が自動で動くので、提案は生成されます
Slack not_in_channel	投稿先チャンネルで /invite @あなたのBot名 を実行
Surge デプロイ失敗	npx surge login でログイン状態を確認
スクリーンショットが真っ白	npx playwright install chromium を実行

:::info 環境制約がある場合 会社のSlackにBot追加不可、APIキーが取れないなどの制約がある場合は、ソース元をJSONファイルに変えてローカルで動かすこともできます。AIに「Linear API を使わずにサンプルデータで動かしたい」と相談してみてください。 :::