# Front End Refactor Loop

> 指定されたフロントエンド範囲に対して、同梱のfront-end-design-patternsを使って監査・リファクタリングする。独立エージェント向けのread-only audit modeでは、必要なreferenceだけを選び、実装やSprintを開始せずfindingを返す。React／Vue／JavaScriptのcomponent境界、state、render、bundle、loading、性能の監査と改善で使う。起動語: front-end-refactor-loop, フロントエンドリファクタリングループ, front-end audit, read-only front-end audit

- Skill: `ryryo/front-end-refactor-loop` (Agent Skill, multi-file: 67 files)
- Install (CLI): `npx skillmds@latest add ryryo/front-end-refactor-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryryo/front-end-refactor-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ryryo (https://skillmd.com/u/ryryo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ryryo/front-end-refactor-loop

---


# 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 にversion control／remote操作、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` を読む。

## Read-only audit mode

利用者または呼出元スキルが`read-only audit mode`を指定した場合、この節をSprint初期化、Cursor preflight、実装委譲、修正loopより優先する。

- repositoryと指定scopeをfreshに読み、編集、Sprint／進捗file作成、テスト／build実行、Cursor CLI、version control、外部作用を行わない。
- 許容された既存差分を`git status --short`で確認し、baselineと現在差分の両方を監査する。
- `decision-matrix.md`から現在の症状に必要なreferenceを1〜4件だけ選び、選んだ個別referenceを読む。
- component／composition、hook／effect、context／selector／state、render／canvas／list、bundle／loading、accessibility、SSRのうちscopeへ適用する観点を一件目で止めずに一巡する。
- blanket memoization、行数だけの分割、未計測の性能主張、UI仕様変更、新dependencyをfindingへ昇格させない。
- audit agentは採否、goal化、実装、完了判定をせず、一回のfresh reportを返して停止する。

出力には次を含める。

1. 実際に確認したscopeとpath
2. 選択したpattern referenceと適用理由
3. findingごとのseverity、path／line、到達するrender／interaction経路、影響、最小修正境界、既存oracle、性能計測要否
4. 既に差分で直っている問題、却下／deferした候補と理由

追加のP0／P1／P2がなければ`NO_FINDINGS`とする。read-only audit modeはここで終了する。

## 起動前確認

ユーザー指示から以下を確定する。危険な曖昧さがない限り、質問で止まらず既存コードから推定する。

- 対象範囲: route、component、directory、feature、関連 hook / store / utility。
- 変更禁止条件: 機能、UI、公開 API、データ形式、保存形式、外部通信、イベント順。
- 検証条件: `typecheck`、lint、test、build、browser check、既存 fixture。
- 結果記録: 修正ループごとに変更path、採否、検証結果を記録する。

最初に repository context を読む。

```bash
git status --short
```

あわせて `AGENTS.md`、`package.json`、対象ファイル、周辺利用箇所、既存 test、build / lint / typecheck script を確認する。

## Sprint 初期化

1 回の refactor run につき 1 つの sprint directory を使う。

```bash
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、禁止範囲、検証を記録する。

## 全体フロー

1. 対象範囲と検証条件を確定する。
2. `decision-matrix.md` から今回使う設計パターン reference を選び、必要な個別 reference を読む。
3. `cursor-agent-sprint-cli` の preflight を実行する。
4. 新規監査を read-only worker task として投げる。広い対象は複数 scope に分割する。
5. main Codex が findings を採否判定し、`performance_sensitive` を分類する。
6. 安全に分離できる局所変更だけ Cursor CLI worker に実装委譲する。shared contract や境界判断は main Codex が持つ。
7. 性能計測ゲート対象なら before / after を同じ手順で測り、一時計測コードを削除する。
8. main Codex が diff、write scope、挙動維持、検証結果を確認する。
9. 検証後、変更path、採否、検証結果を記録する。
10. 対象範囲をfreshに読み直して次の新規監査を実行する。
11. 全対象scopeが同じreview対象範囲で`NO_FINDINGS`を返したら最終検証と最終レポートを行う。

## 新規監査

新規監査は毎 round 新しい worker task として実行する。前回 worker の文脈を再利用しない。

監査 task は原則 read-only にする。対象が広い場合は、route、component、shared hook、state、media、bundle などで scope を分け、各 worker の担当範囲を重ねすぎない。

監査 worker には以下を必ず渡す。

- repository 絶対パス。
- `git status --short`で許容する既存差分と、今回のread scope。
- read-only 制約。
- 対象範囲。
- 読むべき pattern reference の候補。
- このスキル配下以外の既存スキル資産を参照しない制約。
- 出力形式と `NO_FINDINGS` の完了条件。

完了判定に使えるのは、許容した既存差分以外がないことを確認し、対象範囲をfreshに読み直し、指定形式で返した結果だけ。`BLOCKED`、形式崩れ、親セッションの要約、範囲外の一般論は採用しない。

## 指摘の採否

`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 成果の統合。
- 性能計測ゲートの設計と結果判断。
- version control操作、最終検証、最終報告。
- 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` で残っていないことを確認する。

## 検証

変更内容に合う最小検証を実行する。

優先順:

1. typecheck
2. 対象ファイル lint
3. 対象 test
4. build
5. browser check
6. 性能計測ゲートの after 計測

検証できない場合は、理由、代替確認、残リスクを report に書く。

## 完了条件

- 最新roundの全監査scopeが同じreview対象範囲で`NO_FINDINGS`を返している。
- 採用した指摘が実装・検収・検証済みである。
- 性能計測ゲート対象の一時計測コードが残っていない。
- 修正済みloopの変更path、採否、検証結果が記録済みである。
- 作業ツリーが clean、またはユーザー由来の unrelated 変更だけが残っている。
- 最終レポートに対象範囲、loop 履歴、適用した pattern、検証結果、性能計測の有無、残リスクを含めている。