【テクニカル・上級編】Notionでガントチャートやロードマップを作る方法：Mermaid記法とデータベースの使い分け – プロジェクト・ナレッジ管理活用バイブル

Notionガントチャート・ロードマップの極限最適化：データベース設計からMermaid自動生成パイプラインまで

幾多のプロジェクトを死地から救い、崩壊寸前の開発生産性を立て直してきた中で痛感してきた真理がある。
それは、「スケジュール管理ツールに人間が奉仕し始めた瞬間、そのプロジェクトは死に向かう」ということだ。

美しいガントチャートを手作業で更新するために、開発者がJiraやNotionのセルをポチポチと叩く。ステータスが変わるたびに依存関係を手動でシフトさせる。そんなエンジニアリングの本質から最も遠い無駄な労力（TOIL）を、我々は今すぐ根絶しなければならない。

Notionは、単なる「ちょっと高機能なメモ帳」ではない。適切に設計されたデータベースと、コードによる厳格な状態管理（Mermaid記法等）を組み合わせることで、人間の介在を最小限に抑えた自律駆動型のロードマップ基盤へと昇華させることができる。

本稿では、Notionにおけるガントチャート構築の2大アプローチ――「ネイティブ・タイムラインビュー」と「Mermaidコードブロック」の内部挙動を解剖し、大規模開発組織のベロシティを極限まで高めるためのアーキテクチャ設計を提示する。

—

1. 2大アプローチのアーキテクチャ比較と選定基準

Notionで時系列スケジュールを表現する場合、選択肢は主に2つ存在する。

1. Notionデータベース（タイムラインビュー / カレンダービュー）
2. Codeブロック（Mermaid.jsによるGanttチャート表現）

これらは排他関係ではない。データの「永続化・クエリ性」と「構造化・可読性」のどちらを主目的に置くかによって、明確に使い分ける必要がある。

【アーキテクトの直言】
日常的なタスクの消化、担当者のアサイン、進捗のトラッキングにはデータベース（タイムラインビュー）一択である。一方、部門横断のアーキテクチャ移行計画や、Gitリポジトリ内でコードと一緒にバージョン管理したいロードマップにはMermaidを採用すべきだ。

—

2. データベース・タイムラインビュー：パフォーマンスハックと高度な依存関係管理

Notionのタイムラインビューは、一見すると直感的だが、データ構造を誤ると数千レコードを超えたあたりからレンダリングが崩壊し、チーム全体の認知負荷を高める「負債」に変わる。

2.1 高速化のためのデータベーススキーマ設計

大規模プロジェクトにおけるタイムラインのパフォーマンスを担保するため、プロパティ設計は以下のように厳格化する。

日付プロパティの粒度統一: 「含める時間 (Include time)」は、厳密なタイムスタンプが必要なデプロイメントタスク以外ではオフにする。日単位の計算に時間を混入させると、タイムゾーンの差異によるズレ（オフセットバグ）の温床になる。
ステータス（Status）のEnum化: 自由記述のテキストは厳禁。`Not started`, `In Progress`, `Blocked`, `Done` を厳格に定義し、ロールアップやフィルターの演算コストを最小化する。
フェーズ分解リレーション: 巨大な単一テーブルを作るな。親タスク（Epic）と子タスク（Task）を自己参照リレーション（Self-relation）で結び、ガントチャート上では親タスクのみ、あるいはドリルダウン形式で表示する。

2.2 リソース競合を防ぐ自動化数式（Formula 2.0）

タイムライン上で「期限切れ（Overdue）」かつ「未完了」のタスクを動的に検出し、視覚的なアラートを出すFormula 2.0の記法を示す。これをプロパティに仕込むことで、日々のスタンドアップでの状況確認コストをゼロに近づける。

// Formula 2.0: 期限超過検知とアラートアイコン付与
let(
isDone, prop(“Status”) == “Done”,
isOverdue, prop(“Date”).end() < now(), if(isDone, "✅ 完了", if(isOverdue, "🚨 期限超過", "⏳ 進行中")) ) ---

3. Mermaid記法によるコード駆動型ロードマップの極限活用

「ドキュメントはコードであれ（Documentation as Code）」。この哲学をNotionに持ち込む最もエレガントな方法が、Mermaidブロックの活用だ。

Notion標準のコードブロックで `mermaid` を指定することで、ブラウザ側でリアルタイムにSVGレンダリングされる。

3.1 複雑な依存関係を持つロードマップの記述例

以下は、マイクロサービス移行プロジェクトにおけるクリティカルパスを可視化するMermaidのGantt構文だ。休日を除外する設定や、セクションごとの明確なグルーピングを行っている。

gantt
title Microservices Migration RoadMap 202X
dateFormat YYYY-MM-DD
axisFormat %m/%d

section インフラ基盤
Kubernetesクラスタ構築 :crit, infra1, 202X-10-01, 14d
Service Mesh (Istio)導入 :crit, infra2, after infra1, 10d

section バックエンド
認証基盤のSaaS移行 :auth, 202X-10-08, 20d
モノリスからのドメイン切り出し :core1, after infra2, 30d

section 検証・リリース
負荷テスト・セキュリティ監査 :crit, test1, after core1, 14d
本番トラフィック切り替え :milestone, rel1, after test1, 1d

3.2 Mermaidの制約を突破する知見

Notion上のMermaidは非常に美しいが、Notionデータベースと直接双方向同期しないという致命的な弱点がある。つまり、Mermaid上のバーをマウスでドラッグ＆ドロップして日程を伸ばすことはできない。

この課題に対し、真にラジカルなエンジニアは「データベースからMermaidコードを自動生成するパイプライン」を構築する。

—

4. 【極秘知見】Notion API × CLIによるガントチャートの完全自動生成パイプライン

手動でNotionデータベースを更新し、さらにMermaidコードを手書きするなどエンジニアのすることではない。Notion APIとTypeScript製スクリプトを用いて、JiraやGitHub ProjectsのイシューからNotionデータベースを同期し、最終的に最新のMermaidロードマップ文字列をNotionページに自動書き込みするパイプラインのアーキテクチャを解説する。

4.1 アーキテクチャ概要

[GitHub Issues / Jira]
│ (Webhook / 定期実行)
▼
[Node.js / TypeScript Automation Script]
│
├─► 1. Notion DatabaseのアイテムをUPSERT
├─► 2. 日付・依存関係をパースし、Mermaid構文文字列を構築
└─► 3. 指定されたNotionページのCodeブロックをAPI経由で置換

4.2 自動化スクリプト（TypeScript実装例）

以下のコードは、Notion SDK (`@notionhq/client`) を使用してデータベースからデータを取得し、MermaidのGantt文字列を動的に生成してページを更新するコアロジックである。

import { Client } from “@notionhq/client”;

// Notionクライアントの初期化（Envからトークン取得）
const notion = new Client({ auth: process.env.NOTION_API_KEY });
const DATABASE_ID = process.env.NOTION_DATABASE_ID!;
const TARGET_PAGE_ID = process.env.NOTION_TARGET_PAGE_ID!;

interface TaskRow {
title: string;
status: string;
startDate: string;
endDate: string;
}

async function fetchDatabaseTasks(): Promise {
const response = await notion.databases.query({
database_id: DATABASE_ID,
sorts: [{ property: “Date”, direction: “ascending” }],
});

return response.results.map((page: any) => {
const props = page.properties;
return {
title: props.Name.title[0]?.plain_text || “Untitled”,
status: props.Status.status.name,
startDate: props.Date.date?.start || new Date().toISOString().split(“T”)[0],
endDate: props.Date.date?.end || props.Date.date?.start,
};
});
}

function generateMermaidGantt(tasks: TaskRow[]): string {
let mermaidCode = “gantt\n title 自動生成ロードマップ\n dateFormat YYYY-MM-DD\n\n section タスク一覧\n”;

tasks.forEach((task, index) => {
const tag = task.status === “Done” ? “done, ” : “”;
mermaidCode += ` ${task.title} :${tag}t${index}, ${task.startDate}, ${task.endDate}\n`;
});

return mermaidCode;
}

async function updateNotionCodeBlock(mermaidCode: string) {
// 注意: 実運用では対象のCodeブロックのblock_idを特定しておく必要があります
const BLOCK_ID = process.env.NOTION_TARGET_BLOCK_ID!;

await notion.blocks.update({
block_id: BLOCK_ID,
code: {
rich_text: [{ type: “text”, text: { content: mermaidCode } }],
language: “mermaid”,
},
});
console.log(“Successfully updated Notion Mermaid block via API.”);
}

async function main() {
try {
const tasks = await fetchDatabaseTasks();
const mermaidSyntax = generateMermaidGantt(tasks);
await updateNotionCodeBlock(mermaidSyntax);
} catch (error) {
console.error(“Pipeline execution failed:”, error);
process.exit(1);
}
}

main();

このスクリプトをGitHub ActionsなどのCI/CDパイプラインに組み込み、毎日深夜やプルリクエストマージ時に実行することで、「誰一人として手動でガントチャートを触らないのに、常に最新かつ正確なロードマップがNotion上に描かれ続ける環境」が完成する。

—

5. エキスパートが警鐘を鳴らすアンチパターンとメモリ最適化

最後に、現場でよく見かける破滅的なアンチパターンに言及しておく。

1. 無限ネストのリレーション地獄

ガントチャートを綺麗に見せたいがために、サブタスクを4階層以上に深くする設計はパフォーマンスを著しく低下させる。Notionのクエリ深度制限とブラウザのメモリ消費（DOMノードの爆発）を引き起こすため、最大でも「Epic ＞ Task」の2階層に抑えよ。

2. 重すぎるインライン画像の多用

タイムラインの各タスクページ内に、アーキテクチャ図や高解像度のスクリーンショットを直接貼り付けるな。画像はCDNやS3に逃がし、リンクとして貼るべきだ。Notionのブロックキャッシュ容量を圧迫し、ガントチャート描画時のスクロールカクつきの主原因となる。

3. 同期の競合（Race Condition）の放置

前述のような自動化スクリプトを複数走らせた場合、Notion APIのレートリミット（通常は平均3リクエスト/秒）に抵触し、`429 Too Many Requests` が返る。指数バックオフ（Exponential Backoff）とリトライロジックを必ず実装すること。

—

結びにかえて

Notionは単なるドキュメントツールではない。API、データベース、そしてコード（Mermaid）を繋ぎ合わせることで、組織の脳髄を同期させる強力なインフラストラクチャへと変貌する。

ツールに使われるな。ツールをハックし、自動化のパイプラインを組み上げ、エンジニアがコードを書くことだけに集中できる環境を創り出すことこそが、真のテックリードの仕事である。