Clarify Code

この skill は明示的に呼び出された場合のみ使用する。

$clarify-code
$clarify-code <対象差分>

• 対象の指定がなければ、現在の作業ツリーの変更を stage 済みの変更も含めて対象にする。
• 対象が指定されていれば、その差分を対象にする。差分を取得できない場合は推測で変更しない。

目的

対象差分に関わる処理を、人間が入口から結果まで追いやすい構造にする。 コード量、関数の短さ、抽象化の数を減らすこと自体は目的にしない。

判断基準

呼び出し元から、次の点を追えるかを確認する。

• 何を入力として受け取るか
• どの条件で何を判断するか
• いつ状態を変更し、どの副作用を起こすか
• 何を結果として返すか
• 失敗した場合に何が起きるか

処理の理解に必要な判断や副作用が、不要なラッパー、ヘルパー、間接層に隠れている場合は構造を見直す。 一方、独立した責務や安定した契約を表す境界は残す。必要なら新たに設けてもよい。 関数を短くするためだけの分割や、行数を減らすためだけの統合は行わない。

Workflow

1. 対象差分と変更意図を確認する。関連する呼び出し元、呼び出し先、テスト、既存コメントも読む。
2. 主要な処理経路を入口から結果まで追い、理解の妨げとなる構造やコメントを特定する。
3. 振る舞いと public API を維持したまま、コードと関連コメントを変更する。
4. 関連するテスト、型チェック、lint などで検証し、コードとコメントの差分を見直す。

コメントの精査

対象差分に関わる処理経路では、変更行の外にある既存コメントも確認する。 コメントの内容をコード、テスト、外部との契約と照らし合わせ、次の基準で扱う。

• コードから分かる手順や要約、作業ログ、古くなった説明は削除または修正する。
• 読みにくい構造をコメントで補っている場合は、構造を見直す。
• 通常の実装が成立しない理由、不変条件、外部 API や互換性の制約、確認済みの性能制約、 既知の問題と回避条件など、コードから読み取れない事実を残す。
• 残すコメントには、適用条件と無視した場合に壊れるものが分かるようにする。
• 公開インターフェースの契約を示す doc comment は、プロジェクトで正本として使う場合、その契約を保つ。

根拠を確認できないコメントは推測で書き換えず、確認できなかった点を報告する。 新しいコメントも、コードだけでは分からず、将来の変更時に守る必要がある事実に限る。

変更時の制約

• 対象差分と、処理の追いやすさに必要な周辺コードだけを変更する。
• 無関係な変更は、stage 済みのものも含めて保持する。
• 入出力、エラー、検証、状態変更、副作用の順序、リソースの扱い、並行処理の意味を保つ。
• public API の名前、型、契約、互換性を変更しない。
• 明確な改善がない箇所は変更しない。

振る舞いを維持できる根拠が不足している場合は、既存テストと呼び出し側から契約を確認する。 必要なら関連する振る舞いをテストで固定してから変更する。 それでも安全に判断できない箇所は推測で書き換えず、理由を報告する。

完了時の報告

• 処理の流れがどのように追いやすくなったか
• 既存コメントをどう扱ったか、その理由
• 振る舞いと public API を維持した根拠
• 実行したテストや検証、その結果
• 変更できなかった箇所と理由があれば、その内容