Back to Details

design-refinement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Refinement

设计细化

非自明なtaskでは、質問を作る前にprojectを読む。 目的はuserを大量の質問でinterviewすることではなく、read relentlessly, ask minimally を実行し、implementationが暗黙のassumptionに依存しない状態へすることである。
对于非平凡的任务，在拟定问题之前先阅读项目。 目标不是用大量问题对用户进行访谈，而是贯彻 read relentlessly, ask minimally（持续阅读，尽量少提问），确保实现不依赖隐含的假设。

1. Read before asking

1. 提问前先阅读

最低限、taskに関係するものを必要な範囲で確認する。
  • current user request / Issue / acceptance criteria
  • project-wide policy / canonical architecture / invariants
  • design / specification
  • relevant ADR
  • relevant project-local Skills / operational docs
  • relevant existing implementationを複数箇所
  • tests / fixtures / schemas / contracts
  • Git history / PR discussion when current codeだけではdecision intentが分からない場合
  • framework/runtime/API/toolのcurrent official documentation when version-sensitive
  • domain vocabulary / glossary when存在する場合
最初に見つけたfile、会話上の印象、一般的なbest practiceだけでproject intentを補完しない。
至少在必要范围内检查与任务相关的内容。
  • 当前用户请求 / Issue / 验收标准
  • 项目级策略 / 规范架构 / 不变量
  • 设计 / 规格说明
  • 相关 ADR
  • 相关项目本地 Skills / 操作文档
  • 多个位置的相关现有实现
  • 测试 / fixtures / schemas / contracts
  • 当仅凭当前代码无法理解决策意图时，查阅 Git history / PR discussion
  • 对版本敏感的 framework/runtime/API/tool 当前官方文档
  • 存在时的领域词汇 / 术语表
不要仅凭最先找到的文件、对话中的印象或通用最佳实践来补全项目意图。

2. Factとdecisionを分離する

2. 分离事实与决策

発見したunknownを少なくとも次へ分類する。
将发现的未知事项至少分为以下几类。

Fact

事实（Fact）

repository、official source、実行可能なprobe、既存system stateから調査できるもの。
例:
  • 現在のAPI behavior
  • existing naming/layout convention
  • framework/runtime capability
  • schema shape
  • test coverage
  • current release/branch state
Factは原則としてagentが調査して解決する。userへ質問しない。
可以从仓库、官方来源、可执行的 probe 或现有系统状态中调查得到的内容。
示例：
  • 当前 API 行为
  • 现有命名 / 布局约定
  • framework/runtime 能力
  • schema 结构
  • 测试覆盖率
  • 当前 release/branch 状态
事实原则上应由 Agent 调查并解决，不向用户提问。

Determined decision

已确定决策（Determined decision）

engineering-decisions
のprecedenceとproject evidenceから実質一意に決まるもの。
reversibleで局所的、acceptance criteriaやpublic contract等を変えない場合はagentが決めて進む。
根据 
engineering-decisions
的优先级和项目证据可以实质上唯一确定的内容。
如果决策是可逆且局部的，并且不会改变验收标准或 public contract 等内容，则由 Agent 决定并继续推进。

Unresolved consequential decision

未解决且影响重大的决策（Unresolved consequential decision）

evidenceを読んでも複数のmeaningful optionが残り、選択によってproduct semantics、architecture、public contract、risk、cost、release scope等が変わるもの。
user escalation候補はこのcategoryに限定する。
即使阅读了证据，仍然存在多个有意义的选项，且选择会改变产品语义、架构、public contract、风险、成本或发布范围等内容。
只有此类决策才应作为向用户升级的候选。

3. Assumptionをhidden stateにしない

3. 不让假设成为隐藏状态

implementationを成立させるために必要だがevidenceで確定していない前提を検出する。
特に確認する:
  • user-visible behavior
  • domain semantics
  • ownership / responsibility boundary
  • source of truth
  • persistence / lifecycle
  • failure behavior
  • compatibility / migration
  • security / privacy / permission
  • performance / cost budget
  • release / rollout behavior
「おそらくこうだろう」でimplementationへ進まず、factなら調査し、decisionならdecision graphへ入れる。
检测实现成立所必需、但无法由证据确定的假设。
尤其需要确认：
  • 用户可见行为
  • 领域语义
  • 所有权 / 职责边界
  • 事实源
  • 持久化 / 生命周期
  • 失败行为
  • 兼容性 / 迁移
  • 安全 / 隐私 / 权限
  • 性能 / 成本预算
  • 发布 / 推出行为
不要以“大概如此”为由直接进入实现；如果内容属于事实，则进行调查；如果内容属于决策，则将其加入决策图。

4. Decision dependency graph

4. 决策依赖图

unresolved decisionに依存関係がある場合、平坦な質問listにしない。
例:
text
A: canonical source of truth
├─ B: conflict resolution behavior
└─ C: offline/cache policy
   └─ D: stale-data UX
B/C/Dの回答がAに依存するなら、Aが未確定な状態で下流質問をuserへ投げない。
各decision nodeは必要に応じて:
  • question / decision statement
  • known evidence
  • alternatives
  • consequences
  • dependency
  • recommended option
  • escalation reason
を持つ。
如果未解决的决策之间存在依赖关系，不要将其整理成扁平的问题列表。
示例：
text
A: canonical source of truth
├─ B: conflict resolution behavior
└─ C: offline/cache policy
   └─ D: stale-data UX
如果 B/C/D 的回答依赖 A，就不要在 A 尚未确定时向用户提出下游问题。
每个决策节点根据需要包含：
  • 问题 / 决策陈述
  • 已知证据
  • 备选方案
  • 后果
  • 依赖关系
  • 推荐方案
  • 升级原因

5. Ask only the decision frontier

5. 只询问决策前沿

現在回答可能で、未解決の上流decisionを持たないnodeだけをdecision frontierとする。
userへ質問するのは、そのfrontierのうち 
engineering-decisions
のescalation criteriaに該当するものだけに限定する。
質問時は単なる「A/Bどちらですか」ではなく、可能な範囲で:
  • 既に確認したevidence
  • 残った選択肢
  • 各選択肢のmeaningful consequence
  • agentの推奨案と理由
を簡潔に示す。
複数decisionが独立しており一度に答えられる場合はまとめてよい。依存しているdecisionを先読みして大量質問しない。
只有当前可以回答，并且不存在未解决上游决策的节点，才构成决策前沿。
向用户提问时，仅限决策前沿中符合 
engineering-decisions
升级标准的节点。
提问时，不要只问“A 还是 B”，而应在可能的情况下简要说明：
  • 已确认的证据
  • 剩余的选项
  • 每个选项的重大影响
  • Agent 的推荐方案及理由
如果多个决策相互独立且可以一次性回答，可以一并提出。不要提前询问存在依赖关系的决策，从而产生大量问题。

6. Stop condition

6. 停止条件

次を満たしたらrefinementを終了し、planning / ticketization / implementationへ進む。
  • task scopeとacceptance criteriaが実装可能な粒度で明確
  • relevant factが調査済み、または明示的なexternal blockerとして特定済み
  • consequential unresolved decisionが残っていない
  • implementationを左右するhidden assumptionが残っていない
  • decision resultが必要なcanonical locationへ反映されている
すべてを完全仕様化することは目的ではない。implementationを安全に開始するために必要なuncertaintyだけを解消する。
满足以下条件后，结束细化并进入规划 / 工单拆分 / 实现阶段。
  • 任务范围和验收标准已清晰到可以实现的粒度
  • 相关事实均已调查，或已明确识别为外部阻塞项
  • 不存在尚未解决且影响重大的决策
  • 不存在会影响实现的隐藏假设
  • 决策结果已反映到相应的权威位置
目标不是将所有内容完全规格化，而是只消除安全开始实现所必需的未知事项。

7. Persist selectively

7. 选择性持久化

long-lived valueを持つdecisionやdomain knowledgeだけをrepository-controlled stateへ永続化する。
候補:
  • design / specification
  • ADR
  • project-local Skill
  • architecture / development docs
  • domain glossary / domain context
  • schema / contract / test
次は通常永続化しない。
  • formatter等が決める自明なchoice
  • 一時的な調査結果
  • reversibleな局所implementation detail
  • conversationでのみ意味を持つ説明
  • private chain-of-thought
domain vocabularyが複雑で複数contributor/agentの共通理解に価値がある場合は、projectに適したglossary/domain contextを作成・更新する。固定の 
CONTEXT.md
file名や独立documentを全projectへ強制しない。
仅将具有长期价值的决策或领域知识持久化到由仓库管理的状态中。
候选内容包括：
  • 设计 / 规格说明
  • ADR
  • 项目本地 Skill
  • 架构 / 开发文档
  • 领域术语表 / 领域上下文
  • schema / contract / test
以下内容通常不应持久化：
  • 由 formatter 等决定的显而易见选项
  • 临时调查结果
  • 可逆且局部的实现细节
  • 仅在对话中有意义的说明
  • 私有思维链
如果领域词汇复杂，并且对于多个 contributor/Agent 形成共同理解具有价值，则创建或更新适合该项目的术语表 / 领域上下文。不要对所有项目强制使用固定的 
CONTEXT.md
文件名或独立文档。

8. Relationship with engineering-decisions

8. 与 engineering-decisions 的关系

このSkillは 
engineering-decisions
を置き換えない。
  • design-refinement
    : implementation前にunknown / assumption / decision dependencyを発見し、質問対象を絞る
  • engineering-decisions
    : 発見されたdecisionをproject evidenceのprecedenceで自律決定するかuser escalationするか判定する
原則:
text
inspect evidence
  -> classify facts / decisions
  -> investigate facts
  -> resolve determined decisions
  -> build unresolved decision graph
  -> ask only consequential frontier
  -> persist significant results
  -> plan / implement
这个 Skill 不会取代 
engineering-decisions
。
  • design-refinement
    ：在实现前发现未知事项、假设和决策依赖关系，并缩小提问范围
  • engineering-decisions
    ：根据项目证据的优先级，判断发现的决策应由 Agent 自主决定，还是升级给用户
原则：
text
inspect evidence
  -> classify facts / decisions
  -> investigate facts
  -> resolve determined decisions
  -> build unresolved decision graph
  -> ask only consequential frontier
  -> persist significant results
  -> plan / implement