# Repo Structure Review

> リポジトリのディレクトリ構造・命名規則・ファイル配置が設計原則と整合しているかをレビューする。構造の崩れを早期に検出し、保守コストの増加を防ぐ。リポジトリ構造をレビューするときに使う。

- Skill: `thinkyou0714/repo-structure-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thinkyou0714/repo-structure-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thinkyou0714/repo-structure-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thinkyou0714 (https://skillmd.com/u/thinkyou0714)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thinkyou0714/repo-structure-review

---


## Purpose

「コードが増えるにつれてどこに何があるかわからなくなる」を防ぐ。
ファイル配置・命名・依存方向が設計原則と整合しているかを定期的に確認し、
構造的な技術的負債の蓄積を防ぐ。

## Use When

- 新機能追加・リファクタリングの前後にリポジトリ構造を確認したい場合
- 「このファイルはどこに置くべきか」の判断基準を整理したい場合
- チームや施工AIに構造のルールを伝えたい場合
- 構造の乱れが保守コストに影響し始めたと感じた場合

## Inputs

以下を準備すること。不足している場合は推測せず、不足を明示する。

- **レビュー対象**: 確認したいディレクトリ・ファイル群（または全体）
- **設計原則・規約**: 現在のプロジェクトの構造ルール（あれば）
- **技術スタック**: フレームワーク（Next.js App Router 等）・言語
- **最近の変更**: 直近で追加・変更したファイルの概要
- **懸念点**: 「ここがおかしい気がする」という観察（任意）

## Output Contract

以下の順で出力すること。順序を変えない。

1. **論点**: このリポジトリ構造の問題を左右する核心的な判断軸
2. **根拠**: その論点をそう判断した理由
3. **構造レビュー結果**: カテゴリ別の評価
4. **含意**: 現在の構造が示す設計上の健全性・リスク
5. **改善案**: 最小変更で構造を改善するための具体的な手順
6. **代替案**: 大規模な再構成が必要な場合の段階的アプローチ
7. **判断材料**: 「今すぐ修正 / 次フェーズで修正 / 現状維持」を選ぶための情報

### 構造レビュー結果 フォーマット

| カテゴリ | 状態 | 問題点・推奨 |
|---|---|---|
| ディレクトリ構造の一貫性 | 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

1. フレームワーク（Next.js App Router 等）の標準構造と比較する
2. ディレクトリごとに「何を置くべきか」の責務を確認する
3. 命名規則（camelCase / kebab-case / PascalCase）の統一性を確認する
4. 循環依存・想定外の依存方向がないかを確認する
5. 問題箇所を「高影響（今すぐ修正）/ 中影響（次フェーズで）/ 低影響（記録のみ）」に分類する
6. 改善案は実際のファイル移動・リネーム手順を含める
7. 最終判断は人間に委ねる

## Guardrails

- 「気になるから全部整理したい」という過剰なリファクタリングを推奨しない
- 現在動いているコードを不必要に動かすことを避ける
- フレームワーク規約がある場合はそれを優先する（独自ルールで上書きしない）
- 構造変更がテストや CI に影響する場合は必ず指摘する
- 改善提案は現在の実装フェーズに照らして優先度をつける

## LAB Cross-Check

| 観点 | 状態 | 備考 |
|---|---|---|
| 自動化フロー | — | n8n / スクリプト配置が設計原則に沿っているか |
| データ / 認証 / ログ | — | Supabase クライアント・認証ファイルの配置が適切か |
| 実装 / 運用フロー | — | デプロイ設定・環境変数ファイルの配置が適切か |
| 非エンジニア理解可能性 | — | 構造の説明を非技術者にできるか |
| 会員共有 / 再利用耐性 | — | レビュー観点が他プロジェクトにも転用できるか |
| 他LLM移植耐性 | — | 評価基準が Claude 固有に依存していないか |

状態は OK / 注意 / NG / 対象外 で記入すること。

## Handoff Notes

- **要件**: 修正すべき構造上の問題と推奨する配置の定義
- **成功条件**: フレームワーク規約と設計原則に沿った構造が維持されている
- **失敗条件**: 循環依存・命名不一致・責務不明ファイルが増加している
- **実行範囲**: 移動・リネームしてよいファイル・ディレクトリ
- **影響範囲**: ファイル移動に伴うインポートパス変更が必要な箇所
- **ロールバック方針**: ファイル移動前に git でスナップショットを取り、revert で戻す
- **コスト比較**: 今修正するコスト vs 構造崩れが蓄積した後に修正するコスト

## Further Reading

- `change-impact-scan` skill — ファイル移動の影響範囲確認
- `implementation-gate` skill — 実装着手前の全体チェック
- [docs/CONTEXT.md](../../../docs/CONTEXT.md) — 技術スタック・ディレクトリ構造
- [docs/DECISIONS.md](../../../docs/DECISIONS.md) — 構造に関する設計決定記録（ADR）