開発コマンド (Development Commands)

日常の開発で使うコマンドの一覧．コマンドを推測せず必ず本ファイルを参照する（新しく確定・変更された時は本ファイルに反映する）．

※ 学習・評価のコマンドは未実装のため本ファイルには未記載（実装時に追記する）． ※ Git Bash ではログの日本語が文字化けする．先頭に PYTHONIOENCODING=utf-8 を付けると正しく表示される．

環境 (Environment)

目的	コマンド	備考
依存の同期	`uv sync`	初回・`pyproject.toml` 変更後．手元には CPU 版 PyTorch が入る
依存の追加	`uv add <パッケージ>`	`uv.lock` が更新されるのでコミットする
開発用依存の追加	`uv add --dev <パッケージ>`	pytest・ruff 等
Python の実行	`uv run python <スクリプト>`	仮想環境を明示的に有効化しなくてよい

データ (Data)

目的	コマンド	備考
合成データの生成	`uv run python scripts/make_synthetic_dataset.py`	出力は `data/synthetic/`（`images/<label>_<severity>/` と `manifest.csv`）．既定は 1 ディレクトリ 10 枚・seed 0
合成データの作り直し	`uv run python scripts/make_synthetic_dataset.py --overwrite`	目印ファイル `.synthetic_dataset` がある出力先だけを削除して作り直す（実データの誤削除を防ぐため）
枚数・seed の指定	`uv run python scripts/make_synthetic_dataset.py --per-dir 50 --seed 1`	出力先は `--out` で変更できる
manifest の生成	`uv run tias-dataset build-manifest --config <設定>`	`images/` を走査して `manifest.csv` を書く．既存があれば `--overwrite` が必要
データセットの集計	`uv run tias-dataset survey --config <設定>`	`runs/<実験ID>/` に集計値だけを書く．最後に実験 ID を出力する（SPEC_01「データセット集計の出力」）

実データ（サーバ上）での実行例（GPU を使わないので --cpu）:

uv run tias-remote run --name manifest --cpu --server Newton -- tias-dataset build-manifest --config configs/newton.yaml
uv run tias-remote run --name survey --cpu --server Newton -- tias-dataset survey --config configs/newton.yaml
uv run tias-remote logs survey          # 最後の行に実験 ID が出る
uv run tias-remote pull <実験ID>          # 集計値と図だけが手元の runs/ に届く

設定ファイルは configs/synthetic.yaml（手元の合成データ）と configs/newton.yaml（サーバの実データ）．環境変数 TIAS_DATA_ROOT を設定すると data.root より優先される．

リモート実行 (Remote Execution)

研究室の GPU サーバ（Newton・Archimedes）で計算するときは tias-remote を使う．コマンドはすべて手元で実行する．空いている GPU を両サーバから自動で選ぶ（未使用の GPU を最優先．仕様は SPEC_03）．サーバ設定は configs/remote.yaml．

目的	コマンド
GPU の状況と `run` が選ぶ GPU	`uv run tias-remote gpus`
実行中ジョブと GPU の状況	`uv run tias-remote status`
コードを送る（全サーバ）	`uv run tias-remote push`
送る一覧だけ見る	`uv run tias-remote push --dry-run`
ジョブを起動（GPU 自動選択）	`uv run tias-remote run --name exp1 -- python scripts/xxx.py`
GPU を指定して起動	`uv run tias-remote run --name exp2 --server Newton --gpu 1 -- python ...`
選ばれる GPU だけ確かめる	`uv run tias-remote run --name exp1 --dry-run -- python ...`
GPU を使わないジョブ	`uv run tias-remote run --name job --cpu [--server Newton] -- ...`（GPU の空きを待たない．`CUDA_VISIBLE_DEVICES` は空）
ログの末尾・追従	`uv run tias-remote logs exp1`・`uv run tias-remote logs exp1 -f`
ジョブを止める	`uv run tias-remote kill exp1`
実験結果を持ち帰る	`uv run tias-remote pull <実験ID>`（重みも要るときは `--with-checkpoints`）

gpus・run・status は GPU を 10 秒観測してから判定するため，1 回に 13 秒ほどかかる．急ぐときは --observe 0（瞬間値のみ．約 2 秒．gpus・run のみ）
run は起動前に選んだサーバへ自動でコードを送る（--no-push で省略）．ジョブには CUDA_VISIBLE_DEVICES・TIAS_DATA_ROOT（そのサーバのデータの場所）が渡る
pull は回収ホワイトリストに名前が一致するファイルだけを runs/<実験ID>/ に持ち帰る．回収しなかったファイルは件数だけ表示される
ジョブログはサーバ上の runs/_remote_logs/<ジョブ名>.log．末尾に === [日時] exit <終了コード> の行が付く
研究室 LAN 内にいるときは踏み台が不要なので，環境変数 TIAS_REMOTE_JUMP を空文字にすると速い（Git Bash: TIAS_REMOTE_JUMP= uv run tias-remote gpus．PowerShell: $env:TIAS_REMOTE_JUMP = ""）
ジョブの実行中に同じサーバへ push しない（上書き展開なので，実行中のジョブが新旧のコードを混ぜて読むおそれがある．実行中なら警告が出る）
各サブコマンドの詳細は uv run tias-remote <サブコマンド> --help

テスト (Test)

目的	コマンド
全テスト	`uv run pytest`
特定ファイル	`uv run pytest tests/data/test_split.py`
詳細表示	`uv run pytest -v`

臨床データに依存するテストは書かない（合成データで動くテストのみ）．

Lint / Format

目的	コマンド
Lint	`uv run ruff check .`
Lint（自動修正）	`uv run ruff check --fix .`
Format	`uv run ruff format .`

※ .claude/ はテンプレート所有のため ruff の対象外（pyproject.toml の extend-exclude）．テンプレート由来のフックのテストは uv run pytest .claude/hooks/tests で実行する．

フック (Hooks)

目的	コマンド	備考
フックのテスト	`bash .claude/hooks/tests/test_hooks.py` 相当を `uv run pytest .claude/hooks/tests`	テンプレート由来．`.claude/` の変更時に確認する

未実装のコマンド (Planned)

実装した時点で本ファイルに追記する．

学習・評価