生成AIサービス+MarkItDown で新規システムのドキュメントを作成/運用する

# やりたいこと

- 新規システム開発における要件定義とシステム設計を整理し、ドキュメントを作成する
- また、ドキュメントは、Markdown で運用する

# 使用するツール
- [ChatGPT 4o](https://chatgpt.com/)
- [GEAR.indigo](https://gearindigo.app/)
- [MarkItDown](https://github.com/microsoft/markitdown/)
- [GitHub Copilot](https://docs.github.com/ja/copilot)

## ChatGPT 4o
主に GEAR.indigo に読み込ませるプロンプトの作成に使用します。
GEAR.indigo は、プロンプトの実行回数に制限があるため、ある程度整理したプロンプトを実行するようにします。

## GEAR.indigo
GEAR.indigo は、システムの提案内容を入力することで要件定義から設計までのドキュメントを生成することができます。また、ドキュメントをもとにソースコードを生成することも可能です。
今回は、要件定義とシステム設計のドキュメント作成に使用します。

**選定理由**
GEAR.indigo は、日本の企業が提供しているサービスです。
公式ページに「ステップバイステップのドキュメント生成」とあるように、1度の生成で完結するのではなく、生成したものをもとにチームで議論を深め、部分的な再生成や人による修正なども加えドキュメントをブラッシュアップしていくことを前提としているように感じました。

これは、日本でよくみられるウォーターフォール開発の文化も考慮されていると思います。
基本的にウォーターフォールは、要件定義→設計→実装→...と各フェーズを順番に進めていくため、GEAR.indigo のように生成したものをもとに議論し修正していくスタイルは実業務においても導入しやすいと感じました。

## MarkItDown
Microsoft が開発した Python ライブラリで、さまざまなファイル形式を Markdown に変換することができます。
GEAR.indigo で生成したドキュメントは、エクスポートした場合に JSON 形式でダウンロードされるため、MarkItDown を使用してMarkdown 形式に変換します。

## GitHub Copilot
GitHub Copilot は、コードの自動補完やコードの提案などをしてくれるAI開発支援ツールです。
この記事では記載しませんが、最終的に Markdown に変換したドキュメントの修正や更新において、より効率的な運用が期待できます。

# やってみる
実際にドキュメントを作成してみます。
今回は、資格勉強などで使用するWeb問題集を作ってみようと思います。
問題を解くサイトとそれを管理するシステムという、よくある構成となります。

## 要件定義

要件定義を作っていきます。
まずは、ChatGPT に実行するプロンプトを作成してもらいます。

![要件定義.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/7808dbf5-d25e-8efd-2c01-dbc9f6849ed8.png)

下記のような内容で生成されました。
```markdown
### プロジェクト概要
本プロジェクトは、資格取得を目指すユーザーが学習を効率化するためのWeb問題集システムを開発することを目的としています。ユーザーは問題を解いて結果を確認し、解説を学ぶことで知識を深め、学習履歴を基に次の学習計画を立てることができます。また、管理者は問題や解説の管理、ユーザーの学習状況の把握を行うことができます。

---

### 現行業務フロー
1. 資格取得を目指す学習者は、書籍やPDF形式の問題集を使用して問題を解く。
2. 学習者は自分で解答をチェックし、間違えた問題をノートにまとめる。
3. 学習の進捗は手動で管理（カレンダーやエクセルシートなどを利用）。
4. 管理者が問題集を作成・配布する際は、メールやクラウドストレージを使用。

---

### 業務要件一覧
1. ユーザーはWebアプリケーション上で問題を解答できる。
2. 解答後に正誤結果と解説を確認できる。
3. ユーザーの学習履歴を保存し、進捗状況を確認できる。
4. 管理者は問題や解説を追加・編集・削除できる。
5. ユーザーからの問い合わせに対応する仕組みがある。
6. システムの動作状況や使用状況を管理者が把握できる。

---

### システム化業務フロー
1. ユーザーがWebアプリケーションにログイン。
2. 問題一覧画面から学習する問題を選択。
3. ユーザーが問題を解答し、送信ボタンをクリック。
4. サーバーが解答を採点し、結果および解説を画面に表示。
5. 学習履歴が自動的に保存され、ユーザーは履歴画面で進捗を確認。
6. 管理者が管理画面にログインし、問題データベースを更新。
7. 管理者がシステム利用状況レポートを閲覧。

---

### 機能要件一覧
#### ユーザー向け
1. ユーザー登録機能（メールアドレスとパスワードによる認証）。
2. ログイン・ログアウト機能。
3. 問題解答機能。
4. 解答結果・解説表示機能。
5. 学習履歴の閲覧機能。
6. 学習目標設定機能（例：1週間の目標問題数設定）。

#### 管理者向け
1. 問題および解説の管理機能（追加、編集、削除）。
2. ユーザーの進捗状況の閲覧機能。
3. システム利用状況の統計情報表示機能。
4. 問い合わせ管理機能。

---

### 非機能要件一覧
1. **パフォーマンス要件**: サーバーは同時に500人以上のユーザーが利用しても快適に動作すること。
2. **可用性要件**: システム稼働率は99.9%以上を目指す。
3. **セキュリティ要件**:
   - ユーザーの個人情報を暗号化して保存。
   - OWASP Top 10の脆弱性に対応。
4. **スケーラビリティ要件**: 将来的なユーザー増加に対応可能な設計。
5. **保守性要件**: ソースコードはモジュール化し、拡張性を確保。
6. **ユーザビリティ要件**: モバイル、タブレット、デスクトップで快適に操作可能なレスポンシブデザイン。

---

これらを基に、効率的かつユーザーにとって有益なシステムを開発します。

```

生成されたテキストの内容を調整し、GEAR.indigo に投げてみます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/5e82b792-8700-4738-1f38-009ecda7ea9b.png)


2分ほどで作成が完了しました。
また、作成された内容は部分的な再生成や手動による修正も可能です。

### 作成物（要件定義）
- プロジェクト概要
- 現行業務フロー
- 業務要件一覧
- システム化業務フロー
- 機能要件一覧
- 非機能要件一覧

**プロジェクト概要**
![gearindigo.app_project_f1Qa5o3r3alWTrfaOE4P_component=basic-infos&edit=true.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/c90653e7-c0c6-e015-8a51-aa47c577424e.png)

**システム化業務フロー**
![gearindigo.app_project_f1Qa5o3r3alWTrfaOE4P_component=tobe-operation-flow&edit=true.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/0aad09ea-1453-f229-04b7-8f7e2d48c2ae.png)

**機能要件一覧**
![gearindigo.app_project_f1Qa5o3r3alWTrfaOE4P_component=functions-list&edit=true.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/102fd5bd-39c3-6d6e-9915-db76911c0704.png)

## システム設計
システム設計は、基本設計と詳細設計の2回に分けてドキュメントを作成していきます。
要件定義で使用したプロンプトを流用し基本設計を作成していきます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/fbf8c609-b31a-8033-0fbf-7c345d509cea.png)

同様に詳細設計も作成します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/58154c06-c0f5-2c1d-d8bf-013e5d84525d.png)

これで、要件定義とシステム設計のドキュメントが一通り作成されました。
実際は、作成されたものに修正を加えブラッシュアップする必要があると思います。

### 作成物（システム設計）
- システム概要
- テーブル定義
- ER図
- 画面遷移
- 画面一覧
- 画面UI
- 共通コンポーネント
- バックエンド処理
- シーケンス図
- アーキテクチャ

**システム概要**
![gearindigo.app_project_f1Qa5o3r3alWTrfaOE4P_component=system-abstraction&edit=true.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/105aa755-4164-be1a-ad5e-6a24b8a6f3f5.png)

**テーブル定義**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/ec5a26b8-97aa-ff72-b187-0396c56d293a.png)

**画面一覧**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/645a92f6-26be-63f0-5d71-a85a38e45d93.png)

**シーケンス図**
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/d523b95c-697a-11e8-8ff3-489f884c88ac.png)


## Markdown に変換する
作成したドキュメントを GEAR.indigo からエクスポートします。
JSON 形式でファイルがダウンロードされるので、MarkItDown を使用して Markdown 形式に変換します。

MarkItDown をインストールします。
```powershell
pip install markitdown
```

サンプルコード
```python:sample.py
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("test.xlsx")
print(result.text_content)
```

が、実行してみたところ「jsonはサポートしていない」という旨のエラーメッセージが出力されました。
```
markitdown._markitdown.UnsupportedFormatException: Could not convert 'asisOperationFlow.json' to Markdown. The formats ['.json', '.json'] are not supported.
```

実際の MarkItDown のソースコードを見てみましたが、たしかに JSON ファイルの変換処理はなさそうでした。
JSON を Markdown に変換する処理を実装してもいいのですが、せっかくなので MarkItDown を使ってみようと思います。

GEAR.indigo は作成したドキュメントを一括でエクスポートする場合はJSON形式になりますが、各ドキュメントを個別でエクスポートすることも可能です。その場合は、主に Word もしくは Excel 形式になるようです。
フロー図やER図などは png 形式でのダウンロードになるようですが、それらは GEAR.indigo 上にて Mermaid 記法で書かれているのでわざわざ変換する必要はないかなと思います。

それでは、各ドキュメントを変換してみようと思います。

```python:index.py
import os
from markitdown import MarkItDown

md = MarkItDown()

# docs フォルダ内のファイルを Markdown に変換する
for file in os.listdir('docs'):
  # ファイル名から拡張子を除いた部分(base_name)と拡張子(_)を取得
  base_name, _ = os.path.splitext(file)
  # ファイルをMarkdownに変換
  result = md.convert(f'docs/{file}')

  # 変換結果をMarkdownファイルとして保存
  # base_nameをファイル名として、utf-8エンコーディングで書き込み
  with open(f'{base_name}.md', 'w', encoding='utf-8') as f:
    f.write(result.text_content)
```

無事、変換できました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1560824/18924e1e-8426-6396-c2ac-e9ea82da660f.png)

# 感想
やはり、0→1 をここまで高速に作成できるのは、とても強力だと感じました。
特に、GEAR.indigo は人間による修正を前提としているので、AI駆動開発の一歩目として非常に扱いやすいツールだと思いました。