386 lines
13 KiB
Markdown
386 lines
13 KiB
Markdown
# 実装計画から GitHub Issues を作成
|
||
|
||
Keywords: github-issues, epic, sub-issues, automation, implementation-plan, mcp-prompts, mcp-tools
|
||
|
||
## 目的
|
||
|
||
実装計画ドキュメント (`implementation-plan-template.md`) から、Epic および子 Issue を自動生成し、GitHub Issues として起票します。
|
||
|
||
## 使用する MCP ツール
|
||
|
||
このコマンドは以下の MCP ツールを使用します：
|
||
|
||
- **`get_implementation_plan_to_issues`**: Issue 作成ガイドライン (`implementation-plan-to-issues.md`) を取得する専用ツール
|
||
|
||
## 使用する MCP リソース
|
||
|
||
以下の MCP prompts も併せて使用できます：
|
||
|
||
- `implementation-plan-template`: 実装計画のテンプレート構造
|
||
- `epic-template`: Epic Issue のテンプレート
|
||
- `feature-template`: Feature Issue のテンプレート
|
||
- `migration-template`: Migration Issue のテンプレート
|
||
- `test-template`: Test Issue のテンプレート
|
||
- `docs-template`: Docs Issue のテンプレート
|
||
- `chore-template`: Chore Issue のテンプレート
|
||
|
||
## 前提条件
|
||
|
||
- `gh` CLI がインストール済み・認証済み
|
||
- リポジトリのラベルが設定済み（例: `type:feature`, `type:migration`, `type:test`, `type:docs`, `priority:P1|P2|P3`, `size:S|M|L`）
|
||
- **MCP サーバーが起動済み**: 以下のテンプレートを MCP prompts から取得します
|
||
- `implementation-plan-template`: 実装計画テンプレート
|
||
- `epic-template`: Epic Issue テンプレート
|
||
- `feature-template`: Feature Issue テンプレート
|
||
- `migration-template`: Migration Issue テンプレート
|
||
- `test-template`: Test Issue テンプレート
|
||
- `docs-template`: Docs Issue テンプレート
|
||
- `chore-template`: Chore Issue テンプレート
|
||
- 実装計画ドキュメントが存在（またはユーザーが提供）
|
||
|
||
## 処理フロー
|
||
|
||
1. **MCP から必要なドキュメントを取得**
|
||
|
||
- **実装計画テンプレート**: MCP prompts から `implementation-plan-template` を読み込み
|
||
- **Issue テンプレート**: MCP prompts から各種テンプレートを読み込み
|
||
- `epic-template` (Epic 用)
|
||
- `feature-template` (実装 Issue 用)
|
||
- `migration-template` (移行 Issue 用)
|
||
- `test-template` (テスト Issue 用)
|
||
- `docs-template` (ドキュメント Issue 用)
|
||
- `chore-template` (Chore Issue 用)
|
||
- ユーザーから実装計画ファイルのパスを受け取る場合はそれを使用
|
||
|
||
2. **実装計画の解析**
|
||
|
||
- 機能名、設計方針、コンポーネント、移行計画を抽出
|
||
- Epic および子 Issue のリストを生成
|
||
|
||
3. **Epic Issue の作成**
|
||
|
||
- MCP から取得した `epic-template` をベースに Epic を作成
|
||
- タイトル: `[Feature] <機能名>: 実装計画と進行管理`
|
||
- サブ Issue のチェックリストを含む
|
||
|
||
4. **子 Issue の作成候補を提示**
|
||
|
||
- 実装 Issue（コンポーネント/ユーティリティ）
|
||
- 移行 Issue（Phase 1〜4）
|
||
- 品質 Issue（テスト/パフォーマンス/セキュリティ/ドキュメント）
|
||
|
||
5. **GitHub Issues として作成**
|
||
- `gh issue create` コマンドを使用
|
||
- ラベル、マイルストーンを適切に設定
|
||
|
||
## Prompt Template
|
||
|
||
以下のタスクを実行してください：
|
||
|
||
1. **MCP ツール「get_implementation_plan_to_issues」を利用して、Issue 作成ガイドラインを読み込むこと**
|
||
|
||
2. **MCP prompts から必要なテンプレートを読み込むこと**
|
||
|
||
- `implementation-plan-template`: 実装計画の構造を理解
|
||
- `epic-template`, `feature-template`, `migration-template`, `test-template`, `docs-template`, `chore-template`: 各種 Issue テンプレート
|
||
|
||
3. **実装計画ドキュメントを解析すること**
|
||
|
||
- ユーザーが指定した実装計画ファイル（または `implementation-plan-template`）を読み込み
|
||
- 機能名、設計方針、コンポーネント、移行計画を抽出
|
||
|
||
4. **Epic Issue と子 Issue のドラフトを生成すること**
|
||
|
||
- Epic: 全体の進行管理用
|
||
- Feature: 実装タスク（コンポーネント/ユーティリティ）
|
||
- Migration: 移行フェーズ（Phase 1〜4）
|
||
- Quality: テスト/パフォーマンス/セキュリティ/ドキュメント
|
||
|
||
5. **GitHub Issues を作成すること**
|
||
- `gh issue create` コマンドを使用
|
||
- 適切なラベル、マイルストーン、優先度を設定
|
||
|
||
## 使用方法
|
||
|
||
### 基本的な使い方
|
||
|
||
```
|
||
@workspace 実装計画から GitHub Issues を作成してください
|
||
```
|
||
|
||
### 実装計画ファイルを指定する場合
|
||
|
||
```
|
||
@workspace <ファイルパス> の実装計画から GitHub Issues を作成してください
|
||
```
|
||
|
||
### オプション指定
|
||
|
||
```
|
||
@workspace 実装計画から GitHub Issues を作成してください
|
||
- マイルストーン: Sprint 5
|
||
- 優先度: P2
|
||
- 担当者: @username
|
||
```
|
||
|
||
## 実行手順
|
||
|
||
1. **MCP からテンプレートを取得**
|
||
|
||
- MCP prompts から `implementation-plan-template` を取得し、実装計画の構造を理解
|
||
- MCP prompts から各種 Issue テンプレート (`epic-template`, `feature-template` など) を取得
|
||
- または、ユーザー指定のファイルを読み込み
|
||
|
||
2. **実装計画の解析と Issue リストの生成**
|
||
|
||
- 機能名、コンポーネント、移行計画を抽出
|
||
- MCP から取得したテンプレートを使用して Issue タイトルと本文のドラフトを生成
|
||
|
||
3. **Epic Issue の作成**
|
||
|
||
```sh
|
||
# Epic 本文を生成
|
||
cat > /tmp/epic-body.md <<'EOF'
|
||
# 背景 / 目的
|
||
|
||
- 機能名: <機能名>
|
||
- 設計方針の要点（抜粋）: <抽出した設計方針>
|
||
|
||
# スコープ
|
||
|
||
- コンポーネント: <抽出したコンポーネント>
|
||
- サービス/ユーティリティ: <抽出したサービス>
|
||
- 移行フェーズ: Phase1〜4
|
||
|
||
# サブ Issue（Tasklist）
|
||
|
||
- [ ] ComponentA: create/parse を実装
|
||
- [ ] ComponentA Utils: validate/transform を実装
|
||
- [ ] ComponentB: 型/ファクトリを実装
|
||
- [ ] Phase 1: 基本実装
|
||
- [ ] Phase 2: 既存コード移行
|
||
- [ ] Phase 3: テスト/ドキュメント
|
||
- [ ] Phase 4: 最適化/クリーンアップ
|
||
- [ ] テスト整備
|
||
- [ ] パフォーマンス検討
|
||
- [ ] セキュリティ/エラー対策
|
||
- [ ] ドキュメント更新
|
||
|
||
# 受け入れ条件（DoD）
|
||
|
||
- 子 Issue が全て Close
|
||
- 相互参照が揃っている
|
||
- ドキュメント/テストが最新
|
||
|
||
# 関連
|
||
|
||
- 設計ドキュメント: <実装計画ファイルへのリンク>
|
||
EOF
|
||
|
||
# Epic Issue を作成
|
||
gh issue create \
|
||
--title "[Feature] <機能名>: 実装計画と進行管理" \
|
||
--body-file /tmp/epic-body.md \
|
||
--label "type:feature" \
|
||
--label "priority:P2"
|
||
```
|
||
|
||
4. **子 Issue 候補の提示**
|
||
|
||
- ユーザーに確認を求める
|
||
- 必要に応じて調整
|
||
|
||
5. **実行確認後、一括作成（オプション）**
|
||
- ユーザーが承認した場合、`gh issue create` を連続実行
|
||
- または、Epic 作成後に UI で「Convert to sub-issues」を使用するよう案内
|
||
|
||
## Issue 種別とテンプレート
|
||
|
||
> **注記**: すべてのテンプレートは MCP prompts から取得します。ワークスペースには `general/issue-templates/*.template.md` として保存されていますが、実行時は MCP 経由でアクセスします。
|
||
|
||
### 実装 Issue（Feature）
|
||
|
||
MCP Prompt: `feature-template`
|
||
ファイル: `general/issue-templates/feature.template.md`
|
||
|
||
タイトル例:
|
||
|
||
- `[Feature][Model] ComponentA: create/parse を実装`
|
||
- `[Feature][Util] ComponentA Utils: validate/transform を実装`
|
||
- `[Feature][Model] ComponentB: 型とファクトリ実装`
|
||
|
||
ラベル: `type:feature`, `size:S|M|L`, `area:*`
|
||
|
||
### 移行 Issue（Migration）
|
||
|
||
MCP Prompt: `migration-template`
|
||
ファイル: `general/issue-templates/migration.template.md`
|
||
|
||
タイトル例:
|
||
|
||
- `[Migration] Phase 1: 基本実装`
|
||
- `[Migration] Phase 2: 既存コード移行`
|
||
- `[Migration] Phase 3: テストとドキュメント化`
|
||
- `[Migration] Phase 4: 最適化とクリーンアップ`
|
||
|
||
ラベル: `type:migration`, `priority:P1|P2|P3`
|
||
|
||
### 品質 Issue（Test/Docs/Chore）
|
||
|
||
MCP Prompts:
|
||
|
||
- Test: `test-template` (`general/issue-templates/test.template.md`)
|
||
- Docs: `docs-template` (`general/issue-templates/docs.template.md`)
|
||
- Chore: `chore-template` (`general/issue-templates/chore.template.md`)
|
||
|
||
タイトル例:
|
||
|
||
- `[Test] ComponentA/B の単体・結合テスト整備`
|
||
- `[Perf] パフォーマンス考慮点の計測/最適化`
|
||
- `[Security] エラーハンドリング/入力検証の整備`
|
||
- `[Docs] 使用例/設計ドキュメント更新`
|
||
|
||
ラベル: `type:test`, `type:docs`, `type:chore`
|
||
|
||
## 実装例（実際の処理）
|
||
|
||
### ステップ 1: 実装計画の読み込みと解析
|
||
|
||
```typescript
|
||
// 実装計画ドキュメントから情報を抽出
|
||
const plan = {
|
||
featureName: "機能名",
|
||
designPrinciples: "設計方針の要点",
|
||
components: ["ComponentA", "ComponentB"],
|
||
phases: ["Phase 1", "Phase 2", "Phase 3", "Phase 4"],
|
||
implementationStatus: {
|
||
done: ["Task 1"],
|
||
todo: ["Task 2", "Task 3"],
|
||
},
|
||
};
|
||
```
|
||
|
||
### ステップ 2: Epic Issue の作成
|
||
|
||
```sh
|
||
# Epic Issue 番号を取得
|
||
EPIC_NUMBER=$(gh issue create \
|
||
--title "[Feature] ${FEATURE_NAME}: 実装計画と進行管理" \
|
||
--body-file /tmp/epic-body.md \
|
||
--label "type:feature" \
|
||
--label "priority:P2" \
|
||
--json number --jq .number)
|
||
|
||
echo "Created Epic: #${EPIC_NUMBER}"
|
||
```
|
||
|
||
### ステップ 3: 子 Issue の作成（オプション）
|
||
|
||
```sh
|
||
# ComponentA の実装 Issue
|
||
cat > /tmp/component-a-body.md <<EOF
|
||
# 目的
|
||
|
||
- ComponentA の create/parse を実装する
|
||
|
||
# 仕様
|
||
|
||
- 入力: <型/前提>
|
||
- 出力: <型/結果>
|
||
|
||
# タスク
|
||
|
||
- [ ] 型定義の作成/更新
|
||
- [ ] create メソッドの実装
|
||
- [ ] parse メソッドの実装
|
||
- [ ] 単体テスト
|
||
- [ ] ドキュメント追加
|
||
|
||
# 完了条件
|
||
|
||
- テストがグリーン
|
||
- ドキュメントに使用例が掲載
|
||
|
||
# 関連
|
||
|
||
- Epic: #${EPIC_NUMBER}
|
||
EOF
|
||
|
||
gh issue create \
|
||
--title "[Feature][Model] ComponentA: create/parse を実装" \
|
||
--body-file /tmp/component-a-body.md \
|
||
--label "type:feature" \
|
||
--label "size:M"
|
||
```
|
||
|
||
## UI での推奨運用（サブ Issue 機能）
|
||
|
||
Epic を作成後、GitHub UI で以下の操作を行うことを推奨します:
|
||
|
||
1. Epic Issue を開く
|
||
2. 本文のチェックリストにカーソルを合わせる
|
||
3. 「Convert to sub-issues」ボタンをクリック
|
||
4. 自動で子 Issue が作成され、親子リンクが確立
|
||
5. 進捗バーが自動更新される
|
||
|
||
この方法により、手動で `関連: #<epic>` を記述する必要がなくなります。
|
||
|
||
## 注意事項
|
||
|
||
- **MCP サーバー**: MCP prompts から各種テンプレートを取得するため、MCP サーバーが起動している必要があります
|
||
- テンプレートは `general/issue-templates/*.template.md` に保存されていますが、実行時は MCP 経由でアクセスします
|
||
- 利用可能な prompts: `implementation-plan-template`, `epic-template`, `feature-template`, `migration-template`, `test-template`, `docs-template`, `chore-template`
|
||
- **ラベル**: リポジトリに存在するラベルのみ指定可能
|
||
- **マイルストーン**: 事前に作成しておく必要がある
|
||
- **担当者**: GitHub アカウント名で指定（例: `@username`）
|
||
|
||
## トラブルシューティング
|
||
|
||
### `gh` CLI が認証されていない
|
||
|
||
```sh
|
||
gh auth login
|
||
```
|
||
|
||
### ラベルが存在しない
|
||
|
||
```sh
|
||
# ラベルを作成
|
||
gh label create "type:feature" --color "0E8A16" --description "New feature"
|
||
gh label create "type:migration" --color "FBCA04" --description "Migration task"
|
||
gh label create "type:test" --color "D93F0B" --description "Testing"
|
||
gh label create "type:docs" --color "0075CA" --description "Documentation"
|
||
```
|
||
|
||
または、`scripts/create-github-labels.sh` を実行してください。
|
||
|
||
### MCP サーバーが起動していない
|
||
|
||
MCP サーバーの起動状態を確認し、必要に応じて再起動してください。
|
||
|
||
## 完了チェックリスト
|
||
|
||
- [ ] MCP ツール `get_implementation_plan_to_issues` で Issue 作成ガイドラインを読み込んだ
|
||
- [ ] MCP prompts から必要なテンプレートを読み込んだ
|
||
- [ ] 実装計画ドキュメントを解析した
|
||
- [ ] Epic Issue が作成された
|
||
- [ ] サブ Issue のチェックリストが揃っている
|
||
- [ ] ラベル/マイルストーンが適切に設定されている
|
||
- [ ] （オプション）子 Issue が作成された、または UI での作成手順が案内された
|
||
|
||
## Notes
|
||
|
||
- **MCP Tools**: 実行前に MCP サーバーが起動していることを確認してください
|
||
- `get_implementation_plan_to_issues`: Issue 作成ガイドラインを取得する専用ツール
|
||
- **MCP Prompts**: 各種テンプレートは MCP prompts から取得します
|
||
- **GitHub CLI**: `gh auth status` で認証状態を確認してください
|
||
- **テンプレート**: ワークスペースの `general/issue-templates/` にテンプレートファイルが存在します
|
||
- **推奨運用**: Epic 作成後、GitHub UI で「Convert to sub-issues」を使用すると親子リンクが自動設定されます
|
||
|
||
## 関連ドキュメント
|
||
|
||
- `general/implementation-plan-template.md`: 実装計画テンプレート
|
||
- `general/implementation-plan-to-issues.md`: Issue 作成の詳細ガイド
|
||
- `general/issue-templates/*.template.md`: Issue テンプレート集
|
||
- `scripts/create-github-labels.sh`: ラベル作成スクリプト
|