はじめに
「図面のない現場で、ビルを建て増しし続けるようなものです」
建設DXコンサルタントの視点から見ると、ソフトウェア開発の現場で頻発する課題は、まさにこの言葉に集約されます。
建設の世界では、設計図なしに施工を進めることはあり得ません。そんなことをすれば、構造計算が狂い、いずれ建物は崩壊します。ところが、デジタルの世界——ソフトウェア開発の現場では、これが日常茶飯事として起きています。
「機能追加が最優先で、ドキュメント更新は後回し」
「創業メンバーしか知らない仕様が山積み」
「新人が入っても、コードのどこを触ればいいか誰も即答できない」
このような状況は、多くの開発現場で見受けられます。
システムが複雑化し、ブラックボックス化していく恐怖。それはまるで、迷宮の中で手探りで工事を続けているようなものです。このままでは、いつか致命的なバグという「事故」が起きます。
今回は、そんな危機的状況を打破するために、AIコードエディタとして注目される「Cursor（カーソル）」を、単なるコーディングツールとしてではなく、「システム全体を透視するアーキテクト」として活用する方法を解説します。
建設現場におけるBIM/CIMや安全管理AIの導入効果と同様に、システム開発においてどのようにAIと対話し、埋もれていた仕様を「生きた設計図」として可視化するのか。その具体的なプロセスとROIについて共有します。
なぜ私たちのシステムは「誰も全容を知らない」状態に陥ったのか
機能追加優先の裏で積み上がった「ドキュメント負債」
まず、なぜシステムはこれほど簡単にブラックボックス化してしまうのでしょうか。
スタートアップや新規事業の立ち上げ期において、「スピード」は正義です。市場の要求に応えるため、昨日はAだった仕様が今日はBになる。そんな激流の中で、きれいに整った設計書をメンテナンスし続けるのは、正直言って不可能です。
「コードこそが正義（Source of Truth）」
エンジニアたちはそう言い聞かせ、ドキュメントを書く時間を惜しんで実装に没頭します。それはある時期までは正しい戦略でした。しかし、サービスが成長し、コード行数が数万、数十万と膨れ上がったとき、その代償は一気に降りかかります。
Wikiに残っているのは1年前の古いアーキテクチャ図だけ。実際のコードは継ぎ接ぎだらけで、クラス間の依存関係はスパゲッティのように絡み合っている。これが「ドキュメント負債」の正体です。
新入社員のオンボーディングにかかるコストの増大
この負債が最も重くのしかかるのが、新しいメンバーを迎えるときです。
一般的な開発チームでは、優秀なエンジニアを採用しても、戦力になるまでに数ヶ月以上かかるケースが少なくありません。なぜなら、彼らがコードを理解しようとしても、全体像を示す地図がないからです。
「この UserParams クラス、どこでインスタンス化されてるんですか？」
「ああ、それはたしか2年前の改修で AuthService の奥の方に移ったはず…ちょっと待って、grepしてみる」
こんな会話が毎日繰り返されます。古参メンバー（ドメインエキスパート）は質問攻めに遭い、自身の開発時間を奪われます。新人は「こんなことも分からないのか」と思われないかと萎縮し、質問を躊躇するようになります。
変更の影響範囲が見えない恐怖
そして最も恐ろしいのが、改修時のリスクです。
「ここを1行直すだけでいいはず」と思って修正したコードが、全く関係ないと思われていた決済処理に影響を与え、本番環境を停止させる。そんな悪夢のような事故は、システムの全体像が見えていないことから起こります。
建設現場で言えば、壁に釘を打ったら、裏にある配管を突き破って水漏れしたようなものです。図面があれば「そこに配管がある」と分かったはずなのに。
安全管理AIが導入された現代の建設現場では、過去のデータから危険予知が行われますが、全体像を把握していないシステム開発では、常に「事故」のリスクと隣り合わせです。
誰も全容を把握していないシステムに手を入れることへの心理的抵抗感。これが開発スピードを劇的に鈍化させ、チーム全体の士気を下げてしまいます。「なんとかしなければならない」。しかし、今さら膨大なコードを読み解いてドキュメントを起こすリソースは限られています。
そこで目をつけたのが、生成AI、特にコードベース全体を理解できる「Cursor」の活用です。
解決策の転換：AIを「コーダー」ではなく「アーキテクト」として扱う
従来のアプローチ（手動更新）の限界
通常、ドキュメント化プロジェクトというと、エンジニア全員で時間を取ってWikiを更新したり、静的解析ツールを使ってクラス図を自動生成したりします。
しかし、静的解析ツールが吐き出す図は、往々にして「詳細すぎて役に立たない」か「抽象的すぎて意味がない」かのどちらかです。数千のクラスが描かれた巨大な図を見せられても、人間はそこから文脈（コンテキスト）を読み取れません。
必要だったのは、単なるクラス図ではなく、「このデータがどう流れて、どこで加工され、どこに保存されるのか」という意味のあるストーリーとしてのアーキテクチャ図でした。
Cursorの「Composer」機能と「Agent」モードへの着目
ここでCursorの登場です。多くの人はCursorを「コードを速く書くための補完ツール」として認識していますが、最新のCursorの真価は「Composer（コンポーザー）」と「Agent（エージェント）」機能にあります。
これまでのAIエディタは、開いているファイルや選択範囲といった局所的な情報を扱うのが精一杯でした。しかし、CursorのComposer機能は、「@codebase」コマンドなどを通じてプロジェクト全体の全ファイルをコンテキストとして読み込み、複数のファイルを横断して理解・編集する能力を持っています。
ここに活路を見出すことができます。
「AIにコードを書かせるのではなく、AIにコードを読ませて、解説させればいいのではないか？」
建設現場において、図面が紛失した古い建物であっても、ドローン測量AIやレーザースキャナで空間全体をスキャンし、そこから正確な3Dモデル（BIM/CIM）を起こす現況測量が行われます。これと同じことを、CursorのComposer機能を使って、複雑化したコードの世界で行うのです。
AIエージェントとの「対話」による現状分析という発想
Cursorを「優秀なコーダー」ではなく、「外部から招聘したベテランアーキテクト」として扱うアプローチが有効です。
特に強力なのが「Agent Mode」です。これを有効にすると、AIは単に質問に答えるだけでなく、自律的に考え、必要に応じてターミナルでコマンドを実行したり、関連ファイルを検索したりして、答えを導き出します。
AIエージェントに対して、こう問いかけるのです。「Composer、現状の認証フローがどうなっているか、関連するコントローラーとサービス層を解析して図解してくれ」。
このアプローチの肝は、能動的な対話にあります。静的解析ツールは一方的に結果を出力して終わりですが、CursorのAgentなら「ここは詳しく解説して」「このモジュールの依存関係だけを抽出して」と、人間の理解度に合わせて説明の粒度を調整できます。これこそが、開発現場で求められる「生きた設計図」への入り口となります。
実践プロセス：対話型AIと作り上げる「生きた設計図」
では、具体的にどのように進めればよいのか。実際のステップとプロンプトの例を交えて解説します。ここが本記事の核心部分です。
ステップ1：現状の依存関係をMermaid記法で可視化させる
まず最初に行うべきは、主要な機能ごとのシーケンス図の作成です。ここで重要なのは、AIに「Mermaid記法」で出力させることです。Mermaidはテキストベースで図を描ける記法で、NotionやGitHubのMarkdownでもそのままレンダリングされるため、ドキュメント管理との相性が抜群です。
この作業において、以前はチャット機能を使用するのが一般的でしたが、現在はComposer機能（⌘I / Ctrl+I）を活用するのがベストプラクティスです。Composerを使用することで、プロジェクト全体の文脈をより深く理解させた状態で、マルチファイルにまたがる高度な分析が可能になります。
実際にComposerに入力するプロンプトの例を見てみましょう。
@Codebase
現在開いている `OrderService.ts` を中心に、注文確定から決済完了、そして在庫引当までの処理フローを分析してください。
その分析結果を基に、Mermaid記法でシーケンス図を作成してください。
条件：
1. 外部サービス（Stripe, SendGrid）との通信を明確に区別すること。
2. データベースへのトランザクション範囲を `rect` で囲んで明示すること。
3. エラー時の分岐処理（在庫切れ、決済失敗）も網羅すること。
この @Codebase というコンテキスト指定が極めて重要です。これによってCursorは、現在開いているファイルだけでなく、インポートされている関連ファイルや、呼び出し元のコントローラーまで遡ってコードベース全体をインデックスし、構造を把握します。
数秒後、Composerは正確なMermaidコードを生成します。それをMarkdownプレビューで確認すると、数時間かけてホワイトボードに描こうとしていた処理フローが、そこにはっきりと図示されます。
このプロセスにより、これまで見過ごされていた論理的な欠陥が露呈するケースは少なくありません。例えば、「在庫引当の前に決済処理が走っている」といった重大な設計ミスが、コードの行間を読むだけでは気づきにくいものの、図として視覚化されることで一瞬で明らかになるのです。
ステップ2：AIとの壁打ちでボトルネックを特定する
図が出力されたら、次はAIとの「壁打ち」です。ここが静的解析ツールとの決定的な違いです。一方的に解析結果を受け取るのではなく、対話を通じて理解を深めます。
Cursorのモデル設定を、推論能力に定評のある「Claudeの最新モデル」や「ChatGPT」などに切り替え、続けて以下のように質問を投げかけます。
このシーケンス図の中で、パフォーマンスのボトルネックになりそうな箇所はどこですか？
また、将来的にマイクロサービス化する場合、どの部分で分割するのが適切か、依存関係の強さから推論してください。
AIからは、アーキテクト視点の鋭い回答が返ってくることが期待できます。
例えば、「InventoryService への問い合わせが同期処理で行われており、かつループ内で呼び出されているため、注文数が増えるとレイテンシが悪化する可能性があります。これをイベント駆動（非同期）にする案が考えられます」といった指摘です。
AIの指摘が常に100%正しいとは限りませんが、チーム内で議論を始めるための「たたき台」としては十分すぎる品質です。ゼロから議論するよりも、AIが提示した仮説を検証する形の方が、合意形成までの時間は大幅に短縮されます。
ステップ3：リファクタリング案のシミュレーションと合意形成
現状（As-Is）が見えたら、次は理想（To-Be）の設計です。
「もしここを非同期処理に変えたら、図はどう変わる？」とComposerで問いかけ、修正後のシーケンス図を生成させます。BeforeとAfterの図を並べて比較することで、チーム全員が「改修によって何がどう変わるのか」を直感的に理解できるようになります。
これは建設現場におけるBIM/CIM（Building Information Modeling）の考え方に通じます。実際に施工を始める前に、デジタル上で3次元モデル（設計図）を用いてシミュレーションを行い、干渉や問題点を事前に潰しておく。これをCursor上で行うことで、実装後の手戻りリスクを極限まで減らすことが可能です。
さらに、最新のAgent Modeを活用すれば、この設計図に基づいたプロトタイプコードの実装までを自律的に試行させることも可能です。施工管理AIが工程を最適化するように、まずは可視化によって合意形成を図り、その後の実装フェーズもAIエージェントと伴走することで、プロジェクトの進行速度と品質の両立が期待できます。
導入の成果：ドキュメントが「死蔵される資料」から「開発の羅針盤」へ
適切にAIを導入し、この取り組みを集中的に行った結果、開発現場に劇的な変化が訪れた事例があります。
オンボーディング期間が3ヶ月から1ヶ月へ短縮
最も顕著な効果は、新メンバーの立ち上がりスピードです。
「まずはこのWikiを見て。Cursorで作った最新のアーキテクチャ図があるから」
そう伝えるだけで、新人はシステムの全体像を掴めるようになります。以前のように「コードの海」に放り込まれて溺れることはありません。コードを読む際も、横に図を置いて照らし合わせることで、理解度が格段に上がります。
結果として、最初のプルリクエストを出すまでの期間が平均3ヶ月から1ヶ月へと、約3分の1に短縮されるケースも報告されています。これは採用コストや教育コストの観点から見ても、高いROI（投資対効果）をもたらします。
レビュー時の「仕様確認待ち」時間の削減
コードレビューの質も変わります。
以前は「この変更、あっちの機能に影響ない？」という確認のために、レビュアーが別ファイルを開いて調査する必要があり、レビューが数日止まることも珍しくありませんでした。
しかし、例えばプルリクエストの説明欄に、Cursorで生成した「変更箇所の依存関係図（Mermaid）」を貼り付けるルールを導入したとします。レビュアーは図を見るだけで影響範囲を把握でき、安心してApproveボタンを押せるようになります。
「仕様確認待ち」という無駄なアイドルタイムが削減され、デプロイ頻度は向上します。
常に最新状態を保てるエコシステムの確立
そして何より重要なのは、ドキュメントが「陳腐化しない」という点です。
仕様が変わったら、またCursorに「今のコードに合わせて図を更新して」と頼めばいいだけです。人間がVisioやPowerPointで線を引く必要はありません。更新コストがほぼゼロになったことで、ドキュメントは常に「生きた状態」を保てるようになります。
「ドキュメントは嘘をつくが、コードは嘘をつかない」という格言がありますが、AIを活用することで「コードから生成されたドキュメントもまた、嘘をつかない」という新しい常識を手に入れることができるのです。
現場からの提言：AIエージェントと共存する未来のアーキテクト像
AIは「正解」ではなく「視点」を提供してくれる
最後に、建設DXコンサルタントの視点から考察します。
CursorのようなAIエージェントは非常に強力ですが、決して万能ではありません。彼らが生成する図や解説には、時に間違いや誤解が含まれます。しかし、それでも価値があるのです。
安全管理AIが現場の潜在的な危険をアラートするように、AIからの「ここは密結合になりすぎていませんか？」「この例外処理は漏れていませんか？」という問いかけは、当たり前だと思っていたコードを見直すきっかけを与えてくれます。
人間が担うべきは「構想」と「意思決定」
AIが詳細な図面を引いてくれるようになった今、人間に求められる役割は何でしょうか。
それは、細かい線を引く作業ではなく、「どのようなシステムを作るべきか」という構想（Concept）と、「どのトレードオフを受け入れるか」という意思決定（Decision）です。
建設現場でも、図面を描く作業がBIM/CIMで自動化されても、建築家の仕事はなくなりません。むしろ、より創造的で本質的な設計業務に集中できるようになります。ソフトウェア開発も同じです。
明日から始められる可視化の第一歩
もし開発チームが、ブラックボックス化したシステムに苦しんでいるなら、まずはCursorにこう聞いてみてください。
「@Codebase このプロジェクトの概要を、新入社員にもわかるように説明して」
そこから対話を始めましょう。AIをコーダーとしてだけでなく、チームの「専属アーキテクト」として迎え入れるのです。
暗闇の中で手探りを続けるのはもう終わりにしましょう。AIという照明を使って、システム全体を明るく照らし出し、再び自信を持って開発を進められる環境を取り戻すのです。
それは決して難しいことではありません。必要なのは、ツールを使いこなす少しの勇気と、現状を変えたいという強い意志だけです。
さあ、開発現場にも「生きた設計図」を広げましょう。
コメント