naming-refactor

命名のリファクタリング

スラッシュまたはドル記号による呼び出しですでにこれらの指示が会話に追加されている場合は、その指示に従ってください。 その場合、スキルツールを使ってこのスキルを再度呼び出さないでください。

リファクタリングのコストにかかわらず、現在のリポジトリ内のすべての名前が、まとまりのある単一のドメインモデルを示すようにしてください。

契約

• 現在の Git リポジトリ全体を対象にしてください。選択したファイルだけに範囲を狭めたり、候補数の上限に達した時点で停止したりしないでください。
• 機能、実行時の動作、副作用、性能に関わる特性、外部から利用される契約を維持してください。大規模な差分、パスの移動、リポジトリが管理するインターフェースの移行は許可されています。
• エクスポートされたインターフェースについて、すべての利用側が対象範囲内にあり、一括で移行できる場合に限り、リポジトリが管理するものとして扱ってください。それ以外の API 名、CLI フラグ、環境変数、設定キー、ワイヤーフィールド、ルート、データベース名、インポートパスは、ユーザーが破壊的変更を明示的に許可しない限り維持してください。
• リファクタリング中に見つかったバグを修正するのは、不具合と意図された動作が明確で、回帰チェックによって修正を証明できる場合に限ります。バグ修正は独立した変更の波としてまとめ、別途報告してください。
• 既存の作業を維持してください。ローカル編集、ファイル移動、ディレクトリ構成の変更、非破壊的な検証は許可されています。ユーザーまたはリポジトリの指示で求められていない限り、コミット、プッシュ、公開、外部への書き込みは行わないでください。
• 交差するリポジトリへの書き込みと、実装および検証を直列化してください。まずコードベース全体の分析とリファクタリング計画を完了し、その後、「実装範囲の取得」で定義されているとおり、各変更の波の前に累積的な書き込み対象を確保してください。
• 検証済みの変更なしという結果が有効なのは、網羅的な確認を終えた後に限ります。差分を生み出すためだけに明確で慣例的な名前を変更しないでください。ただし、差分を最小限に抑えるために弱い名前を残してはいけません。

カバレッジ台帳

この SKILL.md を基準に scripts/naming-ledger.py の場所を解決し、リポジトリ外に台帳を作成してください。

uv run "<skill-dir>/scripts/naming-ledger.py" init --root <repo> --ledger <scratch.json>

ヘルパーは、追跡対象および無視されていない未追跡のすべてのパスを対応付け、既存の作業ツリーの状態を記録します。名前、関連する内容、役割を確認した後に限り、そのパスを処理済みにしてください。

uv run "<skill-dir>/scripts/naming-ledger.py" mark \
  --ledger <scratch.json> --status <pending|retained|renamed|excluded|blocked> \
  --path <path> [--path <path>...] [--reason <text>]

現在の名前が妥当である場合は retained、パスまたはその内容が検証済みの名称変更に含まれる場合は renamed、生成物、ベンダー提供物、バイナリ、または一括処理対象の成果物について、そのソースまたは不変条件を通じて検証した場合は excluded、動作または契約の安全性を確認できない場合は blocked を使用してください。excluded と blocked には理由が必要です。

委任した実行では、各サブエージェントに、リポジトリ外へ、1 行につき 1 レコードの処理状況 TSV を作成させてください。 status<TAB>repo-relative-path<TAB>reason の形式です。並行する mark と refresh の呼び出しは、サイドカーファイル <scratch.json>.lock で直列化されます。調整を行うセッションから、各ファイルを一括で適用してください。

uv run "<skill-dir>/scripts/naming-ledger.py" mark \
  --ledger <scratch.json> --from-file <dispositions.tsv>

サブエージェントは、計画済みだが未検証の名称変更を pending として報告します。変更の波を検証した後は、TSV を書き換えるのではなく、--pending-as renamed（または別の最終ステータス）を指定してそのファイルを適用してください。理由は変更しないでください。また、excluded または blocked には引き続き理由が必要です。

処理状況に記載するパスはリポジトリルートからの相対パスであり、台帳のエントリーと完全に一致する必要があります。台帳に含まれるのは、追跡対象と無視されていない未追跡のファイルのみです。Git で無視される成果物、キャッシュファイル、単独のディレクトリは台帳のパスではありません。不明なパスがある場合、一括処理は安全側に停止します。報告されたパスを確認し、すべてのスキップが意図的であると確かめた場合に限り、--skip-unknown を付けて再実行し、その結果の skipped リストを検証してください。

uv run "<skill-dir>/scripts/naming-ledger.py" pending --ledger <scratch.json> [--limit <n>]
uv run "<skill-dir>/scripts/naming-ledger.py" refresh --ledger <scratch.json>
uv run "<skill-dir>/scripts/naming-ledger.py" summary --ledger <scratch.json>

パスの移動後、および最終検証の前に、台帳を更新してください。新しいパスは pending になります。削除された retained のパスは pending に戻ります。削除されたパスも台帳に残り、renamed、excluded、blocked のいずれかとして処理する必要があります。ヘルパーが pending または blocked のパスがないと報告した時点でのみ、作業は完了です。

リファクタリングの根拠を固める

1. 適用されるリポジトリの指示を読みます。リポジトリのルート、開始時のコミットとステータス、ビルドおよびチェックコマンド、生成ソース、既存の変更に対する所有権の境界を記録します。
2. 台帳を初期化し、リポジトリに適したベースラインのフォーマット、Lint、型、テスト、ビルド、コード生成、API スナップショット、またはスモークチェックを確立します。編集前に既存の失敗の原因を特定します。
3. 外部コントラクト、リポジトリ内で管理される利用側、リフレクションおよびシリアライズの対象、動的インポート、大文字と小文字を区別しないファイルシステムの制約、言語に対応した名前変更ツールを特定します。
4. 動作、型、データフロー、ドキュメント、テスト、関連する履歴から、標準的なドメイン用語を導き出します。意図が不明確な場合は履歴を参照します。ただし、履歴が現在の設計に優先することはありません。

このフェーズを完了するには、記録されたベースライン、明示されたコントラクトの境界、リポジトリ全体を網羅する台帳が必要です。

名前変更マップを作成する

台帳のすべてのパスを調査し、一貫したドメインのまとまりごとに変更する前に、根拠に基づくマップを作成します。ディレクトリ、ファイル、パッケージ、モジュール、名前空間、エクスポート、型、クラス、関数、メソッド、パラメーター、変数、真偽値、定数、テスト、フィクスチャ、ドキュメント、設定、スクリプト、CI を対象にします。

以下のルールを組み合わせて適用します。

• 1 つの概念には 1 つの標準用語を使用します。異なる概念には異なる用語を使用します。
• 偶発的な実装の詳細ではなく、ドメイン上の役割、動作、所有権、ライフサイクル、単位、極性に基づいて命名します。
• 根拠に基づいて具体的な名前を付けられる場合は、data、info、item、manager、process、handle、utils のような誤解を招く名前、意味が多重化した名前、文脈のない名前、汎用的な名前を置き換えます。
• ディレクトリ、ファイル名、主要なエクスポート、モジュールの責務を一致させます。現在の構造が所有権を不明確にしている場合や、文脈の不足を補うために不適切な名前を強いている場合は、パスを移動します。
• 必要な言語、フレームワーク、プロトコル、エコシステムの慣例を維持します。既存の用語体系に一貫性がある場合、リポジトリ全体に及ぶ大文字・小文字の変更や類義語への置き換えは行いません。

名前変更グループごとに、変更前と変更後の概念、根拠、コントラクトの分類、影響を受ける利用側、名前の衝突リスク、動的文字列参照、移行順序、検証チェックを記録します。名前を決める前に、シンボルと参照を調査して曖昧さを解消します。意味が多重化した用語を、盲目的に一括置換してはいけません。

このフェーズを完了するには、除外対象以外のすべてのパスについて、根拠のある命名モデルを維持するか、検証済みの名前変更グループに割り当てるか、具体的な根拠を添えてブロック中として記録する必要があります。

実装範囲の確定

コードベースの分析とリネームマップの作成が完了したら、リネームグループ、依存関係の波、契約境界、リスク、立証チェックを含む、根拠に基づいたリファクタリング計画を提示します。各波の開始前に、リポジトリの調整メカニズムを使って、累積する書き込み対象を確保します。対象には、これまでに書き込みを行ったすべてのパスに加え、その波で扱う定義、検索で見つかった利用箇所、移動元と移動先のパス、および再帰的に移動するディレクトリを含めます。以前の波で対象にしたパスが抜けている確保は無効です。利用箇所を列挙できない場合（広範囲に使われている識別子のリネームや、トップレベルディレクトリの移動など）に限り、作業ツリー全体（--recursive '.'）を確保します。

ai-coord を使う場合は、ai-coord start 'naming refactor' <paths>... [--recursive <dir>]... を実行し、READY が返されてから作業を進めます。BLOCKED、UNKNOWN、パスのない INTENT の結果では編集は許可されず、ユーザーの承認を得ても覆すことはできません。最終検証が完了するまで、確保を維持します。

確保を得たら、現在のコミットと作業ツリーの状態を再確認し、台帳を更新して、リポジトリを記録済みのベースラインと比較します。分析中に内容または存在状態が変わったすべてのパスを再調査し、実装前にリネームマップ、契約境界、立証チェックを更新します。台帳の更新で検出されるのはパスの変更であり、既存パスの内容の変更ではありません。他の作業者が未確保のパスを変更する可能性があるため、各波の直前と最終検証時に旧名を再検索し、新たな利用箇所が見つかった場合は確保対象に追加します。

リポジトリに信頼できる調整メカニズムがない場合は、実装と検証が完了するまで、他のコーディングエージェントがリポジトリに書き込みを行わないことをユーザーに確認します。ユーザーがその代替期間を明示的に確認するまで作業を中断します。作業ツリーが安定していること、プロセスが見当たらないこと、または最初の呼び出しだけを根拠に確認済みと判断してはいけません。

検証済みの波で実行する

実装範囲が有効な状態で、リネームグループを依存関係に沿ったまとまりのある波に分けて適用します。委任するすべての書き込みを、確保済みの書き込み対象内に収めます。範囲の所有権を失った場合や、別の作業者が確保済みのパスに現れた場合は、続行せずに停止します。

• シンボルのリネームには、言語サーバー、コンパイラー、または AST 対応のリネーム機能を優先します。各出現箇所が同じ意味であると確認できた場合に限り、完全一致のテキスト置換を使います。
• 追跡対象のパスを移動する際は、無関係な作業をステージせずに済む、リポジトリで安全な方法を使います。大文字小文字の違いだけによるリネームを大文字小文字を区別しないファイルシステムで行う場合は、中間パスを使います。
• 定義、利用箇所、インポート、再エクスポート、テスト、フィクスチャ、ドキュメント、サンプル、設定、CI、セレクター、リフレクション、シリアライズ、生成ソースを同じ波の中で更新します。
• 生成物は、生成器またはスキーマを変更してから再生成し、検証します。ベンダー提供のソースは編集しません。
• 各波の後に、範囲を絞った立証チェックを実行します。原因を特定できる失敗は、次の波に進む前に修正します。互換性を確認できない場合は、リポジトリ全体に対するリセット、クリーン、チェックアウト、またはスタッシュのコマンドを使わず、その波で行った編集だけを元に戻します。
• 波の検証が完了した後にのみ、その台帳パスを完了扱いにします。パスの移動後は台帳を更新し、新しいパスも対象に含めます。

計画したすべてのリネームが適用されるか、実施不能としてブロックされるまで続けます。リファクタリングのコスト、差分のサイズ、経過時間を中止の基準にしてはいけません。

最終検証とレポート

台帳を更新し、新しいパスをすべて確認して、命名上の重大な問題が見つからなくなるまで意味に基づく命名の確認を繰り返します。 古い名前やパスが残っていないか、大文字・小文字の違いやコード以外のリテラルも含めて検索します。リポジトリ全体のチェックを実行し、 ベースラインと比較します。説明のつかない新たな失敗は許容されません。利用可能な API スナップショット、スキーマ、CLI ヘルプ、インポートサーフェス、または対象を絞ったスモークテストを通じて、安定した外部コントラクトを検証します。

成功時は、次の見出しを先頭に記載します：### ✅ Naming refactor complete — <rename groups> groups · <accounted>/<mapped> paths accounted。 ファイルとディレクトリの移動を正確に報告し、すべての公開名またはエクスポート名の変更、ローカル識別子のグループ数の概要、ベースラインと最終チェックの比較、意図的に維持した外部名、付随的なバグ修正、残るリスクを報告します。コマンド、パス、名前、診断、コントラクト識別子は正確な表記のまま、装飾を加えずに記載します。

台帳が未完成の場合、動作の同等性が証明されていない場合、または外部コントラクトの維持に未承認の破壊的変更が必要な場合は、次の見出しを先頭に記載します：### ⛔ Naming refactor incomplete。妨げとなっている根拠と必要な判断を報告します。保留中またはブロック中のパスが残っている間は、作業が完了したと述べてはいけません。