前言

大家好！
本次 Advent Calendar 的第 16 天，我將以「【複製貼上可行】嘗試創建一份 GitHub Copilot 的"DeepWiki化"文檔指示書」為主題來介紹！

最近在工作中有機會接觸人工智慧，因此這次將針對 AI 進行一些說明。
不過，這篇文章的重點並非在於代碼生成，而是文檔生成。
之所以專注於文檔生成，是因為我曾聽聞到 Devin 的其中一個功能「DeepWiki」。
這個 DeepWiki 是一個能夠從源代碼生成詳細文檔的功能。
當我聽到 DeepWiki 時，我感到這是一個非常好的功能，想要試用，但當我實際希望使用時，卻面臨著在公司內部私有環境中無法輕易使用的問題。

於是我想，「如果我改進提示的寫法，是否能在我一直使用的 GitHub Copilot 上實現類似的功能呢？」

因此，我試著創建了一個「文檔指示書」，以模仿 DeepWiki 的功能。
在這篇文章中，我想介紹我創建的指示書的內容、特徵，及其實際運行的結果！

本文實現的目標

首先，再次強調我想通過這篇文章實現的目標是，只需將「文檔指示書」傳遞給 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 工作區中指示「根據文檔指示書.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 創建的任務列表，逐頁生成文檔。

4.1 輸出格式及文件配置

• 格式: Markdown 格式
• 文件結構: 按章節分別創建個別文件
• 配置位置: wiki/ 目錄（若不存在則自動創建）
• 文件命名規則:
  • 將文檔結構中每一部分標題轉換為文件名
  • 空格替換為連字號（-）
  • 保留數字前綴
  • 例: 「1. 概要」→ wiki/01-概要.md
  • 例: 「2. 快速入門」→ wiki/02-快速入門.md

4.2 創建目次文件

• 文件名: wiki/00-目次.md
• 內容:
  • 整個項目的目次
  • 各頁面的鏈接列表
  • 簡單的導航指南

目次文件範例:

# 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. 步驟的明確化與層次化

首先在「概要」中傳達整體情況，然後在「步驟詳細」中指示具體步驟，使AI沿著「首先掌握全局，然後實施細節」的思維過程進行操作。如此可以避免中途迷失方向。

2. 全面的信息收集 (步驟1)

不僅是源代碼，還將構建設定（如 package.json）以及基礎設施配置（如 Dockerfile）、DB 架構通通納入，從而使文檔生成對各種項目都能成功。

3. 靈活的文檔結構（步驟2）

通過 外部文件定義結構 的方式 (生成指示書/文檔結構.md)，使得每個項目都能進行適當的自定義。
此外，當該檔案不存在時，AI 會分析出最適合的結構，以此來生成文檔，兼顧了方便性。

4. 自我任務管理帶來的穩定性（步驟3）

不會一次性將整個文檔全都創建，而是由 AI 自行進行「TODO 列表創建 → 逐頁生成 → 狀態更新」的任務管理。
這樣的設計能防止 AI 在冗長的文檔生成過程中中斷處理或跳過任務。

5. 輸出規則保障品質（步驟4）

對於圖解、源代碼引用格式等輸出進行具體化規範。
這樣可以確保 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 工作區中指示「根據文檔指示書.md 創建文檔。」即可開始生成文檔。

此外，在此過程中，我指定了「Claude Sonnet 4.5」。

文檔生成結果

接下來，讓我們實際查閱生成的文檔結果。

首先，通過上述步驟和指示，確認 AI 自動分割任務並為每個任務生成文檔。

▼ 生成狀況

▼ 生成的 wiki/ 目錄的文件列表

如上所示，考慮了提供的 文檔結構.md 後進行的任務分割，所有設計書都已生成完成。

接下來，我會介紹具體生成的設計書內容。

此指示書中的內容提到可進行直觀文檔生成，但實際執行的效果如何呢？

結論是，生成的精度相當不錯！

接下來，讓我們看看實際生成的系統整體構成圖和處理流程圖。

▼ 生成文檔的摘錄（系統整體構成圖）
<iframe id="qiita-embed-content__9708a68756f0a155960eaeb191664386"></iframe>

▼ 生成文檔的摘錄（Todo 新規創建流程）
<iframe id="qiita-embed-content__0338b2586ad75eb0a26b5c37581eba96"></iframe>

此外，不僅是圖表，像是端點列表等表格也都準確生成。

▼ 生成文檔的摘錄（端點列表）

顯然可以看出，AI 能夠從源代碼中生成視覺上易於理解的設計書，通過圖及表等方式呈現。

此外，整份文檔也用表情符號等方式生成了清晰易懂的文本。
由於生成的內容龐大，不便於全文展示，我將以下提供 01-概要.md 的部分摘錄。

<details><summary>生成文檔的摘錄（01-概要.md）</summary>

# 📖 概要

## 項目的目的

這個 Todo List 應用程式是一個使用 Spring Boot 框架和 JSP（JavaServer Pages）所開發的簡單且實用的任務管理系統。它旨在學習目的，提供實踐以下技術要素的機會：
- **使用 Spring Boot 進行現代後端開發**
- **實現層式架構**
- **使用 JPA 進行資料庫操作**
- **使用 JSP 進行伺服器端渲染**
---
## 主要功能

這個應用程式提供了任務管理所需的基本功能：

| 功能                     | 說明                             |
|------------------------|--------------------------------|
| ✅ **顯示 Todo 清單**       | 列出所有創建的 Todo                |
| ➕ **新增 Todo**          | 指定標題、描述、優先級來創建 Todo  |
| ✏️ **編輯 Todo**          | 更新現有 Todo 的內容               |
| 🗑️ **刪除 Todo**          | 刪除不需要的 Todo                  |
| ✔️ **切換完成/未完成**     | 一鍵切換 Todo 的完成狀態            |
| 🎯 **設置優先級**         | 設定優先級為低、中、高              |
| 📅 **時間戳管理**         | 自動記錄創建和更新時間              |
---
## 技術棧

### 後端

| 技術                     | 版本    | 角色                     |
|------------------------|--------|------------------------|
| **Java**               | 21     | 程式語言                  |
| **Spring Boot**        | 3.2.0  | 應用程式框架              |
| **Spring Data JPA**    | 3.2.0  | 資料存取層                |
| **Hibernate**          | 6.x    | ORM (物件關聯對映)       |
| **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 資料庫: 無需設置的內存資料庫
• 帶有初始數據: 透過 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（最新版）

  下一步

了解完項目的概要後，請進入下一節：

• 🚀 快速入門 - 實際運行應用程式
• 🏗️ 架構 - 了解系統構成的詳細資訊

• 📁 倉庫結構 - 理解項目的結構

  相關資源:

• 項目根目錄: ../README.md
• 構建設定: ../build.gradle
• 應用程式設定: ../src/main/resources/application.properties

  
  </details>

當前的挑戰與限制

迄今為止，我已經介紹了 GitHub Copilot 進行文檔自動生成的潛力。
然而，這種方法目前確實還存在一些挑戰與限制。

• 精度的限制：儘管在此次實踐中生成的質量相當不錯，但偶爾仍會包含一些細小的錯誤或事實上的誤認。
• 規模的限制：當試圖解析大型項目時，模型可能超出一次能處理的信息量，進而降低準確性或導致處理失敗。
• 理解力的限制：AI 雖然可以解釋代碼的結構及功能，但對於「為什麼會這樣設計」的商業背景或取捨判斷卻無法理解。

因此，我認為這種方法應被視為「能將初稿創作的時間減少 90% 的工具」，而不是完全依賴它，最終的修訂工作仍需由人來完成。

結語

這次的設計

原文出處：https://qiita.com/a32-suzuki/items/c3540da3e009dab1bf97