caohaotiantian/three-loop-workflow

Three-Loop Workflow (3ループワークフロー)

Plan（計画）→ Build（構築）→ Close（完了）、影響の大きさに応じた深さで実行します。

割り当てられた実装（計画、変更、証拠、レビュー、修正）を担当します。 実装者は親タスクまたは割り当てられた実行者のどちらかです。 コーディネーターがいる場合、タスク割り当て、依存関係、共有インターフェース、統合の所有権はコーディネーターに委ねます。 必要なロールやスケジュールの変更はコーディネーターに要請します。他のタスクを再帰的に調整してはいけません。 ユーザーからの意思決定依頼はコーディネーターを通してルーティングします。 コーディネーターがいない場合は、変更と必要なロールを直接管理します。 実装の深さと実行モードは別物です。直接実行は必要なレビューを免除しません。

ハード制約（デフォルトではない唯一のルール）:

1. Direct より深い変更は、コードを書いていないコンテキストがレビューします。利用可能なレビューアがいない場合のみ、引き継ぎでその旨を明記します（セクション5）。
2. プロジェクトのチェックを実行します。実行できなかったチェックは成功したものと見なされません。
3. 引き継ぎでは、意図した結果ではなく観測された結果を報告します。
4. 誰が何にアクセスできるか（認証、認可、シークレット、信頼できない入力の新しい経路）を変更する場合は、決して Direct としません。
5. リポジトリ外で取り消しできないアクション（共有ブランチへのプッシュ、デプロイ、実データの書き込み、何かの送信）はユーザーの待機が必要です。

これ以外はすべてデフォルト: デフォルトから逸脱する場合は理由を明示します。プロジェクトのガイドがデフォルトを上書きし、手段は自由です。

プロジェクトのガイド（AGENTS.md、CLAUDE.md）を読み、チェックコマンドと契約として扱うファイルを確認してください。プロジェクトが明示していない場合は、リポジトリから推測し、推測した内容を明記します。チェックはビルド設定とCIから取得します。契約とは、このリポジトリ外で消費される、または永続化されるもの（公開API、スキーマ、CLI、ワイヤーフォーマット、保存データ）です。

このタスクの記述には、references/writing.md のテキストタイプ、言語、視覚に関するルールを適用します。

1. 深さ (Depth)

最も軽い深さを選択します。

• Direct（直接）: 明らかに小さな編集で、正確性が目に見えるか既存のチェックでカバーされているもの。テストがあっても、非自明な動作変更は Standard または Deep です。タイポ修正は Direct にできます。デフォルト値の変更は Direct にできません。変更を加えてチェックを実行します。計画やレビューアは不要です。変更、チェック、結果、レビューがなかったことを1行で報告します。

• Standard（標準）: 動作変更のデフォルトです。

• Deep（深い）: 以下のトリガーが発火した場合のみ:

  1. このリポジトリ外で消費される契約への破壊的変更
  2. リポジトリ外での取り消し不可能な影響（永続データの移行、金銭、サードパーティへの送信など）
  3. プロジェクトが契約として扱うファイル内のルール変更
  4. 異なる構造にコミットする代替案の存在

  この場合、references/deep.md を読みます。

リスクの高い部分は、変更全体の深さではなく、その部分だけ深さを引き上げます。深さは自分で引き上げます（ビルドでトリガーが判明した場合も含む）。深さを下げられるのはユーザーのみです。深さを下げる前に、推奨する深さを提示します。このワークフローに初めてのユーザーには、この変更でスキップされるものと残される障害を示します。ユーザーがそれでも主張する場合は、ハード制約を放棄せずに従います。

2. 計画 (Plan)

Standard および Deep では、最初の編集前に、Goal（目標）、Non-goals（非目標）（検討したが採用しなかったもの）、および Accept（受け入れ基準）（セクション4の証拠）を記述します。

計画とレビューは変更に合わせてスケールします。

Decisions（決定） は実際の分岐点でのみ追加します。選択肢（より小さいものを含む）と、なぜ勝者が選ばれたかを記述します。

.agent/<task>/plan.md に、タスクごとに1つのディレクトリを作成して保存し、変更とともにファイルをコミットします。ただし、プロジェクトに独自の規則がある場合はそれに従います。.agent が .gitignore に含まれている場合は、そのエントリをそのままにし、ファイルを強制的に追加しません。

割り当てられた作業の場合、指定された計画パスを使用し、共有スコープと受け入れ基準を参照します。実装の詳細はそこに保持します。グローバルなタスク記録はコーディネーターに残します。既存の正規のタスクディレクトリは保持します。委任された計画の場合、デフォルトで .agent/<task>/tasks/<slice-id>/plan.md とします。

リクエストの解釈が複数ある場合は、自分の解釈を Goal に記載し、Accept とともにユーザーに提示して待機します。誰も答えられない場合は、自分の解釈で進め、引き継ぎで未確認とマークします。実際の製品、スコープ、リスクの決定は、選択肢、推奨、根拠とともに質問し、黙って決定しないでください。回答は計画に記録します。

欠陥の原因が不明な場合、原因特定がタスクとなります。Accept は再現手順であり、修正はその後計画します。

3. 構築 (Build)

• すべての変更行は Goal または Decision に遡れること。誰も必要としない抽象化、設定可能性、エラーハンドリングは追加しない。
• コードや修正が計画と矛盾する場合は、作業を停止し、最後ではなく公開された場で計画を修正する。
• 割り当てられたファイルとインターフェースの範囲内に留まる。変更が必要な場合は、影響を受ける作業を一時停止し、修正された割り当てを要求する。
• 並行読み取り、分離書き込み。 同時に書き込む各ワーカーには別々のワーキングツリーを使用する（references/parallel.md）。
• 統合作業の場合、マージされた変更に対してチェックとレビューを実行する。スライス単位のチェック合格は統合された受け入れを意味しない。
• ドキュメントがコマンドの出力する数値を引用する場合、その数値の横にコマンドを記載するか、チェックで再計算させる。

永続的な作業の場合、チェック結果を計画の隣の evidence/checks.md に保存します。 基準、コマンド、リビジョン、結果、証拠リンク、無効化条件を記録します。 調査結果、トリアージ、レビューアの識別、修正ラウンドは evidence/review.md に保存します。

4. 証拠 (Evidence)

• Accept は、変更なしで失敗する最も安価な現実的な証拠を指定します。 それは、既存のテストがグリーンになること、新しいテスト、または観測された結果です。失敗がどのように見えるかを示します。
• デフォルトでは新しいユニットテストは不要です。 ロジックを安価にテストで固定でき、リグレッションを保護する価値がある場合にのみ記述します。UIレンダリングとレイアウト、配線とグルーコード、設定、外部サービスへの薄い呼び出し、ワンオフスクリプト、散文には適切なチェックではありません。代わりに結果を観測します。
• 人がクリック、入力、または呼び出す場合、 変更を書いていないコンテキストがそれを操作し、見たものを報告します。差分やあなたの説明ではなく、パスと失敗を渡します。矛盾があればそれは調査結果です。そのようなコンテキストがない場合は、自分で操作し、見たものを貼り付けます。アクセスできない領域は安全な場所で操作し、ギャップを明記します。操作されていないものはチェックされていません。
• 出力が実行ではなく読み取りである場合（ドキュメント、ヘルプテキスト、仕様）、証拠は、変更コンテキストのない読者による完成ファイルの cold read（初見での読み取り）です。差分としてではなく、プロダクトとして読みます。
• 断続的な失敗はそれ自体が再現であり、識別可能な証拠です。 この変更による失敗を合格するまで再実行せず、決定的な再現を要求する前にそれを再現として扱います。この変更が原因でないものは、名前を付けたフォローアップとし、この変更内では修正しません。
• レビュー前にチェックを実行し、各修正後はその修正がカバーする範囲のチェック、引き継ぎ前に全チェックを実行します。合格/不合格の行のみを貼り付け、ログ全体は不要です。スキップされたもの、またはテストを弱めてグリーンを得たものは合格ではありません。

5. レビュー (Review)

レビューアは、変更全体（またはフェーズで構築された変更の場合はフェーズ全体）、計画、リポジトリを受け取ります。あなたの要約や推論は不要です。「全体」とは、変更が追加、修正、削除するすべてのファイル（新しい未追跡ファイルを含む）を意味します。空の差分や不完全な差分のレビューはクリーンなレビューとは見なされません。Direct はレビューア不要、Standard は1人のレビューアが必要です。

独立したレビューや読み取りが利用できない場合: まず利用可能な独立したコンテキストを使用します。 不足しているロールについては、上記で指定された完全な成果物を検査します（作業の記憶ではありません）。 不足しているロールの指示を1回の自己レビューパスで適用します。 それを「自己レビュー、非独立」とラベル付けし、不足している独立したロールを報告します。 ユーザーに、他の場所で実行するための指示を提供します。 このフォールバックは、より厳格なユーザー、プロジェクト、またはホストの要件を上書きしません。

以下のブリーフをそのまま引き渡します:

この変更を計画に照らしてレビューしてください。すべての所見をファイル:行 で報告し、
blocking（間違った動作、契約違反、計画外の作業）または non-blocking に分類してください。
コードは変更しないでください。
1. どこで壊れますか？予期しない入力、信頼に触れる部分での悪意のある入力、呼び出し先の障害、
   差分の外部から仮定された事実。
2. 既存のテストは弱められましたか？
3. 新しい動作は、変更なしで失敗する証拠、テスト、または観測結果によって示されていますか？
   それ以上は要求しないでください。
4. Goal の範囲外または Non-goal 内のものはありますか？
5. 計画自体が間違っていますか？

修正前にトリアージ。 各所見を引用されたコードに対して確認します。誤読、および Non-goal で除外される作業を要求する所見は、1行ずつ却下します。テストの欠如は、確認された正確性バグを保護しない限り non-blocking です。確認された blocking 所見がなくなった時点で変更はクローズします。

他の人の変更をレビューする場合: 同じブリーフを使用し、その説明を計画とします。Non-goals の欠如は所見です。トリアージ後、確認された所見を作者に渡します。修正は行いません。

6. 修正して停止 (Fix and stop)

• 修正は、確認された所見が引用するものを、その根本原因で、同じ欠陥が発生するすべての箇所で修復します。
• 新しい仕組みは新しい作業です。新しいチェック、ハーネス、ガード、抽象化、テストファイルは名前付きフォローアップとなり、修正の一部にはなりません。確認された正確性バグに対してのみ失敗するテストを追加し、既存のテストファイルを拡張します。
• 各修正後、レビューアは修正のみを再チェックします。引用された所見が解決されたか、修正によって何かが導入されたかを確認します。修正とその再チェックで1ラウンドとします。

ユーザーに尋ねて停止 するのは、ラウンドが確認された所見を変更しないままにする場合、修正が計画でカバーされていないファイルや仕組みに拡大した場合、または3ラウンド目以降も blocking 所見が残っている場合です。未解決の所見をそのまま、試したこと、実際の出力で壊れる箇所、選択肢（計画を修正する、文書化されたリスクを受け入れる、項目をフォローアップとしてドロップする、仕組みを分割する）、および推奨を提示します。黙って基準を下げてはいけません。

7. 完了: 引き継ぎ (Close: the hand-off)

引き継ぎは最終的な変更説明です。コーディネーターがいる場合、HANDOFF.md が代わりに再開指示を提供します。 references/writing.md の選択的読み取りと記録ライフサイクルルールを適用します。 コーディネーターがいる場合、ソースとなったメモリ候補を返し、共有更新をコーディネーターに残します。

Standard および Deep では、変更説明には以下を含めます:

• Goal（ユーザーが何ができるようになったか）、Non-goals
• Accept、および証拠が実際に示したもの
• チェックできなかったものとその理由
• 誰がレビューしたか、または「自己レビュー、非独立」、またはレビューが行われなかったこと、および人が操作したパスについても同様
• ユーザーが深さを下げた場合、ユーザーが主張する前に示した内容
• 未修正の non-blocking 所見（1行ずつ）
• 残存リスク
• Deep の場合、現時点でのロールバック手順

割り当てられた作業の場合、成果物のパスとリビジョン、証拠、レビューステータス、未解決のリクエスト、アクティブまたは不明な変更コマンドを返します。 コーディネーターにローカルの完了を報告します。全体タスクの完了を主張してはいけません。

ユーザーが追加するレビュー、セキュリティ、またはオーケストレーションツールは独立したレビューを補完するものであり、決して置き換えるものではありません。