AIと人間の協働による設計ドキュメント作成

こんにちは、ENECHANGEのエンジニア深澤です。

現在、AIを活用したソフトウェア設計ドキュメントの生成や整備がどこまで現実的に可能なのか、実験的に模索しています。

本記事では、その取り組みの一例をご紹介していきたいと思います。

背景と課題

多くの開発チームが直面している以下のような課題に対して、新しいアプローチを試みました。

ドキュメントの更新が実装に追いつかない
バイナリ形式のドキュメントでは変更履歴の追跡が困難
チーム内での設計の共有と理解が属人化しやすい
レビューとフィードバックのプロセスが不明確
ドキュメントとコードの整合性維持が困難

解決へのアプローチ

これらの問題に対して「設計ドキュメントをコードと同様に扱う」という方針のもと、以下の要素を組み合わせたアプローチを実践しました。

1. プレーンテキストベースのドキュメント管理

reStructuredText形式での記述
Gitによるバージョン管理
Mermaidによる図表の自動生成

2. GitHubを中心としたワークフロー

変更履歴の追跡と管理
Pull Requestベースのレビュープロセス

3. 段階的な設計プロセス

ユーザーストーリー
ドメインモデル
ユースケース
技術設計（画面、DB、メール、バッチ）

使用するツール

主要なツールとその役割：

Cursor: AI支援エディタ（Claude搭載）
Sphinx: ドキュメンテーションツール
GitHub: バージョン管理とIssue管理
GitHub MCP Server: ClaudeとGitHubの連携

ドキュメンテーションツールとしてSphinxを採用しています。

Sphinxは、Python製の高機能なドキュメント生成ツールであり、以下のような特徴があります。

Sphinxの特徴

プレーンテキストベース
- reStructuredText形式での記述
- Gitでの変更管理が容易
- テキストエディタでの編集が可能
豊富な表現力
- 基本的な文書構造（見出し、リスト、表）
- コードブロックのシンタックスハイライト
- 相互参照機能
Mermaid図表対応
- テキストベースでの図表定義
- 各種図表の自動生成
- 変更管理の容易さ

レポジトリ

このアプローチの実践例として、サンプルレポジトリを公開しています。

github.com

試してみたい方は、README.md を参考にしてみてください。

構成要素

1. GitHub Issueとユーザーストーリー

GitHubのIssueを活用して、簡潔なユーザーストーリーを記述します。
このIssueをCursor（Claude）で解析し、設計ドキュメントを生成していきます。

2. 設計ルールの管理（.cursor/rules）

.cursor/rules/
├── workflow.mdc        # 全体のワークフロー
├── user_story.mdc     # ユーザーストーリー作成ルール
├── usecase.mdc        # ユースケース作成ルール
├── domain_model.mdc   # ドメインモデル作成ルール
├── database.mdc       # データベース設計ルール
└── mermaid.mdc        # 図表作成ルール

これらのルールファイルは、Claudeが参照し一貫性のあるドキュメントの作成を支援します。

3. 設計ドキュメントの構造

設計ドキュメントは、以下のような階層構造で管理します。

各階層のテンプレート（template.rst）を用いてドキュメントを作成します。

docs/design/source/
├── batch
│   ├── index.rst
│   └── template.rst
├── database
│   ├── er.rst
│   ├── index.rst
│   └── template.rst
├── ddd
│   ├── index.rst
│   └── template.rst
├── domain_model.rst
├── index.rst
├── mail
│   ├── contact_form.rst
│   ├── index.rst
│   └── template.rst
├── screen
│   ├── diagram.rst
│   └── index.rst
├── usecase
│   ├── diagram.rst
│   ├── index.rst
│   └── template.rst
└── user_story
    ├── index.rst
    └── template.rst

各ディレクトリの役割：

user_story/: ユーザーストーリーの定義と受け入れ条件
domain_model.rst: プロジェクト全体で使用される用語とエンティティの定義
usecase/: ユースケース図と詳細な振る舞いの記述
screen/: 画面遷移図と画面レイアウトの定義
database/: ER図とテーブル定義
mail/: メールテンプレートと送信条件の定義
batch/: バッチ処理の仕様と実行条件の定義
ddd/: ドメイン駆動設計に基づくモデリングと実装方針

実践例：お問い合わせフォーム機能の設計

1. GitHub Issueの作成

2. 設計ドキュメントの作成

Github MCP を利用してClaudeにGitHub Issueを取得させ、以下の順番でドキュメントの生成を行わせます。
- ユーザーストーリー
- ドメインモデル
- ユースケース
- 技術設計（画面、DB、メール、バッチ）

---

**User**

MasaruFukazawa/designdocs-sample の issue #1 を取得してください。
この issue を元に設計を開始してください。

---

**Cursor**

GitHub issueを取得するために、GitHub APIを使用してみましょう。

Issue #1の内容を確認できました。これに基づいて、`.cursor/rules`に従って設計を開始します。

まず、ワークフローに従って、ユーザーストーリーから作成していきます。

### 1. ユーザーストーリーの作成

新しいユーザーストーリーファイルを作成します：