implement-issue

イシュー実装スキル

ブランチの設定、コードベースの分析、実装まで、GitHub のイシューを最初から最後まで実装します。

前提条件の確認（最初に必ず確認）

作業を進める前に、以下を確認してください。

# 1. Check if in a git repository
git rev-parse --is-inside-work-tree

# 2. Check if gh CLI is available and authenticated
gh auth status

# 3. Check for uncommitted changes (warn user if any)
git status --porcelain

確認に失敗した場合は、作業を中止してユーザーに知らせてください。

• Git リポジトリ内にいない → 「このスキルには Git リポジトリが必要です。Git プロジェクトに移動してください。」
• gh の認証が済んでいない → 「まず gh auth login を実行してください。」
• 未コミットの変更がある → 「未コミットの変更があります。先にコミットするか、スタッシュしてください。」

入力

ユーザーは、次のいずれかの形式でイシューを指定します。

• 完全な URL：https://github.com/owner/repo/issues/123
• 短縮形式（リポジトリ内の場合）：#123 または 123

ワークフロー

Step 1：イシュー情報を抽出する

# Get comprehensive issue metadata
gh issue view <ISSUE_NUMBER_OR_URL> --json number,title,body,state,author,labels,milestone,assignees,comments,createdAt,updatedAt

# Get repository info for branch naming
gh repo view --json owner,name,defaultBranchRef

イシューを解析し、次の内容を把握します。

• タイトル：必要な作業の概要
• 本文：詳細な要件、受け入れ基準、背景情報
• ラベル：作業の種類（バグ、機能、改善など）
• コメント：追加の背景情報、議論、説明

Step 2：最新の Main/Master ブランチに同期する

# Detect default branch (main or master)
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')

# Fetch latest changes
git fetch origin $DEFAULT_BRANCH

# Checkout and update default branch
git checkout $DEFAULT_BRANCH
git pull origin $DEFAULT_BRANCH

Step 3：イシューブランチを作成する

イシューに基づいてブランチ名を生成します。

ブランチの命名規則：<type>/<issue-number>-<short-description>

イシューの種類（ラベルに基づく）	ブランチの接頭辞
bug、bugfix	fix/
feature、enhancement	feat/
docs、documentation	docs/
refactor	refactor/
test	test/
chore	chore/
（デフォルト）	issue/

例：

• イシュー #42「ユーザー認証を追加」→ feat/42-add-user-authentication
• イシュー #15「ログインのリダイレクトバグを修正」→ fix/15-fix-login-redirect
• イシュー #99「README を更新」→ docs/99-update-readme

# Create and checkout new branch
git checkout -b <BRANCH_NAME>

Step 4：コードベースを詳しく分析する

実装する前に、コードベースを十分に理解してください。

4.1 プロジェクト構成を分析する

# Get project structure overview
ls -la
find . -type f -name "*.json" -path "*/package.json" -o -name "*.toml" -path "*/Cargo.toml" -o -name "*.go" -path "*/go.mod" 2>/dev/null | head -20

# Check for configuration files
ls -la *.json *.yaml *.yml *.toml .* 2>/dev/null | head -20

4.2 既存のパターンを把握する

探索エージェントを使って、以下を把握します。

1. アーキテクチャ：コードベースはどのように構成されていますか？主なモジュールは何ですか？
2. パターン：どのようなコーディングパターンが使われていますか？（エラー処理、ロギング、テスト）
3. 関連コード：このイシューに関連する既存のコードは何ですか？
4. 依存関係：どのライブラリ／フレームワークが使われていますか？

# Fire multiple explore agents in parallel
background_task(agent="explore", prompt="Find the main entry points and understand the overall architecture of this codebase")
background_task(agent="explore", prompt="Find code related to [ISSUE_TOPIC] and understand existing patterns")
background_task(agent="explore", prompt="Find test patterns and testing conventions in this codebase")

4.3 実装箇所を特定する

イシューの要件に基づいて、以下を特定します。

• 変更が必要なファイル
• 新規作成が必要なファイル
• 追加／更新が必要なテスト
• 更新が必要なドキュメント

Step 5：実装計画を作成する

コーディングを始める前に、詳細な ToDo リストを作成します。

todowrite([
  { id: "1", content: "Understand issue requirements fully", status: "completed", priority: "high" },
  { id: "2", content: "Analyze related codebase areas", status: "completed", priority: "high" },
  { id: "3", content: "[Specific implementation task 1]", status: "pending", priority: "high" },
  { id: "4", content: "[Specific implementation task 2]", status: "pending", priority: "medium" },
  { id: "5", content: "Add/update tests", status: "pending", priority: "high" },
  { id: "6", content: "Run tests and fix issues", status: "pending", priority: "high" },
  { id: "7", content: "Update documentation if needed", status: "pending", priority: "low" },
  { id: "8", content: "Final verification", status: "pending", priority: "high" }
])

Step 6：解決策を実装する

以下の原則に従ってください。

1. 既存のパターンに合わせる：コードベースで確立されている規約に従います
2. 段階的に変更する：小さく、焦点を絞った変更を行います
3. 作業しながらテストする：次に進む前に、各変更が機能することを確認します
4. 複雑なロジックを文書化する：必要に応じてコメントを追加します

実装タスクごとに、以下を行います。

1. ToDo を in_progress にする
2. 変更を加える
3. 変更したファイルに対して lsp_diagnostics を実行する
4. ToDo を completed にする

Step 7：テスト

# Run project tests (detect test command from package.json, Makefile, etc.)
# Common patterns:
npm test
yarn test
go test ./...
cargo test
pytest
make test

以下を確認してください。

• 既存のテストがすべて合格する
• 新機能に対するテストが追加されている
• エッジケースが網羅されている

Step 8：最終確認

# Check for any linting issues
# (detect lint command from project config)

# Verify build succeeds
# (detect build command from project config)

# Review all changes
git diff --stat
git diff

Step 9：変更をコミットする

# Stage all changes
git add -A

# Create commit with conventional commit message
# Format: <type>(scope): <description>
#
# Reference the issue number in the commit body
git commit -s -m "<type>: <short description>

<detailed description of changes>

Closes #<ISSUE_NUMBER>"

コミットメッセージの例：

• feat: add user authentication system
• fix: resolve login redirect loop
• docs: update API documentation

出力形式

実装の完了後、以下を提示してください。

---

実装の概要

イシュー：#[NUMBER] - [TITLE]
ブランチ：[BRANCH_NAME]
ステータス：[実装済み／一部実装済み／ブロック中]

変更内容

ファイル	変更の種類	説明
path/to/file.ts	変更	[変更内容]
path/to/new-file.ts	追加	[追加内容]

実装の詳細

[実装した内容と、それがイシューにどのように対応するかを2～5文で説明]

追加／更新したテスト

• [テスト1の説明]
• [テスト2の説明]

検証結果

チェック	ステータス	備考
ビルド	成功／失敗	[Notes]
テスト	成功／失敗	[Notes]
リント	成功／失敗	[Notes]
診断	問題なし／問題あり	[Notes]

---

次のステップ

ユーザーに以下を提案します。

1. 変更を確認する：git diff origin/<DEFAULT_BRANCH>...HEAD
2. ブランチをプッシュする：git push -u origin <BRANCH_NAME>
3. PR を作成する：gh pr create --title "<PR_TITLE>" --body "<PR_BODY>"

または、希望があれば PR を自動的に作成することを申し出てください。

---

重要な注意事項

1. 実装前に理解する：課題とコードベースを理解するために十分な時間をかけてください
2. 不明点を確認する：課題の要件が不明確な場合は、実装前に確認してください
3. 変更を最小限にする：課題の実装に必要な変更だけを行ってください
4. 規約に従う：既存のコードベースのスタイルやパターンに合わせてください
5. 十分にテストする：変更によって既存の機能が壊れないことを確認してください
6. ドキュメントを更新する：変更がパブリック API やユーザー向け機能に影響する場合は、ドキュメントを更新してください

エラー処理

状況	対応
課題が見つからない	課題番号／URL を確認し、リポジトリへのアクセスを確認してください
ブランチがすでに存在する	既存のブランチを使うか、接尾辞を付けて新しいブランチを作成するか、ユーザーに尋ねてください
マージコンフリクト	ユーザーに報告し、解決手順を提案してください
テストが失敗する	以前から発生していた問題か、変更によって生じた問題かを調査してください
要件が不明確	作業を進める前にユーザーに確認してください
実装がブロックされている	ブロッカーを記録し、代替案を提案してください