product-thinking

プロダクト思考

ユーザーが操作するものを変更するときのランブックです。エージェントは、依頼されたことをそのまま実装するように動作します。この確認では、抜け落ちがちなプロダクト視点のチェックを追加します。つまり、その変更をユーザー向けの画面や機能に恒久的に残す価値があるか、また、うまくいったとどう判断するかを確認します。コードを書く前に各ステップを進め、作業しながらブリーフを記入し、そのブリーフを PR に含めてください。変更に根拠がない場合は、ただ承認するのではなく、このブリーフを使って異議を唱えてください。

実行するタイミング

ユーザー（React Doctor を実行する開発者、またはその CI）が依存するサーフェスに差分が触れるたびに、この確認を実施します。すべてのサーフェスは契約です。リリース後は、それを基に人々が構築するため、ひそかに取り消すことはできません。まずサーフェスがどこにあるかを確認してください。そうすれば、適切な場所を編集でき、追加する前に再利用できるものがないか検索できます。

サーフェス	場所	重要である理由
CLI コマンド／フラグ	cli/index.ts、cli/commands/*.ts、cli/utils/inspect-flags.ts	すべてのフラグは恒久的なものです。解析、文書化、テストが必要であり、リリースを重ねても動作し続けなければなりません。
0–100 スコア	core/src/calculate-score.ts、core/src/constants.ts	ユーザーがスクリーンショットを撮り、CI のゲートに使う数値です。計算方法を変えると、すべてのユーザーのスコアがひそかに変わります。
設定オプション	core/src/types/config.ts、core/src/services/config.ts	既存の優先順位と関わる、長く維持される契約です。新しい設定項目は、後から削除できないことがほとんどです。
JSON レポートのフィールド	core/src/schemas.ts、core/src/build-json-report.ts	他のツールが解析するワイヤーフォーマットです。schemaVersion に対応しないまま形状を変えると、連携が壊れます。
パッケージ API／終了コード	react-doctor/src/inspect.ts、api/src/diagnose.ts	プログラムから利用する側はこれに依存するため、変更は semver 上の互換性を壊し、チェンジセットが必要です。
GitHub Action の入力／出力	action.yml	個別にバージョン管理されています（vN）。入力または出力を変更すると、他のリポジトリのワークフローが壊れます。
ターミナル出力／UX	cli/utils/ レンダラー	第一印象であり、日々の利用体験です。ここでノイズや混乱があると、利用をやめる原因になります。

対象外： lint ルールは rule-research → rule-writing → rule-validate のパイプラインで扱い、ルール設定は doctor-explain で扱います。この確認の対象はルール自体ではなく、ルールを取り巻くサーフェスです。内部のみの変更（エンジン、非公開の core 型、テスト、ツール）では、この確認を完全に省略します。その変更が内部向けである理由を一行で記して、次に進んでください。

ステップ

- [ ] 1. Write the job + the change (2 lines)
- [ ] 2. Search for a reuse candidate; extend it or justify new surface
- [ ] 3. Wire exactly one metric
- [ ] 4. Pick the default + add the compatibility artifacts
- [ ] 5. Update docs
- [ ] 6. Record the kill metric
- [ ] 7. Run checks

1. ジョブと変更内容を書く

何よりも先に、次の2行を書きます。後続のすべてのステップの軸になります。

• ジョブ — 誰が React Doctor を実行し、実際に何を達成しようとしているのか、そして現在は代わりに何をしているのか（既存のフラグや設定オプション、別のツール、あるいは何もしていないのか）。誰かが仮に望むと言ったことではなく、観察した行動に基づいてジョブを定めます。
• 変更 — そのジョブを実現する最小限の範囲です。変更の規模がジョブを上回るなら、根拠のない機能を作ろうとしています。

現在の機能では対応できないジョブを挙げられないなら、作業を止めます。構築するものは何もなく、ユーザーに既存の実現方法を案内するのが適切な対応です。

構築を決める前に、次の2つの基準でも評価します。

• 持続性 — React（または対象のフレームワーク）に対するモデルの能力が向上しても、これは重要なままでしょうか。モデルが取り込む機能や、簡単に一般化される機能を、恒久的な機能として追加する価値はありません。長期にわたって安定した、決定論的な価値に機能範囲を割きます。
• 信頼性 — ユーザーが信頼できない機能は、機能がないよりも悪いものです。ツールを無視するようユーザーに学習させてしまうためです。誤検知が発生する可能性がある場合や、推奨事項を証拠で裏付けられない場合は、まず信頼性の問題を解決します。「おおむね正しい」状態でリリースすれば、製品全体への信頼が損なわれます。

2. 追加する前に検索する

追加より再利用を常に優先します。作らずに済む機能範囲こそ、最もコストの低い機能範囲です。フラグ、オプション、レポート項目を追加する前に、拡張できる既存のものがないか検索します。

bunx @rayhanadev/truffler "<name or behavior>" packages --kind function,interface,type,constant --limit 20
rg -n "<flag-or-option-name>" packages/react-doctor/src/cli packages/core/src/types

何かを書く前に、検索結果の上位を読みます。ほぼ同じジョブを実現する既存の機能範囲があれば、それを拡張します。たとえば、既存のフラグに新しい値を追加する、既存の設定オブジェクトにフィールドを追加する、すでに出力されている内容に列を追加するといった方法です。ジョブが明確に異なり、混乱を招かずに対応できる既存の項目がない場合に限り、まったく新しい機能範囲を追加します。追加する場合は、検索した内容と該当するものがなかった理由をブリーフに記録します。そうすれば、次の担当者は同じ議論を繰り返さずに、その判断の根拠を引き継げます。

3. メトリクスを1つだけ組み込む

確認できない機能範囲は管理できないため、シグナルが出るまでは変更が完了したとは言えません。構築前にそのシグナルを決めます。どの数値が変化するのか説明できないなら、成功の意味をまだ把握できていません。CLI のテレメトリは匿名化された Sentry で、@react-doctor/api ライブラリ、テスト、--no-score ではすでに何も実行されないため、組み込むのはイベントの送信だけです。

• 採用数 — 誰かが使っているかどうかを測ります。cli/utils/constants.ts の METRIC マップに名前を追加し、cli/utils/record-metric.ts から送信します。「このフラグを有効にした人がいるか」を測る場合に使います。
• スキャンごとの結果 — この実行で何が起きたかを測ります。cli/utils/build-run-event.ts の幅広いイベントに属性を追加します（実行単位のディメンションは cli/utils/build-sentry-scope.ts に追加します）。細分化されたカウンターを多数追加するより、幅広いイベントに情報量の多い属性を1つ追加することを優先します。新しいコードを追加しなくても、事後にクエリできる状態を保てます。

匿名化は必須です。属性にユーザー名、パス、シークレット、リポジトリの識別情報を入れてはいけません。すべて scrubSentryEvent / scrubSentryMetric を経由させる必要があります。次に、メトリクス名と「成功した」と判断する基準値をブリーフに記録します。

最重要の指標は、唯一の長期的なメトリクスである CI コホート継続率 です。数週間後もチームが CI で React Doctor を実行しているかを測ります。それ以外の数値の多くは見かけ上の指標として扱います。「単に使われているだけでなく、本当に愛用されているか」を測る代理指標には、なくなったら「非常に残念」と回答する人が 40% 以上となる PMF 調査を使います。

4. デフォルトを選び、互換性を保つ成果物を追加する

デフォルトは実装の詳細ではなく、プロダクト上の決定です。ほとんどのユーザーは変更しないため、ほぼすべてのユーザーにとってデフォルトがそのまま挙動になります。現在の挙動を維持するものを選び、リスクのあるものはオプトインにします。そのうえで、既存ユーザーに不具合が起きないよう、次の成果物を用意します。

• 公開済みパッケージの挙動を変更する場合 → changeset（nr changeset）を追加し、変更がバージョンに反映され、変更履歴に記録されるようにします。
• JSON レポートの形式を変更する場合 → core/src/schemas.ts を編集し、既存の形式を維持するか、schemaVersion を引き上げて、nr smoke:json-report を実行します。CI パイプラインはこの出力を解析するため、予告なしに形式を変更すると、気付かないうちにパイプラインが壊れます。
• スコアの重み付けやアルゴリズムを変更する場合 → すべてのユーザーの数値が一斉に変わり、しきい値に連動した CI のゲートが反転する可能性があります。破壊的変更として扱い、changeset を作成し、変更による影響を明示します。
• action.yml を変更する場合 → vX.Y.Z タグを切り、可変の vN を更新します。そうしないと、メジャーバージョンに固定している他のリポジトリには変更が反映されません。

5. ドキュメントを更新する

見つけられない機能は活用されず、古いドキュメントは信頼を損ないます。ドキュメントの更新も「完了」に含まれ、後回しにするものではありません。

• 新しいフラグやコマンドの近くにある --help／使用方法のテキスト。CLI 自体から見つけられるようにします。
• ウェブサイトのページと、react.doctor/prompts/... にある正式なプロンプト。これはエージェントが実行時に取得するものです。
• 変更によってユーザー向けのワークフローが変わる場合は、配布対象のスキル（skills/react-doctor、skills/doctor-explain）も更新します。

6. 撤退基準となる指標を記録する

機能が増え続けると、使われないフラグや使われなくなった設定キーは、恒常的な保守負担となり、ユーザーが誤解する項目も増えます。追加した価値がなかったと判断する方法を、あらかじめ決めておきます。ブリーフに、ステップ 3 の指標、しきい値、期間を 1 行で記入します。たとえば「<metric> が 2 回のリリース後も N 未満なら削除する」のようにします。思い出すことに頼らず、確認を予定に組み込み、使われていない機能を削除することは失敗ではなく、成果だと捉えます。

7. チェックを実行する

nr typecheck && nr test && nr lint
nr smoke:json-report   # only if you touched the JSON report

ブリーフ

各ステップを進めながら記入し、PR の「理由」に反映します。

## Product brief: <change>

Job: <who / goal / what they do today>
Change: <smallest surface that does it>
Reuse: <what you searched; what you extended, or why new surface was needed>
Metric: <METRIC name or wide-event attribute + the number that means success>
Compat: <default state; changeset / schemaVersion / action tag>
Kill: <metric threshold + horizon that triggers removal>

立ち止まって相談するタイミング

これらは、そのまま進めずに判断を仰ぐべきタイミングです。それぞれ、変更に人の判断が必要であることを示しています。

• 現在の機能では実現できない用途を挙げられない場合 → 機能を追加するのではなく、既存機能の再利用または機能の削除を提案します。
• 指標を定義できない場合 → 計測機能を追加するか、変更が本当に必要かを再検討します。
• 公開済みの契約（パッケージの挙動、JSON の schemaVersion、スコア、またはアクションの入出力）を破る場合 → 取り込む前に、changeset、バージョンの引き上げ、移行手順を確認します。
• 依頼された範囲を超えて作業が拡大する場合 → 範囲を広げる前に、明示的な合意を得ます。

チェックを通過した変更を取り込むには、ship（deslop、changeset、PR、babysit）を使用します。

製品原則（React Doctor）

手順が曖昧な場合、つまりどちらの選択肢も妥当に思える場合は、次の原則に沿ったほうを選んでください。

1. 指摘は多いより少ないほうがよい。 開発者が実際に対処する10件の問題は、読み飛ばされる100件に勝ります。すべてを列挙するのではなく、上限を設けて優先順位を付けてください。
2. 個々の警告より根本原因を重視する。 1つの根本的な問題による症状は、それぞれを別々に報告するのではなく、1つの指摘にまとめてください。
3. 断言より証拠を重視する。 ツールの言葉を信じるよう求めるのではなく、コードや測定結果、理由など、根拠を示してください。
4. 正確さより実行可能性を重視する。 次に何をすればよいかが明確な修正可能な問題は、対処方法がわからない技術的に完璧な指摘に勝ります。
5. ダッシュボードよりワークフローを重視する。 開発者を別の画面に誘導するのではなく、CLI、PR、エディターなど、すでに使っている場所で利用できるようにしてください。
6. 診断より学びを重視する。 問題であることだけでなく、なぜ問題なのかを説明し、ユーザーが学べるようにしてください。
7. 検出範囲より信頼を重視する。 最良の指摘とは、ユーザーが信じて対処するものです。問題の見逃しによる検出範囲の損失よりも、誤検知1件による信頼の損失のほうが大きくなります。