AI エージェント運用 Runbook¶

AI エージェントやコーディング支援ツールが、この repo で 短いコンテキストのまま安全に作業するための正本です。AGENTS.md には要約だけを残し、詳細手順はこの文書へ寄せます。

目的¶

毎ターン読み込むルール量を減らす。
develop worktree を壊れた状態で放置しない。
探索対象から tmp / node_modules / build artifact を外し、ノイズを減らす。
CI 調査や develop 同期のような反復作業を短い手順に標準化する。

初動チェック¶

着手時はまず以下だけ確認します。

git status --short --branch
git worktree list --porcelain
just ai-find-agents
必要な局所 AGENTS.md だけを読む

develop worktree は通常、origin/develop と一致した clean state を保ちます。作業は topic branch / 別 worktree に分離し、日常作業の文脈と修正対象の文脈を混ぜません。

探索ルール¶

repo 全体探索では、以下を既定で除外します。

node_modules
tmp
output
.next
dist
.turbo
.wrangler
.playwright-cli
.playwright-mcp
dist-cosmos
.docker-test
test-results
playwright-report
blob-report
.vitest-attachments
apps/wordpress-cms/**/vendor

標準入口:

just ai-rg <pattern>
just ai-find-agents
./scripts/ops/ai-rg.sh <pattern>
./scripts/ops/ai-find-agents.sh

find や rg を直接叩く場合も、同等の除外条件を維持してください。artifact 配下の AGENTS.md や vendored source を拾って判断しないことが重要です。改行を含む pattern を rg で確認する場合は、通常の regex ではなく rg -U を明示します。

ローカル CPU 負荷の既定¶

ローカル実行では Nx と Vitest の並列が掛け算になりやすいため、既定を控えめにしています。

root の affected 系 script は既定で NX_LOCAL_PARALLEL=4、coverage は NX_LOCAL_PARALLEL=1。手元の CPU / メモリが厳しい環境では NX_LOCAL_PARALLEL=2 などへ下げる。
dev:workspaces は NX_DEV_PARALLEL=3。
Vitest は VITEST_MAX_WORKERS 未指定時、local で 2、CI で原則 50%。Vendure integration は CI 4 / local 2。
local の Vendure Docker image build は BuildKit max-parallelism=2 と file lock で直列化する。必要時は BUILDKIT_MAX_PARALLELISM / BUILDX_BUILD_LOCK_FILE で上書きする。

重い検証を意図して並列を上げる場合は、上記 env を明示し、別 agent や deploy/build と重ねないでください。

局所 Vitest 実行¶

package 配下の単体テストを局所実行するときは、root から path を直接渡すより pnpm --filter <package> exec vitest run <package-relative-path> を使います。

例:

pnpm --filter @ritsubi/contract exec vitest run src/custom-fields/definitions.test.ts

root で pnpm exec vitest run packages/... を直接叩くと、tmp/ 配下の検証用 worktree に同名 path がある場合まで拾い、依存解決が別 workspace として扱われて失敗することがあります。

ローカルメモリ負荷の既定¶

Node 系ツールはデフォルトのままだと、Nx / TypeScript / Vite / ESLint / Vitest が同時に heap を広げてメモリを圧迫しやすいです。

root の affected 系 script は scripts/ops/with-node-memory-limit.sh 経由で実行し、NODE_OPTIONS に --max-old-space-size が未指定なら 4096MB を付与する。
既定値は RITSUBI_NODE_MAX_OLD_SPACE_SIZE_MB で変更できる。例: RITSUBI_NODE_MAX_OLD_SPACE_SIZE_MB=3072 pnpm run typecheck。
ESLint は局所的に重くなりやすいため、root / packages/plugins とも RITSUBI_ESLINT_NODE_MAX_OLD_SPACE_SIZE_MB で個別に上書きできる。
VS Code の tsserver は workspace 既定で 3072MB、project diagnostics / package.json auto import / automatic type acquisition は抑止する。
Nx / rg / VS Code watcher は WordPress vendor、output/、tmp/、 test-results、Playwright report、.wrangler、.playwright-*、 .vitest-attachments、巨大 sourcemap を探索・監視対象から外す。

OOM が出る場合だけ一時的に上限を上げ、通常運用では並列数を先に下げてください。heap 上限を上げると失敗しにくくなる一方、他プロセスを巻き込んで swap しやすくなります。

develop 同期の標準手順¶

develop 自体で作業を進めないことが前提です。常用 worktree は更新専用とし、必要なら別 worktree に branch を切ります。

develop worktree で git status --short --branch を確認する。
rebase / merge の途中なら、先に git rebase --abort または git merge --abort で未完了状態を解消する。
develop にローカル専用コミットがある場合は、必要に応じて退避 branch を切る。
git fetch origin --prune
git checkout develop
git reset --hard origin/develop
修正作業は git worktree add ../<repo>-<topic> -b <branch> develop で別 worktree に切り出す。

develop にローカル専用コミットを積み続けると、状態説明・衝突解消・復旧会話が増え、トークン効率が悪化します。

Worktree 衛生¶

git worktree list --porcelain で stale worktree を定期確認する。
既に消えた path を指す prunable な worktree は棚卸し対象とする。
detached HEAD や rebase 中のまま放置された常用 worktree を見つけたら、その場で復旧または退避する。
Portless の URL / state は worktree 単位で分離し、起動/再起動はその worktree の just から行う。

worktree 運用の全体方針は docs/04-project-management/branch-strategy.md と docs/04-project-management/port-allocation.md を参照してください。

Nx Cloud とリモートキャッシュ¶

ここは 2 つの独立した軸を扱う。混同しない。

Nx Cloud / DTE（分散タスク実行）= 無効。nx.json に nxCloudId を置かず neverConnectToCloud: true を正本にする。CI / ローカルとも NX_NO_CLOUD=true。
self-hosted remote cache = 稼働中。Nx Cloud とは別系統で、nx affected の codegen / build / typecheck の出力を run 跨ぎで再利用している。NX_NO_CLOUD=true とは独立に動く。

Nx コマンド自体は引き続き推奨。通常は scripts/ops/nx.sh または同 wrapper を呼ぶ pnpm / just recipe を使う。

self-hosted remote cache（稼働中・SSOT）¶

公式 self-hosted cache plugin は CVE-2025-36852 "CREEP" で deprecated のため、自前の OpenAPI 互換 server apps/nx-cache（Cloudflare Worker + R2） を使う。エンドポイントは https://ritsubi-nx-cache.ritsubi.workers.dev。

配線: .github/actions/nx-offline-cache-env/action.yml が /health を probe し、200 なら NX_SELF_HOSTED_REMOTE_CACHE_SERVER / NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN / NX_DISABLE_REMOTE_CACHE=false を $GITHUB_ENV へ export する。token / server 未供給（fork PR 等）や health 不達のときは NX_DISABLE_REMOTE_CACHE=true で offline fallback（CI は落とさず local cache only）。
各 reusable workflow は nx-cloud-token input を受け取り、ci-pr-* から protected branch=RW / PR=RO を伝播する。write は RW のみ・PR は RO・409 immutable で CREEP（cache poisoning）を封殺する。詳細は apps/nx-cache/README.md。
動作確認: run log に > nx run <project>:codegen [remote cache] と Nx read the output from the cache instead of running the command for N out of N tasks、env に NX_DISABLE_REMOTE_CACHE: false が出ていればヒットしている。

トークン運用¶

下表のトークンは self-hosted remote cache のアクセストークンとして使う（Nx Cloud を再有効化する場合は同トークンを Cloud 側でも流用する想定）。

用途	Secret 名	権限
protected branch push（`main` / `develop` / `release/*`）	`NX_CLOUD_ACCESS_TOKEN_RW`	read-write
PR / unprotected branch	`NX_CLOUD_ACCESS_TOKEN_RO`	read-only

トークンは GitHub Actions Secrets に格納し、各 workflow から nx-cloud-token input として nx-offline-cache-env へ渡す。同 action は NX_NO_CLOUD=true（Nx Cloud 認可は起動しない）を立てつつ、self-hosted remote cache 側だけを有効化する。

DTE（分散タスク実行）¶

PR 品質ゲート（_ci-pr-core-quality.yml）には DTE の定義が残っているが、既定では neverConnectToCloud: true により起動しない。

仕組み:

[core ジョブ（オーケストレーター）]        [nx-cloud-agents × 2（並列）]
  codegen → verify（ローカル実行）
  ↓
  nx-cloud start-ci-run               ←→  nx-cloud start-agent（タスク待機）
  nx affected --target=lint               ↑ タスクを受け取り並列実行
  nx affected --target=typecheck
  nx affected --target=test
  nx affected --target=build
  nx-cloud stop-all-agents

codegen と検証ステップはオーケストレーターのみで実行（生成物の整合チェックが必要なため）。
lint / typecheck / test / build の各プロジェクトレベルタスクをエージェントに分散し、ウォールクロック時間を短縮する。
NX_CLOUD_ACCESS_TOKEN が未設定の場合（fork PR 等）または neverConnectToCloud: true の場合は start-ci-run と start-agent をスキップし、オーケストレーターのローカル実行にフォールバックする。

関連ファイル:

ファイル	役割
`.github/workflows/_ci-pr-core-quality.yml`	オーケストレーターと `nx-cloud-agents` ジョブの定義
`.github/actions/nx-offline-cache-env/action.yml`	トークン注入と `NX_DEFAULT_OUTPUT_STYLE=static` 設定

ローカル開発¶

ローカル開発では Nx Cloud に接続しない。scripts/ops/nx.sh は NX_NO_CLOUD=true / NX_DISABLE_REMOTE_CACHE=true を補助的に付与し、nx.json の neverConnectToCloud: true が直叩きも含めた最終的な kill-switch になる。

加えて scripts/ops/nx.sh はローカル実行で NX_DAEMON=false を既定にする。Nx daemon の file-watcher が編集を取りこぼすと stale な file hash でキャッシュキーを誤計算し、古い dist/ を復元してしまう。実際に packages/config / packages/plugins の古い dist が復元され、@ritsubi/config / @ritsubi/plugins の import が解決できず just dev-full-vscode（_sync-dev-runtime-baseline の build chain）が落ちる障害が起きた。daemon を切ると毎回 disk から hash を取り直すため、この stale 復元クラスを根絶できる。キャッシュ自体は有効なまま（真に未変更なら cache hit で高速復元）で、追加コストは graph 計算の数秒のみ。CI の ephemeral runner では staleness が起きず daemon の高速化メリットが大きいため、cloud token 付き CI では daemon を残す。NX_DAEMON=true を明示 export すればローカルでも daemon を使える。

stale cache を疑う症状（直前の編集が反映されない / 説明のつかない型・モジュール解決エラー）が出たら ./scripts/ops/nx.sh reset で daemon とキャッシュをクリアして再ビルドする。

pnpm run typecheck などの package script から Nx option を追加する場合、pnpm run typecheck -- --skipNxCache のように -- の後へ置くと、対象 target の tsc へそのまま転送され error TS5023: Unknown compiler option '--skipNxCache' になる。cache を無効化して確認したい場合は scripts/ops/nx.sh affected --target=typecheck --outputStyle=static --skipNxCache のように Nx を直接呼び出す。

Nx Cloud を明示的に再有効化する場合¶

Nx Cloud を使う必要がある場合は、admin で Nx Cloud workspace の有効状態と課金を確認し、DTE / remote cache の必要性を判断してから nx.json に nxCloudId を戻し、neverConnectToCloud を false に戻す。.github/actions/nx-offline-cache-env/action.yml の HTTP probe が通れば CI は cloud mode へ戻る。

Free プラン超過などで workspace が無効化されている状態で neverConnectToCloud を戻すと、"Workspace is unable to be authorized" や workspace status probe 失敗で CI / local 実行が不安定になるため、先に workspace 側を復旧する。

過去の経緯¶

以前は neverConnectToCloud: true と全 CI workflow での NX_NO_CLOUD=true / NX_DISABLE_REMOTE_CACHE=true によって無効化していた（CHANGELOG 参照）。2026-05-18 にリモートキャッシュを再有効化し、2026-05-19 に DTE を追加したが、Free プラン超過時にローカル作業まで Nx Cloud 認可失敗へ巻き込まれたため、Nx Cloud / DTE は再び offline に戻した。その後、Nx Cloud 課金と切り離して remote cache の恩恵だけを得るため、自前の self-hosted remote cache（apps/nx-cache, Cloudflare Worker + R2）を導入し、これが現在の正本。Nx Cloud / DTE は無効のまま、remote cache だけが稼働している。

CI ゲート 2 層構成（PR-smoke / merge-queue-full）¶

ci-pr-develop.yml は PR と merge queue（merge_group イベント） で実行内容を切り替えます。

レイヤ	トリガー	実行内容	目標時間
PR-smoke	`pull_request`	lint / typecheck / unit（DTE）, coverage, dashboard-worker, storefront mock smoke, wrangler types	< 12 min
merge-queue-full	`merge_group`	PR-smoke 全項目 + integration ×2 shard, provider-contract, dashboard-all-smoke, storefront CT, Cloudflare build	< 25 min

必須チェック名¶

ci/required-develop — 両イベントで green が必要。PR では heavy gate を skip し skipped が通過扱い。

heavy gate の判定¶

vendure-quality-heavy / storefront-ct / storefront-cloudflare-build の if 条件が merge_group のときのみ有効化される。

ローカル dev stack (process-compose)¶

just dev-full / just dev-storefront-stack / just dev-dashboard-stack / just dev-storefront-bypass は process-compose が orchestration の正本。process-compose.dev.yaml に全 service の依存関係 / readiness probe / restart policy が宣言済みで、各 stack は namespace (core / cms / dashboard / storefront / bypass / banner-*) の組合せで出し分けます (scripts/dev/run-process-compose.sh)。

AI が dev 起動を扱うときの要点:

「Vendure だけ立っていない / Dashboard だけ生きている」状態は process-compose の depends_on: process_healthy が解決しているはずなので、観測されたら tmp/dev-logs/vendure-app.log を一次情報にする。
Vendure 内側の HMR は apps/vendure-server/scripts/dev-vendure-watch.mjs (debounce + boot gate)、外側の crash respawn は process-compose の availability.restart: on_failure。両者は二重化ではなく階層化で、内側は HMR の fast path、外側は内側が完全に死んだ時の網。
just dev-stop は UDS (tmp/dev-logs/process-compose.sock) 経由で process-compose down を投げてから docker compose を停止する。raw pkill で個別プロセスを殺さないこと (process-compose が即 respawn する)。
ログは tmp/dev-logs/<service>.log を読む。別ターミナルで process-compose attach -U を開くと TUI でタブ切替できる。

トラブルシュート事例¶

Vendure がクラッシュし続け、`migrate:run` が失敗する (2026-05)¶

症状: just dev-full-vscode を起動すると ritsubi-vendure-server:migrate:run が失敗し、tmp/dev-logs/vendure-app.log に次のエラーが繰り返す。

Nest can't resolve dependencies of the SmilePriceMasterService (TransactionalConnection, ?).
SmileSalesRateClassService at index [1] is not available in CommercialRulesPlugin.

原因: CommercialRulesPlugin の providers に SmilePriceMasterService は登録されていたが、その依存サービス SmileSalesRateClassService が未登録だった。NestJS DI が解決できずクラッシュループに入る。

修正: packages/plugins/src/rule-engine/commercial/index.ts の providers 配列に SmileSalesRateClassService を追加（SmilePriceMasterService より前に記載）。

providers: [
  CommercialRuleService,
  CommercialOrderLineListener,
  PriceCalculationService,
  SmileSalesRateClassService,   // ← 追加
  SmilePriceMasterService,
],

tsx/esbuild が TypeORM の `ColumnTypeUndefinedError` を引き起こす (2026-06)¶

症状: pnpm exec tsx で Vendure 設定を読む ops script / CI dry-run が起動時に次のエラーで落ちる。

ColumnTypeUndefinedError: Column type for XxxEntity#field is not defined and cannot be guessed.
Make sure you have turned on an "emitDecoratorMetadata": true option in tsconfig.json.

原因: tsx は内部で esbuild を使う。esbuild は experimentalDecorators には対応しているが、TypeORM が型推論に必須の emitDecoratorMetadata を出力しない。そのため Reflect.getMetadata("design:type", ...) が undefined になり、型指定のない @Column() でエラーになる。TSX_TSCONFIG_PATH で tsconfig を指定しても esbuild の制約は変わらない。

修正: TypeORM entity を import する ops script は tsx ではなく apps/vendure-server/scripts/run-local-ts-source.sh（ts-node + TS_NODE_TRANSPILE_ONLY=1）を使う。ts-node はコンパイラ API 経由で emitDecoratorMetadata を正しく出力する。

# NG
pnpm exec tsx scripts/verify-migration-upgrade-path.ts

# OK
bash apps/vendure-server/scripts/run-local-ts-source.sh scripts/verify-migration-upgrade-path.ts

適用範囲: vendure-config → プラグイン → entity という import チェーンを辿る全スクリプト（migrate:generate / verify-migration-upgrade-path 等）。

`resolve-deploy-target` が "tsx not found" で失敗する (2026-06)¶

症状: GitHub Actions の deploy workflow で Resolve deploy target ステップが次のエラーで失敗し、downstream 全ジョブが空の環境変数で動く。

tsx not found at .../node_modules/.bin/tsx; run pnpm install before resolving deploy targets.
Unsupported environment URL target: production.

原因: scripts/ops/deploy-targets.sh は read-url-topology.mjs を tsx 経由で呼び出して URL を解決する。tsx は node_modules/.bin/tsx に存在するため、setup-pnpm-workspace（pnpm install）より前に resolve-deploy-target-manifest action を実行すると未インストール状態となる。

修正: deploy workflow（_deploy-vendure-fly.yml / _deploy-storefront-workers.yml / _deploy-dashboard-workers.yml）では必ず setup-pnpm-workspace を resolve-deploy-target-manifest より前に配置する。

# NG (旧: pnpm install より前に resolve)
- uses: ./.github/actions/resolve-deploy-target-manifest
- uses: ./.github/actions/setup-pnpm-workspace

# OK (pnpm install → resolve の順)
- uses: ./.github/actions/setup-pnpm-workspace
- uses: ./.github/actions/resolve-deploy-target-manifest

補足: deploy-targets.sh を URL ハードコード方式（tsx 不要）に戻せばこの依存はなくなるが、URL topology SSOT を崩すため非推奨。

`vendure-server:build` が `@ritsubi/plugins` の型エラーで失敗する (2026-05)¶

症状: ritsubi-vendure-server:build が多数の Module '"@ritsubi/plugins"' has no exported member エラーで失敗する。エラー例：

error TS2459: Module '"@ritsubi/plugins"' declares 'VisibilityPlugin' locally, but it is not exported.
error TS2724: '"@ritsubi/plugins"' has no exported member named 'CmsIntegrationPlugin'.

原因: 前のビルドセッションで plugins-watch (tsc -w) が生き残っており、_sync-dev-runtime-baseline 内の _plugins-ensure-built が rm -rf packages/plugins/dist + rebuild を実行したときに書き込みが競合し、dist が破損した。その stale な dist を参照して vendure-server build が失敗した。

修正: scripts/dev/run-process-compose.sh の起動順序を変更し、_stop-dev-processes を _sync-dev-runtime-baseline より先に実行する（旧: Stage 2=sync, Stage 3=stop → 新: Stage 2=stop, Stage 3=sync）。

暫定回避: dist が破損している疑いがある場合は手動で pnpm -C packages/plugins build を実行すれば Nx がキャッシュを更新する。

CI 速度最適化の記録¶

2026-06 時点の構成と改善履歴¶

workspace tarball 撤去（最大の改善、2026-06-08 適用）¶

旧来の prepare-x64-workspace → package-workspace-deps → restore-workspace-deps による node_modules tarball の共有は tar -xzf に約 720 秒かかる重大なボトルネックだった。各 job で pnpm store cache（hardlink install）+ build-internal-workspace-deps（内部 dist を tsc -b で再ビルド）に切り替えることで、job ごとの固定費が 720s → 約 40s に短縮。

self-hosted remote cache のヒット（2026-06）¶

nx affected の codegen / build / typecheck は self-hosted remote cache（apps/nx-cache）から再利用され、入力不変なら再計算ゼロ。過去メモにある「codegen 約 441s」は remote cache 整備前の数値で、現在は run 跨ぎで cache hit する（Nx Cloud とリモートキャッシュ参照）。codegen が毎回フル実行されるように見えたら、まず remote cache のヒットを疑うのではなく、[remote cache] ログと NX_DISABLE_REMOTE_CACHE: false を確認する。

Playwright browser のキャッシュ化（2026-06-09 適用）¶

remote cache / pnpm store cache の外側に残っていた唯一の未キャッシュ install が Playwright browser（playwright install --with-deps で 54〜84s/job）だった。.github/actions/install-playwright-chromium を ~/.cache/ms-playwright の actions/cache（key=playwright-chromium-<os>-<version>）+ launch-probe 化し、cache hit 時は chromium を実起動して確認できれば apt も再 download も skip、失敗時のみ system deps を入れる。2 回目以降の browser 設置が実質ゼロになる。前提として job の PLAYWRIGHT_BROWSERS_PATH: 0 を外す必要がある（後述のトラブルシュート参照）。

その他の適用済み最適化¶

対象	変更内容	効果
`_vendure-db-dry-run-guard.yml`	runner `2vcpu-arm → 8vcpu`、timeout `50→25` 分	Vendure tsc が CPU-bound のため数分短縮
`_storefront-ct.yml`	`PW_WORKERS 4→6`（8vcpu runner を活用）	CT shard 約 15% 短縮
archive/notify job checkout	`fetch-depth:1` + `filter:blob:none`	失敗時 job で 5〜15s 削減
`summarize-affected-projects` action	`nx show projects` + `nx affected --graph` の 2 回 → 1 回統合	analyze critical path 約 10〜30s 削減
`_ci-pr-core-quality.yml`	`typecheck` + `test` を `--targets=typecheck,test --parallel=4` に統合	8vcpu で両 target を並列スケジューリング
`install-playwright-chromium` / `_storefront-ct.yml` / `_vendure-quality.yml`	browser を `~/.cache/ms-playwright` に actions/cache + launch-probe	2 回目以降の Playwright install を 54〜84s → 数秒

CI を新たに遅くしないための指針¶

新しい deploy workflow に resolve-deploy-target-manifest を追加する場合は必ず setup-pnpm-workspace の後に配置する（「tsx not found」問題の再発防止）。
nx affected --graph を composite action 内で複数回呼ぶ必要が生じた場合は graph JSON を1回生成して共有し、Python 等で複数フラグを一括抽出する。
新しい pre-push hook や CI job を 2vcpu で追加する前に、Vendure ビルド（tsc / nx run build）を含む場合は 8vcpu の使用を検討する。
Playwright CT のシャード数や PW_WORKERS を変更する場合は runner の vcpu 数（現在 8vcpu）に対して PW_WORKERS = vcpu * 0.75 程度を目安にする。

トラブルシュート（CI cache）¶

codegen / build / typecheck が毎回フル実行される¶

nx affected のキャッシュ済み target が run 跨ぎで効かない場合の確認順:

run log で nx-offline-cache-env の出力を見る。remote cache healthy (HTTP 200); self-hosted remote cache enabled. なら有効。running offline / probe returned HTTP ...; falling back to offline なら remote cache を掴めていない。
offline に落ちている場合の典型原因: NX_CLOUD_ACCESS_TOKEN_RW/_RO secret 欠落、cache server（ritsubi-nx-cache.ritsubi.workers.dev）の /health が 200 を返さない、fork PR で secret が渡らない。curl -s -o /dev/null -w '%{http_code}' https://ritsubi-nx-cache.ritsubi.workers.dev/health で直接確認できる。
cache は有効なのにヒットしない場合は、対象 target の input が実際に変わっている（codegen schema・lockfile 等）。[remote cache] が付かず実行されているか、Nx read the output ... for N out of N tasks の N を見る。

Playwright browser install が毎回走る（`actions/cache` が効かない）¶

install-playwright-chromium の browser cache は default path ~/.cache/ms-playwright 前提。job / step env に PLAYWRIGHT_BROWSERS_PATH: 0 が残っていると browser が node_modules 配下に入り、cache 経路から自動的に外れる（cacheable=false、従来どおり毎回フル install）。

対処: その job の PLAYWRIGHT_BROWSERS_PATH: 0 を外す。install と test が同一 job 内なら Playwright は default path を自動探索するので安全。
=0 を残したまま default path を cache すると、browser 不在の空 cache を別 job が hit して download を skip → 起動失敗（cache poisoning）になるため、action 側は =0 の job を意図的に cache 対象外にしている。混在は正常な degrade。
適用済み: _storefront-ct.yml / _vendure-quality.yml。未適用（=0 のまま従来動作）: smoke・deploy 系の setup-storefront-smoke-playwright 経路。ここを速くしたい場合も同様に =0 を外す。

CI / 障害調査の短縮手順¶

CI の一次情報は GitHub Actions run logs。
実環境障害の一次情報は Sentry event / issue / stack trace。
staging / production の状態確認は just env-status <env> --format json を優先する。
Fly app の直近ログを CLI で見る場合、現行 flyctl logs は --since を受け付けない。時刻範囲は Sentry / env-status / deploy release 時刻で先に絞り、CLI では fly logs --app <app> --no-tail の ring buffer を rg で絞る。
production smoke は専用 channel を使い、通常顧客や通常 SKU を混ぜない。

要するに、会話で状況を推測する前に「どの single source を開くか」を先に固定します。

運用診断（価格・表示の不利益検出）¶

「0 件可視の顧客 / 0 円販売 / 上代超え」など、設定ミスが顧客の不利益を生んでいないかを Admin API 経由で確認する READ-ONLY 入口。Dashboard を開かずに AI が直接状況を把握できる。

just diagnostics（local, text）/ just diagnostics-json <env> <limit>（JSON, AI 向け）/ just diagnostics-list（check 一覧）。
実体は scripts/ops/run-diagnostics.mjs。local 認証は apps/vendure-server/.env、staging/production は --url(RITSUBI_ADMIN_API_URL)＋認証情報を env/フラグで渡す。
終了コード: 0=検出なし / 1=finding あり / 2=check error / 3=接続・認証失敗。
詳細・検査項目の追加方法は vendure-plugins/diagnostics.md を正本にする。