開発環境

Kamae スキルに従うアプリケーション crate をローカルで立ち上げる手順である。スキルパッケージ本体の編集は スキルリポジトリの開発 を読む。

日常のチェックは 品質ゲート、フィクスチャの組み立ては テストデータ、CI への反映は CI セットアップ を参照する。

目的

Kamae が想定する方法でドメインコードを実装・テストできるワークスペースを整える。型付きドメインモデル、ポートベースのユースケース、コンストラクタ経由のフィクスチャを揃え、レビュアと CI が同じチェックに依存できる状態を目指す。

スキルに従う application crate 向けガイド。スキルパッケージ自体の編集はリポジトリルート DEVELOPMENT.md を参照。

テンプレートからの初回ブートストラップ

gh skill または npx skills でインストールした場合、リポジトリルートの Cargo.toml、rust-toolchain.toml、.github/workflows/ci.yml、scripts/validate_package.py などは同梱されない。プロジェクトブートストラップには ../assets/templates/ 配下のテンプレートを使う。

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

python3 path/to/kamae-rs/skills/kamae-rs/scripts/apply_templates.py --target . --ci backend

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

python3 path/to/kamae-rs/skills/kamae-rs/scripts/apply_templates.py --target . --ci skill-package

--force なしでは既存ファイルを上書きしない。既存リポジトリに適用するときは先に --dry-run を使う。

review probe の健全性チェック

ブートストラップ後、ドメインディレクトリで同梱 review probe を実行し、レビュー前に一般的な Kamae スタンス問題を捕捉する:

cargo run -q --manifest-path path/to/kamae-rs/Cargo.toml -p kamae-review-probe -- src/domain/ src/application/

review probe は既定では助言（advisory）モードである。出力は panic、unsafe 境界、serde derive、PII 用語、rustdoc の不足をレビューの手がかりとして扱い、チームが明示的に配線しない限り、失敗を伴うゲートにはしない。

推奨ローカルファイル:

• ../assets/templates/Cargo.toml -> Cargo.toml または既存 workspace manifest にマージ
• ../assets/templates/rust-toolchain.toml -> チームが MSRV または stable pin を共有するとき rust-toolchain.toml
• ../assets/templates/gitignore -> .gitignore または既存ファイルにマージ
• ../assets/templates/validate_package.py -> スキル/プラグインリポジトリのみ scripts/validate_package.py

コミット前に package.name、workspace members、[workspace.dependencies] を調整する。アプリケーションリポジトリでは単一 crate または 開発環境 の workspace レイアウトから始める。

初回セットアップ

フォーマットと lint コンポーネント付きで Rust をインストール:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup component add rustfmt clippy

Cargo.toml がまだないプロジェクトでは、先に同梱テンプレートをコピーしてから:

cargo check
cargo test
rustc --version

チームがバージョンを共有するときは toolchain を pin:

cp path/to/kamae-rs/skills/kamae-rs/assets/templates/rust-toolchain.toml .

ローカルチェックループ

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

クレートレイアウト、フェイクポート、テスト層、高速ループとフル pre-push ループの詳細は、本稿の後述セクションを参照する。

ツールチェーン

フォーマット、lint、ドキュメント component 付き Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup component add rustfmt clippy

チームが MSRV または stable を共有するとき toolchain を pin:

rust-toolchain.toml

[toolchain]
channel = "1.85.0"
components = ["rustfmt", "clippy"]
profile = "minimal"

domain 作業向け optional だが有用:

ツール	用途
cargo-nextest	大 workspace での高速 test
cargo-watch	domain 編集中の test 再実行
cargo-llvm-cov	移行中触った module のカバレッジ

domain crate ビルドは速く保つ。遷移や value object 反復中は workspace 全体より cargo test -p domain-crate を優先。

推奨 crate レイアウト

責務を分割し、domain ロジックを I/O と framework 型から解放。

my-service/
  Cargo.toml                 # workspace root
  crates/
    domain/                  # entities, value objects, transitions, domain errors
    application/             # use cases, port traits, use-case errors
    infrastructure/          # SQL/HTTP/queue adapters, outbox, telemetry wiring
    api/                     # Axum/tonic handlers, DTOs, composition root
  tests/                     # optional workspace integration tests

単一 crate プロジェクトは crate の代わりに module:

src/
  domain/
  application/
  infrastructure/
  api/
  main.rs                    # composition root

ルール:

• domain は sqlx、axum、tonic など I/O crate に依存しない
• handler と main が adapter を配線。ユースケースは port trait のみ（アプリケーション配線）
• DTO は所有境界（api、infrastructure）の近く。domain 内に置かない

ベースライン Cargo.toml 依存

既存利用から始める。Kamae スタイル bootstrap 時の common pairing:

[dependencies]
thiserror = "2"
serde = { version = "1", features = ["derive"] }
tracing = "0.1"

[dev-dependencies]
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
proptest = "1"
trybuild = "1"

依存があるとき crate-guides/ から crate guide を読み込む。guide があるからといって domain に crate を追加しない。

スキルトピック別 dev-dependencies

Topic	Typical dev-dependencies	Notes
Async use cases	tokio, tokio-test	#[tokio::test] で async port をテスト
Property tests	proptest, proptest-regressions	プロパティベーステスト
Compile-fail state safety	trybuild	テストデータ
HTTP boundary tests	axum, tower, http-body-util	fake use case で handler テスト
Persistence integration	testcontainers, sqlx (test feature)	任意。大半 domain test は fake
Fake time	time + injected clock trait	wall-clock flakiness 回避

integration-test 依存は adapter を所有する crate に。domain には置かない。

テスト層

不変条件を証明できる最下層で test。

層	テスト対象	I/O
Domain unit	constructors, transitions, domain errors	None
Use case	orchestration with fake ports	None
Adapter unit	SQL mapping, DTO TryFrom, redaction	Fake or in-memory
API/integration	handler -> use case -> adapter	Test DB or container optional
Property	input-wide laws	None in the property body

# Fast loop while editing domain code
cargo test -p domain --lib

# Use case tests with fakes
cargo test -p application --lib

# Full workspace before push
cargo test --all-targets --all-features

ドメイン層とユースケース層のテストに Docker は不要である。PostgreSQL や Redis などが本当に必要なのは、アダプター層の統合テストに限る。

Fake port とテストフィクスチャ

test 用 composition root に fake を注入。本番と同じ constructor でフィクスチャ構築（テストデータ）。

application/tests/support/fakes.rs

pub struct FakeRequestStore {
    pub saved: Mutex<Vec<(EnRouteRequest, Vec<TaxiRequestEvent>)>>,
}

impl RequestStore for FakeRequestStore {
    async fn save_assigned(
        &self,
        state: &EnRouteRequest,
        events: &[TaxiRequestEvent],
    ) -> Result<(), RepositoryError> {
        self.saved.lock().unwrap().push((state.clone(), events.to_vec()));
        Ok(())
    }
}

pub fn assign_driver_use_case() -> AssignDriver<FakeResolver, FakeRequestStore> {
    AssignDriver::new(FakeResolver::default(), FakeRequestStore::default())
}

ガイドライン:

• tests/support/ または #[cfg(test)] mod test_support で helper 共有
• fixture の expect のみ。メッセージに fixture 不変条件を述べる
• 欠けた振る舞いを隠す mega-mock より port ごと 1 fake

任意ローカルサービス

アダプター統合テストが実際のインフラを要する場合、チームで共有する推奨手順を 1 つに決め、文書化する。

docker-compose（シンプル、repo に check-in）:

compose.yaml

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: my_service_test
    ports:
      - "5432:5432"

testcontainers（test 内完結）:

• compose がない CI parity に good
• 遅い。infrastructure integration に限定

test 前に migration SQL または schema を load。ローカル dev DB を本番 credential に向けない。

環境と secret

• 非 secret placeholder の .env.example を commit。.env は git 外
• domain 内ではなく startup の config crate 経由で secret 読み取り
• ローカル log 前に PII 保護 ルール

.env.example

DATABASE_URL=postgres://postgres:dev@localhost:5432/my_service_test
RUST_LOG=info,my_service=debug

ローカル tracing には RUST_LOG + main の tracing-subscriber layer で足りる。domain 開発中 OpenTelemetry exporter は optional。

ローカル check ループ

品質ゲート と CI セットアップ に合わせる。編集中 fast path、PR 前 full path。

Fast path（触った crate）:

cargo fmt --all
cargo clippy -p domain -p application --all-targets -- -D warnings
cargo test -p domain -p application

Full path（pre-push）:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features

kamae-rs plugin を vendored/インストールしているプロジェクトは、レビュー依頼前に変更 Rust ファイルで review probe:

cargo run -q --manifest-path path/to/kamae-rs/Cargo.toml -p kamae-review-probe -- src/domain/ src/application/

probe 出力は review lead。自動失敗ではない。初回ブートストラップは本稿の「テンプレートからの初回ブートストラップ」を参照。

エディタとエージェント

rust-analyzer

• マシンが許せば rust-analyzer.check.command を clippy
• プロジェクトが文書化したときだけ rust-analyzer.rustfmt.extraArgs

Kamae skill

• domain 実装/refactor 時 Claude/Codex で kamae-rs skill を load
• crate 嗜好は kamae-rs リポジトリ の rules/ を参照
• エージェントを最初 Cargo.toml へ。crate guide と topic が正しく load される

Watch mode（optional）:

cargo watch -x 'test -p domain --lib'

新 domain module の bootstrap チェックリスト

1. domain / application crate（または module）を作成または特定
2. thiserror domain error と value-object constructor を追加
3. ユースケース前に valid/invalid 構築の単体 test
4. DB schema ではなく 1 ユースケース形の port trait
5. generic port field と test 内 fake adapter でユースケース実装
6. API または infrastructure 境界に DTO TryFrom
7. main または test bootstrap のみでユースケース配線
8. fast check loop。push 前 full path
9. diff に kamae-rs-review（または probe + 関連 checklist）

レガシー codebase では全体再構成前に 段階的導入 の導入ラダーを登る。

ローカルと CI が異なるとき

README または CONTRIBUTING.md に差分を明示:

• CI では test するがローカルではない feature flag
• optional Docker-only integration job
• MSRV job vs 開発者 stable toolchain
• advisory Miri/fuzz job

どの失敗がマージをブロックし、どれがスケジュール実行の助言（advisory）にとどまるのかを、開発者が README や CONTRIBUTING.md で確認できるようにする（CI セットアップ を参照）。

レビューでは、ドメイン crate のインフラ依存、fake port で足りるのに実 DB 必須のテスト、不変条件を迂回するテストヘルパ、文書化されていないローカル品質ゲート、コミットされた秘密や生 PII ログ、ドメインテストの HTTP / DB 直結を指摘する。

レビュー観点

シークレットと PII はコミット済み env ファイルから除外されているか — High

PII 保護 も照合する。コミットされた .env、例の実認証情報、デバッグのため生 PII をログするよう促すローカルセットアップドキュメントを指摘する。

ドメインコードは I/O 依存がないか — High

チームが Kamae 型の分割を掲げているのに、domain クレートやモジュールが sqlx、axum、tonic などのインフラクレートに依存している場合は指摘する。

テスト構成はクレート境界と一致しているか — Medium

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

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

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

フィクスチャはコンストラクタ経由で構築されているか — Medium

テストデータ も照合する。ドメイン / ユースケーステストで public フィールドリテラルや生 ORM 行により不変条件を迂回するテストヘルパを指摘する。

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

Kamae 慣習を採用しているのに、CI セットアップ と揃った高速パスとフル pre-push コマンド一覧がないプロジェクトを指摘する。