prompt-principles
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseEdit rule: each line is a principle with its reason and when it yields. Decisions go to the
decision records, rules a check can hold go to the check, and a line is added only on a person's
yes, after sharpening an existing line is ruled out.
- Show a prompt change working by driving the behavior cases it touches, new or existing eval cases, through — a case the change must catch and one where it must not fire, under a pass rule fixed before the runs — rather than asking the maintainer to judge the words — the maintainer judges a prompt change by what it makes a run do, and a drive is the evidence they rely on; a suite that rewards one direction pulls later tuning further that way; a whole eval suite runs only when they ask, because each run is many paid sessions. Where the change adds something that runs on every use, report each arm's cost and wall time beside its verdict. Yields when the text must be approved as written, such as a public post, or when no case can reach the behavior; then say so.
scripts/verify drive - Settle a prompt change on one run per arm and accept the noise: each touched case once on the skills before the change and once after, adding runs only where that pair does not settle it — a must-catch case passes or fails on both arms, or a verdict is borderline — every run is a paid model session and more runs get expensive, while one pair is good enough once its noise is accepted. Yields when the decision would be costly to reverse and rests on one borderline pair, or when the maintainer asks for a fuller measurement.
- When a skill grows a flag or a mode, keep what every invocation needs inline in , move that mode's bulk to a file under
SKILL.mdloaded only when the mode resolves, and keep the trigger inreferences/, written as an instruction on an event the run can observe, in aSKILL.mdorModestable beside the flags; after adding a reference, check that the default path reaches it — otherwise the default invocation carries the whole file to use a fraction of it, and a trigger inside the deferred file can only be read after the load it was meant to gate; a passive mention or a bare pointer does not load, and the miss is silent. Yields when a mode's mechanics run to a paragraph: an indirection costs a load and a reader's place, and can strand a subtle trigger.What loads - A shipped skill carries its own copy of every term, step, rule and probe its behavior depends on, defined where it first uses it, and defers none to the glossary, another skill, its caller, a host-shipped skill or a section a reader may never reach — a skill installed in someone else's project gets its own and the references its loading layer names, never this repository's
SKILL.md, and the misses were found on standalone runs: a completion path named a skill that did not ship;CONTEXT.md's gloss of fog at first use is the pattern. Yields for plain words that carry no project meaning, and inside one skill or between files a run loads together: there a rule has one owning section and the others point to it, because copies drift — one review found 29 defects, most of them one rule changed in one file while another still stated the old one.figure-out - A shipped skill names the capability it needs, never how one setup reaches it — a fixed path, a tool list, an API or MCP server, another CLI — and says nothing only this repository needs — everyone has a different setup, and the skills run on other harnesses. Hard limit, no trade-off.
- A shipped prompt states what the work owes, the maintainer's rulings, what a run cannot read elsewhere, and corrections of defaults a run was seen to take; how to get there is the run's, and the text holds nothing its own reader does not act on — no account of what a caller, a sibling skill or an earlier version owns. A thin result is the correct one — spelled-out method spends attention on every run, overfits it to one path and holds a better model to today's method. Yields when a drive or session shows a run missing something: it goes back in as an outcome, not as steps.
- When a shipped rule is stated and still broken, do not state it more firmly or add a sibling beside it: replace the failed text with something a run can execute and a reviewer can check (a shape, a named standard, a bound with a rule for what to cut), make it a gate or a check, remove the choice, or give the output one cold reading by a context that did not write it — models comply reliably with a concrete output shape and unreliably with quality adjectives, and more words in a layer nothing verifies change nothing. Yields when output reads as padded to fill the shape: then the shape is the suspect.
- Where a prompt needs a call made, name what to weigh and let the model judge; do not stand a size threshold, a per-mode matrix, a closed list, a fixed template, a required tool or a numeric score in for the judgment, and correct a model's default by naming the specific pattern, as a default it may still choose — stand-ins are brittle and game-able, force-fit the novel case and claim precision nobody has, and a general exhortation only swaps one default for its neighbour. Yields when a prose hint was seen to make a model invent the mechanism (then give the literal action), and when an interaction grammar must survive intact (then ship an executable example).
- Write a prompt's limits so they do not rest on the reading model's temperament: a loop pushed against stopping early states the condition at which it stops, a bar says what a finding must name to count, and a property that decides behavior is declared, never inferred — the prompt that corrects one model's bias amplifies the opposite bias in another: an unstated finish line had runs re-verifying passing gates for two to four times as long. No yield has been stated.
- Put a correction in the file that loads only for the shape of work that showed the failure, folded into the line that already owns that moment before a new one is added — a line in an always-loaded body tilts and weighs down every run, including the small asks that never had the problem. Yields when the same failure is seen in work that file does not load for.
- A restructure, slim or merge of a prompt accounts for every rule it removes or adds — each carried, or dropped or added for a named reason, line by line rather than by section — rewrites here have repeatedly lost load-bearing rules along with the scaffold they meant to cut, and merges have added lines that caused regressions. Yields when a dropped rule shows no need on a drive: record it as dropped rather than restore it.
Before calling prompt work done, check it against these principles from a fresh start — a new
session, or a reviewer who did not do the work. Fix what departs unless the person chose the
departure, and check again only after a fix, until a check finds none. Name each departure kept,
with the principle and why.
编辑规则:每一行都是一项原则,同时说明其理由以及何时应让步。决策写入决策记录;检查能够承载的规则写入检查项;只有在获得本人明确同意后,且已排除通过强化现有规则解决问题的可能,才能新增一条规则。
- 通过 驱动变更所触及的行为用例(新增或已有的 eval case),来证明 prompt 变更确实有效:其中应有一个变更必须捕获的 case,以及一个变更不得触发的 case,并采用运行前固定的通过规则;而不是请维护者评判文字。维护者会依据一次运行在变更后做了什么来判断 prompt 变更,而 drive 正是其赖以判断的证据。只奖励一个方向的测试套件会促使后续调优进一步偏向该方向。完整 eval suite 仅在维护者要求时运行,因为每次运行都会消耗大量付费 session。若变更加入了每次使用都会运行的内容,应在各 arm 的判定结果旁报告其成本和墙钟时间。当文本必须按原样审批(如公开帖子),或没有任何 case 能触达该行为时,本原则让步;此时应明确说明。
scripts/verify drive - 每个受影响的 case 针对变更前的 skill 运行一次,变更后再运行一次;仅当这一对运行结果仍无法定论时,才增加运行次数——即 must-catch case 在两个 arm 上都通过或都失败,或者判定结果处于临界状态。每次运行都是一次付费的模型 session,而更多运行成本高昂;一旦接受噪声,一对运行结果就足够。当某项决策的逆转成本很高且仅依赖一对处于临界状态的运行结果时,或维护者要求更完整的测量时,本原则让步。
- 当一个 skill 新增 flag 或 mode 时,在 中内联保留每次调用都需要的内容;将该 mode 的大量细节移到
SKILL.md下的文件中,并且仅在该 mode 被确定时加载。触发条件仍保留在references/中,写成针对 run 可观察事件发生时的指令,并置于 flags 旁边的SKILL.md或Modes表中。新增 reference 后,应检查默认路径是否能够触达它;否则,默认调用为了使用其中一小部分内容,却要加载整个文件,而放在延迟加载文件内的触发条件,也只有在其本应把关的加载发生后才能被读取。单纯提及或只给出一个指针不会触发加载,遗漏也不会产生任何提示。当一个 mode 的机制说明已经长到足以成为一段文字时,本原则让步;间接引用会多消耗一次加载和读者定位阅读内容的时间,并可能使一个微妙的触发条件被搁置。What loads - 发布版 skill 必须自带其行为所依赖的每个术语、步骤、规则和探针的副本,并在首次使用之处定义;不得将任何内容转交给术语表、另一个 skill、调用方、宿主随附的 skill,或读者可能永远不会读到的章节。安装在他人项目中的 skill 应拥有自己的 以及加载层所命名的 references,绝不应包含本仓库的
SKILL.md。这些遗漏是在独立运行中发现的:完成路径引用了一个未随 skill 一并交付的 skill;CONTEXT.md在首次使用处对 fog 作出解释,就是应遵循的模式。对于不承载项目特有含义的普通词语,以及在单个 skill 内或同一次运行会一起加载的文件之间,本原则让步:在这些范围内,一条规则应只有一个归属章节,其他位置只作指向,因为副本会发生漂移——一次审查发现了 29 个缺陷,其中大多数是某条规则在一个文件中已经更改,而另一个文件仍在陈述旧版本。figure-out - 发布版 skill 只说明所需的能力,绝不描述某一种环境如何获得该能力——例如固定路径、工具清单、API 或 MCP server、另一个 CLI——也不陈述只有本仓库才需要的信息,因为每个人的环境不同,而这些 skill 会运行在其他 harness 上。这是硬性限制,没有权衡空间。
- 发布版 prompt 应说明工作需要交付什么、维护者作出过哪些裁定、某次 run 无法从其他地方读取什么,以及要纠正哪些已被观察到会被 run 采用的默认行为。如何达成结果是 run 自己的事情;文本不应承载任何其读者不会据此行动的内容——不交代调用方、同级 skill 或较早版本负责什么。简明扼要的结果才是正确的:把方法逐步写明会占用每次 run 的注意力,使其过拟合于单一路径,并把更强的模型束缚在今天的方法上。当 drive 或 session 显示某次 run 缺少某些内容时,本原则让步;缺少的内容应作为结果要求写回,而不是作为操作步骤写回。
- 当一条发布版规则已经写明却仍然失效时,不要更强烈地重述它,也不要在旁边新增一条同类规则:应将失败文本替换为 run 可执行且审查者可以检查的内容,例如明确的输出结构、命名标准、带有裁剪规则的上限;将其设为 gate 或 check,移除选择空间,或者让未参与撰写的上下文对输出做一次冷读。模型对具体输出结构的遵守通常很可靠,对质量形容词的遵守则不可靠;在没有任何验证的层中增加更多文字不会带来任何变化。当输出看起来只是为了填满规定结构而被注水时,本原则让步;此时应怀疑该结构本身。
- 当 prompt 需要作出某种判断时,应说明需要权衡哪些因素,并让模型自行判断;不要用大小阈值、逐 mode 矩阵、封闭清单、固定模板、指定工具或数值评分来代替判断。要纠正模型的默认行为,应直接指出具体模式,因为模型仍可能选择原默认值。用来代替判断的方案既脆弱又容易被博弈,会把新 case 生硬套进去,却声称拥有无人真正具备的精确度;泛泛的劝诫也只会把一个默认行为换成相邻的另一个。当观察到一段文字提示使模型自行发明机制时,本原则让步,此时应给出字面操作;当某种交互语法必须原样保留时,也应让步,此时应提供可执行示例。
- prompt 的限制不应取决于阅读该 prompt 的模型具有何种性情:一个被要求不要过早停止的循环,应明确说明它在何种条件下停止;一条达标线应说明一项发现必须点明什么才算数;决定行为的属性必须明示,而不能依靠推断。用于纠正某个模型偏见的 prompt,会放大另一个模型中的相反偏见:此前,由于未声明终止边界,run 曾以长至原来两到四倍的时间反复验证已经通过的 gate。本文未说明任何让步情形。
- 将纠正措施放入只针对曾暴露该失败的工作类型才会加载的文件中;在新增一行之前,先将其并入已经负责该节点的现有行。始终加载的正文中的任何一行,都会影响每次 run 并使其负担加重,包括那些从未出现该问题的小请求。当在某个文件不会加载的工作中再次观察到同一失败时,本原则让步。
- 对 prompt 进行重构、精简或合并时,必须逐行交代每条被移除或新增的规则——是延续保留,还是因某个明确原因而删除或新增,而不能只按章节交代。此前的重写曾多次在删减脚手架时一并丢失承重规则,合并也曾新增导致回归的条款。当 drive 显示被删除的规则并无必要时,本原则让步;应将其记录为已删除,而不是恢复。
在将 prompt 工作宣布完成之前,应从全新起点按照这些原则进行检查——使用新的 session,或由未参与该项工作的审查者检查。除非负责人明确选择偏离这些原则,否则应修复所有偏离之处;且仅在完成修复后再次检查,直到检查不再发现问题。应列出每一项被保留的偏离及其对应原则和原因。