---
applyTo: "**/*"
---

# Repository Common Guardrails

## Scope

- Apply these rules across the repository for all agents.
- Enforce only the minimum rules required to preserve clean architecture.

## Dependency Direction

- Keep dependency flow from outer layers to inner layers.
- Do not import infrastructure implementations from domain or use-case layers.
- Introduce or use interfaces at boundaries when connecting inner logic to outer implementations.

## Layer Integrity

- Respect declared layer boundaries and dependency direction in existing architecture docs.
- Review imports in modified files to avoid accidental auto-import drift.

## Validation

- Validate changed behavior with targeted checks.
- Run architecture-related checks when dependency direction may have changed.

# クリーンアーキテクチャ

このプロジェクトでは、変更に強くテストが容易な設計を実現するためにクリーンアーキテクチャを採用しています。コード作業の際は本ドキュメントをガイドラインとしてご参照ください。

## 目次

---

## 1. 詳細ドキュメント

以下はこのドキュメントおよび関連ファイルの責務です。

| ファイル                                                  | 責務                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------- |
| `docs/reference/copilot/clean-architecture.md`            | 概要・原則・索引                                                    |
| `docs/reference/copilot/clean-architecture-migration.md`  | 実装例、移行手順、`migration-backlog.md` の運用ルール               |
| `docs/reference/copilot/clean-architecture-testing-ci.md` | テスト戦略、CI / lint スニペット、注意点                            |
| `docs/reference/copilot/migration-backlog.md`             | `migration-backlog.md` の運用ルール（作業時の一時ファイル作成手順） |
| `.github/copilot-instructions.md`                         | AI が実行時に参照する全体の実効ルール（Single Source of Truth）     |
| `.github/instructions/*.instructions.md`                  | パス単位の実効ルール（対象ファイル群ごとの行動制限）                |

## 2. AIガードレール総覧

このプロジェクトの AI ガードレールは、次の 2 層で運用します。

- 実効ルール（enforceable）: `.github/copilot-instructions.md` と `.github/instructions/*.instructions.md`
- 解説ルール（explanatory）: `docs/reference/copilot/*.md`

重要なのは、同じルール本文を両方へ重複記載しないことです。実効ルールの一次ソースは `.github` 側とし、`docs` 側は背景、判断基準、運用手順を説明します。

### 2.1 初期適用範囲（2026-02-20時点）

初期フェーズでは次を優先します。

- repo 共通ルール（依存方向保護、最小変更、検証必須）
- docs ルール（記述品質、リンク整備、SoT更新）

初期適用範囲と `.github/instructions` の対応は次のとおりです。

| 適用範囲  | 実効ルールファイル                                            |
| --------- | ------------------------------------------------------------- |
| repo 共通 | `.github/instructions/repo-common-guardrails.instructions.md` |
| docs      | `.github/instructions/docs-common-guardrails.instructions.md` |

backend / frontend / functions の個別ルールは、運用上の失敗事例が蓄積したタイミングで段階的に追加します。

### 2.2 変更フロー


-- 中略 --


## 7. 各層のつながり（依存方向）

このプロジェクトでは、依存方向を常に外側から内側へ保ちます。

```text
functions（最外部）
  -> infrastructure（外側実装）
    -> use-cases（アプリ手順）
      -> domain（最内部ルール）
```

重要なのは「実行時の呼び出し方向」と「コードの依存方向」を区別することです。

- 実行時の呼び出しは、外側から内側へ流れます（例: HTTP Trigger -> Use Case）。
- コードの依存も、同じく外側から内側へ向けます。
- `domain` / `use-cases` は `infrastructure` 実装を直接 `import` しません。
- 永続化や外部APIは、`domain` 側のインターフェースを `infrastructure` が実装して接続します。

### 接続イメージ

- `domain`: ルールとインターフェース（例: `IUserRepository`）を定義する
- `use-cases`: `domain` のインターフェースを受け取って業務フローを実行する
- `infrastructure`: `domain` のインターフェースを実装してDBや外部サービスへ接続する
- `functions`: エントリポイントで実装を組み立て（DI）て `use-cases` を呼び出す

| 層             | 主な接続先（実行時）       | コード依存 | 補足                                      |
| -------------- | -------------------------- | ---------- | ----------------------------------------- |
| functions      | infrastructure / use-cases | 外 -> 内   | 依存を組み立ててユースケースを起動する    |
| infrastructure | use-cases / domain         | 外 -> 内   | `domain` のインターフェース実装を提供する |
| use-cases      | domain                     | 内側のみ   | 業務フローを実行し、実装詳細は知らない    |
| domain         | なし（最内部）             | 内側のみ   | ルールと抽象のみを持つ                    |

## 8. 用語集（クリーンアーキテクチャ）

| 用語                               | 説明                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------ |
| Entity（エンティティ）             | ドメインの中核概念。ビジネスルールを表すオブジェクト。                   |
| Use Case（ユースケース）           | アプリケーション固有の手順。入力を受けて業務フローを実行する。           |
| Interface（インターフェース）      | 層の境界で依存を抽象化する契約。実装詳細を内側に持ち込まないために使う。 |
| Dependency Direction（依存方向）   | 依存の向き。外側の層が内側へ依存し、内側は外側へ依存しない。             |
| Dependency Inversion（依存性逆転） | 内側が抽象（interface）を定義し、外側がその抽象を実装する考え方。        |
| DI（Dependency Injection）         | 必要な依存を外から注入すること。テスト容易性と交換容易性を高める。       |
| Adapter（アダプター）              | 外部ライブラリやSDKを内側の契約へ合わせる実装。                          |
| Source of Truth（SoT）             | 仕様の一次情報源。構造ルールは `docs/spec` を正とする。                  |