create-issue

Create Issue with Spec

GitHub Issue と docs/issues/issue-<N>/spec.md を同時に作成し、両者をリンクする SDD(Spec-Driven Development)向けのスキル。

後続の実装エージェントが spec.md を読むだけで何を作るべきか理解できる状態を作る、という設計思想。

---

付属スクリプト

ルーチンなコマンドは付属シェルスクリプトに切り出してある。Claude はこれらを呼び出すだけでよい。

プラグインとしてインストールされると、スクリプトは ${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/ 配下に展開される。SKILL.md 内に書かれた ${CLAUDE_PLUGIN_ROOT} は Claude Code のインライン置換で絶対パスに置き換わってから Bash tool に渡される(このトークンに bash の parameter expansion %/ 等を加えると置換エンジンにマッチしなくなり、空文字展開で失敗するので、素の ${CLAUDE_PLUGIN_ROOT} のまま使うこと)。末尾スラッシュ付きで展開されて // が入ることがあるが Unix では無害。作業ディレクトリ(cwd)はユーザーのプロジェクトのままで OK。

スクリプト	役割	使い方
check-prereqs.sh	環境の前提チェック	bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/check-prereqs.sh"
create-issue.sh	Issue 作成 + 番号取得	bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/create-issue.sh" "<タイトル>" [ラベル]
repo-info.sh	リポジトリ情報を JSON で取得	bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/repo-info.sh"
update-issue.sh	Issue 本文を更新	bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/update-issue.sh" <番号> <本文ファイル>
commit-spec.sh	spec ディレクトリをコミット	bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/commit-spec.sh" <番号>

---

ワークフロー

ステップ 1: 前提チェック

bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/check-prereqs.sh"

エラー終了した場合は内容をユーザーに報告して中断する。WARN: が出た場合(作業ツリーに未コミットの変更がある等)は、続行してよいかユーザーに確認する。

ステップ 2: Issue の内容を固める

ユーザーの指示から以下を抽出・確認する:

• タイトル: 一文で簡潔に、40 文字以内が目安
• 概要: 何を実現するかの 1-2 文
• 受け入れ条件: Definition of Done(客観的に検証可能な粒度で)
• ラベル: 任意(feature, bug, refactor, docs など。リポジトリに存在するものに限る)

情報が不足している場合は最小限の質問で埋める。十分な情報があればそのまま進む。

粒度チェック: このIssueは半日〜1日で実装できる規模か? 大きすぎる場合は分割をユーザーに提案する。

TODOリストから作成する場合: ユーザーが「docs/todo.md の X をIssueにして」のように指示したら、該当ファイルを読んで項目を特定してから進める。

ステップ 3: Issue を作成して番号を取得

ISSUE_NUM=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/create-issue.sh" "<タイトル>" "<ラベル>")
# ラベル不要なら第2引数を省略:
# ISSUE_NUM=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/create-issue.sh" "<タイトル>")

この時点では Issue 本文はプレースホルダ。本文はステップ 5 で更新する。

ステップ 4: spec ディレクトリと spec.md を作成

SPEC_DIR="docs/issues/issue-${ISSUE_NUM}"
mkdir -p "$SPEC_DIR"

既存ディレクトリがある場合: ${SPEC_DIR} がすでに存在する場合は、ユーザーに確認してから上書きするか別対応する。黙って上書きしない。

${SPEC_DIR}/spec.md を、下の「spec.md テンプレート」に沿って作成する。必須セクションは「概要」と「受け入れ条件」、他は任意。

タイトル行 # Issue #<番号>: <タイトル> は、ステップ 3 で取得した実際の番号とタイトルに置き換える。

ステップ 5: Issue 本文を正式版に更新

まず、リポジトリ情報から spec.md への絶対 URL を組み立てる:

REPO_INFO=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/repo-info.sh")
REPO_FULL=$(echo "$REPO_INFO" | jq -r .nameWithOwner)
DEFAULT_BRANCH=$(echo "$REPO_INFO" | jq -r .defaultBranch)
SPEC_URL="https://github.com/${REPO_FULL}/blob/${DEFAULT_BRANCH}/${SPEC_DIR}/spec.md"

次に、Issue 本文を一時ファイルに書き出して update-issue.sh で適用する:

BODY_FILE=$(mktemp)
cat > "$BODY_FILE" <<EOF
## 概要

<1-2 文の概要>

## 詳細仕様

詳細は [\`${SPEC_DIR}/spec.md\`](${SPEC_URL}) を参照。

## 受け入れ条件

- [ ] <条件1>
- [ ] <条件2>
EOF

bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/update-issue.sh" "$ISSUE_NUM" "$BODY_FILE"
rm -f "$BODY_FILE"

Issue 本文は GitHub UI で読める最小限に留め、詳細は spec.md に任せる。受け入れ条件のチェックボックスを Issue 側にも残すと、UI でクリックして進捗を追えるので便利。

ステップ 6: コミット

bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/commit-spec.sh" "$ISSUE_NUM"

push はスクリプトに含まれていない。ユーザーが明示的に「push まで」と言っている場合、または直プッシュ運用を確認済みの場合のみ、別途 git push する。

ステップ 7: 結果を報告

以下をユーザーに報告する:

• 作成された Issue の番号と URL
• 作成された spec.md のパス
• コミットハッシュ
• push したかどうか

---

spec.md テンプレート

以下をベースに Issue の内容に応じて使う。「概要」と「受け入れ条件」は必須、他は任意。

# Issue #<番号>: <タイトル>

## 概要

<このIssueで何を実現するのか、1-2 文で>

## 背景・目的

<なぜこれが必要か、現状の課題、解決したいこと>

## 受け入れ条件

- [ ] <満たすべき条件1。客観的に検証可能な粒度で>
- [ ] <満たすべき条件2>
- [ ] <...>

## 技術的メモ

- 関連ファイル: `path/to/file.ts`, `path/to/another.ts`
- 使用するライブラリ: <あれば>
- 設計方針・制約: <あれば>

## 対象外 (Out of Scope)

- <このIssueでは扱わないこと>

## 参考

- <関連する過去のIssue、ドキュメント、外部リンクなど>

テンプレート使用の原則

• 受け入れ条件の質: 「動くこと」ではなく「X したときに Y になること」の形で書く。後でテストに 1:1 で対応づけやすくする。
• 技術的メモの役割: 実装エージェントへのヒント。該当ファイルパスを示すだけでも実装時の探索コストが大きく下がる。
• 対象外セクションの使い所: スコープが曖昧になりそうな場合に積極的に使う。「認証は既存のものを使い、このIssueでは変更しない」など。

---

例

例 1: 直接指示されたケース

ユーザー: 「ユーザー一覧画面にページネーションを追加する Issue を作って」

動き:

1. bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/check-prereqs.sh" で環境確認
2. ISSUE_NUM=$(bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/create-issue.sh" "ユーザー一覧にページネーションを追加" "feature")
3. docs/issues/issue-${ISSUE_NUM}/spec.md を作成。受け入れ条件に「1 ページあたり 20 件表示」「前後ページへのナビゲーションがある」「URL にページ番号が反映される」などを含める
4. repo-info.sh で URL を組み立て、本文を一時ファイルに書いて update-issue.sh で更新
5. bash "${CLAUDE_PLUGIN_ROOT}/skills/create-issue/scripts/commit-spec.sh" "$ISSUE_NUM"
6. Issue URL、spec.md パス、コミットハッシュを報告

例 2: TODO リストからのケース

ユーザー: 「docs/todo.md の『通知機能』を Issue にして」

動き:

1. docs/todo.md を読み、「通知機能」の該当箇所を特定
2. その記述をもとに Issue タイトルと spec 内容を組み立てる
3. 以降は例 1 と同じ流れ
4. 作業後、TODO リスト側で該当項目に Issue 番号(例: #42)を付記して更新することをユーザーに提案する(自動ではやらない)

---

注意点

• Issue 作成の取り消し: ステップ 3 で Issue 作成が成功した後、ステップ 4-6 のどこかで失敗した場合は、作成済みの Issue を gh issue close <番号> --reason "not planned" でクローズするか、ユーザーに手動対応を依頼する。中途半端な状態で黙って放置しない。
• ラベル: リポジトリに存在しないラベルを指定するとエラーになる。不明な場合は gh label list で確認してから使うか、ラベルなしで作成する。
• 複数 Issue の一括作成: ユーザーが「これらを全部 Issue にして」のように複数依頼した場合は、1 つずつ順番に処理する(番号の重複や依存関係確認のため)。
• ブランチ: このスキルは現在のブランチに対して spec.md をコミットする。SDD 運用上、spec はデフォルトブランチに直接コミットされる想定(実装 PR はこの後で別ブランチから作成される)。ユーザーが非デフォルトブランチにいる場合は、意図を確認する。
• jq の依存: ステップ 5 で repo-info.sh の出力をパースするのに jq を使う。未インストールの場合は、gh repo view --json nameWithOwner -q .nameWithOwner のように gh 組み込みの -q フラグを直接使う形に代替してよい。