Communitygithub.com

T0mSIlver/skills

移除自我敘述的後設評論——那些描述所在成品、重述讀者已見內容或說明產出過程的文字——從 UI 文案、文件、程式碼註解、提交訊息和 PR 描述中。在編寫或審查這些表面時應用,並在編輯散文前使用 unslop。觸發條件:重述標籤的工具提示、「本節說明…」、重述下一行程式碼的註解、「執行時顯示進度」、重述差異的 PR 清單。

skills 是什麼?

「Unnarrate」技能是人工智慧代理的工具,用於自動檢測和刪除跨各種表面(包括 UI 文案、文件、程式碼註解、提交訊息和 PR 描述)的「後設評論」。後設評論指那些描述所在成品、重述讀者已見內容或說明產出過程的冗餘文字。該技能基於清晰的刪除測試:若文字在心理刪除後讀者沒有損失,或是可原封不動移植到其他專案、其他 PR 或不同程式碼上方,則應刪除。它能有效清除重述標籤的工具提示、重述下一行程式碼的註解、重述 diff 的 PR 清單等常見模式。然而,該技能也明確保留「為什麼」的註解、即時反饋、實際替代文字及帶有追蹤連結的待辦事項。支援的平台包括 AI 輔助開發環境(如 Claude Code、Cursor、Codex)以及基於代理的開發工作流程。使用方式為:先對受影響的表面進行全面清理,刪除而非改寫;刪除造成真正空缺時,改進成品本身而非敘述;最後對殘留文字執行 unslop。此技能附帶 `reference/terminology.md` 檔案,按社群命名現象並提供來源,便於引用或擴展檢查清單。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Unnarrate

與 unslop 搭配使用。Unslop 修正 AI 散文的語氣;這個工具則刪除根本不該存在的文字:後設評論 —— 那些向受眾敘述成品本身的文字。進度條已經宣告進度;旁邊再寫「執行時顯示進度」是第二個冗餘的符號。代理程式之所以不斷產生這類文字,是因為它們把思考鏈敘述到觸及的每一個表面。

刪除測試

刪除任何僅包含以下內容的句子、標籤或註解:

  1. 對所在成品的描述(「本節說明…」),
  2. 讀者已經能看到的內容(重述標籤的工具提示、重述下一行程式碼的註解),或
  3. 產出過程(// 應要求提取為輔助程式)。

兩個判斷標準決定模糊案例:

  • 在心裡刪除它。 如果讀者毫無損失,它就是無操作 —— 看似做了什麼但實際上沒改變任何事的文字。
  • 可移植性。 如果這行文字可以原封不動地出現在另一個專案、另一個 PR 或不同程式碼上方,它就沒有說明這個專案的任何獨特性。刪除它。

按表面類型決定刪除內容

UI 文案

  • 描述介面已自行執行行為的文案:「安裝時顯示進度」、「載入時出現轉圈圈」、「清單會自動更新」。控制項本身就是符號;不要添加語言符號。
  • 在可見轉圈圈旁邊的「載入中…」文字;「檔案上傳成功」→「檔案已上傳」。
  • 重述標籤的工具提示和說明文字:欄位「出生城市」,提示「請輸入您的出生城市」。
  • 位置敘述:「點擊下方按鈕提交」、「從下拉選單選擇選項」。
  • 入門/引導標記文案:列舉每個控制項,而非指向那個非顯而易見的操作。
  • 無障礙重複:<button> 上的 aria-label="提交按鈕",alt="圖表圖片"(螢幕閱讀器已宣佈角色)。

文件和 README

  • 「本文件說明…」、「在本指南中,我們將…」、「歡迎閱讀 X 的文件」。直接開始內容。
  • 只宣告後續章節的概述章節;結尾的「總而言之」段落重述頁面內容。
  • 重述簽章的 Docstring(get_user(id) — 「根據 id 取得使用者」);<summary>取得或設定 X</summary>。PEP 257 明確禁止這種寫法。
  • 範例程式碼上方的「以下範例示範如何…」;重述相鄰程式碼區塊的散文。
  • 對任何專案都成立的功能清單和章節介紹。

程式碼註解

  • 重述下一行程式碼:// 匯入 React、// 回傳值、// 遍歷項目。
  • 章節橫幅:// ===== 輔助程式 =====、// --- 步驟 3:驗證 ---。
  • 計劃和階段敘述:// 階段 2:重構、// 使用新建立的 Foo 模型。
  • 變更日誌敘述:// 從 useState 改為 useReducer、// 移除了舊的處理程式。Git 歷史已記錄這些。
  • 針對審查者而非未來讀者的註解:// 注意:我保留了這個行為不變。

提交和 PR

  • 逐檔案重述 diff 的清單;「此 PR 新增…」後面緊跟著標題原文。
  • 以重述內容填滿的範本區段:「測試計劃:執行測試」但沒有具體細節。
  • 努力敘述:「全面重構」、「謹慎保留向後相容性」。陳述審查者可以驗證的事實。

保留 —— 並非所有敘述都是無操作

  • 即時敘述是符號;靜態敘述是警訊。 代理在運作時串流顯示「正在安裝相依套件…」是真實的回饋。而描述這個回饋存在的文案則是反模式。
  • 「為什麼」的註解保留: 理由、不變量、關於非顯而易見行為的警告、問題和事件的連結。規則刪除的是重述,而非所有註解 —— 與周圍程式碼的註解密度保持一致。
  • 包含表面無法顯示資訊的指示保留: 格式(「YYYY-MM-DD」)、限制(「8 個以上字元」)、副作用(「這會電子郵件通知團隊」)、不可逆警告。
  • 真正的替代文字保留。 刪除「圖片的…」前綴,保留圖片所呈現內容的描述。
  • 附帶追蹤連結的待辦事項保留; 單純的 // TODO:改進這部分 則刪除。

應用方式

  1. 掃描受影響的表面,找出上述模式。刪除,不要改寫 —— 大多數命中案例不需要任何替代。
  2. 當刪除造成真正的空缺時,改進成品本身(更清晰的標籤、不言自明的控制項),而不是改進敘述。
  3. 然後對殘留的文字執行 unslop。

reference/terminology.md 按社群命名此現象(後設論述、空洞對話、顯而易見的註解、無操作)並提供來源,便於引用或擴展檢查清單。

相關技能