開発進捗ログ

立ち上げ（フェーズ 1: 方針決定）

•  プロジェクト方針の確定と要件定義書の作成: TIASjudge（ルールベースの舌診支援アプリ）の舌色 5 分類を機械学習で推定する研究プロジェクトとして，目的・スコープ・成功基準を確定し PLAN_01 要件定義書 を作成した．開発モードは solo．
  • 前提（データ取り扱い）: 臨床データは手元 PC に置かない．原本は研究室 PC に保管し，研究室 LAN 内で計算サーバへ一度だけコピーする．手元へ持ち帰るのは非個人情報の派生物（集計指標・ログ・モデル重み）のみ．リモート実行の構成は SmTIAS-LightSim の方式（コードを手元から送り，結果を回収）を踏襲する
  • 設計判断: 本フェーズのゴールを「現状把握」とし精度の絶対値目標を置かない．評価は患者単位分割を必須とし（画像単位のランダム分割は同一患者が train / test に跨り過大評価になる），既存ルールベースを同一テストセットのベースラインとして並べて比較する
  • スコープ外: セグメンテーションの学習・5 分類以外の所見・TIASjudge への組み込み実装・撮影条件の色補正
  • 未確定: 画像枚数・患者数・クラス分布・ラベル形式・患者 ID の追跡可否は研究室 PC で実データを確認して確定する

立ち上げ（フェーズ 2〜3: 技術選定・環境構築）

•  技術スタックの確定: PyTorch ＋ timm・uv・YAML ＋ pydantic・リモート実行は SmTIAS-LightSim の sm-remote 移植，実験記録は軽量自作，CI なしと決め ENV_01 を作成した．
  • 設計判断: 実験管理に W&B・MLflow を採らず自作にしたのは，臨床データ由来の指標を外部サービスへ送らない方針と，実験数に対する運用コストの釣り合いから
•  環境構築: GitHub private リポジトリを作成し Dependabot alerts / security updates を有効化（検証済み）．.github/dependabot.yml（uv ＋ github-actions）・.gitignore 更新（data/・runs/・重み）・pyproject.toml（Python 3.12）・パッケージ骨組み・README を作成し，ENV_02〜ENV_04 を整備した．Newton に ~/work/TIASJudgeModel と ~/data/TIASJudgeModel（700）を作り，コードを tar over ssh で送って uv sync を通し torch 2.14.0+cu130・CUDA 有効・GPU 3 台を確認した．
  • 確認できたこと: Linux では PyPI の wheel がそのまま CUDA 版で入る（ENV_01 の想定どおりで [tool.uv.sources] での対処は不要）．GPU は 3 台のうち 1 台が他ユーザー使用中で，共用前提の GPU 指定が必要
  • 失敗パターン: ① 手元の uv sync が PyPI からのダウンロードで connection reset（safetensors）→ 再試行中 / ② 非対話 ssh では uv が PATH に無く command not found（export PATH="$HOME/.local/bin:$PATH" が必要）/ ③ 踏み台経由で Newton.local の名前解決が一時的に失敗（再試行で復帰）．② ③ は ENV_02 のトラブルシューティングに記録した
  • 未実施: push・PR，臨床データの初回コピー（研究室 PC → Newton），倫理審査・データ利用許諾の確認．仕様設計（フェーズ 4）はドラフトを提示済みで保存保留

立ち上げ（フェーズ 4〜6: 仕様設計・規約整備・開発計画）

•  仕様設計: SPEC_01 アーキテクチャ設計と SPEC_02 学習・評価仕様を作成した．
  • 設計判断 ①: 手元へ持ち帰れるものを回収ホワイトリストとして仕様に固定した（画像・manifest・個票は回収しない）．「回収しないよう気を付ける」では守れないため，ツールの制約として実装しテストで固定する
  • 設計判断 ②: manifest.csv を学習の唯一の入口とし，patient_id を必須にした．取得できない場合に画像 ID を患者 ID と見なす代替はしない（同一患者が分割を跨ぐと評価が壊れる）
  • 設計判断 ③: 色を変えるデータ拡張を既定で禁止した．舌の色そのものが正解ラベルであり，color jitter 等はラベルを壊す
  • 設計判断 ④: クラス ID を固定表（0=淡白 … 4=紫）にして混同行列の軸をぶらさないようにした
•  規約整備: .claude/rules/ に coding-style・project-structure・testing・error-handling を作成し（path-scoped rule），pyproject.toml に ruff の選択ルールと pytest の slow マーカーを追加した．CLAUDE.md の必須ルール欄にプロジェクト固有の制約（データの持ち出し禁止・患者単位分割・色拡張の禁止等）を明記した．
  • 方針: 書式・命名・docstring 等の標準部分は SmTIAS-LightSim と同一にし，本プロジェクト固有の規則（臨床データの扱い・個人情報を含むログの禁止・データ整合性の fail fast）だけを追加した
•  開発計画: PLAN_02 開発ステップを作成した（Step 1 基盤 → 2 リモート実行 → 3 データセット集計 → 4 学習最小版 → 5 評価 → 6 ベースライン比較 → 7 実験反復 → 8 結論）．
  • 順序の理由: Step 1・2 は手元で完結しデータのコピー待ちの間に進められる．実データの素性が判明する Step 3 の後に SPEC を更新してから学習に入る