【簡易版】グラフエンジニアリング — 複数チームをつなぐ「肝」を設計する

非エンジニア向けに、グラフエンジニアリングって言葉に惑わされず
グラフエンジニアリングのエッセンスを抽出し、
実用で必要な知識やよくある勘違いに対する解説をまとめたコンテンツです。

Transcript

1. GRAPH ENGINEERING / LECTURE NOTES グラフエンジニアリング — 複数チームをつなぐ「肝」 を設計する — チーム横断の「つながり」を、第一級の設計対象にする — 2026.07.29 三宅隼斗 ※ 今日は結論より問いを持ち帰る回
2. 1 第1部 概念編 グラフとは何か、なぜ 見落としが起きるのか → まず前提を揃える
3. 0 1 / W H AT I S A G R A P H グラフは、絵ではなく「つながりの情報」 ここでいうグラフは、棒グラフでも描かれた絵でも ない。「何と何がつながっているか」という情報そ のものの呼び名（数学由来）。 点＝ノード（チーム・人・ファイル・仕事）、線＝ チームA ハブ チームB エッジ（参照・連携・順序・データの流れ）。 点＝ノード／線＝エッジ、これだけで全体が書ける 実装してできるのは、 つながりの一覧 表 というテキストファイルだけ ※ 絵はあとから人間向けに描き起こした写し
4. 0 2 / T H R E E F L O W P AT T E R N S どんなワークフローも、この3つの組み合わせ
5. 0 3 / T H R E E L AY E R S 一番大事な区別 — 判断・状態・保証 文章は判断のため、構造は保証のため ※ 文章は読まれた瞬間しか働かない
6. 04 / WHY WE MISS THINGS 見落としが起きる3つの理由 1 2 ルールは「読解」される 思い出すべき瞬間がある プログラムなら100行は必ず実 「PRを作ったらマージ確認」 行。AIには新入社員のマニュ は、直後に想起されないと意 アルに近く、守られる確率 味がない。知識でなくタイミ 98%でも年数回は抜ける。 ングの問題。 AIの賢さの問題ではない 3 誰も起きていない時間が ある ルールは読む主体が起きてい る時間しか存在しない。事故 はセッションの間、チームの 間に起きる。
7. 0 4 / A C A S E S T U DY 実例: draft PR事故の解剖 syncがPR作成 自動マージ不発 draftのまま 条件を満たさず沈黙 数日間、誰も気づかない 人が偶然発見 恐ろしいのは、事故の瞬間に「間違えた人」が誰もいないこと。「期待」と「現実」 を突き合わせる係が、どこにもいなかった ※ ルールの文章を増やす対策は逆効果になりうる
8. 05 / FOUR NEW QUESTIONS 書き出すと、新しく立てられる4つの問い チームA 量の問い 不在の問い 自動の辺は2本のつもり 無い辺はどれか。見張 が、棚卸しで7本だった りの辺が0本だった 形の問い 単位の問い 集めるが配らない、と 悪い箱は無く、無い辺 いう構造の偏り が1本あっただけ チームB チームC ハブ 共有ナレッジ 手動のみ・自動0本
9. 2 第2部 実装編 図を描くことではなく、2つの テキストファイルを作ること → ここから実践のはなし
10. 06 / TWO TEXT FILES 実装の正体は、2種類のテキストファイル 状態の実装＝台帳 保証の実装＝イベント定義 — 点と辺の一覧を「項目名: 値」で書いたテ — 「この出来事が起きたら、これを実行す キストファイル る」を書いたもの — 1つの連携＝1エントリ — 例: .github/workflows/、routineのスケジュ — 例: edges.yaml ール - name: weekly-sync from: routine to: shared-knowledge expected_interval_days: 7 watch: true
11. 0 7 / YA M L B A S I C S YAML超入門 — 読み方のルールは3つだけ 1 2 3 コロンの左右 字下げの深さ 「- 」で始まる行 左が項目名、右が値 深いほど上の項目の中身 一覧の1件をあらわす md JSON YAML 人向けの文章 機械向け 人も機械も読める中間 ※ #で機械が無視する注釈が書ける（JSONは不可）
12. 08 / TWO KINDS OF RUNNERS 実行者は2種類 — routineとActions 判断の仕事はroutine、照合の仕事はActions
13. 0 9 / G AT E O R D E T E C T 止めるか、すぐ知らせるか 強制ゲート（ブランチ保護） 検知型 — 条件を満たさないと押せない、破れないル — 違反はできてしまうが、直後に必ず通知が ール 届く — privateリポジトリでは有料プランが必要 — Actionsだけで作れて無料 個人運用は検知型で十分
14. 1 0 / A U T O - G E N E R AT E D M A P S 古い地図は、無いより危険 2 1 台帳（データ） mermaidで自動生 成 点と辺の一覧。機械に 台帳を変えたPRには地 は最適だが人間は全体 図の再生成を必ず含め 像を組み立てにくい る。地図は手で編集し ない 3 人間が地図を眺め る 構造の違和感を拾うの は、最後まで人間の仕 事
15. 3 第3部 応用編 人間の組織は、同じ形をしている → 仕事と日常への置き換え
16. 11 / SAME SHAPE, EVERYWHERE 人間の組織にも、同じ構造がある ンダー通知へ ※ 家庭の例：ゴミ出しも「覚えている人が偉い」からカレ
17. 12 / RECIPES 実践レシピ一覧 1 2 台帳 見張り 検知型ゲート つながりの期待を「項目名: 値」で 定期イベントで台帳と実績を突き 必ず守りたい手順を、通知される 1ファイルに 合わせる 線に置き換える 4 5 3 6 学びの網 地図の自動生成 組み替えの定石 知見ファイル冒頭に出どころ・関 台帳からmermaidを再生成し、常 機械は「提案」まで。反映は人間 連・確認日を付ける に最新の全体像を渡す の承認後
18. 13 / TIPS 細かいtips集 事故は「切れ目」に住む。セッションの間、チーム 手動の辺も台帳に登録する。存在の記録が自動化候 の間から構造化する 補リストになる 効果は「チーム数」でなく「切れ目の数」に比例 「食い違ったら台帳が正」と正本を決め、文章側は する 参照の一行に痩せさせる 監視は、既に流れている痕跡（週次ログ）を読むほ 自動化には監視をセットで付ける。片方だけだと静 うが安くて壊れにくい かな故障が起きる 見張りが確認できるのは「辺が動いたか」まで。仕 形そのものが変わる組み替えだけは、提案→承認を 事の質は守備範囲外 必ず通す
19. 14 / GLOSSARY 用語ミニ辞典
20. 15 / A REAL GRAPH 自動 手動・未実装 実例: 複数リポジトリをつなぐ、自分の地図 ローカル GitHub 新 設 ・ 出る 辺 資産 sell-buy 未実装 秘書 → 破線・未実装 隔週・自動 自動書き込み（週次） crossteam-review 全チーム横断点検 shared-knowledge 台帳＝edges.yaml 隔週蒸留→PR claude-skills 学びの蒸留 英語 「集めるが配らない」偏りを、出る辺2本で一部解消 稼働中の自動の辺 12本／見張り対象 8本／未実装 5本 は結論より、問いを持ち帰る回でした -07-29棚卸し）｜今日 ※ shared-knowledge/GRAPH.mdより一部抜粋（2026