shibryo Create Issue
タスクまたはバグを、追跡可能なIssueとして作成する。
Issue作成時点では、作業を見失わないために必要な事実を記録する。詳細な調査や実装設計は行わず、後からIssueを磨ける状態にする。
原則
- Issueの種類は
taskまたはbugとする - 確認できた事実と推測を区別する
- 不明な情報を推測で補わない
- 実装方法を早期に固定しない
- 完了を確認できる条件を書く
- プロジェクト固有の規約を標準より優先する
- Issueの保存先に依存しない
手順
1. プロジェクトの規約を確認する
次の順序で適用する。
- ユーザーからの明示的な指示
- プロジェクトに含まれるIssue関連の規約
- Issue管理先に用意されたテンプレート
- このSkillの標準
確認対象には、プロジェクトの指示ファイル、既存Issue、Issueテンプレート、ラベル規約を含める。
既存の規約がない場合、このSkillの標準を使用する。
2. Issueの種類を決める
次の基準で分類する。
task
予定している変更または作業を表す。
例:
- 機能追加
- 既存機能の改善
- リファクタリング
- ドキュメント更新
- 依存関係の更新
- 運用作業
bug
期待する振る舞いと実際の振る舞いの差異を表す。
例:
- 機能が期待どおり動作しない
- 回帰が発生している
- テストが継続的に失敗する
- テスト結果が不安定になる
種類を判断できない場合は、期待する振る舞いが既に存在するかを確認する。
既存の期待を満たしていない場合は bug、新しい状態を実現する場合は task とする。
それでも判断できない場合は、作成前にユーザーへ確認する。
3. 必要な情報を集める
Issueの種類に応じて、作成に必要な情報を集める。
コードベース、既存Issue、関連ドキュメントから短時間で確認できる事実は確認する。ただし、原因調査、詳細設計、広範な実験までは行わない。
不足している情報のうち、Issueの意味を左右するものだけをユーザーへ質問する。
確認できない情報は、省略するか未確認であることを明示する。
4. タイトルを書く
タイトルだけで対象と事象が識別できるようにする。
task のタイトルは、実現したい結果を書く。
bug のタイトルは、期待と異なる事象を書く。
実装方法、原因が未確認の断定、曖昧な表現をタイトルに含めない。
悪い例:
- 修正する
- 対応する
- APIを変更する
- キャッシュが原因でログインできない
良い例:
- 無効化されたユーザーを一覧から除外できるようにする
- セッション更新後にログイン状態が失われる
5. 本文を書く
プロジェクト固有のテンプレートがない場合、次の形式を使用する。
task
## 目的
{この作業によって実現したい状態}
## 背景
{現在の状態と、この作業が必要になった理由}
## 完了条件
- [ ] {結果を確認できる条件}
対象範囲や制約が明確になっている場合は、必要な情報だけを追加する。
空の見出しや、内容のない定型文は追加しない。
bug
## 発生したこと
{実際に確認された振る舞い}
## 期待する振る舞い
{本来期待される振る舞い}
## 再現方法
1. {再現手順}
## 環境
- {発生を確認したバージョンや実行環境}
## 補足
{ログ、スクリーンショット、関連Issueなどの証跡}
再現方法、環境、証跡が得られていない場合は、確認できていないことを明示する。
原因の仮説を書く場合は、確認済みの事実とは分けて記載する。
6. 保存先を決める
ユーザーまたはプロジェクトが指定したIssue管理先を使用する。
保存先の例:
- GitHub Issues
- GitLab Issues
- リポジトリ内のIssueファイル
- その他のIssue管理システム
保存先を一意に判断できない場合は、Issueを作成せず、本文案を提示して保存先を確認する。
保存先固有のラベル、担当者、マイルストーンは、既存の規約または明示的な指示がある場合だけ設定する。
存在しないラベルや分類を独自に作成しない。
7. Issueを作成して確認する
ユーザーがIssueの作成を依頼し、保存先が確定している場合はIssueを作成する。
作成後にIssueを読み直し、次を確認する。
- タイトルと本文が意図どおり保存されている
- Issueの種類が正しい
- 指定されたメタデータが反映されている
- 本文が保存先固有の記法で崩れていない
最後に、作成したIssueのURLまたはパスと種類を報告する。
ユーザーが下書きだけを求めた場合は、Issueを作成しない。
カスタマイズ
プロジェクトは次の項目を変更または追加できる。
- Issueの保存先
taskとbugに対応するラベル- 必須項目
- 本文の見出し
- タイトル規約
- 担当者やマイルストーンの設定方法
- 使用する言語
保存先固有の分類が存在する場合も、このSkillでは意味上の種類を task または bug として扱う。