要件定義書 - masa-codehub/github-auto-setup GitHub Wiki

1. 概要と背景

1.1. プロジェクトの目的と背景

本プロジェクトは、ソフトウェア開発プロセスにおけるGitHub上のセットアップ作業（プロジェクト作成、リポジトリ作成、Issue登録など）の効率化を目的とします。現状、これらの作業、特に要件定義書に基づいてIssue、マイルストーン、ラベル等を作成・登録するプロセスが手作業で行われており、非効率性やヒューマンエラーのリスクが課題となっています。

提供された「要件定義書からのGitHubプロジェクト・リポジトリ・Issue自動作成に関する調査報告書」（以下、調査報告書）に基づき、これらの課題を解決するための自動化ツールを開発します。

1.2. 解決したい課題

非効率性: 手作業によるGitHubリソースの作成・登録にかかる時間と工数の削減。
ヒューマンエラーのリスク: Issue登録時の入力ミス、設定漏れ、担当者割り当てミスなどの削減。
標準化の欠如: プロジェクトやIssue登録のフォーマット・粒度のばらつきを抑制し、管理を容易にする。
開発体験の低下: 開発者が本来注力すべきタスクに集中できるよう、単純作業の繰り返しから解放する。

2. システム化の目的とゴール

2.1. システム化の目的

本システムの導入により、以下のビジネス目標達成を目指します。

GitHubプロジェクトセットアップのリードタイムを [具体的な目標値]%短縮 する。
Issue登録に関する手作業起因のエラー発生率を [具体的な目標値]%削減 する。
開発チーム内でのIssue管理プロセスの標準化を促進する。
開発者の満足度を向上させる。

2.2. 主要な成功基準

指定されたMarkdown形式のテキストファイルをインプットとし、CLI引数でリポジトリ名・プロジェクト名が指定され、生成AIによる解析を経て、GitHub上にプロジェクト、リポジトリ、Issue、ラベル、マイルストーンが自動で作成・設定されること。
ツールの操作が容易であり、開発者が日常的に利用できること。
処理結果（成功・失敗、スキップしたIssueの情報含む）が明確にユーザーにフィードバックされること。
（TDD観点）主要な機能（特にGitHub連携部分やデータ整形ロジック）に対してユニットテスト・結合テストが実装され、品質が担保されていること。
（Clean Architecture観点）将来的な機能拡張（例: Web UI化、Django連携）や仕様変更に対応しやすい疎結合な設計であること。
LangChainを利用し、設定によって生成AIモデル（ChatGPT, Gemini等）を切り替え可能であること。

3. スコープ定義

3.1. 対象範囲（In Scope）

入力: - Markdown形式のテキストファイル（ファイルパス指定）。 - CLI引数によるリポジトリ名、プロジェクト名の指定。
処理: - 入力テキストファイルの読み込み。 - LangChainフレームワークを利用し、選択された生成AI API (ChatGPT API, Gemini API等) を用いたテキスト内容の解析と、GitHubリソース情報（ラベル、マイルストーン、Issueタイトル/本文/担当者等）の抽出・構造化。 - GitHub APIまたはGitHub CLI (gh) を利用した以下のGitHubリソースの作成・設定（冪等性を考慮）。 - リポジトリ (Repository): 引数で指定された名前で新規作成、デフォルトPrivate - プロジェクト (Project): 引数で指定された名前で作成 (Projects V2) - ラベル (Label): 色は自動割り当て - マイルストーン (Milestone) - Issue (タイトル, 本文, ラベル, マイルストーン, 担当者): 重複時はスキップし記録。担当者はMarkdown内に特定の記法があれば設定、なければ未設定。 - 作成されたIssueのプロジェクトへの自動追加。
出力: 標準出力への処理結果（成功・失敗、エラー内容、作成リソースURL、スキップしたIssue情報等）の表示。
実行形態: コマンドラインインターフェース (CLI) アプリケーション。
開発言語: Python。
認証: GitHub Personal Access Token (PAT) および生成AI APIキーの利用。

3.2. 対象範囲外（Out of Scope）

WebアプリケーションとしてのUI開発（将来的な展望としては考慮するが、今回の開発範囲外）。
入力テキストファイル（要件定義書）自体の作成支援機能。
生成AIを利用しない、規約ベースのパーサー実装。
AIによるIssue担当者の推測機能。
GitHub以外のプラットフォーム（GitLab, Jira等）への対応。
複雑なエラーリカバリ処理（エラー発生時は基本的に処理中断）。
GUIインストーラーの提供。
生成AIのFine-tuning等の高度なカスタマイズ。

4. 主要なステークホルダーと役割

開発者: 本ツールの主要ユーザー。Issue登録作業の効率化を期待。
プロジェクトマネージャー (PM): プロジェクトセットアップや進捗管理の効率化、標準化を期待。入力テキストの記述スタイルに関与。
システム管理者/運用担当: （将来的なWebアプリ化の場合）デプロイや運用に関わる可能性。
(DDD観点): 開発者やPMが持つ「GitHubでのプロジェクト管理」や「要件をタスクに落とし込むプロセス」に関する知識がドメイン知識の源泉となる。彼らとの対話を通じて、「リポジトリ」「プロジェクト」「Issue」「ラベル」「マイルストーン」「担当者」「タスク」といったユビキタス言語を定義し、ドメインモデルに反映させる。

5. ユースケース定義

5.1. UC-001: テキストファイルからGitHubリソースを自動登録する

アクター: 開発者、プロジェクトマネージャー
事前条件: - ユーザーは本CLIツールを実行できるDocker環境を持っている。 - 有効なGitHub PATおよび生成AI APIキーが環境変数等で設定されている。 - 入力となるMarkdownファイルが存在する。 - 作成対象のリポジトリ名、プロジェクト名がCLI引数で指定されている。 - 対象のGitHubリソースを作成・変更する権限をPATが持っている。
事後条件: - Markdownファイルの内容に基づき、引数で指定された名前の対応するGitHubリソース（リポジトリ、プロジェクト、ラベル、マイルストーン、Issue）が作成または適切に設定される。重複するIssueはスキップされる。 - 処理結果（成功、失敗、作成されたリソースのURL、スキップしたIssueの情報など）がユーザーに表示される。
基本フロー: 1. アクターはCLIコマンドを実行し、入力Markdownファイルのパス、リポジトリ名、プロジェクト名を指定する。(docker run ... python main.py --file path/to/requirements.md --repo my-repo --project "My Project") 2. システム(CLI)は指定されたファイルを読み込む。 3. システムはファイル内容を、設定された生成AIモデル (LangChain経由) に送信し、解析を依頼する。 4. システムは生成AIからの解析結果（構造化データ）を受け取る。 5. システムは解析結果に基づき、GitHub API/CLI を呼び出す準備をする。 6. システムは引数で指定された名前のリポジトリ、プロジェクト、および解析結果に基づくラベル、マイルストーンについて、GitHub上に既に存在するか確認する（冪等性担保）。 7. 存在しないリソース、または更新が必要なリソースを作成・設定する（リポジトリは新規Private）。 8. システムは解析結果の各Issueについて、Issueを作成する前に同名のIssueが存在しないか確認する。 - 8a. 存在する場合：Issue作成をスキップし、その旨を記録する。 - 8b. 存在しない場合：Issueを作成し、タイトル、本文、抽出されたラベル、マイルストーンを設定する。もし解析結果に特定の記法による担当者情報が含まれていれば、それも設定する。

9. システムは正常に作成されたIssueを、引数で指定された名前のプロジェクトに追加する。 10. システムは全ての処理結果を集約し、標準出力にサマリーを表示する。

代替フロー（例外フロー）: - 4a. ファイルが存在しない場合：エラーメッセージを表示し処理を中断。 - 4b. 必須のCLI引数（ファイルパス、リポジトリ名、プロジェクト名）が不足している場合： エラーメッセージを表示し処理を中断。 - 4c. 生成AI APIキーが無効、またはAPI呼び出しエラーの場合：エラーメッセージを表示し処理を中断。 - 4d. 生成AIが期待した形式で解析結果を返さなかった場合：エラーメッセージを表示し処理を中断。 - 7a. GitHub認証失敗の場合：エラーメッセージを表示し処理を中断。 - 7b. GitHub API/CLIエラーの場合：エラー内容を表示し処理を中断。
(Clean Architecture観点): ユースケースはUI（CLI引数解析含む）、Frameworks & Drivers（AI/GitHubクライアント）、Entities（ドメインモデル）から分離される。

6. ドメインモデル（初期案）

エンティティ (Entity): Repository, Issue, Label, Milestone, Project
値オブジェクト (Value Object): - FilePath: path - GitHubCredentials: token - AiApiCredentials: api_key, model_name - RepositoryName: owner, repo (CLI引数から生成) - ProjectName: name (CLI引数から生成) - LabelName, LabelColor (Optional) - MilestoneTitle - Assignee: login (Optional, 特定記法があれば抽出) - ParsedRequirementData: (AIの解析結果) labels: List[LabelName], milestone: Optional[MilestoneTitle], issues: List[IssueData(title, body, assignees: Optional[List[Assignee]], ...)] (担当者はOptional)
集約 (Aggregate): Repository Aggregate, Project Aggregate
ドメインサービス (Domain Service): - RequirementAiParser: Markdownテキストとプロンプトを受け取り、LangChainを通じて生成AI APIと通信し、ParsedRequirementData を生成する。担当者情報の特定記法解析も含む可能性あり。 - GitHubResourceCreator: ParsedRequirementData およびCLI引数で指定されたリポジトリ名・プロジェクト名を受け取り、GitHubリソースを作成・設定する。冪等性ロジック（重複Issueスキップ含む）を含む。
ユビキタス言語 (Ubiquitous Language): - 要件定義ファイル (Requirement File) - 生成AI (Generative AI) - LangChain: 生成AIアプリケーション開発フレームワーク。 - 解析 (Parse / Interpretation) - プロンプト (Prompt) - 登録 (Register / Create / Apply) - リポジトリ (Repository), プロジェクト (Project), イシュー (Issue), ラベル (Label), マイルストーン (Milestone), 担当者 (Assignee) - 冪等性 (Idempotency) - スキップ (Skip)
(DDD観点): LangChainの導入はInfrastructure層の詳細だが、開発者間の共通言語として重要になる可能性。

7. 機能要件

FR-001: コマンドライン引数で指定されたパスのテキストファイルを読み込むこと。
FR-002改: 読み込んだMarkdownテキストの内容を、LangChainフレームワークを通じて設定された生成AI APIを利用して解析し、ラベル、マイルストーン、およびIssueリスト（タイトル、本文、特定の記法があれば担当者情報を含む）の情報を抽出・構造化すること。 - 入力: ファイル内容文字列, AI APIキー, プロンプトテンプレート, 設定されたAIモデル名 - 出力: ParsedRequirementData オブジェクト or AI解析エラー
FR-003改: CLI引数で指定されたリポジトリ名で、GitHubに新規にPrivateリポジトリを作成すること。
FR-004改: CLI引数で指定されたプロジェクト名で、GitHubにプロジェクト(v2)を作成すること（冪等）。
FR-005改: ParsedRequirementData に基づき、指定リポジトリにラベルを作成すること（冪等）。色は自動割り当て。
FR-006: ParsedRequirementData に基づき、指定リポジトリにマイルストーンを作成すること（冪等）。
FR-007改: ParsedRequirementData のIssueリストに基づき、指定リポジトリにIssueを作成し、関連情報（ラベル、マイルストーン、記法があれば担当者）を設定すること。Issue作成前に同名Issueの存在を確認し、存在する場合はスキップする。
FR-008改: 正常に作成されたIssueを、CLI引数で指定された名前のプロジェクトに追加すること。
FR-009改: 処理全体の実行結果（成功、失敗、エラー内容、作成したリソースURL、スキップしたIssueのタイトルリスト等）を標準出力に分かりやすく表示すること。
FR-010改: GitHub PATおよび生成AI APIキーを環境変数等から安全に読み込み、利用すること。
FR-011: CLIのヘルプメッセージを表示する機能 (--help)。
FR-012: （オプション）ドライラン機能 (--dry-run) を実装する。
FR-NEW-01改: CLI引数パーサーを実装し、必須引数（--file, --repo, --project）およびオプション引数を解釈する機能。
FR-NEW-02: LangChainを利用し、設定ファイルや環境変数等で利用する生成AIモデル（例: ChatGPT, Gemini）を切り替え可能にする機能。

8. 非機能要件

性能: - NFR-Perf-01: GitHub APIレート制限を考慮。生成AI APIのレスポンスタイムも処理時間に影響することを考慮。 - NFR-Perf-02: 利用するパーサーライブラリ、AI APIクライアントは妥当なメモリ使用量であること。
可用性: - NFR-Avail-01: CLIツールとして、実行環境とネットワーク接続があれば利用可能。GitHubおよび生成AI APIサービスが利用可能である必要がある。
セキュリティ: - NFR-Sec-01: GitHub PAT、生成AI APIキーをソースコード中にハードコーディングしない。環境変数推奨。 - NFR-Sec-02: 利用するライブラリに既知の脆弱性がないか確認。
保守性/拡張性: - NFR-Maint-01: クリーンアーキテクチャの原則に従う。 - NFR-Maint-02: プロンプトテンプレート、利用AIモデル設定、デフォルト値などを外部設定ファイル化。 - NFR-Maint-03: Pythonの型ヒント、静的解析ツール活用。 - NFR-Maint-04: 可読性の高いコード、ドキュメンテーション。 - NFR-Maint-05: 将来的なDjangoでのWebアプリ化を考慮し、コアロジックはAPIとして呼び出しやすいインターフェース（例: 関数、クラスメソッド）で実装。 - NFR-Maint-06改: LangChainを活用し、異なる生成AIモデルへの切り替えや追加を容易にする。
テスト容易性: - NFR-Test-01: UseCase層、Domain層のユニットテスト。 - NFR-Test-02: 生成AI APIクライアントやGitHubクライアントはモックを用いてテスト可能にすること。 - NFR-Test-03: CLIのエンドツーエンドに近いテスト（簡単な入力ファイルとモックAPIを使用）。
UI/UX (CLI): - NFR-UIUX-01: コマンドライン引数やオプションは直感的。 - NFR-UIUX-02: ヘルプメッセージは十分な情報を提供。 - NFR-UIUX-03: 進行状況（AI解析中、GitHub登録中など）やエラーメッセージ、スキップ情報は具体的で分かりやすいこと。
AI利用に関する考慮事項: - NFR-AI-01: 生成AIの解析精度は100%ではなく、手動での確認・修正が前提であることを関係者で合意する。 - NFR-AI-02: 生成AI APIの利用コストを意識する。 - NFR-AI-03: AI出力の変動する可能性があるため、処理の再現性について考慮する。

9. 受け入れ基準 (Acceptance Criteria)

AC-UC001-Full-AI-Args: - Given Markdownファイル test.md があり、有効なGitHub PATとAI APIキーが環境変数に設定されている。担当者指定の記法 (Assignee: @user1) がファイル内の一部のIssueに含まれている。 - When python main.py --file test.md --repo final-repo --project "Final Project" を実行する。 - Then 生成AI APIが呼び出され、標準出力に成功メッセージと作成された各リソースのURLが表示され、かつ実際にGitHubを確認すると、final-repo というPrivateリポジトリ、Final Project というプロジェクト(v2)が作成され、test.md の内容に対応するラベル、マイルストーン、Issue（担当者情報が記法通りに設定されているものと、未設定のものがある）が作成され、Issueがプロジェクトに追加されている。
AC-UC001-SkipDuplicate: - Given 上記AC-UC001-Full-AI-Argsの実行後、再度同じコマンドを実行する。 - When python main.py --file test.md --repo final-repo --project "Final Project" を実行する。 - Then 標準出力にスキップされたIssueの情報が表示され、GitHub上でIssueが重複して作成されていない。
AC-UC001-AiError: - Given AI APIキーが無効である。 - When python main.py --file test.md --repo any-repo --project "Any Project" を実行する。 - Then 標準出力にAI API関連のエラーメッセージが表示され、処理が中断され、GitHubへの変更は行われない。
AC-FR-NEW-01-ArgsParsing: - Given なし。 - When python main.py --file test.md （必須引数不足）を実行する。 - Then 標準出力に引数不足を示すエラーメッセージが表示され、処理が中断される。
AC-FR-NEW-02-ModelSwitch: - Given 設定ファイルでAIモデルをGeminiに変更する。 - When python main.py ... を実行する。 - Then （モックまたはログ確認で）Gemini APIが呼び出されることを確認できる。
AC-NFR-Sec-01-NoHardcode-AI: - Given ソースコードレビュー。 - When コード全体を確認する。 - Then ソースコード中にGitHub PATおよびAI APIキー文字列がハードコードされていない。
(TDD観点): LangChainのChainやAgentのテスト、モデル切り替えに関するテストを追加。

10. 用語集

要件定義ファイル (Requirement File): Markdown形式のテキストファイル。
生成AI (Generative AI)
LangChain: 生成AIアプリケーション開発フレームワーク。
解析 (Parse / Interpretation)
プロンプト (Prompt)
登録 (Register / Create / Apply)
冪等性 (Idempotency)
スキップ (Skip)
PAT (Personal Access Token)
APIキー (API Key): 生成AI APIキー。
CLI (Command Line Interface)
プロジェクトV2 (Project V2)
(その他) リポジトリ、Issue、ラベル、マイルストーン、担当者
(DDD観点): LangChainは技術詳細だが、開発者間の共通言語として重要になる可能性。

11. 制約条件・前提条件

開発言語: Python 3.12.4
実行環境: Docker上のLinux環境。インターネット接続環境が必要。
外部依存: GitHub API または GitHub CLI (gh)。生成AI APIサービス。LangChainフレームワークおよび関連ライブラリ。
認証: GitHubアカウントおよび必要なスコープを持つPAT、有効な生成AI APIキーが事前に準備されていること。
入力フォーマット: 要件定義ファイルはMarkdown形式。AIが解釈しやすい構造が望ましい。担当者情報は特定の記法がある場合のみ解釈対象とする。
リポジトリ・プロジェクト名: CLI実行時に引数で指定されること。
初期フェーズ: CLIアプリケーションとして提供。
機能優先度: 1. リポジトリ/Issue作成 -> 2. ラベル/マイルストーン -> 3. プロジェクト作成の順。