開発・品質チェック¶

このページでは、実装変更時に使うformatter、linter、テスト、ドキュメントのビルド、pre-commitの手順を説明します。変更内容ごとのテスト範囲はテストマップを参照してください。

開発依存関係¶

uv sync --group dev --group docs
npm install
uv run pre-commit install

PythonはRuffとpytest、Markdown / YAML / JSON / TOMLはPrettier、shell scriptはShellCheckで検証します。

Python¶

リポジトリ全体を確認する場合:

uv run ruff check src tests
uv run ruff format --check src tests

変更ファイルだけを確認・整形する場合:

uv run ruff check path/to/file.py
uv run ruff format --check path/to/file.py
uv run ruff format path/to/file.py

無関係なファイルをまとめて整形せず、変更した範囲を中心に実行します。

Python以外¶

確認:

npm run format:check -- README.md docs/**/*.md configs/**/*.yaml

変更ファイルの整形:

npm run format -- path/to/file.md path/to/config.yaml

shell scriptを変更した場合はpre-commit経由またはShellCheckを直接実行します。

テスト¶

全pytest:

uv run --group dev pytest -q

よく使う部分テスト:

uv run --group dev pytest tests/test_module_boundaries.py
uv run --group dev pytest tests/test_encoder.py tests/test_training.py tests/test_reranker.py

変更種別ごとの基準:

変更	主なテスト
module boundary	`tests/test_module_boundaries.py`
encoder / model input	`tests/test_encoder.py`とtraining系
self-play / training record	`tests/test_training.py`とself-play / promotion系
submission bundle	`tests/test_submission.py`
rule agent	`tests/rule_agents/`

詳細はTest Mapを参照してください。

ドキュメント¶

ローカルserver:

mise run docs:serve

strict build:

uv run --group docs mkdocs build --strict

VS CodeではTasks: Run Taskからdocs: serveを起動し、Simple Browserでhttp://127.0.0.1:8000を開きます。

現行仕様はdocs/architecture/、運用手順はdocs/operations/、実験途中の仮説はdocs/research/、作業履歴はdocs/journal/へ置きます。

コミット前の確認¶

staged fileをcommit前と同じ条件で確認します。

uv run pre-commit run

hookはcommit時にも自動実行されます。全ファイルへの一括修正は意図しない差分を増やすため、通常はstaged fileまたは変更ファイルを対象にします。

生成物¶

次のディレクトリはソースコードではなく生成物として扱います。

data/          self-play / evaluation data
checkpoints/   model checkpointとlatest alias
logs/          長時間run、manifest、metrics
dist/          submission bundle
site/          MkDocs build output

大きな生成物は原則commitしません。schemaとlatest aliasの規約は生成物一覧を参照してください。

変更時の確認順¶

変更したmoduleのnarrow testを実行する。
変更ファイルへRuffまたはPrettierを実行する。
public API、CLI、config、artifact形式を変えた場合はmodule docsを更新する。
module boundary変更時はboundary testを実行する。
可能なら全pytestとMkDocs strict buildを実行する。

実装上の共通ルールはリポジトリ直下のAGENTS.md、コードの責務境界はソースコード設計を参照してください。