mcpField
D
develop-issue

develop-issue

github.com/patinaproject開発168 回インストール今日更新
リポジトリ

develop-issue について

develop-issueは、GitHub Issueに取り組む目標指向のワークフロースキルです。ブランチ作成、実装、デバッグ、レビュー、PR完了の各スキルを連携し、検証やフィードバックへの終了条件を定めています。人の判断が必要な場合は作業を中断します。

主な機能

  1. 01同一リポジトリのIssueを1件受け付け
  2. 02実装・デバッグ・レビューのスキルを連携
  3. 03検証結果とレビュー指摘への対応を要求
  4. 04PRチェックとブロッカーを追跡
  5. 05goal-metとhuman-blockedの終端状態

活用シーン

  1. 01Issueの受け入れ条件に沿った変更の実装
  2. 02開発中に発生した不具合や不安定動作の調査
  3. 03PR完了前のコードレビュー指摘への対応
  4. 04権限や設計判断が必要な場合の作業停止

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/patinaproject/skills --skill develop-issue

インストール後、Claude Code で/develop-issueを入力して読み込まれたか確認します。

詳細

Issue の開発

クイックスタート

同じリポジトリにある GitHub issue の参照を 1 つだけ指定して実行します。

/develop-issue #123
/develop-issue https://github.com/<owner>/<repo>/issues/123

このスキルは、目標指向のコントローラーです。既存のワークフロースキルを調整し、その契約とリポジトリのガードレールを維持しながら、プルリクエストをマージすることはありません。

最終目標

本番環境に対応できる実装を行い、表示されるすべての PR チェックに合格し、ローカルレビューでのすべての指摘と PR のレビューコメントに対処します。

本番環境への対応可能性は、リスクがゼロであるという保証ではなく、証拠に裏付けられた準備状況として扱います。絶対的な確実性など、裏付けのない断定はしないでください。

最終状態

  • goal-met：本番環境への対応を示す証拠が goal-met を裏付けており、必要な終了ゲートをすべて満たし、表示される必須および任意の PR チェックにすべて合格しています。
  • human-blocked：作業を進めるには、人間の判断、外部へのアクセス、プロダクトまたはデザイン上の決定、権限、シークレット、相反する指示、または issue の範囲外にある妥当な作業が必要です。

人間が対応すべき未解決のブロッカーが残っている場合は、goal-met と報告しないでください。

必須の子スキル

ブランチの設定や実装に着手する前に、エージェント環境で次のスキルが利用可能であることを確認してください。

  • new-branch
  • implement
  • diagnosing-bugs
  • review-code
  • finish-pr

implement は、合意した段階で tdd と review を利用するため、これらもインストールされている必要があります。

不足しているスキルがある場合は、実装を開始せずに停止してください。不足しているスキル名とインストール手順を報告してください。

npm_config_ignore_scripts=true npx skills@latest add patinaproject/skills --skill new-branch --skill review-code --skill finish-pr -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@implement -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@tdd -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@review -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@diagnosing-bugs -y

implement、tdd、review、diagnosing-bugs、writing-great-skills、prototype のインストールヒントは、意図的にソースカタログのデフォルトブランチを参照しています。固定したリビジョンをインストールする場合は、参照先に #<git-ref> を追加してください。

条件付きルート

条件付きルートは、一律に必須となるものではありません。issue が該当ルートの条件に当てはまる場合に限り、指定されたスキルが利用可能か確認してください。条件に該当するスキルが不足している場合に限り、そのスキル名とインストール手順を示して停止してください。

条件付きルートが該当する場合のインストール手順：

npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@writing-great-skills -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@prototype -y
  • issue がインストール可能なスキルパッケージの範囲を変更する場合は、writing-great-skills を参照してください。対象には、スキルのエントリー手順、フロントマターや説明、ワークフローの契約テキスト、例、参考資料、同梱のヘルパースクリプトが含まれます。implement で変更を作成する前に、そのレビューを適用してください。
  • prototype は、issue で使い捨ての探索、状態モデルの妥当性確認、UI の方向性の探索、または同等のプロトタイプ作業を明示的に求めている場合に限り使用してください。issue でプロトタイプ成果物のコミットが明示的に求められていない限り、ローカルレビューの前にプロトタイプの成果物を削除するか、取り込んでください。

issue で明示的に求められていない限り、上流の計画、トリアージ、アーキテクチャレビュー、引き継ぎ、または会話モードのスキルを、通常の /develop-issue ルートに追加しないでください。

入力契約

  1. 裸の issue 番号、#<number>、または同じリポジトリの GitHub issue URL を 1 つ受け付けます。
  2. issue の参照がない場合は拒否します。
  3. issue の参照が複数ある場合は拒否します。
  4. 別のリポジトリの issue URL は拒否します。
  5. 現在の作業ディレクトリのデフォルト gh リポジトリを通じて issue を解決します。
  6. 受け入れ条件、範囲、リポジトリのルール、デザイン上の決定が実行可能な場合に限り、その issue を実装の事前承認として扱います。

issue に実行可能な受け入れ条件がない場合、リポジトリのルールと矛盾する場合、デザイン上の決定が必要な場合、外部へのアクセスに依存する場合、または issue に記録されていない判断を必要とする場合は、人間の判断を仰いでください。

必須の完了条件

  • Issue の範囲と受け入れ基準を網羅しています。
  • リポジトリに記載された検証を実行し、結果を記録しています。
  • 変更に実行可能な動作が含まれる場合、関連するテストを追加または更新しています。
  • ローカルの review-code で見つかった問題を修正するか、対応方針を決定しています。
  • finish-pr によって提示された GitHub PR のレビューコメントとホストされたレビューコメントを修正するか、対応方針を決定しています。
  • finish-pr の実行後、現在表示されている必須および任意の PR チェックがすべて通過した場合に限り、goal-met と報告します。
  • ブランチの範囲外で失敗した PR チェックについては、human-blocked の最終レポートで具体的な対応方針を示します。表示中の PR チェックがひとつでも失敗している間は、goal-met と報告しないでください。
  • 残存リスクとテストの不足は、具体的で Issue に関連し、人間の判断に役立つ場合に限って報告します。

このスキルでは、表示されている PR チェックには必須チェックと任意チェックの両方が含まれます。

機能マップ

  • new-branch：Issue に紐づくブランチのセットアップ（前提条件についてはワークフローのステップ 4 を参照）。
  • implement：受け入れ基準に基づいて Issue の変更を実装します。合意した接点で tdd を使い、記載された検証を実行してブランチにコミットします。
  • diagnosing-bugs：根本原因が不明、再現方法がない、動作が不安定、またはパフォーマンスが低下している場合に使います。
  • review-code：ビルダーのコンテキストとは独立した、新鮮なコンテキストでブランチ差分を確認し、正確性とマージに関わるリスクをレビューします。
  • finish-pr：コミット、プッシュ、PR の作成または更新、PR チェック、PR フィードバックへの対応、マージ可能な状態であることの報告を行います。
  • writing-great-skills：インストール可能なスキルパッケージの表層に関する変更に使います。
  • prototype：使い捨ての探索を明示的に依頼された場合にのみ使います。

ワークフロー

  1. AGENTS.md と CLAUDE.md があれば読み、さらにそれらが読み込むドキュメントも確認します。

  2. 同一リポジトリ内の単一の Issue 参照と、必要な子スキルを検証します。

  3. ブランチのセットアップ前に、Issue を作業開始済みにします。この「作業を開始します」という手順には、独立したアクションが 2 つあります。自分への割り当てと GitHub Project のステータス更新です。それぞれベストエフォートで実行します。どちらも実作業を妨げるものではなく、human-blocked による停止の原因にもなりません。

    自分への割り当て：

    • Issue の現在の担当者を assignees フィールドから確認します（例：gh issue view <number> --json assignees）。担当者リストが空の場合にのみ割り当てます。
    • Issue の担当者が 0 人の場合は、Issue 単位の呼び出しを 1 回だけ使い、現在 gh で認証されているユーザーに割り当てます。gh issue edit <number> --add-assignee @me を 1 回実行してください。「自分」は @me として扱います。ユーザー名をハードコードしないでください。そうすることで、このスキルをすべての利用者が再利用できます。
    • Issue に担当者が 1 人以上いる場合は、@me であっても他のユーザーであっても、何もしません。追加の担当者として @me を加えないでください。
    • これは Issue 単位の呼び出しであり、プロジェクト項目ごとの操作ではありません。割り当てを new-branch に追加しないでください。このツールはローカルブランチの操作に限定されます。
    • 割り当ての呼び出しが失敗した場合（権限、書き込みアクセス権の不足、API エラー）、理由を記録してスキップし、ブランチのセットアップと実装を続けます。 GitHub プロジェクトの状態：
    • issue の GitHub Project items（issue の projectItems データ）を確認し、既存の GitHub Projects を調べます。各既存の GitHub Project item について：
      • プロジェクトアイテムの調査を使って、In progress が完全一致する選択肢として用意されている互換性のあるフィールドを見つけ、そのプロジェクトアイテムを In progress に更新します。
      • issue をプロジェクトに追加しないでください。プロジェクトのフィールドやステータスの選択肢を作成しないでください。
      • プロジェクトに互換性のあるステータスフィールドがない場合、In progress の選択肢がない場合、または権限の問題でプロジェクトアイテムの調査や更新に失敗した場合は、互換性のないプロジェクトアイテムをスキップして続行します。
    • プロジェクトのステータス更新結果と自身への割り当て結果を記録し、更新した各アイテムとスキップした各アイテムの理由を最終報告に含めます。

  4. ブランチ設定の前提条件を満たします。現在のブランチが対象 issue に紐づくブランチであることを確認します（ブランチ名には、new-branch が生成する <issue>-<slug> の規則に従って issue 番号が含まれます）。確認が通った場合に限り new-branch をスキップします。それ以外の場合は、作業ツリーがデフォルト以外の issue に紐づかないブランチで始まった場合も含めて、new-branch を実行して issue に紐づくブランチを作成するか、ホストから提供されたブランチの名前を変更できない、または変更すべきでない場合は、その相違を明示します。

  5. Conditional Routes セクションで発動条件を満たすルートを適用します。

  6. 実際の状態と最終目標の間にある現在の不足を明示して、次に使う機能を選びます。

  7. 実装、診断、ローカルレビュー、公開を、固定された必須の順序として扱わないでください。現在の障害または準備上の不足を解消する機能を呼び出します。

  8. ローカルレビューの前、および最終的な公開準備状況を判断する前に、リポジトリで文書化されている検証を実行します。

  9. レビュー可能なローカル変更があるか確認します。対象は、デフォルトブランチとのマージベース以降のコミット済みブランチ差分、ステージ済みの変更、ステージされていない変更、未追跡ファイルです。

  10. レビュー可能なローカル変更がある場合は、review-code を呼び出し、その完全な契約を遵守します。develop-issue の明示的な使用は、この必須のローカルレビューゲートへの十分な承認となります。追加のユーザー確認を求めず、新しい読み取り専用レビュアーをディスパッチします。review-code の境界を厳守してください。同じスレッドで代替対応を行わず、ファイルの編集、ステージング、コミット、プッシュ、PR コメント、レビューコメントの変更、その他の作業ツリーの変更を行わないでください。新しいレビュアーをディスパッチできない場合、または review-code が停止条件を報告した場合は停止します。

  11. ローカルレビューでの指摘は、Review Finding Router を通じて処理します。

  12. コミット、プッシュ、PR の作成または更新、表示可能なチェックの確認、PR フィードバックループ、マージ可能な状態になったことの報告には finish-pr を使います。ローカル検証と review-code が問題なしの場合、レビュー可能なローカル変更がないためスキップされた場合、またはすべてのローカル指摘に ready-for-agent、ready-for-human、wontfix のいずれかの処置が記録された場合に限り、finish-pr を呼び出します。

  13. 最終目標に到達するか、人間が対応すべきブロッカーによってそれ以上進められなくなるまで、ループを続けます。

長時間の実行中や再開可能な実行中は、最終報告で使う用語に沿って、issue の参照情報と URL、ブランチ名、最終状態、重要な変更、準備状況、ブロッカー、次のアクションを含む簡潔なチェックポイント状態を維持します。その状態から再開し、最終ワークフロー状態に到達するまで続行します。つまり、本番環境への準備が整っていることを示す証拠により goal-met が裏付けられるか、または human-blocked の停止が記録されている状態です。

レビュー指摘の振り分け

指摘を、次の結果のいずれか1つに分類します。

結果使用する条件次のアクション
ready-for-agent期待される動作が明確である、またはローカルで証拠を集められる明確な動作変更は implement に回します。根本原因が不明、再現手順がない、動作が不安定、またはパフォーマンスが低下している場合は diagnosing-bugs に回します
ready-for-human判断、外部へのアクセス、手動テスト、デザインに関する意見、不足情報、スコープの変更、プロダクト上の判断、権限、方針の不一致、またはイシューの範囲外で妥当な作業が必要ループを停止し、確認した証拠とともにブロッカーを報告します
wontfix指摘が古い、誤っている、リポジトリのルールに反する、または意図的に却下されている報告で丁寧に説明します。将来のレビュー担当者が同じ懸念を再度提起してしまう場合に限り、簡潔なコードコメントを追加します

v1 には needs-info の状態はありません。情報不足の場合は ready-for-human に分類します。

最終レポート

報告のガイダンス

進捗報告、中断後に再開できるチェックポイント、最終引き継ぎでは、何が変わったか、作業が完了可能な状態かブロックされているか、次に人が行うべきことを伝えます。判断のための検証証拠は内部に保持します。検証に失敗した場合、スキップまたは中断された場合、準備状況が変わった場合、ブロッカーの説明や残存リスクの特定が必要な場合、または人による次のアクションが必要な場合は、検証の詳細を報告します。

子スキルの出力は、成果、準備状況、ブロッカー、次のアクションが伝わる表現にします。進捗報告では現在のチェックポイントと次のアクションを示し、チェックリストを繰り返さないようにします。

ワークフローが停止したら、プロセスログではなく、まず人に向けて書きます。成果から始め、読み手が理解または対応するうえで必要な詳細だけを示します。

以下を含めます。

  • 何が変わったかを、意味のある箇条書きで1～3項目。
  • 作業の到達点。issue、PR、ブランチへのリンクを含めます。URL がある場合はリンクにし、ない場合は名前を明記します。
  • プロジェクトのステータス更新結果は、準備状況が変わった場合、失敗またはスキップされた場合、ブロッカーの説明になる場合、または人による次のアクションが必要な場合に限ります。
  • issue の自己アサイン結果は、失敗した場合、準備状況が変わった場合、または人による次のアクションが必要な場合に限ります。正常にアサインできた場合は記載しません。
  • 終端状態：goal-met または human-blocked。
  • 本番環境への準備状況の判断材料。
  • 検証コマンドと結果。最も有用なレベルで要約します。すべて成功した場合は、通常の検証を簡潔な1行にまとめます。
  • 追加または更新した関連テスト。
  • 子スキルの停止理由。ただし、人が次にすべきことが変わる場合に限ります。
  • ローカルレビューの結果と指摘への対応状況。
  • PR のレビューとチェックのフィードバック状況。
  • 最新の review-code の結果。レビュー可能なローカル変更がなかったためスキップした場合も、レビュー担当者の確信度または次のアクションに影響する場合に限り記載します。
  • 人が対応すべきブロッカーがあれば、その内容。
  • wontfix の説明があれば、その内容。
  • 具体的かつ関連性のある残存リスクまたはテストの不足に限ります。
  • finish-pr を実行した場合は、PR の URL と準備状況。

以下は明確かつ具体的に示します。

  • 失敗したチェック、スキップされたチェック、未解決のリスク、人による対応がまだ必要な事項。
  • 実行されなかった、または成功しなかった検証について、その正確なコマンドとブロッカー。
  • 実行時に必要なトークンまたは予算の報告。ただし、結果の後に記載し、報告の中心にしないでください。

以下は省略するか、最小限にします。

  • すべて成功した場合の、実行したコマンドの長い一覧。
  • lint、型チェック、テスト、フック、PR チェックがそれぞれ検証済みであることの繰り返し。
  • 「ステータスを確認し、差分をレビューし、チェックを実行しました」のような一般的なプロセス説明。
  • すべて成功している場合の、PR チェック項目の完全な一覧。
  • 人が次にすべきことに影響しない限り、マージ可能性、レビュー状況、無関係な未コミットファイルの状態。
  • すべて成功した場合の、クリーンなワークツリー、HEAD SHA の一致、マージ状態、チェック一覧、レビューコメント数などの finish-pr の準備条件。検証結果の1行にまとめます。ただし、ゲートの失敗によって人が次にすべきことが変わる場合は除きます。
最終出力の良い例

issue 190 の例：

Done: [#190](https://github.com/patinaproject/skills/issues/190) is implemented
on [PR #197](https://github.com/patinaproject/skills/pull/197)
([branch `190-human-focused-final-output`](https://github.com/patinaproject/skills/tree/190-human-focused-final-output)).

Changed:
- `develop-issue` final reports now lead with outcome and meaningful changes.
- Routine verification is collapsed unless something failed, skipped, or needs
  human attention.

Verified: routine checks passed.

Needs human attention: none before review.
最終出力の悪い例

プロセスの記録のような最終出力は避けてください。

Implemented issue #190.

Verification:
- develop-issue workflow test passed.
- markdownlint passed.
- type-check passed.
- commit hook passed.
- PR check Test Gate passed.
- PR check code-review passed.
- PR is MERGEABLE and CLEAN.

Child skills invoked: new-branch, implement, review-code, finish-pr.
No unrelated dirty files except local config. Goal marked complete.

悪い例の形式は避けるべき例としてのみ使用し、その構成をまねしないでください。

コメント

Markdown 対応