review-a-design

デザインをレビューする — 完成しているかだけでなく、妥当かを確認する

プラットフォームの /open-knowledge スキルは、ここでのすべての Markdown 操作に引き続き適用されます（exec による読み取り、write／edit による書き込み、通常の相対 Markdown リンク、対象範囲内の .md の管理は MCP が担当）。このスキルは、その上にデザインレビューの技法を重ねます。

3 種類のレビューはそれぞれ異なり、このスキルが担当するのはそのうち 1 つだけです。

• 完全性レビューで問うのは、すべてのセクションが埋まっているかです（Drawbacks と Alternatives は空欄ではありませんか？）。
• 正確性レビューで問うのは、個々の主張が事実に基づいているかです（ベンチマークには本当に 40ms とありますか？ その API は非推奨になっていますか？）。
• 妥当性レビューで問うのは、そもそもこれを構築すべきか、また、提示された目標と制約から導かれるデザインになっているかです。

あなたが行うのは 3 つ目です。提案は完全で、事実として正確であっても、間違ったデザインであることがあります。症状を解決していたり、目標を定める前に選ばれていたり、藁人形のような代替案しか検討していなかったりするためです。完全性と正確性は確認が容易で、ほかの人が担当するレビューです。ユーザーがどの種類のレビューを望んでいるか曖昧な場合は、まずその旨をユーザーに伝えてから、妥当性レビューを行ってください。

あなたが提示するのは指摘事項であり、修正案ではありません。変更内容を決めるのは執筆者です。明示的に依頼されない限り、レビュー対象の成果物を書き換えてはいけません。

---

ステップ 0：成果物を特定して読み込み、引き継いでいる内容も確認する

絶対条件：最後まで読んでいないデザインや、引き継いだ決定事項から切り離されたデザインをレビューしてはいけません。 前半だけのレビューは、何もしないより悪い結果になります。理解が不十分なまま、執筆者からの信頼を損ねるからです。

1. 種類を特定します。次のいずれかです。
   • 提案（proposals/NNNN-name.md — Motivation / Design / Drawbacks / Alternatives / Unresolved questions）、
   • 仕様（specs/NNN-name/spec.md — Goals / Non-goals / Design / Migration / Test plan。parent_proposal: を含む）、
   • 決定事項（decisions/NNNN-title.md — Context / Decision / Consequences。supersedes: の連鎖を含む）、または
   • まだ文書化されていない進行中の選択（ユーザーが会話の中で検討中のもの）。これは有効なレビュー対象です。ステップ 1 を参照してください。
2. 全体を読みます：exec("cat proposals/0003-feature.md")。
3. 依存関係を確認します。デザインの妥当性は、その土台の妥当性に左右されます。
   • 仕様が parent_proposal: で参照する親提案と、決定事項が実装する提案。
   • 前提としている決定事項 — exec("grep -rln <subsystem-keyword> decisions/") を実行し、該当するものを cat で読みます。採択済み ADR と矛盾しているのに、そのことに触れていないデザインは、それ自体が指摘事項です。
   • 同じサブシステムに関する過去の事後分析 — exec("ls -A postmortems/") と search({ query: "<subsystem> failure" }) を実行します。事後分析には障害モードが記されています。それを再び招くデザインを見つけることは、最も価値の高い指摘です。
   • 置き換えまたは重複する関連する提案／決定事項 — supersedes: の連鎖を両方向にたどります。
4. デザインがソースコードを参照している場合は、ホストのネイティブツール（Read、Grep）を使ってコードを読みます。ソースコードはナレッジベースの対象外です。対象範囲内の Markdown には exec／search を使います。

このデザインの目標、制約、土台となる過去の決定事項を明確に説明できるようになるまで、先へ進んではいけません。

ステップ 1：設計そのものの論拠を再構成し、それを示す

何かを批評する前に、設計の論拠を自分の言葉で述べてください。設計が目指すもの、受け入れる制約、そしてなぜこの設計がそれらの制約から導かれるのかを説明します。ステップ 2 に進む前に、その内容をユーザーに示してください。

この確認が必要な理由：

• 論拠を明確に再構成できれば、意図した読者に理解されたという確認を作者に無償で返せます。これは、レビューがもたらす最も有益な成果であることも少なくありません。
• **目標、制約、そしてなぜこの設計がそれらから導かれるのかを述べられないのであれば、レビュー対象となるものはまだ存在していません。これこそが指摘すべき点です。**ここで止めて、次のように報告してください。「この設計が目標から導かれる理由を再構成できません。論理のつながりが途切れている箇所はここです。」論拠を述べられない設計の表面的な部分をレビューしても、確信に満ちた雑音を生むだけです。まず論拠を明確にするため、作成スキルに差し戻してください。

文書がない進行中の選択については、このステップで初めて論拠を言葉にすることを促します。多くの場合、再構成するだけで、レンズを一つも使わずに疑問が解決します。

---

ステップ 2：妥当性のレンズを適用する

以下の各レンズを通して設計を検討します。レンズとは、特定の問いと、それによって見つかる問題を組み合わせたものです。この成果物に当てはまるレンズを使い、明らかに当てはまらないものは省略し、必要に応じて有用なレンズを追加してください。9つすべてを機械的に埋めないでください。同じ浅い指摘を9回繰り返すレビューからは、何も学べません。

• 問題の視点 — 提示された問題は本当の問題ですか。それとも、上流にある問題の症状ですか？ 誰の問題であり、仮定上ではなく、現在それが実害をもたらしていると示す証拠は何ですか？ 症状を対象にした設計は、どれほど洗練されていても健全ではありません。防げる失敗：間違った問題を見事に解決してしまうこと。
• 目標導出の視点 — 設計は提示された目標から導かれていますか。それとも、先に選んだ設計を正当化するために目標を後付けしていますか？ まず目標を読み、次に設計を先入観なしに読んでください。これらの目標から、この設計を予測できたでしょうか？ どの目標からも求められていない機能が設計にあるなら、目標が明記されていないか、その機能がスコープ外です。防げる失敗：ソリューションを先に決めてからの合理化。
• 代替案の視点 — 代替案は実質を備えていますか。それとも藁人形ですか？ 却下した案の最も強力な形、つまりスティールマンを検討し、文書がその案に向き合っているのか、それとも弱い戯画に向き合っているのかを確認してください。代替案のセクションで、各案をそっけない一文だけで退けているのは要注意です。防げる失敗：結論ありきの判断を比較検討に見せかけること。
• 制約の視点 — どの制約が絶対的で、どれが単なる慣習の引き継ぎですか？ 絶対的な制約：物理法則、コンプライアンス、すでに踏み出した後戻りできない決定、下流チームとの契約などです。柔軟な制約：「ずっとこうしてきた」、現在のツールの限界、変更可能な期限などです。柔軟な制約を絶対的なものとして扱う設計は、検討が不十分で、おそらく必要以上に大規模です。防げる失敗：存在しない壁を理由にした不要な複雑さ。
• コストの視点 — この設計によって何ができなくなり、今後3年間、チームに毎週どんな負担が発生しますか？ 継続的な義務を明確にしてください。元に戻せない移行、永続的にバックフィルが必要になるスキーマ、オンコール対応の範囲などです。影響範囲はリリース時だけではなく、その後の保守負担も含みます。防げる失敗：安く見えて、後々大きなコストがかかる設計。
• 可逆性の視点 — 一方通行の扉ですか、両方向の扉ですか？ 両方向の扉（簡単に元に戻せるもの）は、委員会で検討するのではなく、実際に試すべきです。設計を安価に元へ戻せるなら、過剰なレビューは全員の時間を浪費します。その場合の結論は「まず出荷して学ぶ」です。一方通行の扉（データ移行、公開 API、外部との契約）には、両方向の扉に不要だった厳密な検討が必要です。防げる失敗：労力のかけ方を誤ること。可逆的な選択に重いプロセスを課し、不可逆的な選択には軽いプロセスしか適用しないこと。
• 失敗の視点 — これが機能するために何が真でなければならず、それぞれの前提の境界では何が起きますか？ 基盤となる前提を列挙し、それぞれの限界まで検討してください。負荷が10倍になった場合、ネットワークがまったく使えない場合、悪意ある入力があった場合、2つ目の書き込み元が同時に存在する場合はどうなるでしょうか？ Step 0 の過去の事後検証と照合してください。この設計によって、過去に名指しされた失敗が再発しませんか？ 防げる失敗：通常の経路では健全でも、あらゆる境界条件で破綻する設計。
• シンプルさの視点 — 提示された目標を満たす、実質的に小規模な設計はありますか？ 具体的に示してください。「キューをなくして同期呼び出しにする。目標にはスループットが一度も挙がっていない」のように書きます。「シンプルにする」では、判断材料になりません。YAGNI はスタイルの指摘ではなく、健全性に関する論拠です。推測に基づく汎用性は、誰も明示していない目標のためにコストを支払うため、健全ではありません。防げる失敗：まだ抱えていない問題まで解決する設計。
• スコープの視点 — 非目標は時期を限定した正当なものですか。それとも、問題解決に不可欠なスコープがひそかに外されていますか？ 適切な非目標には、「今は対象外です。その理由は X であり、後から追加できる接続点はここです」とあります。不適切な非目標は、実際の問題の難しい半分をひそかに除外し、設計を実現可能に見せます。すべての非目標を読み、それがなくても設計が本当の問題を解決できるかを確認してください。防げる失敗：縮小された問題にしか対応できない、実現可能そうな設計。

---

ステップ 3：指摘事項を書く

各指摘事項には4つの要素があります。2つ目が欠けている指摘は意見なので、削除してください。

1. 主張 — 1文で、何に問題があるのかを述べます。
2. 根拠 — 該当箇所を引用するか、リンクします。例：the Design section says "[quoted text]" または [the Migration plan](./specs/012-sync/spec.md) assumes X。根拠を示すポインターのない指摘は意見です。削除してください。 これこそが、著者が行動に移すレビューと、著者に反感を抱かせるレビューを分ける唯一の規律です。
3. 重大度 — 次のいずれかです。
   • blocking — 記載どおりに設計を進めるべきではありません。根幹を支える前提が誤っている、既知の障害を再び招く、または誤った問題を解決している場合です。
   • substantive — 設計は進められますが、実質的に弱めているため、承認前に回答が必要です。
   • minor — 指摘する価値はありますが、安全に先送りしたり、見送ったりできます。
4. 解決策 — 具体的な代替案、または結論を出すための質問です。「こちらの方が悪い」では行動につながりません。「移行をなくせる、Xを行う双方向ドア型の案を検討してください」や、「2つのエージェントが同じドキュメントを書き込むとどうなりますか。設計ではこの点に対処していますか？」のように記述します。

読んだ順ではなく、重大度順に並べてください。 blocking の指摘から始めます。著者はレビューの冒頭を読み、要点が分かった時点で読むのをやめます。blocking の指摘を6つの minor な指摘の下に埋もれさせるのは、その価値を損ないます。

---

ステップ 4：調整 — 自分の指摘を批判的に読み直す

提出する前に、これらの視点を自分自身に向けてください。すべてに問題を指摘するレビューでは、著者はレビューを無視するようになります。 擁護できない指摘が1つでもあると、著者はそれ以外の指摘も割り引いて受け取ります。

• 著者の立場から各指摘を読み直し、反論してみてください。根拠を擁護できない場合は削除します。
• 各指摘の確信度と考えが変わる条件を示します。「blocking、確信度高 — 親提案の負荷数値が誤っている場合を除きます。その場合は minor に下がります」のように記述します。反証条件を示せない指摘は、おそらく指摘ではなく単なる好みです。
• 重複をまとめます。同じ根本原因から生じた指摘が3つある場合は、3つの症状を含む1つの指摘にします。
• 調整後に blocking も substantive も残らない場合は、その旨を率直に伝えます。「これは妥当です。minor な指摘が2つあります」は、完全で価値のあるレビューです。徹底しているように見せるために、重大度を作り出さないでください。

---

ステップ 5：提出する

通常は会話内で提出します。 ほとんどのレビューはメッセージで十分です。再構成した議論（ステップ 1）、重大度順の指摘事項（ステップ 3）、調整に関する注記（ステップ 4）を含めます。

ドキュメントとして保存するのは、ユーザーから依頼された場合、または後で参照する価値があるほど実質的なレビューの場合に限ります（承認または却下を控えた提案に対する blocking なレビューなど）。その場合は、次のようにします。

• レビュー対象の成果物の隣に書き込みます。write({ document: { path: "proposals/0003-feature-review.md" } })。
• edit を使って、成果物の未解決の質問（提案の場合）または未解決の質問（仕様の場合）のセクションからリンクします。プレーンな Markdown リンク [design review](./0003-feature-review.md) を使用し、バッククォートで囲んだり、HTML アンカーにしたりしないでください。
• ドキュメント自体のフロントマターまたは冒頭の行に、助言的なものであることを明記します。これは著者への参考意見であり、最終判断ではありません。成果物の所有者は著者であり、何を反映するかは著者が決定します。

指摘事項を「適用」するために、レビュー対象の設計を編集してはいけません。あなたの役割は指摘事項を提示することであり、それを反映するのは執筆スキルです。

---

ステップ 6：引き継ぎ

修正の担当者に、ブロッキングとなる指摘や重要な指摘を引き継ぎます。

• 提案に関する指摘 → /frame-a-proposal（論拠、代替案、または動機を見直す必要があります）。
• 仕様に関する指摘 → /write-a-spec（目標、対象外事項、移行、またはテスト計画を見直す必要があります）。
• 議論の結果、選択が確定した指摘（「議論の結果、同期バージョンを採用することになった」など）→ /record-a-decision。選択とその根拠を decisions/ に記録し、以前の ADR を覆す場合は supersedes: リンクを付けます。
• 過去の失敗が再び持ち込まれているという指摘 → 該当する postmortems/YYYY-MM-DD-name.md を作者に示し、設計でその失敗を明確に考慮するよう伝えます。

作者が次にどこへ進めばよいか正確に把握できるよう、引き継ぎの際にスキル名と理由を伝えます。

---

対象外

• 完全性を確認するチェックリストではありません。「セクション X が空である」ことが指摘に当たるのは、その空白によって設計が妥当性を失う場合に限ります（Alternatives がなければ選択肢を検討した証拠がない——指摘すべきなのはそこです。空の見出しではありません）。
• **ファクトチェックではありません。**個々の主張が真実かどうかを確かめるのは、正確性を確認する作業であり、別の仕事です。主張を前提として受け入れ、それに基づく設計が妥当かを検証します。ある主張が設計の根幹を支えており、かつ疑う具体的な理由がある場合に限って指摘してください。それ以外は、ファクトチェックを別途依頼してください。
• **コードレビューではありません。**バグ、スタイル、実装品質を確認するために差分をレビューすることは対象外です。このスキルでレビューするのは設計であり、コードではありません。
• **書き直しではありません。**依頼されていない限り、レビュー対象の成果物を編集してはいけません。指摘を提示し、設計を変更するのは作者です。
• **最終判定を下す立場ではありません。**レビューは、決定権を持つ作者への助言です。「却下」のように判決を下すようなレビューは権限を越えています。一方、「ここを改善すればより強固になります。ここをブロッキングと考える理由はこれです」と伝えるレビューは、その役割を果たしています。