# 新規プロジェクトへの flaker 導入チェックリスト
[English](new-project-checklist.md)
新しいリポジトリで flaker を「即日 → 1 週 → 1 ヶ月」の段階で価値を出すための手順書。0.7.0 以降を前提とする。
Day 1 は `init → doctor → plan → apply → status` の 5 ステップで収束させる。順に実行すれば 30 分で初期セットアップが終わり、1 週間で計測ベースが整い、2〜4 週間で CI gating に昇格できる状態になる。
---
## Day 0: 前提確認 (5 分)
```bash
node --version # >= 24
pnpm --version # >= 10
git remote -v # origin が GitHub を指している
gh auth status # ログイン済み (flaker apply で履歴収集するときに必要)
```
GitHub Actions を使っていない / 履歴が無い場合も問題ない。`flaker apply` は履歴ゼロの repo では cold-start 経路 (local run で self-seed) を選ぶので、Day 1 の手順はそのまま通る。CI 履歴は後から自然に溜まる。
`moon` (MoonBit) は不要。flaker は `dist/moonbit/flaker.js` を bundle 済みで配布し、無ければ TypeScript fallback (`src/cli/core/loader.ts`) で動く。
---
## Day 1: インストールから収束まで (15 分)
Day 1 は次の 5 ステップで完結する。個別のキャリブレーション / 履歴取り込みは `flaker apply` が内部で面倒を見るので、ユーザーが順序を覚える必要はない。
### 1. インストール
```bash
pnpm add -D @mizchi/flaker
```
### 2. `flaker.toml` を生成
adapter / runner をその場で指定:
```bash
# 例: vitest プロジェクト
pnpm flaker init --adapter vitest --runner vitest
# 例: playwright e2e
pnpm flaker init --adapter playwright --runner playwright
# 例: jest
pnpm flaker init --adapter jest --runner jest
# 例: actrun (GitHub Actions ローカル実行) で playwright をラップ
pnpm flaker init --adapter playwright --runner actrun
```
owner / name は git remote から自動検出される。`--owner` / `--name` で上書き可。
0.7.0 以降、`flaker init` は `[profile.scheduled]` / `[profile.ci]` / `[profile.local]` の既定値も同時に書き込む。
### 3. doctor で環境チェック
```bash
pnpm flaker doctor
```
期待する出力:
```
OK config flaker.toml is readable
OK config ranges all values within expected ranges
OK duckdb DuckDB initialized successfully
OK moonbit MoonBit JS build detected (or fallback)
Doctor checks passed.
```
DuckDB が落ちる場合は `node --version` が 24 未満の可能性が高い。
### 4. affected resolver を設定
`flaker run --gate iteration` / `hybrid` strategy を活かすには resolver の設定が必要。`flaker init` の既定は `simple`。プロジェクトの形に合わせて `flaker.toml` の `[affected]` セクションを編集:
```toml
# 単一 package / フォールバック (init 既定。vitest / jest ライブラリでまずこれ)
[affected]
resolver = "simple"
config = ""
# pnpm / npm / yarn workspaces を使っているモノレポ
[affected]
resolver = "workspace"
config = ""
# glob ルールを手で書く (flaker.affected.toml を別途作成)
[affected]
resolver = "glob"
config = "flaker.affected.toml"
# bitflow を使っている場合
[affected]
resolver = "bitflow"
config = "flaker.star"
# MoonBit プロジェクト
[affected]
resolver = "moon"
config = ""
```
resolver を設定しないと `hybrid` は `weighted` / `random` フォールバックで動くだけ。選択の目安:
- 単一 package なら `simple` のまま
- monorepo なら `workspace` (最も楽)
- 細かい依存ルールが要るなら `glob`
詳細表は [how-to-use.ja.md 依存分析の設定](how-to-use.ja.md#依存分析の設定) を参照。
### 5. `flaker plan` で差分を確認
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker plan
```
`flaker.toml` を desired state として、今 DB に何が欠けているかを planner が示す。履歴ゼロの repo なら `collect_ci` + `cold_start_run` が、`[quarantine].auto=true` のときは `quarantine_apply` も plan に載る。
### 6. `flaker apply` で収束させる
```bash
pnpm flaker apply
```
`flaker apply` は `collect` / `calibrate` / `quarantine apply` を現状に応じて自動で順に実行する idempotent コマンド。同じコマンドを cron や nightly で回しても状態が壊れない。
### 7. `flaker status` で確認
```bash
pnpm flaker status
```
サマリダッシュボードが 1 画面で出る。Day 1 段階では `data confidence: insufficient` が出て普通。1 週間運用すると自然に `moderate` に上がる。
---
## Day 2-3: 継続的な apply
`flaker apply` は idempotent なので、Day 2 以降は「1 日 1 回走らせておく」だけで十分。手動で `collect` / `calibrate` を順に叩く必要はない。
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker apply
pnpm flaker status # 日次ダッシュボード
pnpm flaker status --detail # KPI ビュー (旧 analyze kpi)
```
内部で何が走っているか知りたい・個別コマンドで掘りたい場合
`flaker apply` は内部的に以下を現状に応じて実行する。単体で叩きたい場合は直接呼んでもよい (0.7.0 以降はすべて deprecated / hidden、`flaker apply` が canonical)。
**CI 履歴取り込み:**
```bash
export GITHUB_TOKEN=$(gh auth token)
pnpm flaker collect ci --days 30
```
**キャリブレーション:**
```bash
pnpm flaker collect calibrate
```
`flaker.toml` の `[sampling]` セクションに最適な戦略・サンプル率が書き込まれる。`--dry-run` を付ければ書き込まずに推奨だけ見られる。
データが少ないとき (commits < 20) は `confidence: insufficient` か `low` の警告が出るが無視して続行 OK。1 週間後に再度 `flaker apply` を回せば自然に更新される。