implement-issue

Implement Issue from Spec

docs/issues/issue-<N>/spec.md を真実の源として、Issue を実装しブランチを切って PR を出すまでを一貫して行うスキル。

create-issue と対になる位置づけで、SDD(Spec-Driven Development)のサイクルを完結させる。

---

付属スクリプト

ルーチンな Git/GitHub 操作はシェルスクリプトに集約。実装判断と差分生成は Claude 本体が担当する。

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

スクリプト	役割	使い方
check-prereqs.sh	前提チェック(gh 認証・git・デフォルトブランチ・作業ツリー)	bash "${CLAUDE_PLUGIN_ROOT}/skills/implement-issue/scripts/check-prereqs.sh"
create-branch.sh	規約に沿ったブランチ作成	bash "${CLAUDE_PLUGIN_ROOT}/skills/implement-issue/scripts/create-branch.sh" <番号> <type> <short-desc>
create-pr.sh	現ブランチから PR 作成	bash "${CLAUDE_PLUGIN_ROOT}/skills/implement-issue/scripts/create-pr.sh" "<タイトル>" <body-file>

コミットは Claude が git コマンドで直接行う(内容ごとにメッセージが変わるため)。

---

ワークフロー

このスキルは完全自動ではなく、各ステップでユーザーに確認を取るチェックポイントを設けている。勝手に解釈して進めない。

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

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

エラー終了したら内容をユーザーに報告して中断する。WARN: が出た場合は続行してよいか確認する。

ステップ 2: Issue と spec.md を読み込む

gh issue view <番号> --json number,title,body,state,labels

続いて docs/issues/issue-<番号>/spec.md を Read で読み込む。

spec.md が存在しない場合は中断する。「先に create-issue スキルで spec を作ってください」とユーザーに伝える。Issue 本文だけを頼りに実装を始めない。

Issue の状態が CLOSED の場合もユーザーに確認する(意図せず閉じた Issue を実装しようとしている可能性)。

ステップ 3: 実装計画をユーザーと合意する【チェックポイント】

spec.md を読んだ上で、以下をユーザーに提示して合意を取る:

1. spec の解釈: 受け入れ条件の要旨を 2-3 行でまとめる
2. 曖昧な点: spec が曖昧だと感じた箇所があれば質問する(勝手に解釈しない)
3. ブランチ名の案: <type>/issue-<番号>-<short-desc> の形式で提案
   • type は feature / fix / refactor / docs / test のいずれか
   • short-desc は英語・kebab-case・30 文字以内
4. 実装方針のラフスケッチ: 編集/追加するファイルと主な変更点を箇条書き

ユーザーから OK が出るまで先に進まない。

ステップ 4: ブランチを作成

bash "${CLAUDE_PLUGIN_ROOT}/skills/implement-issue/scripts/create-branch.sh" <番号> <type> <short-desc>

成功するとブランチ名が stdout に返る。以降の作業はこのブランチで行う。

ステップ 5: 実装とテスト

Claude が Edit / Write / Bash 等を使って実装する。以下を守る:

• spec.md の受け入れ条件を 1 つずつ満たす。大きな Issue なら条件ごとにコミットを分ける。
• テストを追加/更新する。受け入れ条件のうち自動テストで検証可能なものは必ずテストに落とし込む。
• コミットは Conventional Commits(Issue 番号を末尾に付ける)
  • feat: <説明> (#<番号>) — 新機能
  • fix: <説明> (#<番号>) — バグ修正
  • refactor: <説明> (#<番号>) — リファクタ
  • docs: <説明> (#<番号>) — ドキュメント
  • test: <説明> (#<番号>) — テスト追加/修正
• コミット単位: 意味のある粒度で分ける。一気に巨大コミットを作らない。

実装中に spec の解釈で迷ったら、その場でユーザーに確認する(推測で進めない)。

ステップ 6: セルフレビュー【チェックポイント】

PR を出す前に、以下を順にチェックしてレポートをユーザーに提示する。1 つでも FAIL があれば PR 作成に進まず、ユーザー判断を仰ぐ。

1. リンター / フォーマッター / 型チェック: CLAUDE.md の ## Commands セクション(または同等の記載)を参照してコマンドを実行する。プロジェクトに定義が無ければそのことを明記して省略。
2. テスト: 同様にプロジェクトのテストコマンドを実行。追加したテスト + 既存テストの双方が通ること。
3. spec.md の受け入れ条件: - [ ] を全件列挙し、それぞれについて「自動テストでカバー済み」「手動確認: 実装の該当箇所 file:line」「未達」を明記。
4. デバッグコード混入チェック: git diff <default-branch>...HEAD で console.log / print( / debugger / TODO: remove 等が残っていないか確認。
5. 意図しない変更の確認: git diff --stat <default-branch>...HEAD を表示し、変更ファイルが想定どおりか目視確認。
6. コミットメッセージの規約チェック: git log <default-branch>..HEAD --oneline を表示し、Conventional Commits 形式と Issue 番号が揃っているか確認。

レポートは以下のような構造化された形式で出す:

[PASS/FAIL] リンター: <実行コマンド>
[PASS/FAIL] 型チェック: <実行コマンド>
[PASS/FAIL] テスト: <実行コマンド>
[PASS/FAIL] 受け入れ条件:
  - [x] 条件1 — tests/foo.test.ts:12 でカバー
  - [x] 条件2 — src/bar.ts:42 で実装、手動確認済み
  - [ ] 条件3 — 未達(理由)
[PASS/FAIL] デバッグコード混入なし
[PASS/FAIL] 変更ファイルは想定どおり
[PASS/FAIL] コミットメッセージ規約準拠

ステップ 7: PR 本文を組み立てる【チェックポイント】

PR 本文を一時ファイルに書き出す:

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

<1-2 文で何をしたか>

## 関連 Issue

Closes #<番号>

## 変更内容

- <箇条書き>

## テスト

- <追加/変更したテストの概要、実行結果>

## 動作確認

<該当すれば、スクショや手順。なければ省略>
EOF

PR タイトルは代表コミットと同じ形式(例: feat: ユーザー一覧にページネーションを追加 (#42))。

タイトルと本文をユーザーに提示して OK をもらう。

ステップ 8: PR を作成

bash "${CLAUDE_PLUGIN_ROOT}/skills/implement-issue/scripts/create-pr.sh" "<タイトル>" "$BODY_FILE"
rm -f "$BODY_FILE"

スクリプトは未プッシュのブランチを自動で git push -u origin <branch> する。

ステップ 9: 結果を報告

• 作成された PR の URL
• ブランチ名
• 追加/変更したファイル一覧(git diff --stat <default-branch>...HEAD)
• セルフレビューのサマリ
• 次にユーザーがやるべきこと(レビュー依頼、CI 確認など)

---

例

例: Issue #42 の実装

ユーザー: 「Issue #42 を実装して」

動き:

1. check-prereqs.sh で環境確認(デフォルトブランチにいる・作業ツリーがクリーン)
2. gh issue view 42 と docs/issues/issue-42/spec.md を読む
3. 受け入れ条件の要旨・曖昧な点・ブランチ名案 feature/issue-42-add-pagination・実装方針をユーザーに提示して合意を取る
4. create-branch.sh 42 feature add-pagination
5. src/users/UserList.tsx を編集、tests/users/UserList.test.tsx を追加。コミット 2 個に分ける:
   • feat: add pagination to user list (#42)
   • test: add tests for user list pagination (#42)
6. セルフレビュー: lint/typecheck/test を実行、受け入れ条件 3 件すべて PASS、デバッグコード無し、変更 2 ファイル、コミットメッセージ OK
7. PR 本文を組み立ててユーザー確認
8. create-pr.sh で PR 作成
9. PR URL とサマリを報告

---

注意点

• spec.md が無い Issue: 先に create-issue スキルを使うよう促す。古い Issue で spec が無い場合は、ユーザーに「spec を先に作るか、このスキルを使わず手動で進めるか」を確認する。黙って Issue 本文だけで実装を進めない。
• デフォルトブランチ前提: このスキルは「デフォルトブランチにいる & 作業ツリーがクリーン」を必須にしている。既に作業中のブランチに追加実装したい場合はこのスキルの対象外(手動で対応)。
• PR 作成の取り消し: ステップ 8 で PR 作成に失敗した場合、ブランチとコミットはローカルに残っている。ユーザーに状況を報告し、再実行するか手動で gh pr create するか相談する。勝手にブランチを削除しない。
• push 運用: create-pr.sh が自動で git push -u origin を行う。push を避けたい運用の場合はこのスキルを使わず手動で進める。
• 大きすぎる Issue: 実装中に「この Issue 1 本で収まらない」と感じたら、その時点でユーザーに分割を提案する(無理に 1PR に押し込めない)。
• 受け入れ条件の更新: 実装中に spec の受け入れ条件に過不足が見つかった場合、spec.md を先に更新するかユーザーに確認する。コードと spec が乖離したまま PR を出さない。
• CLAUDE.md のコマンド欄: lint/test コマンドの出所はプロジェクトの CLAUDE.md。このスキル内にはハードコードしない。CLAUDE.md に該当セクションが無い場合、セルフレビューでその旨を明記して「コマンドが不明のため未実行」とする。