user-input-protocol

ユーザー入力プロトコル

価値観： 尊重 — 重要な判断は開発者の判断に従います。エージェントは、質問すべき場面で決して憶測しません。

目的

判断が必要な場面で、エージェントが人間に入力を求めるための構造化された形式を定義します。開発者に代わってエージェントが憶測するのを防ぎ、十分な情報に基づいて判断できるだけの背景を質問に含め、ユーザーに直接質問できないサブエージェント向けに、一時停止と再開のパターンを提供します。

プラクティス

作業を止めて提示し、決して憶測しない

人間の判断が必要な決定に直面したら、直ちに作業を止めます。推測してはいけません。「最も可能性が高い」選択肢を選んではいけません。決定事項を明確に提示し、回答を待ちます。

人間の入力が必要な決定：

• ビジネスルールの曖昧さ（有効な解釈が複数ある）
• アーキテクチャ上のトレードオフ（パフォーマンスとシンプルさなど）
• スコープに関する質問（この機能に X を含めるべきか）
• 破壊的な操作（ファイルの削除、強制プッシュ、データの削除）

人間の入力が不要な決定：

• 明らかに正解が一つある実装の詳細
• プロジェクトの規約で定められている書式、命名、スタイルの選択
• 要件が曖昧でない場合のテスト構成

AWAITING_USER_INPUT 形式を使用する

入力が必要なときは、次の構造化されたチェックポイントを出力します。

AWAITING_USER_INPUT
---
Context: [Why you are asking -- what you were doing and what you found]
Decision needed: [The specific question, one sentence]
Options:
  A) [Label] -- [What this means and its implications]
  B) [Label] -- [What this means and its implications]
  C) [Label] -- [What this means and its implications]
Recommendation: [Which option you suggest and why, or "No recommendation"]
---

チェックポイントのルール：

• 背景には、質問に至った経緯を説明します（「入力が必要です」だけでは不十分です）
• 具体的な選択肢を 2〜4 個提示します。自由回答形式で「どうすればよいですか？」と尋ねてはいけません
• 各選択肢には、ラベルだけでなく、その選択がもたらす影響を含めます
• 推奨案がある場合は明記します。開発者は別の案を選択できます

例：

AWAITING_USER_INPUT
---
Context: While implementing the login endpoint, I found two email validation
patterns in the codebase. auth/validate.rs uses strict RFC 5322 parsing.
signup/forms.rs uses a simple regex check. These produce different results
for edge cases like "[email protected]".
Decision needed: Which email validation approach should be the project standard?
Options:
  A) Strict RFC 5322 -- rejects fewer valid addresses, more complex to maintain
  B) Simple regex -- faster, but may accept malformed addresses
  C) Context-dependent -- strict for auth, lenient for forms
Recommendation: A) Strict RFC 5322, applied everywhere for consistency
---

一時停止前に状態を保存する（サブエージェント）

サブエージェントやバックグラウンドタスクは通常、ユーザーに直接質問できません。サブエージェントが入力を必要とする場合は、作業を最初からやり直さずに再開できるよう、一時停止する前に進捗を保存する必要があります。

一時停止前に保存する状態：

1. 実行していたタスク
2. 作成または変更したファイル
3. 完了した分析
4. 作業を妨げている具体的な決定事項
5. 再開後すぐに続行できるだけの背景情報

状態の保存先は、実行環境によって異なります。

• タスクのメタデータ（Claude Code：メタデータを指定した TaskUpdate）
• ファイルシステム（一時ファイルに JSON チェックポイントを書き込む）
• メモリツール（利用可能な場合は MCP サーバー）

状態を保存したら、AWAITING_USER_INPUT チェックポイントを出力して停止します。オーケストレーターまたはメインの会話が一時停止を検出し、ユーザーに質問を提示した後、回答を添えてサブエージェントを再開します。

作業をやり直さずに再開する

ユーザーの回答を受けて再開したら：

1. 保存した状態を取得します
2. 必要なファイルと背景情報が揃っていることを確認します
3. ユーザーの決定を適用します
4. 停止した箇所から続行します

すでに分析したファイルを再分析してはいけません。すでに保存した背景情報を読み直してはいけません。状態を保存する目的は、すぐに再開できるようにすることです。

行うこと：

• 「厳密な RFC 5322 を選択されました。ログインエンドポイントに適用します。」

行わないこと：

• 「メール検証の仕様を理解するために、コードベースを再分析します……」

ファクトリーモードでの一括判断

パイプラインまたはファクトリーワークフロー内で実行する場合、すべての判断のたびにパイプラインを停止させないでください。判断を分類し、適切な方法で処理します。

• ゲートで解決可能： 人間に尋ねてはいけません。品質ゲートが答えを提示します（テストの合否、ミューテーションスコア、CI の状態）。これらは完全に自動化されています。
• 判断が必要： 次回の人間によるレビューサイクルにまとめます。例：レビュー中に浮上した設計上のトレードオフ、優先順位付けが必要な、進行を妨げないレビュー指摘、ふりかえりの提案。
• ブロッキング： パイプラインを直ちに一時停止します。例：レビュー中に指摘されたセキュリティ上の懸念、3 回の修正サイクル後も解決できないゲートの失敗、正確性に影響する曖昧な要件。

ゲートで解決可能な判断が AWAITING_USER_INPUT チェックポイントに表示されることはありません。判断が必要な項目は収集され、人間によるレビュー段階で 1 つのグループ化されたチェックポイントとして提示されます。ブロッキングの判断には、標準の AWAITING_USER_INPUT 形式を直ちに使用します。

ファクトリーモードで AWAITING_USER_INPUT を出力する場合は、区切り文字の後に urgency フィールドを含めてください。

AWAITING_USER_INPUT
---
Urgency: blocking | next-review | informational
Context: ...
Decision needed: ...
Options: ...
Recommendation: ...
---

• blocking -- パイプラインは停止しており、直ちに対応が必要
• next-review -- 次回予定されている人間によるレビューにまとめる
• informational -- 対応不要、情報共有のみ

スタンドアロンのユーザーは urgency フィールドを無視できます。チェックポイント形式は引き続き後方互換性があります。

複数の質問を含むチェックポイントを処理する

関連する判断が複数必要な場合は、繰り返し一時停止するのではなく、1 つのチェックポイントにまとめます。質問にはそれぞれ番号を付けてください。

AWAITING_USER_INPUT
---
Context: Setting up the test infrastructure for the new auth module.
Decisions needed:

1. Test framework?
   A) Jest -- already used in 3 other modules
   B) Vitest -- faster, but would introduce a second test runner
   Recommendation: A) Jest for consistency

2. Test file location?
   A) Colocated (auth/__tests__/) -- matches signup module pattern
   B) Top-level (tests/auth/) -- matches API module pattern
   Recommendation: A) Colocated, to match the newer module convention
---

適用に関する注意

• スタンドアロンモード： 推奨事項です。エージェントが自ら一時停止の規律を守ります。
• パイプラインモード： 構造上の要件です。AWAITING_USER_INPUT はパイプラインの状態をディスクに書き込み、現在のエージェントを停止させます。

厳守事項：

• 判断が必要な場合は人間の入力が必要です：[RP]

制約

• 「直ちに停止し、推測しない」： 「停止」とは、判断に関わる経路を止めることであり、必ずしもすべての作業を止めることではありません。無関係な別の作業を進められる場合は、進めてください。ただし、判断が必要な経路については、その選択肢を前提とするコードの「準備」さえ含め、進捗させてはいけません。準備も判断に当たります。
• 「具体的な選択肢を 2～4 個」： 選択肢は、同じアプローチのバリエーションではなく、実質的に異なる代替案でなければなりません。「ライブラリ A を使う」「オプション X を指定してライブラリ A を使う」「オプション Y を指定してライブラリ A を使う」は、3 つの選択肢ではなく、設定の異なる 1 つの選択肢です。それぞれの選択肢は、意味のある別の進め方を示す必要があります。

検証

このスキルを適用した後、次の点を確認してください。

• 人間の判断が必要なすべての決定に AWAITING_USER_INPUT 形式を使用した
• 各チェックポイントに、背景情報、影響を含む選択肢、推奨事項を記載した
• 自由形式の質問（「どうすればよいですか？」など）をしていない
• サブエージェントが一時停止する前に状態を保存した
• 作業再開時に、保存した状態を使い、再分析しなかった
• 関連する判断を 1 つのチェックポイントにまとめた

依存関係

このスキルは単独で動作します。ワークフローを強化するには、次のものと連携します。

• tdd： テスト要件が曖昧な場合は、一時停止して受け入れ基準を明確にします。自動モードでは、オーケストレーターが一時停止したサブエージェントを検出し、質問をユーザーに伝えます。
• debugging-protocol： デバッグによって根本原因が曖昧だと判明した場合は、一時停止して質問します。

依存関係が不足していますか？次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill tdd