# 開発ステップ (Development Steps)

[PLAN_01 要件定義書](PLAN_01_要件定義書.md)の目的を満たすための実装順序．各ステップは `/implement <タスク>` で進める（実装 → テスト → リファクタリング → ドキュメント更新）．

## 全体像 (Overview)

| Step | 内容 | 前提 |
| --- | --- | --- |
| 1 | 基盤: 設定スキーマ・合成データ生成・manifest 読み込み・患者単位分割 ✅ 完了 | なし（手元で完結） |
| 2 | リモート実行ツール（送信・実行・回収・GPU 確認，回収ホワイトリスト）✅ 完了（Newton・Archimedes の 2 サーバ対応） | Step 1 |
| 3 | データセット集計（実データの素性把握）✅ 完了（結果は [TEST_02](../06_TEST/TEST_02_データセット集計結果.md)） | **臨床データのコピー完了**・倫理確認 |
| 4 | 学習パイプライン最小版（ConvNeXt-Tiny を 1 本通す）✅ 完了 | Step 2・3 |
| 5 | 評価・レポート生成（指標・混同行列・`runs/` 出力）✅ 完了（5-fold 交差検証として実装．結果は [TEST_03](../06_TEST/TEST_03_交差検証結果.md)） | Step 4 |
| 6 | ベースライン比較（TIASjudge のルールベース）※ 後回し | Step 5 |
| 7 | 実験反復（不均衡対策・モデル比較・解像度検討）※ 一部実施（モデル比較: [TEST_03](../06_TEST/TEST_03_交差検証結果.md)・不均衡対策: [TEST_04](../06_TEST/TEST_04_クラス不均衡対策の実験.md)） | Step 6 |
| 8 | 結論（5-fold 交差検証・評価レポート・配布形式の判断） | Step 7 |

Step 1・2 はデータのコピー待ちの間に進められる．

## Step 1: 基盤 (Foundation)

- **成果物**: `schema.py`（pydantic 設定），`data/manifest.py`（読み込み・検証），`data/split.py`（患者単位分割），`scripts/make_synthetic_dataset.py`
- **完了条件**: 合成 manifest で分割が患者単位に保たれ，同一 seed で再現することがテストで確認できる．不正な manifest が停止する
- **理由**: 手元だけで完結し，以降すべての土台になる．最重要の「患者単位分割」をここで固める

## Step 2: リモート実行ツール (Remote Execution)

- **成果物**: `remote/`・`cli/remote.py`（コード送信 / ジョブ実行 / 結果回収 / GPU 空き確認）
- **完了条件**: コードを送って合成データの短い学習をサーバで実行し，結果を回収できる．**回収ホワイトリスト**が効いており，画像・manifest が回収対象にならないことがテストで確認できる
- **注意**: 非対話 ssh では `uv` が PATH に無いため，ツール側で `export PATH="$HOME/.local/bin:$PATH"` を行う（[ENV_02](../02_ENV/ENV_02_環境構築手順.md)トラブルシューティング）

## Step 3: データセット集計 (Dataset Survey)

- **成果物**: `tias-dataset build-manifest`・`tias-dataset survey`（[SPEC_01](../04_SPEC/SPEC_01_アーキテクチャ設計.md)「データセット集計の出力」），設定 `data.severities` による「ややあり込み / 除外」の切り替えと，クラス × 程度での層化分割（[SPEC_02](../04_SPEC/SPEC_02_学習・評価仕様.md)「程度（ややあり）の扱い」），集計レポート（`docs/06_TEST/` に記録）
- **完了条件**: 両サーバで manifest を生成し，実データの集計（件数・サイズ・破損・舌領域の割合・**クラス × 程度ごとの Lab 色**）が手元に集計値だけで届く．「ややあり」の色が淡紅と同じクラスの「あり」のどちらに近いかが数値（ΔE）で分かる
- **背景**: 「ややあり」は臨床上は淡紅（正常）と判断されることが多い境界例であり，入れる場合と入れない場合の両方で実験する（2026-09-27 ユーザー判断）
- **前提**: 研究室 PC → サーバのデータコピー（両サーバとも完了済み）

## Step 4: 学習パイプライン最小版 (Minimal Training)

- **成果物**: `models/`・`training/`・学習コマンド，設定 YAML 1 本
- **完了条件**: 手元で合成データ 1 エポックが通り，サーバで実データの学習が完走して `runs/<実験ID>/` が生成される
- **方針**: 精度は問わない．「落ちずに回り，記録が残る」ことだけを見る

## Step 5: 評価・レポート生成 (Evaluation)

- **成果物**: `evaluation/`・評価コマンド（macro F1・クラス別指標・混同行列・学習曲線）
- **完了条件**: val で選び test を最後に一度だけ見る運用が実装され，指標が既知の混同行列に対してテストで期待値と一致する

## Step 6: ベースライン比較 (Baseline)

> ⚠ **一旦後回しとする**（2026-09-27 のユーザー判断）．入力条件の違い（TIASjudge は撮影画像から ROI を取るが，本データセットは舌領域を黒背景で切り出した画像）を揃える設計判断が必要なため，機械学習側のパイプラインを先に通す．Step 5 の後に Step 7 へ進み，本ステップは条件が整った時点で実施する．

- **成果物**: `baseline/`（TIASjudge のルールベース診断），比較レポート
- **完了条件**: 同一テストセットでルールベースと機械学習モデルの指標が並べて出る
- **ここで決める**: ルールベースを移植するか別リポジトリを参照するか（SPEC_02 の未確定事項）

## Step 7: 実験反復 (Experiments)

- **成果物**: 実験群（クラス不均衡対策・モデル比較・入力解像度・マスク外領域の埋め方）とその記録
- **完了条件**: 各要因の効果が**独立した実験として**切り分けて記録されている
- **注意**: 共用サーバのため使用する GPU を明示的に指定する
- **進捗**: クラス不均衡対策（[TEST_04](../06_TEST/TEST_04_クラス不均衡対策の実験.md)）・色特徴分類器との比較（[TEST_05](../06_TEST/TEST_05_色特徴分類器の実験.md)）・ハイパーパラメータの比較（[TEST_06](../06_TEST/TEST_06_ハイパーパラメータの比較.md)）を実施．TIASjudge への組み込みに向けて，判定モデルの書き出しとセグメンテーションの再現を実施（[TEST_07](../06_TEST/TEST_07_セグメンテーションの再現と判定モデルの書き出し.md)・[SPEC_04](../04_SPEC/SPEC_04_TIASjudge引き渡し仕様.md)）

## Step 8: 結論 (Conclusion)

- **成果物**: 5-fold 交差検証の結果，評価レポート，TIASjudge への引き渡し方針（配布形式）
- **完了条件**: PLAN_01 の成功基準 4 項目が満たされ，「組み込むか・手法を変えるか」の判断材料が揃う

## 進め方の原則 (Process Rules)

- Step 3 の結果で SPEC_01・SPEC_02 を更新してから Step 4 以降に進む（仕様変更は先にドキュメントへ反映する）
- 実験は 1 回の変更で 1 要因のみ変える（効果の切り分けができなくなるため）
- 各ステップ完了時に進捗を記録する（`.claude/rules/progress-log.md`）