create-issue

GitHub Issue の作成

ユーザーの説明をもとに、対話形式で確認しながら、適切に構成された GitHub Issue を作成します。

リポジトリの検出

プラットフォームの CLI を使って、現在の git remote からリポジトリを検出します。例：

# GitHub lane (CODE_HOST=github):
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner')

# GitLab lane (CODE_HOST=gitlab):
REPO=$(glab repo view -F json | jq -r '.path_with_namespace')

どちらの場合も、OWNER と REPO_NAME（GitLab の場合は NAMESPACE と PROJECT）に分割します。検出に失敗した場合は、対象のリポジトリをユーザーに尋ねます。

プロセス

ステップ 1：リクエストを把握する

ユーザーが機能やバグについて説明したら、確認の質問をして背景情報を集めます。すぐに Issue を作成してはいけません。

機能の場合、以下を確認します：

• ユーザーにとっての目標は何ですか？（実装の詳細ではありません）
• 受け入れ基準は何ですか？（動作をどのように検証しますか？）
• 各受け入れ基準は、_マージ前に検証可能_ですか？ 証拠を PR のマージ前に、自律型の開発／レビューエージェントがアクセスできる場所（CI ジョブ、PR プレビュー URL、ステージングコマンド、ローカルでの再現など）から取得できますか？マージ前に検証可能な受け入れ基準を優先し、作成者には検証場所と期待される証拠を明記してもらいます。基準が_マージ前に検証できない_場合（デプロイ／本番環境、実ユーザー、長時間の連続稼働、外部承認、本番テレメトリー、またはボットが持たない認証情報が必要な場合）は、まず既存の PR プレビュー／ステージング環境で同じコードパスを同じ入力により検証できるか確認します。マージ前に本当に検証できない場合は、別のブロック対象ではない、autonomous ではないフォローアップに分割します（references/ac-verification.md を参照）。ループがマージ前に満たせないブロッキング受け入れ基準は、開発↔レビューのループが終了しなくなる既知の要因です。
• UI／UX に影響しますか？
• どの既存機能に関連しますか？
• 優先度とスコープの制約

バグの場合、以下を確認します：

• 再現手順
• 期待される動作と実際の動作
• 環境（本番、ステージング、PR プレビュー）
• 深刻度（ブロッキング、性能低下、見た目の問題）
• エラーメッセージやログの有無
• 修正の各受け入れ基準は、_マージ前に検証可能_ですか？ バグ修正には通常、複数の受け入れ基準があります。主要な「回帰テストが修正前に失敗し、修正後に成功する」（これはマージ前の標準です。検証場所として CI の unit／E2E ジョブを明記してください）だけでなく、すべての基準を分類します。受け入れ基準を「デプロイ済みのパイプラインで失敗したバッチを再生して検証する」のような_マージ後／本番環境での再実行_として記述しないよう注意してください。既存の PR プレビュー／ステージング環境で同じコードパスを同じ入力により検証できる場合は、その環境を検証場所として指定します。マージ後にしか確認できない基準は、別のブロック対象ではない、autonomous ではないフォローアップに分割します（references/ac-verification.md を参照）。各基準を個別に分類することは、機能の場合と同様にバグ修正にも適用されます。Issue の種類にかかわらず、ループがマージ前に満たせないブロッキング受け入れ基準は、開発↔レビューのループが終了しなくなる既知の要因です。（注：バグの ## Environment フィールドで prod を指定するのは問題ありません。これは再現環境であり、受け入れ基準ではありません。）

1 回につき、焦点を絞った質問を 2～3 個尋ねます。明確な Issue を作成するのに十分な情報が集まったら終了します。

上記の各受け入れ基準に対するマージ前に検証可能かどうかの分類は、機能とバグの両方に適用されます。機能の場合と同様に、ブロッキングとなる本番環境限定の受け入れ基準を含むバグ報告を作成してはいけません。

ステップ 2：Issue の下書きを作成する

Issue の種類に応じて適切なテンプレートを使用します。テンプレートの全文は、references/issue-templates.md を参照してください。

どちらのテンプレートにも、以下の必須セクションが含まれます：

• Summary／Motivation（機能の場合）、または Steps to Reproduce（バグの場合）
• チェックボックス付きの Requirements（機能の場合）、または Expected/Actual Behavior（バグの場合）
• Testing Requirements（必須の TDD セクション：テストケースのドキュメント、ユニットテスト、E2E テスト）
• チェックボックス付きの Acceptance Criteria
• Issue の順序付けのための Dependencies セクション

ステップ 3：ワークスペースの変更を検出して添付する

Issue の下書きを作成したら、ワークスペースを確認し、自律型開発エージェントに役立つ可能性のあるローカル変更がないか調べます。検出、添付、クリーンアップの完全な手順については、references/workspace-changes.md を参照してください。

概要：

1. git status --short を実行します。変更がない場合はスキップします
2. 変更を要約し、ユーザーに確認を求めます
3. 差分のサイズに応じて方法を選びます：インライン（500 行未満）、ブランチをプッシュ（500 行以上）、またはファイル一覧へのフォールバック
4. Issue の本文に ## Pre-existing Changes セクションを追加します
5. 添付後、必要に応じてローカル変更をクリーンアップします

ステップ 4：ユーザーに確認する

次の内容を含め、Issue の下書きをユーザーに提示します：

1. 提案するタイトル（簡潔で内容がわかるもの）
2. Issue の本文全体（該当する場合は Pre-existing Changes セクションを含む）
3. 提案するラベル
4. autonomous ラベルを追加するかどうか

AskUserQuestion を使用して確認します：

• 「この Issue の内容は正しいですか？作成しますか？」
• autonomous ラベルについて質問します。AI に自動で対応させるかどうかを確認します

マージ前検証可能性に関するアドバイザリ自己スキャン（ランタイムスクリプトではなく、あなたがリンターとして実施）：下書きの AC チェックボックス行のみ（## Acceptance Criteria の下にある - [ ] 行。他のフィールドは対象外です。これにより、Stage: の値として prod が適切に使われる場合のバグテンプレートの ## Environment フィールドで誤検知するのを避けます）を対象に、マージ前の AC ではないことを示す表現をスキャンします： post-merge、after merge、in production、およびその他の表現 — live users、soak、rollout、approver、prod telemetry、manual smoke。ブロッキング AC に該当する表現があり、対応するフォローアップへの分割がない場合、作成者に警告し（アドバイザリであり、ブロッキングではありません）、references/ac-verification.md §3 に従って分割することを提案します（ブロッキングではなく、autonomous でもないフォローアップを作成し、## Out of Scope で参照します。## Dependencies では参照しません）。該当する場合でも、下書きを不合格にしないでください。

エージェントが書き込めない領域に関するアドバイザリ自己スキャン（対象は同じく AC チェックボックス行のみで、同じ行を 2 回目にスキャンします）：開発エージェントのスコープ付きトークンでは書き込めない検証対象を示す表現もスキャンします。最低限、in (the )?PR (body|description|title) と PR metadata を対象にします。このような AC はマージ前に完全に検証可能でも、dev-actionable=false の状態で処理が停滞することが確実になります。スコープ付きトークンでは PR／Issue のコメント投稿やファイルのコミットはできますが、設計上、PR のメタデータは編集できないためです（2 トークン分割の詳細は references/ac-verification.md §5 を参照）。該当する場合、作成者に警告し（アドバイザリであり、ブロッキングではありません）、エージェントが書き込み可能な対象を指定するよう表現を変更することを提案します。たとえば、「…in PR body」を「…as a PR comment」に変更します。該当する場合でも、下書きを不合格にしないでください。

ステップ 5：Issue を作成する

GitHub MCP ツールまたは gh CLI を使用して、次の内容で Issue を作成します：

• title：確認済みのタイトル
• body：確認済みの本文
• labels：適切なラベル（以下のラベルガイドを参照）

作成した Issue の URL をユーザーに知らせます。

ブランチのプッシュを保留にした場合（大きな差分に対する方法）：

Issue の作成後、Issue 番号がわかったら：

1. 実際の Issue 番号を使用して、ステップ 3 のブランチプッシュコマンドを実行します
2. Issue の本文を更新し、ブランチ参照セクションを追加します

ラベルガイド

ラベル	適用する場合
bug	バグ報告
enhancement	機能リクエスト
autonomous	AI に開発／テスト／レビュー／マージを自動で行わせることをユーザーが確認した場合
no-auto-close	autonomous と併用します。AI は開発／テスト／レビューを行いますが、マージ前に停止し、手動での承認を求めます
documentation	ドキュメントのみの変更
good first issue	簡単で、範囲が明確なタスク

自律的なラベルの判断

イシューの下書きを作成した後、autonomous ラベルを追加するかどうか、必ずユーザーに尋ねてください。

autonomous が適切なケースについて、次のように案内してください。

• 適しているケース：範囲が明確で、受け入れ基準がはっきりしており、既存のパターンに従い、曖昧な設計上の判断が不要な場合
• 適していないケース：重要なアーキテクチャ上の判断が必要な場合、開発中にユーザーの意見を求める必要がある場合、機密性の高いインフラストラクチャの変更を伴う場合、探索的な作業や調査タスクの場合

次のように質問してください。

"このイシューを自律開発パイプラインで処理しますか？AI が変更の開発、テスト、レビュー、マージを自動で行います。受け入れ基準が明確で、範囲が定義されたタスクに最適です。"

ユーザーが autonomous を選択した場合は、no-auto-close も付けるかどうか尋ねてください。

"このイシューに no-auto-close ラベルも付けますか？このラベルを付けると、AI は開発、テスト、レビューを行いますが、マージの前に停止します。最終的なマージ判断を行えるよう、通知が届きます。機密性の高いインフラストラクチャの変更、プロダクトの承認が必要な機能、実験的な作業におすすめです。"

ラベルの組み合わせの概要：

• autonomous のみ = AI が開発／テスト／レビューを行い、合格すると自動マージします
• autonomous + no-auto-close = AI が開発／テスト／レビューを行いますが、マージ前に停止し、手動での承認を求める通知を担当者に送ります

執筆ガイドライン

• タイトル：動詞で始め、具体的にします。「プラン一覧ページにページネーションを追加する」のように記述し、「プランページの改善」のような表現は避けてください
• 本文：コードベース全体にアクセスできる一方で、この会話での口頭の説明を知らない AI 開発者向けに記述してください
• 受け入れ基準：主観的ではなく、客観的に検証できるものにしてください
• AC の検証可能性：受け入れ基準ごとに、マージ前に検証可能（マージ前に証拠を取得できるもの。対象となる場所（CI ジョブ、PR プレビュー URL、ステージング用コマンド、またはローカルでの再現手順）と期待される証拠を明記）か、マージ前に検証不可能（デプロイ／本番環境、実ユーザー、一定期間の稼働、外部承認、本番テレメトリー、またはボットが持たない認証情報が必要）かを分類してください。前者を優先し、結果を述べるだけでなく、必ず検証場所と期待される証拠を明記してください。実際にマージ前に検証できない基準は、別のブロッキングではなく、autonomous でもないフォローアップに記載してください（## Out of Scope で言及し、## Dependencies には記載しないでください）。これをブロッキングの AC として残すと、開発とレビューの反復が終わらなくなることが知られています。詳しい評価基準、既存のプレビューの再利用に関するガイダンス、分割手順、具体例については references/ac-verification.md を参照してください。
• 範囲：大規模で複数の部分から成るイシューより、小規模で焦点を絞ったイシューを優先してください
• 参考情報：関連するイシュー、PRD のセクション、コードパスがあればリンクしてください
• 依存関係：## Dependencies セクションには、このイシューを開始する前にクローズまたはマージが必要なイシューのみを記載してください。文脈のために参照する親エピック、このイシューによってブロックが解除されるイシュー、真のブロッカーではない #NNN 参照は含めないでください。自律ディスパッチャーはこのセクションを文字どおりに解析します。未完了のイシューをリスト項目に記載すると、そのイシューがクローズまたはマージされるまで、このイシューは通知なくスキップされます。解析対象はリスト項目の行のみ（-、*、1. で始まる行）です。## Dependencies から次の ## までの文章や引用は無視されます。リスト項目では、#N（同一リポジトリ）と owner/repo#N（別リポジトリ）の両方が認識されます。ブロッカーがない場合は、正確に None と記載してください。後続のイシューを記述する際に先行するイシュー番号がわかるよう、依存関係の順にイシューを作成してください。
• テスト要件：「Testing Requirements」セクションは必ず含めてください。開発エージェントはプロジェクトの TDD ワークフローに従いますが、イシューで明示されていないと E2E テストやテストケースのドキュメントを省略することがあります。次の点を具体的に記載してください。
  • 各テスト種別で確認すべき主なシナリオ（箇条書きで 2～4 項目）
  • バグの場合：修正前は失敗し、修正後は成功する回帰テスト

複数のIssueの作成

大規模な機能を複数のIssueに分割する場合：

1. 依存関係の順にIssueを作成する — 依存関係のないIssueを先に作成し、その後、それらに依存するIssueを作成します。これにより、依存関係を記述する際にIssue番号が分かるようになります。
2. 各Issue本文の ## Dependencies セクションに、直接ブロックしているIssueへのリスト項目リンクとして #N（同一リポジトリ）または owner/repo#N（別リポジトリ）を記載します。親エピック、コンテキスト用Issue、このIssueがブロックを解除するIssueは参照しないでください。このセクション内のリスト項目の参照はすべてハードブロッカーとしてディスパッチャーが扱います。本文中や引用ブロック内の参照は無視されます。
3. 一貫した命名規則を使う — 絞り込みやすいように、タイトルの先頭にプロジェクト／機能名を付けます（例：「MyProject: DynamoDB インフラストラクチャの追加」）。
4. 計画への相互参照を追加する — 実装計画がある場合は、各Issueを関連する計画のタスク／チャンクにリンクします。
5. ディスパッチャーはブロックされているIssueをスキップします — ## Dependencies セクションに未解決の依存関係があるIssueは、すべての依存関係が解決される（クローズ／マージされる）まで、自律型ディスパッチャーによって無視されます。

---

参考資料

詳細については、以下を参照してください：

• references/issue-templates.md -- 必須セクションをすべて含む、機能およびバグIssueの完全なテンプレート
• references/ac-verification.md -- マージ前／マージ前でないACの分類基準、既存のプレビューを再利用するためのガイダンス、ブロックしないフォローアップへの分割手順、no-auto-close の補足説明、および実例2件（ループ防止）
• references/workspace-changes.md -- ワークスペース変更の検出、添付方法、およびクリーンアップ手順の全容