thinkyou0714 Purpose
「コードが増えるにつれてどこに何があるかわからなくなる」を防ぐ。 ファイル配置・命名・依存方向が設計原則と整合しているかを定期的に確認し、 構造的な技術的負債の蓄積を防ぐ。
Use When
- 新機能追加・リファクタリングの前後にリポジトリ構造を確認したい場合
- 「このファイルはどこに置くべきか」の判断基準を整理したい場合
- チームや施工AIに構造のルールを伝えたい場合
- 構造の乱れが保守コストに影響し始めたと感じた場合
Inputs
以下を準備すること。不足している場合は推測せず、不足を明示する。
- レビュー対象: 確認したいディレクトリ・ファイル群（または全体）
- 設計原則・規約: 現在のプロジェクトの構造ルール（あれば）
- 技術スタック: フレームワーク（Next.js App Router 等）・言語
- 最近の変更: 直近で追加・変更したファイルの概要
- 懸念点: 「ここがおかしい気がする」という観察（任意）
Output Contract
以下の順で出力すること。順序を変えない。
- 論点: このリポジトリ構造の問題を左右する核心的な判断軸
- 根拠: その論点をそう判断した理由
- 構造レビュー結果: カテゴリ別の評価
- 含意: 現在の構造が示す設計上の健全性・リスク
- 改善案: 最小変更で構造を改善するための具体的な手順
- 代替案: 大規模な再構成が必要な場合の段階的アプローチ
- 判断材料: 「今すぐ修正 / 次フェーズで修正 / 現状維持」を選ぶための情報
構造レビュー結果 フォーマット
| カテゴリ | 状態 | 問題点・推奨 |
|---|---|---|
| ディレクトリ構造の一貫性 | OK / 注意 / NG | |
| ファイル命名規則の統一性 | OK / 注意 / NG | |
| 依存方向（循環依存・逆依存） | OK / 注意 / NG | |
| コロケーション原則（関連ファイルの近接配置） | OK / 注意 / NG | |
| フレームワーク規約への準拠（App Router 等） | OK / 注意 / NG | |
| テストファイルの配置 | OK / 注意 / NG | |
| 設定ファイル・環境変数の管理 | OK / 注意 / NG | |
| 不要・重複ファイルの存在 | OK / 注意 / NG |
Review Lens
- 目的妥当性: レビュー観点が保守コストに直結しているか
- 範囲の過不足: フレームワーク固有の規約を見落としていないか
- 中長期リスク: 現在の構造が機能追加時に複雑度を急増させないか
- LAB全体との整合性: Next.js App Router の規約・Supabase のファイル配置と整合しているか
- 非エンジニア理解可能性: 構造の問題と改善案を非技術者に説明できるか
- 他LLM移植耐性: 評価基準が Claude 固有の解釈に依存していないか
Instructions
- フレームワーク（Next.js App Router 等）の標準構造と比較する
- ディレクトリごとに「何を置くべきか」の責務を確認する
- 命名規則（camelCase / kebab-case / PascalCase）の統一性を確認する
- 循環依存・想定外の依存方向がないかを確認する
- 問題箇所を「高影響（今すぐ修正）/ 中影響（次フェーズで）/ 低影響（記録のみ）」に分類する
- 改善案は実際のファイル移動・リネーム手順を含める
- 最終判断は人間に委ねる
Guardrails
- 「気になるから全部整理したい」という過剰なリファクタリングを推奨しない
- 現在動いているコードを不必要に動かすことを避ける
- フレームワーク規約がある場合はそれを優先する（独自ルールで上書きしない）
- 構造変更がテストや CI に影響する場合は必ず指摘する
- 改善提案は現在の実装フェーズに照らして優先度をつける
LAB Cross-Check
| 観点 | 状態 | 備考 |
|---|---|---|
| 自動化フロー | — | n8n / スクリプト配置が設計原則に沿っているか |
| データ / 認証 / ログ | — | Supabase クライアント・認証ファイルの配置が適切か |
| 実装 / 運用フロー | — | デプロイ設定・環境変数ファイルの配置が適切か |
| 非エンジニア理解可能性 | — | 構造の説明を非技術者にできるか |
| 会員共有 / 再利用耐性 | — | レビュー観点が他プロジェクトにも転用できるか |
| 他LLM移植耐性 | — | 評価基準が Claude 固有に依存していないか |
状態は OK / 注意 / NG / 対象外 で記入すること。
Handoff Notes
- 要件: 修正すべき構造上の問題と推奨する配置の定義
- 成功条件: フレームワーク規約と設計原則に沿った構造が維持されている
- 失敗条件: 循環依存・命名不一致・責務不明ファイルが増加している
- 実行範囲: 移動・リネームしてよいファイル・ディレクトリ
- 影響範囲: ファイル移動に伴うインポートパス変更が必要な箇所
- ロールバック方針: ファイル移動前に git でスナップショットを取り、revert で戻す
- コスト比較: 今修正するコスト vs 構造崩れが蓄積した後に修正するコスト
Further Reading
change-impact-scanskill — ファイル移動の影響範囲確認implementation-gateskill — 実装着手前の全体チェック- docs/CONTEXT.md — 技術スタック・ディレクトリ構造
- docs/DECISIONS.md — 構造に関する設計決定記録（ADR）