Cursor Project Rulesでコーディング規約を自動化｜カスタムルール設定・チーム品質向上

【Project Rules が強い理由】

✅ チーム全員が同じルールを使える
→ `.cursor/rules/*.mdc` をGitにコミットすれば全員に自動適用

✅ ファイルシンボルを使ってプロジェクト内のファイルを参照できる
→ 「@PULL_REQUEST_TEMPLATE.md を読んでPRを作成してください」が可能

✅ 4タイプの発動条件で「いつルールを参照するか」を細かく制御できる
→ `*.test.ts` ファイルだけにテストルールを適用、など

✅ ルールを複数ファイルに分割して管理できる
→ frontend-rules.mdc / backend-rules.mdc / test-rules.mdc など

【Auto Attached の設定例】

テストファイル専用ルール：
  Globs: **/*.test.ts, **/*.spec.ts
  → テストファイルを開いたときだけ「Vitest形式で書く・AAA構造で書く」を適用

CSSファイル専用ルール：
  Globs: **/*.css, **/*.scss
  → CSSファイルに対してのみ「BEM記法・CSS変数使用必須・モバイルファースト」を適用

WordPressテンプレート専用ルール：
  Globs: **/templates/**/*.php, **/template-parts/**/*.php
  → PHPテンプレートファイルに「esc_html / wp_kses_post の使用必須・nonce 検証」を適用

【Agent Requested の推奨ケース】

✅ 特定のドメイン知識が必要なルール（DBの命名規則・インデックス設計方針）
✅ ある程度頻度は低いが、使うときには必ず参照してほしいルール
✅ セキュリティに関するルール（SQL インジェクション対策・入力値検証ルール）
✅ Docker環境・環境依存のコマンド実行ルール

Description 例：「データベース設計・マイグレーション・スキーマ変更について質問・作業するときに参照する」

// 保存場所
.cursor/
  └─ rules/
       ├─ coding-standards.mdc    // Always：全体コーディングルール
       ├─ frontend-rules.mdc      // Auto Attached：*.tsx, *.ts
       ├─ test-rules.mdc          // Auto Attached：*.test.ts
       ├─ database-rules.mdc      // Agent Requested
       └─ create-pullrequest.mdc  // Manual

// ✅ .cursor/rules/ ディレクトリをGitにコミットすることで
//    チームメンバー全員に同じルールが自動適用される

【/Generate Cursor Rules の活用パターン】

パターン1：対話後にルール化する
→ AI との実装のやり取りが終わった後に
  「この会話をProject Rulesにまとめてください」
→ 今回の実装方針・スタイルガイドがルールとして保存される

パターン2：最初にルールを作成してから開発を始める
→ 新規プロジェクト開始時に
  「React + TypeScript + Tailwind を使ったフロントエンドプロジェクトのProject Rulesを作成してください」
  「ディレクトリ構造はfeatures/コンポーネント設計はAtomicDesignです」
→ プロジェクトのルールセットが一気に生成される

パターン3：既存のREADMEやESLint設定からルール化する
→ 「@eslint.config.js @README.md の内容を参考にProject Rulesを作成してください」
→ 既存の設定ファイルからルールを自動抽出する

## フロントエンドコーディング規約

### 技術スタック
- 言語：TypeScript（strict: true）
- フレームワーク：React 18 + Next.js 14 (App Router)
- スタイリング：Tailwind CSS + CSS Variables
- 状態管理：Zustand（サーバー状態は TanStack Query）
- フォーム：React Hook Form + Zod

### 型の扱い
- `any` 型の使用禁止。不明な型は `unknown` を使う
- 型アサーション（`as`）の使用は最小限にし、型ガードを使う
- 関数の戻り値の型は明示的に定義する

### コンポーネント設計
- 1ファイル1コンポーネントを原則とする
- Props の型は `interface` で定義し、ファイル先頭に記述する
- コンポーネントはデフォルトエクスポートを使用する
- 300行を超えるコンポーネントは分割を検討する

### 命名規則
- コンポーネント：PascalCase（例：`UserProfileCard.tsx`）
- 関数・変数：camelCase（例：`getUserProfile`）
- 定数：SCREAMING_SNAKE_CASE（例：`MAX_RETRY_COUNT`）
- カスタムフック：`use` プレフィックス（例：`useUserProfile`）
- CSS クラス：Tailwind を基本とし、カスタムは BEM を使用する

### 禁止事項
- `console.log` の本番コードへの混入（デバッグ後は必ず削除）
- `useEffect` 内での直接 DOM 操作（Ref を使う）
- インラインスタイル（`style={{ color: 'red' }}`）の使用
- マジックナンバーの直書き（定数として切り出す）

## テストコード規約

### テストフレームワーク
- Vitest（単体・統合テスト）
- React Testing Library（コンポーネントテスト）
- Playwright（E2Eテスト）

### テスト構造（AAA パターン必須）
- Arrange（準備）→ Act（実行）→ Assert（検証）の順で記述する
- 各フェーズをコメントで明示すること

```typescript
it('ユーザー名が空のとき、エラーメッセージを表示する', () => {
  // Arrange
  const { getByRole, getByText } = render(<LoginForm />);
  const submitButton = getByRole('button', { name: '送信' });

  // Act
  fireEvent.click(submitButton);

  // Assert
  expect(getByText('ユーザー名を入力してください')).toBeInTheDocument();
});
```

### テストの命名規則
- `it('〜のとき、〜する')` の形式（日本語可）
- テスト対象の振る舞いが明確にわかる名前をつける
- NG：`it('test1')` / OK：`it('emailが無効な形式のとき、送信ボタンが無効になる')`

### モックの扱い
- `vi.mock()` を使ったモジュールモックは `describe` ブロック外に配置する
- モックデータはテストファイルの末尾にまとめて定義する
- `afterEach` で `vi.clearAllMocks()` を呼び出す

## WordPress テーマ開発規約

### セキュリティ（必須）
- 出力は必ずエスケープ関数を使用する
  - HTMLコンテキスト：`esc_html()` `esc_attr()` `wp_kses_post()`
  - URLコンテキスト：`esc_url()`
  - JSコンテキスト：`esc_js()`
- フォーム送信には必ず nonce を検証する
  `wp_verify_nonce()` で検証してから処理する
- 入力値は必ずサニタイズする
  - テキスト：`sanitize_text_field()`
  - メールアドレス：`sanitize_email()`
  - URL：`esc_url_raw()`

### テンプレート設計
- 共通パーツは `get_template_part()` を使う（コピペ禁止）
- カスタムフィールドは ACF を使い、`get_field()` で取得する
- ループ内では `have_posts()` / `the_post()` を使う

### アセット登録
- JavaScript は `wp_enqueue_script()` で登録する（直接 `<script>` タグ禁止）
- CSS は `wp_enqueue_style()` で登録する
- バージョンには `filemtime()` を使ってキャッシュバスティングを行う

```php
wp_enqueue_style(
  'theme-style',
  get_template_directory_uri() . '/assets/css/main.css',
  [],
  filemtime(get_template_directory() . '/assets/css/main.css')
);
```

## Docker 環境でのコマンド実行ルール

### 基本の実行コマンド
通常の npm コマンドは使用せず、必ず docker compose exec を経由して実行する。

```bash
# 開発サーバー起動
docker compose up -d

# Node.js コマンドの実行（npmの代わりに使う）
docker compose exec app npm run dev

# テスト実行
docker compose exec app npx vitest run

# 特定ファイルのテストのみ実行
docker compose exec app npx vitest run src/utils/formatter.test.ts

# 特定行のテストのみ実行（失敗箇所がわかっている場合）
docker compose exec app npx vitest run src/utils/formatter.test.ts:25
```

### データベース操作
```bash
# マイグレーション実行
docker compose exec app npx prisma migrate dev

# Prisma Studio（DB GUI）
docker compose exec app npx prisma studio
```

### コンテナ再起動
```bash
# 特定コンテナの再起動
docker compose restart app

# 全コンテナの停止・削除・再起動
docker compose down && docker compose up -d
```

## Pull Request 作成手順

### 必須前提条件
1. Issue 番号を確認する
   - Issue のリンクが提供されていない場合は「関連する Issue はありますか？」と必ず確認する
   - Issue が存在しない場合は PR の説明に明記する

### 差分の確認
- マージ先ブランチは特に指示がなければ `main` とする
- `git diff origin/main...HEAD | cat` で差分を確認してからPRを作成する

### Pull Request の作成
```bash
# ブランチのプッシュと PR 作成を1コマンドで実行
git push origin HEAD && \
echo -e "{{PRテンプレートを1行に変換}}" | \
gh pr create --draft --title "{{PRタイトル}}" --body-file - && \
gh pr view --web
```

### PR テンプレート
@PULL_REQUEST_TEMPLATE.md からテンプレート内容を取得すること

### タイトルの命名規則
- `feat: ユーザー認証機能の追加`（新機能）
- `fix: ログイン時のエラーハンドリング修正`（バグ修正）
- `refactor: UserService のロジック整理`（リファクタリング）
- `docs: API仕様書の更新`（ドキュメント）
- `test: ユーザー登録のテスト追加`（テスト）

【ルール設計の3つの原則】

1. Always に詰め込みすぎない
→ Always ルールが長すぎるとコンテキストウィンドウを圧迫する
→ 「絶対に必要なもの」だけを Always にして、それ以外は分割する

2. Auto Attached は Glob パターンを具体的に設定する
→ 「**/*.ts」だと広すぎる → 「**/*.test.ts」のように絞る
→ 複数のパターンを組み合わせる：「**/*.css, **/*.scss, **/*.module.css」

3. 1ルールファイルに1テーマ
→ 「frontend-rules.mdc」にWordPressルールを混在させない
→ 分割することでルール管理が容易になる（追加・削除・改訂しやすい）

// 推奨ディレクトリ構成
your-project/
├── .cursor/
│   └── rules/
│       ├── README.md          // ← ルールの説明書を作る
│       ├── coding-standards.mdc
│       ├── frontend-rules.mdc
│       ├── test-rules.mdc
│       └── create-pr.mdc
├── src/
└── ...

// チームへの周知コミットメッセージ例
git commit -m "feat: Cursor Project Rules を追加（コーディング規約・テストルール・PR自動作成）"

// ルールの先頭に追加するデバッグ行
まず、このファイルを参照したら、「RULE_LOADED: frontend-coding-standards」と出力してください。

// Chat / Composer で AI からこのメッセージが表示されれば
// ルールのコンテキストが正しく読み込まれている証拠

// 確認後はデバッグ行を削除して本番運用に移る

// ルール改善の質問テンプレート
@frontend-coding-standards.mdc のルールについて
わかりにくいところや、改善したほうがよいポイントはありますか？
特に「コンポーネント設計」セクションが意図通りに機能していません。

// AIが返してくれること
→ ルールの曖昧な表現の指摘
→ より具体的な書き方の提案
→ 追加すべきルールの提案
→ 矛盾するルールの検出