---
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 は日本語で統一し、一覧で意味が分かる名前を使います。

## 事前確認

1. `gh --version` で CLI が使えるか確認します。
2. `gh auth status` でログイン状態を確認します。
3. `git remote -v` で対象リポジトリが正しいか確認します。
4. 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

```md
## 概要

この issue の目的を書く。

## ゴール

- 到達したい状態

## スコープ

- この issue で扱う範囲

## スコープ外

- 今回は扱わない範囲

## 子 issue

- #123 ...
- #124 ...
```

### 子 issue

```md
## 背景

なぜ必要かを書く。

## やること

- 実施内容

## 完了条件

- 終わったと判断できる状態
```

必要なら次も追加します。

- `## 期待する状態`
- `## README に含めたい内容`
- `## 方針`

## gh での作成手順

1. issue 本文を先に固めます。
2. 子 issue を `gh issue create --title ... --body-file - <<'EOF' ... EOF` で作成します。
3. 作成された URL から issue 番号を確認します。
4. 子 issue 番号を埋め込んだ親 issue を最後に作成します。
5. 必要な label を付与します。
6. 最後に作成した issue 番号と URL を一覧で報告します。

複数 issue を作るときは、先に本文を決めてからまとめて作るとブレにくいです。

## label 運用

このリポジトリでは、label は日本語で統一し、次の軸で整理します。

- `種別: ...`
- `領域: ...`
- `優先度: ...`
- `状態: ...`

現時点の基本 label:

- `種別: 親issue`
- `種別: 環境整備`
- `領域: 環境構築`
- `領域: ドキュメント`
- `領域: Astro`
- `領域: Lint/Format`
- `優先度: 高`
- `状態: 着手可能`

### label の扱い

1. `gh label list` で既存 label を確認します。
2. 足りない label だけ `gh label create` で追加します。
3. 既存の英語 custom label がある場合は、必要に応じて `gh label edit --name` で日本語へ寄せます。
4. issue には意味のある label だけを付け、過剰に増やしません。

## 報告のしかた

最後は次を短く返します。

- 作成または更新した issue 番号
- 各 issue の役割
- 付与した label
- 次に着手すべき issue

## 安全策

- `gh` の認証や対象リポジトリが曖昧なまま issue を作りません。
- 依頼範囲が曖昧なら、実装に踏み込まず issue の粒度とゴールを先に整理します。
- ユーザーが求めていない issue を先回りで大量追加しません。
- 既存 label の意味を壊す rename は避け、影響がある場合は一言添えます。