junior-to-senior

ジュニアからシニアへ

目の前の計画は、能力のあるジュニアが書いたものだと想定してください。流暢で、自信にあふれ、過去の情報で訓練されています。ジュニアにはなかった2つの要素、つまり実際に存在するこのコードベースと今日の最新技術の動向に基づくシニアレビュアーを構築し、そのシニアに計画を徹底的に批判させ、作り直させます。

このスキルが存在するのは、エージェントが生成した計画が、2つの高度で失敗するためです。

• 霧 — 計画では大枠をうまく説明しています（「キャッシュを追加する」「認証に対応する」「スケーラブルにする」など）が、難所については決断を下していません。インターフェースも、データの形も、障害処理も、具体的なライブラリ名もありません。計画を読むエンジニアは、結局、重要な決定をすべて自分で下さなければなりません。
• トンネル — 計画は関数シグネチャやファイル差分に深く踏み込んでいますが、プロダクトのビジョンがありません。誰のためのものなのか、成功とは何を意味するのか、対象外は何か、なぜ無難な代替案よりこの方法が優れているのかが示されていません。機能全体の形がまだ間違っているのに、局所的な詳細を最適化しています。

どちらも高度の失敗です。シニアの仕事は、計画を適切な高度に引き上げること、そしてモデルの訓練データのカットオフを超えて、その内容を強化することです。

最重要ルール

シニアの指摘には、すべて根拠が必要です。 コードベースに関する主張には、ファイルと行番号を引用します。ベストプラクティスに関する主張には、取得した情報源（公式ドキュメント、リリースノート、RFC、事後分析など）と日付を添えます。ウェブ調査ができない場合は、その指摘に [training-data, unverified] と明記し、古い知識を最新の事実として装うことがないようにします。直感だけで主張するシニアは、声が大きいだけのジュニアです。

フェーズ 0：ジュニアの成果物を記録する

レビュー対象を正確に特定します。

• エージェントがこの会話で直前に作成した計画（デフォルト。少し前に作成した自分の出力も含みます）。
• 貼り付けられた計画、設計ドキュメント、RFC、課題の説明。
• ユーザーが指定した、リポジトリ内の計画ドキュメント。

対象を固定します。レビューを始める前に、成果物を全文引用するか言い換えて、変化し続ける記憶ではなく、固定されたテキストをレビューできるようにします。まだ成果物がない場合は、その旨を伝え、先にジュニアの草案を作成するか、ユーザーの既存のアイデアをレビューするかを提案します。根拠のないレビューはしません。

フェーズ 1：シニアを構成する

シニアとは、単なる口調ではありません。今行った調査に基づいて構成するレビュアーのプロファイルです。このフェーズを省略して批評に進むと、ありきたりで中身のないレビューになります。

1a. 領域を抽出する

計画が扱う、技術的に重要な領域を2～5個挙げます（例：「Postgres スキーマの移行」「React サーバーコンポーネント」「OAuth トークンの更新」「1,000万行でのベクトル検索」）。各領域について、その分野のスタッフレベルのエンジニアなら見過ごさない問題を1文で記述します。この一覧に基づいて、以降の調査を進めます。

1b. コードを調査する — この場で実際に何が真実か

計画を評価する前に、リポジトリを調査します。

• 計画が従うべき既存の慣習とアーキテクチャ（または、正当な理由を明示して変更すべき点）。
• ロックファイルやマニフェストに記載された実際のバージョン — 固定されたバージョンに存在しない API を推奨する計画は、阻害要因です。
• 既存の実例：コードベース内の類似機能、ADR、マイグレーション、テストパターン。
• ジュニアの計画が見落としている現実の制約：ビルドシステム、デプロイ先、パフォーマンス予算、既存データ。

広範囲の調査には、サブエージェント（例：Explore）を使い、レビューのコンテキストを整理して保ちます。

1c. Web 調査 — 現在の状況

計画における重要な判断ごとに、現在の最先端の状況を調査します。ジュニアの知識は学習データのカットオフ時点で止まっていますが、シニアの知識はそうであってはなりません。一次情報（公式ドキュメント、変更履歴、リリースノート、メンテナーの投稿）を優先し、日付を確認します。探すのは、次の3種類の変化です。

• 非推奨化 — 計画の手法が現在は推奨されていない、または廃止されている。
• 置き換え — カットオフ以降に、新しいパターン／ライブラリ／APIが明らかに主流になった。
• 苦い経験から得た教訓 — 公開された事後分析、ベンチマーク、セキュリティ勧告によって、トレードオフの評価が変わった。

検索クエリのパターン、情報源の品質ランキング、調査を終了するタイミングについては、references/research-playbook.md を参照してください。Web にアクセスできない場合は、コードの調査だけで進め、ベストプラクティスに関する主張すべてに [training-data, unverified] を付けてください。

1d. 分離

ハーネスがサブエージェントに対応している場合、シニアレビューは、凍結された成果物と調査結果を受け取り、ジュニアの計画を導いた推論は受け取らない、コンテキスト分離されたサブエージェントで実行してください。同じコンテキスト内での自己レビューは、自分自身の正当化に引きずられます。レビューを追認ではなく敵対的なものにするには、分離が必要です。

フェーズ 2：計画の解像度を診断する

行単位の批評に入る前に、成果物を霧、トンネル、または混在に分類します（実際の計画の多くは、難しい部分が霧に包まれ、簡単な部分にトンネルのように焦点を当てています。そのため、各セクションを個別に評価してください）。

霧の判定 — 計画に記載された各コンポーネントについて、有能なエンジニアが、自分でプロダクトやアーキテクチャの判断を下さずに、明日から作業を始められるでしょうか。トンネルの判定 — 誰を対象としているか、成功の定義、明示的に対象外とするもの、そして明白な代替案よりこの方法が優れている理由が計画に記載されているでしょうか。

診断用の完全なチェックリスト、曖昧な表現のブラックリスト（「シンプル」、「スケーラブル」、「適切に処理する」、「堅牢」など）、重大度の定義については、references/review-rubric.md を参照してください。

フェーズ 3：敵対的レビュー

シニアは、コードベースの実情（1b）、現在の最先端の状況（1c）、計画の解像度（フェーズ 2）の3つの観点から、凍結された成果物をレビューします。レビューのルールは次のとおりです。

• 曖昧な表現はすべて、それが避けている具体的な問いを示して、疑問を呈します。
• 名前が挙がっている技術にはすべてバージョンと選定理由を求め、名前が挙がっていない技術（「キュー」、「何らかのキャッシュ」）は具体名を挙げるか、未決の判断として指摘します。
• 境界をまたぐデータ構造はすべて明記します。
• すべての計画について、ロールバックの方法、移行の方法、10倍の規模で何が壊れるかを問います。
• 批判する前に、相手の主張を最も強い形で述べます。まずジュニアの選択肢の最も説得力のある説明を示し、そのうえで、なお劣る理由を示します（または、優れていると認めます。根拠が裏付ける場合にジュニアに同意することは、スキルの失敗ではなく、妥当なシニアとしての結論です）。

指摘には3段階の重大度を使います。ブロッカー（計画が記載どおりでは成り立たない）、重大（機能はするものの、最先端の方法より実質的に劣る、またはリポジトリに適合しない）、軽微（仕上げの改善）です。それぞれに根拠と具体的な修正案を添えてください。定義と例については、references/review-rubric.md を参照してください。

フェーズ 4：計画を完成させる

書き直しを伴わない批評は、ただの不満です。次の構成でシニア版の計画を作成してください。

1. 目標と対象外 — プロダクトの意図を1段落で説明し、対象外の項目を明示します。
2. 判断事項 — 重要な選択ごとに、選んだ案、バージョン、理由、却下した最有力の代替案、根拠（ファイル参照またはソースリンク）を示します。
3. 適切な解像度での設計 — 難しい部分について、インターフェース、データ構造、障害時の処理を示します。定型的な部分は意図的に大まかに記述します。
4. 順序 — 各マイルストーンに、観測可能な検証手順を設けます（「完了」は雰囲気ではなく、確認可能でなければなりません）。
5. リスクとロールバック — 元に戻すのが最も難しい点と、そこから抜け出す方法を示します。
6. 人間への未解決の質問 — シニアが独自に決めてはならないプロダクト上の判断を示します。スコープ設定はシニアの役割ですが、プロダクトの方向性を決めることは役割ではありません。

出力形式

最初にレビューを行い、2つの成果物を提出します。

## Senior Review

**Altitude diagnosis:** fog | tunnel | mixed — one-sentence justification.

### Blockers
- [B1] Finding — evidence (file:line or source+date) — fix.

### Major
- [M1] ...

### Minor
- [m1] ...

### What the junior got right
- Credit where due; preserved in the rewrite.

## Promoted Plan (v2)
[Phase 4 structure]

## Delta summary
- 3-6 bullets: what changed from junior to senior and why.

## Open questions for you
- Product decisions that need a human.

境界

• シニアはスコープを定め、計画を強化しますが、プロダクトの方向性を勝手に決めることはありません。本質的なプロダクト上の選択は書き直しに盛り込まず、「未解決の質問」に記載します。
• ジュニアの計画を黙って置き換えてはいけません。ユーザーにはレビュー、書き直し、差分を提示し、判断を委ねます。
• 調査結果がユーザーの明示した希望と矛盾する場合は、根拠を示して判断を保留します。シニアが知らない背景をユーザーが把握している可能性があるためです。
• ブロッカーも重大な問題もゼロというレビューも、正当な結果です。その場合は「この計画で問題ありません」と伝えて、そこで終えます。厳密さを示すために、無理に問題点を作り出してはいけません。