diff --git a/.claude/commands/auto-refactor.md b/.claude/commands/auto-refactor.md index 7555642..7cd24b0 100644 --- a/.claude/commands/auto-refactor.md +++ b/.claude/commands/auto-refactor.md @@ -9,10 +9,11 @@ ユーザーが席を外している無人時間に，空いた稼働枠を「コードの大規模リファクタリング」と「実装とドキュメントのズレ解消」に充てるために起動されました． GUIDE_02（ドキュメント作成），GUIDE_04（Git 運用），GUIDE_05（エージェント運用）を読み，書式・規約・パイプラインのルールを理解した上で，以下の不変条件を厳守してループを回してください． -このループが扱う作業は **2 種類**ある． +このループが扱う作業は **3 種類**ある． - **コードリファクタ系**：挙動を変えずにコード品質を改善する（安全網＝テスト）． - **ドキュメント同期系**：実装を真として `docs/` の記述を実態に近づける．ただし「ドキュメントに無い事項の追記」は自動で行い，「ドキュメントと実装の矛盾」は自動で書き換えず報告のみ（後述）． +- **ドキュメントリファクタ系**：ドキュメントの**意味を変えずに**読みやすさ・品質を上げる（冗長表現の簡潔化，表記統一，書式整形，リンク修正等）．コードリファクタにおけるテストに相当する「意味が保たれたかの自動検証手段が無い」ため，**情報を削るより残す側に倒す**のが原則（後述の不変条件 9）． ## このコマンドの位置づけ（重要） @@ -33,6 +34,7 @@ 6. **除外領域に触れない**：後述の「対象外の領域（除外リスト）」に該当する箇所はリファクタ対象に選ばない． 7. **疑わしきは停止**：判断に迷う・安全網が確認できない・テストコマンドが特定できない場合は，無理に進めず停止して状況を報告する． 8. **ドキュメントは「追記は自動・矛盾は報告のみ」**：実装を真としてよいのは**ドキュメントに記載が無い事項の追記**だけ．ドキュメントと実装が**食い違う**箇所は**自動で書き換えず**，要確認リストに記録して報告する（矛盾は実装バグの兆候かもしれず，無人で塗り潰すと検出機会を失うため）．`docs/01_GUIDE/`（規約），`CLAUDE.md`，`docs/03_PLAN/`・`docs/PROGRESS.md`（計画・進捗）は実装を真とする対象に**含めない**． +9. **ドキュメントリファクタは「意味保存」が絶対条件**：自動で行ってよいのは**意味・情報を保ったままの品質改善**だけ．具体的には ①無損失整形（表記揺れの統一・書式/見出し/表の整形・リンクや参照の修正・明らかなタイポ）と，②**意味を保った簡潔化・重複の集約**（冗長な言い回しを短くする，同一内容の重複を1か所に集約して他はリンクする）．**消してはいけないもの**＝事実・決定事項・設計判断（なぜその案にしたか）・失敗パターン・具体的な制約や閾値．これらが落ちる「陳腐化記述の削除」や「大規模な再編」は自動で行わず，要確認リストに**提案として記録**する．意味保存を自動検証する手段は無いため，迷ったら削らない（残す側に倒す）． ## 対象外の領域（除外リスト） — コードリファクタの対象に選ばない @@ -46,7 +48,7 @@ - ビルド成果物・キャッシュ（`dist/`，`build/`，`.next/`，`coverage/` 等） - ドキュメント全般（`docs/`，`CLAUDE.md`，`.claude/` 配下） -※ ドキュメントはコードリファクタの対象にはしないが，**ドキュメント同期系の処理（D）**では `docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` を更新対象とする（不変条件 8 の範囲で）．`docs/01_GUIDE/`・`CLAUDE.md`・`.claude/`・進捗系は同期処理でも自動編集しない． +※ ドキュメントはコードリファクタの対象にはしないが，**ドキュメント同期系の処理（D）／ドキュメントリファクタ系の処理（DR）**では `docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` を更新対象とする（不変条件 8・9 の範囲で）．`docs/01_GUIDE/`・`CLAUDE.md`・`.claude/`・進捗系（`docs/03_PLAN/`・`docs/PROGRESS.md`）は自動編集の対象に**含めない**． 判断に迷うファイルは「触らない」側に倒す（不変条件 7）． @@ -66,7 +68,9 @@ 4. **ベースラインの確認**：既存テストがある場合は検証スイートを実行し，**開始時点で全て緑**であることを確認する．赤がある場合は，リファクタの前提（緑からの出発）が崩れているため**停止して報告**する．既存テストが0件の場合はテスト実行を省略してよいが，ビルド/型チェックがあれば実行して緑を確認する． 5. **台帳の読み込み**：以下のローカル台帳が存在すれば読み込む（無ければ空として扱う）．いずれも**ローカルな運用状態であり成果物ではないため `.gitignore` 対象**とする（追跡されていなければ `.gitignore` に追記する）． - `.claude/auto-refactor-skip.md`（スキップ台帳）：過去に安全に扱えなかったリファクタ対象．今回も**再挑戦せず除外**する．形式は1行1エントリ `- <対象> | <理由> | <日付>`． - - `.claude/auto-refactor-doc-review.md`（ドキュメント要確認リスト）：過去に検出した「ドキュメントと実装の矛盾」．**既出の矛盾は再記録しない**（重複・トークン浪費防止）．形式は1行1エントリ `- <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因> | <日付>`． + - `.claude/auto-refactor-doc-review.md`（ドキュメント要確認リスト）：過去に検出した「ドキュメントと実装の矛盾」および「自動では行わない簡潔化・再編の提案」．**既出の項目は再記録しない**（重複・トークン浪費防止）．形式は1行1エントリ，先頭にカテゴリを付ける: + - 矛盾: `- [矛盾] <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因> | <日付>` + - 提案: `- [提案] <箇所> | <提案内容（どう簡潔化/再編したいか）> | <自動で行わない理由> | <日付>` ## ループ本体 (Loop Body) — 安全な作業が尽きるまで繰り返す @@ -78,8 +82,9 @@ - **リファクタ対象（コード）**：除外リスト・スキップ台帳に該当しないもの．優先度の目安（高い順）：重複コードの集約 → 過度に長い関数の分割 → 命名の改善 → デッドコード除去 → 構造の単純化． → 選んだら「リファクタ処理 (R)」へ． - **ドキュメント・ドリフト項目**：`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` と実装を突き合わせ，**記載漏れ**または**矛盾**がある箇所．要確認リストに既出の矛盾は除外する． → 選んだら「ドキュメント同期処理 (D)」へ． +- **ドキュメントリファクタ項目**：`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` の中で，**意味を変えずに**改善できる箇所（冗長な言い回し，表記揺れ，書式の乱れ，重複，リンク切れ等）． → 選んだら「ドキュメントリファクタ処理 (DR)」へ． -両種別とも作業項目が無くなったら**ループを終了**し，完了報告へ進む． +いずれの種別も作業項目が無くなったら**ループを終了**し，完了報告へ進む． --- @@ -152,16 +157,39 @@ #### ステップ D3: 矛盾は報告のみ（自動で書き換えない） - **ドキュメントは書き換えない**（不変条件 8）．矛盾は実装バグの兆候かもしれず，無人で「実装に合わせて」塗り潰すと検出機会を失う． -- `.claude/auto-refactor-doc-review.md`（要確認リスト）に**1行追記**する: `- <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因（仕様が古い/実装バグの疑い 等）> | <日付>`． +- `.claude/auto-refactor-doc-review.md`（要確認リスト）に**1行追記**する: `- [矛盾] <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因（仕様が古い/実装バグの疑い 等）> | <日付>`． - **既に記録済みの矛盾は再記録しない**．記録（または既出確認）したらステップ 0 へ戻る． --- +### ドキュメントリファクタ処理 (DR) + +#### ステップ DR1: 改善方針の判定（意味保存が絶対条件） + +選んだ箇所について，意味・情報を保ったまま改善できるかを判定する（不変条件 9）． + +- **無損失整形 or 意味を保った簡潔化/集約** → ステップ DR2 へ（自動で実施）． + - 例：冗長な言い回しを短くする，表記揺れ・カタカナ/英字のゆれを統一，見出しレベル・表・コードフェンス・箇条書きの整形，重複説明を1か所に集約して他はリンク，切れたリンクや古い参照（GUIDE_03 命名）を実在パスに修正，明らかなタイポ修正． +- **情報が落ちる削除・大規模再編**（陳腐化記述の削除，ファイル分割/統合，節の大幅な並べ替え等） → ステップ DR3 へ（自動では行わず提案のみ）． + +#### ステップ DR2: ドキュメントリファクタ実施（自動） + +- 該当ドキュメントを，**意味・決定事項・設計判断・失敗パターン・具体的制約を一切落とさずに**整形・簡潔化する．GUIDE_02（ドキュメント作成）・GUIDE_03（命名）に従う． +- 迷ったら削らない（残す側に倒す）．少しでも情報が落ちる懸念があれば DR3 に回す． +- GUIDE_04 のコミット書式に従い，タグ **`[clean]`** でコミットする（例: `[clean] 04_SPEC の冗長な説明を簡潔化`）．コミット後，ステップ 0 へ戻る． + +#### ステップ DR3: 削除・大規模再編は提案のみ（自動で行わない） + +- 本文は書き換えない．`.claude/auto-refactor-doc-review.md` に**1行追記**する: `- [提案] <箇所> | <提案内容（どう簡潔化/再編したいか）> | <自動で行わない理由（情報が落ちうる 等）> | <日付>`． +- **既出の提案は再記録しない**．記録（または既出確認）したらステップ 0 へ戻る． + +--- + ## 停止条件 (Stop Conditions) 以下のいずれかでループを止める． -- **リファクタ対象（テスト生成で保護下にできるものを含む）とドキュメント・ドリフト項目が，両方とも尽きた** → **正常終了**． +- **リファクタ対象（テスト生成で保護下にできるものを含む）・ドキュメント・ドリフト項目・ドキュメントリファクタ項目が，すべて尽きた** → **正常終了**． - 同じ箇所で繰り返しテストが赤になる／テストコマンドが途中で失敗するようになった → **異常として停止し報告**． - 不変条件を満たせない状況になった → **停止して報告**． - ユーザーが割り込んで中断した → その時点までの成果（コミット済み）は `refactor/` ブランチに残る． @@ -175,7 +203,7 @@ `/loop` で回すと，作業が尽きた後もウェイクのたびに「対象なし → 即終了」を繰り返し，**無駄にトークンを消費**しうる．これを防ぐため，以下の収束ルールを守る． -- 各イテレーションの開始時に全範囲を再スキャンし，**この回で実施した作業の件数**を数える（リファクタ＋特性化テスト生成＋ドキュメント追記＋**新規に記録した**矛盾．既出の矛盾の再確認は作業に数えない）． +- 各イテレーションの開始時に全範囲を再スキャンし，**この回で実施した作業の件数**を数える（リファクタ＋特性化テスト生成＋ドキュメント追記＋ドキュメントリファクタ＋**新規に記録した**矛盾・提案．既出項目の再確認は作業に数えない）． - **作業件数が 0 だった回**を「空振り」とカウントする． - **空振りが 2 回連続**したら，もう安全に拾える作業は出尽くしたとみなし，**`/loop` 自体を終了する**（次のウェイクをスケジュールしない）． - 1 回の空振りで即終了しないのは，「順序やコミットの巡り合わせで一時的に拾えなかっただけ」のケースを 1 回分許容するため． @@ -189,8 +217,9 @@ - 作業ブランチ名 - 追加した特性化テストの件数（= `[add]` のテストコミット数）と対象モジュールの一覧 - 実施したリファクタリングの件数（= `[clean]` コミット数）と概要の一覧 -- 更新したドキュメントの件数と内容（追記した `02_ENV`／`04_SPEC`／`05_TECH` の箇所一覧） -- **⚠ ドキュメントと実装の矛盾**：要確認リスト `.claude/auto-refactor-doc-review.md` に記録した件数と概要．**実装バグの可能性があるため自動では直していない**ので，1件ずつ「仕様を直す／実装を直す」を人間が判断してほしい旨を明記する +- 更新したドキュメントの件数と内容（`02_ENV`／`04_SPEC`／`05_TECH` への**追記**と，意味を保った**簡潔化・整形**（`[clean]`）の箇所一覧） +- **⚠ ドキュメントと実装の矛盾**：要確認リスト `.claude/auto-refactor-doc-review.md` の `[矛盾]` の件数と概要．**実装バグの可能性があるため自動では直していない**ので，1件ずつ「仕様を直す／実装を直す」を人間が判断してほしい旨を明記する +- **簡潔化・再編の提案**：同リストの `[提案]` の件数と概要（情報が落ちうるため自動では行わなかったもの．採否は人間が判断） - スキップした対象とその理由（挙動が固定できずテスト生成に失敗／検証スイートが緑にできなかった 等）．詳細はスキップ台帳 `.claude/auto-refactor-skip.md` に追記済み - ⚠ 自動生成した特性化テストは**現状の挙動（バグを含む）を固定**したもの．後で内容を一度目視確認することを推奨する旨を添える - 次のアクションの案内：「内容を確認の上，問題なければ `/commit push`（または `merge`）で `main` に取り込めます」