clean-revisions

当用户对你上一版产物(SKILL.md / prompt / 设计文档 / README / commit message / 代码注释段)提出修改意见,你即将产出 B 版本时——产物必须是一个干净的替换件,**禁止把"从 A 到 B 的修订过程"作为文字写进产物本身**。触发:用户说"改一下 / 重写 / 精炼一下 / 再写一份 / 优化一下 / 加上 X / 去掉 Y / 那段不要了 / 重新

SKILL.md

GitHub

clean-revisions

修订一个已经写过的产物时,你产出的不是"diff 叙事",是一个完整的、独立可读的新版本。读者打开新版本不需要知道旧版本存在过。

唯一一条核心规则

产物里只有"是什么",不能有"以前是什么、为什么改、怎么改的"。

如果你想解释 A → B 为什么这么改,写在对话回复里——产物之外、代码块之外、文件之外的那一层。

心智切换:narrative → replace

错的心智 对的心智
"用户指出 A 的 X 问题,我要改 X 写出 B" "用户的新需求集合是 {old 要求} ∪ {新约束}。我从零写一份满足这个集合的产物。"
"我在 A 的基础上 patch 几处" "我把 A 当参考资料,重写一个独立产物"
"记得告诉读者哪里改了" "读者不关心改没改,读者要的是当前形态"

禁词清单(出现在产物正文里就是错的)

中文:

  • 原本…现在…
  • 之前提到…
  • 已更新 / 已修改 / 已优化 / 已增补
  • 因为你说…所以…
  • 这次去掉了…
  • 上一版里有 X,本版……
  • (注:…)这种修订旁注

英文:

  • previously
  • now (used as "原来 X, now Y" 的对照)
  • updated to / changed to / revised to
  • as you mentioned / as noted / per your request
  • this version
  • the new approach
  • (note: ...) parenthetical revision asides

上面禁词的"形态"也禁——把"原本 X,现在 Y"改成"原本是 X,已经改为 Y"不算解决问题。

反例 / 正例

反例(产物里出现修订叙事):

# fix-login-bug

原先这个 skill 只处理 OAuth 路径,**现在按你的要求**扩展到 SAML。
之前的 description 太长,**已经精炼**到一句话。

## 触发条件
用户说"登录挂了"——之前还包括"login 不工作",**这次去掉**避免和 ...

正例(同一个产物,干净版本):

# fix-login-bug

排查 OAuth 与 SAML 两条登录路径的故障定位 skill。

## 触发条件
用户说"登录挂了"。

注意正例里:

  • 没有"原先 / 现在"
  • 没有"按你的要求"
  • 没有"已经精炼"
  • 触发条件直接给当前结论,不解释为什么"这次去掉"了某个候选

给用户的解释放哪

如果你判断这次改动用户需要知道为什么(例如你做了用户没明说的判断),只在对话回复里说:

"改了。把 description 从工作流概要改成纯触发条件,理由:避免 Claude 跳过 skill 主体(详见 writing-skills CSO 原则)。文件如下:"

[干净产物]

对话里说"我改了什么、为什么改" → OK 产物文件里说"我改了什么、为什么改" → 违反本 skill

抵抗 sycophancy 的同源约束

  • 不要在产物开头加"好的 / 当然 / 没问题 / 让我们 / 我现在就来"
  • 不要在产物结尾加"希望这版本满足你 / 如果还有需要告诉我 / 这次应该更清晰了"
  • 这些都是对话 surface 的话,不属于产物

测自己的草稿

在交付前对你写出的草稿做一次"chemical wash":

  1. 逐字搜本 skill 的禁词清单——出现一个就把那一句重写成"当前形态陈述",不是删
  2. 问自己:如果一个全新读者只看这份产物,能不能完整理解它? 有任何"需要知道前一版才能看懂"的地方,重写
  3. 问自己:这份产物可以被独立 cite 吗?任何依赖"上面/前面/上次"的指代,重写

测过再交付。

例外(什么时候本 skill 不适用)

  • 用户明确要 diff:例如"列一下这次都改了什么"——那就在对话里给 diff,但产物本体仍然干净
  • 真·变更日志类产物(CHANGELOG.md、迁移说明):那是"记录变更"作为它本来的内容形态,不属于 revision residue
  • 学术论文 / 法律文件 / 合规审计场景,要求保留 revision history——按那个领域的规矩走
  • 解释性教学模式(Claude 的 explanatory / learning mode)显式打开时

与其他 skill 的关系

  • [[writing-skills]](superpowers):写 skill 的更系统教程,本 skill 是它"反 narrative artifact"那条原则的纯净版抽取
  • [[grill-me]]:grill-me 的对话本身不是产物,可以自由 narrate;但 grill-me 收尾如果要落"决策记录"成文件,那份文件适用本 skill