はじめに
みなさん、こんにちは！
アドベントカレンダーの16日目は「【コピペOK】GitHub Copilotを"DeepWiki化"するドキュメント指示書を作成してみた」という内容でお届けします！
最近業務でもAIに触らせていただく機会があったので今回はAIについて記載していきます。
ただ、この記事ではコード生成ではなく、ドキュメント生成に着目してみました。
なぜドキュメント生成に着目したかというと、Devinの機能の一つである「DeepWiki」のお話を聞く機会があったからです。
このDeepWikiとは、ソースコードから詳細なドキュメントを作成する機能です。
DeepWikiの話を聞いたときに、このようなすごい機能があるんだ、使ってみたいと思ったのですが、いざ使ってみようとすると社内のプライベート環境では簡単に使えないという問題がありました。
そこで、「プロンプトの書き方を工夫すればいつも使ってるGitHub Copilotで似たようなことができるんじゃないの？」と思いました！
というわけで、DeepWikiの機能をCopilotで模倣する「ドキュメント指示書」を自作してみました。
この記事では作成した指示書の中身や特徴、実際に動作してみた結果をご紹介したいと思います！
この記事で実現すること
まず、改めましてこの記事で実現したいことは、「ドキュメント指示書」をGitHub Copilotに渡すだけで、プロジェクト全体を解析させ、Markdown形式の詳細なドキュメントを自動生成させるということです！
また、この「ドキュメント指示書」は、単にソースコードを要約するだけではなく、以下の特徴を持たせました。
網羅的なプロジェクト解析
ソースコードだけでなくpackage.jsonやDockerfile、.github/workflowsといったビルドツールやインフラ構成ファイルまで自動でスキャンし、プロジェクトの全体像を正確に把握する。
柔軟なドキュメント構成
プロジェクト内にドキュメント構成.mdというファイルを用意することで、生成されるドキュメントの章立てや順序を柔軟に変更することが可能。
もしファイルがなければ、AIがソースコードを分析し、与えたコードに適した構成でドキュメントを生成。
図解による直感的なドキュメント生成
単なるテキストではなく、Mermaidで図も自動生成。
アーキテクチャ図やシーケンス図など、テキストだけでは伝わりにくい情報を視覚的に表現。
このような特徴を持つ指示書を活用することで、これまでコード補完ツールとして使っていたGitHub CopilotでDeepWikiのようなドキュメント作成体験ができるはずです！
そもそもDeepWikiとは
ここまでDeepWikiという単語を何度も出してきたのですが、「そもそもDeepWikiって何？」という方のために簡単に説明します。
冒頭でも述べましたが、DeepWikiとは今話題のAIエージェント「Devin」に搭載されている機能の一つです。
その役割は、ソースコードリポジトリを自律的に解析し、プロジェクトの技術ドキュメントを全自動で生成することです。
また、DeepWikiの主な機能としては以下のようなものがあげられます。
| 主な機能 | 説明 |
|---|---|
| アーキテクチャの解析 | プロジェクトのフレームワークやライブラリを特定し、システム全体の構造を図や文章で解説 |
| 主要機能の特定 | コードを読み解き、アプリの核心的な機能を特定 |
| 依存関係のマッピング | ファイルやコンポーネント間の複雑な依存関係を可視化 |
| 正確なコード参照 | 「ファイルパス＋行番号」付きの正確なコード抜粋が埋め込まれ、クリックで該当コードにジャンプ可能 |
このような機能から、数日かけて行っていたプロジェクト全体像の把握をDeepWikiは数分で完了させることができます。
ただし、前述した通りDeepWikiはすぐに社内のプライベートな環境で使えるものではありませんでした。
なので、現在使用しているGitHub Copilotで同じようなプロジェクト情報のドキュメント化の実現にチャレンジしました！
【全文公開】DeepWiki化を実現する「ドキュメント指示書」
お待たせしました！
今回作成した「ドキュメント指示書」の全文を記載します。
このドキュメント指示書を作成したいプロジェクト内に追加し、Copilot Workspaceに「ドキュメント指示書.mdからドキュメントを作成して。」と指示を与えるだけで自律的なドキュメント生成が始まります。
ドキュメント指示書
# ドキュメント指示書
## 1. 概要
ワークスペース内のすべてのファイルを分析し、包括的なプロジェクトドキュメントを生成する。
ドキュメントは以下の手順で実行する：
1. 必要情報の読み込み
2. ドキュメント構成の確認
3. タスク分割
4. ドキュメントの生成
下記でそれぞれの手順の詳細を説明する。
---
## 2. 手順詳細
### 手順1: 必要情報の読み込み
以下の情報を自動収集する：
#### 1.1 プロジェクト基本情報
- プロジェクト名、説明（README、ビルドファイルから抽出）
- 使用言語（ファイル拡張子から判定）
- ビルドツール（build.gradle, package.json, pom.xml等）
#### 1.2 ソースコード
- **メインコード**: `src/`, `lib/`, `app/`, `pkg/` 等の標準ディレクトリ
- **設定ファイル**: application.properties, .env, config.yaml等
- **ビュー/テンプレート**: *.jsp, *.html, *.vue, *.jsx等
- **テストコード**: `test/`, `tests/`, `spec/` ディレクトリ
#### 1.3 インフラ・デプロイ
- Docker: Dockerfile, docker-compose.yml
- CI/CD: .github/workflows/, .gitlab-ci.yml等
- クラウド設定: vercel.json, netlify.toml等
#### 1.4 データ構造
- ORM定義（Entity, Model等）
- マイグレーション、スキーマファイル
- 初期データ（seeds, data.sql等）
#### 1.5 既存ドキュメント
- README.md, CONTRIBUTING.md
- docs/, wiki/ ディレクトリ
- API仕様（openapi.yaml, swagger.json）
#### 1.6 自動除外
以下は読み込みをスキップ：
- `node_modules/`, `vendor/`, `.venv/`, `build/`, `dist/`, `target/`
- `.git/`, バイナリファイル、ログファイル
### 手順2: ドキュメント構成の確認
#### 2.1 構成ファイルの確認
プロジェクトルート配下の`生成指示書/ドキュメント構成.md`の存在を確認：
**存在する場合：**
- ファイル内容を完全に読み込み
- 各セクションの順序・内容を厳密に守る
- セクション番号の重複や誤りは自動修正する
**存在しない場合：**
- AIが自動的にコード構造を分析し、ドキュメント構造を決定する
- シンボル・ファイル類似性・トピックで論理的にグループ化する
#### 2.2 優先度の考慮
構成ファイルに`priority`フィールドがある場合、その順序で処理する。
---
### 手順3: タスク分割
ドキュメント構成に基づいて、以下の手順でタスク管理を実施：
#### 3.1 タスクリストの作成
- `manage_todo_list` ツールを使用
- ドキュメント構成の各ページを個別のタスクとして登録
- タスクタイトル例: "00-目次.md を作成"、"01-概要.md を作成"
- 全タスクのステータスを `not-started` で初期化
**タスクリスト例:**
```
1. [not-started] 00-目次.md を作成
2. [not-started] 01-概要.md を作成
3. [not-started] 02-クイックスタート.md を作成
...
```
#### 3.2 進捗管理のルール
- 作成開始前に該当タスクを `in-progress` に更新
- ページ作成完了後、即座に該当タスクを `completed` に更新
- 次のページに進む前に、必ず完了状態を記録
- ユーザーが現在の進捗状況を把握できるようにする
---
### 手順4: ドキュメントの生成
3で作成したタスクリストに従い、1ページずつドキュメントを生成する。
#### 4.1 出力形式とファイル配置
- **フォーマット**: Markdown形式
- **ファイル構成**: セクションごとに個別ファイルとして作成
- **配置場所**: `wiki/` ディレクトリ（存在しない場合は自動作成）
- **ファイル命名規則**:
- ドキュメント構成の各セクションタイトルをファイル名に変換
- スペースはハイフン（-）に置換
- 数字接頭辞を保持
- 例: 「1. 概要」→ `wiki/01-概要.md`
- 例: 「2. クイックスタート」→ `wiki/02-クイックスタート.md`
#### 4.2 目次ファイルの作成
- **ファイル名**: `wiki/00-目次.md`
- **内容**:
- プロジェクト全体の目次
- 各ページへのリンク一覧
- 簡単なナビゲーションガイド
**目次ファイルの例:**
```markdown
# Todo List Wiki
## 📚 目次
- [📖 1. 概要](./01-概要.md)
- [🚀 2. クイックスタート](./02-クイックスタート.md)
- [🏗️ 3. アーキテクチャ](./03-アーキテクチャ.md)
- [📁 4. リポジトリ構造](./04-リポジトリ構造.md)
- [🗄️ 5. データモデル](./05-データモデル.md)
...
```
#### 4.3 作成の流れ
**各ページ作成の流れ:**
1. `manage_todo_list` でタスクを `in-progress` に更新
2. ページを作成
3. `manage_todo_list` でタスクを `completed` に更新
4. 次のタスクに進む
**完全実行:** 全タスク完了まで中断せず継続。1ページ作成 → `completed` 更新 → 次ページ作成を繰り返し、全ページを完遂する。
#### 4.4 出力ルール（厳守）
1. **見出しと絵文字**
- 各ファイルの冒頭（H1）に適切な絵文字を配置
- サブセクションは H2, H3, H4 で階層化
2. **ファイル間リンク**
- 他のセクションへの参照は相対パスで記述
- 例: `詳細は [アーキテクチャ](./03-アーキテクチャ.md) を参照`
3. **図表の記述**
- Mermaid図は必ず ` ```mermaid ``` ` で囲む
- 各ページに適切な図を配置
4. **コードスニペット**
- 言語指定付きコードブロック
- 重要行にコメントを追加
- ファイルパスと行番号を明記
5. **ソースコード参照**
- プロジェクトルートからの相対パスで記述
- 行番号範囲を含める
- 例: `(../src/main/java/jp/co/app/todo/model/Todo.java:15-30)`
6. **一貫性**
- 全ファイルで記述スタイルを統一
- 用語の使い方を統一
#### 4.5 生成されるファイル構成例
```
wiki/
├── README.md (または 00-目次.md) # 目次・ナビゲーション
├── 01-概要.md # プロジェクト概要
├── 02-クイックスタート.md # セットアップ手順
├── 03-アーキテクチャ.md # システム構成
├── 04-リポジトリ構造.md # ディレクトリ構造
├── 05-データモデル.md # DB設計
├── 06-コアコンポーネント.md # 主要クラス解説
├── 07-APIドキュメント.md # エンドポイント仕様
├── 08-テスト戦略.md # テスト構成
├── 09-デプロイメント.md # ビルド・デプロイ手順
├── 10-コントリビューションガイド.md # 開発ガイド
└── 11-まとめ.md # 総括
```
各ページで関連するソースコードファイルへのリンクを明記する。
このドキュメント指示書を生成したいプロジェクトの任意の場所（./生成指示書など）に追加し、指示を与えると./Wikiに詳細な設計書が生成されます。
ドキュメント指示書のポイント
上記で紹介したドキュメント指示書は以下のような特徴を持っています。
これらの特徴も軽くご紹介します。
1. 手順の明確化と階層化
最初に「概要」で全体像を伝え、次に「手順詳細」と具体的なステップを指示することで「まず全体を把握し、次に各論を実行する」という人間と同じ思考プロセスを辿らせています。このようにすることで、途中で迷子になることを防いでいます。
2. 網羅的な情報収集 (手順1)
ソースコードだけでなく、ビルド設定(package.json等)やインフラ構成(Dockerfile等)、DBスキーマまで読み込ませることで、様々なプロジェクトに対してドキュメント生成を可能にしています。
3. 柔軟なドキュメント構成（手順2）
生成指示書/ドキュメント構成.mdという外部ファイルで構成を定義できるようにすることで、プロジェクトごとに適したカスタマイズが可能になります。
また、ファイルがなければAIが最適な構成を分析し、与えたソースコードに適した構成でドキュメントを生成してくれる機能も備えることで、手軽さも両立しています。
4. 自己タスク管理による安定性（手順3）
ドキュメント全体を一度に作らせるのではなく、「TODOリスト作成 → 1ページずつ生成 → ステータス更新」というタスク管理をAI自身に行わせています。
これにより、長大なドキュメント生成プロセスでもAIが途中で処理を中断したり、タスクを飛ばしたりすることを防いでいます。
5. 出力ルールによる品質担保（手順4）
Mermaidによる図解、ソースコード引用の形式など、アウトプットに関するルールを具体化しています。
これにより、AIの出力のブレを抑え、常に一定の品質を保ったドキュメントが得られます。
サンプルプロジェクトによる実践
実際に前述で述べたような設計書が生成されているか、簡単なサンプルプロジェクトで実践してみました。
今回は、Java(Spring Boot) + Gradleで書かれたシンプルなTodoアプリのプロジェクトを用いて、この指示書を実行しました。
ドキュメント生成方法
./生成指示書というディレクトリに、上記で示したドキュメント指示書.mdを追加しました。
また、今回は同じディレクトリ上にドキュメント構成.mdを作成し、ドキュメントの構成を明示的に指定しました。
作成したドキュメント構成は以下に示します。
ドキュメント構成は、各セッションが設計書の１ページに対応するよう設計されています。
ドキュメント構成
# ドキュメント構成
生成するドキュメントは以下の構成にしてください。
## 1. 概要
- プロジェクトの目的と概要
- 主要機能の一覧
- 使用されている技術スタック（表形式）
- アーキテクチャパターン
## 2. クイックスタート
- 前提条件（Java 21、Gradleなど）
- ローカル環境でのセットアップ手順
- アプリケーション起動方法
- 動作確認方法（ブラウザアクセス、H2コンソールなど）
## 3. アーキテクチャ
- システム全体の構成図（Mermaid形式）
- レイヤードアーキテクチャの説明
- コンポーネント間の関係性図
- 主要な処理フロー図
## 4. リポジトリ構造
- ディレクトリ構成の詳細
- 各ディレクトリの役割と責務
- 主要ファイルの配置と目的
- 設定ファイルの説明
## 5. データモデル
- エンティティ一覧と説明
- テーブル構造詳細
- ER図（Mermaid形式）
- リレーションシップ
## 6. コアコンポーネント
- Entity層の詳細
- Repository層の実装
- Service層のビジネスロジック
- Controller層のリクエスト処理
- View層（JSP）の構造
## 7. APIドキュメント
- エンドポイント一覧表
- 各エンドポイントの詳細仕様
- リクエスト/レスポンス例
- 主要メソッドのAPIリファレンス
## 8. テスト戦略
- テストの構成と方針
- テストカバレッジ
- 単体テスト例
- 統合テスト例
## 9. デプロイメント
- ビルド手順（Gradle）
- 実行/起動方法
- 環境設定の詳細（application.properties）
- 依存関係の管理
- トラブルシューティング
## 10. コントリビューションガイド（オプション）
- 開発環境のセットアップ
- コーディング規約
- ブランチ戦略
- プルリクエストのガイドライン
## 11. まとめ
- プロジェクトの特徴
- 主要な設計判断とその理由
- 学習ポイント
- 今後の拡張性や改善点
指示内容通り設計書ができているか確認するために今回の実践では詳細にドキュメント構成を作成していますが、ドキュメント構成ファイルはなくても設計書の生成は可能です。
これらのファイルを追加後、Copilot Workspaceに「ドキュメント指示書.mdからドキュメントを作成して。」と指示を与えることで、ドキュメント生成が開始されます。
また、このときAIは「Claude Sonnet 4.5」を指定しました。
ドキュメント生成結果
では実際に、作成されたドキュメント生成結果をご紹介します。
まずは、上記手順で指示を与えることで、AIが自動的にタスク分割し、タスクごとにドキュメント生成していることを確認しました。
▼ 生成状況
▼ 生成されたwiki/ディレクトリのファイル一覧
上記の通り、与えたドキュメント構成.mdを考慮したタスク分割が行われ、すべての設計書が生成されたことが分かります。
また、次は実際に生成した設計書の中身についてご紹介していきます。
今回紹介した指示書では、図を用いた直感的なドキュメント生成が可能と述べてましたが、実際にできているのかを確認しました。
結論から言うとなかなかの精度で生成してくれてました！
実際にどのような図が生成されているのか、以下に今回生成したシステム全体構成図と処理フロー図を示します。
▼ 生成ドキュメントの抜粋（システム全体の構成図）
▼ 生成ドキュメントの抜粋（Todo新規作成フロー）
また、図だけではなくエンドポイント一覧といった表なども正確に生成してくれていました。
▼ 生成ドキュメントの抜粋（エンドポイント一覧）
| メソッド | パス | 説明 | レスポンス |
|---|---|---|---|
| GET | / |
Todo一覧画面を表示 | HTML |
| POST | /todos |
新しいTodoを作成 | リダイレクト |
| POST | /todos/{id}/update |
Todoを更新 | リダイレクト |
| POST | /todos/{id}/toggle |
完了状態を切り替え | リダイレクト |
| POST | /todos/{id}/delete |
Todoを削除 | リダイレクト |
| GET | /api/todos/{id} |
Todo詳細を取得（JSON） | JSON |
このように、ソースコードから図や表などを用いて視覚的にもわかりやすい設計書を生成してくれたことが分かります。
また、ドキュメント全体としても絵文字などを用いてわかりやすい文章で生成されていました。
生成物を全文載せてしまうと分量が膨大になってしまうので、一部抜粋として01-概要.mdを折り込みで載せておきます。
生成ドキュメントの抜粋（01-概要.md）
# 📖 概要
## プロジェクトの目的
このTodo Listアプリケーションは、Spring BootフレームワークとJSP（JavaServer Pages）を使用した、シンプルで実用的なタスク管理システムです。学習目的で設計されており、以下の技術要素を実践的に学ぶことができます：
- **Spring Bootによるモダンなバックエンド開発**
- **レイヤードアーキテクチャの実装**
- **JPAを使用したデータベース操作**
- **JSPによるサーバーサイドレンダリング**
---
## 主要機能
このアプリケーションは、タスク管理に必要な基本的な機能を提供します：
| 機能 | 説明 |
|------|------|
| ✅ **Todo一覧表示** | 作成したすべてのTodoを一覧で表示 |
| ➕ **Todo新規追加** | タイトル、説明、優先度を指定してTodoを作成 |
| ✏️ **Todo編集** | 既存のTodoの内容を更新 |
| 🗑️ **Todo削除** | 不要なTodoを削除 |
| ✔️ **完了/未完了切り替え** | Todoの完了状態をワンクリックで切り替え |
| 🎯 **優先度設定** | 低・中・高の3段階で優先度を設定 |
| 📅 **タイムスタンプ管理** | 作成日時・更新日時を自動記録 |
---
## 技術スタック
### バックエンド
| 技術 | バージョン | 役割 |
|------|-----------|------|
| **Java** | 21 | プログラミング言語 |
| **Spring Boot** | 3.2.0 | アプリケーションフレームワーク |
| **Spring Data JPA** | 3.2.0 | データアクセス層 |
| **Hibernate** | 6.x | ORM (Object-Relational Mapping) |
| **H2 Database** | 最新 | インメモリデータベース（開発用） |
### フロントエンド
| 技術 | バージョン | 役割 |
|------|-----------|------|
| **JSP** | 3.1 | サーバーサイドテンプレート |
| **JSTL** | 3.0 | JSPタグライブラリ |
| **Bootstrap** | 5.3.0 | CSSフレームワーク |
| **Bootstrap Icons** | 1.11.0 | アイコンライブラリ |
### ビルド・開発ツール
| 技術 | バージョン | 役割 |
|------|-----------|------|
| **Gradle** | 8.x | ビルドツール |
| **Lombok** | 最新 | ボイラープレートコード削減 |
---
## アーキテクチャパターン
このアプリケーションは、**レイヤードアーキテクチャ**（階層化アーキテクチャ）を採用しています。
```mermaid
graph TB
subgraph "プレゼンテーション層"
View[View<br/>JSP]
Controller[Controller<br/>TodoController]
end
subgraph "ビジネスロジック層"
Service[Service<br/>TodoService]
end
subgraph "データアクセス層"
Repository[Repository<br/>TodoRepository]
Entity[Entity<br/>Todo]
end
subgraph "データ層"
Database[(H2 Database)]
end
View -->|リクエスト| Controller
Controller -->|応答| View
Controller -->|ビジネスロジック呼び出し| Service
Service -->|CRUD操作| Repository
Repository -->|JPA| Entity
Entity -->|SQL| Database
style View fill:#e1f5ff
style Controller fill:#fff4e1
style Service fill:#ffe1f5
style Repository fill:#e1ffe1
style Entity fill:#f0f0f0
style Database fill:#d0d0d0
```
### レイヤーの責務
1. **プレゼンテーション層（View + Controller）**
- HTTPリクエストの受信と処理
- ユーザーインターフェースの描画
- 入力バリデーション
2. **ビジネスロジック層（Service）**
- ビジネスルールの実装
- トランザクション管理
- データの変換と処理
3. **データアクセス層（Repository + Entity）**
- データベースとのやりとり
- エンティティとテーブルのマッピング
- クエリの定義
4. **データ層（Database）**
- データの永続化
- データの整合性保証
---
## プロジェクトの特徴
### 🎓 学習しやすい設計
- **シンプルな構造**: 必要最小限の機能に絞り、理解しやすい構成
- **明確な責任分離**: 各レイヤーの役割が明確
- **実用的なコード**: 本番環境でも通用するベストプラクティス
### 🚀 すぐに動かせる
- **H2データベース**: セットアップ不要のインメモリDB
- **初期データ付き**: `data.sql`でサンプルデータを自動投入
- **組み込みTomcat**: 外部サーバー不要で即起動
### 🔧 拡張性を考慮
- **インターフェース駆動**: Repository層でSpring Data JPAを活用
- **設定の外部化**: `application.properties`で容易に設定変更可能
- **RESTful設計**: API化への拡張が容易
---
## 動作環境
### 必須要件
- **Java**: 21以上
- **Gradle**: 8.x以上（Gradleラッパーを使用する場合は不要）
### 推奨環境
- **OS**: Windows 10/11, macOS, Linux
- **IDE**: IntelliJ IDEA, Eclipse, VS Code
- **ブラウザ**: Chrome, Firefox, Edge（最新版）
---
## 次のステップ
プロジェクトの概要を理解したら、次のセクションに進みましょう：
- **[🚀 クイックスタート](./02-クイックスタート.md)** - 実際にアプリケーションを動かしてみる
- **[🏗️ アーキテクチャ](./03-アーキテクチャ.md)** - システム構成の詳細を学ぶ
- **[📁 リポジトリ構造](./04-リポジトリ構造.md)** - プロジェクトの構成を理解する
---
**関連リソース:**
- プロジェクトルート: `../README.md`
- ビルド設定: `../build.gradle`
- アプリケーション設定: `../src/main/resources/application.properties`
現状の課題と限界
ここまで、GitHub Copilotによるドキュメント自動生成の可能性をご紹介させていただきました。
しかし、このアプローチも現状ではいくつかの課題や限界点があります。
- 精度の限界：今回の実践ではなかなかのレベルで生成してますが、時折細かな間違いや事実誤認が含まれることがあります。
- 規模の限界：大規模なプロジェクトを丸ごと解析させようとすると、モデルが一度に処理できる情報量を超えてしまい、精度が低下したり処理が失敗したりする可能性があります。
- 読解力の限界：AIはコードの構造や機能を説明できますが、「なぜこの設計になったのか」というビジネス上の背景やトレードオフの判断までは理解できないです。
このように、この手法はあくまで「ドラフト作成時間を9割削減してくれるツール」と捉え、すべて鵜吞みにするのではなく、最後の仕上げは人の手で行う、という付き合い方が現実的だと思いました。
おわりに
今回思い付きでやった設計書自動生成ですが、想像以上にきちんと設計書が生成されており、相変わらず最近のAIはすごいなと驚愕しました。
AIが賢いのはもちろんなのですが、「指示の出し方（プロンプト）」を工夫することが重要だと改めて実感しました。
いつもは適当にプロンプトを与えがちなので、これからはプロンプトを与える前にこのプロントは曖昧じゃないかを考えるようにしたいなと思いました。
また、今回作成したドキュメント指示書ですが完全自動化などもやってみたいと思いました。
たとえば、CIツールと連携させ、mainブランチへのPushをトリガーに設計書を自動更新するワークフローなど構築できたらさらに使い勝手がよくなるなと思いました。
長くなってしまいましたが、最後まで読んでいただきありがとうございました！