# 撮った写真を AI エージェントで仕分ける — AI エージェント向けの手順書

https://etoile25.com/trackside/ja/guide/agent/ (この文書) / 人向けの説明: https://etoile25.com/trackside/ja/guide/
作成: Team Étoile (Trackside)。最終更新: 2026-11-02

---

## 0. この文書を読んでいる AI エージェントへ

あなたは、サーキットで写真を撮るカメラマン (以下「撮影者」) に頼まれて、この文書を読んでいる。
撮影者が渡す**写真・動画のフォルダ**と**エントリーリスト**から、次のフォルダを作るのがゴール:

```
<書き出し先>/
  01_予選/
    025_チーム名/
      1_ベスト/                         その台を代表する 3〜6 枚
      2_そのほか/
      3_要確認_ピンぼけ・ぶれ・見切れ/      消してはいない。撮影者が見て判断する
      動画/
    ゼッケン判別不能/                      番号が読めなかった写真
  02_決勝/ …
  README_仕分け.txt                         内訳
```

**守ること**
1. **撮影者はこの文書を読んでいない。** 必要なことは §1・§3 からあなたが短く伝える。長い説明を一度に浴びせない
2. 作業は §4 の道具 `rail.py` が示す **1 手ずつ** に従う。自分の判断で段を飛ばさない・独自の手順を作らない
3. 撮影者に聞くのは、`rail.py next` が「【あなた】」と示した決めごと (全部で 3 回) と、§2 の準備で必要な確認だけ
4. **原本の写真・動画を書き換えない・消さない・動かさない。** 道具は原本を読むだけで、書き出しは複製
5. 写真の中身 (人物) や名簿 (ライダー名) をチャットに貼らない・詳しく描写しない。件数・ファイル名・ゼッケン番号は伝えてよい
6. エラーで止まったら、メッセージを読んで原因を 1 行で伝え、書いてある直し方に従う。書いていなければ撮影者に聞く

**この手順が前提にしている環境**: Mac、ターミナル、AI エージェント (Claude Code か Codex)。動作を確かめたのは Apple シリコンの Mac・macOS 26。
ピンぼけ・ベストの仕分け (§2.3) は macOS 15 以降が必要 (Apple の画像解析の新しい機能を使う)。Intel の Mac・古い macOS は未確認。
Windows・Linux では今は使えない (準備の setup.sh が止まる。動画のコマ抜きと画像の解析に macOS の機能を使うため)。

## 1. 最初の 1 往復で撮影者に伝えること

次を 5〜6 行で (言い換えてよい):

- 写真のフォルダ (とエントリーリスト) をもらえれば、**走行枠ごと・ゼッケン番号ごとに分け、ピンぼけ・ぶれ・見切れを「要確認」に、その台を代表する 3〜6 枚を「ベスト」に**仕分けたフォルダを作ります
- **元の写真は動かしません・書き換えません。** 仕分けたフォルダは別の場所に複製で作ります (同じディスクなら容量はほぼ増えません)
- 最初に道具の準備 (数分) があります。時間の目安は写真 1,000 枚で 20〜30 分前後 (見積もり)。途中で止めても続きからできます
- 聞くのは 3 回だけ: ①エントリーリスト ②走行枠の分け方と名前 ③振り分け結果を見て進めてよいか
- 費用はご契約の AI のプランの範囲です。**入門プラン (Claude Pro など) だと数百枚で使用量の枠に達して止まることがあります** (§3.3)

続けて、次の 3 点を確かめる:
1. 写真・動画のフォルダの場所 (Finder からターミナルへドラッグすると場所が入る)。SD カードから直接でもよい
2. エントリーリストがあるか (主催の PDF・ウェブの URL・CSV)。無くても進められる
3. ピンぼけ・ベストの仕分けを使うか (§2.3 の追加の部品。合わせて 1.5GB 程度の取得とディスクが要る)。使わなければゼッケン別だけ

撮影者が初めてで「なぜチャットではだめなの」「いくらかかるの」と聞いたら §3 の該当項目だけを短く答える。

## 2. 準備 (初回だけ)

### 2.1 道具一式 (キット) を取得する

置き場所は撮影者に聞く。特に希望が無ければホーム (`~/photo-rail` ができる)。

```bash
cd ~
curl -fLO https://etoile25.com/trackside/ja/guide/kit/photo-rail-kit.zip
curl -fLO https://etoile25.com/trackside/ja/guide/kit/photo-rail-kit.zip.sha256
shasum -a 256 -c photo-rail-kit.zip.sha256      # 「OK」と出ること。出なければ止めて撮影者に伝える
unzip -o photo-rail-kit.zip                     # photo-rail/ に展開される
rm photo-rail-kit.zip photo-rail-kit.zip.sha256
```

2 回目以降 (新しい版にする) も同じ手順でよい。`local/` (作業の状態) と `generated/` (中間物) は上書きされない。

### 2.2 実行環境を作る

```bash
cd ~/photo-rail && bash setup.sh
```

`setup.sh` がすること: Python 3.12 以上の確認 (無ければ `uv` で用意する)、`.venv` を作って Pillow と numpy を入れる、
Xcode Command Line Tools (`swift`) の確認。足りないものがあれば、何を入れるかを表示して止まる。

- `uv` が無いと言われたら、撮影者に了承を取ってから入れる: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- `swift` が無いと言われたら、撮影者に `xcode-select --install` を実行してもらう (画面のダイアログで承認が要る)

### 2.3 (任意) ピンぼけ・ベストの仕分けの部品

撮影者が使うと答えたときだけ。物体検出の RF-DETR (Apache-2.0) と PyTorch を入れる (入れた後で約 1GB。**モバイル回線では避ける**)。
初回の実行時に学習済みの重み (約 400MB) が `~/.roboflow/` に取得される。部品の利用条件は配布元 (Roboflow) で確かめてもらう。

```bash
cd ~/photo-rail && bash setup-cull.sh
```

使わない場合は、後で `rail.py` が部品の無いことを示したときに `skip` を選ぶ (§5)。

## 3. 撮影者に説明すること (聞かれたら・初めての人に)

### 3.1 AI エージェントが何をするか

| 撮影者が今まで手でしていたこと | エージェント (+ 手元の道具) がすること |
|---|---|
| 撮影時刻を見て、フリー走行・予選・決勝に分ける | 全部の写真の撮影時刻を読み、撮影の空きで走行枠の案を出す。前の撮影の残り (別の日) も見つける |
| 1 枚ずつ見てゼッケン番号のフォルダにコピー | 縮小した写真を 1 枚ずつ見て番号を読み、表にし、番号 + チーム名のフォルダに複製する |
| ピンぼけ・ぶれ・はみ出しを目で探して除ける | Mac の上の画像処理で被写体のピント・連写の中のぶれ・見切れを測り「要確認」へ (消さない) |
| たくさんの中から良い写真を選ぶ | 点数 (ピント・大きさ・位置・美しさ) の高い順に、似た写真を除いて 3〜6 枚を「ベスト」へ |

### 3.2 なぜ「チャットの一問一答」ではうまくいかないか

- **枚数**: チャットに一度に添付できる画像は数枚〜数十枚。1 日 3,000 枚なら 100 回以上の往復になる
- **手元のファイルに触れない**: チャットは画像を見るだけで、Mac のフォルダを作ったりコピーしたりできない。仕分けは人の手作業に戻る
- **長い作業を覚えていられない**: 会話が長くなると前半を忘れる。エージェントは結果を表 (CSV) に書いてから次へ進むので、何時間でも、途中で止めても続きから再開できる
- **並行できない**: エージェントは判別の担当を最大 20 本同時に走らせる (85 枚ずつ)
- **毎回同じやり方**: 手順・判定の基準・フォルダの名前が道具とこの文書に固定されているので、来週の大会でも、別の人がやっても同じ形の結果になる。チャットは聞き方で答えが変わる

### 3.3 費用とプラン (2026-11-02 時点。変わるので公式ページで確かめる)

従量課金の API は使わない。月額プランの使用枠の中で動く (枠を使い切ると、待つか追加の支払い)。

|  | Claude (Claude Code) | ChatGPT (Codex) |
|---|---|---|
| 入門 | Pro $20/月 (約 3,000 円。年払い $17/月) | Plus $20/月 (約 3,000 円。Free・Go にも付くが、数千枚には足りない見込み) |
| たくさん使う | Max $100/月 (約 15,000 円、Pro の 5 倍) / Ultra $200/月 (週に Pro の 10 倍。5 時間の枠なしは認証済みアカウントのみ) | Pro $100 / $200 / $500/月 |
| 枠 | 5 時間ごと + 週ごと | プランにより 5 時間ごと + 週ごと |
| 公式 | https://claude.com/pricing | https://learn.chatgpt.com/docs/pricing |

- 使用量になるのは**エージェントが画像を見て考える部分**だけ (縮小版 長辺 1100px ≒ 1 枚 約 1,200 トークン + やり取りの読み直し)。走行枠の判定・縮小・ピンぼけの測定・コピーは Mac の上で動き、使用量も通信もほとんど使わない
- **目安 (実測ではない)**: 入門プランの 5 時間枠では数百〜1,000 枚程度で枠に達する見込み。1 日数千枚をその日のうちに回すなら上のプラン。**最初に 1 フォルダ (数百枚) で試し、使用量の % がどれだけ動いたか**を見てから全体を判断する (Claude Code: `/usage`、Codex: `/status`)
- **高いと感じるとき**: 大会のある月だけ上のプランにする / 判別の担当に軽いモデル (Claude なら Sonnet) を指定する (使用量は下がるが、精度は未検証。最初の 1 フォルダで比べる)
- **安いと感じるとき**: 人が 3,000 枚を手で仕分けると数時間〜1 日。それが待ち時間 + 確認 10 分程度になる
- 通信: 送るのは縮小した画像だけ (写真 1,000 枚で 200〜300MB 程度の見積もり)。原本 (数十 GB) は送らない

### 3.4 Claude と Codex

| | Claude Code | Codex |
|---|---|---|
| 画像を見る | Read で手元の画像を見る | 手元の画像を見る機能がある |
| 並行して判別 | サブエージェント (最大 20 本同時) | サブエージェント、または区間ごとに `codex exec` |
| この手順での実績 | 1 万枚超 (Team Étoile、2026-10〜11) | 未検証。最初の 1 区間の結果の表を開いて書式を確かめてから広げる |

## 4. レールの回し方

以下、`rail` = `cd ~/photo-rail && .venv/bin/python3 tools/rail.py` (キットの場所に合わせる)。

```bash
rail init <名前> --src <写真のフォルダ> [--src <動画のフォルダ>] [--entry <PDF|URL|CSV>] [--out <書き出し先>]
rail next <名前>     # 次の 1 手と担当 (機械 / エージェント / あなた) と、打つコマンドが出る
rail run <名前>      # 【機械】の段を、撮影者かエージェントの番になるまで進める
rail status <名前>   # 全体と、各段にかかった時間
```

- `<名前>` は英数字と `-` `_` (例 `20261101-motegi`)。書き出し先の既定は `<写真のフォルダ>_仕分け` (SD カードなら `~/Pictures/<名前>_仕分け`)
- **1 手ごとに `rail next` を見る。** 出た担当どおりに動く:
  - 【機械】→ `rail run`。終わったら出た数字 (枚数・台数・時間) を 1〜2 行で伝える
  - 【エージェント】→ §6 のとおり作業し、終わったら `rail run`
  - 【あなた】→ 撮影者に**その決めごとだけ**を、選択肢と既定の案を付けて聞き、答えをコマンドにして実行する

## 5. 撮影者への決めごと (3 回)

| いつ | 聞くこと | 既定の案 |
|---|---|---|
| 最初 | エントリーリストはあるか | PDF・URL なら `rail set <名前> --entry <PDF か URL>` → §6.1 で表にする。無ければ `rail set <名前> --no-entry` (フォルダ名が番号だけになり、読み違いの照合ができない) |
| 下見の後 | 走行枠の分け方と名前。`rail next` が撮影の空きで案を出す | 名前は時刻から推して「フリー走行 / 予選 / 決勝」を提案。**「同じ大会の別の日? 要確認」と出たら必ず聞く**。分けるときは区切りの時刻を聞いて `--split N@HH:MM`、つなぐときは `--merge N,M`。**撮影者の答え無しに `--accept` しない** |
| 振り分けの後 | 走行枠ごとの台数・判別不能の枚数を見て、進めてよいか | **数字を見せて答えをもらう (聞かずに `rail ok` しない)**。判別不能が多ければ (目安 5% 超) 確認ページ (`bib_review.html`、`rail next` が場所を出す) を開いてもらう |

ほかに、ピンぼけの仕分けの部品が無いと `rail next` が言ったら、§2.3 で入れるか、`rail skip <名前> cull` (ゼッケン別だけ書き出す) かを聞く。

## 6. エージェントの作業

### 6.1 エントリーリストを表にする

PDF・URL を読み、`~/photo-rail/materials/_entry_lists/<名前>.csv` に次の形で書く:

```
number,class,team,riders,note
25,ST600,Team Example,山田 太郎;鈴木 花子,
```

ゼッケン番号は数字だけ、riders はライダー名を `;` 区切り。書いたら**行数・クラスごとの台数・先頭 5 行の番号・クラス・チーム名** (ライダー名の列は見せない) を撮影者に見せて確かめてから
`rail set <名前> --entry materials/_entry_lists/<名前>.csv`。

### 6.2 ゼッケンの判別 (1 段目・2 段目)

`rail next` が区間の一覧とプロンプトの雛形を出す。判別のルールはキットの `docs/bib-sort-agent-instructions.md` に一本化してあり、判別の担当がそれを読む。

- **Claude Code**: 区間ごとにサブエージェント (general-purpose) を 1 本ずつ起動する。同時に 20 本まで、1 本終わるごとに次を足す。
  プロンプトは雛形の `<EVENT>` `<CHUNK>` `<担当>` `<原本>` を区間の行で差し替えたものだけ (ルールを書き足さない・省かない)
- **Codex**: 同じプロンプトでサブエージェント (または区間ごとの `codex exec`) を起動する。最初の 1 区間の CSV を開いて書式を確かめてから広げる
- 全部終わったら `rail run`。CSV が無い区間・途中までしか書いていない区間 (使用量の枠切れ・通信断) は、`rail next` がその区間だけを「途中まで (19/87)」のように出す。途中の区間は CSV を消してから起動し直す
- 判別の担当が「間引いた」「全部見ていない」と報告した区間も、CSV を消して起動し直す

## 7. 困ったとき

| 症状 | 対処 |
|---|---|
| 使用量の枠に達して止まった | 枠が戻るのを待ち (撮影者のプランの画面に戻る時刻が出る)、`rail next` から続ける。途中の区間は §6.2 |
| 走行枠の案が 1 つにまとまりすぎる / 分かれすぎる | 走行枠を決める前なら `--split N@HH:MM` / `--merge N,M`。決めた後は別の名前で `init` し直す |
| カメラの時計がずれている | 区切りは時刻の**差**で決めるので問題ない。外す案になった今日の写真は `rail sessions <名前> --keep N` |
| 書き出した後で判別を直したい | `generated/_rails/<名前>/<走行枠>/_bib_work/ledger/stage2_fix.csv` に、直す写真に写る全車両の行を判別の CSV と同じ列で書いて `rail run` |
| 「書き出し先に、この道具が書いていないファイルがあります」 | 撮影者のファイルを上書きしないために止まった。`rail set <名前> --out <別の場所>` か、そのファイルを移してから `rail run` |
| SD カードから直接 | 階層の深い `DCIM/100XXXXX/` も読む。**書き出しが終わるまでカードを挿したまま** |
| 写真を後から足した | 走行枠を決めた後の追加は取り込まない。別の名前で `init` する |
| RAW (CR3・ARW・NEF など) しかない | JPEG だけを扱う。カメラ側で RAW+JPEG にするか、JPEG を書き出してから |

## 8. 終わったら

撮影者に次を伝える: 書き出し先 / 走行枠ごとの「ベスト・そのほか・要確認・動画・判別不能」の枚数 (`README_仕分け.txt` と同じ) /
かかった時間 (`rail status`) / 確認してほしいこと (判別不能が多い番号、エントリーに無い番号の警告)。

あわせて伝える後片付け:
- 中間物 (縮小版など) は `~/photo-rail/generated/` と `~/photo-rail/local/` にある。要らなくなったら撮影者に確かめて消してよい (原本と書き出し先には影響しない)
- エントリーリストの CSV (`materials/_entry_lists/`) はライダー名 (個人情報) を含む。要らなくなったら撮影者に確かめて消す

## 9. 安全と個人情報

- 写真には他のライダー・観客が写る。仕分けた写真を配る・載せるときの判断は撮影者のもの。この手順は手元のフォルダを作るまで
- エージェントのサービスに送るのは縮小した写真と、表 (CSV) の文字だけ。原本は送らない。送った画像の扱いは各サービスの規約による
- 道具は無保証。原本を書き換えない作りだが、大事な写真は別の場所にもバックアップがある状態で使ってもらう