GitNexusとOpenSpecで、既存リポジトリをすぐにAI駆動開発のレールに乗せる

Posted at 2026-04-08

この記事は、すでに動いている既存リポジトリを対象にしています。
新規プロジェクトでの仕様駆動開発の始め方は前回の記事をご覧ください。

はじめに

AI駆動開発を既存プロジェクトに導入しようとして、手が止まったことはないだろうか

ドキュメントは古い。仕様は人の頭の中。コードを読めば分かるが、影響範囲がどこまであるのか、把握しにくい。

この記事では、OpenSpecとGitNexusを組み合わせて、既存リポジトリをAI駆動開発に乗せやすくする手順を書いてます。

既存コードからナレッジを抽出する

OpenSpecはコーディングエージェントのための仕様駆動開発フレームワークです。

企画・設計・仕様・タスクの生成を行う仕様駆動の基本機能に加え、完了したタスクの仕様をプロジェクトのナレッジとして蓄積し、次の開発サイクルで自動参照させる仕組みが組み込まれています、詳しくは前回の記事で紹介した。

OpenSpecの機能の中に /opsx:explore という機能があります。既存のコードベースを探索して、機能構造や仕様を抽出してくれる。

/opsx:explore 機能ごとに仕様を抽出してください

実行すると、コーディングエージェントがリポジトリ内を調べ回って、モジュール構成や依存関係を整理してくれる。仕様が明文化されていない既存プロジェクトでも、コードから今どうなっているかを引き出せる。

抽出された仕様は次のタスクのナレッジとして参照されるので、仕様駆動開発の基盤が一瞬でできあがる。

ここまでは良い。問題はその探索の精度だ。

`/opsx:explore` が頼っているもの

/opsx:explore の裏側では、コーディングエージェントの標準的な検索ツールが使われている。 Grep でキーワードを探し、 Glob でファイルを見つけ、 Read で中身を読む。ファイルを探して、中身を読んで、構造を推測する、というやり方だ。

この方法には限界がある

ファイル単位の探索になる。関数Aが関数Bを呼び、Bが関数Cを呼ぶ……という実行フローは、ファイルを何個も読まないと見えない
機能の境界が分からない。「この関数はどの機能に属するのか」は、呼び出し関係を辿らないと判断できない
探索回数が増える。「この関数の呼び出し元は？」→ Grep → 「その呼び出し元は？」→ Grep → ……と何往復もする
見落としが起きる。命名規則が不統一だったり、動的な呼び出しがあると、Grepでは引っかからない

小さなリポジトリなら問題にならない。でも数十ファイルを超えると、エージェントが全体像を掴むまでに時間がかかるし、構造の見落としも増える。

要するに、コードの何がどこにあるかは探せるが、何が何とどう繋がっているかは苦手なのだ。

GitNexusで「繋がり」を可視化する

GitNexusとは

GitNexusは、リポジトリを解析してナレッジグラフを作るツールだ。

ナレッジグラフとは、モノとモノの関係を辿れる地図のような形で保持したデータ構造のこと。コードの場合は、「関数Aが関数Bを呼ぶ」「クラスCがモジュールDに依存している」といった関係がこれにあたる。

GitNexusはリポジトリ内の関数やクラスの呼び出し関係を解析して、「何が何とどう繋がっているか」を丸ごと構造化してくれる。

公式には「Building nervous system for agent context（エージェントの文脈のための神経系を構築する）」と謳っている。
要するに、AIエージェントが「この関数はあの機能と繋がっている」と把握できるように、コード全体の関係性を事前に教えておく仕組みだ。

実際の作業の流れ

ここからは、自分のプロジェクトで実際にやった作業を見せていく。

既存リポジトリ
     │
     ▼
┌─────────────────────────────┐
│ Step 1: GitNexusで現状把握   │  ← コードから機能構造を自動抽出
└──────────────┬──────────────┘
               ▼
┌─────────────────────────────┐
│ Step 2: OpenSpecで仕様を記述 │  ← 抽出した構造をもとにspecを書く
└──────────────┬──────────────┘
               ▼
    AI駆動開発のレールに乗った状態

Step 1: GitNexusで現状を把握する

まずGitNexusをインストールして、リポジトリのルートで解析を実行する。

npm install -g gitnexus
cd /path/to/your-repo
npx gitnexus analyze

コマンドを実行すると、ナレッジグラフ用のインデックスが作成される。

% npx gitnexus analyze

  GitNexus Analyzer

  ████████████████████████████████████████ 100% | Done

  Repository indexed successfully (2.3s)

  478 nodes | 610 edges | 9 clusters | 10 flows
  /path/ai-manager

インデックスが作成されたら、下記のコマンドで GitNexus のローカルサーバーを起動できる。

npx gitnexus serve

その後、https://gitnexus.vercel.app/ を開くと、インデックスが存在するリポジトリの中身をUI上で確認できる。

実際に開くと、どのエンドポイントがどこまで影響範囲を持つのか視覚的に確認できるし、クエリを打つこともできる。

ただ、この画面は基本使わない

GitNexus は MCP を提供しているので、OpenSpec のコマンドと組み合わせて、コーディングエージェント経由で使うのがメインになる。

Claude Code から使う場合は、下記のコマンドを利用すれば簡単にMCPサーバーとして追加できる。

# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp

# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp

または .mcp.json に直接書いてもいい。

.mcp.json

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

設定できたら、Claude Code上で /opsx:explore を実行する。

/opsx:explore 機能ごと、調査してください、調査時にGitNexus mcp使ってください

GitNexusのMCPが入っている状態だと、エージェントがGrep/Globの代わりにGitNexusのツールを使い始める。

❯ /opsx:explore 機能ごと、調査してください、調査時にGitNexus mcp使ってください  
                                                                              
⏺ 機能ごとの調査ですね。まずはGitNexusでコードベースの全体像を把握し、そこから各
  機能を掘り下げていきます。                                                    
                                                                                
⏺ まずGitNexusのリソースからコードベース全体像と機能クラスター、実行フローの一覧
  を取得します。                                                                
                                                                                
⏺ readMcpResource(Read resource "gitnexus://repo/ai-manager/context" from server
                  "gitnexus")                                                   
  ⎿  {                                                                          
       "contents": [                                                            
         {                                                                      
     … +13 lines (ctrl+o to expand)

調査完了したら、下記のような機能マップが表示される。（抜粋）

⏺ 全体像が把握できました。以下にこのプロジェクト(ai-manager)の機能マップをまとめます。

  ---
  ai-manager 機能マップ

  ┌─────────────────────────────────────────────────────────────────────┐
  │                        ai-manager 全体像                            │
  │                  (AWS Amplify + React フロントエンド)                 │
  ├─────────────────────────────────────────────────────────────────────┤
  │                                                                     │
  │  ┌─── Frontend (React) ──────────────────────────────────────────┐  │
  │  │                                                               │  │
  │  │  ┌──────────┐   ┌──────────────────┐   ┌──────────────────┐  │  │
  │  │  │  App.tsx  │──▶│  parseReview.ts  │   │ReferenceSidebar  │  │  │
  │  │  │ (メイン)  │   │ (レビュー解析)    │   │ (参照データUI)    │  │  │
  │  │  └──────────┘   └──────────────────┘   └──────┬───────────┘  │  │
  │  │       │                                        │              │  │
  │  │       │          ┌──────────────────┐          │              │  │
  │  │       │          │  documentsApi.ts │◀─────────┘              │  │
  │  │       │          │ (ドキュメントAPI) │                         │  │

実際どんな検索が行われたに興味がある方はこちらを開いてみてね

調査順に見ていこう。

モジュール（クラスタ）

まず、関連するコードが機能単位で自動グルーピングされる。

modules:
  - name: "Ui"           # 12 symbols, cohesion: 100%
  - name: "Cluster_0"    # 8 symbols (App + parseReview)
  - name: "Documents"    # 7 symbols, cohesion: 95%
  - name: "Components"   # 6 symbols (ReferenceSidebar + API)
  - name: "Pptx-parse"   # 6 symbols, cohesion: 100%

100ファイルのリポジトリが「5つの機能の集まり」として整理された。各モジュールには cohesion（凝集度）というスコアがつく。値が高いほど、そのモジュール内のコードが密に連携していることを示す。Grepで1ファイルずつ探さなくても、機能の境界線が一目で分かる。

次に、エントリーポイントから末端までの呼び出しチェーンが自動でトレースされる。

processes:
  - "App → ParseCategory" (5 steps, intra_community)
  - "ReferenceSidebar → Sleep" (4 steps, cross_community)
  - "Handler → ExtractTextNodes" (4 steps, intra_community)
  # ...他7フロー

intra_community はモジュール内で完結するフロー、 cross_community はモジュールをまたぐフローだ。フロントエンドからバックエンドに跨がる処理も、1つのフローとして追える。

呼び出しチェーン

さらに、特定のフローを詳細にトレースすると、「どのファイルの、どの関数が、どの順で呼ばれるか」がステップごとに出てくる。

name: "App → ParseCategory"
trace:
  1: App (src/App.tsx)
  2: parseReviewText (src/lib/parseReview.ts)
  3: flushSlide (src/lib/parseReview.ts)
  4: parseSlideSection (src/lib/parseReview.ts)
  5: parseCategory (src/lib/parseReview.ts)

コードを1行も読まずに、「App.tsxから parseReviewText が呼ばれ、その中でスライドごとにカテゴリ分類が行われている」ことが分かる。Grepで5回検索して辿る情報が、1回のクエリで出てくる。

Step 2: OpenSpecで仕様を記述する

あとはこれだけです、openspecで利用できるナレッジが自動作成される。

/opsx:explore GitNexusの調査結果を元に、機能単位にspecsにまとめてください

GitNexus Module	OpenSpec Spec
Pptx-parse	`specs/pptx-parse/spec.md`
Documents	`specs/markdown-upload/spec.md`
Components（Sidebar）	`specs/reference-sidebar/spec.md`

実行フローのトレースを見ながら、要件とシナリオを書いていく。

例えば Handler → ExtractTextNodes の4ステップトレースからは、こういうspecが書ける。

openspec/specs/pptx-parse/spec.md

### Requirement: スライドテキスト抽出
システムは PPTX ファイル内の各スライドから、
タイトル・本文テキストを抽出しなければならない（MUST）。

#### Scenario: 複数スライドのテキスト抽出
- **WHEN** 5枚のスライドを含む PPTX ファイルが送信される
- **THEN** スライド番号順に5つのスライドデータを返す

GitNexusとOpenSpecの役割分担

ここまでの2ステップを振り返ると、GitNexusとOpenSpecの役割がはっきりする。

GitNexusが出すのはコードの構造情報である。モジュール分類、呼び出しチェーン。今コードがどうなっているかは分かるが、仕様は出てこない。

OpenSpecが担うのは、その構造情報を仕様として定着させること。GitNexusで抽出した機能構造をOpenSpecのspecファイルに落とし込めば、コーディングエージェントが次の開発で参照できるナレッジになる。

GitNexusが地図を描く役で、OpenSpecが地図を保存して次に使えるようにする役だ。

レールに乗せた後の運用

レールに乗せたら終わりではない。開発が進むとコードが先に変わり、specとの間にズレが生まれる。このズレを放置すると、AIは自信満々に間違ったコードを書く。地図が古い状態でナビに従うようなものだ。

正直な評価

正直に書くと、specの差分特定はコードの精読がないと無理だった。GitNexusだけで完結するわけではない。

GitNexusが効いたのは「入口」と「分割判断」のフェーズだ。5つのモジュールと10の実行フローが出てきた時点で、100ファイルのリポジトリの全体像が頭に入った。specをどう分割するかの判断材料として、モジュール分類と実行フローの一覧がそのまま使えたのは大きい。この構造化された出力がなければ、分割の粒度で迷っていたと思う。

今回のリポジトリは100ファイル規模なので、Grep + Read の直球アプローチでも全体像の把握自体はできたかもしれない。ただ、「モジュールの境界」と「実行フローの全体像」を最初に構造として提示してくれるかどうかで、その後の作業効率が変わる。GitNexusが本領を発揮するのは数百ファイル以上の規模感か、初見のリポジトリだろう

ツールの効果は「使えば必ず速くなる」ではなく「規模と複雑さに応じて効果が増す」と考えたほうが正しい。小さなリポジトリでも、構造を言語化する訓練としては十分価値がある。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up