はじめに
こんにちは、世界。
ログラスでQAエンジニアを担当している大平です。
今回は、生成AIを使って、既存機能の仕様書を作成する話になります。
コンテキストと悩みごと
現在、社内で生成AIの活用が盛り上がっており、テストに関しても、試行錯誤をしております。
試行錯誤の結果、人間がテスト分析、設計を行い、AIでテスト実装（テストケースの作成）を任せるということまでは実践レベルで利用しています。
ただ、生成AIでテスト分析、設計を実践するためには、コンテキストとして、既存機能の詳細な仕様書の情報が必要になります。仕様書の代わりにソースコードという方法もありますが、toBのプロダクトでは、複雑なビジネスコンテキストが絡み合うためソースから仕様を読み解こうとすると、どうしても精度が低くくなります。
私が担当するプロダクトでは、PRDやマニュアルレベルのドキュメントはあるのですが、新規事業のため、機能変更の頻度が多く、詳細レベルの仕様書までは作っていませんでした。これは、メンテナンスコストを考えたうえでの判断になります。
ただ、生成AIを活用するためにはコンテキストが重要となります。今回は、生成AIに実例マッピングのプラクティスを使って、メンテナンスコストを抑えつつ、既存機能についてGherkin記法の仕様書を作成することにしました。
生成AIとGherkin記法で既存機能の仕様書をつくる
普段、私は、Claude Codeを使っているため、Gherkin記法で既存機能の仕様書をつくる仕組みをClaude Codeのカスタムスラッシュコマンドで作成しました。
カスタムスラッシュコマンドの大まかな流れとしては、Playwright MCPを活用して画面情報を調査、その後、AIがユーザーに実例マッピングのプラクティスをベースに質問をして、仕様書を作成するワークフローになります。
実際には、こんな感じです。（長いため一部省略しています）
# 既存機能の仕様書をGherkin記法でつくるワークフロー定義
### Phase 0: 既存知識の確認
#### Step 0.1: 実例マッピング、Gherkin記法の知識の確認
蓄積済み知識を把握して、的確な実例マッピングを実行します
実例マッピング、Gherkin記法の知識の確認：/XXXX/XXXX/knowledge/_knowledge.md
#### Step 0.2: ドメイン知識確認
蓄積済みドメイン知識を確認します
既存のドメイン知識を確認：/XXXX/XXXX/knowledge/domain_knowledge.json
### Phase 1: 画面情報の確認
#### Step 1.1: Web画面の分析開始
User Request: "この画面の実例マッピングをして [URL]"
1. 新しいセッションでログイン認証
2. 指定URL直接アクセス
3. DOM構造・インタラクティブ要素の詳細分析"
[Auto-execute: node /XXXX/XXXX/scripts/analyze_web.js "[target_url]"]
画面アクセス: [target_url] 正常アクセス
分析結果: /XXXX/XXXX/session/[analysis_file].json に保存
#### Step 1.2: Web画面分析結果確認・詳細表示
画面分析結果の出力
画面基本情報
- ページタイトル: [title]
- URL: [target_url]
検出された要素詳細
見出し: [N]個
[具体的な見出しテキストとレベルを列挙]
ボタン: [M]個
[具体的なボタンテキストと状態を列挙]
テーブル: [K]個
[テーブル構造の詳細を列挙]
フォーム・入力: [L]個
[フォームと入力フィールドの詳細を列挙]
#### Step 1.3: Web画面分析結果確認・ソースコード補完
サブエージェントでソースを読み込み、分析結果を補完する（一部省略）
**分析結果**: /XXXX/XXXX/session/[analysis_file].json に保存"
### Phase 2: ユーザージャーニー推定
#### Step 2.1: ユーザージャーニー推定
ドメイン知識、画面分析結果から以下のユーザージャーニー、主要操作フローを推定しました
推定ユーザージャーニー:
[推定ユーザージャーニーを列挙]
主要な操作フロー:
[主要な操作フローを列挙]
### Phase 3: 業務目的・ドメイン理解確認
#### Step 3.1: 業務目的確認
”この画面で実現したい業務目的は何ですか？具体的な業務目的を教えてください。”
#### Step 3.2: ユーザータイプ確認
"この業務を実行するユーザーはどのような人ですか？ユーザーの業務背景、所属、どのようなロール（権限）を教えてください。"
### Phase 4: 実例マッピングの質問
#### Step 4.1: 通常実例収集
"最も頻繁に発生する通常の実例を教えてください。以下の形式で教えてください"
- **前提条件**: どのような状況で開始するか
- **ユーザーアクション**: 具体的にどの要素をどう操作するか
- **期待結果**: 何が表示・変更されるか
#### Step 4.2: 例外実例マッピング
"エラーが発生する実例や例外的な状況の実例はありますか？具体的なエラー条件と、その時の画面動作を教えてください。"
#### Step 4.3: ビジネス要件、性能要件の確認
"この機能に関するビジネス要件・性能要件はありますか？具体的な要件があれば教えてください。"
#### Step 4.4: 実例マッピングの結果出力
"収集した実例マッピング情報を出力します"
### 通常実例 ([N]件)
[通常実例の一覧を表示]
### 例外実例 ([M]件)
[例外実例の一覧を表示]
### ビジネス要件・性能要件 ([P]件)
[ビジネス・性能要件の一覧を表示]
### Phase 5: ドメイン知識更新
収集した実例マッピング情報をドメイン知識として蓄積しています
[Domain knowledge update to domain_knowledge.json]
### Phase 6: Gherkin記法のfeatureファイル生成
収集した実例マッピング情報を元に[feature_name].featureを作成します
"featureファイルを生成しました！"
各フェーズの説明
Phase 0: 既存知識の確認
AIに必要なコンテキストを読み込ませるフェーズです。
Step 0.1: 実例マッピング、Gherkin記述の知識の確認
AIに実例マッピング、Gherkin記述の知識を読み込ませます。この知識は、あらかじめ、私からインプットしたものになります。
Step 0.2: ドメイン知識確認
過去に実行した際に記録したドメイン知識を読み込みます。
ドメイン知識は、「Phase 5:ドメイン知識更新」のタイミングで保存します。
Phase 1: 画面情報の確認
仕様を作成したい機能のWeb画面を分析するフェーズです。
Step 1.1: Web画面の分析開始
このコマンドの実行時に指定したURLをもとに、analyze_web.jsを実行します。
”analyze_web.js”は、Playwrightのスクリプトでテスト環境のプロダクトにログインして、Playwright MCPを利用してWeb画面を分析します。
Step 1.2: Web画面分析結果確認・詳細表示
今回、どのぐらい画面を解析したか、私が確認するために画面の分析結果を出力します。
出力結果の情報を確認して、情報が足りない場合は、私がAIにソースコードから確認する情報を指示します。
Step 1.3: Web画面分析結果確認・ソースコード補完
ソースコードを読み込み、分析するサブエージェントを呼び出して、分析結果の補完をします。
Phase 2: ユーザージャーニー推定
Web画面分析結果と既存のドメイン知識を元にAIにユーザージャーニーを推測させるフェーズです。
Step 2.1: ユーザージャーニー推定
AIがドメイン知識とWeb画面の情報からユーザージャーニー、主要操作フローを推測した内容を出力します。ここで、間違っていれば、私が指摘します。
Phase 3: 業務目的・ドメイン理解確認
仕様書を作りたい機能（Web画面）の業務目的について、私が回答するフェーズです。
Step 3.1: 業務目的確認
AIの質問”この画面で実現したい業務目的は何ですか？具体的な業務目的を教えてください。”について、私が回答します。
Step 3.2: ユーザータイプ確認
AIの質問"この業務を実行するユーザーはどのような人ですか？ユーザーの業務背景、所属、どのようなロール（権限）を教えてください。"について、私が回答します。
Phase 4: 実例マッピングの質問
AIが実例マッピングのプラクティスを使って、私に機能（Web画面）の使い方（仕様）を質問するフェーズです。
Step 4.1: 通常実例収集
一般的な使い方について、AIが質問して、私が回答します。
Step 4.2: 例外実例マッピング
例外的な処理について、AIが質問して、私が回答します。
Step 4.3: ビジネス要件、性能要件の確認
ビジネス要件・性能要件について、AIが質問して、私が回答します。
Step 4.4: 実例マッピングの結果出力
私が回答した内容をAIがまとめて出力します。ここで、間違っていることがあれば、私が指摘します。
Phase 5: ドメイン知識更新
収集した実例マッピング情報を元にドメイン知識をファイルに保存するフェーズです。
Phase 6: Gherkin記法のfeatureファイル生成
収集した実例マッピング情報を元にGherkin記述のファイル生成を作成するフェーズです。
試行錯誤したこと
対話から仕様書を作成する
このカスタムスラッシュコマンドの一番のポイントは、生成AIがソースコードを読んで仕様書を生成するのではなく、生成AIがWeb画面とソースコードの情報を元に実例マッピングのプラクティスを使って、人間に仕様をヒアリングすることです。
これは、前述の通り、現状ので生成AIでは、複雑なtoBのプロダクトのソースコードからビジネスコンテキストを読み取ることが難しいため、ビジネスコンテキストを人間が付与することで、ビジネス価値の観点で仕様書を作成することができます。
実例マッピングでは、構造化された会話を通して、フィーチャーの具体的な振る舞いを明確化していきます。本来、実例マッピングは、何かを作る際にその具体な仕様を導くために使うプラクティスですが、今回はすでにあるフィーチャーに対して、具体的なリバースエンジニアリングするために利用しています。
人間もAIも理解しやすいGherkin記法を採用する
今回の仕様書の目的は、生成AIがコンテキストを判断するためです。そのため、人間も、生成AIも読みやすいGherkin記法を採用しました。Gherkin記法で仕様書を作成していれば、今後の自動テストを進めていったときに再利用できることも採用の理由となります。
良いシナリオを人間が判断する
この仕組みは、良いシナリオとは何か（BRIEFの原則）を人間が知っている必要があります。生成AIが実例マッピングのプラクティスでヒアリングして、Gherkinファイルを作成してくれても、その成果物の良し悪しは、人間が判断しないといけません。
そのため、もし同じ取り組みをされる方がいる場合は、「The BDD Books」で勉強することをお勧めします。
継続的な学習を促す
実例マッピングのプラクティスやドメイン知識については人間がインプットします。ワークフローで得たドメイン知識として保存し、次回のワークフローで活かせるようにします。
また、ワークフローの途中でも、実例マッピングの質問仕方が悪い場合は指摘して、AIにワークフロー自体の修正をさせます。私は、ワークフローの実行中にワークフローを自体をアップデートできることが、生成AIでのワークフローを実行する際の特徴だと思います。
ワークフローの途中で良いアイディアをつけば、すぐに実践できます。実際、今回紹介したワークフローの初期はソースコードの解析がありませんでした。そこから、Web画面分析の精度がでないのでソースコードの解析を追加→コンテキストウィンドウを省エネ化するためにサブエージェント化をしています。
むすび
今回は、AI駆動開発（テスト含む）のために、まずは必要なコンテキストを作成する取り組みを紹介しました。次は、この仕様書を元にテスト分析設計を精度向上にチャレンジにしたいと思います。
みなさまの取り組みのヒントになれば幸いです。
おわり。
Discussion