Spec Loader リファクタースキル

Spec Loaderシステムが実装やテストで正しく使われているかをチェックし、未導入のファイルをリファクタリングするスキルです。

When to Use

「/ssot-refactor」と指示された時
「spec loaderが使われてるかチェックして」と言われた時
「specをロードしてないファイルを探して」と言われた時
新機能実装後のspec loader導入確認時
リファクタリング対象の洗い出し時

実行フロー概要

Phase 1: スキャン → prompts/01-scan.md
    ↓
Phase 2: 分析 → prompts/02-analyze.md
    ↓
Phase 3: リファクタ → prompts/03-refactor.md
    ↓
Phase 4: 検証 → prompts/04-verify.md
    ↓
完成

途中再開

「Phase 2から再開」のように指定可能。

Phase 1: スキャン

参照: prompts/01-scan.md

実装ファイルでspec loaderを使っていないファイルを検出
テストファイルでspec loaderを使っていないファイルを検出
未導入ファイル一覧を作成
次フェーズへ自動遷移

検出対象:

app/routes/ 配下で loadSpec をimportしていないファイル
app/components/ 配下で spec を使うべきなのに使っていないファイル
tests/ 配下で tests/utils/loadSpec を使っていないファイル

Phase 2: 分析

参照: prompts/02-analyze.md

各ファイルでどのspecを使うべきか特定
ハードコードされている値を洗い出し
リファクタリング対象を優先度付け
次フェーズへ自動遷移

分析観点:

どのサービス/セクションに属するか（blog/posts, account/authentication等）
ハードコードされているリテラル値
spec loaderで置き換え可能な箇所

除外するハードコード:

data-testid="..." の文字列リテラル（ui_selectors 廃止済みのため対象外）
aria-labelledby="..." / id="..." のアクセシビリティ属性値

Phase 3: リファクタ

参照: prompts/03-refactor.md

spec loader の import を追加
ハードコード値をspec参照に置換
型定義を追加（必要な場合）
次フェーズへ自動遷移

Phase 4: 検証

参照: prompts/04-verify.md

npm run typecheck 実行
npm test 実行
spec loader導入率の再計測
完了報告

チェックポイント

#	項目	確認内容
1	実装のspec loader	`app/routes/`で`loadSpec`を使っているか
2	テストのspec loader	`tests/`で`tests/utils/loadSpec`を使っているか
3	正しいローダー	サーバー側とテスト側で適切なローダーを使い分けているか
4	型定義	spec用の型をimportしているか
5	ハードコード	リテラル値がspec参照に置き換えられているか

Spec Loader の使い分け

場所	使用するローダー	import文
Route loader/action	`specLoader.server`	`import { loadSpec } from '~/spec-loader/specLoader.server'`
lib層	`specLoader.server`	`import { loadSpec } from '~/spec-loader/specLoader.server'`
Vitest	`loadSpec.ts`	`import { loadSpec } from 'tests/utils/loadSpec'`
Playwright E2E	`loadSpec.ts`	`import { loadSpec } from 'tests/utils/loadSpec'`

Specファイルの対応表

サービス	セクション	specファイル
blog	posts	`blog/posts-spec.yaml`
blog	post-detail	`blog/post-detail-spec.yaml`
blog	landing	`blog/landing-spec.yaml`
blog	common	`blog/common-spec.yaml`
account	authentication	`account/authentication-spec.yaml`
account	profile	`account/profile-spec.yaml`
account	subscription	`account/subscription-spec.yaml`
shared	project	`shared/project-spec.yaml`
shared	validation	`shared/validation-spec.yaml`

成果物

フェーズ	成果物
Phase 1	spec loader未導入ファイル一覧
Phase 2	リファクタリング計画（優先度付き）
Phase 3	修正済みファイル
Phase 4	導入率レポート

参照ドキュメント

ファイル	役割
`prompts/*.md`	各フェーズの金型
`docs/adoption-patterns.md`	導入パターン一覧と修正例
`.claude/rules/ssot/spec-loader.md`	SsoTルール定義
`app/spec-loader/specLoader.server.ts`	サーバー側ローダー実装
`tests/utils/loadSpec.ts`	テスト側ローダー実装

SSoT対象外（ハードコードが正しい値）

以下の値は 意図的にハードコード されており、spec化してはならない。

値の種類	理由
`data-testid` 属性値	`ui_selectors` は廃止済み。コンポーネント・テストに直接文字列で記述する
`aria-labelledby` / `id`（モーダル等）	アクセシビリティ用ハードコード識別子。spec管理不要

`extractTestId` / `ui_selectors` の廃止について

app/lib/blog/common/extractTestId.ts は削除済み（Phase 0 対応）
全 spec YAML から ui_selectors: セクションは削除済み
data-testid 値は各 .tsx / .test.tsx / .spec.ts に直接ハードコード済み

スキャン時にこれらをリファクタ対象と誤検出しないこと。

注意事項

全フェーズを自動実行 - スキャン→分析→リファクタ→検証を一気通貫で処理
既存のロジックは維持 - spec loader導入のみ、機能変更はしない
複雑性が増す場合は相談 - コードが著しく複雑になる場合はオペレータに確認
data-testid はSSoT化しない - ハードコードが正しい状態。誤って spec 化しないこと

ssot-refactor