Notion AIレビュー自動化（要件定義）
Notion × Make × GitHub Actions × OpenAI を組み合わせて、要件定義ドキュメントの整形と不足指摘を自動化する仕組み。すぅ AI駆動PM が実装・公開した組織向け自動レビュー基盤。
要件入力の粒度を均一化し、レビュー往復回数を削減することを目的とする。書き手はNotionのボタンを押すだけという運用シンプルさが特徴。
解決する本質的な問題
要件定義の最大ボトルネックは2点：
- 入力の粒度が揃わない — 書き手の経験差でフォーマットがバラバラ
- レビュー基準が人によって分散する — レビュー担当者の稼働逼迫・主観的判断のブレ
テンプレート配布や教育では解決しきれないこれらの課題を、AIによる自動整形 + 赤ペン指摘で前段処理することで、後段レビューの負荷を大幅に下げる。
システム構成
[書き手]
↓ Notionページに自由記述
[Notion ボタン「要件定義レビュー」押下]
↓ ステータスを「レビュー中」へ更新
[Make Webhook]
↓ ページIDなどのメタ情報をペイロードに
[GitHub Actions (workflow_dispatch)]
↓ スクリプト（Node / Python）を実行
1. Notion API でページ内容を取得
2. テンプレート定義ページを参照→不足フィールドを補完・整形
3. レビュー観点ページを適用→不足・曖昧さを赤ペン指摘として生成
4. Notion API でページ本文・コメントを更新
5. ステータスを「完了」または「差し戻し」へ遷移
2つの定義ページ（Notionで管理）
テンプレート定義ページ
要件定義ドキュメントの章立てを定義する。
| セクション | 内容 |
|---|---|
| 概要 | 何を実現するか |
| 背景・目的 | なぜ必要か |
| 対象ユーザー／ステークホルダー | 誰が使うか |
| スコープ（含む／含まない） | 境界の明確化 |
| ユーザーストーリー | ユーザー視点の要件 |
| 受け入れ条件（テスト観点） | 検証可能な条件 |
| 非機能要件 | 性能・セキュリティ・運用 |
| 依存関係／前提／制約 | 外部依存と前提事項 |
| リスクと対応方針 | リスクの発生確率・影響度 |
| スケジュール案／優先度 | タイムラインと優先付け |
レビュー観点定義ページ
AIがチェックすべき軸を列挙する。ルール変更はこのページを更新するだけで反映される（Actionsコードの変更不要）。
観点例:
- 目的の明確さ
- スコープの境界の明確さ
- 受け入れ条件の検証可能性（「ユーザーが確認できる事実」として書かれているか）
- 非機能要件の具体性（P95応答時間・可用性・RTO/RPOなど数値目標の有無）
- 依存とリスクの記載有無
- 曖昧語の排除（「できるだけ」「なるべく」「高速」など）
赤ペン指摘のサンプル出力:
受け入れ条件に”ユーザーが確認できる事実”が書かれていません 非機能要件に数値目標（例：P95応答時間、可用性、RTO/RPO）がありません スコープの”含まない”が空欄です リスクに”発生確率と影響度”の記載がありません
設計上の重要な原則
1. Makeは中継のみ（ロジックをActionsに集約）
Makeに詳細ロジックを持たせず、中継と権限分離に徹する。整形・レビュー生成はGitHub Actionsに集約することで、保守性・テスト容易性が向上する。
2. 冪等性の担保
同じページIDへの複数回実行でも破壊的にならない設計：
- 整形済み要件は所定セクションのみを差し替え
- 赤ペン指摘はタイムスタンプ付きで追記
3. ルール変更のNotionページ完結
テンプレートとレビュー観点はNotionのページを更新するだけで反映される。Actionsのコードを頻繁に変更しない運用設計。
GitHub Actions のシークレット構成
| シークレット名 | 内容 |
|---|---|
NOTION_TOKEN | Notion統合で発行したトークン |
TEMPLATE_PAGE_ID | テンプレート定義ページのID |
REVIEW_CRITERIA_PAGE_ID | レビュー観点ページのID |
OPENAI_API_KEY | OpenAI APIキー |
権限・セキュリティ設計
- Notion統合の権限は必要最小限に限定（対象DBとテンプレート/観点ページのみ）
- GitHubのリポジトリシークレットにトークン・IDを登録（コード直書き禁止）
- Make側の認証情報はシナリオのセキュアストレージに保存
- 個人情報・機微情報を扱う場合はマスキング方針とログ保管期間を明確化
運用のコツ
- 「生の入力でよい」と周知 — 着手ハードルを下げる
- 赤ペン指摘は具体的に — 観点ページの定期調整で学習コストを下げる
- メトリクスを追う — 差し戻し率・往復回数・所要時間を計測して改善効果を可視化
- 週次で観点ページを更新 — 実際の差し戻し理由を反映する改善サイクル
処理時間の目安
| フェーズ | 時間 |
|---|---|
| レビュー着手までの待機 | 即時（ボタン押下ベース） |
| 一往復あたりの処理時間 | 2〜3分程度（AIモデルによる） |
待機中は別の作業が可能。完了後にステータスが変わるため、通知を確認して対応する。
応用ケース（要件定義以外）
- 企画書・提案書のレビュー（目的・市場分析・収益モデル・リスクのチェック）
- マニュアル・手順書の品質チェック（手順順序・注意事項・トラブル対処の確認）
- レポート・報告書の標準化
- 教育資料・研修資料の完成度チェック
- 契約書・規約のレビューポイントチェック（法的要件・解約条件など）
コアバリュー
書き手の体験を「Notionのボタン一つ」に集約することで、AIに抵抗がある人でも自然に使える。かつ、テンプレートとレビュー観点はNotionページで管理するため、PMが運用しながら継続改善できる。「初期設定コスト ＋ 恒久的な低運用コスト」のトレードオフが明確な仕組み。
トラブルシュート早見表
| 症状 | 確認ポイント |
|---|---|
| Makeが起動しない | Webhook URLの誤り・シナリオが無効 |
| GitHub Actionsが失敗 | シークレット不足・権限不足・入力パラメータ欠落 |
| Notion更新が403/404 | 統合が対象DBとページに追加されているか確認 |
| レート制限エラー | 呼び出し間隔の調整・指数バックオフ・キュー導入 |
| 文字化け・改行崩れ | リッチテキストとプレーンテキストの扱い統一 |