fix-prose

Files (3)

• SKILL.md
• rules.toml
• scan.py

SKILL.md (first lines)

# 語彙・言い回しの自動修正

コードコメントやドキュメントの自然言語を走査し、`rules.toml` で宣言した「直したい語彙・言い回し」を検出して**その場で書き換える**。
AI らしい定型語、過剰敬語、冗長表現、ヘッジなど、自分の好みに合わせた語彙ルールを辞書で管理する。

検出は `scan.py`（ルール辞書を読んで該当箇所を JSON で返す）が担い、書き換えは本手順に従って Claude が行う。
コード識別子やコードフェンス内はスクリプト側で対象外にしているため、コメント・散文だけが対象になる。

## 入力

`$ARGUMENTS` に走査対象のパスとオプションが渡される。

- パスはファイル / ディレクトリを複数指定可（ディレクトリは再帰）
- パス省略時は main から分岐した後の変更ファイルと未追跡ファイルが対象
  - 分岐点は `main` と `origin/main` のうち存在するものと HEAD の merge-base。どちらもなければエラー終了
  - 分岐点からの差分は未コミットの変更を含み、削除済みを除く
  - サブモジュール・入れ子のリポジトリ・シンボリックリンク・`node_modules` 等の除外ディレクトリ配下は走査せず、`files_skipped` に理由付きで載る
- `--profile <name>` で contextual 語の許容範囲を切り替え（省略時は `rules.toml` の `default_profile`）
  - `technical` … コード / 技術文書向け。技術的に正当な語（robust 等）は許容
  - `docs` … 一般ドキュメント向け
  - `strict` … contextual もすべて指摘

例

- `/fix-prose` → main との差分ファイルを technical で走査・修正
- `/fix-prose --profile docs` → main との差分ファイルを docs で走査・修正
- `/fix-prose src/` → src 配下を technical で走査・修正
- `/fix-prose README.md docs/ --profile docs`
- `/fix-prose .` → カレント以下すべて

## 手順

### 1. スキャンの実行

`uv run ${CLAUDE_SKILL_DIR}/scan.py $ARGUMENTS` を実行する。

- `$ARGUMENTS` にパスがない場合は、スクリプトが main との差分ファイルを対象にする
  - `main` / `origin/main` がない、共通祖先がないなどの理由で `failed to list files changed vs main` で終了した場合は、ユーザーにパスを尋ねて再実行する
  - 差分がない、または全件が除外されたために `no scannable files changed vs main` で終了した場合は、JSON は出ないため、stderr に列挙された除外パスとともに報告して終了する
- パスにスペースや glob 文字（`*` `?` 等）を含む場合は、Bash コマンド構築時に各パスを個別にダブルクォートで囲む（`$ARGUMENTS` 全体を一括クォートするとフラグや複数パスの分割が壊れる）
- 依存（pygments, typer）は PEP 723 により `uv run` が自動解決する
- 上記以外で非ゼロ終了した場合は stderr のエラーをユーザーに報告して終了

### 2. 出力（JSON）の解析

stdout は JSON で、以下のフィールドを含む。

- `profile` - 適用プロファイル
- `files_scanned` - 走査したファイル数
- `files_skipped` - スキップしたファイル（理由付き）
- `summary` - 件数集計（`total`, `always`, `pattern`, `contextual_flagged`, `contextual_allowed`, `density_reports`）
- `findings` - 検出配列
  - `path`, `line` - 該当箇所
  - `lang` - `en` / `ja`
  - `tier` - `always` / `contextual` / `pattern`（`density` は findings ではなく後述の `density` 配列に出る）
  - `matched` - 実際にマッチした表層文字列
  - `base` - ヒットした辞書キー
  - `suggest` - 置換候補の配列
  - `snippet` - 該当行のテキスト
  - `note` - 補足（contextual に多い）
  - `allowed_by_profile` - contextual のみ。`true` なら現プロファイルで許容
- `density` - 密度レポート（多用 / 共起）
  - 比率版: `ratio`, `threshold`, `words`（語ごとの出現数）
  - 共起版: `cooccurrence`（同居した語）, `snippet`

### 3. 書き換えの適用

ティアごとに方針を変えて、**該当ファイルを Edit ツールで直接書き換える**。

#### always（文脈不問）

確認なしで置換する。`suggest` の中から文脈に最も自然なものを選ぶ。
適切な候補がなければ、語の意図を保ったまま平易な表現に言い換える。

#### contextual（文脈依存）

- `allowed_by_profile == true` → 原則そのまま（技術的に正当な用法）。
  ただし明らかに空虚な賛辞・誇張（例: "seamless experience" のような中身のない強調）であれば置換する。
- `allowed_by_profile == false` → `note` を踏まえて置換する。ヘッジ（「〜と思われます」等）は、根拠があるなら言い切りに直す。

#### density（多用 / 共起）

同じ語の多用や、複数の冗長語の共起を解消する。語を削る・言い換える・文を再構成するなど、密度を下げる方向で最小限に直す。
ただし `ratio` が高くても `words` の合計出現が少ない（散文が短く分母が小さい）場合や、該当語が contextual で許容（`allowed_by_profile == true`）の単発語だけの場合は「多用」ではないため書き換えず、報告に留める。

#### pattern（構造パターン）

特定の語ではなく「形」を捉えた検出（全角括弧の補足など）。`matched` は正規表現に一致した範囲、`note` に再構成の指針がある。
note に従って文を組み替える。例えば後付けの理由・限定を表す全角括弧は本文へ展開し、用語の初出注記やスコープ表記のような短く独立した注は残す。機械置換ではないため、文意とニュアンスを保つことを最優先する。

#### 共通ルール

- **コードの意味を変えない**。識別子・API 名・設定キー・コマンド・固有名詞には触れない（スクリプトが除外済みだが、念のため確認する）。
- `suggest` は意味の参考であって字面どおり挿入するものではない。書き換えは対象テキストの言語（`lang`）に合わせる。`lang` と `suggest` の言語が食い違う場合（例: 英語コメントに日本語 suggest が付く pattern ヒット）は、suggest の意味を汲んで周辺と同じ言語で平易に言い換える。
- 1 ファイルずつ、**最小限の差分**で適用する。周辺の文体は保つ。
- 置換して文意が通らない / ニュアンスが変わる場合は適用せず、判断保留として報告する。
- 同一行に複数ヒットがある場合はまとめて直す。語尾の冗長表現（「〜できる形になります」等）は無理に元の構文を残さず、一文に統合して平易化してよい（体言止めの解消を含む）。

### 4. 結果の報告

以下を簡潔に報告する。

- 修正件数（ティア別）
- ファイルごとの主な変更（before → after を数件）
- 適用を見送った項目とその理由（contextual 許容、文意不通など）
- 密度レポートで対応した箇所

### 5. 辞書へのワード追加

ユーザーが「今後 X を Y に直して」「この語も対象にして」と指示した場合、`${CLAUDE_SKILL_DIR}/rules.toml` の該当セクションに 1 行追記する。

- 常に直す語 → `[en.always]` / `[ja.always]` に `"語" = ["置換候補", ...]`
- 技術文脈だけ許す語 → `[en.contextual]` / `[ja.contextual]` に
  `"語" = { suggest = ["置換候補"], allow_in = ["technical"], note = "" }`（キーは必ずダブルクォートで囲む。`〜`・空白入りキーが無引用だと TOML が壊れる）
- 多用だけ抑える語 → `[en.density]` / `[ja.density]` の `words` に追記

追記後、必要なら同じ対象に対して再スキャンを実行する。日本語の語頭ワイルドカードは `〜`（例: `"〜と思われます"`）で表す。

## 禁止事項

From rysk-tanaka/skills, MIT.

More from rysk-tanaka/skills