vibe-scratch-workflow

name	vibe-scratch-workflow
description	`vibe new` から `vibe shell-stdin --restore` で scratch-db を積み上げ、`finalize`/`normalize`/`apply` まで安全に回すための実践手順。

Vibe Scratch Workflow

使う場面

• 新しいライブラリを素早く試作したいとき
• .vibe の scratch namespace で段階的に設計を詰めたいとき
• tmp/tmp-hash-* 配下で何度も同じ検証を回したいとき

標準フロー

1. プロジェクト作成

vibe new tmp/tmp-hash-<id>/my_lib
cd tmp/tmp-hash-<id>/my_lib

2. scratch-db を固定する

export VIBE_SCRATCH_DB_PATH="$PWD/.vibe/namespaces/my_lib.db"

3. shell-stdin --restore で定義を積み上げる

printf '%s\n' \
  'export enum MyType { A; B }' \
  'export let f = (x: Int) -> Int { x + 1 }' \
  'exit' | vibe shell-stdin --no-prompt --restore

4. 追加の式や確認を同じ scratch-db で続ける

printf '%s\n' \
  'f(1)' \
  'exit' | vibe shell-stdin --no-prompt --restore

5. 仕上げ

vibe finalize --db "$VIBE_SCRATCH_DB_PATH" --library --export my_lib.vibe
vibe normalize --write my_lib.vibe
vibe check my_lib.vibe
vibe test my_lib.vibe
vibe fetch my_lib.vibe
vibe apply my_lib.vibe

ベストプラクティス

• shell-stdin は --restore を付けないと空の scratch source から始まる。
• 長い式や複数行入力は heredoc / printf '%s\n' ... でまとめて shell-stdin に渡す。
  • 直接クオートを重ねるより parse 崩れを起こしにくい。
• scratch-db を明示的に分けたいときは VIBE_SCRATCH_DB_PATH を固定する。
• finalize --library は未使用定義と副作用文を落としてからエクスポートできるため、ライブラリ整形の基準にする。
• scratch の破棄は vibe history reset、または対象 DB ファイルの削除で行う。
• エクスポート後の確認は vibe test my_lib.vibe と vibe symbols --json my_lib.vibe を基準にする。

Qualified Names（修飾名）

@ で始まるパッケージ参照では -（ハイフン）と /（スラッシュ）が識別子の一部として扱われる。 @ なしの場合、- は減算演算子、/ は除算演算子になる。 詳細は docs/language-tour/syntax-reference.vibe.md の "Qualified Names" セクションを参照。

反復デバッグ

• 同じワークフローの連続実行:

pkf run debug-scratch-workflow

• 便利な環境変数:
  • VIBE_SCRATCH_RUNS=50 実行回数
  • VIBE_SCRATCH_KEEP_SUCCESS=1 成功ケースも保持
  • VIBE_SCRATCH_CLI_BUILD=debug|release|skip CLI ビルドモード

scratch 反映後の検証

• exported module を lock/apply まで含めて確認する場合:

vibe finalize --db "$VIBE_SCRATCH_DB_PATH" --library --export my_lib.vibe
vibe fetch my_lib.vibe
vibe apply my_lib.vibe
vibe test my_lib.vibe

• scratch-db 自体は中間生成物なので、共有・レビュー対象は finalize 後の .vibe を優先する。