measure-dont-guess

# typescript-template での計測

masseater/typescript-template から作ったリポジトリで、何をどこで計り、どう読むかの参照である。

## 信号の出し方

サーバーの信号は 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` で止まったら、テストとログで計れる範囲を進める。画面を計れていないことをユーザーに伝える。

---
name: measure-dont-guess
description: 仮説を白黒つける計測を実装や修正の前に決めて実行し、その結果だけで判断する。不具合の原因を調べるとき、性能や挙動を比べるとき、新しい機能を書き始めるとき、「たぶん」で判断しそうになったときに使う。
---

# measure-dont-guess

推測ではなく計測で判断するための規則である。

- 計る前に、仮説と採用する値を書く
- 本番か、本番と同じ条件で計る
- 計測していない主張は推測と明記する
- 計れないときは推測で進めず、何が足りないかをユーザーに伝える

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

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

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

## 本番での計測

判断の根拠にする計測は、本番環境で行う。手元やテスト環境は、データの規模や外部サービスが違い、本番と逆の結論が出ることがある。

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

## 計測の記録

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

## 用途

次もすべて読むこと。

- [`measure`](usecases/measure.md)。仮説を立てて計り、結果で判断する
- [`find-root-cause`](usecases/find-root-cause.md)。不具合の根本原因を探す
- [`improve-performance`](usecases/improve-performance.md)。性能を改善する

## 参照

[`typescript-template`](references/typescript-template.md) も読むこと。masseater/typescript-template から作ったリポジトリで、何をどこで計るかを書いている。ほかのリポジトリでは、同じ役割のものに読み替える。

# 不具合の根本原因を探す

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

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

複数の層をまたぐ処理の例は、CI からビルド、署名へ進む処理や、API からサービス、DB へ進む処理である。

修正にはついでの改善やリファクタリングを混ぜない。混ぜると何が効いたか分からなくなる。

3 回直しても直らなければ、4 回目を試さずに設計を疑い、ユーザーに相談する。直すたびに別の箇所が壊れるのは、設計の問題であることが多い。

# 性能を改善する

計測で見つけたボトルネックに対して、改善を 1 つずつ入れる手順である。

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

# 仮説を立てて計り、結果で判断する

実装や修正の前に、仮説を白黒つける計測を決めて実行する手順である。

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

結果を見てから基準を決めると、都合よく読んでしまう。だから手順 3 は計る前に書く。

- どの仮説も確定しなければ、計る対象を増やして手順 3 に戻る
- 計れないときは推測で進めず、何が足りないかをユーザーに伝える
- 新しい機能は、受け入れ条件を確かめるテストかスクリプトを先に書き、失敗することを確かめてから実装する