Implementation Recipes

更新日: 2026-07-05

よくある変更作業の手順書である。変更対象、関連 docs、テストを一緒に確認する。

新しい search value profile を追加する

読む docs:

• search.md
• search-ismcts.md
• test-map.md

手順:

1. src/pca/search/mcts.py の SearchValueConfig に必要な weight を追加する。
2. search_value_config_for_profile() に profile 名と default weight を追加する。
3. self-play CLI の --search-value-profile choices を更新する。
4. evaluation CLI の --search-value-profile choices を更新する。
5. 必要なら src/pca/training/selfplay/cli.py / src/pca/evaluation/tournament/impl.py の default 補正を追加する。
6. tests/test_encoder.py に value sign、terminal value、aux/progress の期待値を追加する。
7. docs/architecture/modules/search.md と source-design.md を更新する。

確認:

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

self-play JSONL に field を追加する

読む docs:

• training-selfplay.md
• training-data.md
• artifacts.md

手順:

1. schema field なら src/pca/training/targets.py の dataclass に default 付きで追加する。
2. game 中に作る値なら training/selfplay/records.py または record_targets.py / record_metadata.py に追加する。
3. JSONL load 互換のため training/data/records.py の record_from_dict() を確認する。
4. batch tensor に必要なら training/data/search_collate.py または belief_collate.py に追加する。
5. loss に使うなら training/policy_value/losses.py に metrics と mask を追加する。
6. round-trip / backward compatibility test を追加する。
7. artifacts.md の schema 説明を更新する。

確認:

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

新しい model head を追加する

読む docs:

• models.md
• training-policy-value.md
• training-data.md

手順:

1. src/pca/models/policy_value_unified/heads.py に head module を追加する。
2. model.py の output dict に head output を追加する。
3. target が必要なら training/targets.py と JSONL generation を更新する。
4. training/data/search_collate.py で target tensor と mask を作る。
5. training/policy_value/losses.py で loss と metrics を追加する。
6. training/policy_value/checkpointing.py に config metadata を保存する。
7. training/policy_value/model_config.py で checkpoint 互換を確認する。
8. model forward / loss / checkpoint load のテストを追加する。

確認:

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

新しい rule agent を追加する

読む docs:

• rule-agents.md
• training-selfplay.md

手順:

1. src/pca/rule_agents/agents/<agent_id>/ に agent package を作る。
2. package の __init__.py から Agent を export する。
3. 必要な heuristic を heuristics.py または agent 内に実装する。
4. registry YAML に agent_id, class_path, deck_csv, compatibility metadata を追加する。
5. rule_pool_policy_factory() で assignment metadata が付くことを確認する。
6. teacher policy weight を使う場合は decision.meta の weight keys を確認する。
7. rule-agent test と self-play record test を追加する。

確認:

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

evaluation metric を追加する

読む docs:

• evaluation.md
• artifacts.md

手順:

1. metric の元データが self-play/evaluation summary にあるか確認する。
2. evaluation/tournament/types.py の dataclass に field を追加する場合は default を付ける。
3. evaluation/tournament/impl.py の match loop で値を集める。
4. evaluation/tournament/summaries.py で aggregate と CSV row を更新する。
5. CLI output / JSON output の互換を確認する。
6. tests に summary aggregation と CSV output の期待値を追加する。

確認:

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

public API / facade を追加する

読む docs:

• api-reference.md
• test-map.md

手順:

1. 実体 module の __all__ に公開名を追加する。
2. package facade (__init__.py, types.py, summary.py, dataset.py など) に re-export する。
3. tests/test_module_boundaries.py に assertIs と __module__ の期待値を追加する。
4. api-reference.md と対応 module docs に API を追加する。

確認:

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

最新デフォルト CLI profile を更新する

読む docs:

• tools-and-config.md
• api-reference.md

手順:

1. 新しい世代の標準 config を configs/vNN/ に追加する。
2. configs/default.yaml の commands で selfplay, train, eval, selfplay-train が新 config を指すようにする。
3. 必要なら README.md の default profile 説明を更新する。
4. pca --print-command train で delegated command が想定通りか確認する。
5. tests/test_app_config.py に profile load / argv 変換の期待値を追加する。

確認:

PYTHONPATH=src uv run python -m unittest tests.test_app_config tests.test_cli_config
pca commands
pca --print-command train --input data/selfplay/custom.jsonl