implement-issue

implement-issue

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

フロー

Step 1: Issue を取得する

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

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）

計画の必須セクション:

# [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 があるか検索する:

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

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

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

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

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 無効にする。