| name | front-end-refactor-loop |
| description | 指定されたフロントエンド範囲に対して、同梱の front-end-design-patterns 参照を使った新規監査、Cursor CLI sprint への安全な局所委譲、main Codex による採否判定・修正・検証・必要時の性能計測・コミットを NO_FINDINGS まで反復する。機能変更なしの React / Vue / JavaScript リファクタリング、描画ホットパス整理、依存安定化、派生 state 整理、component 境界分離、bundle / lazy loading 改善、サブエージェント調査つきフロントエンドリファクタリングで使う。起動語: front-end-refactor-loop, フロントエンドリファクタリングループ, Reactリファクタリングループ, Vueリファクタリングループ, NO_FINDINGSまでリファクタ, Cursor CLIでフロントエンドリファクタ
|
front-end-refactor-loop
指定されたフロントエンド範囲を、挙動変更なしで反復的に整理する。main Codex がループ制御、採否判定、統合、検証、最終報告を担当し、read-only 監査や安全に分離できる局所実装だけを cursor-agent-sprint-cli 経由で Cursor CLI worker に渡す。
絶対ルール
- このスキル配下以外の既存スキル資産を参照しない。必要な設計パターン資料は、このスキルの
references/front-end-design-patterns/ から読む。
cursor-agent-sprint-cli は WORKSPACE/.codex/skills/dev/cursor-agent-sprint-cli をパス参照して使う。- Cursor CLI worker に commit、push、PR 作成、branch 切替、sprint 完了判断、最終報告、進行管理ファイルの任意更新を任せない。
- 機能、UI 仕様、公開 API、データ形式、保存形式、URL、イベント順、外部 API 呼び出しを意図的に変えない。
- 既存の未コミット変更を戻さない。関係がある場合は差分を読んで作業し、関係がなければ触らない。
- worker の報告だけで採用しない。main Codex が必ず
git diff、write scope、検証結果を確認する。
- 性能改善を主張する変更、render / state / bundle / canvas / list / queue に影響する変更では、必要に応じて性能計測ゲートを通す。
参照資料
必要になった時点で以下を読む。最初から全 reference を読み込まない。
- 設計パターンの入口:
references/front-end-design-patterns/decision-matrix.md
- React 参照候補:
references/front-end-design-patterns/react/index.md
- Vue 参照候補:
references/front-end-design-patterns/vue/index.md
- JavaScript / bundle / loading 参照候補:
references/front-end-design-patterns/javascript/index.md
- Worker 用プロンプト雛形:
references/prompt-templates.md
- ループ報告雛形:
references/report-templates.md
decision-matrix.md で候補を 1 から 4 件に絞り、必要な個別 reference の Original Skill Metadata と original-skill-body を読む。
起動前確認
ユーザー指示から以下を確定する。危険な曖昧さがない限り、質問で止まらず既存コードから推定する。
- 対象範囲: route、component、directory、feature、関連 hook / store / utility。
- 変更禁止条件: 機能、UI、公開 API、データ形式、保存形式、外部通信、イベント順。
- 検証条件:
typecheck、lint、test、build、browser check、既存 fixture。
- コミット方針: 原則として修正ループごとに
dev:simple-add 相当の最小コミットを行う。ユーザーがコミット不要と明示した場合はコミットしない。
最初に repository context を読む。
git status --short
git branch --show-current
あわせて AGENTS.md、package.json、対象ファイル、周辺利用箇所、既存 test、build / lint / typecheck script を確認する。
Sprint 初期化
1 回の refactor run につき 1 つの sprint directory を使う。
WORKSPACE="$(pwd)"
SPRINT_SKILL_DIR="$WORKSPACE/.codex/skills/dev/cursor-agent-sprint-cli"
SPRINT_SLUG="frontend-refactor-<short-slug>"
"$SPRINT_SKILL_DIR/scripts/init_sprint.sh" --workspace "$WORKSPACE" --slug "$SPRINT_SLUG"
. "$WORKSPACE/.codex/tmp/$(date +%y%m%d)_$SPRINT_SLUG/sprint-env.sh"
SPRINT_SKILL_DIR が存在しない場合だけ、リポジトリ実体に合わせて絶対パスを確認する。cursor-agent-sprint-cli の scripts や templates はこのスキルへコピーしない。
brief.md には対象範囲、挙動維持制約、参照する pattern reference、検証コマンド、完了条件を書く。tasks.md には round、audit task、implementation task、main-owned task、write scope、禁止範囲、検証を記録する。
全体フロー
- 対象範囲と検証条件を確定する。
decision-matrix.md から今回使う設計パターン reference を選び、必要な個別 reference を読む。cursor-agent-sprint-cli の preflight を実行する。- 新規監査を read-only worker task として投げる。広い対象は複数 scope に分割する。
- main Codex が findings を採否判定し、
performance_sensitive を分類する。
- 安全に分離できる局所変更だけ Cursor CLI worker に実装委譲する。shared contract や境界判断は main Codex が持つ。
- 性能計測ゲート対象なら before / after を同じ手順で測り、一時計測コードを削除する。
- main Codex が diff、write scope、挙動維持、検証結果を確認する。
- 検証後、コミット方針に従って
dev:simple-add 相当で最小コミットを行う。
- 最新 clean HEAD から次の新規監査を実行する。
- 全対象 scope が同じ最新 clean HEAD で
NO_FINDINGS を返したら最終検証と最終レポートを行う。
新規監査
新規監査は毎 round 新しい worker task として実行する。前回 worker の文脈を再利用しない。
監査 task は原則 read-only にする。対象が広い場合は、route、component、shared hook、state、media、bundle などで scope を分け、各 worker の担当範囲を重ねすぎない。
監査 worker には以下を必ず渡す。
- repository 絶対パス。
- expected HEAD と
git status --short の期待値。
- read-only 制約。
- 対象範囲。
- 読むべき pattern reference の候補。
- このスキル配下以外の既存スキル資産を参照しない制約。
- 出力形式と
NO_FINDINGS の完了条件。
完了判定に使えるのは、同じ最新 clean HEAD を確認し、対象範囲を fresh に読み直し、指定形式で返した結果だけ。BLOCKED、形式崩れ、古い HEAD、親セッションの要約、範囲外の一般論は採用しない。
指摘の採否
NO_FINDINGS でない場合、main Codex が全件を読む。
- 機能変更、UI 仕様変更、公開 API 変更、データ形式変更を含む提案は採用しない。
- 好みだけの抽象化、既存規約に合わない置き換え、大きな依存追加は採用しない。
- 採用する指摘は、変更範囲、挙動維持根拠、検証方法、性能計測要否を明確にする。
- 同一 round 内で安全に直せる指摘はまとめて直す。write scope が重なる作業を複数 worker に並列委譲しない。
実装委譲の基準
Cursor CLI worker に渡してよいもの:
- 単一 component / hook / utility の局所整理。
- テスト追加や fixture 追加。
- import 整理、型補助、純粋関数抽出。
- write scope を絶対パスで限定でき、他 task と重ならない変更。
main Codex が担当するもの:
- component API、routing、state / context、data fetching、bundle boundary などの contract 判断。
- 複数 worker 成果の統合。
- 性能計測ゲートの設計と結果判断。
- コミット、最終検証、最終報告。
- write scope が広い変更、既存未コミット変更に接する変更。
性能計測ゲート
以下に該当する場合は、原則として before / after の最小計測を行う。
- render 回数、React commit duration、state churn に影響する。
- state / context / selector / memo / callback / component boundary を変える。
- list / grid / card / table / canvas / image preview / hover / drag / queue / timer に関わる。
- route split、lazy import、bundle size に関わる。
- large object state、large data URL、image encode / decode、canvas 同期処理に関わる。
- レポートで「速くなる」「再描画が減る」「bundle が分離される」と主張する。
型整理、命名整理、局所ファイル分割、dead code 削除、import 整理、性能改善を主張しない保守性中心の変更では省略してよい。省略した場合は理由を書く。
計測コードは一時差分にする。after 計測後に必ず削除し、git status --short と git diff で残っていないことを確認する。
検証
変更内容に合う最小検証を実行する。
優先順:
- typecheck
- 対象ファイル lint
- 対象 test
- build
- browser check
- 性能計測ゲートの after 計測
検証できない場合は、理由、代替確認、残リスクを report に書く。
完了条件
- 最新 round の全監査 scope が同じ clean HEAD で
NO_FINDINGS を返している。
- 採用した指摘が実装・検収・検証済みである。
- 性能計測ゲート対象の一時計測コードが残っていない。
- 修正済み loop はコミット方針どおり処理済みである。
- 作業ツリーが clean、またはユーザー由来の unrelated 変更だけが残っている。
- 最終レポートに対象範囲、loop 履歴、適用した pattern、検証結果、性能計測の有無、残リスクを含めている。
