# Deslop Comments

> 日本語のコードコメントからAI生成特有の冗長さ・不自然さを除去する。編集対象はコメントのテキストのみで、コード本体の挙動・制御フロー・import・依存関係は変更しない。 「コメントを整理して」「コメントが冗長」「コメントが不自然」「AIっぽいコメントを消して」「deslop-comments」「/deslop-comments」と言われたときに使う。 実装が完了した直後、大きめの生成コード変更のあとにコメントの壁が残っているときにも使う。

- Skill: `rerelurelu/deslop-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rerelurelu/deslop-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rerelurelu/deslop-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: GPL-3.0
- Author: rerelurelu (https://skillmd.com/u/rerelurelu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rerelurelu/deslop-comments

---


# Deslop Comments (日本語特化)

対象は日本語で書かれたコードコメント（line comment、block comment、JSDoc/TSDoc、docstring）。英語コメントの内容評価はこのSkillの対象外とする。

**変更範囲の契約**: このSkillが変更してよいのはコメントのテキストと、それに付随する空白だけ。コードの実行結果が変わる変更（ロジック、分岐、import、依存関係、try/catchの構造）は一切行わない。それが必要に見える場合はコメントを直さず、その旨を報告するだけにとどめる。

## 対象範囲 (scope)

`$ARGUMENTS` が指定されていればそれを対象範囲にする。指定が無ければ `git status` の modified / staged / untracked ファイルを対象にする。対象が無ければその旨を報告して終了する。

## 判定基準

コードコメントは、そのコードを理解するためにその場で必要な情報だけを持つものとする。設計判断の履歴、代替案、意思決定の経緯はADR・design documentの責務であり、コードコメントからそれらへのリンクは持たせない。理由は次の通り。

- コードは「何をしているか」をコード自身が表現する。コメントに残す価値があるのは「なぜ必要か」「コードだけでは分からない前提・制約・落とし穴」だけ
- ADR・design documentへのリンクは、ファイル移動・リネーム・ドキュメント再編で腐る
- コードを読むために外部ドキュメントへの遷移を要求したくない
- このSkillの責務はコメントのテキストだけであり、別ドキュメントを編集する判断はその責務の外にある

各コメントについて次を問う。

> このコメントが無いと、次にこのコードを読む人は間違えるか、遅くなるか、驚くか。それはコード自体を読めば分かることではないか。

「コードを読めば分かる」ならCUT。分かるに該当しないが冗長・説明過多ならREWRITE。既に簡潔で重要ならKEEP。

## 三つの判定

**CUT（削除）** — 次に該当するコメントは削除する。

- シグネチャや変数名をそのまま日本語訳しただけの説明（例: `userId: string` に対する `/** ユーザーID */`）
- コードの制御フローをそのままなぞる説明（例: `getUser()` の直前にある `// ユーザーを取得する`）
- 見出し・区切りバナー（`// ===== 初期化処理 =====`）
- 具体性のない先送り（`// TODO: あとで実装する` のように何を・いつやるか書いていないもの。ただしTODO自体の削除は「禁止事項」を参照）
- コメントアウトされたコード
- ファイル冒頭や別コメントで既に書かれている内容の繰り返し

**REWRITE（その場で短く書き直す）** — 残す価値のある情報を含むが、冗長・AI生成的・説明過多な場合、その場で短く書き直す。別ドキュメントへは移さない。残すのは次だけ。

- 「何をしているか」ではなく「なぜ必要か」
- 局所的な制約・非自明な前提
- workaroundの理由
- 一見すると誤りに見える実装の意図
- コードだけでは表現できない落とし穴

例:

```ts
/**
 * この処理ではユーザーの状態を確認し、
 * API側の仕様として404が返された場合については、
 * 未登録ユーザーとして扱うことで後続処理を継続できるようにしている。
 * 詳細は docs/adr/0012.md を参照。
 */
```

```ts
// API仕様上、404は未登録ユーザーとして扱う
```

程度までその場で縮める。ADR・design documentへのリンクは情報価値として数えない。既存コメントにそのようなリンクがある場合も、リンク先の内容を推測して書き戻さない。リンクを除去した結果、コードコメントとして有用な局所情報（なぜ必要か・制約・workaround理由・落とし穴）が本文に何も残らないならCUTする。リンク以外に上記の情報が本文にあるなら、それだけを残してREWRITEする。

**KEEP（保持）** — 既に簡潔で、コードだけでは分からない重要情報を持っているコメントはそのまま残す。

ファイル冒頭のdocblockは「このモジュールが何をするか」＋「非自明な点1つ」までは許容する。それを超える部分は他のコメントと同じ基準（CUT/REWRITE/KEEP）で判定する。

## comment consistencyとの責務境界

このSkillはコメントと実装の整合性を網羅的にレビューするSkillではない。`final-cleanup` ではこのSkillの前段で別途comment consistency checkを行う想定であり、このSkillの責務は「内容として正しいコメントについて、残す価値があるか・冗長ではないか・日本語としてAI生成的や不自然ではないか」の判断に限定する。

処理中にコメントとコードの明白な矛盾を偶然見つけた場合は、コードを変更せず、コメントも推測で修正せず、完了報告に記す。

## 日本語コメントに特有のslopパターン

英語コメントの一般的なslop（冗長な説明、自明な言い換え）に加えて、日本語コメントでは次のパターンが高頻度で出現する。

- **敬体・常体の混在**: 同一ファイル内で「〜です・ます」と「〜だ・である」が混ざっている。文体を統一する（周囲の既存コメントの文体に合わせる）
- **指示・提案口調**: 「〜してください」「〜しましょう」のような、コードに対する呼びかけ調のコメント。コメントは事実の記述であり、指示文ではない。事実の記述に書き換えるか、内容が自明なら削除する
- **和訳JSDoc**: 型で表現済みの情報を日本語文にしただけのJSDoc/TSDoc（例: `@param {string} name - 名前` のように型と重複するだけの説明）
- **二重言語コメント**: 同じ内容を英語と日本語で両方書いている。1つに統一する
- **装飾記号**: 絵文字や罫線での装飾（`// ✅ 完了`、`// ---処理ここまで---`）

## 別ファイルを編集しない

このSkillが変更してよいのは引き続きコメントのテキストと、それに付随する空白だけ。README、ADR、design document、その他のファイルへ情報を移動・追記・新規作成しない。

## 禁止事項

- **コードに触らない**。コメントが誤っている原因がコード側のバグにある場合、コードは直さずその旨を報告するだけにする
- **`TODO` / `FIXME` / `HACK` マーカーを削除しない**。内容が古くなっていても、削除ではなく報告にとどめる
- **ライセンスヘッダー、shebang、tooling向けpragmaを剥がさない**。`@ts-expect-error`、`biome-ignore`、`eslint-disable` などはコメントの見た目をしているが挙動を変える指示なので、削除対象ではなく上記KEEPの対象として扱う

## 完了条件

プロジェクトにtypecheckとformatterがあれば実行し、コメント以外の差分が出ていないことを確認する。無ければ `git diff` を読み返し、コメントと空白以外の変更が無いことを目視で確認する。

## 完了報告

変更内容が分かる程度の簡潔な報告にする。

```
Deslop comments 完了
CUT: <件数、または対象なし>
REWRITE: <件数、または対象なし>
KEEP: <判断に迷い残したものがあれば>
整合性の疑い: <あれば。なければ省略>
```