Appearance
4. Issue を作成する
概要
「残席が少ないイベントを分かりやすくする」という要望を、実装作業の基準となる Issue にします。
Issue に変更の背景と完了条件を記録すると、実装担当者とレビュー担当者が「なぜ変更するのか」「どの状態になれば完了か」を共有できます。実装前に境界値や期待する表示を明確にすることで、認識のずれや確認漏れを減らせます。
このハンズオンでは、残席が0席、1〜3席、4席以上の場合に期待する表示と、テスト・ビルドの成功を完了条件として記載します。作成した Issue 番号は、後続のブランチ名や Pull Request でも使用します。
手順
1. Issue の内容を確認する
.github/ISSUE_TEMPLATE/change-request.md を開き、背景と完了条件を確認します。
2. Issue を作成する
確認した背景と5つの完了条件を GitHub Issue に記録し、実装とレビューの基準として共有できる状態にします。
Agent モードで以下の指示を与えます。
text
既存の AGENTS.md と git-workflow Skill のガードレールに従ってください。
.github/ISSUE_TEMPLATE/change-request.md と現在の GitHub リポジトリを確認してください。
タイトルを「残席が少ないイベントを分かりやすくする」とし、背景と、テンプレートに沿った5つの完了条件を含む Issue の作成案を示してください。
作成先リポジトリ、タイトル、本文、外部へ公開される影響を要約し、askQuestions で明示的な承認を得るまで Issue を作成しないでください。対象不明や同じ Issue が既にある場合は作成せず質問してください。
承認後に1件だけ作成し、Issue の番号と URL を報告してください。次を確認します。
- 作成先、タイトル、背景、5つの完了条件が意図した内容である
- 外部へ公開される影響を確認して明示的に承認するまで Issue が作成されていない
- 同じ Issue が既にある場合は重複して作成されていない
- 承認後に1件だけ作成され、Issue 番号と URL が報告されている
powershell
# Issue の本文をヒアストリングとして変数へ保存します
$body = @"
## 背景
空席が3席以下のイベントを見逃さないように、残席表示を強調したい。
## 完了条件
- [ ] 空席が1〜3席の場合は ``残席わずか（残り N 席）`` と表示される
- [ ] 空席が4席以上の場合は ``残り N 席`` と表示される
- [ ] 空席が0席の場合は ``満席`` と表示される
- [ ] 境界値を確認する Vitest のテストが成功する
- [ ] Vite のビルドが成功する
"@
# タイトルと本文を指定して Issue を作成し、その URL を保存します
$issueUrl = gh issue create --title "残席が少ないイベントを分かりやすくする" --body $body
# 作成した Issue の URL を表示します
$issueUrlbash
# Issue の本文を heredoc で変数へ保存します
body=$(cat <<'EOF'
## 背景
空席が3席以下のイベントを見逃さないように、残席表示を強調したい。
## 完了条件
- [ ] 空席が1〜3席の場合は `残席わずか（残り N 席）` と表示される
- [ ] 空席が4席以上の場合は `残り N 席` と表示される
- [ ] 空席が0席の場合は `満席` と表示される
- [ ] 境界値を確認する Vitest のテストが成功する
- [ ] Vite のビルドが成功する
EOF
)
# タイトルと本文を指定して Issue を作成し、その URL を保存します
issue_url=$(gh issue create --title "残席が少ないイベントを分かりやすくする" --body "$body")
# 作成した Issue の URL を表示します
printf '%s\n' "$issue_url"- GitHub で演習用リポジトリを開き、Issues を選択します。
- New issue を選択します。
- テンプレートの 小規模な変更 を選択します。テンプレートが表示されない場合は Blank issue を選択し、
change-request.mdに記載の内容を記載します。- タイトル:「残席が少ないイベントを分かりやすくする」と入力します。
- 本文: テンプレートに沿って背景と5つの完了条件を入力します。
- Submit new issue を選択します。
3. Issue 番号を記録する
作成した Issue の番号と URL を取得し、後続のブランチ名や参照先に使用できるよう記録します。
Agent モードで以下の指示を与えます。
text
現在の GitHub リポジトリで、未完了かつタイトルが「残席が少ないイベントを分かりやすくする」と一致する Issue を読み取り専用で検索してください。
一致する Issue が1件なら番号と URL を表示してください。0件または複数件なら推測せず、候補を示して質問してください。Issue の作成や編集は行わないでください。次を確認します。
- 未完了でタイトルが一致する Issue が1件だけ特定されている
- Issue 番号と URL が報告されている
- 0件または複数件の場合は候補が示され、推測されていない
- Issue の作成や編集が行われていない
powershell
# 未完了 Issue の番号、タイトル、URL を取得します
$issues = gh issue list --state open --limit 100 --json number,title,url |
ConvertFrom-Json
# 演習で作成したタイトルと一致する Issue を1件選びます
$issue = $issues |
Where-Object { $_.title -eq "残席が少ないイベントを分かりやすくする" } |
Select-Object -First 1
# 選択した Issue の URL を変数へ保存します
$issueUrl = $issue.url
# 選択した Issue の番号を変数へ保存します
$issueNumber = $issue.number
# Issue 番号を表示します
$issueNumberbash
# 演習で作成したタイトルと一致する未完了 Issue の URL を取得します
issue_url=$(gh issue list --state open --limit 100 --json title,url \
--jq '.[] | select(.title == "残席が少ないイベントを分かりやすくする") | .url' |
head -n 1)
# 演習で作成したタイトルと一致する未完了 Issue の番号を取得します
issue_number=$(gh issue list --state open --limit 100 --json number,title \
--jq '.[] | select(.title == "残席が少ないイベントを分かりやすくする") | .number' |
head -n 1)
# Issue 番号を表示します
printf '%s\n' "$issue_number"作成した Issue のタイトル横に表示される #1 のような番号を記録します。URL の末尾にある数値も Issue 番号です。
後続の記事では、この Issue 番号からブランチ名と参照先を組み立てます。ターミナルを開き直した場合も、GitHub から取得し直せます。
確認事項
- Issue が Open である
- Issue のタイトルが「残席が少ないイベントを分かりやすくする」である
- Issue に背景と5つの完了条件が保存されている
- 後続の記事で使う Issue 番号と URL が記録されている
まとめ
Issue に変更の背景と完了条件を記載し、実装を始める前に「なぜ変更するのか」と「何を満たせば完了なのか」を共有しました。今回の完了条件では、残席が0席、1〜3席、4席以上の場合を分けています。このように境界値を具体化すると、実装者とレビュー担当者が同じ基準で動作を確認できます。
Issue は単なる作業メモではなく、要望、実装、テスト、レビューを結び付ける基準になります。実装中に要件が変わった場合は、コードだけを変更せず、先に Issue の背景や完了条件を更新して認識をそろえます。
補足: 実務で役立つ Issue の書き方
- 背景には解決したい問題を記載し、実装方法を早い段階で決め過ぎないようにします。
- 完了条件は「正しく対応する」のような曖昧な表現を避け、第三者が確認できる結果として記載します。
- 1つの Issue で扱う変更を小さくすると、Pull Request のレビューや問題発生時の切り戻しが容易になります。
- 既定ブランチ向け Pull Request の本文に
Closes #<Issue番号>と記載すると、マージ時に Issue を自動で閉じ、要望から変更までの履歴をたどれます。既定ブランチ以外を向く Pull Request では、自動クローズされません。
補足: IssueOps で Issue を自動化の入口にする
IssueOps は特定の製品名ではなく、Issue の作成、編集、ラベル付与、コメントなどをきっかけに自動処理を実行する運用手法です。Issue を人と自動化の共通インターフェイスとして使うことで、依頼内容、実行状況、結果を1か所に残せます。
例えば、Issue Forms で必要な入力項目をそろえ、Issue の opened や labeled イベントで GitHub Actions を開始できます。Workflow から GitHub CLI や API を呼び出すと、ラベルの付与、担当者の設定、環境の準備、デプロイ要求の受け付けなどを自動化できます。
自動化では、入力値と実行者の権限を検証し、Workflow の permissions を必要最小限にします。Issue 本文の値を検証せずにシェルコマンドへ渡したり、承認なしで破壊的な処理を実行したりしないことが重要です。
参考資料:
次は、記録した Issue 番号をブランチ名や Pull Request に使用し、作業と目的を関連付けます。