measure-dont-guess

measure-dont-guess

「何を計るか」以降は masseater/typescript-template から作ったリポジトリの構成で書いている。ほかのリポジトリでは、同じ役割のものに読み替える。

この skill が必要な理由と達成したい状態

この skill が必要な理由: 推測は計るより速く答えが出て、たいてい筋が通って見える。推測で進めた変更は、結果が正しくても偶然か根拠によるものかを区別できず、間違っていても気づく材料が残らない。次に同じ判断をする人は、また推測から始める。

この skill で達成したい状態: すべての判断が、誰でも再現できる根拠に基づいている。

どこで計るか

判断の根拠にする計測は、本番環境で行う。 本番で計れないときは、コード、設定、インフラ、データの規模と形、外部サービスを本番と同じにしたステージング環境を作って計る。 手元やテスト環境の計測は、計る仕組みが動くかを確かめるためだけに使う。データの規模や外部サービスが違い、本番と逆の結論が出ることがある。

手順

1. 答えが事実で決まる問いを1つ立てる。
2. 考えられる仮説をすべて挙げる。
3. 仮説ごとに、計る対象と、採用する値・捨てる値を計る前に書く。結果を見てから基準を決めると、都合よく読んでしまう。
4. 再現手段と観測点を作り、結果が分かっている入力で正しく計れることを確かめる。
5. 変える条件を1つにして計る。時間や性能は複数回計り、ばらつきも見る。
6. 条件、コマンド、生の結果を残す。
7. 手順3の基準で判断する。予想と違えば仮説を疑う。
8. 変更後に同じ仕組みで計り直し、効果を確かめる。

どの仮説も確定しなければ、計る対象を増やして手順3に戻る。 計れないときは推測で進めず、何が足りないかをユーザーに伝える。

新しい機能は、受け入れ条件を確かめるテストかスクリプトを先に書き、失敗することを確かめてから実装する。

計測していない主張は推測と明記する。 変更の根拠にした計測は、条件とコマンドと結果をコミットメッセージに書く。 都合の悪い結果が出たら、そのまま報告して仮説を見直す。

不具合の根本原因を探すとき

症状を消す修正ではなく、原因を直す。原因が分かるまで修正を書かない。

1. エラーメッセージとスタックトレースを最後まで読む。答えがそのまま書いてあることが多い。
2. 確実に再現する手順を作る。再現しないうちは、観測点を増やして情報を集める。
3. 最近の変更（差分、コミット、依存、設定、環境の違い）を見る。
4. 複数の層をまたぐ処理（CI → ビルド → 署名、API → サービス → DB など）は、層の境界ごとに入ってきた値と出ていく値をログに出し、一度動かして壊れている層を特定してから、その層を調べる。
5. 不正な値は、呼び出し元をたどって出どころまで遡り、そこで直す。
6. 同じコードベースで動いている似た実装を探し、壊れている側との違いを小さなものまですべて挙げる。

修正は失敗するテストを先に書いてから 1 つだけ入れ、ついでの改善やリファクタリングを混ぜない。混ぜると何が効いたか分からなくなる。 3 回直しても直らなければ、4 回目を試さずに設計を疑い、ユーザーに相談する。直すたびに別の箇所が壊れるのは、設計の問題であることが多い。

性能を改善するとき

1. 対象をスパンで計れるようにし、改善前の値を取る。
2. 計測で分かったボトルネックに対して、改善を 1 つずつ入れる。
3. 改善前と同じ条件で計り直し、値が良くなったことを確かめる。良くならなければ次の仮説で 2 に戻る。
4. 改善で別の箇所が遅くなっていないかも計る。

何を計るか

サーバーの信号はEffectのAPIで出し、Cloudflare Workers Observabilityに集める。 Effect.withSpan は apps/web/src/pages/home/api/tracing.server.ts がWorkersのトレースに写す。 Effect.log* はWorkers Logsに入る。 D1やfetchの呼び出しは、Cloudflareが自動でスパンにする。 メトリクスは、Workersのリクエスト数・エラー数・CPU時間・所要時間を使う。 観測の設定とサンプリング率は apps/web/alchemy.run.ts の observability にある。

課題	出すもの
不具合	入力と分岐を Effect.annotateLogs 付きの Effect.logInfo で出し、Effect.withSpan で経路を見て、テストで再現する
遅さ	Effect.withSpan の所要時間を変更の前後で比べ、ロジック単体は vp test bench で比べる
新機能	受け入れテストに加え、成功と失敗を Effect.annotateLogs 付きのログで出し、Workers Logsで件数を集計する

計測結果を読む

ログとトレースは、リクエストの一部だけを標本として残す。 計測のあいだだけサンプリング率を上げ、終わったら戻す。 判断には、標本の件数が足りているかも添える。

本番のログ・トレース・メトリクスは、.mcp.json の cloudflare-observability MCPサーバーで問い合わせる。 ほかのCloudflareのAPIは cloudflare-api MCPサーバーで呼ぶ。 どちらもAlchemyのプロファイルの認証情報を使う。 デプロイしたWorkerのログを流して見るときは、apps/web で vp exec alchemy logs --tail を使う。

Effectのログとブラウザのconsoleは、vp run dev のターミナルにも出る。

ブラウザ

vp dlx @playwright/cli で操作し、console・requests・snapshot で観測する。 クラウド環境では、.playwright/cli.config.json の launchOptions.executablePath に /opt/pw-browsers のChromiumを書く。

alchemy dev が CredentialsUnavailable で止まったら、テストとログで計れる範囲を進め、画面を計れていないことをユーザーに伝える。