tlc-discover

TLC Discover

このプロジェクトが実際にどの段階にあるのかを把握します。問題を理解します。解決するかどうかを決めます。そして、その後で初めて、方法を決めます。

SITUATION ────→ PROBLEM ───────→ VERDICT ───────→ DECIDE
(where this     (no solution     (a stop, or a    (two shapes, costed
 project is)     proposed yet)    record)          against this repo)

これはスクリプトではなく、前提条件の順序です。 実施するのはインタビューです。決まっていることを踏まえて回答できる質問をし、回答可能なことがなくなったら終了します。順序は自然に決まります。「方法」には「解決するかどうか」が前提としてあり、「解決するかどうか」には「現状」が前提としてあるからです。これらを4つの段階として進めると、まだリリースされていないプロジェクトに、今その問題を解決するコストを尋ねるディスカバリーになってしまいます。

ここで問題となる失敗は、事実を捏造することではなく、早まって収束することです。2ターン目に解決策を提案し、「いいですね」と言われたことで、検討は伴わないのに、決定と同じ権威を持つ決定をでっち上げてしまうことです。以下に示すものはすべて、それを起こりにくくするためのものです。

成果物は、会話に参加していない人でも、チームでも、計画ツールでも、そこから計画を立てられる設計ドキュメントです。決定があったことを記録するだけでなく、設計そのものを示す必要があります。つまり、覆すのが難しい決定、クリティカルパスのフロー、状態とその変更者、実際に存在するスキーマ、呼び出し元が依拠するコントラクトを示します。関係性や順序が内容となる場合は、図で表します。30個のリテラル値を並べた表は、設計の服を着た仕様書にすぎません。また、垂直スライスごとに構成し、作業の一部分を知りたい読者が1つのセクションを読むだけで、その差分、フロー、スキーマ、コントラクト、決定事項、未解決の質問を見つけられるようにします。Shape を読んでも何を狙っているのか伝わらない、スライスを読んでもその部分がどう進むのか分からない、あるいは Work のインデックスを見てもどのスライスが明確なのか分からないのであれば、すべての決定事項を記録していても失敗です。

重要なルール

1. 判定前に技術を提案してはいけません。 ライブラリも、プロバイダーも、パターンもです。問題のセクションでいずれかを推奨していたら、すでに問題の捉え方が解決策に偏っています。これは、提案を禁じるものであり、把握を禁じるものではありません。プロジェクトがすでに使っているもの、すでに採用したもの、すでに書きかけているものは制約です。それを後から知ると、チームが先月決着させたことをディスカバリーで蒸し返すことになります。
2. 決定が未確定なら、判定はそこで止めます。 判定を提示して、回答を待ちます。一方、Situation によってすでに誰かが決定済みだと分かっている場合、それはゲートではなく記録上の明示事項です。答えが分かっているゲートを設けるのは、承認の儀式を作り、本当に重要なゲートまで皆がクリックして通り過ぎるように仕向けることです。
3. 自分なら出荷しない選択肢を提示してはいけません。 毎回2つの形を検討します。2つ目が独立したセクションに値するのは、現実的な選択肢である場合だけです。そうでなければ、それが勝つために何が真である必要があるかを、1文で示します。それは、この計画を立てる人が知っておくべき、選択肢を除外する特性です。
4. 判断を変える数値を、調べる前に明示します。 問いのないデータは、コンテキストを無駄に消費するノイズです。また、数値が欠けていることは、問題についての発見ではありません。多くの場合、それは計測の仕組みについての発見です。質問し、情報がないことから規模を推測してはいけません。
5. 具体的な値のない決定は、決定済みではありません。 形状、境界、ステータス、フィールドなどです。後続の作業は曖昧な入力を受け付けません。ここで明確にするのが最も低コストです。
6. 影響が大きく、明確さが低いものは、ここでは決定しません。 RFC またはスパイクにします。無理に決めると、最もコストの高い成果物が生まれます。つまり、決着したように読めるのに、実際には決着していない決定です。
7. 参照アーキテクチャではなく、このコンテキストに合わせて解決します。 推奨案は、測定された問題に答える最小限の形です。それより重い案を採用するには、現時点で真であるか、近いうちに真となる信頼できる条件が必要です。読者の視野を広げるためだけに存在する選択肢も歓迎しますが、その目的を明記してください。それぞれ1行にとどめ、候補のように装ってはいけません。

インタビュー

今答えられることを尋ねてください。前提条件が確定している質問はすべて妥当です。前提条件がまだ未解決の質問は妥当ではありません。なぜなら、その答えは推測であり、あなたはそれを発見事項として扱うことになるからです。答えられることが何も残っていないときに完了です。下記のセクションをすべて訪れたときではありません。まだ到達していないセクションで重要な質問でも、尋ねる必要があります。

ここにあるものは、ただ存在するというだけの理由で段落を書かれることはありません。 入力のないステップは一行で済みますし、内容のないセクションはそもそも現れません。ましてや「N/A」を下に添えた見出しとして現れることはありません。同じ儀式に謝罪の言葉をかぶせただけです。これは質問とドキュメントの両方に当てはまり、これによって一つのスキルが2時間の変更にも四半期の仕事にも対応できるのです。

すべての質問には、あなたの推奨回答とその理由を一行で添えます。 そうすれば同意には一言で済み、反対には一文で済みます。一方、空欄の質問は、ユーザーがここに来てやってもらうはずだった作業をユーザーに押し付けることになります。あなたが推奨を持たない質問は、たいてい調べるべき質問です。

事実は調べ、決定は尋ねる。 リポジトリ、トラッカー、ドキュメントで決着できることは、自分で行って決着させてください。読めばわかったはずの事実に誰かの注意を費やすことは、セッションが「記入用紙」という評判を得る方法です。プロダクトの意見、優先順位、リスクへの許容度は、本人たちだけのものです。

フロンティアは広くても、デリバリーは小さく保ってください。答えが互いに依存し合う場合は質問を一つ、依存しない場合は二つです。フロンティアが決めるのは何が尋ねられるか、そしていつ終わるかであり、一度にいくつ届くかではありません。一度に十個は記入用紙の一括投下であり、人は記入用紙の一括投下には同意で答えます。

話すことではまったく答えられない質問もあります。 どのように感じられるべきか、1ページか3ページか - これらには反応できる何かが必要であり、それに取り組み続けるとセッションの長さが倍になり、何にも収束しません。その瞬間に気づいて別の場所へ回してください。作ることだけが答えるスパイクへ、見ることだけが答えるデザイナーへ。そのルーティングは結果であり、抽出の失敗ではありません。

状況

以下の質問をそもそも尋ねる価値があるかどうかは、3つの事実で決まります。これを見誤ると、まるで別のプロジェクトを調査しているかのようなヒアリングになってしまいます。

このプロジェクトがどの段階にあるか。 安定して利用されている製品には、測定できる現在があります。まだリリースされていないものには、現在がまったくありません。小さな現在ではなく、何もないのです。そのため、現在のコストに関する質問を4回しても何も得られず、結果として根拠の薄い提案に見えてしまいます。開発が活発に進んでいるプロジェクトには、指標よりも価値のあるものがあります。誰かが作成したロードマップと、誰かが途中まで実装したコードです。

意思決定がまだ開かれているか。 誰もまだ決めておらず、それこそがこの取り組みの存在理由であることもあります。一方で、ロードマップや四半期計画、あるいは上級者がすでに決定している場合もあります。そのときの誠実な役割は、誰が決めたかを記録し、セッションを方向性の検討に充てることです。最初に決めつけずに尋ねてください。この2つでは、尋ねる内容がほとんど重なりません。

これに関係する進行中の作業は何か。 すぐに確認できるもの、つまり作業中のブランチ、課題トラッカーの現在のサイクル、連携済みのナレッジベース、このスキルがすでに作成した設計ドキュメントなどを調べ、それ以外は尋ねてください。チームが先週始めたことを知っているのは、その場にいる人であり、どんな調査よりも確かな情報源だからです。これらが一つも存在しない可能性も考慮してください。トラッカーも Wiki もないプロジェクトは珍しくありません。リポジトリと回答者がいれば、いつでも十分です。

何が懸かっているか。 作業にどれくらい時間がかかるかではなく、それについて判断を誤った場合にどれほどの損失が生じるかです。1人が午後のうちに元に戻せる変更と、全員のデータを移行する変更は、ロードマップ上では同じ規模に見えても、ここではまったく別物です。この事実によって、残りの作業をどこまで行うかが決まります。

進行中の作業は、背景を変えるだけでなく、答えそのものを変えます。別の場所で半分まで作られた機能があれば、これはその拡張になります。以前の設計ドキュメントで決着した判断は、確定済みの前提情報です。それを蒸し返すのは、徹底的に見せかけた手戻りです。また、誰かが現在書き換えているファイルは、まだ回避できる競合です。方針を決めるだけならコストはかかりません。

6週間後に読む人が、問題のセクションが薄いのはまだ何もリリースされていなかったからなのか、それとも誰も思いつかなかったからなのかを判断できるよう、それぞれを1行で記録してください。進行中の作業については、先例として踏襲するものと対象外にするものを、それぞれ1文で記録します。コミットハッシュやメソッド名がドキュメントに紛れ込みやすいのはここですが、どちらも記載すべきではありません。

調査そのものが不要な作業もあります。そう判断することも仕事の一部です。 懸かるものが小さく、午後のうちに元に戻せる答えで、その場に意見の相違がないなら、段落で推奨事項を示して終わりにしてください。ドキュメントも、結論も、セクションも不要です。機能自体を退けられない調査は追認であり、調査そのものを不要と判断できないなら、人々が避けるようになる事務作業です。その結果、本来必要だった意思決定について調査が実施されなくなります。基準を満たすには、次の3つすべてが同時に当てはまる必要があります。元に戻すのが簡単で、影響範囲が小さく、意見の相違がないこと。どれか1つでも欠けていれば、セッションを実施します。

問題

このフェーズでは、技術的なことは何も起きません。人は「キャッシュが必要だ」「Stripeを追加すべきだ」と解決策を抱えてやってきます。最初にすべきことは、その解決策が何への答えだったのかを突き止めることです。持ち込まれた解決策はたいてい、比較検討した末に選んだものではなく、最初に思いついたものだからです。

まず、どの種類の問題なのかを見極めてください。問題の種類によって問いが異なり、誤った問いを使うと、確信に満ちた誤答にたどり着くことになるからです。痛みの問題とは、今起きていて何らかのコストを生んでいることです。測定できる「今日」があります。不在の問題とは、すでに存在するプロダクトに能力が欠けていることです。誰もそれをしていないため、困っている人はいません。構築の問題とは、まだ開発中のものに必要な次の要素です。「今日」も、代替手段も、尋ねる相手もありません。プロダクトがまだ誰にも届いていないからです。

新機能のほとんどは2つ目の種類ですが、1つ目の種類の問いに当てはめると、どれも単なる好みのように見えてしまいます。最初の2種類の問いを3つ目に当てはめると、すべての問いへの答えが空になり、もともと疑問視されていなかった作業の根拠が弱いように見えてしまいます。

痛みについては、誰が困っているのかを、実際に話を聞きに行けるほど具体的に特定します。今どんなコストが発生しているのかを、ビジネスが実際に重く受け止める単位で把握します。たとえば、分数、チケット数、解約数、返金額、オンコールの呼び出し回数です。何も変えなかったらどうなるのかも確認します。これにより、実際の問題と単なる好みを区別できます。放置しても何のコストも発生しない問題は、言い方が洗練されているだけの好みです。

不在については、今日、誰がこれをできないのかを確認し、続いてこのフェーズ全体を支える問い、その代わりに何をしているのかを尋ねます。ソフトウェアができるのを座って待っている人はいません。スプレッドシートを使ったり、手作業で進めたり、サポートチケットを送ったり、競合製品を使ったり、ひっそりと諦めたりします。その結果、こちらには何も伝わりません。代替手段が証拠です。観察でき、機能ができる前から存在し、「今どんなコストが発生しているのか」に正直に対応するものです。さらに、これを作らなかったら何が引き続き不可能なのか、そして、それが理由で誰が去り続けるのかを確認します。

構築については、ユーザーではなく、約束が軸になります。ロードマップ、ピッチ、以前の設計ドキュメントで、この要素によって何が可能になると約束されていたのか。これがないと何が滞るのか。顧客にとってではなく、開発中のものにとって何が滞るのかを確認します。どのブロックに着手できないのか、何が仮実装になるのか、何を二度書くことになるのか。そして、この種の問いが誠実さを保つための問い、次の要素を待つのではなく、なぜ今なのかを尋ねます。構築では、いずれ作る価値のあるものがほとんどであり、今判断すべきなのは順序だけだからです。

ある種類の問いを別の種類の問題に当てはめてはいけません。「何もしなかったら何が壊れるのか」は、不在の場合は答えが自明です。何も壊れません。それが不在の意味だからです。構築の場合は、「プロジェクトが滞る」という本当の答えが、特別扱いを求めているように聞こえますが、実際にその通りです。どちらかを調査結果として扱えば、このスキルはチームに、これから作れるはずの新しいものをすべて諦めさせることになります。

鋭く問いかけてください。曖昧な答えは書き留めるものではなく、掘り下げるべきものです。「ユーザーが不満を感じている」なら、どのユーザーが、何をしていて、どのくらいの頻度でそう感じているのかを尋ねます。抽象的な表現はすべて、数字か名前が出てくるまで問い直してください。曖昧な答えを集めて後から整理するのではなく、その場で問い直します。

エンドユーザーがいない場合――リファクタリング、インフラ、プラットフォームの作業など――変わるのは関係者だけです。オンコール担当者が困り、次の機能が困り、チームが困ります。そして、ここでの一連の流れとは、デプロイ、デバッグ、復旧のために、誰かが今日何をしているかという運用上の手順です。「社内向けだから」と問いを省けば、社内向けの作業はいつまでも機能開発に負け続けます。

エビデンス

何かを取得する前に、どの数値が意思決定を変えるのかを伝えてください。それから、その数値を確認します。広く情報を集めようとするのは誤りです。誰も質問していないダッシュボードは、何の役にも立たないままコンテキストを消費し、意思決定を改善することなく文書を長くします。

利用できるものはプロジェクトごとに異なるため、決めつけずに調べてください。プロダクト分析、エラー追跡、ログ、課題管理ツール、サポート件数など、実際の環境で使えるものを利用し、いずれかが必ず存在することを前提にしてはいけません。最低限確認できるのはリポジトリです。これは常に存在します。

数値がないことは、何かの証拠にはなりません。 その背後には正反対の状況が隠れています。計測したところ小さいというのは問題についての発見であり、誰も計測できるようにしていないというのは計測環境についての発見です。追跡されていないことが起きる頻度は、実際に起きる頻度と同じです。この二つを混同すると、追跡されていない問題を小さい問題だと読み違えることになります。

ですから、数値がない場合は、推測せず、尋ねてください。 その場にいる人たちは、サポートや営業、あるいは自分たちの一週間の経験から状況を知っています。それはどちらの方向への暗黙の思い込みよりも確かな情報です。誰も測れないことと、その代わりに聞いたことを、それぞれ何であるかを明記して記録してください。測定可能にすることが最初の一手として適切な場合もありますが、自動的にそうなるわけではありません。また、存在しない機能には、計測する対象もありません。

エビデンスの収集はインタビューで行うものであり、文書の一節ではありません。 その目的は結論を出すことであり、結論が出たら、それを左右した数値は「Problem」に記載します。問題を読む人が必要とする、その一文に入れてください。数値と、数値がない項目を別々に並べるのは、意思決定に至るまでの作業記録です。文書に記録するのは意思決定であり、作業過程ではありません。問題の測定に、まだ存在しないイベントが必要なら、それはスライスです。

ジャーニー

人が実際にたどる一連の流れを確認し、本人にも確かめてください。図でもペルソナでもありません。ここで作るのはマップではなく、重要な状態と、それぞれの状態で何が起きるべきかです。これは、このあと計画を立てる人が必要とする情報であり、そうでなければその人が独自に作り上げることになります。

ジャーニーの確認はエビデンスに続いて行います。数値によって、どの状態を詳しく検討する価値があるかが変わるからです。ほとんどの利用が一方の経路をたどるなら、その経路の空状態、期限切れ、放棄にはきちんと向き合う必要がありますが、もう一方の経路は一行で済むかもしれません。すべての分岐を同じ深さでたどると、誰も読まないマップになってしまいます。

実際の一連の流れには、誰もが説明する正常系より多くの状態があります。空の状態、初回、再試行、途中まで完了した状態、期限切れ、権限がない状態、ユーザーがいったん離れて翌日に戻ってくる状態などです。これらを見つけ、具体的な質問としてユーザーに確認し、ユーザーの判断を記録してください。

これらはプロダクト上のエッジケース、つまり何が起きるべきかについてのものです。並行性、冪等性、認可、可観測性といったエンジニアリング上の横断的な関心事は、ここでは尋ねません。これらは後でコードを確認して判断し、元に戻すのが難しいものだけを「Key decisions」に記載します。それ以外は計画に含めます。境界は明確です。回答にプロダクト上の判断が必要なら、ここで尋ねます。リポジトリの確認が必要なら、後回しにします。

文書にジャーニーのセクションはありません。 ジャーニーについて尋ねるのは、結論を出す前のプロダクト確認の場です。そして、確認済みの各状態は、それに回答するスライスの状態テーブルに、呼び出し元に見える内容と並べて記載します。文書の冒頭にジャーニー全体を置き、各スライスに契約全体を記載するのは、同じ事実を異なる視点で二重に記録することです。計画を立てる人は、両者を手作業で突き合わせなければなりません。どのスライスにも触れられない状態は、「Work index」に一行で記載し、その状態を処理する既存のコードを示します。

対象範囲を決める

このディスカバリーで回答する質問と、回答しない質問を明示し、調査を始める前に合意を得てください。調査には自然な終わりがなく、この後のフェーズでは、時間のかかる作業として、選択肢ごとにコードを確認します。最初に境界を決めなければ、「問題を理解する」がリポジトリ全体の監査になってしまいます。

作るより安く済ませる

結論を出す前に、ここで一度、解決策の選択肢を広げます。上のフェーズでは、持ち込まれた解決策から問題を掘り起こしました。そのまま同じ解決策を技術フェーズに渡せば、技術フェーズは忠実にその二つの形を生み出します。間違った解決策が二つになっても、間違いであることに変わりはありません。各ステップが進展しているように見えるため、このスキルが最も気づきにくい失敗です。

そこで、提案されたものを作らずに、測定したコストをどうすれば取り除けるかを考えます。デフォルトを変える。手順をサポートするのではなく、なくす。上流で混乱を防ぐ文言にする。最初の10件は手作業で対応する。通常、何を作るべきかがわかるのは、こうしてみてからです。コストの大半を占める部分だけを解決し、残りはそのままにする。購入する。

購入については、外部を調べる必要がありますが、範囲は限定します。そもそも該当する製品が存在するか、そして置き換えられる数週間分の作業と比べて、おおよそいくらかかるかを確認します。ベンダーの調査ではありません。また、ルール1への違反でもありません。ある製品カテゴリが存在すると記すことは、パターンを提案することではないからです。誰がどのように 形にするか は、Prior art まで待ちます。

ほとんどはその場で退けられます。それが目的です。ユーザーの目に見えるところで検討することで、コストのかかる道をデフォルトではなく選択肢にします。候補が残った場合、それはディスカバリーで最も大きなリターンが得られる瞬間です。そして、それが起きるのはここか、どこでもありません。結論の後は、作業の形とコストが確定し、どのように 作るかを比べる段階では、誰も 何を 作るかを再検討しないからです。

判定

決定がすでに確定している場合、これはゲートではなく記録です。決定した人と日時を一行で記し、そのまま設計に進みます。例外は限定的ですが、実際にあります。問題の検討結果が決定と矛盾するなら、そのことを率直に述べて止めてください。確定済みの計画を中断するだけの価値があるのは、その指摘です。それ以外の場合、すでに下した決定を改めて審査にかけないでください。

決定が未確定なら、結果は四つです。構築する、より小さいもの、または別のものを構築する、今は構築しない、構築しない。最後の三つを選べることが、最初の選択肢に価値を与える大きな要素です。

構築中は、判定の対象は存在するかどうかではなく、順序です。プロジェクトの中核として設計された要素に対して「構築しない」が有効な選択肢となることはまれですが、「X の後まで今は構築しない」はよくあります。その場合も同じ負担を伴います。待つ間に何が滞るのか、後から実現した場合に何を二度書くことになるのか、です。

二つ目の選択肢には落とし穴があります。「より小さいもの、または別のもの」は新たな提案なので、問題のセクションはそれに対しても依然として有効でなければなりません。測定したコストのどの部分を取り除き、どの部分を残すのかを示してください。そうしないと、少し異なる問題への安価な答えが、安いという理由だけで承認されてしまいます。

見送ることも賭けであり、ほかの選択肢と同じように、それ自体の根拠が必要です。負担は自然と偏ります。構築するには証拠を示す必要がある一方、何も測定されていなければ、構築しないという選択が既定値になります。これは中立ではなく、判断を一方に傾けるものです。したがって、「今は構築しない」と「構築しない」にも、それぞれ根拠が必要です。現状を続けるコストと、答えを変えるために何が真実になる必要があるかを、実施するコストと同じ単位で示してください。一方がエンジニアリングの週数で、もう一方が形容詞なら、形容詞は必ず負けます。そして、その形容詞はたいてい顧客のことです。

問題のフェーズで定めた言葉を使い、理由とともに示してください。何もしないコストと、何かをするコストを比べます。それから止めてください。技術的な選択肢について話し合う前に、ユーザーが確認します。ここがゲートです。自分で通り過ぎてしまえば、それまでのすべてが無意味になります。

**判定は会話のゲートであり、文書では一行です。**判定はヘッダーの Status に記載します。confirmed by <who>, <date>、または理由を添えた declined のいずれかです。それ以外の場所には記載しません。理由、検討したより安価な方法、比較した四つの結果は、決定に至るまでの作業です。それらは会話の中にあり、必要とする読者は、確認した人に尋ねられます。ヘッダーにすでに記載された内容を繰り返す Verdict セクションは、文書を長くするだけで、決定をより確かなものにはしない儀式です。

何をもって成功とするか

判定は賭けです。そして、誰も結果を確定しない賭けは、日付が付いただけの意見にすぎません。ですから、技術的な話に入る前に、これをやる価値があったと判断できる条件を、Evidence が定めた問題そのものの単位で示してください。コストが返金なら、成功は返金額で測ります。手作業にかかった時間が問題なら、成功は時間で測ります。ここで単位を変えると、賭けがいつの間にか絶対に負けないものになってしまいます。

「リリースした」は成功ではありません。すでにやると合意したことにすぎません。 このすり替えは、この規律で最もよくある失敗です。成功が保証されているからこそ、居心地よく感じられます。機能が公開されたことは成果物であり、誰かの問題が解決したかどうかにかかわらず成り立ちます。増える一方の数値も同じです。

3つの項目で決着をつけます。成功の条件 ―― 成果と、おおよその達成時期。早期シグナル ―― 四半期ではなく数日で確認できる兆候と、賭けがうまくいっていない場合にどう見えるか。目的は、対処が安いうちに行動することです。レビュー ―― 日付またはトリガーと、確認する人。これがなければ誰も確認しません。また、決定したことから学べる唯一の機会がレビューです。

影響が小さい場合は、最初の項目だけで十分です。見直す人がいない変更にレビュー日を設けるのは、必要な変更に対してこのセクションを省くよう人々に教える儀式にすぎません。

成果を測定できない場合は、Evidence が使う言葉で答えてください。記録されていないことは、規模が小さいことと同じではありません。そのうえで、正直な選択肢を2つのうちから選びます。指標ではない、観察可能な代替指標を挙げます。たとえば、スプレッドシートの更新が止まる、サポートスレッドが再発しなくなる、手作業の手順がランブックからなくなる、といったものです。または、何を計測できるようにする必要があるか、その計測がこの作業に含まれるかを明記します。構築の場合、代替指標は構造的で確認可能なものになります。待機ブロックを開始できること、スタブにしたものがそうなっていないこと、などです。

測定に、まだ存在しないイベントが必要なら、それは構築作業であり、計画に含める必要があります。 計画担当者がこのセクションからタスクにするのは、これだけです。ここに書かれたほかの内容は、受け入れ基準にはなりません。「返金が3分の1に減る」ことはマージ時のテストでは証明できません。これを後工程に持ち越すと、正しい実装がブロックされるか、合格できるよう基準が弱められます。

判定が今は行わないまたは構築しないの場合、ドキュメントのステータスを declined とし、理由、状況、問題、境界を記載します。再検討する条件は境界に記載してください。却下した作業について、Shape やスライスを作り出してはいけません。

判断する

次に、リポジトリを開いてください。何かを提案する前に、また、リポジトリの外にあるものを読む前に開きます。選択肢とは設計だけではなく、このリポジトリでかかるコストも合わせたものです。同じ選択が、あるコードベースでは明白でも、別のコードベースでは馬鹿げていることがあります。先に提案して後から確認すると、方針を固めるのではなく、自分の立場を擁護することになります。先にベンチマークを読むと、他人の視点を通して自分のコードベースを見ることになります。

リポジトリからわかること

** churn は、どの選択肢が正しいかを示すものではありません。間違えたときにどれだけのコストがかかるかを示します。** これが堅牢性の軸を調整する基準であり、git は常に利用できるため、入手できる最も有用なシグナルです。年に二度しか変更されないファイルにある一方通行のドアは、選択を誤っても安く済みます。同じドアが毎週変更されるファイルにあれば、毎週請求が届くようなものです。答えがすでに「ごくわずか」である場合は、コマンド一つで確認して先に進みましょう。また、プロジェクトができてから3か月しか経っていなければ、読み取れる履歴はありません。

変更頻度はどちらの方向にも曖昧なので、決して単独で読み取らないでください。変更頻度が低いのは安定しているからかもしれませんし、放置されているからかもしれません。あるいは、誰もが迂回するほど扱いにくいのかもしれません。変更頻度が高いのは、ビジネスの最重要経路だからかもしれませんし、適切に分割されたことがない領域だからかもしれません。これを区別するための、安価なシグナルが二つあります。変更に関わる著者の人数です。著者が多いほど、変更は単なる編集ではなく調整コストになります。そして変更の新しさです。6か月経っても動き続けている領域は、まだ形が定まっておらず、今日抽象化する価値はありません。

慣習も読み取り、検討コストではなく優先順位として扱ってください。このコードベースが、目の前の問いにすでに答えを出しているなら、何が問題なのかを具体的に言える場合を除き、その答えに従います。代替案のほうが何を好ましく感じさせるかではありません。外部のアイデアが既存の案と同点にすぎないなら、採用しません。同点の判断は、どちらが文章にしやすく興味深いかで決まりがちです。それこそが、もっともらしい改善を一つずつ積み重ねるうちに、プロダクトラインが方向を逸れていく原因です。

先行事例

誰かがこの問題の一部をすでに解決しています。その方法を読むのは、本番環境で発見するより安価です。数値に適用される規律は、ここにも当てはまります。調べる前に、ベンチマークによって何が変わるのかを明確にしてください。そうしなければ、「他の人はどうしているか」という問いに、関係のない企業についての段落が三つ返ってくることになります。

持ち帰る価値のあるものは三つあります。独立したチームの間で繰り返し見られる形です。収束は証拠であり、どこでも同じ境界が見られるなら、それは流行ではなく、たいてい重要な役割を担っています。誰もが報告している失敗です。このスキルで最も安価に得られるものは、出荷してからではなく、読むことで回避できるエッジケースです。そして、不要だとわかったものです。これは、チームが取り除いたものについて説明して初めて得られます。

決してそのまま適用できないのは規模であり、このセクションが害をもたらすのもそのためです。 あなたの千倍のトラフィックを持つ企業が公開した設計は、その企業の制約を忠実に説明しています。それを採用すると、自分には存在しない問題に対するコストまで背負い込むことになります。ベンチマークがより複雑なものを推奨する場合は、その企業の条件のうち、どれを共有しているのかを述べてください。一つも共有していないなら、それは興味深くても無関係であり、そのように述べること自体が調査結果です。設計そのものではなく、設計の背景にある制約を読んでください。

比較可能なものが何もない場合も、それは結果です。問題が特殊なのか、あるいは問題の捉え方がずれていて、誰もその名前で呼んでいないのかもしれません。後者なら、もう一度調べる価値があります。

間違えたときの影響が小さいところでは、このセクション全体を省略してください。 その場にいる全員がすでに思い描ける形に、文献レビューは必要ありません。それでも実施すれば、これを防ぐために設けられた水増しになってしまいます。ウェブアクセスもどこでも保証されているわけではありません。利用できない場合は、その旨を述べてください。今日ある製品の動作について記憶を頼りに推論するのは避けてください。それこそ、ナレッジチェーンが禁じている、作り上げられた制約です。実際に読んだものは Sources に引用してください。Sources に含めるのは、調査の根拠となった文書だけです。ロードマップ、意思決定記録、以前の設計文書、外部の参考資料が該当します。コードパスは、裏付ける事実のすぐ横に本文中で引用し、Sources には重複して記載しません。

2つの形

個々の決定を別々に提案するのではなく、全体の形を提案します。選択肢が2つずつある決定が8つあれば、選択肢は16個になり、読む人は疲れ果ててしまいます。実際に分岐するのは形であり、細かな決定はそこから導かれます。それぞれ一行で十分です。

1つ目の形は、分かりやすいものです。すでに文脈が示しているもの、労力に対する価値の比率が最も高いもの、妥当なチームが出荷するものです。2つ目は、時間が経っても持ちこたえる形です。今のコストは高くなります。軸は常に同じです。今払うか、後で払うか。その軸に名前を付けることで比較が誠実になり、2つ目が単なる別の趣味ではなく、異なる賭けになるのです。

それぞれ、どのような条件なら優位になるかを示します。そうすれば、誰かが建設的に異議を唱えられます。「もう一方のほうが好きだ」ではなく、「その条件は違う。こちらの領域は毎月変更している」と言えるようになります。

より軽い形を推奨案とし、より重い形はそこから推奨を覆さなければなりません。そして、推奨が覆るのは異例ではなく、普通にあり得る結果です。より重い形を正当化する条件は将来についての主張であり、確認されていない将来の主張をもとに、実現しない規模に今日のコストを払うことがないよう、デフォルトを設けます。そこで条件を現在形で示し、確認します。「2つ目のリージョンが必要になるかもしれない」ではなく、「現在は1つのリージョンで運用しており、ロードマップ上、もう1つ追加する予定はありません」とします。

条件が当てはまるなら、そう明記して切り替えます。 Situation にはすでに根拠が集まっています。ロードマップ上の確約、現在進行中でこれを必要とするブロック、今日すでに存在する2つ目の利用者などです。したがって、「現実的に近い」とは、そのリストにある事実を指し、決して単なる感覚ではありません。リストに当てはまるものがあるのに、今、より軽い形を出荷すれば、同じものを2回作ることになります。

作り込みが足りない場合も、それ自体が根拠となり、コストのかかり方も異なります。 過剰な作り込みは目に見えるお金の無駄になります。一方、作り込み不足は、書き直しに加え、そこに至るまでに壊れたものへの対応も招きますが、どちらも見積もりには含まれません。したがって、より軽い形を推奨する場合は、それでは耐えられないことと、何が書き直しを必要とするのかを明記してください。どちらも挙げられないなら、2つの形を比較したのではなく、1つの形を説明して、それをデフォルトにしただけです。

ほかの選択肢は、異なる視点として示し、そのように明記します（ルール7）。実際には3つのアプローチがあるものの、そのうち2つを除外する場合は、それぞれを除外する理由を一行ずつ添えて3つすべてを挙げるほうが、採用した案だけをひそかに持ち込むより優れています。そうすることで、「これが私の答えです」から「これが選択肢の全体像で、ここから絞り込まれます」へと伝え方が変わります。各選択肢は一行にとどめ、Decision には入れず、推奨案を必然に見せるために水増しもしません。その水増しこそ、ルール3が禁じるわら人形論法です。

2つ目の形が本当に有力な候補でないなら、独立したセクションを設ける必要はありません。「より重い形が割に合うのはNを見込む場合だけですが、そうは見込んでいません」という一文で比較全体を示し、採用しなかった代替案と、それを退けた特性を計画担当者に伝えられます。

形は最大4文です。記録が何か、運用で何をするか、どこに境界があり、変更にどれだけのコストがかかるか、そして条件付きのより重い代替案です。どのレイヤーに従うかは書きません。リポジトリのルールですでに決まっており、それを言い直すのはハーネスが文書に漏れ出すことになります。設計がルールから逸脱する場合に限り、一文を使う価値があります。前例も挙げません。Situation › In flight ですでに示されています。Shape で手法に言及しているなら、それは実装の話です。Key decision を言い直しているなら、それは繰り返しです。

ドキュメントに記載する内容

ドキュメントに記載するのは、基本的な決定事項――プロダクト、API、スキーマ、方向性――だけであり、計画から導き出せる内容は含めません。 この分量を保つためのルールは3つあり、ドキュメントを書いた後ではなく、書く前に確認します。

1. 各決定事項は、それを管轄する最上位の箇所に一度だけ記載します。 重要な決定事項は、覆すのが難しいすべての内容を記載する場所です。スライスでは「重要な決定事項2」と示して先に進みます。同じ事実を「概要」「重要な決定事項」、スライスの表、図に記載しても、4つの見方になるわけではありません。読者が同じ決定事項に4回出会い、メンテナーが3か所で更新することになります。10個の決定事項を80回述べる設計は、各セクションだけを見れば妥当に見えても、冗長に感じられます。
2. 識別子の上限は、ルート、テーブル、カラム、クラス、用語集の用語です。 それより細かいもの――メソッド、コンテナートークン、ファイルパス、CSS セレクター――は設計に記載しません。ルートとクラスからメソッドを特定できないなら、それは計画の問題です。メソッドまで記載した設計は計画の領域に踏み込み、計画が役割を果たした瞬間に計画とのずれが生じます。
3. ドキュメントには、何を実現するかを記載し、何をするかは記載しません。 状態テーブル、コントラクト、スキーマがスライスを定義します。追加するファイルや変更するメソッドの一覧は計画の成果物です。それを含む設計は、設計の見出しを付けたタスクリストにすぎません。

スライス

設計は、ビューの種類ではなく、垂直スライスごとに構成します。スライスとは、担当者を割り当てられる垂直の単位です。レコード、それを動かす操作、新しい子を示す親、画面が含まれます。また、読者が一か所で内容を理解できるよう、提供するもの、ステータス、状態テーブル、そのスライスに内容があるビューだけを記載します。ある操作を理解したい読者は、1つのセクションを読めば済みます。すべてのフローを「フロー」に、すべてのテーブルを「スキーマ」に、すべての決定を1つのテーブルにまとめたドキュメントは、書き手にとって都合のよい構成です。読者は1つのスライスを組み立てるために5つのセクションを読み回り、諦めてしまいます。

まずスライスを切り分けてから、内容を埋めます。 通常は5〜8個です。スライスが1つなら、セクションは1つで、目次は不要です。「請求書の支払い」はスライスですが、「サービスを書く」はタスクであり、タスクは計画に属します。目次は、スライス、完了時に実現している内容、ステータスを示す表で、その後に順序を記載します。ドキュメント内の曖昧さはすべて、このステータス列に現れます。clear、デフォルトを採用したopen、rfc、spike、designです。

スライス名には、ドメイン用語またはコード識別子を使い、文章上の動詞は使いません。 「請求書」や「請求書の支払い」は、テーブルやルートなど、読者が検索できるものを指します。「請求する」や「精算する」は、リポジトリにも用語集にも存在せず、その場にいなかった読者が最初に尋ねるのは、それが何を意味するのかです。同じ原則は文章にも当てはまります。レコードは、毎回用語集と同じ名前で呼びます。同じものを別の名詞で表すのは、文章としてどれほど自然に読めても、用語集が禁じる同義語です。それが最初に紛れ込むのは設計ドキュメントです。

スライスは、その状態テーブルと、そのスライスだけが記載できる内容で構成します。 状態テーブル――このスライスが扱う各ジャーニーの状態、どうなるべきか、呼び出し元に何が見えるか――がスライスの受け入れ基準です。このようにジャーニーを分けて記載することは、確認にもなります。ユーザーが確認した各状態には、いずれかのスライスに行があるか、すでに何が処理しているかを示す1行が目次の下に必要です。インタビューで確認した状態がどのスライスにも存在しないことは、作り込み不足の具体的な形であり、リリースせずに読むだけで発見できる唯一の形です。「追加／変更」リストはありません。計画は、コントラクト、スキーマ、フローからファイルとメソッドを導き出します。スライスごとの決定事項テーブルもありません。コストのかかる内容は「重要な決定事項」に記載し、覆せるもので読者から異論が出る価値のある内容は、「検討した代替案」の1行にまとめます。選択肢と、それが適切となる条件を記載します。 導出可能な規約は、スライスごとではなく、索引の下に一度だけ記載します。 コピーするテキスト、トリミング、並び順、400 の正確な文言、ボディ参照とパス ID がどのコードを取得するか - 「すべて Invoice が行うとおり」と、その規約を保持するレコードを添えて。これらをスライスに置くと、重要な 7 つの決定が、重要でない 23 の決定の下に埋もれてしまいます。

関係や順序が内容そのものである場合は図を描き、そうでない場合は文章を書きます。 各ビューは、そのビューのための内容を持つスライスにのみ現れます:

• スキーマ - スライスがテーブルを作成または変更する場合: カラムテーブル - 名前、型、NULL 許容性、参照、備考 - に加えて、索引と、既に存在するテーブルで何が変更されるか。コードではありません。構築者はカラムテーブルを ORM 呼び出しに変換する方法を知っています。複数のレコードを関連付ける場合はエンティティ図を、コードと照合したうえで。あるスライスが変更するが別のスライスが作成したテーブルは、それが作成された場所に置きます。
• フロー - スライスが一方通行の扉を保持する場合: 参加者がファイルではなくレイヤーであり、ステップが、読み取り前の拒否、失敗しうる読み取り、トランザクション、そしてクリーンに敗北しなければならない競合であるシーケンス図。トリミングや存在チェックではありません - それらは計画のものです。ステータスコードごとではなく、扉ごとに 1 つ。
• 状態 - 状態が 2 つを超える場合、または書き込み者が 1 つのみの場合のみ。2 つの状態と 1 つの遷移は Key decisions の 1 文であり、それらの図は 1 文を絵にしたものです。
• コントラクト - スライスが追加するエンドポイントごとに 1 行: メソッド、パス、リクエスト形状、成功レスポンス形状。失敗コードは、それがエンコードする結果の隣の状態テーブルに既にあります。
• Open、RFC、スパイク、設計 - それらがブロックするスライスに置き、スライスのステータスがどれであるかを示します。グローバルなハンドオフセクションはありません。

Key decisions は索引の上に、文章で、5 から 8 項目記載します: 元に戻すのが難しいものは、それがどこにあっても。そこで読むのをやめた読者は設計を理解できます。8 項目を超える必要があるなら、形が見つかっていません。各項目は不変条件か配置であり、決してメカニズムではありません - 「Payment の記録と Invoice の支払い済みマーク付けはアトミックである。失われた競合は孤児を残さない」は決定です。それを実現する SQL はそうではありません。

マイグレーションとロールアウト は、Situation が製品が使用中であると述べた場合にのみ現れます: 既存の行、バックフィル、デプロイ順序、更新前に古いクライアントが何を見るか。構築中は 1 行か何もなしです。定常運用では、ここに技術的リスクが宿り、これを飛ばした設計はコードのコストは見積もったが変更のコストは見積もっていません。

すべての図は、掲載される前にリポジトリと照合されます。存在しないメソッドを呼び出すシーケンス、基数が誤ったエンティティ図、コードが到達できない状態 - それぞれは絵をまとった捏造された制約であり、絵は文章より速く信じられます。Mermaid が既定です。ドキュメントのある場所で差分が取れ、レンダリングされるからです。設計ハンドオフから渡された描画済み画面はリンクされ、決して再描画されません。

不変条件であり、メカニズムではありません。 「Invoice ごとに 1 つの Payment、そして失われた競合は孤児の Payment を残さない」は決定です - これは製品上の帰結であり、一意索引だけを読んだ計画者は、必要とするアトミック性に到達しないでしょう。「条件付き UPDATE ... WHERE status = 'open'、ゼロ行はロールバックを意味する」はメカニズムです - 不変条件を満たすいくつかのうちの 1 つであり、それを名指しすると他を閉ざし、メソッド名を禁じているドキュメントに SQL を持ち込むことになります。設計は不変条件を述べ、明白な前例がそれを侵害する場合はそう言います - 「Refund はステータスと台帳エントリを別々に書き込む。ここではそれをコピーしないこと」は、計画者が導出できず、さもなければ間違えるであろう一文です。テスト: 有能な計画者が不変条件だけを読んで、自力でここに到達するか - そして同じ場所に到達するか? はいなら、それは計画者のものです。前例が間違った方向を指すなら、警告はあなたのものです。 コードが登場することはほとんどありません。 ORM の完全なテーブル定義、サービスメソッド、ルートハンドラー、SQL の述語はどれも、ビルダーがカラムテーブル、フロー、契約をもとに記述するものです。それらを設計に書くと、設計文書がコードの照合先ではなく、コードから乖離するものになってしまいます。例外は、列挙型の値、パス、レスポンスの形など、それ自体がプロダクトの決定事項となるリテラルです。これらはすでに状態テーブル、契約、スキーマに記載されています。

いつ決定を止めるか

残るすべての問いは、2 つの軸で整理できます。このグリッドが終了条件です。エネルギーが尽きたときではなく、すべての問いが 4 つのセルのいずれかに収まったときに完了です。

	明確	不明確
影響大	決定します。形、代替案、判断が変わる条件を記録します。	決定しません。 RFC が必要です。答えを得る方法が実際に作ることだけなら、スパイクを実施します。
影響小	1 行で記録します。	妥当な既定値を採用して記録し、実装しながら決定します。

右上のセルは、決定することが進捗のように感じられるため、ルールが破られやすい箇所です。重大な選択肢を誰も明確に理解できていないなら、それこそ会話の中で決着をつけるべきではありません。RFC に回すことは、発見が失敗するのではなく、発見が機能しているということです。

不足しているのが、実際に作らなければ得られない知識、つまりプロバイダーがそのように動作するか、この規模でそのアプローチが十分な性能を発揮するかであれば、RFC よりスパイクを選びます。答える問い、それぞれの答えによって何が変わるか、いつ終了するかを記述します。終了条件のないスパイクは、実装になってしまいます。

デザインが必要なのは、3 つ目の引き継ぎ先であり、そうしなければ見落とされるものです。API の裏側では、ディスカバリーで決定し、そのままプランニングに進めます。一方、画面ではその間に誰かがデザインを描く必要があります。プランはデザインが済んでいる前提で、そのデザインをリンクして参照するだけで、新たに作り出すことはありません。そのため、デザインが済むまで画面のプランニングができない場合は、その旨と、デザインで解決すべき内容を明記します。対象となる画面と、対応するジャーニーの状態です。作成した図はこの文書に置きます。Sources にリンクまたはパスを記載し、スライスの状態テーブルから参照します。別添の概要資料や、この文書をもとにプランニングする人が開かない PDF には置きません。

その後、グリッドの各セルをスライスに反映します。決定済みのものは Decisions テーブルに、RFC、スパイク、デザインが必要なものはステータスと未解決の問いに記載します。Work インデックスでは、グリッド全体を 1 つのステータス列で示します。その列だけを見ても、作業内容と未解決の点を読者が把握できないなら、インデックスとして不十分です。

決定事項は、最後にまとめてではなく、決めた時点で記録します。後から書き起こすと決定を再導出することになり、再導出の過程で理由がいつの間にか正当化に変わってしまいます。

形式

.design/<name>.md の成果物を書くときは、references/document-format.md を読みます。判定が確認された後、または確定した決定を記録した後に読み、インタビュー中には読み込みません。このテンプレートのセクション見出しは固定文字列です。読者やツールは見出し名でセクションを検索します。

知識の連鎖

順序を厳守します。既存のコードと規約、プロジェクトのドキュメント、ライブラリのドキュメント、ウェブ検索、それでも不明なら不確実として明記します。API、制限、動作を捏造してはいけません。「これについてのドキュメントは見つけられませんでした」と伝えるほうが、もっともらしい作り話をするより適切です。ここでは、制約を捏造してもバグが発生するのではなく、利用可能だった選択肢が排除されてしまいます。

出力

成果物を作成します。ただし、Situation の結論として発見すべきことが何もない場合は、段落を作成します。フェーズについて説明してはいけません。質問の仕方はインタビューのルールに従います。ここでは、結論を断定的に述べ、余計な文言や曖昧な表現を削ります。

例

例 1：未決定の判断

ユーザー：「ダッシュボードにキャッシュを追加すべきですか？」 アクション：

1. 状況を確認します（リリース済みの製品、進行中の作業）。リポジトリから判断できないことだけを質問します。
2. 「キャッシュが必要」という話の背後にある問題を明らかにします。誰が困っているのか、現状どれだけのコストがかかっているのか、何も変えなかったらどうなるのかを確認します。
3. 判断を変える数値を特定し、その数値だけを調べます。
4. 重要なユーザージャーニーの状態を順に確認します。構築よりも低コストな方法を提示します。
5. 結論を出したら止まり、返答を待ちます。
6. 確認を得た後、リポジトリを読み、次に2つの設計案を示します。その後、作業をスライスに分け、それぞれに差分、フロー、スキーマ、契約、判断を記載します。references/document-format.mdに従って.design/<name>.mdを作成します。 結果：ヘッダーにStatusを含み、Situation、Problem、Success、Boundary、Shape、Key decisions、Workを記載した設計ドキュメントになります。Workには、ステータス付きのスライス一覧と、各スライスの状態テーブルを含む個別セクションが含まれます。または、Boundaryの後で終了するdeclinedドキュメントになります。

例 2：すでに決定済み

ユーザー：「課金機能を構築することはすでに決めています。設計を一緒に考えてください。」 アクション：

1. 決定済みの内容をSituationに記録します。結論を改めて問い直してはいけません。
2. 設計に影響するユーザージャーニーの状態と根拠を聞き取ります。
3. 提案の前にリポジトリを確認します。コストを見積もった2つの設計案を提示します。クリティカルパスのフロー、状態機械、スキーマに基づいて設計し、.design/<name>.mdを作成します。 結果：結論の行は「すでに決定済み — Situationを参照」です。Shape、Key decisions、すべてのスライスに内容が記載されます。会話の内容がなくても、誰もがこのドキュメントを基に計画を立てられます。

例 3：対象外のスキル

ユーザー：「この設計ドキュメントをタスクに分割してください。」 アクション：このスキルは実行しません。計画はドキュメントを基に始めます。このスキルが作成するのはドキュメントです。 結果：引き継ぎます。このスキルでは.design/ファイルを作成しません。

よくある失敗

2ターン目で結論を出す

原因：結論を出す前に解決策を提案し、ユーザーが「いいですね」と答えたことを決定と見なしてしまいました。 対策：止まります。問題の本質を明らかにします。すでに決定済みであれば、その内容を記録して判断ゲートを省略します。2つ目の判断を作り出してはいけません。

新機能の必要性が明らかにならない

原因：欠如や構築上の問題に対して、「何もしなかったら何が壊れますか」といった痛みを尋ねる質問をしてしまいました。 対策：問題の種類に合わせて質問を切り替えます。欠如の場合は、代わりに何をしているかを尋ねます。構築の場合は、何が滞っているのか、なぜ次の要素ができた後ではなく今なのかを尋ねます。数値がないからといって、問題が小さいとは限りません。

説明文やテンプレートのプレースホルダーが成果物に残る

原因：山括弧のヒントを残したまま、Formatテンプレートをコピーしてしまいました。 対策：すべてのプレースホルダーを具体的な値に置き換えるか、セクションごと省略します。「N/A」と記載した見出しは含めません。

設計の体裁をした仕様書

原因：1つのDecisionsテーブルが、エラー文言、切り詰め、並べ替え順などを含む30行に膨れ、設計を実際に左右するトランザクションはその中の1セルに埋もれてしまいました。フローも状態機械もなく、スキーマは1行だけです。 対策：変更しにくい重要な判断は、Key decisionsに文章で記載します。スライス内に、そのスライスが担うクリティカルパスを図示します。スキーマは列形式のテーブルで記述します。導出可能な値は省きます。プランナーはリポジトリにすでにある規約から値を得られるため、その規約は一覧の下で一度だけ参照します。

スライスではなく画面ごとに整理する

原因：Flowsにすべてのフロー、Schemaにすべてのテーブル、Contractにすべてのエンドポイント、1つのDecisionsテーブルにすべての選択肢、最後にすべての未解決の質問をまとめていました。各セクションは整理されていても、作業の一部を理解したい読者は5つのセクションを行き来することになります。 対策：まずスライスに分割します。それぞれのスライスに、独自の状態テーブル、フロー、スキーマ、契約、未解決の質問を含めます。スライスの前に置くのは、方針、重要な判断、各スライスのステータスを1つずつ記載した一覧だけです。

10の決定事項が80回も書かれる

原因：取引について、状況、先行事例、構成の2か所、2つの主要な決定事項、スライスの「提供内容」、状態テーブル、図、その後の段落、横断的な項目、決定事項の行、スキーマの注記に記載されています。各セクションには「内容があるから」という理由で記載され、取引についてはあらゆる場所に内容がありました。 解決策：各決定事項は、それを管轄する最も上位のセクションに一度だけ記載します。主要な決定事項に記載し、スライスでは「主要な決定事項2」と述べ、図に示します。それ以外では触れません。その後、スライスごとの決定事項テーブル、横断的な項目、追加／変更リストを削除します。これらが重複の温床でした。

設計の中に書かれた計画

原因：各スライスに、変更するファイル、コンテナのトークン、メソッド名、テストスイートでのDELETE FROMの順序、画面上のユニオン型が列挙されています。 解決策：識別子の上限を設けます。ルート、テーブル、列、クラス、用語集の用語までです。それより細かい内容は計画に属します。設計では何が存在するかを示し、計画では何を行うかを示します。

誰も確認しなかった図

原因：エンティティ図ではすべての台帳エントリに請求書があることになっていますが、コードでは返金と調整のエントリには請求書がありません。 解決策：図をリポジトリと照らし合わせて確認してから取り込みます。図は文章よりも素早く信じられます。だからこそ、誤った図はより大きな損失を招きます。