クラシルでサーバーサイドエンジニアをしている negi です。
Notion AI や Notion MCP を活用することで、より効率的な開発フローが実現できそうだったため、その取り組み内容を紹介します。
まずは、クラシルにおける仕様書の管理方法について触れておきます。
仕様書管理
仕様書の管理方法には、大きく分けて「ストック型」と「フロー型」の2つがあります。
ストック型は、1つの仕様書を最新の状態に保ち続ける方法です。
要件変更や設計変更があった際にも、同じドキュメントを更新していき、常に最新の状態を保つことを目指します。
一方、フロー型は、変更や追加のたびに新しい仕様書（ドキュメント）を作成していく方法です。
過去の仕様書は変更することはなく、履歴や経緯をドキュメントとして積み重ねていくことが特徴です。
クラシルでは、仕様書の運用において「フロー型」のスタイルを採用しています。
ユーザーの反応や事業状況に応じてプロダクトの仕様は日々変化していくため、1つの仕様書を常に最新の状態に保ち続ける「ストック型」の運用は、現実的には難しいです。
また、仕様の背景や判断の経緯を後から振り返りたいというニーズも多くあります。
「なぜこの設計になったのか？」「いつ誰が決めたのか？」といった情報は、「ストック型」の運用では失われやすいです。
こうした課題を解消するために、クラシルではドキュメントを新たに作成していくフロー型の運用を採用しています。
実際にクラシルで記載している仕様書の項目は以下の通りです。
記載内容の一覧
# 目的・経緯
- 目的や背景
- UI イメージ
# 仕様
- 実装内容の概要
# DB 設計
- ER 図
- テーブル定義（カラム名、型、用途など）
- インデックス定義
- レコード数の試算
- レコード例
# エンドポイント設計
- シーケンス図
- 処理概要
# 外部サービス
- AWS やサードパーティサービスの利用内容
- 各サービスの制約事項
# 品質担保
- テストケース（正常系・異常系）
- RSpec・実機確認の内容
# デプロイ
- デプロイ先サーバ一覧
- デプロイ順序
フロー型の課題
フロー型では 変更点だけを記載すればよく、メンテナンスコストを大幅に削減 できるという利点があります。
しかし、その代わりに以下のような課題が発生します。
- 変更のたびに既存の処理内容を書き起こす必要がある
- ドキュメントが増えすぎて、仕様全体を俯瞰しにくくなる
- テンプレートが適切でないと、記述の質にばらつきが生じる
これらの課題に対して、以下のような対策を行っています。
既存の処理を毎回書き起こす必要がある
Notion AI を活用し、テキストからシーケンス図のベースを自動生成することが可能です。
下記のようにAI が自動的にシーケンス図のベースを作ってくれるため、記述時間を大幅に短縮できます。
検証
プロンプト送信
結果
仕様全体の俯瞰がしにくい
Pull Request と仕様書を紐づける運用を行っています。
Pull Request に Notion の仕様書リンクを記載することで、レビュー時に「何が、なぜ変更されたのか」がすぐに追えるようになり、実装の意図や背景をドキュメントから簡単に把握できます。
テンプレートによる記述のばらつき
Notion の「テンプレートボタン」機能を活用しています。
変更内容に応じて、必要なテンプレートだけが表示されるように設定しており、記述のばらつきや冗長な情報記載を防止できます。
例
エンドポイントの追加・変更・削除のテンプレートボタンを用意
エンドポイントの追加する場合はボタンをクリックするとテンプレートが追加される
Notion MCP を使ったコード生成の検証
仕様書が完成したあとは実装に入りますが、
今回は Notion MCP を活用してコード生成がどこまで実用的か検証してみました。
※Notion MCPのコード生成にはClaude Codeを使用
検証：レシピ一覧 API の新規追加
検証用に、以下の仕様を記載したドキュメントを作成しました。
- 新規テーブル追加（recipes）
- テーブル定義（カラム、型、用途など）
- API の新規追加（GET /api/v1/recipes）
- シーケンス図付き
- シーケンス図付き
この仕様書を用意した上で、Notion MCP に対して以下のプロンプトを送信しました。
https://www.notion.so/XXXXXXXXXXXXXXXXXXXXXXXX
この仕様書を参照し、コードを生成してください。
結果
出力されたコード
生成されたコードは、仕様書に記載した内容を大枠で反映した構造になっており、土台として十分使えるレベルでした。
特にルーティング・コントローラー・モデル構造の初期設計が再現されており、実装の叩き台として有効でした。
もちろん細部には手直しが必要ですが、設計・実装の初期負荷を軽減するには非常に効果的だと感じました。
まとめ
今回は、クラシルで実践している Notion を活用した仕様書管理と、Notion MCP によるコード生成の検証を紹介しました。
フロー型の仕様書運用はメンテナンスコストを抑えられる一方で、ドキュメントの見通しや品質を保つには工夫が必要です。
私たちは Notion AI やテンプレートボタンを活用し、記述の効率化と標準化を図っています。
また、Notion MCP によるコード生成は、現在はあくまで検証段階であるものの、初期のたたき台として十分実用的であり、開発スピードの向上にもつながると感じています。今後はより精度の高いコード生成を実現するために、仕様書テンプレートの整備や誰が書いても一定品質のアウトプットが得られる仕組みを構築し、開発体験の向上を目指していきたいです。
Views: 0
