Communitygithub.com

T0mSIlver/skills

移除自我叙述的元评论——即那些描述所在产物、重复读者已见内容或叙述生成过程的文本——从界面文案、文档、代码注释、提交信息和PR描述中。适用于编写或审查这些内容时,以及在编辑散文之前使用。

skills 是什么?

该技能旨在消除AI生成内容中常见的“元评论”现象,即那些描述自身所在产物、重复读者已见信息或叙述生成过程的冗余文本。它主要应用于UI文案、文档、代码注释、提交信息和PR描述等场景。技能的核心是通过“删除测试”来判断文本是否冗余:如果删除后读者不损失任何信息,或者该文本可以原封不动地移植到其他项目,那么就应该删除。它提供了各类表面的具体删除示例,包括UI中的重复提示、文档中的结构描述、代码中的逐行注释、以及PR中的文件级重复列表。同时,技能也明确了保留的例外情况,如“为什么”这类解释性注释、实时反馈、以及无法通过界面表达的必要信息。该技能是“unslop”的搭档,先删后改。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/T0mSIlver/skills/tree/HEAD/unnarrate

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

去叙述

与 unslop 搭配使用。Unslop 修复 AI 文本的语调;这个工具删除那些根本不应该存在的文本:元评论——即叙述产物本身以面向其受众的写作。进度条本身就已经在宣告进度;旁边写着“运行时会显示进度”是第二个多余的指示符。AI 智能体持续产生这类文本,因为它们将其思维链叙述到它们触碰的每一个表面上。

删除测试

删除任何唯一内容属于以下情况的句子、标签或注释:

  1. 对所在产物的描述(“本节描述……”),
  2. 读者已经可以看到的内容(重复标签的工具提示,重复下一行的注释),或
  3. 生成它的过程(// 根据要求,提取到辅助函数中)。

两个检查决定模棱两可的情况:

  • 在脑海中删除它。 如果读者没有损失任何东西,那它就是一个无操作——一段看似有作用但实际上不改变任何东西的文本。
  • 可移植性。 如果该行可以原封不动地出现在另一个项目、另一个 PR 或不同的代码上方,那么它就没有说明本项目的任何信息。删掉它。

按表面需要删除的内容

UI 文案

  • 描述界面已自行执行的行为的文案:“安装时会显示进度”、“加载时会显示旋转指示器”、“列表会自动更新”。控件本身就是指示符;不要添加语言的指示符。
  • 可见旋转指示器旁边的“正在加载……”文本;“文件上传成功” → “文件已上传”。
  • 重复标签的工具提示和帮助文本:字段“出生城市”,提示“输入您的出生城市”。
  • 位置叙述:“点击下方按钮提交”、“从下拉菜单中选择一个选项”。
  • 新手引导/教练标记文案,列举每一个控件,而不是指向非显而易见的一个操作。
  • 可访问性冗余:<button> 上的 aria-label="提交按钮",alt="图表图片"(屏幕阅读器已宣布角色)。

文档和 README

  • “本文档描述……”、“在本指南中,我们将……”、“欢迎阅读 X 的文档”。直接从内容开始。
  • 仅用于宣布后续章节的概述部分;末尾重复页面内容的“总结”段落。
  • 重复函数签名的文档字符串(get_user(id) — “通过 id 获取用户”);<summary>获取或设置 X</summary>。PEP 257 明确禁止了这一点。
  • 示例上方的“以下示例展示了如何……”;重复相邻代码块的散文。
  • 对任何项目都成立的功能要点和章节介绍。

代码注释

  • 重复下一行:// 导入 React,// 返回值,// 遍历项目。
  • 章节横幅:// ===== 辅助函数 =====,// --- 步骤 3:验证 ---。
  • 计划和阶段叙述:// 阶段 2:重构,// 使用新创建的 Foo 模型。
  • 变更日志叙述:// 从 useState 改为 useReducer,// 移除了旧的处理程序。Git 历史记录了这些。
  • 面向审阅者而非未来读者的注释:// 注意:我保留了此行为不变。

提交信息和 PR

  • 逐文件重复 diff 的要点列表;“此 PR 添加了……”,后面跟的是标题原样。
  • 填充了重复内容的模板章节;“测试计划:运行了测试”,没有具体细节。
  • 努力叙述:“全面重构”、“仔细保留了向后兼容性”。陈述审阅者可以验证的事实。

保留——并非所有叙述都是无操作

  • 实时叙述是指示符;静态叙述是问题信号。 智能体在运行时流式输出“正在安装依赖……”是真实的反馈。而描述该反馈存在的文案才是反模式。
  • 保留“为什么”注释: 基本原理、不变性、关于非显而易见的警告、指向问题和事件的链接。规则删除的是重复,而不是注释——与周围代码的注释密度匹配。
  • 保留包含界面无法显示的信息的指令: 格式(“YYYY-MM-DD”)、约束(“8+ 个字符”)、副作用(“这将给团队发送邮件”)、不可逆性警告。
  • 保留真正的替代文本。 删除“……的图片”前缀,保留图片内容的描述。
  • 保留带有跟踪链接的 TODO; 仅 // TODO:改进此项 则删除。

应用方法

  1. 扫描变更过的表面,查找上述模式。删除,不要重写——大多数命中点不需要替换。
  2. 当删除留下真正的空白时,修复产物(更清晰的标签、不言自明的控件),而不是修复叙述。
  3. 然后对保留下来的内容运行 unslop。

reference/terminology.md 按社区命名了该现象(元话语、快乐谈话、显而易见的注释、无操作),并给出了来源,供引用或扩展检查清单使用。

相关技能