アンナレート(Unnarrate)
unslopのコンパニオンスキル。unslopがAIの散文の響きを修正するのに対し、これはそもそも存在すべきではないテキスト、すなわちメタコメンタリー(作品そのものをその読者に対して語る文章)を削除します。プログレスバーは既に進行状況を示していますが、その横に「実行中に進行状況が表示されます」と書くのは、2つ目の冗長な標識です。エージェントは思考過程をあらゆる表面に語りかけるため、このようなテキストを常に生成します。
削除テスト
次の内容のみを含む文やラベル、コメントは削除します。
- それが置かれている作品の説明(「このセクションでは…について説明します」)
- 読者が既に見える内容(ラベルを言い直すツールチップ、次の行を言い直すコメント)
- 生成過程(
// リクエストにより、ヘルパーに抽出)
接戦の場合は、次の2つのチェックで判断します。
- 頭の中で削除してみる。 読者が何も失わなければ、それはノーオペレーション(何かを行っているように見えて何も変えないテキスト)です。
- 移植性。 その行が別のプロジェクト、別のPR、別のコードの上でも変更せずに使えるなら、このプロジェクトについては何も語っていません。削除しましょう。
削除対象(表面別)
UIコピー
- インターフェースが既に行っている動作を説明するコピー:「インストール中に進行状況が表示されます」「ロード中にスピナーが表示されます」「リストは自動的に更新されます」。ウィジェット自体が標識です。それに言葉の標識を追加してはいけません。
- 目に見えるスピナーの横にある「読み込み中…」のテキスト。「ファイルが正常にアップロードされました」→「ファイルをアップロードしました」。
- ラベルを言い直すツールチップやヘルプテキスト:フィールド「出生地」、ヒント「あなたの出生地を入力してください」。
- 位置的なナレーション:「下のボタンをクリックして送信」「ドロップダウンからオプションを選択してください」。
- すべてのコントロールを列挙するだけで、1つの非自明な操作を指し示さないオンボーディング/コーチマークコピー。
- アクセシビリティの重複:
<button>上のaria-label="送信ボタン"、alt="グラフの画像"(スクリーンリーダーは既にロールを読み上げます)。
ドキュメントとREADME
- 「このドキュメントでは…について説明します」「このガイドでは…を行います」「Xのドキュメントへようこそ」。コンテンツから始めましょう。
- 続くセクションを単に予告するだけの概要セクション、ページを言い直す末尾の「まとめ」段落。
- シグネチャを言い直すdocstring(
get_user(id)— 「IDでユーザーを取得します」);<summary>Xを取得または設定します</summary>。PEP 257はこれを明確に禁止しています。 - 例の上にある「次の例は…を示しています」という散文、隣接するコードブロックを言い直す散文。
- どのプロジェクトでも当てはまる機能の箇条書きやセクションの導入文。
コードコメント
- 次の行を言い直す:
// Reactをインポート、// 値を返す、// アイテムをループ処理する。 - セクションバナー:
// ===== ヘルパー =====、// --- ステップ3: 検証 ---。 - 計画やフェーズのナレーション:
// フェーズ2: リファクタリング、// 新しく作成されたFooモデルを使用。 - 変更履歴のナレーション:
// useStateからuseReducerに変更、// 古いハンドラを削除。Gitの履歴がこれを保持しています。 - 将来の読者ではなくレビューアに向けられたコメント:
// 注: この動作はそのまま維持しました。
コミットとPR
- 差分をファイルごとに言い直す箇条書き。「このPRは…を追加します」に続いてタイトルそのまま。
- 言い直しで埋められたテンプレートセクション。「テスト計画: テストを実行しました」— 具体性なし。
- 努力のナレーション:「大規模なリファクタリング」「下位互換性を注意深く維持」。代わりに、レビューアが確認できる事実を述べてください。
保持するもの — 語るものすべてがノーオペレーションではありません
- ライブナレーションは標識です。静的ナレーションは兆候です。 エージェントが作業中に「依存関係をインストール中…」とストリーミングするのは実際のフィードバックです。そのフィードバックの存在を説明するコピーはアンチパターンです。
- 「理由」のコメントは残します: 根拠、不変条件、非自明な動作に関する警告、問題やインシデントへのリンク。このルールは言い直しを削除するものであり、コメントを削除するものではありません — 周囲のコードのコメント密度に合わせてください。
- 表面が表示できない情報を伝える指示は残します: 形式(「YYYY-MM-DD」)、制約(「8文字以上」)、副作用(「これによりチームにメールが送信されます」)、不可逆性の警告。
- 本当のaltテキストは残します。 「…の画像」という接頭辞は削除し、画像が何を示しているかの説明は残します。
- トラッキングリンク付きのTODOは残します。 裸の
// TODO: 改善するは削除します。
適用方法
- 変更箇所を上記のパターンでスキャンします。書き換えずに削除します — ほとんどの該当箇所は置き換えを必要としません。
- 削除によって実際のギャップが生じた場合は、ナレーションではなく作品自体を修正します(より明確なラベル、自己説明的なコントロール)。
- その後、残ったものに対して
unslopを実行します。
reference/terminology.mdは、この現象をコミュニティごとに命名しています(メタ談話、ハッピートーク、自明コメント、ノーオペレーション)。引用やチェックリスト拡張のための出典も記載されています。