name: github-issue-workflow description: GitHub issue の切り分け、本文作成、gh コマンドでの issue 作成、親子 issue の整理、日本語 label の運用をこのリポジトリ向けに進めるスキルです。タスクを見やすい issue に整理したいときや、既存 issue に分かりやすい label を付けたいときに使います。
GitHub Issue ワークフロー
ユーザーが GitHub issue を作りたい、タスクを issue に切り分けたい、gh コマンドでまとめて issue を作ってほしい、label を整理したいと言ったときに使います。
このリポジトリでは、issue を「後で見返しても迷わないこと」を優先して作ります。作業の進めやすさを重視し、タイトル、本文、label の意味が一覧で伝わる状態を目指します。
基本方針
- いきなり issue を量産せず、先にゴールとスコープを短く整理します。
- 1つの大きい依頼は、必要に応じて親 issue と子 issue に分けます。
- 子 issue の番号を親 issue 本文に入れたいので、複数作る場合は子 issue を先に作ります。
- issue 本文は見出しをそろえ、完了条件を必ず書きます。
- label は日本語で統一し、一覧で意味が分かる名前を使います。
事前確認
gh --versionで CLI が使えるか確認します。gh auth statusでログイン状態を確認します。git remote -vで対象リポジトリが正しいか確認します。- issue 化の判断に必要な最小限のファイルだけ読みます。基本は
AGENTS.md、README.md、package.json、関連するmemos/を優先します。
issue の切り方
単発タスク
単独で完結する作業なら issue は 1 本で十分です。本文は少なくとも次の見出しを入れます。
## 背景## やること## 完了条件
複数タスク
まとまりのある複数タスクなら、親 issue 1 本と子 issue 複数本に分けます。
- 親 issue は目的、ゴール、スコープ、スコープ外、子 issue の導線を書く
- 子 issue は実作業単位に切る
- 子 issue は 1 issue 1 成果物を基本にする
環境構築のような広い依頼では、次の粒度を優先します。
- ドキュメント整備
- フレームワークやビルド基盤の整備
- lint / format / check などの検証基盤整備
タイトルの付け方
- タイトルは短く、一覧で意味が分かるものにします。
- 変更の種類が分かる接頭辞を必要に応じて使います。例:
epic:,chore:,feat:,fix:,docs: - ただし本文で十分に伝わる場合は、接頭辞の乱用は避けます。
- 同階層の issue はタイトルのトーンをそろえます。
例:
epic: 環境構築を完了して実装開始できる状態にするchore: 開発前提とセットアップ手順を整備するchore: Astro の確認コマンドとチェック基盤を整える
本文テンプレート
親 issue
## 概要
この issue の目的を書く。
## ゴール
- 到達したい状態
## スコープ
- この issue で扱う範囲
## スコープ外
- 今回は扱わない範囲
## 子 issue
- #123 ...
- #124 ...
子 issue
## 背景
なぜ必要かを書く。
## やること
- 実施内容
## 完了条件
- 終わったと判断できる状態
必要なら次も追加します。
## 期待する状態## README に含めたい内容## 方針
gh での作成手順
- issue 本文を先に固めます。
- 子 issue を
gh issue create --title ... --body-file - <<'EOF' ... EOFで作成します。 - 作成された URL から issue 番号を確認します。
- 子 issue 番号を埋め込んだ親 issue を最後に作成します。
- 必要な label を付与します。
- 最後に作成した issue 番号と URL を一覧で報告します。
複数 issue を作るときは、先に本文を決めてからまとめて作るとブレにくいです。
label 運用
このリポジトリでは、label は日本語で統一し、次の軸で整理します。
種別: ...領域: ...優先度: ...状態: ...
現時点の基本 label:
種別: 親issue種別: 環境整備領域: 環境構築領域: ドキュメント領域: Astro領域: Lint/Format優先度: 高状態: 着手可能
label の扱い
gh label listで既存 label を確認します。- 足りない label だけ
gh label createで追加します。 - 既存の英語 custom label がある場合は、必要に応じて
gh label edit --nameで日本語へ寄せます。 - issue には意味のある label だけを付け、過剰に増やしません。
報告のしかた
最後は次を短く返します。
- 作成または更新した issue 番号
- 各 issue の役割
- 付与した label
- 次に着手すべき issue
安全策
ghの認証や対象リポジトリが曖昧なまま issue を作りません。- 依頼範囲が曖昧なら、実装に踏み込まず issue の粒度とゴールを先に整理します。
- ユーザーが求めていない issue を先回りで大量追加しません。
- 既存 label の意味を壊す rename は避け、影響がある場合は一言添えます。