---
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` ラベルを付けた