---
name: orchestrating-development
description: 開発フェーズ全体の TDD ワークフローをオーケストレーション。バックエンド・フロントエンドの開発順序と TDD サイクルの実践方法を案内し、Codex 分業体制もサポートする。開発中に生まれる知識を Living Documentation としてコードと同期させる実践も案内する。「開発を始めたい」「TDD の進め方を知りたい」「Codex と分業で開発したい」「開発フェーズの全体像を把握したい」「開発しながらドキュメントをコードと同期させたい」といった場面で発動する。開発フローを標準化することで、品質のブレを防ぎチーム全体の生産性を底上げする。
---

# 開発フェーズオーケストレーション

開発フェーズ全体のワークフローを案内する。TDD サイクルに従い、バックエンド→フロントエンドの順序で品質を担保しながら開発を進める。

## オプション

| オプション | 説明 |
|-----------|------|
| なし | 開発フェーズ全体のワークフローを表示 |
| `--codex` | Claude（計画・設計・受入）と Codex（実装）の分業体制で開発 |

## 開発フェーズの全体像

1. **バックエンド開発** (Skill: `developing-backend`) — インサイドアウトアプローチ推奨
2. **フロントエンド開発** (Skill: `developing-frontend`) — アウトサイドインアプローチ推奨

各開発で Red-Green-Refactor サイクルを厳密に実行する。テストなしでプロダクションコードを書かない。

### レビューポイント

コーディングとテストガイドのイテレーション開発フローに準拠し、以下のタイミングでレビュースキルを発動する。

| タイミング | スキル | 説明 |
|-----------|--------|------|
| TODO 完了時（コードレビュー） | `developing-review` | TDD サイクルで TODO を完了するたびにコード品質・テスト品質・設計整合性をレビュー |
| 受け入れ前（品質チェック） | `operating-qt` | SonarQube によるコード品質分析・Quality Gate 確認を実施し、品質基準を満たしていることを検証 |
| イテレーション完了時（ユーザーレビュー） | `analyzing-review` | 受け入れフェーズでユーザー視点・プロダクト視点からの成果物レビュー |
| 設計ドキュメント新規作成の直前 | `apply-docs-structure` | 開発中に設計ドキュメント・ADR を新規に書く前に配置先（プロジェクト別カテゴリの `<project>/` 配下）を判断する。配置を誤ると docs と apps のトレーサビリティが壊れ、後からの移動は索引・リンク・来歴すべての修正になる |
| 設計ドキュメント更新時 | `apply-okf` | 開発中に `docs/design/` や ADR を更新したら OKF フロントマター（`generated`）と `log.md` を追従させる。実装で設計が変わったのに文書の来歴が古いままだと、次のイテレーションで古い設計を信頼してしまう |
| 設計判断を下したとき | `creating-adr` | 代替案を比較して選んだ判断は、その場で文脈・理由・却下した代替案を ADR に残す。後から思い出して書くと根拠が失われる |
| イテレーション完了時（生きたドキュメントの確認） | — | Living Documentation を採用している場合、生成するドキュメント（用語集・図・ガイドツアー）がビルドで生成できること、手書きでコードを複製した一覧・図が増えていないことを確認する（下記「Living Documentation の実践」） |

## TDD サイクル

TDD は「テストを書いてからコードを書く」手順ではなく、「設計を小さなフィードバックループで検証する」手法。10-15 分で 1 サイクルを完了させる。

1. **Red**: 失敗するテストを最初に書く
2. **Green**: テストを通す最小限のコードを実装する
3. **Refactor**: 重複を除去し設計を改善する
4. @docs/reference/コーディングとテストガイド.md のワークフローに従う

## Living Documentation の実践

開発中に生まれる知識（用語・構造・判断の理由）を、別文書に書き写すのではなくコードとテストに持たせ、足りない意図と根拠だけを補う。採用するかどうかと局面ごとの重点は開発戦略（@docs/development/development_strategy.md、`creating-development-strategy`）で決まっているので、ここではそれを TDD サイクルの中で実行する。原則と手法は @docs/reference/LivingDocumentation導入ガイド.md を参照する。

### TDD サイクルへの組み込み

新しい作業は増やさず、既存のステップの中で知識を残す。

| ステップ | 知識の残し方 |
| :--- | :--- |
| Red | テスト名とシナリオをユビキタス言語で書く。テストは「振る舞いの仕様」として読まれるドキュメントになる |
| Green | 最小限の実装に集中する。この段階ではドキュメントのことは考えない |
| Refactor | 名前をドメインの用語に揃える（用語集の元になる）。開発戦略で決めた語彙に従い、役割・性質などの本質的な知識だけをアノテーション（言語によっては属性・デコレータ・命名規約）で補う |
| コミット | 変更の意図をコミットメッセージに書く（`git-commit`）。コードの差分から読み取れる「何を」ではなく「なぜ」を書く |
| 設計判断 | 代替案を比較した判断は ADR に残す（`creating-adr`） |

アノテーションの付け方は @docs/reference/アノテーション導入ガイド.md、コア概念・模範例の選び方は @docs/reference/ダイナミックキュレーション導入ガイド.md、処理の流れの案内は @docs/reference/ガイドツアー・サイトシーイング導入ガイド.md に従う。

### 守ること

- **書く前に探す**: 知識がすでにコード・テスト・ADR・コミット履歴にあれば、ドキュメントに書き写さずリンクするか生成する
- **手で複製しない**: クラス一覧・依存関係図・用語一覧など、コードから取り出せるものを `docs/design/` に手で書き写さない。`docs/design/` にはコードから読み取れない意図・判断・却下した代替案を書く
- **重複には検証を付ける**: やむを得ず重複させた知識（公開 API の契約、シナリオとコード）は、不一致を検出するテストで守る
- **付けすぎない**: アノテーションは例外と本質的な知識にだけ付ける。すべてのクラスに同じアノテーションを付けるとノイズになる
- **書きにくさを設計のシグナルにする**: 名前が決まらない、図が交差だらけになるといった場合は、ドキュメントではなく設計を直す

## 参照ドキュメント

- @docs/reference/コーディングとテストガイド.md — TDD ワークフロー詳細
- @docs/reference/CodexCLIMCPアプリケーション開発フロー.md — Codex 連携フロー
- @docs/reference/LivingDocumentation導入ガイド.md — 開発中の知識をコードと同期させる原則と手法
- @docs/development/development_strategy.md — 局面ごとの TDD アプローチと Living Documentation の重点（あれば）
- @docs/design/architecture.md, @docs/design/architecture_backend.md, @docs/design/architecture_frontend.md
- @docs/design/data-model.md, @docs/design/domain-model.md, @docs/design/tech_stack.md
- @docs/design/ui-design.md, @docs/design/test_strategy.md
- 作業開始前に対象の @docs/development/iteration_plan-N.md の内容を確認する
- 作業完了後に対象の @docs/development/iteration_plan-N.md の進捗を更新する

## Codex 分業モード（--codex）

Claude と Codex の役割を分離し、計画・設計・受入を Claude が担い、実装を Codex に委譲する。

**前提条件**: Codex MCP サーバーが設定済みであること（@docs/reference/CodexCLIMCPサーバー設定手順.md 参照）

### 役割分担

| フェーズ | 担当 | 責務 |
|---------|------|------|
| 計画 | Claude | 要件分析、タスク分解、優先度決定 |
| 設計 | Claude | API 設計、UI 設計、データモデル設計 |
| 実装 | Codex | コード実装、ユニットテスト作成 |
| 受入 | Claude | 設計レビュー、E2E テスト作成・実行、品質確認 |

### 開発フロー

```mermaid
graph LR
    A[計画] --> B[設計]
    B --> C[実装指示]
    C --> D[受入]
    subgraph Claude
    A
    B
    D
    end
    subgraph Codex
    C
    end
```

### 指示サイズ

| 粒度 | 推奨度 | 説明 |
|------|--------|------|
| 1 ファイル単位 | 推奨 | コード全文を含めた具体的な指示。最も確実 |
| タスク単位（2-3 ファイル） | 注意 | タイムアウトリスクあり。順次実行を推奨 |
| 機能・ストーリー単位 | 非推奨 | タイムアウトする。必ず分割して実行する |

### Codex への指示原則

1. **1 ファイル 1 指示**: 複数ファイルの同時指示はタイムアウトする（IT1 実績: 6 ファイル同時→タイムアウト、1 ファイルずつ→各 15-35 秒で成功）
2. **コード全文を渡す**: 自然言語の説明より、作成すべきファイルの完全なコードを指示に含める
3. **「既存コードは変更しないでください」を明記**: 追記指示時に Codex が他の箇所を無断で書き換えるのを防ぐ
4. **`--write` フラグを含める**: 書き込みが必要な場合は prompt 冒頭に `--write` を付ける
5. **知識の残し方も指示に含める**: Living Documentation を採用している場合、渡すコード全文に規定のアノテーションとユビキタス言語の命名を含める。Codex に任せると語彙が揺れ、生成する用語集や図が崩れる

### Codex への指示例

```
codex:codex-rescue に以下を委譲:

--write apps/sms/backend/src/main/java/.../HomeSummaryResponse.java に以下の record を作成してください。

（ファイルの完全なコードをここに記載）
```

### 受入基準

- [ ] `git diff` で意図しない変更がないことを確認（Codex は指示外のコードを書き換えることがある）
- [ ] すべての受入条件が満たされている
- [ ] 既存テストが壊れていない（Codex の変更で `localStorage` → `sessionStorage` 等の無断変更がないか）
- [ ] E2E テストがすべてパス
- [ ] ESLint / Prettier / 品質チェックがパス
- [ ] （Living Documentation 採用時）規定のアノテーションと命名が守られ、生成するドキュメントがビルドで生成できる

### Codex の既知の問題と対策

| 問題 | 事例 | 対策 |
|------|------|------|
| タイムアウト | 6 ファイル同時指示で応答なし | 1 ファイルずつ順次指示 |
| 既存コードの無断変更 | `localStorage` → `sessionStorage` に書き換え | 「既存コードは変更しない」を明記 + `git diff` で検証 |
| API パターンの変更 | headers マージ方式をスプレッドから `Object.assign` に変更 | コード全文を渡して曖昧さを排除 |
| Spring Boot 4.0 パッケージ名の誤り | `@WebMvcTest` の import パスが旧バージョン | 既存テストの import パターンをコード全文に含める |

### Codex が書き込みできない場合

1. Claude が勝手に直接編集を進めてはいけない
2. ユーザーに状況を報告し、確認を待つ
3. ユーザーの許可を得てから代替手段を実行する

## 途中から再開

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

**Example:**

```
ユーザー: 「バックエンドの認証機能は実装済み。次の機能に進みたい」
回答: イテレーション計画を確認し、次のユーザーストーリーを特定する。
      既存コードのテスト結果を確認し、Green 状態であることを検証してから
      次のタスクの Red フェーズに進む。
```

## コンテキスト管理

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

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

## 注意事項

- プロジェクトのテスト環境が設定済みであること（前提条件）
- TDD の三原則を厳密に守る。テストなしでプロダクションコードを書かない
- コミット前に必ず品質チェックリストを実行する
- TODO 駆動開発でタスクを細かく分割してから実装を開始する
- Rule of Three: 同じコードが 3 回現れたらリファクタリングする
- コードから取り出せる知識を設計ドキュメントに手で書き写さない。書くのはコードに無い意図と根拠だけにする

## 関連スキル

- `creating-development-strategy` — 局面ごとの TDD アプローチと Living Documentation の重点を定める開発戦略
- `developing-backend` — バックエンド TDD 開発
- `developing-frontend` — フロントエンド TDD 開発
- `developing-review` — 開発成果物のマルチパースペクティブレビュー（TODO 完了時のコードレビュー）
- `analyzing-review` — 分析成果物のマルチパースペクティブレビュー（イテレーション完了時のユーザーレビュー）
- `operating-qt` — コード品質管理（受け入れ前の SonarQube 品質チェック）
- `developing-release` — リリースワークフロー（品質ゲート・バージョン管理・CHANGELOG）
- `apply-docs-structure` — 設計ドキュメント・ADR を新規に書く直前の配置先判断（プロジェクト別カテゴリ）
- `apply-okf` — 開発中に更新した設計ドキュメント・ADR への OKF 規約適用
- `creating-adr` — 開発中に下した設計判断の根拠の記録
- `git-commit` — 変更の意図を残すコミット