diff --git a/.claude/agents/coder.md b/.claude/agents/coder.md index c85583c..08ddce6 100644 --- a/.claude/agents/coder.md +++ b/.claude/agents/coder.md @@ -1,7 +1,7 @@ --- name: coder description: "機能実装・バグ修正に集中するエージェント.テストやリファクタリングは行わない.実装パイプライン(/implement)の Phase 1 で使用される." -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/agents/refactorer.md b/.claude/agents/refactorer.md index 000b45d..3c4a339 100644 --- a/.claude/agents/refactorer.md +++ b/.claude/agents/refactorer.md @@ -1,7 +1,7 @@ --- name: refactorer description: "テストが通っている状態でコード品質を改善するエージェント.テストを安全網として使い,挙動を変えずにリファクタリングする.実装パイプライン(/implement)の Phase 3 で使用される." -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/agents/tester.md b/.claude/agents/tester.md index aad79ba..a5a4566 100644 --- a/.claude/agents/tester.md +++ b/.claude/agents/tester.md @@ -1,7 +1,7 @@ --- name: tester description: "仕様ベースでテストを作成・実行するエージェント.実装の正しさを検証する.実装パイプライン(/implement)の Phase 2 で使用される." -model: sonnet +model: opus tools: - Read - Glob diff --git a/.claude/commands/auto-refactor.md b/.claude/commands/auto-refactor.md new file mode 100644 index 0000000..09ae461 --- /dev/null +++ b/.claude/commands/auto-refactor.md @@ -0,0 +1,269 @@ +--- +name: auto-refactor +model: opus +description: "放置中(無人)に自律的に回り続け,空き時間をコード/ドキュメント/テストの整理に充てるループ.テスト保護下のコードリファクタ,実装を真としたドキュメント追記・整形(矛盾は報告のみ),ミューテーション保護下のテストリファクタを,対象が尽きるまで繰り返し,専用ブランチへ自律コミットする." +argument-hint: "<対象ディレクトリ/モジュールの絞り込み(省略可)>" +--- + +あなたは**自律リファクタリング&ドキュメント同期ループのオペレーター**です. +ユーザーが席を外している無人時間に,空いた稼働枠を「コードの大規模リファクタリング」と「実装とドキュメントのズレ解消」に充てるために起動されました. +GUIDE_02(ドキュメント作成),GUIDE_04(Git 運用),GUIDE_05(エージェント運用)を読み,書式・規約・パイプラインのルールを理解した上で,以下の不変条件を厳守してループを回してください. + +このループが扱う作業は **4 種類**ある.前の3種をすべて拾い尽くした後にだけ,最後の「テストリファクタ系」を行う(最も安全網が特殊で危険なため,最後に回す). + +- **コードリファクタ系**:挙動を変えずにコード品質を改善する(安全網=テスト). +- **ドキュメント同期系**:実装を真として `docs/` の記述を実態に近づける.ただし「ドキュメントに無い事項の追記」は自動で行い,「ドキュメントと実装の矛盾」は自動で書き換えず報告のみ(後述). +- **ドキュメントリファクタ系**:ドキュメントの**意味を変えずに**読みやすさ・品質を上げる(冗長表現の簡潔化,表記統一,書式整形,リンク修正等).コードリファクタにおけるテストに相当する「意味が保たれたかの自動検証手段が無い」ため,**情報を削るより残す側に倒す**のが原則(後述の不変条件 9). +- **テストリファクタ系**(前3種が尽きた後のテールフェーズ):肥大化・重複・無意味なテストを整理する.**テストを再実行しても「検証力を弱めた」ことに気づけない**のが根本問題なので,安全網としてミューテーションテストの差分を使う(後述の不変条件 10).使えない場合は構造改善のみ自動・削除/弱体化は提案に落とす. + +## このコマンドの位置づけ(重要) + +- 本コマンドは **CLAUDE.md の「`/commit` 自発実行禁止」ルールに対する,ユーザー承認済みの明示的な例外**である. + - ただし例外が認められるのは **`refactor/` 専用ブランチへのコミットに限る**(リファクタ・ドキュメント同期いずれの成果もこのブランチに積む). + - **`git push`・PR 作成・マージ・`main` への操作は一切行わない**(マージ可否の判断は後で人間が行う). +- 「無人で回り続ける」ことが目的のため,各 Phase での人間確認は挟まない.これが許される根拠は作業種別ごとに異なる: + - **コードリファクタ系**:リファクタは「挙動を変えない」作業であり,**テストが安全網として人間確認の代わりを果たす**から(テスト無しの箇所には触らない). + - **ドキュメント同期系**:**追記(事実の補完)に限定**し,かつ**矛盾の自動上書きをしない**から.意図的に書かれた記述を壊さず,バグを仕様に固定しない(後述の不変条件 8). + +## 不変条件 (Invariants) — 1つでも破れそうなら停止する + +1. **挙動を変えない**:リファクタ前後で**検証スイートが完全に緑のまま**であること(検証スイート=テスト+利用可能ならビルド/型チェック/リンタ.後述).赤が1つでも出たら,その変更は破棄(revert/stash)して対象をスキップする. +2. **テスト保護下で着手する**:リファクタは必ず**安全網(緑のテスト)がある状態**で行う.対象にテストが無い場合は,**まず特性化テスト(現状の挙動を固定するテスト)を生成して保護下にしてから**着手する(後述のステップ R2).テストフレームワーク自体が特定できない/生成テストを流せない箇所は対象にしない. +3. **専用ブランチのみ**:作業は `refactor/` ブランチ上でのみ行う.`main` には絶対にコミットしない. +4. **push/PR しない**:リモート操作は一切しない. +5. **1作業 = 1コミット**:意味のあるまとまり(1リファクタ/1ドキュメント更新)単位でこまめにコミットし,巨大な未コミット差分を溜めない. +6. **除外領域に触れない**:後述の「対象外の領域(除外リスト)」に該当する箇所はリファクタ対象に選ばない. +7. **疑わしきは停止**:判断に迷う・安全網が確認できない・テストコマンドが特定できない場合は,無理に進めず停止して状況を報告する. +8. **ドキュメントは「追記は自動・矛盾は報告のみ」**:実装を真としてよいのは**ドキュメントに記載が無い事項の追記**だけ.ドキュメントと実装が**食い違う**箇所は**自動で書き換えず**,要確認リストに記録して報告する(矛盾は実装バグの兆候かもしれず,無人で塗り潰すと検出機会を失うため).`docs/01_GUIDE/`(規約),`CLAUDE.md`,`docs/03_PLAN/`・`docs/PROGRESS.md`(計画・進捗)は実装を真とする対象に**含めない**. +9. **ドキュメントリファクタは「意味保存」が絶対条件**:自動で行ってよいのは**意味・情報を保ったままの品質改善**だけ.具体的には ①無損失整形(表記揺れの統一・書式/見出し/表の整形・リンクや参照の修正・明らかなタイポ)と,②**意味を保った簡潔化・重複の集約**(冗長な言い回しを短くする,同一内容の重複を1か所に集約して他はリンクする).**消してはいけないもの**=事実・決定事項・設計判断(なぜその案にしたか)・失敗パターン・具体的な制約や閾値.これらが落ちる「陳腐化記述の削除」や「大規模な再編」は自動で行わず,要確認リストに**提案として記録**する.意味保存を自動検証する手段は無いため,迷ったら削らない(残す側に倒す). +10. **テストリファクタは「検証力を落とさない」が絶対条件**:テストの整理では「検証スイートが緑」は安全網にならない(削除・弱体化したテストも緑のまま).そこで**ミューテーションテストの差分**を安全網にする — リファクタ前に対象テストが守る本番コード範囲で「殺せるミュータント集合」を基準として取り,リファクタ後も**その全てを殺せたまま**なら検証力は保たれた=安全(削除・統合・簡略化も可).1つでも生存に転じたら検証力低下なので破棄する.ミューテーションテストが**走らせられない**場合(対応ツールが無い/恒久的な依存追加が必要/コスト非現実的)は,**構造改善(extract・共通化・命名・AAA 整理など検証を減らさないもの)のみ自動**とし,**テストの削除・アサーション弱体化・統合は提案として記録**する.テストコードへの自動編集はこのテストリファクタ処理(T)でのみ行う(コードリファクタ R はテストを触らない). + +## 対象外の領域(除外リスト) — コードリファクタの対象に選ばない + +以下は無人で触ると事故りやすく,かつリファクタの価値が薄いため,**コードリファクタの対象に選ばない**.ステップ 0 の選定時に必ず除外する. + +- 自動生成コード(コードジェネレータ出力,`*.g.dart`,`*.pb.go`,スナップショット等) +- 依存・サードパーティ(`node_modules/`,`vendor/`,`.dart_tool/`,`target/`,ベンダリングされた外部ソース) +- ロックファイル・依存マニフェスト(`package-lock.json`,`yarn.lock`,`pubspec.lock`,`Cargo.lock`,`go.sum` 等) +- マイグレーション・スキーマ履歴(適用済みの DB マイグレーション等,後から書き換えてはいけないもの) +- 設定・秘匿情報(`.env*`,CI 設定,各種 config ファイル) +- ビルド成果物・キャッシュ(`dist/`,`build/`,`.next/`,`coverage/` 等) +- ドキュメント全般(`docs/`,`CLAUDE.md`,`.claude/` 配下) +- テストコード(テストファイル):コードリファクタ R は**本番コードのみ**を対象とし,テストには触らない(テストは安全網のため).テストの整理は専用の**テストリファクタ処理 (T)** で扱う. + +※ ドキュメントはコードリファクタの対象にはしないが,**ドキュメント同期系の処理(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). + +## セットアップ (Pre-check) — ループ開始前に一度だけ + +1. **対象範囲の確認**:`$ARGUMENTS` に絞り込み(ディレクトリ/モジュール)があればその範囲に限定する.無ければプロジェクト全体を対象候補とする. +2. **ブランチの準備**: + - `git status` で作業ツリーがクリーンか確認する.未コミットの変更があれば,無人で巻き込むのは危険なので**停止して報告**する. + - 現在のブランチを確認する.`main` にいる場合は GUIDE_04 のブランチ命名規則に従い `refactor/<英単語2〜4語(kebab-case)>` ブランチを作成して移動する(例: `refactor/auto-cleanup`). + - 既に `refactor/` ブランチにいる場合はそれを使う.`feature/` 等の他作業ブランチにいる場合は,混在を避けるため**停止して確認を求める**. +3. **検証スイートの特定**:プロジェクトの構成ファイル(`package.json`,`pubspec.yaml`,`Cargo.toml`,`go.mod`,`pyproject.toml`/`pytest.ini` 等)から,以下を特定する. + - **テスト実行コマンドとフレームワーク**(必須). + - 利用可能なら **ビルド/型チェック/リンタのコマンド**(例: `tsc --noEmit`,`cargo build`,`go build ./...`,`flutter analyze`,`npm run lint` 等).これらは「テスト緑」だけでは拾えないコンパイル破壊やリンタ違反を検出する追加の安全網になる. + - 以降,**「検証スイート」= テスト+(あれば)ビルド/型チェック/リンタ** をまとめて指す.緑の判定はこの検証スイート全体で行う. + - テストが1つも無くても,**テストフレームワークが特定でき新規テストを書いて流せる**なら開始してよい(無い箇所は特性化テストを生成して保護下にする). + - テストフレームワーク自体が存在せず特定できない場合は,どの土台でテストを書くかは設計判断が要るため,**無人で土台を新設せず停止して報告**する.ただしこの場合でも**ドキュメント同期系(D)は実行してよい**(テスト不要のため). +4. **ベースラインの確認**:既存テストがある場合は検証スイートを実行し,**開始時点で全て緑**であることを確認する.赤がある場合は,リファクタの前提(緑からの出発)が崩れているため**停止して報告**する.既存テストが0件の場合はテスト実行を省略してよいが,ビルド/型チェックがあれば実行して緑を確認する. +5. **台帳の読み込み**:以下のローカル台帳が存在すれば読み込む(無ければ空として扱う).いずれも**ローカルな運用状態であり成果物ではないため `.gitignore` 対象**とする(追跡されていなければ `.gitignore` に追記する). + - `.claude/auto-refactor-skip.md`(スキップ台帳):過去に安全に扱えなかったリファクタ対象.今回も**再挑戦せず除外**する.形式は1行1エントリ `- <対象> | <理由> | <日付>`. + - `.claude/auto-refactor-doc-review.md`(ドキュメント要確認リスト):過去に検出した「ドキュメントと実装の矛盾」および「自動では行わない簡潔化・再編の提案」.**既出の項目は再記録しない**(重複・トークン浪費防止).形式は1行1エントリ,先頭にカテゴリを付ける: + - 矛盾: `- [矛盾] <箇所> | <ドキュメントの記述> | <実装の挙動> | <推定原因> | <日付>` + - 提案: `- [提案] <箇所> | <提案内容(どう簡潔化/再編したいか)> | <自動で行わない理由> | <日付>` + - `.claude/auto-refactor-test-review.md`(テスト要確認リスト):テストリファクタで「自動では行わなかった削除・統合・弱体化の提案」.**既出は再記録しない**.形式は1行1エントリ `- [提案] <対象テスト> | <提案内容> | <自動で行わない理由(ミューテーション未実施 等)> | <日付>`. + +## ループ本体 (Loop Body) — 安全な作業が尽きるまで繰り返す + +各イテレーションで「作業項目を1つ」選び,種別に応じた処理を1サイクル実行する. + +### ステップ 0: 作業項目を1つ選ぶ + +セットアップで確定した範囲の中から,次のいずれかの作業項目を**1つ**選ぶ. + +- **リファクタ対象(コード)**:除外リスト・スキップ台帳に該当しないもの.優先度の目安(高い順):重複コードの集約 → 過度に長い関数の分割 → 命名の改善 → デッドコード除去 → 構造の単純化. → 選んだら「リファクタ処理 (R)」へ. +- **ドキュメント・ドリフト項目**:`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` と実装を突き合わせ,**記載漏れ**または**矛盾**がある箇所.要確認リストに既出の矛盾は除外する. → 選んだら「ドキュメント同期処理 (D)」へ. +- **ドキュメントリファクタ項目**:`docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` の中で,**意味を変えずに**改善できる箇所(冗長な言い回し,表記揺れ,書式の乱れ,重複,リンク切れ等). → 選んだら「ドキュメントリファクタ処理 (DR)」へ. + +上記**3種すべてに作業項目が無い場合に限り**,テールフェーズとして次を検討する: + +- **テストリファクタ項目**:肥大化・重複・無意味なテスト(test smells)の整理対象. → 選んだら「テストリファクタ処理 (T)」へ.(前3種が残っている間は選ばない=最後に回す) + +これら**4種すべて**に作業項目が無くなったら**ループを終了**し,完了報告へ進む. + +--- + +### リファクタ処理 (R) + +#### ステップ R1: 保護状態の確認 + +- 「その箇所を変更したときに失敗するテストが存在するか」を確認する. + - **保護下にある** → ステップ R3 へ. + - **テストが無い** → ステップ R2(特性化テストの生成)へ. + +#### ステップ R2: 特性化テストの生成(テストが無い対象のみ/tester エージェントに委譲) + +テストが無い対象は,まず安全網を作る.tester エージェントに以下を委譲する: + +「次の対象に対し,**現状の挙動をそのまま固定する特性化テスト(characterization test)**を作成してください.理想の仕様ではなく,**今のコードが実際に返す挙動**を観測してアサーションに落とすこと(バグも含めて現状を固定する).境界値・主要な分岐・代表的な入出力を網羅してください.作成後にテストを実行し,**現状コードで全て緑**になることを確認してください.緑にできない(=挙動が固定できない)場合は,その旨を報告してください. + +対象: {ステップ 0 で選んだ対象} +テストコマンド: {セットアップで特定したコマンド}」 + +- tester の報告と実テスト結果を確認する. + - **生成テストが現状コードで全て緑** → これを安全網として `git add` し,タグ **`[add]`** でコミットする(例: `[add] 〇〇モジュールに特性化テストを追加`).**この時点ではまだリファクタしない**.コミット後,この対象を「保護下になった」状態でステップ R3 へ進む(同一イテレーション内で続けてよい). + - **緑にできなかった/挙動が固定できない** → この対象は安全に触れないため変更を破棄し,**スキップ台帳(`.claude/auto-refactor-skip.md`)に「対象・理由・日付」を追記**してからステップ 0 へ戻る(以後のイテレーション・ウェイクで再選択しない). + +#### ステップ R3: リファクタ前の緑確認 + +- 検証スイート(テスト+あればビルド/型チェック/リンタ)を実行し,緑であることを確認する(ベースライン/生成した特性化テストの再確認). + +#### ステップ R4: リファクタリング実行(refactorer エージェントに委譲) + +refactorer エージェントに以下を委譲する: + +「次の対象を,挙動を変えずにリファクタリングしてください.テストを安全網とし,リファクタ後に検証スイートを再実行して**全て緑のまま**であることを必ず確認してください.緑にできない場合は変更を破棄し,その旨を報告してください. + +対象: {ステップ 0 で選んだ対象} +検証コマンド: {セットアップで特定したテスト+ビルド/型チェック/リンタのコマンド}」 + +#### ステップ R5: リファクタ後の緑確認 + +- refactorer の報告と実際の検証スイート(テスト+あればビルド/型チェック/リンタ)の結果を確認する. +- **全て緑** → ステップ R6 へ. +- **赤がある/緑にできなかった** → その変更を破棄(`git checkout -- .` または `git stash`)し,**スキップ台帳に「対象・理由・日付」を追記**してステップ 0 へ戻る(同じ対象は再選択しない). + +#### ステップ R6: 専用ブランチへコミット + +- `git add` で当該変更をステージングする(`.env`・クレデンシャル・ビルド成果物は含めない). +- GUIDE_04 のコミット書式に従い,タグ **`[clean]`** でコミットする(例: `[clean] 重複した入力バリデーションを共通関数に集約`). +- **push・PR はしない.** ステップ 0 へ戻る. + +--- + +### ドキュメント同期処理 (D) + +#### ステップ D1: 実装とドキュメントの突き合わせ + +- 選んだ項目について,**実装(コード)を読み,対応する `docs/02_ENV/`・`docs/04_SPEC/`・`docs/05_TECH/` の記述**を確認する. +- 食い違いの種別を判定する: + - **追記型**:ドキュメントに記載が無いが実装にある(例:新しい環境変数・依存,新規モジュール/API,コードで確定した技術選定や制約) → ステップ D2 へ. + - **矛盾型**:ドキュメントの記述と実装の挙動が**食い違う**(例:仕様では戻り値 A だがコードは B を返す) → ステップ D3 へ. + +#### ステップ D2: 追記(自動/実装を真とする) + +- 実装を真として,該当ドキュメント(`02_ENV`/`04_SPEC`/`05_TECH` の適切な場所)に**事実を追記・補足**する.GUIDE_02 のドキュメント作成規約と GUIDE_03 の命名規則に従う. +- **既存の意図的な記述は消さない**.追記・補完にとどめ,全面書き換えはしない. +- コミット(GUIDE_04 準拠): + - 新規セクション/新規ドキュメントファイルの追加 → タグ **`[add]`**(例: `[add] 04_SPEC に〇〇APIの仕様を追記`). + - 既存記述への事実追記・補足 → タグ **`[update]`**(例: `[update] 02_ENV に新規環境変数 FOO を追記`). +- コミット後,ステップ 0 へ戻る. + +#### ステップ D3: 矛盾は報告のみ(自動で書き換えない) + +- **ドキュメントは書き換えない**(不変条件 8).矛盾は実装バグの兆候かもしれず,無人で「実装に合わせて」塗り潰すと検出機会を失う. +- `.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 へ戻る. + +--- + +### テストリファクタ処理 (T) — 前3種が尽きた後のテールフェーズ + +テストコードを整理する.**「検証スイートが緑」は安全網にならない**(削除・弱体化したテストも緑のまま)ため,ミューテーションテストの差分を安全網とする(不変条件 10). + +#### ステップ T1: ミューテーション安全網が使えるか判定 + +- 選んだテストと,それが守る**本番コード範囲**を特定する. +- その範囲に対し,**ミューテーションテストを一時的に走らせられるか**を判定する: + - 言語/スタックに対応するツール(例: JS/TS の Stryker,Python の `mutmut`/`cosmic-ray`,Java の PITest,Go の `go-mutesting` 等)を,**依存を恒久追加せず**に実行できるか(`npx`/`uvx`/`pipx run` 等のエフェメラル実行を優先). + - **走らせられる** → ステップ T2(ミューテーション保護下の全自動)へ. + - **走らせられない**(対応ツールが無い/恒久的な依存・設定の追加が必要/リポ規模的にコストが非現実的) → ステップ T3(構造改善のみ自動)へ.恒久セットアップが要る場合は**無人で導入せず**,テスト要確認リストに「ミューテーションテスト導入の提案」を記録する. +- コスト対策として,ミューテーションは**対象テストが守る本番コード範囲に限定**して実行する(リポ全体には走らせない). + +#### ステップ T2: ミューテーション保護下のテストリファクタ(全自動) + +1. **基準取得**:対象範囲でミューテーションテストを実行し,現在のテスト群が**殺せるミュータント集合**を基準(baseline)として記録する. +2. **リファクタ実施**:肥大化・重複・無意味なテストを整理する(**削除・統合・簡略化を含めてよい**). +3. **検証**: + - 通常の検証スイートが**緑**であること,かつ + - ミューテーションを再実行し,**baseline で殺せていたミュータントが1つも生存に転じていない**こと(=検証力が落ちていない). + - 両方満たす → タグ **`[clean]`** でコミット(例: `[clean] 重複した〇〇のテストを集約`).**一時的に作成/設定したミューテーション関連の成果物はコミットに含めない**(後始末する). + - 1つでも生存に転じた/検証スイートが赤 → その変更を破棄(revert/stash)し,検証力が落ちる変更は行わない(必要ならテスト要確認リストに `[提案]` として記録). +4. ステップ 0 へ戻る. + +#### ステップ T3: ミューテーションが使えない場合(構造改善のみ自動) + +- **自動でよいのは検証を減らさない構造改善のみ**:共通セットアップの extract,ヘルパー/ビルダーへの集約,テーブル駆動化(パラメタライズ),命名・AAA 構造の整理など.アサーションの数・強さを変えないこと. + - 実施後に検証スイートが緑であることを確認 → タグ **`[clean]`** でコミット. +- **テストの削除・アサーション弱体化・検証が減りうる統合は自動で行わない**.`.claude/auto-refactor-test-review.md` に `- [提案] <対象テスト> | <提案内容> | <自動で行わない理由> | <日付>` を**1行追記**(既出は再記録しない). +- ステップ 0 へ戻る. + +--- + +## 停止条件 (Stop Conditions) + +以下のいずれかでループを止める. + +- **4種すべて(コードリファクタ/ドキュメント同期/ドキュメントリファクタ/テストリファクタ)の作業項目が尽きた** → **正常終了**. +- 同じ箇所で繰り返しテストが赤になる/テストコマンドが途中で失敗するようになった → **異常として停止し報告**. +- 不変条件を満たせない状況になった → **停止して報告**. +- ユーザーが割り込んで中断した → その時点までの成果(コミット済み)は `refactor/` ブランチに残る. + +## /loop との併用(推奨される使い方) + +このコマンドは単体で「作業が尽きるまで」連続実行するが,ユーザーが `/loop` でラップして起動すると,放置中の空き枠を使って自律的に再トリガーし続けられる(本コマンドの本来の目的). +`/loop` で回す場合も上記の不変条件・停止条件は同じく厳守すること.長い待機を挟む場合はキャッシュとコストを意識した間隔を選ぶ. + +### 収束条件(loop-until-dry)— 空回りでトークンを浪費しない + +`/loop` で回すと,作業が尽きた後もウェイクのたびに「対象なし → 即終了」を繰り返し,**無駄にトークンを消費**しうる.これを防ぐため,以下の収束ルールを守る. + +- 各イテレーションの開始時に全範囲を再スキャンし,**この回で実施した作業の件数**を数える(コードリファクタ+特性化テスト生成+ドキュメント追記+ドキュメントリファクタ+テストリファクタ+**新規に記録した**矛盾・提案.既出項目の再確認は作業に数えない). +- **作業件数が 0 だった回**を「空振り」とカウントする. +- **空振りが 2 回連続**したら,もう安全に拾える作業は出尽くしたとみなし,**`/loop` 自体を終了する**(次のウェイクをスケジュールしない). + - 1 回の空振りで即終了しないのは,「順序やコミットの巡り合わせで一時的に拾えなかっただけ」のケースを 1 回分許容するため. +- 1 件でも作業した回が出たら,空振りカウントは 0 にリセットする. +- 終了時は「空振りが続いたため収束した」旨を完了報告に明記する. + +## 完了報告 (Reporting) + +ループ終了時,ユーザーに以下を報告する. + +- 作業ブランチ名 +- 追加した特性化テストの件数(= `[add]` のテストコミット数)と対象モジュールの一覧 +- 実施したリファクタリングの件数(= `[clean]` コミット数)と概要の一覧 +- 更新したドキュメントの件数と内容(`02_ENV`/`04_SPEC`/`05_TECH` への**追記**と,意味を保った**簡潔化・整形**(`[clean]`)の箇所一覧) +- **⚠ ドキュメントと実装の矛盾**:要確認リスト `.claude/auto-refactor-doc-review.md` の `[矛盾]` の件数と概要.**実装バグの可能性があるため自動では直していない**ので,1件ずつ「仕様を直す/実装を直す」を人間が判断してほしい旨を明記する +- **簡潔化・再編の提案**:同リストの `[提案]` の件数と概要(情報が落ちうるため自動では行わなかったもの.採否は人間が判断) +- 整理したテストの件数と概要(`[clean]`).ミューテーションテストを**安全網に使えたか/使えず構造改善のみに留めたか**を明記する +- **テストリファクタの提案**:`.claude/auto-refactor-test-review.md` の `[提案]` の件数と概要(削除・統合・弱体化など自動では行わなかったもの.ミューテーション導入の提案を含む場合はそれも) +- スキップした対象とその理由(挙動が固定できずテスト生成に失敗/検証スイートが緑にできなかった 等).詳細はスキップ台帳 `.claude/auto-refactor-skip.md` に追記済み +- ⚠ 自動生成した特性化テストは**現状の挙動(バグを含む)を固定**したもの.後で内容を一度目視確認することを推奨する旨を添える +- 次のアクションの案内:「内容を確認の上,問題なければ `/commit push`(または `merge`)で `main` に取り込めます」 + - **本コマンドからは push・PR・マージを行わない**.取り込みは必ずユーザーの明示指示(`/commit push` 等)で行う. diff --git a/.gitignore b/.gitignore index d2f109f..7bc8335 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,11 @@ # /implement が /commit に渡すコンテキストファイル .claude/commit-context.md +# /auto-refactor のローカル運用状態(スキップ台帳・要確認リスト) +.claude/auto-refactor-skip.md +.claude/auto-refactor-doc-review.md +.claude/auto-refactor-test-review.md + # -- プロジェクト立ち上げ時に有効化する(GUIDE_04 参照) -- # .env # .env.* diff --git a/CLAUDE.md b/CLAUDE.md index cfdc591..329ab8c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,6 +16,7 @@ - ブランチ名・コミットメッセージの書式は GUIDE_04 に従う - コミットは `/commit` を使用する(push・PR 作成は `/commit push`) - **`/commit` はユーザーが明示的に指示した時のみ実行する.Claude が自発的に `/commit` や `git commit` を呼んではならない**(`/implement` 完了後も,案内するだけで自分ではコミットしない) + - **例外**: `/auto-refactor`(無人運転のリファクタ/ドキュメント整理ループ)はユーザー承認済みの例外として `refactor/` 専用ブランチに自律コミットする.ただし push・PR・マージ・`main` への操作はしない(取り込みは人間が `/commit push` 等で行う) ### エージェントチーム(GUIDE_05 準拠) diff --git "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" index 2936c2a..ae5ea44 100644 --- "a/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" +++ "b/docs/01_GUIDE/GUIDE_05_\343\202\250\343\203\274\343\202\270\343\202\247\343\203\263\343\203\210\351\201\213\347\224\250\343\203\253\343\203\274\343\203\253.md" @@ -136,6 +136,8 @@ ※ リファクタリングとテストは実装と一体の成果物として,まとめてコミットする.必要に応じて分割コミットも可. +※ **例外(無人運転)**: `/auto-refactor` は CLAUDE.md の「`/commit` 自発実行禁止」ルールに対するユーザー承認済みの例外として,`refactor/` 専用ブランチに自律コミットする.push・PR・マージ・`main` への操作は行わず,取り込み可否は人間が判断する. + ## 進捗記録の運用ルール(CLAUDE.md / PROGRESS.md) 進捗記録は **2 ファイルの二段構成**で管理する.Phase 4 や `/setup` 中断時にこれらを更新する.