1. はじめに：なぜあなたの現場のドキュメント生成AIは「使えない」のか
多くのエンジニアが「AIに仕様書を作らせる」という試みに挑戦し、そして失敗しています。その理由は、ファイル単体のコードをチャット欄にコピペして「このコードを解説して」と頼んでしまうからです。
このようなアプローチでは、以下のような問題が発生します。
- 表面的なコードの翻訳に終始する 「
getUser()はユーザー情報を取得する関数です」といった、コードを日本語に置き換えただけの解説しか返ってこない。 - システム全体の依存関係を無視する 別のファイルに定義されているデータベースのスキーマや共通バリデーション、外部APIとの境界線をAIが認知できず、生成された仕様書が穴だらけになる。
従来の「手探りでコードを1行ずつ読む」スタイルから、「AIに構造を正確に吐き出させる」スタイルへシフトするためには、ファイル単体ではなくリポジトリ全体をコンテキスト（文脈）として丸ごと理解させる必要があります。
2. Cursorの「@Codebase」がもたらすパラダイムシフト
Cursorが持つ最も強力な機能の一つが @Codebase です。これは、プロジェクト内の全ファイルをバックグラウンドでインデックス化し、AIがリポジトリ全体の構造を俯瞰して理解できるようにする仕組みです。
これを正しく活用することで、ファイル間の複雑な依存関係や、長年の運用でブラックボックス化した「泥臭いビジネスロジック」を紐解いた、本当に実務で役立つドキュメントの自動生成が可能になります。
🚀 精度を120%に引き上げるための事前準備
@Codebase を叩く前に、以下の2点を確認・設定しておくことで、出力される仕様書の精度が劇的に向上します。
- プロジェクトインデックスの作成（必須） Cursorの
Settings > Features > Repository IndexingがHandled（インデックス完了）になっていることを確認してください。ここが未完了だと、AIがリポジトリ全体を正しく参照できず、精度が著しく低下します。 .cursorrulesによる挙動の固定 プロジェクトのルートディレクトリに.cursorrulesを配置し、「ドキュメント生成を依頼された際は、単なるコードのトレースではなく、ビジネスロジックの意図（Why）を抽出すること」をあらかじめ定義しておくのがスマートなアプローチです。
3. 【実践】ソースコードから仕様書を自動生成する最強プロンプト
Cursorの Composer または Chat を開き、@Codebase を指定した上で以下のプロンプトを投入してください。役割（Role）と出力フォーマットを厳密に固定することで、エンジニアだけでなくPMやディレクターにとっても価値のある機能仕様書がMarkdown形式で出力されます。
Markdown
# 役割
あなたは複雑なレガシーシステムのソースコードを解析し、後続のエンジニアがモダン環境（TypeScript/Next.js/AWS等）へリプレイスや機能追加を行うための「ドメイン知識付き機能仕様書」を作成する、経験豊富なシニアテクニカルディレクターです。
# 前提条件
ソースコードの表面的なトレース（「〜の処理をして、〜を返します」など）は完全に不要です。
「このコードはビジネス上、どのようなルール（ドメイン知識）を満たすために、なぜこのような実装になっているのか」を重点的に解析してください。
# 解析対象
@Codebase 内の [特定のコンポーネントやレガシーなディレクトリを指定]
# 実行指示
以下の【出力フォーマット】に厳密に従い、Markdown形式で仕様書を出力してください。
# 出力フォーマット
## 1. 業務機能・ユースケース概要
- このモジュールがビジネス上で達成している目的（一言で）
- どのようなユーザーアクション、またはバッチ処理からキックされるか
## 2. データ構造とコンテキスト
- この処理が依存している主要なデータモデル（テーブル構造、またはI/OとなるJSONのスキーマ）
- 外部API、決済基盤、または別システムとの境界線（インターフェース仕様）
## 3. 主要処理フロー（Mermaidシーケンス図）
- 正常系の処理フローを、Mermaidの `sequenceDiagram` を用いて視覚的に出力してください。
## 4. 現場の泥臭い仕様・例外・歴史的負債（★最重要）
- コード内に隠された「特殊なバリデーションルール」や「特定の顧客依存の条件分岐」
- エラーハンドリングの挙動（リトライ処理の有無、デッドロック対策、吐き出されるログのフォーマット）
- コメントアウトや古い関数名から推察される「歴史的経緯」や、リプレイス時に踏むと爆死する罠
## 5. リプレイスに向けたアーキテクチャの評価
- このコードの結合度・密結合になっている箇所の指摘
- 次のモダン化フェーズで「どこをインターフェース（境界線）として切り離すべきか」のエンジニアリング視点での提案
4. 応用：Notion APIと連携して「チームの資産」に昇華させる
Cursorがチャット欄に吐き出したMarkdownを、そのまま放置しては意味がありません。これを組織の共通ナレッジベースである「Notion」へシームレスに同期・蓄積させてこそ、仕組みとしての真価を発揮します。
- MarkdownからNotion Blocksへの変換 吐き出されたドキュメントを、Notionの仕様書データベース（「機能名」「解析日」「ステータス：リプレイス対象」などのプロパティ付き）へ構造化して流し込みます。
- TypeScriptによる自動化と冪等性（べきとうせい）の担保 Notion APIを型安全に叩くTypeScriptスクリプトを用意し、スレッドURLや一意の識別子（session_id）をキーにして重複チェックを行うロジックを組み込みます。すでにデータベース側に同じ仕様書が存在する場合は最新の解析結果で「上書き（Update）」し、存在しない場合は「新規作成（Create）」する。この冪等な同期フローを構築することで、ドキュメントの先祖返りや重複によるノイズを完全に防ぐことができます。
5. 現場で運用に乗せるためのトラブルシューティング
AIを活用したドキュメント自動生成を実務のワークフローに定着させるには、いくつかの現実的な壁を乗り越える必要があります。
① ハルシネーション（AIの嘘）を殺す「コードの二重チェック」
AIが生成した仕様書の「泥臭い仕様」セクションに書かれている関数名、条件式、またはエラーログのフォーマットが本当に正しいか、Cursorの Cmd + Shift + F（プロジェクト全体検索）を使って実在性を必ずスポットチェックするルーティンを徹底してください。特に古い言語の暗黙の型変換やトリッキーな仕様をAIが解釈する際、稀に「もっともらしい嘘」が混ざることがあります。
② コンテキストウィンドウ（トークン上限）の壁を壊す
数十万行に及ぶ巨大なレガシーシステムを一撃で @Codebase に丸投げしても、AIのコンテキストウィンドウが溢れるか、大雑把な要約しか返ってきません。 実務における職人技は、システムを「データ入力（コントローラー）層」「ビジネスロジック（サービス）層」「データ永続化（インフラ/リポジトリ）層」のようにレイヤーやドメインの境界線で適切に区切り、小さな単位でステップバイステップでCursorに食わせていくことです。上流の境界線（インターフェース）を人間が引き、中身の紐解きをAIに任せるという役割分担が最も高いパフォーマンスを発揮します。
6. まとめ：テックリードが推進すべき「ドキュメント内製化」の未来
本記事では、Cursorの @Codebase 機能を活用し、ブラックボックス化したレガシーシステムから実務で使える「ドメイン知識付き機能仕様書」を自動生成するノウハウを解説しました。
多くの現場で生成AIによるドキュメント作成が失敗に終わるのは、コードの表面的な翻訳にとどまってしまうからです。しかし、リポジトリ全体のコンテキストをAIに正しく理解させ、ビジネスロジックの「意図（Why）」や「歴史的経緯（泥臭い分岐）」に焦点を当てたプロンプトを組むことで、AIは強力な開発パートナーへと進化します。
エンジニアがドキュメント作成という単純作業や手探りのコード解析から解放され、本質的な設計やモダン化、新規機能の開発といったコア業務に集中できる環境を作ること。これこそが、これからのテックリードやディレクターに求められるAI時代の開発プロセス刷新と言えます。
まずはブラックボックス化している特定のディレクトリを一つ指定し、今回のプロンプトを試してみてください。驚くほどリアルなシステムの姿が浮き彫りになるはずです。
