開発環境とセットアップ

スキルテンプレートからプロジェクトを立ち上げる担当者、および kamae-py スキルリポジトリのコントリビューター向けの手順書である。ツールチェーンとテンプレートの適用が揃っていないと、以降のドメイン規約をローカルで再現できず、CI 上だけが正しく見える状態になりやすい。

日常のチェックコマンドは品質ゲート、GitHub Actions の配線は CI セットアップを参照する。

プロジェクトのブートストラップ（テンプレートから）

このスキルを gh skill または npx skills でインストールしたとき、リポジトリルートの pyproject.toml、.github/workflows/ci.yml、scripts/validate_package.py などはスキルと一緒にはインストールされない。プロジェクトをブートストラップするときは ../assets/templates/ のテンプレートを使う。

最も手早い方法は、同梱スクリプトを使うことである。

python path/to/kamae-py/scripts/apply_templates.py --target . --ci backend

スキル/プラグインリポジトリ向け:

python path/to/kamae-py/scripts/apply_templates.py --target . --ci skill-package

スクリプトは --force がない限り既存ファイルを上書きしない。既存リポジトリに適用するときはまず --dry-run を使う。

ポリシーサニティチェック

ブートストラップ後、同梱ポリシーチェッカーを実行し、CI に到達する前に一般的な Kamae 方針の問題を検出する:

python path/to/kamae-py/scripts/check_kamae_policy.py --target .

tests/ もスキャンするには --include-tests を追加する。警告をエラー扱いするには --strict を使う。チェッカーはプロジェクト設定、禁止パッケージマネージャーファイル、frozen ドメインモデル、kind 判別共用体、純粋遷移、広い except や typing.cast などのリスクパターンをカバーする。

推奨ローカルファイル:

../assets/templates/pyproject.toml -> pyproject.toml または既存ファイルへマージ。
../assets/templates/gitignore -> .gitignore または既存ファイルへマージ。
../assets/templates/validate_package.py -> スキル/プラグインリポジトリのみ scripts/validate_package.py。

コミット前に project.name、description、[tool.mypy].files を調整する。アプリケーションリポジトリでは [tool.mypy].files は通常 src と tests を指す。スキルリポジトリでは scripts、examples、tests を含める。

初回セットアップ

uv と Python 3.12+ を使う。Docker は任意 — デフォルトはローカル Python ツールチェーンと、必要なときだけの任意コンテナ依存（例: Postgres 統合テスト）。

1. uv をインストールし Python をピン留め

curl -LsSf https://astral.sh/uv/install.sh | sh   # or brew install uv
cd your-project
uv python pin 3.13

2. テンプレートからブートストラップ（新規プロジェクト）

python path/to/kamae-py/scripts/apply_templates.py --target . --ci backend --dry-run
python path/to/kamae-py/scripts/apply_templates.py --target . --ci backend

3. 依存関係を同期

uv sync
uv lock
uv run python --version
uv run python -c "import pydantic; print(pydantic.__version__)"

プロジェクトにまだ pyproject.toml がないなら、まず同梱テンプレートをコピーしてから uv sync を実行する。

4. Docker なしのローカルサービス（任意）

統合テストに Postgres または Redis が必要なとき:

サービス	macOS (Homebrew)	Linux (apt)
PostgreSQL	`brew install postgresql@16 && brew services start postgresql@16`	`sudo apt install postgresql`
Redis	`brew install redis && brew services start redis`	`sudo apt install redis-server`

開発用データベースを作成し、設定をそこに向ける:

createdb myapp_dev
export DB_HOST=localhost DB_PORT=5432 DB_NAME=myapp_dev DB_USER=$USER DB_PASSWORD=

pydantic-settings で .env を使う（境界防御を参照）。.env を .gitignore に追加する。

5. ツールチェーンの検証

uv run ruff format --check .
uv run ruff check .
uv run mypy .
uv run pytest
python path/to/kamae-py/scripts/check_kamae_policy.py --target . --include-tests

6. エディタ統合

IDE で Ruff をフォーマット/リントプロバイダーとして有効化する。
uv sync 後、インタープリタを .venv/bin/python に設定する。
Pydantic mypy プラグインが解決されるよう、プロジェクトルートから uv run mypy を実行する。

ローカルチェックループ

ブートストラップ後、品質ゲートのベースラインコマンドを実行する。スキル/プラグインリポジトリではさらに uv run python scripts/validate_package.py を実行する。

チームがコミット前の自動フォーマットを望むなら、品質ゲートから pre-commit フックをインストールする。

mypy と Pydantic プラグイン設定については、../assets/templates/pyproject.toml をマージするか、ドメインモデリングに従う。

Docker を追加するタイミング

次のときに Docker または Compose を使う:

本番同等性に正確なイメージバージョンが必要。
オンボーディングで Postgres/Redis をローカルインストールさせたくない。
CI が統合テストに同じ docker compose up を使う。

ドメイン単体テストはコンテナなしで uv run pytest 実行可能に保つ。統合テストはマーカー（pytest -m integration）または任意 compose プロファイルの背後に置く。

kamae-py リポジトリでの開発

前提条件

uv がインストールされ PATH で利用可能であること。
プロジェクトの範囲に合う Python バージョン。このリポジトリは .python-version でローカル Python をピン留めしている。

クローンとブートストラップ

git clone <repository-url>
cd kamae-py
uv python install
uv sync

uv python install は .python-version を読み、未インストールならピン留めパッチリリースをインストールする。uv sync は仮想環境を作成し、ロック済み依存関係をインストールする。

インストールの検証

uv run python --version
uv run python -c "import pydantic; print(pydantic.__version__)"
uv run pytest

変更前にすべてのテストが通るべきである。

ローカル品質ゲートの実行

品質ゲートのベースラインコマンドを実行する。このリポジトリではさらに次を実行する:

uv run python scripts/validate_package.py
uv run python skills/kamae-py/scripts/check_kamae_policy.py --include-tests --strict
uv run ruff format --check .

フォーマットチェックが失敗したら uv run ruff format . で適用する。

スキルパッケージの作業

スキルは skills/kamae-py/ にある:

SKILL.md — ディスパッチガイドと frontmatter。
“ — 詳細リファレンス文書。
scripts/ — apply_templates.py、check_kamae_policy.py などのヘルパースクリプト。
assets/templates/ — インストール可能なプロジェクトテンプレート。

新しいリファレンス文書を追加したら、SKILL.md からリンクし、スキルディスパッチャーが表面化できるようにする。scripts/validate_package.py がチェックできるよう相対リンクを優先する。

プロジェクト固有のルール形式は kamae-py リポジトリの rules/ を参照。

check_kamae_policy.py を変更したら、tests/test_check_kamae_policy.py にテストを追加または更新する。

テスト用テンプレート適用

scripts/apply_templates.py はテンプレートをターゲットディレクトリにコピーする。テンプレート変更をこのリポジトリに影響させずテストするには一時ディレクトリを使う:

mkdir -p /tmp/kamae-test
uv run python skills/kamae-py/scripts/apply_templates.py --target /tmp/kamae-test --ci backend --force

既存プロジェクトに適用するときは、まず --dry-run を使う。

依存関係の変更

依存関係を追加または削除したら uv.lock を更新する:

uv add <package>
# or
uv remove <package>
uv lock

CI は uv sync --locked を実行するため、古いロックファイルでビルドは失敗する。

コミット前

上記のローカル品質ゲート一式を実行する。
意図しないテンプレートまたはロックファイル変更がないか git diff を確認する。
コミットは内容を絞る。1 つの論理変更につき 1 コミットとする。たとえば新しいリファレンス文書とその SKILL.md へのリンクは 1 コミットにまとめ、依存関係の更新は別コミットに分ける。

トラブルシューティング

Mypy が pydantic.mypy プラグイン欠如を報告: [tool.mypy] plugins = ["pydantic.mypy"] が設定され、仮想環境が uv run 経由で有効であることを確認する。
ロックファイルのドリフト: uv lock を実行し、更新された uv.lock をコミットする。
新リファレンスでポリシーチェッカー失敗: チェッカーはデフォルトで src/ と tests/ のみ検査する。スキルリポジトリは --include-tests でチェックされる。別の場所にコードを追加したら、[tool.mypy].files にパスを追加するか、適切なスコープでチェッカーを実行する。

レビュー観点

コミットされた env ファイルにシークレットと PII がないか — High

PII と観測経路の保護と照合する。コミットされた .env、例の実認証情報、デバッグ用に生 PII をログするよう促すローカルセットアップ文書を指摘する。

ドメインコードはフレームワークと ORM の import がないか — High

チームが Kamae スタイルの分離を主張しているのに、domain モジュールが FastAPI、Django モデル、SQLAlchemy セッション、boto3、その他インフラクレートを import する箇所を指摘する。

テスト配置はレイヤー境界に合っているか — Medium

ユースケース層のフェイクやインフラ層のアダプターではなく、ドメインテストが HTTP サーバーや DB プールを直接引く配置を指摘する。

ドメインとユースケースのテストは Docker なしで動くか — Medium

基本的な遷移やユースケーステストにフェイクポートで足りるのに、ライブ DB や外部サービスを要求するワークフローを指摘する。

フィクスチャはコンストラクタ経由で組み立てられているか — Medium

テストデータと照合する。ドメイン/ユースケーステストで生 dict、model_construct、ORM 行により不変条件を迂回しているテストヘルパーを指摘する。

文書化されたローカルチェックループがあるか — Low

CI セットアップと整合するファストパスとフル pre-push コマンド一覧なしに Kamae 規約を採用するプロジェクトを指摘する。