Zenn
Sun* DevelopersPublicationへの投稿
🤖

GPT・Mermaid・Githubを活用して設計業務をラクにする

kazz
2023/12/20に公開
GitHub
UML
設計
Mermaid
ChatGPT
idea

株式会社SunAsterisk Engineer の長浦和輝(ナガウラカズキ) @fizzkazzです。

昨年のAdvent Calendarでは、トラストレス・トラストから理解するblockchainの基礎を投稿しました。blockchainにご興味があれば、ぜひご覧ください。

今回のテーマ

本稿では、図系の設計ドキュメント作成・管理・運用にフォーカスして、GPT・Mermaid・Githubを活用してそれらを効率化する方法について、実際のプロジェクトにおいて採用した例を紹介します。

以下が、本稿で紹介する内容です。

  • ChatGPTとMermaidを組み合わせた作図の効率化
  • gitを活用した設計ドキュメントの管理
  • Githubを使った図を中心としたドキュメント管理と、設計レビューフローの効率化

こんな人に読んでほしい

以下のような悩みを抱えているエンジニア・PM・PdMの方に読んでいただきたいです。

  • 設計ドキュメント作成のうち、特に作図に必要以上の時間を取られている
  • 設計ドキュメントの管理がカオスになっている
  • 設計レビューのフローを仕組み化したい

[結論]効率的な設計ドキュメント作成フロー例

詳細を説明する前に、以下に今回紹介する活用例での設計ドキュメント作成フローを示します。

(今回は、ER図やシーケンス図といった作図系にフォーカスを当てています。)

それでは、それぞれのフェーズにおける具体的な方法を紹介します。

作図の効率化

Mermaidとは

(Mermaidについて既に知っている方は、この節は読み飛ばしてください)

たとえば、ER図やシーケンス図などの図示系の設計ドキュメントを作成する際に、以下のような悩みを抱えていませんか？

  • 設計は頭の中にあるのに、図示するのに時間がかかる
  • 図のレイアウト調整など、本質的でない部分に時間を取られる
  • 修正が必要になった際に、GUIツールでポチポチ修正するのが面倒

こういった課題に対しては、Mermaidを使うと効率化できます。

例えば、代表的なGUI上の作図ツールとして、draw.ioがありますが、MermaidはそのようなGUIツールと比べて以下のような特徴があります。

  • テキストベースでコードライクに図を作成できる
  • バージョン管理がしやすい
  • ドキュメントとして出力できる
  • VSCodeの拡張機能を使用して、プレビューを確認できる

例えば、以下のようにコードライクにER図を作成することが可能です。

```mermaid
---
title: Order example
---
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

(引用: Mermaid, https://mermaid.js.org/syntax/entityRelationshipDiagram.html)

また、このMermaidとGPTを組み合わせることで、設計ドキュメントの作成をさらに効率化できます。次節では、代表的なGPT系ツールであるChatGPTを使用した例を紹介します。

ChatGPTでの設計ドキュメント作成

例えば、シーケンス図を作成してみます。

私がGPTを活用してシーケンス図を作成する際、ある程度決まったテンプレートに沿ってプロンプトを使用します。
今回は、そのテンプレートを用いて、トークンによる認証認可とアカウント情報取得の簡単なシーケンス図を作成してみます。
(最近は、AWSのCognitoやAuth0で認証周りを実装することが多いですが、こちらはあくまで例として取り上げています。)

プロンプト

以下の要件に従って、シーケンス図を作成してください。

[使用するツール]

- Mermaid

[図示ルール]

- activate, deactivate, loop, alt, opt, par, noteを必要に応じて使用する

[出力形式]

- Markdown (スニペットで出力すること)

[要件 / 図示するスコープ]

- Userはログインできる
- Userはアカウント情報を確認できる

[制約条件]

- Userは、WebアプリケーションからEmail/PASSで認証を行う
- 認可サーバーは、認可トークンを発行する
- 認可トークンは、JWTを使用する
- リソースサーバーは、認可トークンを検証し、REST APIにてアカウント情報を返却する

実際のChatGPTの出力

今回は、GPT-4を使用しています。

以下は、指定された要件に従って作成したシーケンス図のMarkdown形式での表現です。この図はMermaidを使用して描かれ、ユーザーがWebアプリケーションを通じてログインし、アカウント情報を確認するプロセスを示しています。

```mermaid
sequenceDiagram
    participant User
    participant WebApp
    participant AuthServer
    participant ResourceServer

    User->>WebApp: ログインリクエスト (Email/PASS)
    activate WebApp
    WebApp->>AuthServer: 認証リクエスト
    activate AuthServer
    AuthServer->>WebApp: 認可トークン (JWT)
    deactivate AuthServer
    WebApp->>User: ログイン成功、認可トークン発行
    deactivate WebApp

    opt アカウント情報の確認
        User->>WebApp: アカウント情報確認リクエスト
        activate WebApp
        WebApp->>ResourceServer: 認可トークンでアカウント情報リクエスト
        activate ResourceServer
        ResourceServer->>ResourceServer: トークン検証
        alt トークンが有効
            ResourceServer->>WebApp: アカウント情報
            WebApp->>User: アカウント情報表示
        else トークンが無効
            ResourceServer->>WebApp: エラー応答
            WebApp->>User: エラーメッセージ表示
        end
        deactivate ResourceServer
        deactivate WebApp
    end
```
この図は、ユーザーがログインを試み、成功した場合に認可トークン（JWT）を受け取り、その後アカウント情報を確認するシーケンスを示しています。プロセスは、ユーザー、Webアプリケーション、認可サーバー、リソースサーバー間のやりとりを表しています。また、認可トークンの検証と、アカウント情報のリクエストと応答に関する分岐（`alt`）も含まれています。

(図のプレビュー)

このように、概ね想定通りのシーケンス図を作成することができました。

実際の業務の中では、GPTの出力を叩き台として、ドメインや実際のシステムの構成などを考慮し、必要に応じて修正を加えています。

より詳細に条件分岐等を指定することもできますが、プロンプト作成自体の工数を考慮して、まずはある程度の粒度で作成することをおすすめします。

管理の効率化

次に、管理の効率化について紹介します。

上記のように、コードライクに作成した設計ドキュメントは、当然のことながらバージョン管理がしやすいです。

シーケンス図やER図の管理/閲覧

図示系の設計ドキュメントは、Mermaidを使用して作成し、Markdown形式で出力します。

ディレクトリ構成はどのように管理しても良いですが、以下のような構成をおすすめします。

ProjectAlpha
│
├── ERDiagrams
│   └── ERDiagram.md
│
├── SequenceDiagrams
│   └── LoginSequence.md
│   └── PaymentProcessSequence.md
│   └── UserRegistrationSequence.md
│
├── Flowcharts
│   └── OrderProcessingFlowchart.md
│   └── CustomerServiceFlowchart.md
│
└── ClassDiagrams
    └── ClassDiagram.md

Github上で専用のリポジトリを作成し、上記を配置します。

GithubはMarkdown形式のファイルをプレビューできるので、このような構成にすることで、Github上でそのまま図を確認することができます。

wiki等でドキュメント管理をしている場合は、メインブランチのHEADコミットの参照リンクを貼ることで、wikiからたどって図を確認できるようになります。

https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files

また、特定のメジャーリリース時点での設計を確認できるようにしたい場合、タグを切った上でReleaseを作成すると良いでしょう。

https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository

レビューフローの効率化

設計書のレビューフローは、ほとんどの現場では人力運用ベースで行われ、コードレビューのように仕組み化されていないことが多いかと思います。

Github上でドキュメント管理を行うことにより、設計レビューのフローを仕組み化することができます。

ここでは、以下のような運用ルールを想定してみます。

  • 特定の1人のレビュワーが、設計ドキュメントの変更をレビューする
    • レビューがない場合は、正の設計ドキュメントの変更を許可しない

具体的には、以下のようにGithub上での設定を行います。

レビュワー、レビュイーそれぞれが適切な権限を持ったGithubアカウントを持っていることが前提です。

(以下の設定は、GithubのOrganizationプランで行うことを想定しています)

  • メインブランチ向けのRules > Rulesetsを作成する
    • "Require a pull request before merging"を有効にする
      • "Additional settings"で"Required approvals"を1に設定する
      • 更に細かいルールを設定したい場合は、こちらを参考にしてください。
    • "Block force pushes"を有効にする

これにより、メインブランチへの変更は、必ずPull Requestを経由してレビューを受けることになります。

また、以下の設定を行うことで、自動的に設計のレビュワーをアサインすることができます。

  1. レビュワー・レビュイーを含んだ専用のTeamを作成する
  2. 自動割り当ての設定を参考に、Teamにおいてレビュワーを自動割り当てるように設定する

まとめ

本稿では、GPT、Mermaid、およびGithubを活用して、設計ドキュメントの作成、管理、および運用を効率化する方法について実際の活用例を紹介しました。最後にポイントをまとめます。

ポイント

  1. GPTとMermaidの組み合わせ: 作図プロンプトを作成し、ChatGPTとMermaidを用いて効率的に設計ドキュメントを生成する方法を示しました。これにより、作図作業の時間を大幅に短縮することができます。

  2. 設計ドキュメントのバージョン管理: gitとGithubを使用して設計ドキュメントの管理を行うことで、容易に厳密なバージョン管理が可能になります。Mermaidで生成された図は、Github上で直接プレビューが可能です。

  3. レビューフローの効率化: Github上でのPull Requestとレビュープロセスを活用することで、設計ドキュメントのレビューが仕組み化され、透明性と効率が向上します。

これらのツールと方法論を組み合わせることで、設計プロセス全体をより効率的かつシームレスに行うことができます。エンジニア、PM、およびPdMは、これらのアプローチを取り入れることで、日々の作業負荷を軽減し、よりクリエイティブな作業に集中することが可能になります。

設計は非常に重要な作業ですが、一方でドキュメント作成自体に多くの時間を費やしてしまうことがあります。その作業に費やす時間を減らすことで、より多くの時間を実装やテストに費やすことができます。また、設計ドキュメントの管理を効率化することで、設計の変更に伴うコミュニケーションコストを削減することができます。

ぜひ、部分的にでも活用してみてください。

Sun* Developers
Sun* DevelopersPublication

Sun*は「誰もが価値創造に夢中になれる世界」をビジョンに掲げ、現在4ヶ国、6都市にて1500名以上のエンジニアやクリエイターが在籍するデジタル・クリエイティブスタジオです。

Discussion