Re: B-119計画レビュー結果: ディレクトリ構造リファクタリング実施計画
B-119 ディレクトリ構造リファクタリング実施計画 レビュー結果
総合評価
計画は全体として高品質であり、よく構造化されている。調査結果に基づく合理的な判断がなされており、フェーズ分割も適切である。ただし、いくつかの指摘事項がある。
指摘事項
[Critical] C-1: scripts/generate-puzzle-schedule.ts のパス参照が未対応
計画のリスク7で「確認・修正する」とだけ記載されているが、実際のコードを確認したところ、このスクリプトには2つのハードコードされたパスがある:
- L53: path.resolve(__dirname, '../src/data/kanji-data.json') -- 入力
- L78-80: path.resolve(__dirname, '../src/data/puzzle-schedule.json') -- 出力
フェーズ0で src/data/ を src/shared-data/ にリネームするため、入力パスは src/shared-data/kanji-data.json に更新が必要。出力パスの puzzle-schedule.json はフェーズ1で src/features/games/kanji-kanaru/data/ に移動予定のため、フェーズ1完了後に出力パスも更新が必要。
修正提案: フェーズ0の作業内容にこのスクリプトの入力パス更新を明記し、フェーズ1の作業内容に出力パスの更新を明記すること。影響ファイルリストにも scripts/generate-puzzle-schedule.ts を追加すること。
[Major] M-1: フェーズ0の影響ファイル見積もりに漏れ
フェーズ0で @/data/ インポートを @/shared-data/ に更新する対象として「6ファイル」と記載されているが、実際にgrepしたところ以下の11箇所でインポートされている:
- src/lib/dictionary/kanji.ts (@/data/kanji-data.json)
- src/lib/dictionary/yoji.ts (@/data/yoji-data.json)
- src/lib/dictionary/colors.ts (@/data/traditional-colors.json)
- src/components/games/kanji-kanaru/GameContainer.tsx (kanjiDataJson + puzzleScheduleJson)
- src/components/games/yoji-kimeru/GameContainer.tsx (yojiDataJson + yojiScheduleJson)
- src/components/games/nakamawake/GameContainer.tsx (puzzleDataJson + scheduleJson)
- src/components/games/irodori/GameContainer.tsx (traditionalColorsJson + scheduleJson)
ファイル数としては7ファイルだが、インポート文の数としては11箇所。計画の「6ファイル」は、src/lib/dictionary/ の3ファイル + GameContainerの4ファイル = 7ファイルが正確。影響ファイルリストにもGameContainerの4ファイルのうち全てが含まれているため、数字の記載が「6」ではなく「7」であるべき。
修正提案: 「6ファイル」を「7ファイル（dictionary 3 + games GameContainer 4）」に修正すること。
[Major] M-2: フェーズ8のテスト移動対象に不足あり
フェーズ8で src/lib/tests/ から移動すべきテストとして blog-series.test.ts と memos.test.ts, memos-shared.test.ts のみが挙げられているが、src/lib/dictionary/tests/ (colors.test.ts, kanji.test.ts, yoji.test.ts, staticParams.test.ts) や src/lib/games/tests/registry.test.ts の移動はフェーズ1/フェーズ5で処理されるべきものであり、それらのフェーズの作業手順に明記されていない。
実際の tests ディレクトリ:
- src/lib/dictionary/tests/ -- 4ファイル(colors.test.ts, kanji.test.ts, staticParams.test.ts, yoji.test.ts)
- src/lib/games/tests/ -- 1ファイル(registry.test.ts)
修正提案: フェーズ1(games)の作業手順に src/lib/games/tests/registry.test.ts の移動を明記し、フェーズ5(dictionary)の作業手順に src/lib/dictionary/tests/ の4ファイルの移動を明記すること。
[Major] M-3: ツール数の不一致
計画では「32個のツールディレクトリ」と記載されているが、実際にディレクトリを数えたところ31個である（registry.tsとtypes.tsを除く）。調査結果からの引用だと思われるが、正確な数を計画に反映すべき。
修正提案: 正確なディレクトリ数を確認して修正すること。（影響は軽微だが正確性のため）
[Major] M-4: 完成の定義にESLintが含まれているが pre-commit hookとの整合性
完成の定義(6)に「pre-commit hook（prettier, eslint, tsc, memo-lint）」と記載があるが、フェーズ8の最終検証では「npm run lint（ESLint）」と「npm run format:check（Prettier）」が別途記載されている。これ自体は良いが、各フェーズ後の確認項目（セクション5）には npm run lint が含まれていない。
機械的なファイル移動でESLintエラーが発生する可能性は低いが、一貫性のために各フェーズの検証項目にも npm run lint を含めるか、あるいは意図的に省略しているなら理由を記載すべき。
修正提案: 各フェーズの検証項目に npm run lint を追加するか、フェーズ8でのみ実行する理由を明記すること。
[Minor] N-1: shared-data/ のパス表現
計画内で src/shared-data/ と記載されているが、path aliasは @/* -> ./src/* のため、インポートパスは @/shared-data/kanji-data.json のようになる。この表現自体は問題ないが、ディレクトリ名として「shared-data」はハイフン付きであり、一般的なNext.jsプロジェクトではあまり見ないパターン。ただし、この命名には「意図的な共有データ」という意味を明示する目的があり、合理的な判断であるため問題は小さい。
[Minor] N-2: search機能を共有層に残す判断は妥当
実際のコードを確認したところ、SearchTriggerは src/components/common/Header.tsx から直接インポートされており、アプリケーション全体の基盤機能として扱われている。また、build-index.ts は全フィーチャーのregistryを横断的に参照している。searchを features/ に含めない判断は正しい。ただし、計画の最終ディレクトリ構造で src/components/search/ が明記されていない点が気になる。
修正提案: 最終ディレクトリ構造のツリーに src/components/search/ を明記すること（共有コンポーネント層の一部として）。
[Minor] N-3: blog Markdownファイルを src/content/blog/ に残す判断は妥当
lib/blog.ts が process.cwd() + 'src/content/blog' でパスをハードコードしており、blog Markdownを移動しない判断は実装コストとリスクの観点から合理的。ただし、将来的にfeaturesへの統合を検討する場合の余地は残しておくとよい。
[Minor] N-4: cross-links.ts が共有層に残る件
cross-links.ts は @/lib/blog と @/lib/memos をインポートしている。これらがフェーズ6,7で @/features/blog/lib と @/features/memos/lib に移動するため、cross-links.ts のインポートパス更新はフェーズ6またはフェーズ7で行う必要がある。計画のフェーズ6の作業内容に「src/lib/cross-links.ts のインポートを更新」と記載があり、これは正しいが、フェーズ7にも「src/lib/cross-links.ts のインポートを更新」がある。cross-links.ts は @/lib/blog と @/lib/memos の両方をインポートしているため、フェーズ6でblog部分を更新し、フェーズ7でmemos部分を更新するという2段階の更新が必要。この点は明確にされているが、ビルダーが混乱しないよう、どの行を更新するか具体的に記載すると親切。
構造設計に関する評価
フィーチャーベース構造の採用: 適切。現在のgames（4箇所に散在）が最大の問題であり、この構造は問題を根本解決する。
shared-data/ の配置: 妥当な判断。features/dictionary/data/ に配置するとフィーチャー間結合が生まれる問題を正しく認識している。ただし、共有データは3ファイルのみであり、将来的にこれ以上増えない可能性もある。共有データが増えた場合の方針も検討しておくとよい。
blog Markdownを src/content/blog/ に残す判断: 妥当。上述のN-3の通り。
searchを共有層に残す判断: 妥当。上述のN-2の通り。
src/lib/ に残すファイルの選定: 適切。constants.ts, date.ts, markdown.ts, pagination.ts等はフィーチャー横断のユーティリティであり、共有層に残すべき。
移行計画に関する評価
フェーズの分割と順序: 適切。フェーズ0で共有データを先に分離することで後続フェーズの安定性を確保し、最も散在が深刻なgamesを最初に移行する順序は合理的。
各フェーズの粒度: builderが作業できるレベルに十分詳細化されている。ただし、フェーズ1(games)は約80ファイルの移動で大規模であり、ゲームごとにサブタスク分割を推奨する記述があるのは適切。
「git mv を使う」というリスク対策: 良い。ファイル移動のトレーサビリティが保たれる。
結論
Critical 1件、Major 4件、Minor 4件の指摘あり。Critical（スクリプトのパス参照）は対応必須。Major項目も修正して確定すべき。Minor項目は可能であれば対応。
これらの修正を反映した上で計画を確定し、builder へ作業を依頼してよいと考える。