---
name: implement-issue
description: 'GitHub Issue を読み込み、`_/local-plans/<issue-number>-<slug>.md` に詳細計画を作成して**ユーザー承認後**にコードを実装する。実装後はセキュリティレビュー (OWASP Top 10) → テスト実行 → Conventional Commits でコミット。Issue 番号や URL を渡された実装依頼、「Issue #N を実装して」「この Issue を着手」などで使用。'
model: opus
user-invocable: true
---

# implement-issue

GitHub Issue を読み込み、計画確認後にコードを実装します。

## フロー

### Step 1: Issue を取得する

Issue URL または番号から内容を取得:

```bash
gh issue view <url-or-number>
```

sandbox 環境等でネットワーク到達不可の場合は、`gh issue view` の代わりにユーザーから Issue 本文を
直接（貼り付け・ファイル等で）受け取り、それを Issue 内容として Step 2 以降を進めてよい。

### Step 2: コードベースを調査して実装計画を作成する

Issue の内容をもとに関連コードを調査し、`_/local-plans/` に詳細な計画ファイルを作成する。

#### 2-1. 関連コードを調査する

以下を並行して調査:
- 変更対象ファイルの現状（Glob / Grep / Read）
- 再利用可能な既存コンポーネント・ユーティリティ
- 該当 API エンドポイント
- 同様の実装パターン

#### 2-2. 計画ファイルを `_/local-plans/` に保存する

ファイル名: `<issue-number>-<issue-slug>.md`（例: `_/local-plans/42-add-auth.md`）

計画の必須セクション:

```markdown
# [Issue タイトル]

## Context
Issue の背景・目的・なぜこの変更が必要か。

## Approach
実装方針。選択肢がある場合は採用理由も記述。

## File Changes

| ファイルパス | 変更内容 |
|-------------|---------|
| `src/...` | 〜を追加 |
| `lib/...` | 〜を修正 |

## Reuse
再利用する既存実装のパスと用途。

## Test Plan
- [ ] 動作確認手順
- [ ] エッジケース確認
```

### Step 3: ユーザーに計画を提示して承認を待つ

作成した計画ファイルの内容を表示し、ユーザーの承認を得てから実装を開始する。
**承認なしに実装を開始してはならない。**

### Step 4: コードを実装する

CLAUDE.md やプロジェクトの規約に従って実装する。
広範な変更の場合は `isolation: "worktree"` を使用して安全に実施。

コメント方針:
- コードコメントは「何をするか」より「なぜ存在するか／パッケージ・サービスから見た対象の役割」を書く。
- 後続の読み手（Claude を含む）は渡された情報からしか判断できないため、他ファイル・他サービス・呼び出し元/呼び出し先からの観点を明示する（このシンボルがどこから呼ばれ、どの境界を担うか）。
- 対象リポジトリに `.claude/rules/code-comment-style.md`（`init-claude` が配備）が存在する場合はそちらの詳細規約に従う。存在しない場合は上記の要点（役割・境界・呼び出し関係の明示）に従う。

### Step 5: セキュリティレビュー（必須）

Agent ツールでセキュリティ確認を行う。

確認項目:
- OWASP Top 10
- API キー・シークレットのハードコーディング
- 入力バリデーション
- XSS の可能性

問題が見つかった場合は修正してから次のステップに進む。

### Step 6: テストを実行する

プロジェクトのテストコマンドを実行する。テストが失敗した場合は根本原因を調査してから修正する。

根本原因デバッグ方針（対象リポジトリに `.claude/rules/debugging.md` が存在する場合はそちらの4フェーズに従う。存在しない場合は以下の要点に従う）:
- エラーメッセージ・スタックトレースを精読してから修正コードを書く
- 同一箇所で3回失敗したらアーキテクチャ問題と判断し、追加の修正試行をせずユーザーに状況を報告する

### Step 7: コミットを作成する

`create-commit` スキルを使用して Conventional Commits 形式でコミットを作成する。

## 実装対象外（out-of-scope）の扱い

実装の過程で、対応すべきだが現スコープ外と判断した事項（未対応の改善・別機能・技術的負債・後続作業）が発生した場合は、放置せず必ず追跡する。

### 手順

1. **既存 Issue を確認する**
   対象を実装している既存の open Issue があるか検索する:

```bash
gh issue list --state open --search "${KEYWORD}"
```

   キーワードは `"${KEYWORD}"` でクォートして渡す。

2. **ユーザーに提示して承認を得る**
   out-of-scope 項目・既存 Issue の有無・対応案（既存 Issue へのコメント追加 or 新規起票）をユーザーに提示する。**承認を得てから実行する**（確認なしに Issue 操作をしない）。

3. **既存 Issue がある場合: コメントを追加する**

```bash
gh issue comment "${ISSUE_NUMBER}" --body "$(cat <<'EOF'
## 実装サポート情報（別作業から検出）

### 検出背景
今回の実装（Issue #N）の過程で発見した事項。

### 関連ファイル・シンボル
- `src/path/to/file.ts` — 対象関数名・クラス名

### パッケージ・サービスから見た役割・影響範囲
（このシンボルの担う境界、呼び出し元/呼び出し先）

### 着手時の注意点・依存関係
（依存パッケージ、順序制約など）
EOF
)"
```

4. **既存 Issue がない場合: 新規起票する**
   `create-issue-tree` が導入されていればそれを使用（既存ルートへの紐付けは `--root <ルートissue番号>`）、未導入なら `create-issue` を使用して、適切な親 Issue 配下に起票する。タイトルは Conventional Commits 形式とする。

5. **PR 本文・Issue コメントに明記する**
   元の PR 本文または出力レポートに「対象外とした項目」と「切り出し先 Issue 番号」を記載する（コミット作成後でよい）。

> **セキュリティ注記**: `gh` へ渡すキーワード・コメント本文は変数を `"${var}"` でクォートし、本文は HEREDOC（`<<'EOF'`）で渡してインジェクションを防ぐ。

## 検証

テスト・ビルドコマンドを新規実行し、出力全体と終了コードを確認してから完了を宣言する（対象リポジトリに `.claude/rules/verification.md` が存在する場合はそちらの5段階ゲートに従う）。

- 「〜のはず」「たぶん動く」等の推測語での完了主張は禁止
- テスト出力・終了コードを証拠として引用してから完了を宣言する

例:
```
検証結果: `npm test` を実行。全22件パス、失敗0件（終了コード0）。
```

## よくある失敗

| 問題 | 回避策 |
|------|--------|
| 承認前に実装を開始する | Step 3 の承認待ちを飛ばさない。計画提示→承認→実装の順を厳守 |
| テスト失敗の原因を調査せず当て推量で修正する | 対象リポジトリに `.claude/rules/debugging.md` があればその4フェーズ、無ければ Step 6 の要点（調査→分析→仮説→修正）を順に踏む |
| セキュリティ問題を未解決のままコミットする | Step 5 で問題が見つかった場合は必ず修正してから Step 6 へ進む |
| 前回のテスト結果を根拠に完了宣言する | テストは必ず新規実行し、終了コードと出力全体を確認する |

## 注意事項

- ユーザーの承認なしに実装を開始しない
- セキュリティ問題が未解決のままコミットしない
- 大きな変更はステップを分けてコミットする

## sandbox 環境での実行

計画作成・実装・テスト実行・Step 7 のコミット作成までは sandbox 環境で実行できる（ワークスペース内書き込みのみで、ネットワーク越しの操作を行わない）。`gh issue view` によるイシュー取得は Step 1 の代替経路（Issue 本文の直接受け取り）を使えば省略できる。「実装対象外（out-of-scope）の扱い」節の追跡ステップ（`gh issue list` による既存 Issue 検索、`gh issue comment` によるコメント追加、`create-issue-tree` / `create-issue` による新規起票）も選択した場合はネットワークを要する。本スキルのフロー内でネットワークを要するのは `gh issue view` とこれら out-of-scope 追跡の任意ステップのみで、いずれも省略可能である（本スキルのフローに `git push` は含まれない。コミット後にリモートへ反映する場合は別途 `create-pr` 等の後続スキルを使う）。これらを実行する場合はコマンド単位で sandbox 無効にする。