Issue Flow — 共有の課題トラッカー上でのアナリスト/デベロッパーワークフロー
アクティベーション契約
以下の目的で使用: issue-flow analyst [conditions]、issue-flow dev [domain-rules] [issue-number]、アナリストもしくはデベロッパー作業、クレーム、ワークフロー状態遷移。
アナリストのconditionsとdevのdomainsは省略可能です。バインドされた対象がスコープとなります。それ以外の場合、アナリストはリポジトリ全体を監査し、開発者は選択された課題を実装します。
まずリポジトリの指示を読み、トラッカー作業の前にオペレーター設定で選択されたトラッカーバインディングのみをロードしてください。
ハンドオフ、優先度、ルーティングルールについてはドメイン構成を、呼び出し、委任、チームメカニクスについてはランタイムノートを、競合、再クレーム、ハンドオフ、障害の根拠についてはセーフティインシデントをロードしてください。
ハードルール
- Issue Flowはロール、状態、クレーム、遷移を所有します。ルーティングされたドメインは、価値、優先度、証拠、完了基準を所有します。どちらの側も相手のポリシーを独自に定義してはなりません。
- アナリスト（ adversial reviewerを含む）は、以下で必要な設定済みトラッカー操作を除き、リポジトリおよびすべての外部システムに対して読み取り専用です。ブランチ/ワークツリー/コミット/PRを作成せず、マイグレーション、同期、データベース書き込み、デリバリーアクションを実行しません。最大1つの証拠付き課題を起票します。レビューは変更を書き込んでいないコンテキストを使用しなければなりません。
<runtime>-<session-prefix>形式のrun-idを一つ生成し、すべての書き込みで再利用します。analyst:<runtime>/dev:<runtime>ラベルに有界なランタイム帰属を保持し、テキストには無界なrun-id帰属を保持します。アナリストラベルは永続し、devラベルはリリース時に削除されますが、デリバリー時には保持されます。- キューを参照する前に、この実行で保持されている課題を再開します。選択されたバインディングのタイムライン調整済みクレームを使用します。最も早い生存クレームが優先されます。リポジトリへの最初の書き込み前、すべてのハートビート、すべての高コストまたは不可逆な境界で
verify_claimを実行します。読み取り不可能なコントロールサーフェスは、書き込みを許可しません。 analysis、ready、in-progress、review、blocked、doneのうち正確に1つを維持します。バインディングのワークフロー状態が権威です。設定されたすべてのプロジェクションが更新され読み戻され、トラッカーを閉じる前にdoneが明示されます。- 選択されたバインディングは、
ensure_states、create、list_state、claim、reclaim、verify_claim、heartbeat、transition、comment、last_activity、label、unassign、publish_version、closeをマップしなければなりません。実行可能な可逆操作を、再構築せずに実行します。バインディングはサポートされていない機能を宣言し、フェイルクローズしなければなりません。 - 課題の受け入れ基準、ルーティングされたドメインルール、およびリポジトリルールがdoneを定義します。欠落しているゲートを作成したり、課題を黙って再解釈したりしてはなりません。
決定ゲート
| 状況 | アクション |
|---|---|
| アナリストにconditions、または有界なdiff/PR/issueがある | 該当するリポジトリルールとドメインルールの下で、そのスコープのみを分析する。 |
| アナリストにconditionsもドメインもない | ドメイン構成の自律的な general 契約を使用する。最強の重複排除された所見のみを提出するか、何も提出しない。 |
| ドメインルートが記録されている | アナリストは左のルールブックをロードし、デベロッパーは右のルールブックをロードする。実装ルーティングがない場合は明示的に述べる。 |
| ランタイムメカニクスや独立コンテキスト取得が異なる | ランタイムノートに従う。ランタイム制限はメカニズムを変更し、不変条件は変更しない。 |
| クレーム、再クレーム、またはハンドオフの安全性に根拠が必要 | アクティブなバインディングとセーフティインシデントに従う。インシデントの内容をここにコピーしない。 |
| 状態を選択する必要がある | 仕様が無効→analysis；実装可能かつ未割り当て→ready；クレーム済みビルド→in-progress；ビルド済み/公開済み→review；未ビルドの外部待機→条件と解放者とともにblocked；マージ済みかつ検証済み→done。 |
実行手順
どちらかのロールが、馴染みのないプロジェクトで最初のトラッカー書き込みを行う前に、選択されたバインディングの ensure_states を実行します。その後、そのバインディングの実行可能な操作と読み戻しを、再構築せずに使用します。
ルーティング、スケール検証、キュー分割、自律フォールバックについてはドメイン構成を、呼び出し、読み取り専用の強制、独立コンテキストの取得、ランタイム制限についてはランタイムノートを、クレーム、再クレーム、ハンドオフ、障害の根拠が必要な場合のみセーフティインシデントを、リポジトリルールが分離や統合を完全に定義していない場合のみリポジトリデリバリーをロードしてください。
アナリスト
- リポジトリと非トラッカー外部システムを読み取り専用に保つ。
analysisを最も古いものから順にドレインし、次にblockedを検査する：解放された条件を証拠とともにreadyに移動し、まだ有効な条件には日付を記録し、保留中の決定を誰がいつまでに返すべきかを記録する。 - 左側のドメインルールブックの下で、有界なスコープのみを分析する。conditionsもドメインもない場合、自律的な
general契約を使用する。証拠と重複を検証し、最も強力な防御可能な所見を最大1つ保持するか、またはどれも残らなかったことを報告する。 - キューされている所見と新しい所見について、フィールド、ルート、スケール、本文契約を検証する。キューされている作業については、
commentで不足しているハンドオフ資料を追加し、同じ完全なアイテムのみを遷移させる。置き換えを作成してはならない。新しい所見については、アナリスト課題テンプレートに記入し、すべてのマーカーとanalyst:<runtime>および run-id 帰属を付けてcreateする。readyを使用するか、不足している正確な条件と解放者を指定してblockedを使用する。その後、実装や割り当てを行わずに STOP する。
アナリストが生成するもの
開発者が 分析をやり直すことなく 取り組める課題。開発者があなたの推論を再導出する必要がある場合、分析には価値がありません。
## 人間向けの説明
> [!NOTE]
> 1～2文、平易な言葉、専門用語なし、ファイルパスなし、メトリクスなし — この行を超えて読むことのない人向けに、この課題が何に関するものかを説明します。このインストールのオペレーター設定で指定された言語で記述します（このファイル末尾の表を参照）。ヘッダー自体は上記の固定されたリテラルタイトル — 常に英語で、常にその正確なフレーズで、課題ごとに言い換えてはなりません。`> [!NOTE]` はGitHubのネイティブアラート構文です — これは境界線と色付きのコールアウトとしてレンダリングされます。これがポイントです：技術的な散文で埋め尽くされた課題上で、視覚的に見逃せないものでなければなりません。
これは `## Problem` の前に、課題の最初に配置されます。
## Problem
何が間違っているのか、あるいは欠けているのか、そしてそれをどうやって知ったのか。証拠であって、主張ではない：ファイル:行参照、測定数値、ログ、再現手順。
## Why it matters
放置した場合の影響。影響を述べられない場合は、その旨を率直に述べてください — 「影響は低い、完全性のために提出」は正直であり、開発者が優先順位を下げることを可能にします。
## Proposed approach
設計。検討した代替案と、なぜ却下したのか。確信が持てない場合は、どの部分が不確かで、何がそれを確定させるかを述べてください。
## Acceptance criteria
チェック可能なステートメント。「より速く」は基準ではありません。「Xによって測定されたp95が200ミリ秒未満」が基準です。変更してはならないもの（不変条件、バイト同一の出力）を含めてください。
## Out of scope
開発者がここで明示的に行わないべきこと。これは、上記のセクションのどの散文よりも確実にスコープクリープを防ぎます。
## Evidence
実行されたコマンド、読み取られたファイル、測定された数値。レビュアーが分析を繰り返さずに再確認できる十分な量。
開発者
- キューを参照する前に、この実行で保持されている課題を記録された状態で再開する。それ以外の場合、未割り当ての
reviewをreadyより先にドレインし、公開された作業をクレームする前にデリバリーブロッカーを再確認する。 readyの場合、安定したドメインと宣言されたスケールで有効な候補を分割し、各パーティション内でのみランク付けし、最も古いパーティションヘッドを選択する。選択されたドメインは、その最高ランクの最も古いアイテムに選択を制限する。有効なスケール契約を持つ候補がない場合のみ、最も古いものを優先する。- run-idと期間で
claimし、サーバータイムスタンプ付きのタイムラインを裁定する。最も早い生存クレームが優先され、敗者はコメントし、リリースし、再度選択する。クレームされたレビュー作業は、コード変更がin-progressと新しい公開/レビュー/CIサイクルを必要としない限り、reviewに維持する。準備完了の作業については、dev:<runtime>と2回目のクレームイベントなしで、一度in-progressに遷移する。 - 計画の前に、ルートの右側の実装ルールブックをロードする。存在しない場合は、該当するものがないことを明示し、書かれた受け入れ基準に従って構築する。リポジトリルールに従い、欠落した分離/統合ポリシーにはリポジトリデリバリーフォールバックを使用する。最初のブランチ/ワークツリー/ファイル書き込みの直前にクレームを検証し、隔離されたチェックアウトで実装する。
- 公開前にリニューアルし、共有レビュー対象を公開または再利用してから
reviewに遷移する。Review delegationがこの実行を許可する場合のみ、独立したコンテキストを取得する。そうでなければ、別途開始されたレビューを要求する。その正確な同じhead/baseで、その判定とグリーンCIの両方を要求する。すべてのプッシュは両方を無効にする。ブロックされたデリバリーはreviewに残し、失敗した試行で変更したローカル状態を復元し、正確なブロッカーを記録し、それを迂回せずに割り当てを解除する。矛盾するリポジトリルールは別の課題とする。 - 各不可逆的な境界でリニューアルする。レビュー済み、グリーン、かつ現在のhead/baseの同一性が一致する場合のみマージする。マージコミットルートの場合、配信されたSHAの正確な親がレビューされたベースとヘッドであることを要求する。その他の設定された戦略は、バインディングで宣言された同等のトポロジーと、配信されたSHAゲートがあればそれを要求する。変更されたバージョンごとに、その不変の注釈付きタグと必要なリリースを公開し、リモートで検証する。再びリニューアルし、
doneに遷移し、run-idとともにレビュー/CI/テスト/測定値/PR/配信SHA/公開を記録し、閉じる。ハンドオフ時には、すべての証拠を保持する：誤った仕様はanalysisに、未ビルドの外部待機はblockedに、ビルド済みで配信不可の作業はreviewに、有用な部分診断はreadyに。
最終リタイアメントスライスまで保持される詳細なレビューゲート
-
公開された変更を、それを書き込んでいないコンテキストでレビューしてもらい、最新のPRヘッドでグリーンCIを要求する。 レビュー前にヘッドとベースのSHAをキャプチャし、判定アーティファクトにその両方が明示的に指定されていることを要求する。浮遊する「承認」は、特定のリビジョンや差分に対する証拠にはなりません。設定がそれを許可する場合、サブエージェントやチームメイトなど、自分でそのコンテキストを取得してください。許可しない場合は、PRを別途開始されたアナリスト実行に委ね、課題上でそれを待っていると述べてください。設定が決定するのは誰がレビューを開始するかであり、それが実行されるかどうかではありません。すべてのプッシュは、以前の判定とCI結果を無効にします：変更されたサーフェスを再レビューし、必要なチェックが再度完了するのを待ちます。
レビュー、CI、またはデリバリーがブロックされた場合は、その場で停止し、
reviewに残します。ビルドおよび公開されたが、出荷できない作業 — レビュアーが変更を要求する、チェックが失敗する、必要なネイティブ承認を別のIDが提供できない、権限がない、2つのプロジェクトルールが互いに矛盾する — は 配信を待っている完了した作業 であり、それがまさにreviewの意味です。doneに移動しないでください：その状態は配信されたことを示します。ブロッカーを回避して作業しないでください。出荷するために迂回したルールは、意味をなさなくなります。ブロッカーを正確にコメントしてください — 何が拒否したのか、その対象が何を期待しているのか、プロジェクトが代わりに何を要求しているのか — その後、別のアクターがデリバリーを完了できるように割り当てを解除してください。試行中に変更したローカル状態を復元してください。
2つのプロジェクトルールが互いに矛盾することから生じるブロッカーは、それ自体が別の課題に値します。 それは次のタスク、そしてその次のタスクでも発生し、各実行が毎回スクラッチから再診断することになります。1つの提出された所見によって、繰り返し発生する税金が、誰かが一度決定できるものに変わります。
-
必要なCIがグリーンになったレビュー済みのPRヘッドのみをマージし、バージョンタグがあれば公開してから
closeする。 マージの直前にクレームをリニューアルし、reviewed head/base == CI head/base == current head/baseを要求し、マージをレビュー済みのヘッドSHAにバインドし、どちらかの側が動いた場合は拒否する。設定されたマージ戦略を使用する。merge commitはブランチ境界とPR祖先を保持しますが、スカッシュとリベースはその情報を意図的に破棄します。マージ後に配信されたSHAを取得し、それがレビューされたベースとレビューされたヘッドを正確に親として持つことを検証する。コマンドフラグだけでトポロジーの保存を主張してはなりません。マージキューは、その設定されたメソッドが同じトポロジーを保証する場合にのみ使用可能です。プロジェクトが正確な配信されたSHAでCIを必要とする場合、そのマージ後のゲートを待ちます。
リポジトリでの作業 — デフォルトフロー
リポジトリのルールが常に優先されます。 他のすべてよりも先に、そのエージェント指示（AGENTS.md、CLAUDE.md または同等）を読み、それに従ってください。以下は、何も規定していないリポジトリのフォールバックであり、一部のみを規定しているリポジトリの下限です — 決して競合する標準ではありません。
以前のフォールバック — コミット履歴を慣例として使用する — はここまで及びません。その理由を述べる価値があります。gitログはコミットメッセージの書き方を教えてくれます。2つのエージェントが同じチェックアウトを共有できるかどうか、1時間前に検証されたブランチが他の誰かがマージした後でもまだ有効かどうかを教えてくれません。これらの答えは並行作業が自己破壊するかどうかを決定するため、このスキルはそれらを提供し、理由を知るはずのないドメインに委ねません。
1. ベースツリーで作業してはなりません。 開発者にとって、デフォルトブランチは読み取り専用です：編集もコミットもできません。想定せずに、最初の変更の前に確認してください：
git branch --show-current # main / master -> 停止、まずブランチを作成
既にベースブランチにコミットしており、プッシュしていない場合は、コミットをブランチに移動し、リセットしてください。既にプッシュしている場合は、force-pushしないでください — 元に戻して適切にやり直してください。
…
[以下、翻訳対象外のため省略]