antislop-code

antislop-code

反スロップ：AI コーディングエージェント向けルール。コードコメントスキル

antislop システムの一部です。コアである antislop.md と併せて読んでください。このスキルは、汎用的な AI らしい（装飾的、明白な内容の言い換え、堅苦しい、大げさな）コメントを除外しつつ、実際に情報を伝えるコメントは残します。コアのルールを番号で参照し、重複させたり、番号を振り直したりしません。コードコメントを書く、または編集するタスクでは、このスキルを読み込んでください。

このスキルの使い方

• コードコメントに触れるタスクでは、必ず antislop.md と併せて読み込んでください。コアには仕組み（目的のテスト、3 つのティア、デリバリーゲート）が記載され、このスキルにはコメント固有の詳細が記載されています。
• 各項目は同じ形式です。Tell（パターン）、Why（スロップに見える理由）、Fix（代わりに何をするか）があり、該当するコアのルールを R-XX で示します。
• **適用範囲のガードレール：**このスキルで変更するのはコメントのみです。実行可能なコード、識別子、インポート、フォーマット、インデント、空白、制御フロー、ロジックは決して変更しないでください。判断に迷った場合は、コードに手を加えないでください。
• コアに記載されているデリバリーゲートが引き続きゲートとして機能します。このファイルの末尾にある「コードコメントチェックリスト」は、併せて実行するコメント固有の補足チェックリストです。

何も付け加えないコメント

装飾的な区切り

• **Tell：**同じ文字を繰り返したバナーコメント、すべて大文字のラベル、またはセクション名を囲む罫線。例：Authentication を囲む // =======================、// -------- WORKFLOW --------、/* ---- ROUTES ---- */ のような見出し。
• **Why：**装飾そのものがメッセージです。= や - で囲まれたラベルは、情報を加えずに「AI が作った」と示し、すべて大文字の表記は大声で叫んでいるように見えます。
• **Fix：**簡潔な一行に置き換えるか、ラベルに意味がなければ完全に削除してください（R-31）。

明白な内容の言い換え

• **Tell：**次の行や宣言にすでに示されていることを繰り返すコメント。たとえば、let count = 0 の上にある // Initialize the variable、class User {} の上にある // User class、function validateUser() の上にある // Validate user、または const userAge = 25; // User age is 25 です。
• **Why：**情報を加えずに読み取りの負荷を増やすだけです。コードにすでに書かれている内容を、コメントがただ繰り返しています。
• **Fix：**コメントを削除し、コード行には手を加えないでください。

ワークフローの説明

• **Tell：**処理の流れを段階ごとに説明するコメント。たとえば、// Step 1: Validate input、// Step 2: Process request、// Step 3: Return response、または // First...、// Next...、// Finally... です。
• **Why：**制御フローはコード自体から読み取れます。番号を振ると説明ではなくチェックリストのように見えます。
• **Fix：**削除してください。流れを本当に追いにくいのであれば、それは構造の問題であり、コメント不足の問題ではありません。

中身のないラベル

• **Tell：**情報が伴わない汎用的なラベル。// Main logic、// Core logic、// Business logic、// Helper function、// Entry point、// Error handling、// Note: This is important.、// Important: Please read. などです。
• **Why：**ラベルが示すのは分類であって、事実ではありません。「Main logic」では、コードから推測できないことは何もわかりません。
• **Fix：**具体的な情報を伝えていない限り、削除してください。「Note: retries happen only on 5xx」には残す価値がありますが、「Note: this is important」にはありません。

曖昧なプレースホルダー

• **Tell：**具体的な内容を示さず、将来の作業を予告するコメント。// TODO: Improve this、// Future improvements、// Additional optimization can be added here、// Add more validation などです。
• **Why：**曖昧な TODO はノイズです。タスク（何を、なぜ）ではなく、感想（もっとよくできる）を示しています。
• **Fix：**削除してください。実行に移せるだけの背景情報を含み、具体的なタスクを示す場合に限り、TODO を残してください。

シグネチャの言い換え

• 見分け方： シグネチャをそのまま言い換えただけのドキュメントです。たとえば、関数名とパラメーターを見れば内容がわかる関数に対して、@param price The price. や @returns Total price. を繰り返す JSDoc ブロックなどです。
• 理由： シグネチャを繰り返すドキュメントは、理解を深めずに文章量だけを増やします。読者に新しい情報は何も伝わりません。
• 修正方法： 繰り返しを簡潔にするか、削除します。ビジネスルール、エッジケース、前提条件、アルゴリズム、制限事項、副作用、API の動作、セキュリティ上の影響を説明するドキュメントは残します。実質的なドキュメントは決して削除しないでください。

装飾的な絵文字

• 見分け方： // ✅ Validation や // 🚀 Performance のように、コメントで装飾として絵文字を使っています。
• 理由： 絵文字はコード上の視覚的なノイズであり、特定の絵文字（✅、🚀、🔒）は AI がよく使う語彙です。
• 修正方法： 平易な英語に置き換えるか、ラベルに意味がなければ削除します。

終了マーカー

• 見分け方： } // end if、# End of function、// End processOrder のように、ブロックの終了を示すだけのコメントです。
• 理由： 閉じ波括弧ですでにブロックは終了しています。このマーカーは必要だからではなく、習慣で付けられています。
• 修正方法： 削除します。長いファイルで終了マーカーが本当に役立つまれなケースでは、習慣で付けるのではなく、混乱を防げる箇所に限って残します。

あるべき書き方

説明しすぎるコメント

• 見分け方： 1 行で収まる事実について、理由、背景、経緯を重ねて何行にもわたって説明するコメントです。たとえば、スタブが PATH 上にあること、回避策がどのリリースで導入されたか、それ以前に何が壊れていたかを説明する 4 行のブロックなどです。どの文も正しいとしても、長さが見分ける手掛かりになります。
• 理由： 人はメモを残し、ジェネレーターは事例を書きます。1 行の事実を段落に膨らませたり、「X なので Y、したがって Z」という連鎖を組み立てたり、問題番号や修正されたバージョンを挙げたりするのは、ほかの AI らしいパターンと同じ冗長な装飾です。その結果、重要な 1 行が不要な行に埋もれてしまいます。
• 修正方法： 制約だけに絞ります。1 行、長くても 2 行にし、3 行にはしません。プラットフォーム特有の落とし穴、気付かれずに起こる失敗、プロトコルのルール、パフォーマンスへの影響は残します。問題番号、バージョンの経緯、理由を重ねた説明は省きます。

1 行ごとの解説

• 見分け方： // Initialize count、続けて // Loop items、// Get item、// Increment、// Return result のように、当たり前の処理を 1 行ずつ説明するコメントです。
• 理由： すべての行にコメントが付いていると、どのコメントも重要ではなくなります。読者は意味のあるコメントを見つけるために、一つひとつ確認しなければなりません。
• 修正方法： 1 行ごとではなく、論理的なブロックごとに簡潔なコメントを 1 つ書きます。ブロックにコメントが不要なら、何も書きません。

堅苦しい、または大げさな表現

• 見分け方： 「この関数は、認証プロセスを続行する前に、渡された認証情報が有効かどうかを検証する役割を担っています」のように形式ばって長いコメントや、// MAIN LOGIC のように大文字で強調するコメントです。
• 理由： 堅苦しく大げさな表現は、次の担当者にメモを残すエンジニアの言葉ではなく、生成された文章のように読めます。
• 修正方法： 自然な開発者の言葉で、短く、通常の文頭大文字表記のコメントを書きます。// Validate credentials before issuing a token. のようにします。よいコメントは「何を」ではなく「なぜ」を説明し、簡潔にまとめます。

禁止事項ではない（これらは保持する）

次のことを説明するコメントは、決して削除しないでください。

• ビジネスロジックと意図
• アーキテクチャ上の決定
• セキュリティ上の考慮事項
• パフォーマンスのトレードオフ
• 並行処理の動作
• プロトコルの詳細
• API 契約
• 回避策
• エッジケースと前提
• ライセンスおよび法的通知

保持しなければならない例:

// Stripe may retry webhook deliveries for up to three days.
// Ignore duplicate events using the event ID.

コメントは、コードがすでに示していない何かを説明しているとき、その存在価値があります。つまり、理由、制約、自明ではない動作です。

存在価値があるということは、何が残ってよいかを示すものであり、どれだけ長くてよいかを示すものではありません。回避策のメモは回避策についての 1 行であり、それについての段落ではありません。上記の例が 2 行なのは、2 つの事実が実在するからであり、2 行が目標だからではありません。このリストは、コメントが本来受けるべきでないレビューを生き延びる最も一般的な理由です。内容が正当に価値があるため、長さが検討されないのです。価値は長さではありません。

コードコメントチェックリスト

タスクがコメントに触れる場合は、中核となる Delivery Gate と併せてこれらを実行してください。すべての回答が はい でなければなりません。

• すべてのコメントは、コードがすでに示していない情報を追加していますか？ (R-31)
• コメントは、装飾的な区切り線、すべて大文字のバナー、罫線で描かれたヘッダーを避けていますか？
• コメントは、自明な行、宣言、シグネチャの言い換えを避けていますか？
• コメントは、手順ごとのワークフローの記述を避けていますか？
• コメントは、空の TODO を避け、TODO にはタスク名が書かれていますか？
• コメントは、装飾的な絵文字を避け、末尾に句点を付けていますか？
• コメントは、1 行ごとではなく、1 つの論理ブロックにつき 1 つですか？
• コメントは 1 行、2 つ目のコメントが新しい事実を伝える場合にのみ 2 行ですか？
• 残ったコメントは、短く、自然で、文頭が大文字になっていますか？
• スコープのガードレールは守られていますか。つまり、変更されたのはコメントのみで、コードは変更されていませんか？