Back to Details

refactor-for-determinism

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refactor for Determinism

面向确定性的重构

Build reliable skills by separating deterministic steps from judgment-based steps.
通过将确定性步骤与基于判断的步骤分离，构建可靠的Skill。

Core Principle

核心原则

Deterministic steps belong in scripts. Use SKILL.md to orchestrate the workflow and reserve judgment for the non-deterministic parts.
确定性步骤应放在脚本中。使用SKILL.md编排工作流，将判断环节留给非确定性部分。

Workflow

工作流程

1. Identify Deterministic vs Non-Deterministic Work

1. 区分确定性与非确定性工作

For each step in the skill:
  • Deterministic: repeatable, mechanical, or validation-heavy steps → script candidates
  • Non-deterministic: judgment, interpretation, creative choices → keep in SKILL.md
Examples of deterministic steps:
  • Running quality checks
  • Verifying clean git state
  • Updating version strings
  • Promoting CHANGELOG sections
  • Collecting diff context for review
Examples of non-deterministic steps:
  • Writing changelog content
  • Selecting a solution approach
  • Code review judgments
  • Deciding release timing
针对Skill中的每个步骤：
  • 确定性步骤：可重复、机械性或侧重验证的步骤 → 适合做成脚本
  • 非确定性步骤：需要判断、解读或创意选择的步骤 → 保留在SKILL.md中
确定性步骤示例：
  • 运行质量检查
  • 验证git状态是否干净
  • 更新版本字符串
  • 升级CHANGELOG章节
  • 收集差异上下文用于评审
非确定性步骤示例：
  • 编写CHANGELOG内容
  • 选择解决方案路径
  • 代码评审判断
  • 决定发布时机

2. Design Scripts for Deterministic Steps

2. 为确定性步骤设计脚本

For each deterministic step:
  • Create a script in 
    scripts/
    within the skill directory
  • Make it self-contained with clear error messages
  • Validate inputs and exit non-zero on failure
  • Prefer small, single-purpose scripts
针对每个确定性步骤：
  • 在Skill目录下的
    scripts/
    文件夹中创建脚本
  • 确保脚本独立运行，并配有清晰的错误提示
  • 验证输入，失败时返回非零退出码
  • 优先选择小型、单一用途的脚本

3. Update SKILL.md to Use Scripts

3. 更新SKILL.md以调用脚本

  • Replace manual command lists with script calls
  • Reference scripts using relative paths: 
    scripts/...
  • Keep judgment steps explicit in prose
  • 用脚本调用替换手动命令列表
  • 使用相对路径引用脚本：
    scripts/...
  • 在文字描述中明确保留判断步骤

4. Document Boundaries

4. 明确边界文档

Make the line between scripted and non-scripted steps obvious:
  • Use section headers like "Deterministic Steps" and "Judgment Steps"
  • Call out where human/agent judgment is required
让脚本化步骤与非脚本化步骤的界限清晰可见：
  • 使用“确定性步骤”和“判断步骤”这样的章节标题
  • 标注出需要人类/Agent判断的环节

Output Format

输出格式

undefined
undefined

Determinism Audit

确定性审计

Deterministic Steps (script candidates)

确定性步骤（候选脚本）

  • [Step] → [script name]
  • [步骤] → [脚本名称]

Non-Deterministic Steps (keep in SKILL.md)

非确定性步骤（保留在SKILL.md中）

  • [Step] → [why it needs judgment]
  • [步骤] → [需要判断的原因]

Script Plan

脚本规划

  • scripts/[name] - [purpose, inputs, outputs]
  • scripts/[名称] - [用途、输入、输出]

SKILL.md Updates

SKILL.md更新内容

  • [Where to call each script]
undefined
  • [每个脚本的调用位置]
undefined

Common Mistakes

常见错误

MistakeFix
Scripting judgmentKeep decision-making in SKILL.md
One giant scriptSplit into small, focused scripts
Silent failuresPrint clear errors and exit non-zero
Hardcoded pathsUse repo-relative paths
Forgetting SKILL.md updatesAlways wire scripts into instructions
错误修复方案
脚本中包含判断逻辑将决策逻辑保留在SKILL.md中
单个巨型脚本拆分为小型、专注的脚本
静默失败打印清晰的错误信息并返回非零退出码
硬编码路径使用仓库相对路径
忘记更新SKILL.md务必将脚本关联到操作说明中

What NOT to Do

禁忌事项

  • Do NOT hide decisions inside scripts
  • Do NOT make scripts that require manual editing
  • Do NOT mix multiple responsibilities into one script
  • Do NOT add extra documentation files beyond SKILL.md
  • 请勿在脚本中隐藏决策逻辑
  • 请勿创建需要手动编辑的脚本
  • 请勿将多个职责混合到单个脚本中
  • 请勿在SKILL.md之外添加额外的文档文件