ファイル・フォルダ構成と役割

実装を進めるときの地図。2026-09-01 時点の実態を記録し、未着手のものは「予定」として区別している。

構成そのものの規約は CLAUDE.md §9.1 が正。この文書は各ディレクトリが何を担うかと 依存の向きを補足するもの。両者が食い違ったら CLAUDE.md に従い、この文書を直す。

1. 依存の向き（最重要）

app/  (画面・APIルート)
  │  呼ぶ
  ▼
lib/db  lib/logger  lib/settings        ← 非純粋層（I/O・副作用あり）
  │  呼ぶ
  ▼
lib/judge  lib/config  lib/format       ← 純粋層（副作用なし・テストで固定）

下の層が上の層を import してはいけない。 特に:

• lib/judge/ は lib/logger/ を import しない（CLAUDE.md §9.4 の純粋関数規約）
• 判定結果のログは、判定関数の中ではなく呼び出し側（APIルート）で記録する
• lib/judge/ は USE_FIXTURES の切替の外側。fixtures でも本番でも同じロジックが走る

2. ルート直下

※ d-watch-api.yaml の info.description は却下済みの Laravel 構成（D-001）の記述を 現行構成（Next.js の API ルート、D-046）に書き直し済み。servers.url も /api/v1 という 実態と異なる記載になっていたため /api（app/api/clean-logs 等の実ルートと一致）に修正済み （D-050）。securitySchemes も cookie 方式（type: apiKey / in: cookie / name: dwatch_session）へ 書き換え済み（指示書I 段階0 / D-101）。bearerAuth と Laravel Sanctum への言及は残っていない。 401（未認証）/ 403（IP拒否）を components/responses に定義し、/auth/login は security: [] で 認証不要にしてある。

3. app/ — 画面とAPI

画面

画面は (dashboard) ルートグループの中に置く。 ログイン画面だけはシェルを出さないため外に置く。

APIルート

全APIルートの共通形:

export async function GET(request: Request) {
  return withRequestId(request, async () => {
    // ... 本体
    // catch 節では logApiError() を呼ぶ（console.error は禁止）
  });
}

.cursorrules にあった app/api/v1/ という記載は実態と異なる（v1 は無い）。 ログの route フィールドにも実際のパスを入れること。

4. lib/ — ロジック層

純粋層（副作用なし。テストで固定する）

非純粋層（I/O・副作用あり）

lib/logger/ の内訳

5. components/

判定結果（◎○△×、L1〜L3、ソート順）はAPIから受け取る。フロントで再計算しない。

6. docs/

7. 触ってはいけないもの

8. 未確定（決まり次第この文書を更新する）