korori-web

Imported from yuuya-1205/korori-web (AGENTS.md). Install upstream with npx skills add yuuya-1205/korori-web. Copyright stays with the author.

AGENTS.md — korori-web

React + Vite + TypeScript の Web アプリケーション。

このファイルは、人間とエージェント（Claude Code 等）の両方に共通する開発規約を定める。 実装タスクに着手する前に必ず読むこと。

現状

リポジトリはまだスキャフォールドされていない（package.json 未作成）。 下記のコマンド・ディレクトリ構成は「これから作るときの目標形」であり、 最初のセットアップもこの構成に沿って行う。

スタック

コマンド

npm run dev          # 開発サーバー
npm test             # Vitest watch モード（TDD の主戦場）
npm run test:run     # 1 回だけ実行（CI / コミット前）
npm run test:cov     # カバレッジ付き
npm run typecheck    # tsc --noEmit
npm run lint         # ESLint（レイヤー境界チェックを含む）
npm run build        # 本番ビルド

開発の 2 原則

1. TDD（テスト駆動開発）

プロダクションコードは、それを失敗させるテストを書いてからでないと書かない。

Red → Green → Refactor のサイクルを小さく回す。 「テストを後で書く」は原則として認めない。テストを後に回すと、 テストしにくい設計（巨大な関数、隠れた依存、副作用の混在）がそのまま固定化されるため。

詳細な手順・アンチパターンは .claude/skills/tdd/SKILL.md を参照。

2. Clean Architecture

依存は常に内側（domain）へ向く。外側の都合が内側に漏れてはいけない。

presentation ─┐
              ├─→ application ─→ domain
infrastructure┘

domain は React も fetch も localStorage も知らない。 application はインターフェース（ポート）だけを知り、実装は知らない。

詳細なレイヤー定義・配置ルール・違反例は .claude/skills/clean-architecture/SKILL.md を参照。

ディレクトリ構成

src/
├── domain/                    # 業務ルールの中心。外部依存ゼロ
│   ├── entities/              # エンティティ（同一性を持つ）
│   ├── value-objects/         # 値オブジェクト（不変・等価性は値で判断）
│   ├── errors/                # ドメイン例外
│   └── repositories/          # リポジトリ「インターフェース」のみ
│
├── application/               # ユースケース（アプリ固有のルール）
│   ├── usecases/
│   └── ports/                 # 外部サービスのインターフェース
│
├── infrastructure/            # 外界との接続。domain/application の実装を提供
│   ├── http/                  # API クライアント
│   ├── repositories/          # domain/repositories の実装
│   └── storage/
│
├── presentation/              # React（UI）
│   ├── pages/
│   ├── components/
│   ├── hooks/
│   └── di/                    # 依存の配線（Composition Root）
│
└── shared/                    # 全レイヤーが依存してよい純粋ユーティリティのみ

テストは実装ファイルの隣に *.test.ts(x) として置く（コロケーション）。 E2E / 結合テストのみ tests/ 配下にまとめる。

コーディング規約

• 命名: ファイルは実装の主エクスポートに合わせる（OrderId.ts → OrderId）。 React コンポーネントは PascalCase、それ以外は camelCase。
• any 禁止。型が決まらない箇所は unknown + 絞り込みで書く。
• 例外よりも Result 型を優先（ドメインの想定内の失敗は戻り値で表現し、 想定外のバグのみ throw する）。呼び出し側が握りつぶす事故を型で防ぐため。
• 副作用は外側に押し出す。domain / application の関数は原則として純粋に保つ。
• コメントは「何を」ではなく「なぜ」を書く。

コミット

• Conventional Commits（feat: / fix: / refactor: / test: / chore:）。
• グリーン（全テストが通る状態）でのみコミットする。
• 1 コミット = 1 つの意味のある変更。リファクタと機能追加を混ぜない。

プルリクエスト前チェックリスト

npm run typecheck && npm run lint && npm run test:run

加えて自問すること:

• 新しい振る舞いに対して、先に失敗するテストを書いたか
• domain が React / fetch / ブラウザ API を import していないか
• ユースケースのテストが、本物の HTTP や localStorage に触れていないか
• テストが実装の詳細ではなく「振る舞い」を検証しているか