ジャンプTOON ソフトウェアエンジニアの國師 (@ronnnnn_jp) です。

この記事では、仕様書の作成・レビューに生成 AI を活用するための実践的なアプローチを紹介します。

目次

1. 生成 AI による開発効率の変化
2. LLM の特徴と制約
3. コンテキスト情報の整備
4. 手順や制約の明確化
5. 評価と効果
6. なぜ Notion AI か
7. おわりに

生成 AI による開発効率の変化

2024 年 5 月にサービスを開始したジャンプTOON は、モバイルアプリケーションと Web ブラウザアプリケーションを提供しています。バックエンドも含め、ジャンプTOONの開発は大きく次の流れで進みます。PM が企画と仕様策定を行い、開発メンバー (エンジニア、デザイナ、QA など) を巻き込んで仕様をブラッシュアップします。その後、デザイナが UI デザイン、エンジニアが実装を進めます。

昨今ではコーディング AI エージェントと共にコーディングを行う流れが加速し、私たちのチームのエンジニアも積極的に使用しています。AI エージェントによる設計やコード生成、実装・レビューに関連するワークフローの自動化に伴い、エンジニアが主軸となる開発工程は効率化が進んでいます。

一方、エンジニアが主軸となる開発工程が効率化されることで、その前後の工程がボトルネックとして顕在化してきました。

仕様書の作成とレビューといった上流工程をより効率化、整備することは、エンジニアリングの後段にある QA 工程にも効いてくるのではないかという仮説のもと、企画、仕様策定フェーズにメスを入れることに決めました。

💡 企画書や仕様書というのは Web サービス界隈では一般的な用語であるものの、チームによって定義が異なるため、私たちのチームでの扱いをここに定義します。

企画書

企画書とは、新機能や施策の「Why（なぜやるか）」と「What（何をやるか）」を定義するドキュメントです。詳細な実装仕様（How）を記述する仕様書の前段階に位置します。

仕様書

仕様書とは、企画書で定義された「Why / What」を「How（どう実現するか）」に落とし込むドキュメントです。開発者・QA が実装・検証可能なレベルで、機能の振る舞いを詳細に記述します。

企画書と仕様書の違い

観点	企画書	仕様書
目的	Why / What を定義	How を定義
粒度	概要・方針レベル	詳細・実装レベル
対象読者	意思決定者、ステークホルダー	開発者、QA
成果物	施策の承認	実装可能な設計

LLM の特徴と制約

LLM (Large Language Model) は、非構造化テキストデータの生成が得意です。仕様書といった特定パターンの抽出をプログラム的に処理することが難しいドキュメントとの相性が良いです。

一方で、LLM 単体にはコンテキスト維持の難しさ、コンテキスト長の制限、知識更新ができないなどの制約があります。そこで AI エージェント側では、会話履歴の要約、function calling、RAG などを組み合わせ、制約がある前提でもより良い出力を得る工夫がされています。この制約を背景に、「Context Engineering」と呼ばれるように、コンテキスト設計自体が成果を左右する、という見方も広がっています。

また、LLM は次の出力を確率的に選択するというメカニズムから (他の要因もあります)、出力にブレが生じることが多いです。Temperature や Top-p、Top-k といったパラメータで出力を調整することも可能ですが、AI エージェントを使用する際にはそれらのパラメータまで調整することは一般的に少ないと思います (あるいはそもそも調整できない)。

つまり、自由度が高く、比較的トークン数の大きい非構造化データである仕様書を LLM でうまく扱うには、渡すコンテキスト情報の整備と、明確な手順や制約を含む指示 (プロンプト) が必要不可欠です。これらは LLM の制約を相互に補う役割を担います。

この記事でも、

• コンテキスト情報の整備
• 手順や制約の明確化

この 2 点に焦点を当てつつ、仕様書の作成・レビューというユースケースでどうしたかを紹介します。

コンテキスト情報の整備

私たちのサービスは既にローンチから 2 年弱経過しており、アーカイブ済みも含め 200 を超える既存の仕様書をすべてコンテキストに含めることはできません。

これらの背景と LLM の特徴・制約を踏まえ、最初から AI に任せるのではなく、まずは仕様書の作成やレビュー時に参照するコンテキスト情報の整備から開始しました。

カテゴライズ

作成やレビュー対象の仕様書と関連性の高い仕様書を効率よく探索させるため、既存の仕様書をカテゴリ分けしました。カテゴリは「大カテゴリ」により大きく分類し、さらにそこから「サブカテゴリ」でより詳細な分類を行っています。

これらのカテゴリを「メタデータ」として仕様書に付与することで、AI エージェントが関連する仕様書を探索しやすくしています。

画面遷移図の作成

私たちはクライアントアプリケーションを提供している以上、画面遷移に関する仕様を定義する機会が多いです。

仕様書同士の関係性は仕様書の階層構造や仕様書内の参照である程度解決できますが、クライアントアプリケーションの画面同士の関係性は仕様書のそれと必ずしも一致しません。そこで、画面遷移に関する情報を仕様書とは別に与えることで、画面遷移を考慮した仕様を LLM が生成できるのではないかと考えました。

画面遷移図の作成にあたっては、コーディング AI エージェントを活用し、クライアントアプリケーションのソースコードをもとに原案を作成させ、人間の目でチェックしながら AI エージェントを使用してブラッシュアップしました。

ちなみに、先のカテゴライズに関しても AI エージェントと協業して作成したものですが、この画面遷移図を渡すことで精度が大きく向上しました。

用語集の更新

私たちはサービスの立ち上げ当初から、仕様書とは別に「サービス用語集」というサービス独自のユビキタス言語をドキュメントとして管理・運用してきました。このナレッジベースへの追加・更新は特にルールやフローがなく、サービス全体の用語を網羅できているとは言えない状況でした。この状況で AI エージェントに仕様書の作成やレビューを行わせても、用語の意味を正確に捉えられず、アウトプットの品質が下がることが想像できます。これも AI エージェントと協業し、サービス用語集の最新化を行いました。

アーカイブ

サービスを運営している期間が長くなればなるほど、過去の仕様や使われなくなった用語が発生します。基本的には最新の仕様をベースとして、新しい機能の仕様書を作成することが多いため、AI エージェントにとってノイズにならないよう整理する必要があります。ただ、過去の仕様や用語も参照したくなるケースもあるため、古くなった仕様書や用語は削除せず、アーカイブ状態が分かるようにしました。

手順や制約の明確化

先の LLM の特徴でも言及しましたが、LLM 単体ではリクエストごとにコンテキストやプロンプトの記憶が分離されます。一般的な AI エージェントは、セッションという単位でコンテキストやリクエストの履歴などを保持することで、会話の流れを汲み取った出力を得ることができます。しかし、セッション間で記憶を維持、整理し出力に反映するような AI エージェントは提供され始めてはいるものの、まだ一般的とは言いにくい印象です。

私たちのチームではドキュメント管理に Notion を利用しており、その上で動作する Notion AI を仕様書の作成、レビューで活用しています。その Notion AI も現時点で確認できた公開情報の範囲では、セッション間で永続的に記憶を保持する機能は明示されていません。

そのため、AI エージェントにどういう制約の下、どういう手順で何をさせたいかを言語化することにしました。これは、LLM の再現性という課題を緩和させることが狙いです。

フォーマット策定

AI エージェントにただ「仕様書を作成して」と指示するだけでは、おそらく毎回異なる形式、内容、観点の仕様書が出力されるでしょう。そこで、一つの大きな制約として仕様書のフォーマットを定め、それに従って出力されるようにしました。

仕様書のフォーマットは、

• AI エージェントにとってどのような内容をどのような順で出力すれば良いかというガイドライン
• 何を無視し出力しないかというガードレール

の両側面の役割を持ちます。

# 概要
※ 施策の概要を記載

## 企画書
※ 企画書のリンク

## 要件
※ 施策の要件を簡潔に記載

## やらないこと
※ やらないことを明記

## デザイン
※ 完成したデザイン (Figma) へのリンク

# 使用する単語
※ 使用する用語を用語集データベースに追加した上で参照

# 全体フロー図
※ Mermaid を用いて、この機能全体の大まかな処理フローを可視化

# ユーザ面
※ 画面単位で仕様を記載

## {機能名}

### {画面名}

**概要**
※ この画面の目的やユーザ操作によるアプリケーションの挙動を記載

**構成要素**
※ 該当画面に配置されている要素をすべて記載

**{要素名}**
※ 画面内の要素に対しての仕様を記載

# 管理面
※ 画面単位で仕様を記載

## {機能名}

### {画面名}

**概要**
※ この画面の目的やユーザ操作による FB を記載

**構成要素**
※ 該当画面に配置されている要素をすべて記載

**{要素名}**
※ 画面内の要素に対しての仕様を記載

## データ構造
※ 管理面で登録を行うデータを表形式で記載

| **項目** | **データ必須** | **データ形式** | **データ条件** | **ユーザ表示** | **例** | **備考** |
| --- | --- | --- | --- | --- | --- | --- |
| データ項目 | 必須登録か任意登録か | 登録時の形式 (文字列、数値等) | データの入力制限や条件 | ユーザ面で項目自体が表示されるか | データの記述例 | その他、特記事項 |

# システム面
※ 複数の画面で再利用されたり、画面を持たなかったりする挙動 (非同期・バッチ処理といったバックエンド処理含む)

## {ケース}
※ 対応・考慮すべきケース

# ログ面
※ 企画書段階で設定した理想状態を機能リリース後に評価するための状態定義、および達成するのに必要な新規ログまたは既存ログの改修

## リリース後の評価イメージ
※ 定量的に向上させたい値の変化イメージを記載

## 追加ログ
※ 要素に対して、新規で追加する必要のあるログ項目

# その他資料
※ 他の仕様書や競合他社の参考資料を記載

統一されたフォーマットは AI の出力を安定化させることはもちろん、人間にとっても可読性の向上につながると考えています (大きなフォーマット変更は慣れるまで時間を要することもありますが)。

観点チェックリスト

仕様書の作成、レビューを AI エージェントに任せるにあたり、普段から仕様書を作成してきた PM メンバーの業務フローや考え方を言語化し体系的に伝える必要があります。しかし、「仕様書の正解」を定義するために、属人化した経験や知識をすべて引き出して言語化するのは至難の業でした。そこで視点を変えて、与えたコンテキストとフォーマットから仕様書を AI エージェントに作成させたのちに、「こういう観点を守れているか」という制約を与えることで仕様書を理想系に近づける方法をとりました。

業務フローの言語化とプロンプト作成

人間の作業を AI エージェントが代替する際に気をつけたいポイントが、LLM の出力や AI エージェントの振る舞いのブレをいかに最小限にできるかです。AI エージェントの強みは、定型化が難しい処理でも目標に向けて自律的に行動できる点です。しかし、再現性が低ければ自動化のメリットが薄れます。人間の業務フローを可能な限り言語化し、手順と制約を明確にすることがこの課題を解決するための一つの方法だと考えています。

私たちが今回作成した仕様書の作成、レビュープロンプトも処理手順をステップバイステップで記述しています。これに先で説明したコンテキスト情報と制約も組み合わせることで、仕様書の作成、レビューを行う AI エージェントを実現しています。

input として渡された要件定義に基づいて、後述の手順に沿って仕様書を作成します。

# サービスについて

仕様書の対象となるサービスは、「ジャンプTOON」というオンライン Webtoon プラットフォームです。
詳細はサービス概要ページを参照してください。

# 仕様書について

仕様書とは、**企画書で定義された「Why / What」を「How（どう実現するか）」に落とし込むドキュメント**です。開発者・QA が実装・検証可能なレベルで、機能の振る舞いを詳細に記述します。

# 仕様書作成手順

下記の手順を TODO リストに加えて順に実行します。
作業途中で計画変更が必要な場合は、適宜 TODO リストを更新してください。

### TODO 初期化例

1. 要件の概要理解
2. 既存サービス用語と仕様の調査
3. 新しいサービス用語の追加
4. 仕様書の構成把握と追加調査
5. 仕様書のドラフト作成
6. ドラフトのレビューと修正
7. 仕様書の作成
8. 仕様書の完成報告

## 1. 要件の概要理解

引数として渡された要件定義を読み込み、以下の観点で要件を整理します：

- **目的**: この機能で何を実現したいか
- **対象ユーザ**: 一般ユーザ / 管理者 / 両方
- **対象プラットフォーム**: App / Web / 管理画面 / 複数
- **キーワード**: 要件に含まれる重要な用語 (後の調査で使用)

## 2. 既存サービス用語と仕様の調査

「1. 要件の概要理解」で抽出した情報を基に、既存の用語や仕様を調査します。

### 調査対象

- 用語集
- 仕様書
- 画面遷移図

### 調査手順

1. 用語集の調査
    - キーワードで用語集を検索
    - 関連する用語の定義を確認
    - 新規用語が必要かどうかを判断

2. 仕様書の調査

    #### 2-1. カテゴリの推測
    要件の内容から、仕様書の「大カテゴリ」と「サブカテゴリ」を推測します。

    #### 2-2. カテゴリベースの検索
    推測したカテゴリで仕様書データベースをクエリします。

    #### 2-3. 関連仕様の絞り込み
    クエリ結果から、関連度の高い仕様を特定します。

3. 画面遷移図の調査
    画面遷移図を参照し、機能の関連性と画面構成を把握します。

### 外部メモリへの記録

調査結果はユーザのプライベートページに以下の形式で記録します：

```markdown
# 調査メモ: {機能名}

## 要件サマリ
- {要件の概要を 3 行以内で記載}

## 関連用語
| 用語 | 定義 | 出典 |
| --- | --- | --- |
| {用語} | {定義の要約} | {ファイルパス} |

## 関連仕様
| 仕様名 | 関連理由 | 参照すべき箇所 |
| --- | --- | --- |
| {仕様名} | {なぜ関連するか} | {具体的なセクション} |

## 設計上の考慮事項
- {既存仕様との整合性で注意すべき点}
- {流用できるパターンや設計}
```

## 3. 新しいサービス用語の追加

仕様の作成にあたり用語集に存在しないサービス用語がある場合、データベースの要素として新しく追加します。

## 4. 仕様書の構成把握と追加調査

仕様書の構成は仕様書テンプレートを参照します。

## 5. 仕様書のドラフト作成

仕様書テンプレートの構成に基づき、仕様書のドラフトを作成します。

### 記載の具体例

**良い例 (要件)**:

```markdown
## 要件
- ユーザはコインショップ画面からコインを購入できる
- 購入完了後、所持コイン数がリアルタイムで更新される
- 購入履歴はマイページから確認できる
```

**悪い例 (要件)**:

```markdown
## 要件
- コイン購入機能を実装する
```

(検証可能な形式になっていない)

---

**良い例 (やらないこと)**:

```markdown
## やらないこと
- 有償コイン限定コンテンツ
  - 理由: 課金に伴う無償コイン量の制限 (有償の 20% 上限)が発生するため
- 返金対応
  - 理由: 基本方針として返金は行わない。ストアからの返金は制限不可のため、不正返金時の対応のみ記載
```

**悪い例 (やらないこと)**:

```markdown
## やらないこと
- 有償コイン限定コンテンツは対応しない
- 返金対応しない
```

(理由が記載されていない)

## 6. ドラフトのレビューと修正

レビューで問題が発見された場合、クリティカルな問題のみ修正します。

## 7. 仕様書の作成

レビューを通過したら、仕様書を完成とします。

## 8. 仕様書の完成報告

```
仕様書の作成が完了しました。
完成した仕様書は 〇〇 に保存されています。

## 作成した仕様書の概要
- {機能の概要を 1〜2 行で}

## 関連する既存仕様
- {参照した既存仕様へのリンク}

## 確認事項
- {ユーザに確認してほしい点があれば記載}
```

# 例外対応

### 要件が曖昧な場合

```
⚠️ 要件の確認が必要です：
以下の点が不明確なため、仕様書の作成を一時停止しています。
1. {不明点 1}
2. {不明点 2}
```

### 既存仕様と矛盾する場合

```
⚠️ 既存仕様との矛盾を検出しました：
- **既存仕様**: {既存仕様の内容}
  - 出典: {ファイルパス}
- **今回の要件**: {今回の要件}

どちらを優先しますか？
1. 既存仕様を維持 (今回の要件を調整)
2. 今回の要件を優先 (既存仕様の更新が必要)
```

現在、企画書のレビュー、仕様書の作成、仕様書のレビューを行う 3 つの AI エージェントを運用しています。それぞれの大まかな処理や構成は次のとおりです。企画書レビューエージェントは省略していますが、仕様書レビューエージェントと大枠は同じです。

再現性高く処理してほしいステップは手順を具体的かつ明確に、AI エージェントにアイデアを出させたり柔軟性を高めたいところは抽象度を上げるようにしています。

評価と効果

先で紹介した 3 つの AI エージェントは、BETA 版としてすでに試験運用を始めています。まだ運用を始めたばかりで評価は難しいですが、一定の評価を得られています。

これらの AI エージェントに対するフィードバックもナレッジとして蓄積しているため、数ヶ月後にフィードバックを反映して安定版としての稼働を目指しています。

また、AI エージェントや LLM は人間と同じで完璧ではありません。AI エージェントの出力をただ鵜呑みにし考えるのをやめるのではなく、一緒に考え、良い仕様書にブラッシュアップできる、そういった AI エージェントを目指しています。

今回は既存の開発フローに沿って AI エージェントを適用させましたが、開発フローの随所で生成 AI の活用が進んでいるため、開発フロー自体の見直しも検討しています。

なぜ Notion AI か

先で AI エージェントとして Notion AI を使用していると触れましたが、このセクションではおまけ的にその選定理由について触れます。

サービス開始当初から私たちはドキュメント管理に Notion を使用してきました。LLM や AI エージェントの登場により、Notion の情報をそれらに渡す機会も増えてきました。しかし、Notion はブロック単位でリッチな情報を扱える一方で、LLM に渡す入力としてはノイズになりやすい場合があり、相性が良くありませんでした。Notion AI も早い時期に登場しましたが、エージェントやプロンプトの管理機能がなく、応答の品質や手順への準拠も私たちの期待値に達しませんでした。

Notion のドキュメントをすべて Markdown 化し、GitHub で運用しつつ、GitBook 等による非エンジニアによるドキュメンテーション作業の簡略化も検証しましたが、なかなか私たちのニーズに応えられるサービスを見つけられませんでした。

そんな中 2025 年 9 月に Notion 3.0 が発表され、Notion AI のエージェント機能が公開されました。

Notion 3.0：エージェント | Notion

エージェント機能に加え、外部 LLM プロバイダーの新しいモデルへの対応により、応答の品質がかなり改善されたことを確認できました。その結果、ドキュメント資産をそのまま活用でき、非エンジニアにとってもドキュメント管理が楽であることが決め手となり、Notion AI の採用に至りました。Notion MCP の改善によりエンジニアの作業環境でも Notion のデータを引きやすくなったのも決め手のひとつです。

今後、カスタムエージェントも登場するようで、それも楽しみです。

カスタムエージェント | Notion

おわりに

この記事では、仕様書の作成とレビューを行う AI エージェントに施した工夫を紹介しました。いくつかの手法を紹介しましたが、抽象化すると至ってシンプルで、渡すコンテキストを整理すること、手順と制約を具体的かつ明確にすること、この 2 つだけです。この考え方は、仕様書の作成とレビューだけにとどまらず、生成 AI を活用した作業すべてに応用できると考えています。

ぜひ皆さんも身近な業務に生成 AI を取り入れてみてください。