Back to Details

shunk031-codex-worker-prompting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex Worker Prompting

Codex工作者提示词编写指南

Write prompts that make worker decisions and stop conditions explicit.
编写能明确工作者决策逻辑与终止条件的提示词。

Eight principles

八项原则

  1. Write contracts, not vibes. Put machine-checkable conditions in every instruction: exact SHAs, exact commands, exact pass/fail gates, and explicit STOP conditions. Have workers self-check against these gates, and treat pushback that a gate is impossible as signal, not defiance. Pair every gate with a statement of what it does not measure, and treat a gate conflict like an impossible gate: stop and report instead of silently satisfying one gate.
  2. Assume literal execution. Expect every assertion to be executed as written, including mistakes. Add verification clauses such as read-backs, 
    ls-remote
    comparisons, and precondition checks so workers halt on stale or wrong facts. State invariants explicitly, including numbers, claim strength, attribution, file scope, and section order; a literal executor treats every unstated property as mutable.
  3. Bound the loops, not the task count. Let a dispatch carry a full lifecycle, but give every retryable step an explicit retry budget, wait duration, and terminal report state. For judgment tasks such as screening or review, state the decision rule, uncertain-case default, and cost asymmetry justifying that default. Encode authorization boundaries, including user-owned merges and destructive actions, as STOP conditions inside the prompt.
  4. Enumerate VERIFIED environment facts inline. List proxies, push-URL pitfalls, API field IDs, sandbox variables, and auth fallbacks using only verified facts. Write unverified beliefs as hypotheses to verify, and supply the exact command block to run instead of describing it.
  5. Dispatch requirements and acceptance criteria, not implementations. If you believe a tool or approach is unsuitable, state that belief as a hypothesis for worker verification and require research before implementation for tool choices. Workers execute solution framing literally and will build exactly the wrong thing well.
  6. Write the dispatch in the artifact's target register. A worker mirrors dispatch vocabulary and constraints into deliverables. For reader-facing artifacts, keep internal codenames and audit constraints out of the prompt body, and state that compliance evidence belongs in the PR body, not the document.
  7. Fix the class, prove the sweep. When a reviewer names defect instances, instruct the worker to remove the defect class. Require sweep evidence: an enumerate-and-classify table of every candidate, or a detector that reproduces the known-bad state before the fix and reports zero after it.
  8. Rotate on role and degradation, then on context. Start a fresh session for every independent review verdict, retire sessions showing degraded output or anchoring to a failed approach, and rotate long-lived workers at natural boundaries before context runs out; a fixed remaining-context percentage is not a reliable trigger. When re-dispatching after a crash or rotation, enumerate on-disk state, including paths and whether each artifact is final, and state what must not be recomputed. Externalize handoff state in handoff documents and PR comments where repository policy allows; keep PR bodies reader-facing rather than a state ledger.
Transport mechanics such as dispatch delivery, report formats, and reconciliation belong to the 
shunk031-orchestrate-herdr-workers
skill. This skill owns only prompt-writing guidance.
  1. 编写明确约定，而非模糊感觉：在每条指令中加入可机器校验的条件：精确的SHA值、精确的命令、明确的通过/失败判定标准，以及清晰的STOP终止条件。让工作者自行对照这些标准进行检查，将无法满足标准的反馈视为有效信号而非抵触行为。为每个判定标准补充说明其不包含的衡量维度，若出现标准冲突，应视为无法满足的情况：停止任务并上报，而非默认满足其中某一项标准。
  2. 假设执行会完全字面化：预期所有表述都会被严格按照字面执行，包括错误内容。添加验证条款，例如结果回读、
    ls-remote
    对比、前置条件检查等，确保工作者在遇到过时或错误信息时停止执行。明确声明不变量，包括数字、断言强度、归属信息、文件范围和章节顺序；字面化执行器会将所有未明确说明的属性视为可变项。
  3. 限制循环次数，而非任务数量：允许一次调度包含完整的生命周期，但为每个可重试步骤设置明确的重试次数上限、等待时长和最终报告状态。对于筛选或评审等判断类任务，明确说明决策规则、不确定情况的默认处理方式，以及支持该默认方式的成本不对称性理由。将授权边界（包括用户拥有的合并权限和破坏性操作）编码为提示词中的STOP终止条件。
  4. 在提示词中内联枚举已验证的环境信息：仅使用已验证的信息列出代理配置、推送URL陷阱、API字段ID、沙箱变量和认证备选方案。将未经验证的假设作为待验证的假说，并提供可直接运行的精确命令块，而非仅描述命令。
  5. 调度需求与验收标准，而非具体实现方案：若你认为某个工具或方法不合适，将该观点作为待工作者验证的假说，并要求在选择工具前先开展调研。工作者会完全字面地执行解决方案框架，可能会完美地构建出完全错误的产物。
  6. 使用产物目标受众的语言编写调度指令：工作者会将调度指令中的词汇和约束反映到交付成果中。对于面向读者的产物，在提示词主体中避免使用内部代号和审计约束，并说明合规证据应放在PR正文而非文档中。
  7. 修复缺陷类别，验证全面覆盖：当评审者指出缺陷实例时，指示工作者消除整个缺陷类别。要求提供全面覆盖的证据：一份包含所有候选对象的枚举与分类表格，或是一个能在修复前复现已知错误状态、修复后报告零错误的检测器。
  8. 依据角色与性能退化轮换会话，其次考虑上下文：针对每个独立的评审结论启动新会话，终止输出质量下降或执着于失败方案的会话，并在上下文耗尽前的自然边界轮换长期运行的工作者；剩余上下文百分比并非可靠的触发信号。在崩溃或轮换后重新调度时，枚举磁盘上的状态，包括文件路径和每个产物是否为最终版本，并明确说明哪些内容不得重新计算。在仓库政策允许的情况下，将交接状态记录在交接文档和PR评论中；保持PR正文面向读者，而非状态台账。
调度交付、报告格式和协调等传输机制属于
shunk031-orchestrate-herdr-workers
技能范畴。本技能仅负责提示词编写指导。