# Railway Framework 実装計画

**作成日:** 2026-01-08
**対象:** Phase 1（6週間）
**開発手法:** TDD（テスト駆動開発）

---

## 1. TDD開発方針

### 1.1 基本原則

すべての機能実装において、以下のサイクルを厳守します：

```
1. Red    - まずテストを書く（失敗することを確認）
2. Green  - テストが通る最小限のコードを実装
3. Refactor - コードをリファクタリング（テストは通ったまま）
```

### 1.2 テストの種類

| 種類 | 目的 | 配置場所 |
|-----|------|---------|
| Unit Test | 個別関数・クラスのテスト | `tests/unit/` |
| Integration Test | コンポーネント間連携テスト | `tests/integration/` |
| E2E Test | CLIコマンドの動作テスト | `tests/e2e/` |

### 1.3 テストカバレッジ目標

- **Unit Test:** 90%以上
- **Integration Test:** 主要フローをカバー
- **E2E Test:** 全CLIコマンドをカバー
- **総合:** 80%以上

### 1.4 TDDの実践手順

各Issueで以下の手順を実行：

```bash
# 1. テストファイルを作成
# 2. テストケースを実装（Redフェーズ）
pytest tests/unit/test_xxx.py -v  # 失敗を確認

# 3. 最小限の実装（Greenフェーズ）
pytest tests/unit/test_xxx.py -v  # 成功を確認

# 4. リファクタリング（Refactorフェーズ）
pytest tests/unit/test_xxx.py -v  # 成功を維持

# 5. カバレッジ確認
pytest tests/unit/test_xxx.py --cov=railway --cov-report=term-missing
```

---

## 2. 実装フェーズ概要

### 2.1 Phase 1a: 基本機能（Week 1-2）

| Issue | タイトル | 依存関係 |
|-------|---------|---------|
| #01 | プロジェクト構造とCI/CD設定 | - |
| #02 | 設定プロバイダーレジストリ | #01 |
| #03 | @nodeデコレータ（基本版） | #02 |
| #04 | @entry_pointデコレータ | #03 |
| #05 | pipeline()関数（基本版） | #03 |
| #06 | 設定管理（Settings） | #02 |
| #07 | ロギング初期化 | #06 |
| #08 | railway init コマンド | #01 |
| #09 | railway new コマンド | #08 |
| #10 | railway list コマンド | #08 |

### 2.2 Phase 1b: 拡張機能（Week 3-4）

| Issue | タイトル | 依存関係 |
|-------|---------|---------|
| #11 | リトライ機能（tenacity統合） | #03, #06 |
| #12 | エラー表示の改善 | #03, #07 |
| #13 | railway run コマンド | #04, #08 |
| #14 | TUTORIAL.md自動生成 | #08 |
| #15 | テストテンプレート自動生成 | #09 |

### 2.3 Phase 1c: 高度な機能（Week 5-6）

| Issue | タイトル | 依存関係 |
|-------|---------|---------|
| #16 | pipeline型チェック（strictモード） | #05 |
| #17 | 非同期ノード基本サポート | #03 |
| #18 | カスタムエラー型階層 | #03, #12 |
| #19 | 遅延初期化（_SettingsProxy） | #06 |
| #20 | 統合テストとドキュメント | #01-#19 |

---

## 3. 依存関係グラフ

```
Phase 1a (Week 1-2)
==================

#01 プロジェクト構造
 ├── #02 設定プロバイダーレジストリ
 │    ├── #03 @nodeデコレータ
 │    │    ├── #04 @entry_point
 │    │    └── #05 pipeline()
 │    └── #06 Settings
 │         └── #07 ロギング
 └── #08 railway init
      ├── #09 railway new
      └── #10 railway list

Phase 1b (Week 3-4)
==================

#03 + #06 ──→ #11 リトライ機能
#03 + #07 ──→ #12 エラー表示改善
#04 + #08 ──→ #13 railway run
#08 ──────→ #14 TUTORIAL.md生成
#09 ──────→ #15 テストテンプレート

Phase 1c (Week 5-6)
==================

#05 ──→ #16 型チェック（strict）
#03 ──→ #17 非同期ノード
#03 + #12 ──→ #18 エラー型階層
#06 ──→ #19 遅延初期化
全て ──→ #20 統合テスト
```

---

## 4. ディレクトリ構造（実装後）

```
railway_py/
├── railway/                    # フレームワーク本体
│   ├── __init__.py
│   ├── cli/
│   │   ├── __init__.py
│   │   ├── main.py            # railway コマンド
│   │   ├── init.py            # railway init
│   │   ├── new.py             # railway new
│   │   ├── list.py            # railway list
│   │   └── run.py             # railway run
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py          # 設定プロバイダーレジストリ
│   │   ├── decorators.py      # @node, @entry_point
│   │   ├── pipeline.py        # pipeline()
│   │   ├── errors.py          # エラー型階層
│   │   └── types.py           # 型定義
│   ├── templates/
│   │   ├── project/
│   │   ├── entry/
│   │   └── node/
│   └── utils/
│       └── file_ops.py
├── tests/
│   ├── unit/
│   │   ├── core/
│   │   │   ├── test_config.py
│   │   │   ├── test_decorators.py
│   │   │   ├── test_pipeline.py
│   │   │   └── test_errors.py
│   │   └── cli/
│   │       ├── test_init.py
│   │       ├── test_new.py
│   │       ├── test_list.py
│   │       └── test_run.py
│   ├── integration/
│   │   ├── test_settings_integration.py
│   │   └── test_pipeline_integration.py
│   ├── e2e/
│   │   ├── test_cli_init.py
│   │   ├── test_cli_new.py
│   │   └── test_cli_run.py
│   └── conftest.py
├── pyproject.toml
└── README.md
```

---

## 5. 品質ゲート

### 5.1 各Issue完了の条件

- [ ] テストが全て通過
- [ ] カバレッジが目標値以上
- [ ] mypyでエラーなし
- [ ] ruffでエラーなし
- [ ] ドキュメント更新（必要な場合）

### 5.2 Phase完了の条件

- [ ] 全Issueが完了
- [ ] 統合テストが通過
- [ ] E2Eテストが通過
- [ ] カバレッジ80%以上
- [ ] ドキュメントが最新

---

## 6. Issue一覧

| # | タイトル | Phase | ファイル |
|---|---------|-------|---------|
| 01 | プロジェクト構造とCI/CD設定 | 1a | `01_プロジェクト構造.md` |
| 02 | 設定プロバイダーレジストリ | 1a | `02_設定プロバイダー.md` |
| 03 | @nodeデコレータ（基本版） | 1a | `03_nodeデコレータ.md` |
| 04 | @entry_pointデコレータ | 1a | `04_entry_pointデコレータ.md` |
| 05 | pipeline()関数（基本版） | 1a | `05_pipeline関数.md` |
| 06 | 設定管理（Settings） | 1a | `06_設定管理.md` |
| 07 | ロギング初期化 | 1a | `07_ロギング.md` |
| 08 | railway init コマンド | 1a | `08_cli_init.md` |
| 09 | railway new コマンド | 1a | `09_cli_new.md` |
| 10 | railway list コマンド | 1a | `10_cli_list.md` |
| 11 | リトライ機能 | 1b | `11_リトライ機能.md` |
| 12 | エラー表示の改善 | 1b | `12_エラー表示.md` |
| 13 | railway run コマンド | 1b | `13_cli_run.md` |
| 14 | TUTORIAL.md自動生成 | 1b | `14_tutorial生成.md` |
| 15 | テストテンプレート自動生成 | 1b | `15_テストテンプレート.md` |
| 16 | pipeline型チェック（strict） | 1c | `16_型チェック.md` |
| 17 | 非同期ノード基本サポート | 1c | `17_非同期ノード.md` |
| 18 | カスタムエラー型階層 | 1c | `18_エラー型階層.md` |
| 19 | 遅延初期化（_SettingsProxy） | 1c | `19_遅延初期化.md` |
| 20 | 統合テストとドキュメント | 1c | `20_統合テスト.md` |

---

**次のステップ:** Issue #01 から順に実装を開始
