ドキュメントの陳腐化を防ぐCursor活用

はじめに

こんにちは、食べログカンパニー開発本部飲食店プロダクト開発部の菅原です。所属する予約基盤チームでは、食べログ内の中心機能の1つである予約システムの開発・運用を担当しています。

大規模かつ長期にわたるサービス開発では、多くの開発者が共通の課題に直面します。その1つが「ドキュメントの陳腐化」です。

仕様変更にドキュメント修正が追いつかず、いつしかコードと乖離してしまいます。改善を試みますが、なかなか継続できずに挫折した経験を持つ方も少なくないでしょう。ドキュメント管理には多くのコストを割けない現実もあります。そのため運用によるカバーへ頼らざるを得ない状況が生まれます。

この困難なドキュメント管理を、AIに任せることができれば大きなメリットが期待できます。本記事では、主にソースコードと密接に関連する技術仕様書や設計書を「ドキュメント」と定義し、AI搭載のコードエディタであるCursorを活用した解決策を探ります。

開発を蝕む「ドキュメントの陳腐化」という技術的負債

本記事で扱う「ドキュメントの陳腐化」とは、ソースコードの変更にドキュメントの更新が追いつかず、情報が古くなって信頼性が失われた状態を指します。特に、仕様書、設計書など、コードと密接に関連するドキュメントでこの問題は顕著になります。

ドキュメントの陳腐化はなぜ発生するのでしょうか。その原因は多岐にわたります。

大規模かつ長期運用のプロジェクトでは、多数の開発者が関与します。そのためドキュメントが際限なく増え続けます。さらに、継続的な仕様変更に対してドキュメント修正が追いつきません。結果として、ソースコードとの乖離が発生します。

開発プロセスにおいても、ドキュメント更新が見積もりに含まれず、後回しにされがちです。また、一時的な情報と継続的に維持すべき情報が混在します。このことが管理の複雑化を招きます。人力での棚卸しや単純なバージョン管理といった従来対策には限界があります。

ドキュメントの陳腐化が引き起こす問題は深刻です。具体的には、以下のような問題が発生します。

探索コストの増大
- 正しい情報を探すために、開発者はソースコードを読んだり仕様の経緯を探し回る時間が増加します。
手戻りコストの発生
- 古いドキュメントを元にした設計が、実装段階での手戻りを引き起こします。
改修漏れのリスク
- ドキュメントにない仕様の考慮が漏れて、影響範囲の特定を誤る可能性があります。
属人化と開発のボトルネック
- 特定のメンバーに知識が集中し、開発の停滞を招きます。

Cursorを活用したドキュメント管理アプローチ

ドキュメント陳腐化の課題に対し、理想はソースコードの変更をトリガーとして関連ドキュメントを全自動で更新し続けることです。その実現可能性を探るために技術検証をしました。具体的には、AI搭載のコードエディタであるCursorを用いて、人間とAIで作業をする「半自動化」のワークフローを試しています。

ここで言う「半自動化」とは、人間とAIの協業ワークフローを指します。例えば、開発者が別の作業を進める間に、AIがドキュメント修正の下準備を非同期で進めるような形です。

このアプローチが実現すると、開発プロセスは次のように変わります。

メンテナンスコストの大幅な削減
- 開発者はコードに集中でき、ドキュメント修正の負担から解放されます。
常に正しいドキュメントの生成
- ドキュメントは常にソースコードと一致し、信頼できる情報源となります。
属人性の排除とナレッジの共有化
- 特定のメンバーに依存せず、誰でも正確な情報へアクセスできるようになります。

実現可能性を探るための技術検証

AIによるドキュメント更新の半自動化を実現するためには、まずAIがソースコードとドキュメントを正確に対応付けられるかを確認する必要があります。そこで、以下の3つの観点で技術検証を行いました。

ドキュメントからソースコードを特定できるか
- 古いドキュメントを元に、対応する最新のソースコードを見つけ出せるか。
ソースコードからドキュメントを特定できるか
- コード変更があった際に、影響を受けるドキュメントを特定できるか。
ドキュメントの更新案を生成できるか
- 特定した情報をもとに、ドキュメントの具体的な修正案を作成できるか。

これらの検証を通じて、AIが人間をどの程度サポートでき、半自動化ワークフローが実用的かを判断することを目指しました。

AIの性能は、与えられる情報の明確さに大きく左右されると予想されます。そこで、まずはキーワードがはっきりしている理想的なケースから検証を始め、徐々に条件を複雑化させて、実際に近い状況でAIがどこまで対応できるのかを段階的に確認していくことにしました。

キーワードが明確な予約API設計書とソースコードを用いて検証

キーワードとして特徴的なプロジェクト名が含まれており、かつAPIが独立して機能しているケースで検証します。設計書には、APIバージョンがv1からv2にアップデートするための修正点が書かれています。

設計書内容は以下となります。

現状の情報
修正方針
注意点

■ 実際に指示したプロンプト

MCPサーバーでコンフルから情報を取得してください
@{Confluence URL} 
これに対応するソース・ファイルがどこにあるか確認してください

食べログでは仕様書や設計書の管理にConfluenceを利用しています。そのためCursorのConfluence連携機能を利用して情報を取得しました。

■ Cursorの結果

・Confluenceページ（設計書）の概要
・修正方針
・注意点
・対応するソースファイル（ControllerやUsecaseなど）
・設計書で扱う機能の具体的なメソッド名
・修正内容に沿った機能
・修正が必要な箇所の洗い出し
・必要なテストケース
・関連するモデル情報
・関連するライブラリ情報
・まとめ

この検証結果から得られた知見は以下の通りです。

上手く行ったポイント
- キーワードが明確でソースコード上でも同じように利用されているため、大まかなプロンプトでも検索が可能でした。
  - キーワードがはっきりしていると検索精度が高くなりそうです。
- 設計書の内容に加えて、関連情報も取得できました。
  - AIが意図を汲み取って情報を提示してくれます。
上手くいかなかったポイントと改善策
- 必要以上の情報を取得してしまうことがありました。
  - プロンプトで必要な情報だけを要求するように指定すれば回避可能です。

汎用的なキーワードしかない予約詳細/変更の仕様書とソースコードを用いて検証

キーワードに特徴的なものがなく、一般的な用語しか含まれない仕様書で検証します。予約詳細や変更は、食べログのユーザー・店舗会員・社内管理者など、複数の箇所で利用される予約コアロジックです。

仕様書の内容は以下となります。

要件定義
予約詳細の仕様（表示）
予約詳細の仕様（処理制御）
予約詳細の仕様（処理実行）
予約変更の仕様（表示）
予約変更の仕様（処理制御）
予約変更の仕様（処理実行）

■ 1回目の実際に指示したプロンプト

以下のドキュメントをMCPを使って確認してください。この内容は古いので新しく更新したいのですがどのソースコードが該当するかわかりません。その調査と修正点をチャットにまとめてください
@{Confluence URL}

■ 1回目のCursorの結果

・該当するソースコード
　・今回対象としないソースコードのController
　・今回対象としないソースコードのView
　・今回対象としないソースコードのUsecase
　・今回対象としないソースコードのModel
・現在の実装と仕様書の差分・修正点
　・表示項目の差分
　・機能の差分
・具体的な修正が必要な箇所
・新規実装が必要な項目
・推奨する対応手順

1回目では、ほとんど期待する結果は得られませんでした。そのため、プロンプトを変更し複数回試しました。

■ 2回目のプロンプト

リポジトリ内の該当ソースの箇所をサブシステムレベルで指定しました。

以下のドキュメントをMCPを使って確認してください。この内容は古いので新しく更新したいのですがどのソースコードが該当するかわかりません。その調査と修正点をチャットにまとめてください
こちらは食べログノートの資料です。また調べてほしいのはxxxサブシステムになります。
@{Confluence URL}

※ 食べログノート: 飲食店運営者向けのオンライン予約台帳サービスです。

■ 2回目のCursorの結果

内容は割愛しますが、2回目でも正しい情報にたどり着くことはできませんでした。

■ 3回目のプロンプト

さらに具体的な情報を加えて作成しました。

以下のドキュメントをMCPを使って確認してください。この内容は古いので新しく更新したいのですがどのソースコードが該当するかわかりません。その調査と修正点をチャットにまとめてください
こちらは食べログノートの資料です。また調べてほしいのはxxxサブシステムになります。
食べログノートはtabelog_note_apiにあります。
以下の情報も参照してドキュメントと突き合わせてください。
・Controllerで使っているUsecase
・tabelog_note_apiのview presenterを確認
・ControllerやUsecaseから呼び出されているModel及びLibrary情報
@{Confluence URL}

■ 3回目のCursorの結果

・ドキュメント内容
・該当ソースコードの調査結果
　・該当する予約詳細/変更のController
　・該当する予約詳細/変更のUsecase
　・該当する予約詳細/変更のView
　・該当する予約詳細/変更のModel
　・該当する予約詳細/変更のLibrary

ほぼ必要な情報を取得できました。この検証結果から得られた知見は以下の通りです。

上手く行ったポイント
- コンテキストを詳細に渡すことで検索が可能でした。
- AI自身に調査させるフェーズを設けると精度が上がりました。
上手くいかなかったポイントと改善策
- 汎用的なキーワードだけでは検索は困難でした。
  - 詳細な情報をプロンプトで渡すことで検索範囲を絞る必要があります。
- ソースコードの調査はできましたが、修正点の洗い出しまでには至りませんでした。
  - 調査、ソースコード検索、修正のようにフェーズを分けると良さそうです。

キーワードが明確な予約APIのソースコード（Controller）を用いてドキュメント取得の検証

キーワードとして明確なプロジェクト名が含まれる予約APIのControllerを指定しました。

ソースコードの内容は以下となります。

データを登録する機能
データを取得する機能
データを削除する機能

■ 実際に指示したプロンプト

このファイルに対応するドキュメントの洗い出しをしてください。ドキュメントはMCPサーバーを使ってConfluenceにアクセスしてください。

■ Cursorの結果

・API仕様書（OpenAPI形式のyamlファイル）
・API設計書（データを登録する機能）
・API設計書（データを取得する機能）
・API設計書（データを削除する機能）
・関連ドキュメント
　・テスト設計書
　・メンテナンス手順書
　・過去のバグ情報
・技術詳細
　・認証方式
　・エラーハンドリング
　・環境
　・実装パターン

結果から必要なドキュメント情報は取得できました。この検証結果から得られた知見は以下の通りです。

上手く行ったポイント
- ソースコードのコメントに記載されたキーワードを手がかりに、正しいドキュメントを発見できました。
- 目的のドキュメント以外にも、関連する可能性のあるドキュメントを複数見つけ出すことができました。
上手くいかなかったポイントと改善策
- コメント内のキーワードも使って検索しているため、コメントがなければ精度が落ちる可能性があります。
  - 可能であればキーワードをコメントに含めると検索しやすくなります。

キーワードが明確ではない予約APIのPull Requestを用いてドキュメント取得の検証

次に、キーワードが明確ではない予約APIのControllerを指定しました。これは予約変更が可能か判定する予約コアロジックのAPIで、仕様を変更せずパフォーマンス改善のみを行ったPull Requestです。このパフォーマンス改善に関して、更新するべきドキュメントは存在しません。

ソースコードの内容は以下となります。

ある特定のN+1問題を修正したソースコード
修正したコードのテストコード

■ 1回目の実際に指示したプロンプト

このブランチの変更点をドキュメントに反映したいです。該当するドキュメントをConfluenceのMCPを使って検索してください
変更点はあくまでこのブランチで追加修正した内容に限ります。

■ 1回目のCursorの結果

・Pull Requestの修正内容
・関連度の高いドキュメント
　・関係ないバッチのリグレッションテストのドキュメント
　・関係ないテストデータの自動クリーンアップのドキュメント
　・関係ないテスト設計ガイドブックのドキュメント
・その他関連ドキュメント
　・関係ないFlakyTest対策ナレッジドキュメント
　・関係ないパフォーマンス・チューニングドキュメント
・推奨アクション
・最も関連の高いドキュメントのURL

必要なドキュメントは一つも該当しませんでした。より詳細な情報を伝えて再度確認します。

■ 2回目のプロンプト

ソースコードをより深く理解させ、検索しやすくするためにキーワードを追加しました。

このブランチの変更点をドキュメントに反映したいです。
まずは、何が修正されたかController.,Model, Libraryを確認してください。
その後、今回の修正に該当するドキュメント（設計書、仕様書）をConfluenceのMCPを使って検索してください。必ずしも必要とするドキュメントが存在するかわからないので、修正が確認できないドキュメントは不要です。
変更点はあくまでこのブランチで追加修正した内容に限ります。
また今回の対応は「予約変更可能情報の取得」「YT-008」をキーワードで確認すると良いと思います。

■ 2回目のCursor結果

・Pull Requestの修正内容
・更新すべきConfluenceドキュメント
　・予約詳細/変更仕様書
　・予約変更設計書
　・パフォーマンス改善仕様書（新規作成推奨）
・作成すべき内容
　・改善項目
　・技術的変更点
　・影響範囲
・更新の優先順位
・関連ドキュメント
・総合的な更新戦略

この内容では、結論としてパフォーマンス改善仕様書の作成を推奨されました。このPull Requestで修正したAPIの仕様書や設計書は存在しますが、今回のパフォーマンス改善に関するドキュメントは存在しません。そのため、この結論に達したことは評価できるポイントになります。

この検証結果から得られた知見は以下の通りです。

上手く行ったポイント
- 存在しないドキュメントの場合は、作成を推奨してくれました。
上手くいかなかったポイントと改善策
- キーワードに一致する内容が多いと、精査されず目的ではないものを取得してしまうことがあります。
  - キーワードはドキュメントとソースコードで一致するものを用意すると良さそうです。

ドキュメントの更新をCursorに任せることは可能か

最後に、特定されたドキュメントの更新作業をCursorに任せられるか検証しました。

上手く行ったポイント
- 元のドキュメントにはなかった暗黙的な仕様も含めて、追記を提案してくれました。
- 誤字脱字がなく、整った文章で構成された修正案を生成しました。
- 指示した修正内容を、関連する箇所へ漏れなく水平展開してくれました。
上手くいかなかったポイントと改善策
- 現状ではマークダウン形式にしか対応していないため、Confluenceなどの独自書式は崩れてしまいます。
- 一度に多くの内容を追加しようとすると、ドキュメントの本来の目的が曖昧になる傾向が見られました。

技術検証から導き出された、食べログ予約基盤チームでの実践内容

技術検証の結果、AIは強力なツールであり、ドキュメントとソースコードの検索・更新は可能だと判断しました。しかし、実際に業務へ導入するにはドキュメント管理のプロセス整理が必要不可欠です。例えば、一時的な情報と継続的に維持すべき情報が混在したままでは、本質的な改善に繋がりません。この学びを踏まえ、まずはAI活用の効果が見えやすい小〜中規模のプロジェクトで実践しました。選定理由は、キーワードが明確で検索しやすく、管理が容易なためです。

実践運用を通して、私たちは2つの手順を確立しました。

1. 既存ドキュメントの棚卸しと更新

この手順の目的は、長年更新されていなかった仕様書や設計書を、最新のソースコードの状態と同期させることです。明確なキーワードなどが無い場合もあるため、一つ一つAIでコンテキストを膨らませながら更新を行います。

手順
1. Cursorにドキュメントとソースコードの内容を理解させます。
2. 明確なキーワードがあればプロンプトに追加します。存在しない場合は範囲を限定できるようなコンテキストを追加して誘導します。
3. 一致するまで繰り返し情報を増やしていき、範囲を限定させながら情報を取得します。
4. Cursorにドキュメントとソースコードの修正案を提示させ、開発者がレビューします。必要な情報だけ取捨選択を行います。
5. 選択した内容で、Cursorに最終的な更新を実行させます。次回更新時にドキュメントを更新しやすくなる情報も追記してもらいます。

2. 新規開発時のドキュメント作成支援

このワークフローは、新規機能開発や仕様変更に伴う、設計書・仕様書の作成コスト削減を目的としています。

手順
1. Cursorに実現したいことを伝えて、仕様書・設計書の草案を作成させます。
2. 開発者が草案をレビューし、コメントを残します。
3. レビューコメントをCursorに読み込ませ、「この指摘を反映して修正して」のように指示し、ドキュメントをブラッシュアップします。
4. 完成したドキュメントを元にコード修正を行います。
5. 最終的なコードとドキュメントに乖離がある場合は、Cursorに修正を指示します。

これらの取り組みにより、ドキュメントが最新化され、結果としてAIのコンテキスト理解も向上しました。人が手作業で行うと1ドキュメント30分かかっていた修正が、Cursorを用いることで1分以内に完了するなど、具体的な業務効率化にも繋がっています。

実際にCursorで更新するにあたっての課題と工夫

Cursorの活用は常にうまくいくというわけではありません。技術検証や実践を通して、いくつかの課題と、それを乗り越えるための工夫が必要です。

AI活用の前にドキュメントを整理する
- AIに任せる前に、人間がドキュメントの目的を明確にし、継続的に維持すべき情報を整理することが重要です。
暗黙的なコンテキストを追加で与える
- 単純なプロンプトだけでなく、背景や目的といった人間が持つ暗黙的なコンテキストを補足情報として与えることで、AIの出力精度は向上します。
タスクを細かく分割する
- 一度に大きなタスクを任せるのではなく、小さなステップに分割して一歩一歩進めることで、結果をコントロールしやすくなります。

現在のCursorには、ハルシネーション（もっともらしい嘘の情報を生成する現象）や検索範囲の制約といった技術的な限界も存在します。また、大量のドキュメントを一度に更新しようとすると、検索が困難になるという運用上の課題もあります。これらの限界を理解し、うまく付き合っていく必要があります。

今後の展望と課題

今回の取り組みは、ドキュメント管理の最適化に向けた第一歩です。今後は個別のドキュメント修正に留まらず、組織全体の管理プロセスを見直す必要があります。AI時代のベストプラクティスとして、Markdownでの一元管理なども視野に入れつつ、食べログにとって最適なドキュメント活用のあり方を模索していきます。

最終的な目標は、今回確立した人間とAIの協業モデル（半自動化）をさらに発展させることです。CI/CDパイプラインへの組み込みなどを通して、より自律的なドキュメント更新の仕組みを構築することを目指しています。