Back to Details

user-input-protocol

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

User Input Protocol

用户输入协议

Value: Respect -- the developer's judgment governs all consequential decisions. The agent never assumes when it should ask.
核心原则： 尊重——开发者的判断主导所有重大决策。Agent绝不能自行决定何时应该询问。

Purpose

目的

Defines a structured format for agents to request human input at decision points. Prevents agents from making assumptions on the developer's behalf, ensures questions include enough context for informed decisions, and provides a pause-and-resume pattern for subagents that cannot directly prompt the user.
定义Agent在决策点请求人类输入的结构化格式。防止Agent替开发者做假设，确保问题包含足够上下文以支持明智决策，并为无法直接提示用户的子Agent提供暂停与恢复模式。

Practices

实践规范

Stop and Present, Never Assume

立即停止并呈现，绝不假设

When you encounter a decision that requires human judgment, stop working immediately. Do not guess. Do not pick the "most likely" option. Present the decision clearly and wait.
Decisions that require human input:
  • Business rule ambiguities (two valid interpretations exist)
  • Architecture trade-offs (performance vs. simplicity, etc.)
  • Scope questions (should this feature include X?)
  • Destructive actions (deleting files, force-pushing, dropping data)
Decisions that do NOT require human input:
  • Implementation details with one clearly correct answer
  • Formatting, naming, or style choices covered by project conventions
  • Test structure when requirements are unambiguous
当你遇到需要人类判断的决策时，立即停止工作。不要猜测，不要选择“最可能”的选项。清晰呈现决策内容并等待。
需要人类输入的决策场景：
  • 业务规则歧义（存在两种有效解读）
  • 架构权衡（性能与简洁性等）
  • 范围问题（该功能是否应包含X？）
  • 破坏性操作（删除文件、强制推送、丢弃数据）
无需人类输入的决策场景：
  • 有明确正确答案的实现细节
  • 项目约定覆盖的格式、命名或风格选择
  • 需求明确时的测试结构

Use the AWAITING_USER_INPUT Format

使用AWAITING_USER_INPUT格式

When you need input, output this structured checkpoint:
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"]
---
Rules for the checkpoint:
  • Context must explain what led to this question (not just "I need input")
  • Provide 2-4 specific options. Never ask open-ended "what should I do?"
  • Each option must include implications, not just a label
  • State your recommendation if you have one -- the developer can override
Example:
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 "user+tag@example.com".
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
---
当你需要输入时，输出以下结构化检查点：
AWAITING_USER_INPUT
---
Context: [询问原因——你正在执行的任务及发现的问题]
Decision needed: [具体问题，一句话描述]
Options:
  A) [选项标签] -- [该选项的含义及影响]
  B) [选项标签] -- [该选项的含义及影响]
  C) [选项标签] -- [该选项的含义及影响]
Recommendation: [你建议的选项及原因，或“无推荐”]
---
检查点规则：
  • Context必须解释引发该问题的前因后果（不能只写“我需要输入”）
  • 提供2-4个具体选项。绝不要提出开放式问题“我该怎么做？”
  • 每个选项必须包含影响，不能只有标签
  • 如有建议请说明——开发者可以覆盖你的建议
示例：
AWAITING_USER_INPUT
---
Context: 在实现登录端点时，我发现代码库中有两种邮箱验证模式。auth/validate.rs使用严格的RFC 5322解析。signup/forms.rs使用简单的正则表达式检查。对于“user+tag@example.com”这类边缘情况，两者会产生不同结果。
Decision needed: 项目应采用哪种邮箱验证方式作为标准？
Options:
  A) 严格RFC 5322 -- 拒绝的有效地址更少，维护复杂度更高
  B) 简单正则表达式 -- 速度更快，但可能接受格式错误的地址
  C) 依赖上下文 -- 验证时用严格模式，表单时用宽松模式
Recommendation: A) 严格RFC 5322，全局统一以保证一致性
---

Save State Before Pausing (Subagents)

暂停前保存状态（子Agent）

Subagents and background tasks typically cannot prompt the user directly. When a subagent needs input, it must save its progress before pausing so work can resume without starting over.
State to save before pausing:
  1. What task you were performing
  2. What files you created or modified
  3. What analysis you completed
  4. The specific decision that blocked you
  5. Enough context to continue immediately when resumed
Where to save state depends on your harness:
  • Task metadata (Claude Code: TaskUpdate with metadata)
  • File system (write a JSON checkpoint to a temp file)
  • Memory tools (MCP servers, if available)
After saving state, output the AWAITING_USER_INPUT checkpoint and stop. The orchestrator or main conversation detects the pause, presents the question to the user, and resumes the subagent with the answer.
子Agent和后台任务通常无法直接提示用户。当子Agent需要输入时，必须在暂停前保存进度，以便恢复工作时无需从头开始。
暂停前需保存的状态：
  1. 正在执行的任务
  2. 创建或修改的文件
  3. 已完成的分析
  4. 阻碍工作的具体决策点
  5. 恢复时可立即继续的足够上下文
保存状态的位置取决于你的运行环境：
  • 任务元数据（Claude Code：带元数据的TaskUpdate）
  • 文件系统（将JSON检查点写入临时文件）
  • 内存工具（如可用的MCP服务器）
保存状态后，输出AWAITING_USER_INPUT检查点并停止。编排器或主对话会检测到暂停，将问题呈现给用户，并带着答案恢复子Agent的工作。

Resume Without Redoing Work

恢复工作时无需重复劳动

When resumed with the user's answer:
  1. Retrieve your saved state
  2. Confirm you have the files and context you need
  3. Apply the user's decision
  4. Continue from where you stopped
Do not re-analyze files you already analyzed. Do not re-read context you already saved. The purpose of state preservation is to make resumption instant.
Do:
  • "You chose strict RFC 5322. Applying to the login endpoint now."
Do not:
  • "Let me re-analyze the codebase to understand the email validation..."
当带着用户的答案恢复工作时：
  1. 检索保存的状态
  2. 确认拥有所需的文件和上下文
  3. 应用用户的决策
  4. 从暂停处继续
不要重新分析已分析过的文件。不要重新读取已保存的上下文。状态保存的目的是让恢复工作即时完成。
正确做法：
  • “你选择了严格RFC 5322。现在将其应用到登录端点。”
错误做法：
  • “让我重新分析代码库以理解邮箱验证...”

Batch Decisions in Factory Mode

工厂模式下批量处理决策

When running inside a pipeline or factory workflow, avoid blocking the pipeline on every decision. Classify each decision and route accordingly:
  • Gate-resolvable: Never ask the human. Quality gates provide the answer (test pass/fail, mutation score, CI status). These are fully automated.
  • Judgment-required: Batch for the next human review cycle. Examples: design trade-offs that surfaced during review, non-blocking review findings that need prioritization, retrospective suggestions.
  • Blocking: Pause the pipeline immediately. Examples: security concern raised during review, unrecoverable gate failure after 3 rework cycles, ambiguous requirements that affect correctness.
Gate-resolvable decisions never appear in AWAITING_USER_INPUT checkpoints. Judgment-required decisions are collected and presented as a single grouped checkpoint during the human review phase. Blocking decisions use the standard AWAITING_USER_INPUT format immediately.
When emitting AWAITING_USER_INPUT in factory mode, include an 
urgency
field after the separator:
AWAITING_USER_INPUT
---
Urgency: blocking | next-review | informational
Context: ...
Decision needed: ...
Options: ...
Recommendation: ...
---
  • blocking
    -- pipeline is halted, needs immediate attention
  • next-review
    -- batched for next scheduled human review
  • informational
    -- no action needed, for awareness only
Standalone users can ignore the urgency field; the checkpoint format remains backward compatible.
在流水线或工厂工作流中运行时，避免因每个决策而阻塞流水线。对每个决策进行分类并相应处理：
  • 网关可解决： 绝不询问人类。质量网关会提供答案（测试通过/失败、突变分数、CI状态）。这些完全自动化。
  • 需判断： 批量处理至下一次人类审核周期。示例：审核期间发现的设计权衡、需要优先处理的非阻塞审核结果、回顾建议。
  • 阻塞性： 立即暂停流水线。示例：审核中发现的安全问题、3次返工后仍无法通过的网关故障、影响正确性的模糊需求。
网关可解决的决策绝不会出现在AWAITING_USER_INPUT检查点中。需判断的决策会被收集起来，在人类审核阶段作为单个分组检查点呈现。阻塞性决策会立即使用标准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字段；检查点格式保持向后兼容。

Handle Multi-Question Checkpoints

处理多问题检查点

When multiple related decisions are needed, group them in one checkpoint rather than pausing repeatedly. Number each question.
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
---
Context: 为新的auth模块搭建测试基础设施。
Decisions needed:

1. 测试框架？
   A) Jest -- 已在其他3个模块中使用
   B) Vitest -- 速度更快，但会引入第二个测试运行器
   Recommendation: A) Jest以保证一致性

2. 测试文件位置？
   A) 同目录存放（auth/__tests__/） -- 匹配signup模块模式
   B) 顶层存放（tests/auth/） -- 匹配API模块模式
   Recommendation: A) 同目录存放，以匹配较新的模块约定
---

Enforcement Note

执行说明

This skill is advisory. It instructs agents to pause at decision points and use structured checkpoints. The agent follows these practices by convention. If you observe the agent making decisions it should have asked about, point it out.
本技能为指导性内容。它指示Agent在决策点暂停并使用结构化检查点。Agent会按惯例遵循这些规范。如果你发现Agent做出了本应询问的决策，请指出。

Verification

验证

After applying this skill, verify:
  • Every decision requiring human judgment used AWAITING_USER_INPUT format
  • Each checkpoint included context, options with implications, and a recommendation
  • No open-ended questions were asked ("what should I do?")
  • Subagents saved state before pausing
  • Resumed work used saved state without re-analyzing
  • Related decisions were grouped into single checkpoints
应用本技能后，请验证：
  • 所有需要人类判断的决策均使用了AWAITING_USER_INPUT格式
  • 每个检查点都包含上下文、带影响的选项及推荐
  • 未提出开放式问题（如“我该怎么做？”）
  • 子Agent在暂停前保存了状态
  • 恢复工作时使用了保存的状态，未重新分析
  • 相关决策被分组到单个检查点中

Dependencies

依赖

This skill works standalone. For enhanced workflows, it integrates with:
  • tdd: When test requirements are ambiguous, pause and clarify acceptance criteria. In automated mode, the orchestrator detects paused subagents and relays questions to the user.
  • debugging-protocol: When debugging reveals ambiguous root causes, pause and ask
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill tdd
本技能可独立使用。为增强工作流，它可与以下技能集成：
  • tdd： 当测试需求不明确时，暂停并澄清验收标准。在自动化模式下，编排器会检测到暂停的子Agent并将问题转发给用户。
  • debugging-protocol： 当调试发现模糊的根本原因时，暂停并询问
缺少依赖？通过以下命令安装：
npx skills add jwilger/agent-skills --skill tdd