Issue Management Guidelines

Issue Management Guidelines

概要

このSkillは、Issueの作成、分類、管理に関するガイドラインを定義する。適切なIssue管理により、タスクの可視化、優先順位付け、進捗管理を効率的に行うことを目的とする。

責任範囲

このSkillは以下の範囲をカバーする:

• Issue作成時の記述ガイドライン（タイトル、本文、再現手順）
• Issueテンプレートの定義と使用方法
• Issueの分類とラベル運用ルール
• Issueのライフサイクル管理（作成、割り当て、進捗更新、クローズ）
• Issueのクローズ基準と完了条件
• IssueとPull Requestの関連付け方法

基本方針

• タイトルは簡潔で具体的にする
• 本文には必要十分な情報を記載する
• AI自動生成署名を記述しない
• 原則として英語で記述する（チームの主要言語が英語以外の場合はその言語の使用を許可）
• プロジェクトにテンプレートがある場合はそちらを優先的に使用する
• 適切なラベルを付けて分類する
• 担当者とマイルストーンを明確にする
• Issueの状態を最新に保つ
• 完了条件を明確にする
• 関連するIssueやPRを相互に参照する

Issue作成ガイドライン

タイトルの書き方

• 簡潔で具体的にする（50文字以内を推奨）
• 実装内容や問題の本質を端的に表現する
• プレフィックスを付けて種類を明示する（任意）

良い例:

Implement user authentication feature
Improve product search performance
Fix email input issue on login screen

悪い例:

修正
バグ
機能追加してほしい
エラーが出る
🤖 Generated with [Claude Code](https://claude.com/​claude-code)

プレフィックスの使用（任意）

• プロジェクトで統一する場合は、以下のようなプレフィックスを使用する

feat: 新機能の追加
fix: バグ修正
docs: ドキュメント更新
refactor: リファクタリング
test: テスト追加・修正
perf: パフォーマンス改善
chore: ビルドプロセス、ツール設定など

良い例:

feat: ユーザープロフィール編集機能を追加
fix: ログイン時のセッションタイムアウト問題を修正
docs: API仕様書にエンドポイント説明を追加

本文の書き方

• 背景、目的、詳細を明確にする
• 再現手順（バグの場合）を記載する
• 期待する動作と実際の動作を記載する
• スクリーンショットやログを添付する

良い例:

## 背景
ユーザーから商品検索が遅いという報告が複数件寄せられている。

## 現状の問題
商品検索に平均3秒かかっており、ユーザー体験を損なっている。

## 目的
検索クエリの最適化により、応答時間を1秒以内に短縮する。

## 詳細
- 検索対象: 商品名、カテゴリ、タグ
- データ件数: 約10万件
- 現在のクエリ: 全文検索をループ処理で実施

## 期待する改善内容
- データベースインデックスの追加
- クエリの最適化
- キャッシュの導入

バグ報告の場合:

## 概要
ログイン画面でメールアドレスが入力できない。

## 再現手順
1. ログイン画面を開く
2. メールアドレス入力欄をクリックする
3. キーボードで入力を試みる

## 期待する動作
メールアドレスが入力できる。

## 実際の動作
入力欄がフォーカスされず、キーボード入力が反映されない。

## 環境
- OS: Windows 11
- ブラウザ: Chrome 120.0
- デバイス: PC

## スクリーンショット
（添付）

完了条件の明記

• Issueをクローズする条件を明確にする
• 受け入れ基準（Acceptance Criteria）を記載する

良い例:

## 完了条件
- [ ] 商品検索の応答時間が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つ以上のタイプラベルを付ける
• 優先度ラベルを付ける（必須ではないが推奨）
• 必要に応じてステータスラベルを付ける

良い例:

ラベル: 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がクローズされる

良い例:

## 概要
ユーザー認証機能を実装しました。

Closes #45

Issueのクローズ

• 完了条件をすべて満たしたらIssueをクローズする
• クローズ時にコメントで完了内容を簡潔に記載する
• 対応しない場合は、理由をコメントで説明し、wontfix ラベルを付けてクローズする

良い例:

すべての完了条件を満たしたため、クローズします。

- 商品検索の応答時間: 0.8秒
- 既存機能のテスト: 合格
- パフォーマンステスト: 合格

対応しない場合:

この機能は現在のスコープ外であり、将来的な検討課題とします。

`wontfix` ラベルを付けてクローズします。

Issueのクローズ基準

バグ修正の場合

• バグが修正され、再現しなくなった
• 修正内容がテストされた
• 関連するテストケースが追加された
• PRがマージされた

機能追加の場合

• 機能が実装され、動作確認された
• テストケースが追加された
• ドキュメントが更新された
• PRがマージされた

タスクの場合

• タスクが完了した
• 成果物が確認された
• 関連する作業がすべて完了した

チェックリスト

Issue作成時

• タイトルが簡潔で具体的である
• 本文に必要十分な情報が記載されている
• 英語で記述している（チームの主要言語が英語以外の場合はその言語でOK）
• AI自動生成署名を含めていない
• 適切なテンプレートを使用している（プロジェクトにテンプレートがある場合はそちらを優先）
• ラベルが付けられている（最低1つ）
• 完了条件が明記されている
• 担当者が割り当てられている（決まっている場合）
• マイルストーンが設定されている（該当する場合）

Issue作業中

• 作業開始時に status: in progress ラベルを付けた
• ブロックされている場合は status: blocked ラベルを付け、理由をコメントした
• 進捗があればコメントで報告した
• 関連するPRを作成し、IssueとPRを相互に参照した

Issueクローズ時

• 完了条件がすべて満たされている
• クローズ時にコメントで完了内容を記載した
• 対応しない場合は、理由を説明し wontfix ラベルを付けた
• 重複の場合は、元のIssueを参照し duplicate ラベルを付けた