shepherd

Shepherd

中核となる原則

承認済みの PR または MR を、ノイズではなく根拠に基づいて進めます。ポーリングし、新たに対応可能な項目に対処し、各対象のローカル修正をまとめて 1 回のプッシュで反映してから、対応済みのスレッドを解決します。修正中は影響を受けるローカルチェックを実行し、統合された候補が重要な段階に達したら必須のフルチェックを実行します。CI は確認として利用します。明示的な権限なしにマージしてはいけません。

単発の確認、オープン中の対象がない場合、または人間の判断を要するアクションでは、継続的なポーリングを開始しないでください。状況を報告して終了してください。

手順

1. git remote get-url origin でプラットフォームを判定します。GitHub には gh、GitLab には glab を使用してください。判定できない場合や利用できない場合は、処理を止めて確認を求めます。Claude desktop の ccd_pr ツールなど、PR イベント発生時にこのセッションを起動する PR モニターをホストが提供している場合、ツールが一覧にあるものの使用が延期されていれば、まずそのツールを読み込み、その後はポーリングではなく ホスト管理のモニタリング に従ってください。プロジェクトコントローラーとそのチケットエージェントには、プロジェクトの待機ルールを適用します。セッションは一度に 1 つの PR にのみ紐づくためです。
2. 対象と、処理済み ID のスナップショットを確定します。そのスナップショットにない外部コメント、レビュー、スレッドはすべて新しいものです。セッション開始前のフィードバックも含みます。ポーリングのたびに、フィードバック ID、CI の状態、このコントローラーのコメントを記録します。各対象について、報告の責任者と修正の責任者を確定します。提示されたデリバリーレコードと、引き継がれた実装責任者を再利用してください。デリバリーレコードのない単独の PR では、既存の PR／報告コンテキストとシェパードのスナップショットを使用します。検証済みの PR とリポジトリの証拠から、ソース範囲、ベース／ヘッド、過去の判定、指摘事項とその対応状況を読み込み、証拠が不足している部分は不明として記録してください。引き継がれたワークフローの責任者がいない場合、権限を持つコントローラーは、対象のチェックアウト／ヘッドと競合する書き込み担当者がいないことを検証したうえで、対象範囲内の修正を担当できます。その場合は、コードを書き換える前、または実装修正を引き継ぐ前に、この代替措置を記録してください。責任者または書き込み担当者の状態が未解決でも、読み取り専用の監査では、検証済みの固定候補を調査できます。ただし、これらの不確実性は重大なものとして報告し、書き込み権限を与えたり公開のゲートを解除したりしてはなりません。コミットの作成者から責任者のハンドルを推測してはなりません。記録済みの責任者を維持してください。責任者が対応できない場合、既存の担当者の権限が不確かな場合、または書き込み担当者の状態が不明な場合は、整合性が取れるまでコードの書き込みを保留します。明示的な再割り当てを行う前に、書き込み担当者を必ず停止させてください。この代替措置によって、不足している範囲情報が補われたり、追加の権限が付与されたりすることはありません。修正がなくても、取得時および関連するイベントで PR レビューのタイミング に従い、該当する最新ヘッドのレビュー開始状況を確認します。単発の調査は読み取り専用で行います。
3. 定例の PR／MR の証拠はコントローラーで確認します。読み取り専用のヘルパーを使えるのは、失敗した大規模な CI ログに関する特定の診断上の疑問が 1 つある場合に限ります。共通の 選定と引き継ぎに関するリファレンス に従って選定し、依頼内容を伝えてください。対象、ヘッド、失敗したジョブとログ、疑問点、診断内容・根拠となるログの参照箇所・不確実性を含む範囲を限定した結果形式を正確に指定します。ヘルパーは状態を変更せず、ポーリングを引き継ぐこともありません。トリアージ、修正、返信、プッシュ、解決、再試行、マージは、権限を持つコントローラーが担当してください。
4. プロバイダーのコマンドを使ってプラットフォーム CLI でポーリングし、レビュー、コメント、CI の状態全体をスナップショットと比較します。失敗したログを調べるのは必要な場合に限ります。古いフィードバックを再処理したり、状態だけを伝える更新を投稿したりしてはなりません。ホスト管理のモニタリングでは、起動のたびに一度だけ読み込みます。タイマーやループを開始したり、ポーリングを繰り返したりしてはなりません。
5. リモートに変更を加える前に、新しい証拠をトリアージします。明確な依頼と、範囲の狭い書式、lint、コンパイル、テストの失敗を修正し、明確な質問には該当するスレッドで回答します。関連する境界事例、2 ラウンドの収束監査、レビューの網羅性、ブラウザーの失敗証拠については、動作レビューと修正を適用してください。手順 2 で確定した報告コンテキストと修正責任者を使用します。リモートへの変更は権限を持つコントローラーが引き続き担当します。アーキテクチャ上の問題や矛盾するフィードバック、見慣れない失敗、自明でない修正、範囲外の競合はエスカレーションします。別途指示がない限り、GitLab の手動ジョブはブロッキングではありません。
6. 各対象はそれぞれのヘッドのチェックアウトで扱い、対応可能な既知の項目はまとめて処理します。修正に取りかかる前に、失敗したログを調べ、実際のワークフロー／チェック設定から適用可能なローカル相当のチェックを特定します。証拠が不足している場合は、修正を推測する前に証拠を入手します。このホストで利用できないチェックは、利用できないことを正直に報告してください。修正中は対象を絞ったチェックを実行し、引き続き有効な証拠を再利用します。プッシュ前には、意味のある統合済み候補に対して必要な全チェックを実行します。ただし、PR の必須 CI が同じ全テスト一式を実行し、リポジトリまたはプロバイダーのルールでローカル実行が求められていない場合は例外です。その場合は、プッシュしたヘッドの CI がデリバリーの受け入れまたはマージ前の証拠になります。プッシュ前に、PR レビューのタイミングに従って該当する独立レビューを取得するか、更新してください。リポジトリ／プロバイダーのより厳しいルールを優先し、影響を受けるチェックを更新するか、影響が不明な場合はチェックの範囲を広げてください。 CI を反復的なテストランナーとして使ったり、コミットの一部ごとに全チェックを要求したりしてはなりません。プッシュ前に必要なチェックが失敗している、または証拠がない場合は、プッシュを保留します。CI が提供する全テスト一式は、受け入れまたはマージのゲートとして扱います。ヘッドが変更されるたびに、PR レビューのタイミングに従って証拠を再評価し、修正をプッシュする前に、影響を受ける独立レビューを更新してください。 変更を反映した後、または回答後に返信します。返信と必要なプッシュが成功した場合に限り、該当スレッドを解決します。複数のヘッドをまとめたり、コメントのたびにプッシュしたり、ローカルだけで修正した項目を解決したり、変更がないのにコメントしたりしてはなりません。
7. 検証済みの修正をプッシュした後、CI を再確認します。コードに関係する失敗が再び起きた場合は、手順 6 に戻ります。GitLab のジョブが不安定な可能性がある場合は、コードを変更せずに一度だけ再試行し、2 回目の失敗は報告します。保留中のチェックは 2～5 分ごとに、修正作業中は 30～60 秒ごとにポーリングします。変化のないサイクルが 3 回以上続いたら、以降は 10 分以上の間隔にします。変化のないサイクルが 2 回の場合は、通常どおり 2～5 分の間隔を維持します。ホスト管理のモニタリングでは、プッシュ後にターンを終了してください。
8. 対象のヘッドを正確に更新します。必要なチェック、レビュー、指摘事項への対応がすべて合格し、そのヘッドに適用され、競合がなく、ユーザーから明示的または常設のマージ権限が与えられている場合に限り、マージします。承認だけから権限を推測してはなりません。ホスト管理のモニタリングでは、CI が成功してもセッションは起動しません。そのため、保留中のリモートゲートには、PR レビューのタイミングにある検証済みの適用ルールを使用し、エスカレーション時には、このコントローラーが有効にした auto-merge を無効にしてください。

完了またはエスカレーション

ユーザーが監視を停止するか、すべての対象がマージまたはクローズされるか、エスカレーションが必要になるまで続行します。対象、現在の CI／レビュー状況、実施したアクション、実際に実行したチェック（実行していない場合は「なし」と記載）、利用できない、または不明なチェック、次に必要な人間の判断を報告します。ホスト管理の監視下では、監視が起動しないイベントも明記します。修復サイクルを説明する際は、次の順序にします。失敗したログを調査する（ログがない場合は、チェックの正確な名前、ログ、PR の差分、ヘッド、チェック設定を求め、特定できていないローカルの代替チェックがあれば明記する）。その PR の明確なレビュー依頼と修正をまとめて行う。必要なホスト上で、影響を受ける CI 相当のチェックを実行する。引き続き有効な証拠を再利用する。ステップ 6 に従って統合候補のチェックを完了する。一度だけプッシュする。CI を確認として使用する。未実施のステップを実施済みと主張してはいけません。プラットフォームまたは対象の選択が曖昧な場合、未解決の競合がある場合、重要な人間の判断が必要な場合、レビュー担当者の指示が相反する場合、または 3 回の修復サイクル後も失敗が解消しない場合は、直ちにエスカレーションします。