code-refine

コードのリファクタリング

範囲は、ユーザーがリファクタリングを依頼した対象です。指定がない場合は、ステージ済みと未ステージの差分を、未追跡のソースファイルも含めて対象にします。リファクタリングするコードがない場合は、その旨を伝えて終了します。保留中の変更、ブランチ、プルリクエストなど変更を指定する範囲は、その指定された差分を対象にします。それ以外は領域を対象にします。

code-refinements スキルを読み込み、すべての変更に対して、そのルールと3つのレンズ、すなわち制約、単純さ、パラメトリック性を適用します。インストールされていない場合は、次のコマンドでインストールします。

npx skills add https://github.com/alexandru/skills --skill code-refinements

ワークフロー

1. 範囲、契約、検証方法を確認します。 プロジェクトのエージェント向け指示、規約、関連する仕様を読みます。維持すべき動作と API、対象範囲内のホットパス、必要な検証を特定します。仕様で動作が定義されていない場合は、既存の契約と呼び出し元を調査し、解決されていない曖昧さについて、要件を独自に作り出さずに報告します。
2. 正当化できる改善を特定し、適用します。 3つのレンズを通してレビューし、呼び出し元をたどって動作に関する主張を確認します。各変更で、取り除く複雑さを明示し、以下の契約を維持する必要があります。関連するテストで編集内容を検証し、観測可能な動作が明らかになった場合は、特性テストを追加します。動作の変更を伴う既存のバグは、承認が必要なものとして報告します。修正が承認された場合は、修正する前に、失敗するテストでその問題を実証します。
3. 価値のある改善がなくなるまで繰り返します。 変更したコードと、その中核となるモデルを再評価し、対象範囲内で正当化できる改善がさらにないか確認します。局所的なクリーンアップにとどまらず、別の表現によって無効な状態、処理パス、あるいはモジュール全体をなくせないか検討します。
4. レビュー、検証、報告を行います。 変更全体の差分をレビューし、回帰と変更間の相互作用を確認します。回帰があれば修正または取り消し、サポート対象の構成すべてでプロジェクト必須の検証を実行し、修正後に再実行します。ホットパスを変更した場合は、パフォーマンスを確認します。取り除いた複雑さ、承認されたバグ修正とそのテスト、検証結果と制限事項、ユーザーに判断を委ねる事項を報告します。

不変条件

• 改善とはリファクタリングです。既存のバグを修正する変更も含め、ユーザーの明示的な承認なしにエンドユーザーの動作を変更してはなりません。観測可能な動作を維持する限り、内部構造、データ型、呼び出し順序、中間表現は変更できます。機能は維持し、ホットパスを遅くしてはなりません。
• これまでコードが受け入れていた入力は、引き続き受け入れます。解析できた値、成功したリクエスト、すでに保存されているデータがこれに該当します。入力ルールを厳格化するのは動作の変更であり、承認が必要です。
• 公開 API は動作の一部です。ユーザーがコンパイル時に依存するシグネチャと、契約を記述するそのドキュメントコメントが該当します。ただし、ユーザーまたはプロジェクトの指示で API の変更が明示的に許可されている場合を除きます。変更によって誤りとなるドキュメントの文は更新します。
• テストは、以前に実行されていたすべての環境で、引き続き実行できなければなりません。CI が実行する構成に限定したり、対象ケースを未検証のままテストを削除したりしてはなりません。
• 差分を対象とする場合は、差分で追加または変更された部分だけを改善します。差分によって必要になる場合に限り、周辺コードにも手を加えます。