---
name: developing-backend
description: バックエンド開発の TDD ワークフローを支援。Red-Green-Refactor サイクルとインサイドアウトアプローチで品質の高いバックエンドを実装する。「バックエンドを実装したい」「API を作りたい」「サーバーサイドの機能を追加したい」「バックエンドのテストを書きたい」「ドメインモデルに役割や根拠を残したい」「API ドキュメントや用語集をコードから生成したい」といった場面で発動する。層ごとの知識を Living Documentation としてコードに持たせる実践も案内する。TDD で開発することで、リファクタリングの安全網を確保し、変更を楽に安全にできるコードを維持する。
---

# バックエンド開発

TDD サイクルに従いバックエンドを開発する。インサイドアウトアプローチ（データ層→ドメイン層→API 層）で、内側から外側へ段階的に構築する。

インサイドアウトの利点は、ドメインロジックのテストが外部依存なしで書けること。テストの実行速度が速く、フィードバックループを短く保てる。

## 参照ドキュメント

| 種類 | パス |
|------|------|
| ワークフロー | @docs/reference/コーディングとテストガイド.md |
| アーキテクチャ | @docs/design/architecture_backend.md |
| データモデル | @docs/design/data-model.md |
| ドメインモデル | @docs/design/domain-model.md |
| 技術スタック | @docs/design/tech_stack.md |
| テスト戦略 | @docs/design/test_strategy.md |
| 開発戦略 | @docs/development/development_strategy.md（Living Documentation の採用可否・語彙・局面ごとの重点） |
| Living Documentation | @docs/reference/LivingDocumentation導入ガイド.md、@docs/reference/アノテーション導入ガイド.md |

## TDD サイクル

10-15 分で 1 サイクルを完了させる。サイクルが長引くなら、タスクの粒度が大きすぎる。

1. **Red**: 失敗するテストを最初に書く
2. **Green**: テストを通す最小限のコードを実装する
3. **Refactor**: 重複を除去し設計を改善する

## アプローチ

- **インサイドアウト**（推奨）: データ層から開始し上位層へ展開する
- **アウトサイドイン**: API から開始しドメインロジックを段階的に実装する

## Living Documentation の実践

バックエンドの知識の大半は、スキーマ・ドメインモデル・API 定義・テストの中にある。それを設計ドキュメントに書き写すのではなく、**権威ある情報源をコードに置き、そこから生成し、足りない意図と根拠だけを補う**。採用するかどうかとアノテーションの語彙は開発戦略に従う。ここではインサイドアウトの層ごとに、何をどこに持たせるかを示す。

### 層ごとの知識の持たせ方

| 層 | 権威ある情報源 | 生成・検証するもの | 補う知識 |
| :--- | :--- | :--- | :--- |
| データ層 | マイグレーション・スキーマ定義 | ER 図・テーブル定義をスキーマから生成する。`docs/design/` のデータモデルに列定義を手で複製しない | 正規化を崩した理由などの判断は ADR に残す |
| ドメイン層 | エンティティ・値オブジェクト・集約のコード | ドメインのクラス名・メソッド名・列挙型から用語集（Living Glossary）を生成する | 役割（`@Entity`・`@ValueObject`・`@DomainService` など）とコア概念（`@CoreConcept`）をアノテーションで補う |
| API 層 | コントローラとリクエスト/レスポンスの型 | OpenAPI をコードから生成して公開する。外部に公開した契約は、変更を検出するテストで守る | 外部システムとの境界（連携先・方向）を宣言し、コンテキスト図の元にする |
| 層をまたぐ構造 | パッケージ構成・レイヤー宣言 | 層の依存方向をアーキテクチャテスト（ArchUnit など）で検証し、アーキテクチャ図をコードから生成する | パッケージ単位の宣言（`package-info.java` のレイヤー・境界づけられたコンテキスト）で補う |

### ドメイン層で守ること

インサイドアウトで最初に固めるドメイン層は、用語集と図の出来を左右する。

- **宣言的に書く**: クラス名・メソッド名・列挙型の定数名をドメインの用語にする。生成した用語集が読みにくければ、用語集ではなく名前を直す
- **本質的な知識だけを付ける**: 不変である、副作用がない、値で同一性を判定するといった、要素を消せば一緒に消える性質だけをアノテーションにする。所有者や使われ方などの外在的な知識は付けない
- **デフォルトを決めて例外に付ける**: 値オブジェクトを不変とする方針なら、全クラスに `@Immutable` を付けず、可変なものだけを明示する
- **フレームワークの注釈を流用しない**: JPA の `@Entity` などの技術的な注釈はドメインの意味を表さない。ドメインの役割は独自の語彙で表す
- **テストをシナリオとして読めるようにする**: テスト名は業務の言葉で書く。イベントソーシングを使う場合は「Given 過去のイベント / When コマンド / Then 新しいイベント」の形にし、コマンドは命令形、イベントは過去形で命名する

### TDD サイクルでのタイミング

- **Red**: テスト名とテストデータにドメインの用語を使う
- **Refactor**: 名前を用語に揃え、役割と性質のアノテーションを付ける。付ける数は最小にする
- **コミット**: 変更の意図を書く（`git-commit`）。代替案を比べて選んだ設計判断は ADR に残す（`creating-adr`）

## テストコマンド

```bash
# 全テスト実行
cd apps/backend && ./gradlew test

# 特定テストクラス実行
cd apps/backend && ./gradlew test --tests "UserServiceTest"

# テストカバレッジ確認
cd apps/backend && ./gradlew jacocoTestReport
```

## API ドキュメント

```bash
# バックエンドを起動
cd apps/backend && ./gradlew bootRun
# Swagger UI: http://localhost:8080/swagger-ui.html
# OpenAPI JSON: http://localhost:8080/v3/api-docs
```

API ドキュメントはコードから生成されるので、別文書に API 仕様を手で書かない。エンドポイントの意図や制約など、コードに無い説明はアノテーションの説明文に書き、生成物に含める。

## 品質チェックリスト

コミット前に必ず確認する。

- [ ] すべてのテストがパス
- [ ] ESLint/コンパイラの警告がゼロ
- [ ] テストカバレッジが目標を満たしている
- [ ] 単一の論理的作業単位を表現
- [ ] コミットメッセージが変更内容を明確に説明
- [ ] （Living Documentation 採用時）ドメインの名前が用語に揃い、開発戦略で決めたアノテーションが付いている
- [ ] （Living Documentation 採用時）アーキテクチャテストと公開契約のテストがパスし、生成するドキュメントがビルドで生成できる

## 途中から再開

開発セッションの途中から再開する場合は、まず現在のテスト状態を確認する。

**Example:**

```
ユーザー: 「ユーザー認証の Entity と Repository は実装済み。Service 層に進みたい」
回答: 既存テストを実行して Green 状態を確認する。
      Service 層の失敗するテスト（Red）を書いてから実装に進む。
      Repository の戻り値を使った Service のビジネスロジックをテストする。
```

## コンテキスト管理

タスクの区切りごとに `/compact` を実施して Context limit reached エラーを回避する。

- TDD サイクルを数回繰り返した後、ユーザーストーリー完了時、コミット完了後に実施する
- `/compact` 前に現在の作業状態と次のタスクをメモとして出力する

## 注意事項

- Java/Gradle のテスト環境が設定済みであること（前提条件）
- TDD の三原則を厳密に守る。テストなしでプロダクションコードを書かない
- コミット前に必ず品質チェックリストを実行する
- 作業完了後に対象の @docs/development/iteration_plan-N.md の進捗を更新する
- TODO 駆動開発でタスクを細かく分割し、Rule of Three で 3 回同じコードが現れたらリファクタリングする
- スキーマ・クラス一覧・API 仕様など、コードから取り出せる知識を `docs/design/` に手で書き写さない。書くのはコードに無い意図と根拠だけにする

## 関連スキル

- `developing-frontend` — フロントエンド TDD 開発
- `orchestrating-development` — 開発フェーズ全体のワークフロー
- `git-commit` — Conventional Commits 準拠のコミット
- `creating-adr` — 設計判断の根拠の記録
- `creating-development-strategy` — Living Documentation の採用可否・語彙・局面ごとの重点