hirokimry/comments-rewrite-all

💬 comments-rewrite-all: コード内コメント全書き直しスキル

[!IMPORTANT] このスキルは diff 提案 → CEO 承認 → 書換の 2 段階を必須化 する。 自動マージは禁止する。 コード本体の挙動は変えず、コメントのみを .claude/rules/code-comments.md 基準で書き直す。

リポジトリ内のコード内コメントを コード内コメント作成基準 に沿って一括で書き直し提案する。 承認前は書き換えを行わず、CEO 承認後にのみ反映する。

🎯 対象範囲

| 観点 | 内容 | |------|------| | 📂 対象パス | **/*.sh / **/*.bash / **/*.js / **/*.mjs / **/*.cjs / **/*.ts / **/*.tsx / **/*.jsx / **/*.py / **/*.rb / **/*.go / **/*.rs / **/*.java / **/*.kt / **/*.swift / **/*.json / **/*.yml / **/*.yaml / **/*.toml | | 🚫 除外パス | node_modules/** / vendor/** / .git/** / dist/** / build/** / 自動生成コード（ファイル先頭に Generated by / DO NOT EDIT 等が含まれるもの）/ テストデータ | | 📐 適用基準 | .claude/rules/code-comments.md（コード内コメントの書き方基準） | | 🤝 委譲先 | 対象言語の主担当が明確な場合は領域別 C*O Agent、明確でない場合は CTO | | 🔐 承認 | CEO 承認なしに書き換えない（2 段階必須） | | 🪜 プリセット | full プリセット専用（autonomous-restrictions §4 ガードレール領域準拠） |

対象外（本スキルは扱わない）

• .md 全般（ドキュメント本体）→ /vibecorp:docs-rewrite-all
• LLM 向けプロンプト .md（skills/**/SKILL.md / .claude/agents/*.md / .claude/rules/*.md）→ /vibecorp:prompts-rewrite-all
• GitHub コメント（Issue / PR / レビュー本文 / Bot 通知）→ comment-writing.md 直接適用
• コミットメッセージ本文 → communication.md 直接適用

📝 使用方法

/vibecorp:comments-rewrite-all
/vibecorp:comments-rewrite-all --target shell
/vibecorp:comments-rewrite-all --target typescript
/vibecorp:comments-rewrite-all --target python
/vibecorp:comments-rewrite-all --target config

• --target 未指定なら対象拡張子を全件処理する
• 1 ファイル単位で diff 提案 → CEO 承認 → 書き換えを繰り返す
• 言語別の節（code-comments.md の各言語サブセクション）に従って書き換える

🧭 7 段階動線

このスキルは以下 7 段階を順に進める。

| ステップ | 名称 | 役割 | |---------|------|------| | 1️⃣ | 列挙 | 対象拡張子のファイルを収集する | | 2️⃣ | 抽出 | 各ファイルからコメント行を抽出する | | 3️⃣ | 照合 | code-comments.md の指針 MUST / 禁止パターンと突き合わせる | | 4️⃣ | 提案 | 書き直し案を diff として CEO に提示する | | 5️⃣ | 承認 | CEO の判断を待つ | | 6️⃣ | 書換 | 承認分のみファイルに反映する | | 7️⃣ | レポート | 結果を CEO 向けに整形する |

各ステップは前段の出力を受け取り次段へ渡す。

ステップ 5（承認）でスキップが指示された項目は、ステップ 6 で書き換えない。

1️⃣ 列挙: 対象ファイル収集

対象ファイルを以下の手順で収集する。

git ls-files \
  '*.sh' '*.bash' '*.js' '*.mjs' '*.cjs' '*.ts' '*.tsx' '*.jsx' \
  '*.py' '*.rb' '*.go' '*.rs' '*.java' '*.kt' '*.swift' \
  '*.json' '*.yml' '*.yaml' '*.toml'

• git ls-files を使うことで .gitignore 配下の生成物 / node_modules/ 等を自動的に除外する。
• それでも対象に紛れる生成コードはステップ 2 のファイル先頭スキャンで除外する。
• ファイル一覧を変数に保持し、ステップ 2 へ渡す。

除外条件

| 観点 | 条件 | |------|------| | 📦 サードパーティ依存 | node_modules/ / vendor/ / Pods/ / .bundle/ 配下 | | 🛠️ ビルド成果物 | dist/ / build/ / out/ / target/ 配下 | | 🤖 自動生成 | ファイル先頭 50 行内に Generated by / DO NOT EDIT / Code generated 等を含む | | 🧪 テストデータ | tests/fixtures/ / __fixtures__/ / testdata/ 配下 |

--target <language> 指定時は該当拡張子のみに絞る。

2️⃣ 抽出: コメント抽出

各ファイルから言語に応じたコメント行を抽出する。

| 言語 | コメント形式 | |------|------------| | 🐚 shell / Ruby / Python | # で始まる行（行頭 + インライン）| | 📜 TypeScript / JavaScript / Rust / Go / Java / Kotlin / Swift | // 行コメント + /* ... */ ブロックコメント | | 🐍 Python | # 行コメント + """...""" docstring | | ⚙️ YAML / TOML | # 行コメント | | ⚙️ JSON | // 行コメント（JSON5 / JSONC 拡張のみ）|

抽出時は以下を保持する。

• ファイルパス
• 行番号（開始 / 終了）
• コメント本文
• 直後の対象コード断片（WHY と WHAT の照合に使う）

抽出結果が空のファイルはステップ 3 以降の対象から外す。

3️⃣ 照合: code-comments.md との機械的突き合わせ

ステップ 2 で抽出した各コメントを、code-comments.md の 指針 MUST 全項目 と 禁止パターン全項目 に対して 1 件ずつ突き合わせる。

照合対象の項目本体は .claude/rules/code-comments.md が Single Source of Truth。

• 指針 / 禁止の項目本体は基準ルールに閉じる（スキル側で項目を重複列挙しない）。
• 各コメントに対し「該当する基準項目（指針 N / 禁止 N）」と「該当行番号」を表で記録する。
• 言語別の節（bash / TS / Python / Ruby / Rust / Go / 設定）は対象拡張子に応じて適用する。
• 検出結果が空のファイルはステップ 4 以降の対象から外す。

重点チェック観点

code-comments.md の指針 MUST に対応する以下を機械的に検出する。

| 観点 | 検出シグナル | |------|------------| | ✋ default to no comments | コメントなしで意図が明確になる箇所のコメント残存 | | 🧭 WHY を書く | 「〜を取得する」「〜を加算する」等の WHAT 反復 | | 📍 出所をリンクする | TODO / FIXME で Issue 番号無し（#123 形式の欠落）| | 🔁 コードと一致 | コメントとコード本体の意味乖離（設定キー名と説明の食い違い等）| | 🗣️ 日本語で書く | 英語コメントの残存（標準ライブラリ引用部を除く）| | 🚫 コメントアウトされたコード残存 | # old_func() / // const x = ... 等の死コード残存 |

4️⃣ 提案: diff を CEO に提示

ステップ 3 で集めた書き換え案を、ファイル単位の diff として整形する。

提示時は以下を明示する。

• ✅ 適用候補: 基準逸脱を解消する書き換え。
• ⚠️ 要判断: 意味解釈の余地がある書き換え（コード挙動を変える疑いがあるもの含む）。
• 📍 根拠: 該当する指針 / 禁止項目の番号 + 該当行番号。

提示は ファイル単位 にまとめる。

• 全ファイルを一括提示すると CEO のレビュー負荷が高くなる。
• 1 ファイルずつ承認を取る運用を基本とする。
• CEO の指示で「まとめて見る」と言われた場合のみ複数ファイル同時提示に切り替える。

委譲（オプション）

ファイル所有領域が明確な場合は領域別 C*O に委譲する。判断に迷う場合は CTO に委譲する。

| 領域 | 対象例 | 委譲先 | |------|------|--------| | 🔒 セキュリティ | templates/claude/hooks/protect-*.sh | CISO | | 💰 コスト | templates/claude/hooks/cost-*.sh / 課金関連 | CFO | | 🛠️ 技術 | 一般 shell / TS / Python | CTO | | ⚖️ 法務 | LICENSE 周辺スクリプト | CLO | | 📦 プロダクト | install.sh / ユーザー向け CLI | CPO |

CO は複数並列で起動してよい（各 CO は別ファイルを扱うため競合しない）。

5️⃣ 承認: CEO 判断を待つ

CEO に以下の選択肢を提示する。

| 選択肢 | 効果 | |--------|------| | ✅ 全採用 | 提示した diff を全て書き換え対象に取る | | 🔢 項目選択 | 採用したい項目の番号を指定する | | ⏭️ スキップ | このファイルの書き換えを保留する | | ✋ 中止 | スキル全体を中止する |

承認なしに書き換えは行わない。

AskUserQuestion ツールで選択肢を明示提示してもよい（CEO の判断負荷を下げるため）。

6️⃣ 書換: 承認分のみファイル反映

ステップ 5 で承認された項目のみを Edit ツールで反映する。

書き換え後は以下を必ず実行する。

• 既存テスト一式を走らせる（コメント変更でテストが壊れないことを確認）。
• 該当する言語別の lint / format（shellcheck / tsc / ruff 等）が CI に組み込まれていれば走らせる。
• 破壊が出た場合はその場で書き換えをロールバックし、CEO に報告する。

書き換えは ファイル単位の commit で行う（後追いで diff を追跡できるように）。

コード本体への影響禁止

本スキルは コメントのみを対象とする。

• ❌ コードトークンの追加・削除・並べ替えを行わない。
• ❌ 変数名・関数名のリネームを行わない（命名整理は別 Issue で扱う）。
• ✅ 行頭インデント・空白の調整はコメント行に限り許容する。

7️⃣ レポート: CEO 向け結果整形

以下のフォーマットで結果を CEO に返す。

## 💬 comments-rewrite-all 完了レポート

### 📊 集計
- 対象ファイル数: N 件
- 抽出コメント: C 件
- 書き換え採用: M 件
- スキップ: S 件
- 中止: 0 / 1

### ✅ 採用された書き換え
- {ファイル名}:{行番号}: {変更の動作主語要約}（採用 K 件）

### ⏭️ スキップされた項目
- {ファイル名}:{行番号}: {スキップ理由}

### ⚠️ CEO 判断保留
- {ファイル名}:{行番号}: {判断保留の論点}

### 📍 次のアクション
- 必要に応じて `/commit` で書き換えをコミット
- 残課題は別 Issue で起票（`/issue`）

レポートは 動作主語（〜になった / 〜できるようになった）で書く（communication.md 規約）。

🤝 委譲先エージェント

このスキルは以下の C*O Agent を呼び出すことがある。

| エージェント | 主管轄 | |-------------|--------| | cto | 一般コードコメント・アーキテクチャ周辺 | | cpo | プロダクト方針・install.sh・ユーザー向け CLI | | cfo | コスト・課金関連スクリプト | | ciso | セキュリティフック・認証関連 | | clo | 法務・ライセンス周辺 |

各 C*O は 管轄ファイルのみ 書き換え提案する。判断に迷う場合は CTO がデフォルト窓口となる。

✅ 指針（MUST）

本スキル固有の指針のみを定義する。コード内コメント本体の指針は基準ルールを参照する。

• コード内コメントそのものの指針: .claude/rules/code-comments.md
• ドキュメント書き方の基底指針: .claude/rules/document-writing.md

スキル固有の指針

1. 🛑 diff 提案 → CEO 承認 → 書き換えの 2 段階を守る

   • CEO 承認なしに本体ファイルを書き換えない
   • 自動マージは禁止する

2. 🧹 コメントのみを書き換える

   • コード本体（変数名・関数名・処理順序）は変更対象外
   • 命名整理・ロジック改善は別 Issue で扱う

3. 🗂️ 言語別の節に従う

   • code-comments.md の言語別サブセクション（bash / TS / Python / Ruby / Rust / Go / 設定）に従い、各言語の文化・慣習を尊重する

❌ 禁止パターン

本スキル固有の禁止のみを定義する。コード内コメント本体の禁止パターン （WHAT 繰り返し・誤解を招くコメント・Issue 番号無し TODO 等）は code-comments.md を参照する。

• ❌ CEO 承認なしにファイルを書き換える

  • 自動マージ禁止に違反する

• ❌ コードトークンの追加・削除・並べ替えを行う

  • 本スキルはコメントのみが対象。コード挙動を変える書き換えは禁止

• ❌ 生成コード / node_modules / vendor を書き換える

  • サードパーティ・自動生成物は本スキルの対象外

• ❌ 基準（code-comments.md）を経由せずに書き直し提案を生成する

  • 主観基準による書き換えはレビュー基準が揺らぐ

🛡️ 制約

• 自動マージ禁止: CEO 承認なしに書き換えない（2 段階必須）。
• コード挙動改変禁止: 本スキルはコメントのみを対象とする。
• 対象外パス遵守: node_modules/ / vendor/ / dist/ / build/ / 自動生成コードは触らない。
• 既存テスト破壊禁止: 書き換え後にテストを走らせ、破壊があればロールバック。
• shell 規約: スクリプト記述は .claude/rules/shell.md を遵守する。
• autonomous-restrictions 準拠: 本スキルは自律改善ループ（/vibecorp:diagnose → /vibecorp:autopilot → /vibecorp:ship-parallel）の自動実行対象外とし、人間（CEO）の明示承認を必須化する（.claude/rules/autonomous-restrictions.md）。

🔗 関連

• 適用基準: .claude/rules/code-comments.md
• ドキュメント基底基準: .claude/rules/document-writing.md
• 動作主語ルール: .claude/rules/communication.md
• マークダウン規約: .claude/rules/markdown.md
• shell 規約: .claude/rules/shell.md
• 自律実行不可領域（人間承認必須）: .claude/rules/autonomous-restrictions.md
• 兄弟スキル: /vibecorp:docs-rewrite-all（ドキュメント本文 + md 内コメント例を扱う）
• 兄弟スキル: /vibecorp:prompts-rewrite-all（プロンプト本文 + md 内コメント例を扱う）