337 lines
10 KiB
Markdown
337 lines
10 KiB
Markdown
---
|
||
name: issue-management-guidelines
|
||
description: Issue作成・分類・管理のガイドライン、テンプレート、ラベル運用、ライフサイクル管理を定義する。Issue作成時、バグ報告時、タスク管理時、またはユーザーがIssue、バグレポート、タスク管理、ラベル運用、Issueテンプレートに言及した際に使用する。
|
||
---
|
||
|
||
# Issue Management Guidelines
|
||
|
||
## 概要
|
||
|
||
このSkillは、Issueの作成、分類、管理に関するガイドラインを定義する。適切なIssue管理により、タスクの可視化、優先順位付け、進捗管理を効率的に行うことを目的とする。
|
||
|
||
## 責任範囲
|
||
|
||
このSkillは以下の範囲をカバーする:
|
||
|
||
- Issue作成時の記述ガイドライン（タイトル、本文、再現手順）
|
||
- Issueテンプレートの定義と使用方法
|
||
- Issueの分類とラベル運用ルール
|
||
- Issueのライフサイクル管理（作成、割り当て、進捗更新、クローズ）
|
||
- Issueのクローズ基準と完了条件
|
||
- IssueとPull Requestの関連付け方法
|
||
|
||
## 基本方針
|
||
|
||
- タイトルは簡潔で具体的にする
|
||
- 本文には必要十分な情報を記載する
|
||
- AI自動生成署名を記述しない
|
||
- 原則として英語で記述する（チームの主要言語が英語以外の場合はその言語の使用を許可）
|
||
- プロジェクトにテンプレートがある場合はそちらを優先的に使用する
|
||
- 適切なラベルを付けて分類する
|
||
- 担当者とマイルストーンを明確にする
|
||
- Issueの状態を最新に保つ
|
||
- 完了条件を明確にする
|
||
- 関連するIssueやPRを相互に参照する
|
||
|
||
## Issue作成ガイドライン
|
||
|
||
### タイトルの書き方
|
||
|
||
- 簡潔で具体的にする（50文字以内を推奨）
|
||
- 実装内容や問題の本質を端的に表現する
|
||
- プレフィックスを付けて種類を明示する（任意）
|
||
|
||
良い例:
|
||
|
||
```text
|
||
Implement user authentication feature
|
||
Improve product search performance
|
||
Fix email input issue on login screen
|
||
```
|
||
|
||
悪い例:
|
||
|
||
```text
|
||
修正
|
||
バグ
|
||
機能追加してほしい
|
||
エラーが出る
|
||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
```
|
||
|
||
### プレフィックスの使用（任意）
|
||
|
||
- プロジェクトで統一する場合は、以下のようなプレフィックスを使用する
|
||
|
||
```text
|
||
feat: 新機能の追加
|
||
fix: バグ修正
|
||
docs: ドキュメント更新
|
||
refactor: リファクタリング
|
||
test: テスト追加・修正
|
||
perf: パフォーマンス改善
|
||
chore: ビルドプロセス、ツール設定など
|
||
```
|
||
|
||
良い例:
|
||
|
||
```text
|
||
feat: ユーザープロフィール編集機能を追加
|
||
fix: ログイン時のセッションタイムアウト問題を修正
|
||
docs: API仕様書にエンドポイント説明を追加
|
||
```
|
||
|
||
### 本文の書き方
|
||
|
||
- 背景、目的、詳細を明確にする
|
||
- 再現手順（バグの場合）を記載する
|
||
- 期待する動作と実際の動作を記載する
|
||
- スクリーンショットやログを添付する
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
## 背景
|
||
ユーザーから商品検索が遅いという報告が複数件寄せられている。
|
||
|
||
## 現状の問題
|
||
商品検索に平均3秒かかっており、ユーザー体験を損なっている。
|
||
|
||
## 目的
|
||
検索クエリの最適化により、応答時間を1秒以内に短縮する。
|
||
|
||
## 詳細
|
||
- 検索対象: 商品名、カテゴリ、タグ
|
||
- データ件数: 約10万件
|
||
- 現在のクエリ: 全文検索をループ処理で実施
|
||
|
||
## 期待する改善内容
|
||
- データベースインデックスの追加
|
||
- クエリの最適化
|
||
- キャッシュの導入
|
||
```
|
||
|
||
バグ報告の場合:
|
||
|
||
```markdown
|
||
## 概要
|
||
ログイン画面でメールアドレスが入力できない。
|
||
|
||
## 再現手順
|
||
1. ログイン画面を開く
|
||
2. メールアドレス入力欄をクリックする
|
||
3. キーボードで入力を試みる
|
||
|
||
## 期待する動作
|
||
メールアドレスが入力できる。
|
||
|
||
## 実際の動作
|
||
入力欄がフォーカスされず、キーボード入力が反映されない。
|
||
|
||
## 環境
|
||
- OS: Windows 11
|
||
- ブラウザ: Chrome 120.0
|
||
- デバイス: PC
|
||
|
||
## スクリーンショット
|
||
（添付）
|
||
```
|
||
|
||
### 完了条件の明記
|
||
|
||
- Issueをクローズする条件を明確にする
|
||
- 受け入れ基準（Acceptance Criteria）を記載する
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
## 完了条件
|
||
- [ ] 商品検索の応答時間が1秒以内になる
|
||
- [ ] 既存の検索機能が正常に動作する
|
||
- [ ] テストケースが追加される
|
||
- [ ] パフォーマンステストに合格する
|
||
```
|
||
|
||
## Issueテンプレート
|
||
|
||
### テンプレートの種類
|
||
|
||
プロジェクトで以下のテンプレートを用意する:
|
||
|
||
- **Bug Report（バグ報告）**: バグや不具合を報告する際に使用
|
||
- **Feature Request（機能要望）**: 新機能の提案や機能改善を要望する際に使用
|
||
- **Task（タスク）**: 開発タスクや作業項目を記録する際に使用
|
||
|
||
### テンプレートの配置
|
||
|
||
- GitHubの場合: `.github/ISSUE_TEMPLATE/` ディレクトリに配置
|
||
- GitLabの場合: `.gitlab/issue_templates/` ディレクトリに配置
|
||
- このSkillの `templates/` ディレクトリにマスターテンプレートを保管
|
||
|
||
### テンプレートの使用方法
|
||
|
||
- Issue作成時に適切なテンプレートを選択する
|
||
- テンプレートの各項目を埋める
|
||
- 不要な項目は削除するか、N/Aと記載する
|
||
|
||
## Issueの分類とラベル
|
||
|
||
### ラベルの種類
|
||
|
||
以下のカテゴリでラベルを付与する:
|
||
|
||
**タイプ（Type）**:
|
||
|
||
- `bug`: バグ、不具合
|
||
- `enhancement`: 機能改善
|
||
- `feature`: 新機能
|
||
- `documentation`: ドキュメント関連
|
||
- `refactoring`: リファクタリング
|
||
- `test`: テスト関連
|
||
- `chore`: 雑務、ビルド設定など
|
||
|
||
**優先度（Priority）**:
|
||
|
||
- `priority: critical`: 緊急対応が必要
|
||
- `priority: high`: 高優先度
|
||
- `priority: medium`: 中優先度
|
||
- `priority: low`: 低優先度
|
||
|
||
**ステータス（Status）**:
|
||
|
||
- `status: blocked`: ブロックされている
|
||
- `status: in progress`: 作業中
|
||
- `status: review`: レビュー待ち
|
||
- `status: ready`: 着手可能
|
||
|
||
**その他**:
|
||
|
||
- `good first issue`: 初心者向けのIssue
|
||
- `help wanted`: 協力者を募集
|
||
- `duplicate`: 重複
|
||
- `wontfix`: 対応しない
|
||
- `invalid`: 無効
|
||
|
||
### ラベルの付け方
|
||
|
||
- 必ず1つ以上のタイプラベルを付ける
|
||
- 優先度ラベルを付ける（必須ではないが推奨）
|
||
- 必要に応じてステータスラベルを付ける
|
||
|
||
良い例:
|
||
|
||
```text
|
||
ラベル: bug, priority: high, status: in progress
|
||
```
|
||
|
||
## Issueのライフサイクル管理
|
||
|
||
### Issueの作成
|
||
|
||
- 適切なテンプレートを選択する
|
||
- タイトルと本文を記載する
|
||
- ラベルを付ける
|
||
- 担当者を割り当てる（決まっている場合）
|
||
- マイルストーンを設定する（該当する場合）
|
||
|
||
### Issueの割り当て
|
||
|
||
- 担当者が決まったら、Assigneeに設定する
|
||
- 複数人で作業する場合は、全員をAssigneeに追加する
|
||
- 担当者が決まっていない場合は、ラベル `help wanted` を付ける
|
||
|
||
### Issueの進捗更新
|
||
|
||
- 作業開始時に `status: in progress` ラベルを付ける
|
||
- ブロックされている場合は `status: blocked` ラベルを付け、コメントで理由を説明する
|
||
- 進捗があればコメントで報告する
|
||
- 関連するPRを作成したら、IssueとPRを相互に参照する
|
||
|
||
### IssueとPull Requestの関連付け
|
||
|
||
- PR作成時に、Issue番号を参照する
|
||
- PRの説明欄に `Closes #123` や `Fixes #123` と記載すると、PRマージ時に自動的にIssueがクローズされる
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
## 概要
|
||
ユーザー認証機能を実装しました。
|
||
|
||
Closes #45
|
||
```
|
||
|
||
### Issueのクローズ
|
||
|
||
- 完了条件をすべて満たしたらIssueをクローズする
|
||
- クローズ時にコメントで完了内容を簡潔に記載する
|
||
- 対応しない場合は、理由をコメントで説明し、`wontfix` ラベルを付けてクローズする
|
||
|
||
良い例:
|
||
|
||
```markdown
|
||
すべての完了条件を満たしたため、クローズします。
|
||
|
||
- 商品検索の応答時間: 0.8秒
|
||
- 既存機能のテスト: 合格
|
||
- パフォーマンステスト: 合格
|
||
```
|
||
|
||
対応しない場合:
|
||
|
||
```markdown
|
||
この機能は現在のスコープ外であり、将来的な検討課題とします。
|
||
|
||
`wontfix` ラベルを付けてクローズします。
|
||
```
|
||
|
||
## Issueのクローズ基準
|
||
|
||
### バグ修正の場合
|
||
|
||
- [ ] バグが修正され、再現しなくなった
|
||
- [ ] 修正内容がテストされた
|
||
- [ ] 関連するテストケースが追加された
|
||
- [ ] PRがマージされた
|
||
|
||
### 機能追加の場合
|
||
|
||
- [ ] 機能が実装され、動作確認された
|
||
- [ ] テストケースが追加された
|
||
- [ ] ドキュメントが更新された
|
||
- [ ] PRがマージされた
|
||
|
||
### タスクの場合
|
||
|
||
- [ ] タスクが完了した
|
||
- [ ] 成果物が確認された
|
||
- [ ] 関連する作業がすべて完了した
|
||
|
||
## チェックリスト
|
||
|
||
### Issue作成時
|
||
|
||
- [ ] タイトルが簡潔で具体的である
|
||
- [ ] 本文に必要十分な情報が記載されている
|
||
- [ ] 英語で記述している（チームの主要言語が英語以外の場合はその言語でOK）
|
||
- [ ] AI自動生成署名を含めていない
|
||
- [ ] 適切なテンプレートを使用している（プロジェクトにテンプレートがある場合はそちらを優先）
|
||
- [ ] ラベルが付けられている（最低1つ）
|
||
- [ ] 完了条件が明記されている
|
||
- [ ] 担当者が割り当てられている（決まっている場合）
|
||
- [ ] マイルストーンが設定されている（該当する場合）
|
||
|
||
### Issue作業中
|
||
|
||
- [ ] 作業開始時に `status: in progress` ラベルを付けた
|
||
- [ ] ブロックされている場合は `status: blocked` ラベルを付け、理由をコメントした
|
||
- [ ] 進捗があればコメントで報告した
|
||
- [ ] 関連するPRを作成し、IssueとPRを相互に参照した
|
||
|
||
### Issueクローズ時
|
||
|
||
- [ ] 完了条件がすべて満たされている
|
||
- [ ] クローズ時にコメントで完了内容を記載した
|
||
- [ ] 対応しない場合は、理由を説明し `wontfix` ラベルを付けた
|
||
- [ ] 重複の場合は、元のIssueを参照し `duplicate` ラベルを付けた
|