開発チームがCursorルールを設定して複数リポジトリでアーキテクチャパターンとコーディング規約を統一する方法

開発チームがCursorを活用して組織横断的にアーキテクチャパターンとコーディング規約を徹底する最適なアプローチは、単一の旧式 .cursorrules ファイルからモジュール化されたプロジェクトルール（.cursor/rules/*.mdc）へ移行し、YAMLフロントマターを用いてグローバルな不変条件とファイルパス（Glob）に連動した境界を分離定義した上で、Cursor Team RulesやCI/CD同期パイプラインを通じて複数リポジトリへ展開・ガバナンスすることです。

組織規模でAIコーディングアシスタントを導入する際、適切なルール設計を怠ると「AIによるアーキテクチャのドリフト」が急速に進行します。開発者ごとに生成コードのパラダイムが分裂し、モデルが廃止済みの社内パッケージを補完したり、レイヤードアーキテクチャを無視してUIからデータベースを直接参照したりする事故が頻発します。構造化され、Gitでバージョン管理されたCursorルールを導入することで、モデルのコンテキストトークン消費を抑えつつ、AIコード生成に確実な決定性と整合性をもたらすことができます。

チーム開発におけるAIガバナンスの課題

中央集権的なガードレールなしにCursorを導入した場合、LLMは組織固有の設計コンテキストを把握していないため、パブリックな汎用学習データに基づいてコードを生成します。その結果、以下のような深刻なチーム摩擦が生じます。

• レイヤー境界の破壊： フロントエンドのUIコンポーネント内にデータベースクエリを直接埋め込んだり、ドメインサービス層にExpressやFastify固有のリクエストオブジェクトを渡したりするなど、設計原則に反するコードが生成されます。
• 廃止済みパッケージや存在しない依存の混入： 社内で非推奨となった旧ライブラリ（例：@company/design-system-v2 ではなく旧式の @company/legacy-ui）をモデルが推測してimportしたり、未承認のサードパーティ製ライブラリを勝手に導入したりします。
• コーディングスタイルの分裂： 関数型とオブジェクト指向の混在、例外処理やログ形式の不統一、状態管理ライブラリの重複など、開発者ごとに生成される実装スタイルが乖離します。
• テストコード品質のばらつき： 境界条件や異常系の検証が省略されたり、古いモックライブラリが使われたりするなど、保守性の低いテストコードが量産されます。

これらの課題を解決するには、テックリードが組織の規約を永続的かつコードベースと同期可能な形式でAIエージェントに提示する必要があります。

Cursorルール構造の変遷：.cursorrules からモジュール型 .mdc へ

初期のCursorでは、リポジトリルートに配置された単一の .cursorrules ファイルが利用されていました。後方互換性は維持されているものの、単一の巨大ファイルはすべてのやり取りで全ルールをモデルに読み込ませるため、プロンプトのコンテキストウィンドウを圧迫し、指示の精度低下を招く問題がありました。

最新のCursorでは、.cursor/rules/ ディレクトリ配下にYAMLフロントマターを持つ .mdc（Markdown Cursor） ファイルを配置する「プロジェクトルール」方式が標準となっています。

.mdc ファイルの基本構造

各 .mdc ファイルは、上部のYAMLメタデータと下部のMarkdown指示文で構成されます。

---
description: ドメインサービス層の境界およびリポジトリパターンの制約
globs: src/domains/**/*.ts, src/services/**/*.ts
alwaysApply: false
---

# ドメイン層アーキテクチャ規範

- ドメインサービス内で生のHTTPリクエストオブジェクトを直接参照してはならない。
- すべてのデータ永続化処理はリポジトリインターフェースを介して実行すること。

フロントマターの適用トリガー

YAMLフロントマターの設定によって、ルールがいつコンテキストに注入されるかが制御されます。

アーキテクト向け本番用ルール設計ブループリント

堅牢なチーム開発体制を築くためには、責務ごとに独立した .mdc ファイルを設計します。以下に実務で即座に機能する3つの設計例を示します。

1. リポジトリ全体の基盤規約 (.cursor/rules/00-core-architecture.mdc)

リポジトリ全体に常に適用される最上位のルールです。

---
description: リポジトリ全体のアーキテクチャ基線、技術スタック、禁止パッケージ一覧
alwaysApply: true
---

# コアアーキテクチャ規約

## 技術スタックとバージョン基線
- Node.js ランタイム: v20 LTS
- TypeScript: v5.4+（`strict: true` 必須）
- フレームワーク: Next.js App Router (v14+)
- 状態管理: Zustand（Redux や MobX の導入は禁止）

## 禁止ライブラリとパターン
- 禁止: `axios`（`@lib/api-client` にラップされた標準 `fetch` を使用）
- 禁止: `@company/ui-core-v1`（廃止済み。`@company/design-system-v2` を使用）
- 禁止: `moment.js`（`date-fns` に統一）

## コード品質基準
- 明示的な `any` の使用は厳禁。動的型付けには `unknown` と型ガードを使用すること。
- ガード節（early return）を徹底し、3階層以上のネストした `if/else` を避けること。
- シークレット、APIキー、環境認証情報をコード内にハードコードしてはならない。

2. バックエンドドメイン層の設計規約 (.cursor/rules/backend-services.mdc)

バックエンドのビジネスロジックを編集する際のみ自動で読み込まれます。

---
description: バックエンドサービスのオニオン/ヘキサゴナルアーキテクチャ制約
globs: src/services/**/*.ts, src/domains/**/*.ts
alwaysApply: false
---

# バックエンドドメイン層アーキテクチャ

## レイヤーの責務分離
- コントローラーはHTTPリクエストの検証とレスポンスのシリアライズのみを担当する。
- サービスは純粋なドメインロジックを実装する。Express や Fastify の `req`/`res` オブジェクトをサービス層に持ち込んではならない。
- リポジトリは永続化処理をカプセル化する。サービスはリポジトリの抽象インターフェースに依存し、具象ORMインスタンスに直接依存してはならない。

## 実装例（良い例と禁止例）

```typescript
// ✅ 推奨: サービスは抽象リポジトリインターフェースに依存し純粋エンティティを扱う
export class OrderService {
  constructor(private readonly orderRepository: OrderRepositoryPort) {}

  async processOrder(orderId: string): Promise<Result<Order>> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) return Result.fail('Order not found');
    order.markPaid();
    await this.orderRepository.save(order);
    return Result.ok(order);
  }
}

// ❌ 禁止: ビジネスロジック内でORMインスタンスを直接操作しSQLを発行する
export class OrderService {
  async processOrder(orderId: string) {
    await prisma.orders.update({ where: { id: orderId }, data: { status: 'PAID' } });
  }
}

### 3. 単体・結合テストの規約 (`.cursor/rules/testing-standards.mdc`)

AIが生成するテストコードのフレームワークと書き方を統一します。

```markdown
---
description: 単体テストおよび結合テストの作成標準と検証要件
globs: **/*.test.ts, **/*.spec.ts, src/tests/**/*
alwaysApply: false
---

# テスト自動化規約

## テストスタック
- テストランナー: Vitest
- モックライブラリ: `vi.mock()`（Jest ランナーの混入禁止）
- アサーション: 明示的なマッチャーを備えた `expect()`

## テスト設計ガイドライン
- Arrange-Act-Assert（準備・実行・検証）の3ステップ構造を厳守すること。
- 単体テストは実装ファイルと同階層に配置すること（例: `feature.service.ts` に対し `feature.service.test.ts`）。
- 単体テストで実際の外部ネットワークやDBに接続してはならない。境界で必ずモック化すること。
- 境界値のバリデーションや例外スローなどの異常系テストケースを必ず含めること。

複数リポジトリへのスケール戦略：モノレポとポリレポの比較

単一リポジトリでの管理に加え、エンタープライズ組織では数十〜数百のリポジトリに対してルールを一元管理・同期する必要があります。

                         全社的ルールガバナンス
                                  │
         ┌────────────────────────┴────────────────────────┐
         ▼                                                 ▼
   モノレポ構成 (Monorepo)                         ポリレポ構成 (Polyrepo)
  ├── .cursor/rules/00-core.mdc                  ├── ルール集中リポジトリ: org-cursor-rules
  ├── .cursor/rules/apps-web.mdc (Glob指定)       ├── CI/CD 同期・ドリフト検知パイプライン
  └── .cursor/rules/shared-ui.mdc (Glob指定)      └── Cursor Team Rules（管理画面での集中配布）

戦略1: モノレポにおける階層型Globスコープ

Turborepoやpnpmワークスペースなどのモノレポでは、ルートの .cursor/rules/ に全ルールを配置し、Globパターンによって適用範囲を限定します。

• globs: ["apps/web/**/*"]: WebフロントエンドのNext.js規約、Tailwindクラス利用規約を適用。
• globs: ["apps/api/**/*"]: バックエンドAPIのOpenAPI規約、マイグレーションルールを適用。
• globs: ["packages/ui/**/*"]: 共有UIコンポーネントの後方互換性、アクセシビリティ（ARIA）規約を適用。
• 効果： フロントエンド作業時にバックエンド用DBのルールが読み込まれず、プロンプトの混信を防ぐことができます。

戦略2: ポリレポ向けのCI/CD同期（Rules as Code）

独立したリポジトリ群に対しては、Cursorルールを共有ライブラリと同様にバージョン管理します。

1. 中央リポジトリの設置： 正本となる .mdc ルールを管理する専用Gitリポジトリ（例：org-cursor-rules）を作成し、セマンティックバージョニング（例：v1.2.0）を付与します。
2. CIによる整合性検証： 各サービスリポジトリのCIパイプラインで、ローカルの .cursor/rules/ が中央リポジトリと一致しているかを自動検証します。
3. 自動同期PRの生成： 中央リポジトリのルール更新をトリガーに、GitHub Actions等のスクリプトを通じて各リポジトリへ更新Pull Requestを自動作成します。

戦略3: Cursor Team Rulesによる中央管理

CursorのTeamプランまたはEnterpriseプランを利用している組織では、クラウドダッシュボードから直接全社ルールを配布できます。

• 管理画面での一括設定： 組織管理者がダッシュボード上で共通ルールを登録すると、全メンバーのCursorクライアントへ即時反映されます。
• 強制（Enforced）と任意（Optional）の分離： セキュリティ、ライセンス、基本スタックなど必須の制約を「Enforced」に指定することで、開発者がローカルで無効化することを防ぎます。
• セットアップコストの削減： 各マイクロサービスリポジトリに同一のルールファイルを個別コミットする手間を大幅に削減できます。

アンチパターンと運用のベストプラクティス

Cursorルールをモジュール化された .mdc ファイル群として設計し、Globによるスコープ分離とCI/CDやTeam Rulesによる集中同期を組み合わせることで、開発組織はAI支援による開発速度向上とアーキテクチャの厳格な規律を両立させることができます。

参考文献

• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI