コンテンツにスキップ

Reading Guide

更新日: 2026-07-05

このガイドは、目的別にどのドキュメントと実装を読むべきかを示す。最初から全ファイルを読む必要はない。

初めて読む人

  1. ../source-design.md
  2. src/pca/ 全体の地図、主要 dataclass、CLI、JSONL schema。
  3. index.md
  4. package/subpackage ごとの詳細ドキュメント入口。
  5. flows.md
  6. self-play、ISMCTS、training、submission の処理フローを図で確認する。
  7. artifacts.md
  8. JSONL、CSV、checkpoint、metadata cache の作られ方と読み手を確認する。
  9. test-map.md
  10. 変更時にどのテストを走らせるか確認する。

Self-Play を触る人

読む順番:

  1. training-selfplay.md
  2. search-ismcts.md
  3. training-data.md
  4. artifacts.md
  5. recipes.md

主な実装入口:

Purpose Files
CLI option を追加する src/pca/training/selfplay/cli_args.py, cli.py, types.py
1 game の挙動を見る src/pca/training/selfplay/battle.py
worker / resume / stream output を見る src/pca/training/selfplay/parallel.py, impl.py
JSONL record を変える records.py, record_targets.py, record_metadata.py, record_io.py, training/targets.py
summary CSV を変える summary_stats.py, summary_csv.py, summary_display.py

最低限走らせるテスト:

PYTHONPATH=src uv run python -m unittest tests.test_module_boundaries tests.test_selfplay_summary tests.test_encoder

ISMCTS を触る人

読む順番:

  1. search-ismcts.md
  2. search.md
  3. flows.md
  4. api-reference.md
  5. recipes.md

主な実装入口:

Purpose Files
root policy の流れ src/pca/search/ismcts/impl.py
1 simulation の traversal src/pca/search/ismcts/simulation.py
PUCT / visit distribution src/pca/search/ismcts/actions.py
information set key src/pca/search/ismcts/public_state.py
node / tree state src/pca/search/ismcts/tree.py
diagnostics src/pca/search/ismcts/runtime_stats.py
value shaping src/pca/search/mcts.py

最低限走らせるテスト:

PYTHONPATH=src uv run python -m unittest tests.test_encoder tests.test_module_boundaries

Training を触る人

読む順番:

  1. training-data.md
  2. training-policy-value.md
  3. training-belief.md
  4. artifacts.md
  5. recipes.md

主な実装入口:

Purpose Files
JSONL loader src/pca/training/data/records.py
search batch src/pca/training/data/search_collate.py
policy/value loss src/pca/training/policy_value/losses.py
model config / checkpoint load src/pca/training/policy_value/model_config.py
static metadata table src/pca/training/policy_value/metadata.py
belief dataloader/loss src/pca/training/belief/data.py, losses.py

最低限走らせるテスト:

PYTHONPATH=src uv run python -m unittest tests.test_training tests.test_encoder

Evaluation / Submission を触る人

読む順番:

  1. evaluation.md
  2. serving-submission.md
  3. flows.md
  4. artifacts.md

主な実装入口:

Purpose Files
deck-pool evaluation src/pca/evaluation/tournament/impl.py
summary CSV src/pca/evaluation/tournament/summaries.py
bundle loading src/pca/evaluation/bundle_loader.py
Kaggle entrypoint src/pca/submission/main.py
bundle builder src/pca/submission/build_bundle.py

最低限走らせるテスト:

PYTHONPATH=src uv run python -m unittest tests.test_encoder tests.test_module_boundaries

Rule Agent を触る人

読む順番:

  1. rule-agents.md
  2. training-selfplay.md
  3. recipes.md

主な実装入口:

Purpose Files
generic fallback src/pca/rule_agents/generic.py
heuristic library src/pca/rule_agents/heuristics.py
policy adapter src/pca/rule_agents/policy.py
registry src/pca/rule_agents/registry.py
individual agents src/pca/rule_agents/agents/*

最低限走らせるテスト:

PYTHONPATH=src uv run python -m unittest tests.test_rule_agents tests.test_selfplay_summary