task-clarification-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Task Clarification Harness

任务澄清管控框架

Purpose

用途

Use this skill before implementation when the task may be underspecified, risky, broad, or likely to affect multiple parts of the system.

The goal is to prevent premature coding by forcing a structured, repository-grounded clarification pass first.

This skill helps the agent:

restate the task clearly
inspect the codebase before assuming implementation details
identify ambiguities and missing decisions
map impacted files, modules, symbols, or systems
surface technical and product risks
define scope boundaries
create an implementation contract with validation steps before making changes

This is a pre-implementation harness. It exists to improve correctness, reduce scope drift, and make execution safer by turning vague requests into a constrained engineering artifact.

当任务存在需求不明确、风险高、范围宽泛，或是可能影响系统多个模块时，请在编码实现前使用本skill。

其核心目标是通过强制先完成基于代码仓库的结构化澄清流程，避免过早开始编码。

本skill可帮助Agent：

清晰重述任务内容
在确定实现细节前先检查代码库
识别歧义点和待决策内容
梳理受影响的文件、模块、标识符或系统
暴露技术和产品层面的风险
定义范围边界
在代码变更前创建包含验证步骤的实现契约

这是一套预实现管控框架，通过将模糊的需求转化为有约束的工程交付件，提升实现正确性、减少范围漂移、让开发执行过程更安全。

Required behavior

要求行为

Before making any code changes, the agent must complete a clarification pass.

The agent must:

restate the task in concrete terms
inspect the repository when it is available
identify ambiguities or unanswered questions
identify likely impacted areas
assess risks and assumptions
define scope boundaries
define an implementation contract
define how success will be validated

Do not implement before this pass is complete.

在进行任何代码变更前，Agent必须完成全量澄清流程。

Agent必须：

用具体术语重述任务
当代码仓库可用时完成仓库检查
识别歧义点或未解答的问题
识别可能受影响的范围
评估风险和前置假设
定义范围边界
定义实现契约
定义成功验证标准

澄清流程未完成前禁止启动实现工作。

Workflow files

工作流依赖文件

This skill relies on the following files in the same folder:

```
ambiguity-checklist.md
```
```
scope-boundaries.md
```
```
output-template.md
```
```
references/harness-patterns.md
```

references/validation-linking-criteria.md

references/contract-review-handoff-template.md

references/example-clarification-summary.md

Read and apply them during the clarification pass.

If you write the clarification summary to disk, validate it with:

python scripts/validate_clarification_summary.py <path-to-summary.md>

本skill依赖同目录下的以下文件：

```
ambiguity-checklist.md
```
```
scope-boundaries.md
```
```
output-template.md
```
```
references/harness-patterns.md
```

references/validation-linking-criteria.md

references/contract-review-handoff-template.md

references/example-clarification-summary.md

澄清流程中请读取并应用以上文件的规则。

如果需要将澄清总结写入磁盘，请使用以下命令验证：

python scripts/validate_clarification_summary.py <path-to-summary.md>

Clarification workflow

澄清工作流

Step 1 - Restate the task

步骤1 - 重述任务

Rewrite the request in operational language.

Capture:

what is being asked
what kind of change this is
whether it is a bug fix, enhancement, refactor, migration, cleanup, or investigation
what appears in scope
what appears intentionally out of scope

Do not repeat the user loosely. Translate the request into engineering intent.

用可落地的工程语言重写需求。

需要包含：

需求的核心诉求
变更的类型
属于bug修复、功能增强、重构、迁移、清理还是调研类任务
当前认定的在范围内的内容
当前认定的明确不在范围内的内容

不要松散地重复用户需求，要将需求转化为工程层面的实现意图。

Step 2 - Ground the task in the repository

步骤2 - 结合代码仓库对齐任务信息

Inspect the repository before making implementation claims when repository access is available.

Look for:

real file paths
real symbols, modules, routes, or services
existing patterns to follow
current behavior relevant to the request
nearby tests, docs, config, or observability hooks

Separate:

confirmed facts from repository inspection
likely inferences
unknowns that still need clarification

Do not invent file paths, APIs, or architectural patterns.

If the repository cannot yet support a safe conclusion, prefer

needs-codebase-investigation

当有代码仓库访问权限时，在给出实现相关的结论前先检查代码仓库。

重点查找：

真实的文件路径
真实的标识符、模块、路由或服务
已有的可遵循的开发模式
与需求相关的当前系统行为
周边的测试、文档、配置或可观测性埋点

区分三类信息：

从代码仓库检查得到的确认事实
合理的推断结论
仍需澄清的未知内容

不要虚构文件路径、API或架构模式。

如果当前代码仓库信息不足以支撑得出安全结论，请标记为

needs-codebase-investigation

。

Step 3 - Check for ambiguity

步骤3 - 歧义检查

Read

ambiguity-checklist.md

Look for ambiguity in:

product behavior
expected inputs and outputs
edge cases
authorization or security expectations
data handling
UX or API behavior
backward compatibility
deployment or environment assumptions
acceptance criteria

If important ambiguity exists, explicitly call it out.

读取

ambiguity-checklist.md

。

检查以下维度是否存在歧义：

产品行为
预期的输入输出
边界 case
鉴权或安全预期
数据处理逻辑
UX或API行为
向后兼容性
部署或环境假设
验收标准

如果存在重要歧义，必须明确标注出来。

Step 4 - Map impact surface

步骤4 - 梳理影响面

Identify what parts of the system are likely affected.

Include where relevant:

files
modules
services
routes
UI surfaces
data models
tests
config
docs
CI/CD or runtime assumptions

Do not claim certainty when still inferring. Mark inferred impact as likely, possible, or unclear.

识别系统中可能受影响的部分。

Step 5 - Assess risks and invariants

步骤5 - 评估风险和不变量

Identify execution risks such as:

regression risk
hidden coupling
unclear invariants
missing tests
auth/security exposure
performance implications
data migration concerns
scope creep risk
architecture drift

Be specific. Name the risk and why it matters.

Also capture important invariants such as:

API or UI behavior that must remain stable
data contracts that must not break
security boundaries that must not weaken
performance or operational expectations that must hold

识别执行风险，例如：

回归风险
隐藏的耦合关系
不明确的系统不变量
缺失的测试用例
鉴权/安全暴露点
性能影响
数据迁移隐患
范围蔓延风险
架构漂移

描述需要具体，说明风险内容以及影响。

同时需要记录重要的系统不变量，例如：

必须保持稳定的API或UI行为
不能破坏的数据契约
不能弱化的安全边界
必须满足的性能或运维预期

Step 6 - Define scope boundaries

步骤6 - 定义范围边界

Read

scope-boundaries.md

State clearly:

what should be changed
what should not be changed
what would require explicit approval
what adjacent improvements should be deferred

Do not treat nearby cleanup as automatically in scope.

读取

scope-boundaries.md

。

明确说明：

哪些内容需要修改
哪些内容不应该修改
哪些内容需要额外申请审批
哪些相邻的优化需要延后处理

不要默认将周边的代码清理工作纳入当前任务范围。

Step 7 - Define the implementation contract

步骤7 - 定义实现契约

Turn the clarification pass into a concrete handoff artifact.

Include:

the files, modules, or symbols that are most likely to change
the existing patterns or references to follow
the acceptance criteria or expected outcomes
the approval-required edges that must not be crossed silently
the evidence level for each major claim: confirmed, inferred, or unknown

The contract should narrow the solution space enough that implementation becomes targeted instead of exploratory.

If the contract is important enough to gate implementation, hand it to the sister skill

implementation-contract-review-harness

for a second-pass review before coding.

Use the handoff shape in

references/contract-review-handoff-template.md

If both the clarification artifact and the contract review verdict exist, an optional final gate can be run with

implementation-readiness-gate

before implementation starts.

将澄清流程的输出转化为可交付的具象交接件。

包含：

最可能需要修改的文件、模块或标识符
需要遵循的现有模式或参考资料
验收标准或预期结果
不得私自越过的需要审批的边界
每个核心结论的证据等级：确认、推断、未知

实现契约需要足够收窄解决方案空间，让实现工作是定向的而非探索性的。

如果实现契约重要性足够高，需要作为实现的门禁条件，在编码前将其交给配套skill

implementation-contract-review-harness

进行二次评审。

请使用

references/contract-review-handoff-template.md

中定义的交接格式。

如果同时存在澄清交付件和契约评审结论，可以在启动实现前可选运行

implementation-readiness-gate

作为最终门禁。

Step 8 - Define validation plan

步骤8 - 定义验证计划

Before implementation, define how success will be checked.

Read

references/validation-linking-criteria.md

Include likely checks such as:

lint
typecheck
unit tests
integration tests
manual scenario validation
smoke tests
API contract checks
behavior comparison
documentation review

Do not say "done" without a validation path.

Choose checks that are actually supported by the repository. Prefer repository-native commands over generic placeholders.

Use these selection rules:

if the repository exposes scripts or task runners such as
```
package.json
```
,
```
Makefile
```
,
```
justfile
```
,
```
Taskfile.yml
```
,
```
tox.ini
```
, or
```
noxfile.py
```
, prefer those entry points
if CI workflows already define validation commands, prefer the same commands or the same command family
if typed languages or frameworks expose built-in validators, include them explicitly
if no deterministic check exists for a risk you identified, call that out and add the smallest practical manual validation scenario
if a full suite is expensive, propose the narrowest credible subset for pre-implementation confidence

Never list

lint

typecheck

, or

tests

unless you can point to the repository mechanism that would run them or explicitly mark them unavailable.

在实现前定义如何校验任务是否成功完成。

读取

references/validation-linking-criteria.md

。

包含可能的校验项：

lint检查
类型检查
单元测试
集成测试
手动场景验证
冒烟测试
API契约检查
行为对比
文档评审

没有验证路径的情况下不能声称任务完成。

请选择代码仓库实际支持的检查项，优先使用代码仓库原生的命令而非通用占位符。

遵循以下选择规则：

如果代码仓库暴露了脚本或任务运行器配置，例如
```
package.json
```
、
```
Makefile
```
、
```
justfile
```
、
```
Taskfile.yml
```
、
```
tox.ini
```
或
```
noxfile.py
```
，优先使用这些入口
如果CI工作流已经定义了验证命令，优先使用相同命令或同系列命令
如果强类型语言或框架提供了内置校验工具，明确包含这些工具
如果针对你识别的风险没有确定性的检查手段，明确标注该问题并补充最小可行的手动验证场景
如果全量验证套件成本很高，建议选择可信度最高的最小子集来保障预实现阶段的信心

除非你能指出代码仓库中运行这些检查的机制，或者明确标记它们不可用，否则不要随便列出

lint

、

typecheck

或

tests

。

Output

输出

Before implementation, produce a structured clarification summary using the template in

output-template.md

Treat this summary as the harness artifact that sits between request intake and implementation.

The output must include:

task restatement
task classification
repository-grounded evidence
key ambiguities
likely impacted areas
risks
scope boundaries
implementation contract
validation plan
readiness decision

When the summary is persisted to disk, run the validator script and fix any reported structural issues before treating the artifact as complete.

实现前请使用

output-template.md

中的模板生成结构化的澄清总结。

这份总结是介于需求接收和实现之间的管控框架交付件。

输出必须包含：

任务重述
任务分类
基于代码仓库的佐证信息
核心歧义点
可能的影响面
风险
范围边界
实现契约
验证计划
就绪状态决策

当总结写入磁盘后，请运行验证脚本，修复所有上报的结构问题后再将其视为完整交付件。

Readiness decision

就绪状态决策

At the end of the clarification pass, return exactly one of:

```
ready-for-implementation
```
```
needs-user-clarification
```
```
needs-codebase-investigation
```
```
not-safe-to-proceed
```

Use:

澄清流程结束后，必须返回以下状态中的一种：

```
ready-for-implementation
```
```
needs-user-clarification
```
```
needs-codebase-investigation
```
```
not-safe-to-proceed
```

适用场景：

ready-for-implementation

ready-for-implementation

when the task is clear enough and the likely impact is understood.

适用于任务足够清晰，可能的影响面已经明确的场景。

needs-user-clarification

needs-user-clarification

when important product or behavioral decisions are missing.

适用于缺少重要的产品或行为决策的场景。

needs-codebase-investigation

needs-codebase-investigation

when more repository inspection is needed before safe implementation.

适用于需要进一步检查代码仓库才能安全开展实现的场景。

not-safe-to-proceed

not-safe-to-proceed

when the task is too ambiguous, risky, or underspecified to execute responsibly.

适用于任务歧义过大、风险过高、需求极不明确，无法负责任地执行的场景。

Constraints

约束

Do not:

start implementing before clarifying
silently assume intended behavior
invent repository facts
hide ambiguity behind confident language
expand scope through cleanup impulses
claim readiness without a validation strategy

Do:

reduce ambiguity
ground claims in the real codebase when possible
make assumptions visible
separate known facts from inferences
define boundaries clearly
create a constrained handoff artifact before implementation
make execution safer before code changes begin

禁止：

澄清完成前启动实现
私自假设预期行为
虚构代码仓库相关的事实
用肯定的表述掩盖歧义
出于代码清理的冲动扩大范围
没有验证策略就声称任务就绪

必须：

减少歧义
尽可能基于真实代码库给出结论
明确暴露所有假设
区分已知事实和推断结论
清晰定义边界
在实现前创建有约束的交接交付件
在代码变更开始前降低执行风险

Operating mindset

运行思路

Act as:

a senior engineer clarifying execution before coding
a technical lead reducing delivery risk
a harness layer that improves agent reliability through structure, evidence, and checkpoints

Clarify first. Then implement only if justified.

你需要扮演：

在编码前澄清执行路径的资深工程师
降低交付风险的技术负责人
通过结构化流程、证据和检查点提升Agent可靠性的管控层

先完成澄清，仅当条件满足时再启动实现。