良い技術設計書の書き方！現場で役立つコツ
引用元：https://news.ycombinator.com/item?id=44779428
技術設計書は三層構造が良いよ。一層目は問題提起、ゴール、ノンゴール、要求事項。二層目は機能仕様で、外部から見たシステムの動きを記述。三層目は技術仕様で、内部構造を説明するんだ。各セクションは前のセクションから派生して、問題理解、要件の適切性、機能仕様の要件達成、技術仕様の実装を正当化すべきだよ。もし最初の層に問題があれば、それ以降を読む必要はないしね。よくあるのは技術仕様だけ書かれた設計書だけど、これだとレビューで適切なフィードバックができないんだ。そもそも解決すべき問題がチーム内で合意されてるかも怪しいよね。
この三層構造に付け足しね。一層目には利害関係者を明確にして、現状のAS-ISをスクリーンショット付きで記述すると、みんな何の話かすぐ分かるよ。二層目には検討した代替案と、それを選ばなかった理由もリストアップするといいね。三層目は開発者が選んだ技術設計についてメモを書く感じで、最も重要なのは選択理由だよ。どの層でも参照を追加して使おう。あと、『Less is more』って感じで、長文より一枚の絵の方がずっと伝わるからね。
うん、全部同意だよ。全ての設計書に全てのセクションが必要ってわけじゃないけど、読者が背景とか利害関係者を知ると助かるなら、それは設計の前に書くべきだね。
ちょっと補足だけど、各セクションには可能性の分岐があるんだ。ある問題に対しては色々な機能仕様で解決できるし、ある機能仕様に対しても色々な実装方法がある。これらの可能性の中から選択する行為が『設計』なんだよ。だから設計書には、どんな選択をしたか（時には選ばなかった選択も）と、その理由をちゃんと書き出すべきなんだ。
参照実装のセクションとか、形式的証明も良いかもね。例えば、セキュアなプロトコルについて議論する時には特に役立つんじゃないかな。
うん！Non-goalsってめちゃくちゃ大事だよ。ITの世界だと全部仮想的だから、理論上は何でも可能だと思われがちだけど、明確な制限を設けないと解決策の空間が無限になっちゃって、プロジェクトが『セカンドシステム効果』でダメになっちゃうことだってあるんだ（最初のシステムでもね！）。機械工学や電気工学だと、物理的に不可能な目標は明らかだから、Non-goalsとしてわざわざ mention しなくてもいいんだけどね。
記事からの引用で印象的なのが二つあるね。一つはXのスクリーンショットから『書くというプロセスが、あなたのアイデアを10倍良くする』ってとこ。もう一つは冒頭近くの『最も説得すべき人は、著者自身だ』ってとこ。設計書って本当に重要で、長年この業界にいるけど、Product Managerと名乗る人たちも含め、設計書のアイデアに反発するのを見ると未だに驚くよ。Leslie Lamportも言ってたけど、『書くことは、私たちの思考がいかに雑であるかを教えてくれる、自然な方法だ』ってね。技術的な文章の質を上げたい人は、『Write Like an Amazonian』を読んでみるといいよ：https://medium.com/@apappascs/write-like-an-amazonian-14-tip…
『形容詞をデータに置き換えろ』って考え方がIT業界全体に浸透しすぎたせいで、今もらう履歴書は数字で溢れかえってて、正直どう評価したらいいのか分からないんだよね。
もうこれ以上、『XをN%削減した』って言う『ベテランのプロフェッショナル』からの履歴書が来たら、採用活動を閉じて、IT業界を辞めて、世捨て人になるからね。追伸：このコメントを打ってる最中に、まさにそんな履歴書が来て、今モンゴルへ逃亡しようとしてるよ。
レジュメに数字を書くことへの批判がわからないな。俺は会社でEC2費用を1000万ドル削減した。これは誇れる実績だ。レジュメにはどう書けばいい？「EC2費用を大幅削減！」か？デタラメなレジュメが多いのはわかるが、それは面接で確認すればいい話。俺は自分の成果について全て話せるし、他の人もそうあるべきだ。できなきゃ誇張だとわかるだろ。
ジュニアレベルの採用経験しかないが、レジュメの実績はあまり気にしなかったな。俺が見てたのは「能力」だ。EC2の例は例外だが、大抵の実績は評価基準がない。「2400万ドル管理した」って言われても、もっと管理してる人もいるかもだし、本人が怠け者だった可能性もあるだろ？それより、どんな問題を解決できるか、どんなツールや技術に詳しいかを知りたい。数字だけじゃ役に立たない。
レジュメで嘘をつくなら、評価段階ではどうしようもない。多くのレジュメがデタラメなスキルを書いてる。候補者の実績や貢献が自分の会社にどう関連するか不明なら、それは質の低いレジュメだ。実績が重要なのは、再現性があるはずだから。「くだらない修正で何百ものエンジニアリング時間を削減した」ってのが本当なら、その人は時間短縮もでき、自分の仕事の意味も理解してるはずだ。
解決してきた問題については、解決できる問題よりもごまかしが効かない部分がある。
面接官として何百回も経験したけど、レジュメの記述は不完全なことが多い。「レイテンシを5％削減」なら中央値かロングテールか聞くし、「MLモデルで収益X%増」ならどんな層に影響があったか、回帰や対照群は？と聞くね。技術詳細にこだわるかより、本当に理解してるか確認したい。理解してないなら不採用。もし本当なら良いアイスブレイクになる。PS: 君を面接するなら「どうやったか」聞くよ。
それ全部レジュメに書くの？
いや、ヒントでいいんだ。「レイテンシをp99で」みたいに2語加えるだけで、仕様が明確になり信頼性が大幅に上がると思うよ。
その成功例は良いね。でも、経験2年未満のジュニア開発者のレジュメで、すべての項目がビジネス目標達成ばかりで、技術スキルがほとんど書かれてないのを最近よく見るよ。10年以上採用マネージャーをしてるけど、最近の傾向だね。
そのやり方はRedditの/csmajorsとか/cscareersとかで常に説かれてるフォーミュラだね。
技術系の面接官に感銘を与えたいなら、どれだけ儲けたかより、どんなスマートなアイデアを出してどう実装したかの方が興味を持たれるだろうね。
それで全然OKだよ。面接でその成果をどうやって出したか説明し、スキルを示すことが重要。そこで多くのデタラメはバレるんだ。数字が多すぎたり、正確すぎたりする履歴書は捨てたことないね。むしろ、漠然としてて事実に基づかない大げさな言葉ばかりで情報が少ない履歴書に注意してるよ。
ここでいくら文句言っても、俺も含めほとんどの読者が数字を流し読みしてる事実は変わらないよ。お前が言うように、ほとんどがデタラメだからな。だから気にしないなら今のままでもいいけど、気にするなら自分を際立たせる別の伝え方を考えてみたらどうかな。
俺は履歴書でそうするの好きだし、俺の知ってるほとんどの人もそうだね。調査結果見てみたいけど、一般的とは思えないな。とはいえ、俺は通常、コードを速くするといった、とても測定可能な領域に注目してるよ。
ここ数年で大量の履歴書を読んで、そのやり方にはもううんざりしてるんだ。実際、今は数字を控えめに使ってる履歴書以外は好意的に見てないよ。俺が読んだ中で最高の履歴書（そして最強の候補者）は、自分のスキルと経験にすごく自信を持ってて、少し個性（できる範囲でね）を見せてた履歴書だったな。
ジュニアデベロッパーには申し訳ないと思うよ。俺は今、自分のプロフェッショナルネットワーク経由じゃないと仕事考えないレベルだ。LinkedInとかの”ワンクリック応募”は、リモートワーカーにとって業界最悪の出来事だろうね。
俺の時代は、応募する会社に合わせて履歴書を調整して、関連する経験を強調してた。カバーレターも付けてたよ。毎日大量に応募しまくるとかじゃなかったな。
テクニカルポジションの採用マネージャーとして、これは問題ないし、”履歴書の専門家”もよく提案してる。俺が頭に来るのは、本人が担当した元の設計が問題で、それをあるべき状態に戻しただけなのに成果として語るパターンだね。これ、履歴書でも社内でもよく見るんだ。レベルが高いほど節約額は大きいけど、元々の無駄がひどかっただけってことが多いね。
俺はよく”XをN%削減”ってのを、ちょっとした嘘だと思って読んでるよ。N%がどれだけ正確に測定されたか、そしてそのN%全部が彼らの仕事によるもので、他の要因じゃないとどうやってわかるのか説明しないからね。だから、彼らは雑な仕事をしてて、優秀なエンジニアというよりは、お役所仕事に傾倒してるって印象を受けるんだ。
そういう数字を提示するのは、マネジメントをやる気にさせるために『Soft Skills Engineering』ポッドキャスト[0]でよく推奨されてるアドバイスだよ。数字の意味があるかどうかは疑わしいことが多いって意見には同意するね。
[0] https://softskills.audio/
履歴書にある数字入りの箇条書きの99%はでっち上げのでたらめだし、残りの1%も個人の功績とは言えないから、個人の履歴書に書くのは馬鹿げてるよ。
その気持ちはわかるけど、結論には同意しないな。数字は悪用されることもあるけど、具体性があるから、それを問い詰めてデタラメだと指摘できる。数字を書かない人を責めないけど、それが本当に必要だったのか判断しにくいんだ。
採用マネージャーとして、外部企業の特定の仕事のエンジニアリング価値を主観的に評価したくはないけど、候補者が貢献すべき最高レベルの目標を理解してるかは知りたい。指標は、たとえ欠陥があっても、そういう会話の良いきっかけになるんだ。
履歴書がゴミ箱行きにならないように言われてるから、みんなそうするんだ。悪いのは採用業界だよ。
もっとコメントを表示（1）
採用担当は採用マネージャーの要求次第だよ。嘘つき候補者がすり抜けたり、特定の方法が良いと分かると、みんな真似してひどくなる。Leetcodeが良い例だね。業界全体で悪い採用を助長してるんだ。高給取りが低給取りを馬鹿にするのはおかしいし、採用担当を教育しないとダメだよ。
「XをY%改善」みたいな数字は嘘くさいし、検証できないのにLinkedInとかで流行ってるよね。数字がなくても本質は伝わるし、俺は面接官として、ちゃんと貢献できる奴か見抜く質問をするから関係ないね。
CVは非技術系のHR/採用担当がスクリーニングするから問題なんだ。ワンクリック応募で大量に来るし、HRは形式重視で「XをY%」を見る。本来は応募を制限して、HRが電話とかでしっかりスクリーニングすべきだよ。
デザインレビュアーとして、良いドキュメントは、難解な解決策でも読者にシンプルに伝わるようにするべきだよ。「時間があればもっと短い手紙を書いただろう」って言葉が好き。デザインドキュメントは複雑な事を簡潔に示し、開発の苦労話は別の場所へ。分かりやすく進む道を示すのが大事だね。
「これでバイクシェッディングが起きるか？」「これってバイクシェッディングする価値あるか？」って自分に問いかけるんだ。初めて読む人にも難しいアイデアを簡単に理解させつつ、どうでもいいのにコメントされがちな問題は避けるのが目標だね。
「時間があればもっと短い手紙を書いただろう」って言葉、俺も好きだよ。
「時間Tは長さLに反比例する」ってことだね。「T ∝ 1/L」だよ。
むしろ「ΔLはlog(T)に比例する」って感じじゃない？数式だと「ΔL ∝ log(T)」だよ。
「設計は最適であるべき」ってのは、ちょっと違うと思うな。むしろ十分であることが大事。ソフトウェア設計は制約とトレードオフの対処だ。設計書ではそれらを明確にして、要件を満たすアプローチを示すべき。完璧は無理だし、問題は起きる。設計の目標はリスクを減らし、関係者に何をどう作るか伝える事さ。
「許容できるトレードオフ」とか「要件と制約を満たす」って、結局「制約下の最適化」と同じじゃない？これで「最適じゃないけど十分な解決策」って話になるのが理解できないな。
「最適」って辞書だと「最高」だけど、エンジニアリングでは「完璧じゃなくても複数の制約を満たすもの」って意味もあるんだよ。実際、「パレート最適」って概念が近い。トレードオフを明確にすれば、後で状況が変わった時に違う選択ができるから、設計書に書くのはめっちゃ大事だよ。
「最適」って、大体は「ある目的関数に基づく最適」って解釈してる。技術設計だと考慮点が多いから目的を明確にするのは難しいよね。例えばネットワークサービスなら、コードのシンプルさ、レイテンシー、運用コストとか色々。もしもっと良い設計があったとしても、提示した設計で問題解決できて制約も満たしてるなら、それは失敗じゃないって思うな。
「許容できるトレードオフを行うこと」の同義語は「最適化」じゃなくて、「妥協」って言葉だよ。
設計って固定じゃないから、後で改善できるようにしとくべきだね。どこまで詳細に書くかってのが大事で、「これは不明だけど知ってること（Known unknowns）」を明確にするのがポイント。High Level DesignsとLow Level Designsは別物で、移行時に十分なアプローチが最適化されるようにするんだよ。
ここで言う「最適」には、時間とか労力とかコストも含まれるんだよ。完璧な解決策ってわけじゃないけど、解決策の効果と投入する労力のバランスが取れてるって意味で「最適」なんだ。
明確なドキュメント作成のアドバイスは素晴らしいね。でも承認後にどう維持するかの話がないな。「設計の考古学」にならないように、Andrew Harmel-Lawが提唱する軽量なArchitecture Decision Records（ADRs）ってのが役立つかも。コードと一緒に置いておけば、意思決定の経緯が追えるし便利だぞ。詳細はこのリンク見てくれ: https://martinfowler.com/articles/scaling-architecture-conve…
うーん、Martinfowler.comのリンク、じっくり読む必要ありそうだね。「Advice Process」ってとこで、マネージャーって肩書きの人は読む気なくしそう。ADRsについて調べようとしたけど、Thoughtworksのリンクを辿ったらダウンロードボタンとか出てきて、ちゃんとした定義が見つけられないよ。ADRsの定義、教えてくれないかな？
外部リンクが多くて分かりにくいよね。Martinfowler.comの「The Four Supporting Elements」セクションにある「1. A Thinking and Recording Tool: Decision Records.」を見てみて。直接リンクはここね: https://martinfowler.com/articles/scaling-architecture-conve…
ADRsは「成果物と一緒にソースコードリポジトリに保存されることが多い、軽量なドキュメント」って定義されてるよ。「Elements of an ADR」表もあるから、見つからなかったらまた聞いてね。
Session Messengerは設計やアーキテクチャがコロコロ変わって、どこにも決定版の情報がない状態だね。そういえば、安全なメッセージングならSignalを使うべきだよ、絶対にね。
技術設計書（ADR）のレビューでセキュリティやプライバシー、コンプライアンスの承認を得るのに90日もかかるってホント？そんなに時間がかかるなら、どのPRも90日以内にマージされないんじゃないかな。これはプロセスが重すぎない？
プロセス肥大化はわかるよ。でも、ADRは思ってるより重くないはず。PostgresからAurora移行みたいなのは普通にコードレビューだし、大きな変更はADRがあってもなくてもセキュリティ／コンプライアンスレビューは必要だ。ADRは決定を文書化するだけで、決定自体を作るわけじゃない。むしろ文書化されてないと、インシデント時に大変だよ。実際に大規模導入した人の話を聞きたいな。
Amazonの会議で資料をその場で読むって慣習、変だよね。時間の無駄だし、事前に読めばミーティングはもっと短くなるはず。Googleの設計レビューでも、みんな事前に読まずに来てたな。たぶんドキュメント文化が弱かったからだと思う。事前に読む文化があれば、ミーティングはもっと議論に集中できて良いのに。
Amazonのやり方は、誰も事前に資料を読まない現実に対応してるんだ。会議が多すぎて準備できないからね。理論的には穴だらけに見えるけど、Amazonでは実際にこのやり方で意思決定できてるみたいだよ。結果を見れば、このアプローチのメリットがデメリットを上回ってるってことなんだろうね。
Amazonのやり方って変じゃない？エンジニアに何か期日までにやってほしいのに、座らせて見張ってないとやらないって諦めてるみたいだよね。そんなこと他にないんじゃないかな。
大企業だと、マネジメントからの指示やインセンティブがないと、ほとんどのことは無視されることが多いよ。メールの返信がなくても「ミーティング設定しろ」って言われるのが普通。だから、誰かに何かやってほしいなら、カレンダーに「ミーティング」として時間をブロックするんだ。そうすれば、その時間内でちゃんと対応してくれるからね。
いつも仕事は時間より多いから、優先順位をつけないとね。マネージャーからの指示は優先信号だし、ミーティングもそう。でも、資料を読むだけじゃ生産物にならないから、優先順位が低くなりがちだよ。
それならミーティングを2回にしたら？1回目は個人が好きな時間に資料を読む「読書時間」、そして2回目はみんなで集まって本番のミーティングだよ。
みんなコンテキストスイッチのコストは知ってるのに、なんで不必要に2回もスイッチ増やすんだよ？資料を読む時間を指示されるのが嫌なだけじゃない？
このルールって、コードを書く時間がある若手エンジニアのためじゃなくて、普段は口頭でしかやり取りしない忙しいリーダー層のためのものだよ。
エンジニアはドキュメントを読む時間が割り当てられてないんだよね。
もっとコメントを表示（2）
会社ってそんなもんでしょ？部屋をオフィスって呼んで、お世話係をマネージャーとかリードって呼んでるだけだし。
＞でもそれって変じゃない？エンジニアに締め切りまでに何かやらせるのに、会議室に集めて見張らないとやらないって諦めてるの。会議って本来、非同期でできるはずなのに、なぜかできてないコミュニケーションを強制的に進めるためのものだよね。
それには反対だな。そんな会議がある会社は会議文化が未熟だと思う。会議は情報伝達じゃなくて、低遅延の共同作業のためだよ。デザインドキュメントを読むのは各自のペースがあるから非同期の方が効率的だね。でもトレードオフを議論するのは、会議で直接話す方がメールより効率的だ。デザインドキュメントがXを提案してて、キミはYが良いと思ってるとき、メールだと全ての利点・欠点を書き出さないといけないけど、会議なら20%の理由で納得させられるかもね。
＞キミの言うことは組織的に非効率的だよ。そういう理由はデザインドキュメントに書いとくべきだね。最終決定だけでなく、正当性もね。キミが「未熟な会議文化」と呼ぶものを、僕は「成熟したドキュメンテーション文化」と呼ぶよ。会社によって違うけど、Amazonのやり方は変で子供っぽいと思うけど、「ステークホルダーがオフライン／非同期でデザインを承認してない場合のみ会議が必要」って意見は変わらないな。
決定とその議論はドキュメントに記録すべきだってのは同意だよ。全部が書かれるべきじゃないって言っただけさ。ライブで議論して、後でドキュメントに要約すればいいんだ。関連して、デザインドキュメントに全ての議論を永久に残す必要はないと思うな。Googleにいたとき、各行に20件ものコメントがびっしりついてるデザインドキュメントを読むのが嫌だったよ。僕はドキュメントの持ち主として、そういうコメントスレッドを解決に導いて、議論の簡潔な要約を付録に書いて、スレッドを解決してたね。
＞その通りだよ、全てのやり取りは要らないけど、関連する情報はどこかに書き留めておくべきだね。
＞会議は情報伝達じゃなくて、低遅延の共同作業のため。でもドキュメントなしだと、会議での共同作業って非効率になりがちだ。話が食い違ったり、議論が不明瞭になったり、一度に一人しか話せないからね。事前にドキュメントがあれば、会議の目的が明確になり議論を導けるし、みんな並行してコメントできるから効率的だよ。会議中にドキュメントを読むのは、主催しない会議の準備不要で、他の時間を管理できるから、忙しいマネージャーには大きなメリットだね。
僕は事前にドキュメントを読んで、議論トピックを決めてから会議に臨むべきだと主張してるよ。＞ドキュメントなしだと会議が非効率になるって言うけど、それ会議一般の問題じゃない？キミは何を主張してるの？
「会議中にドキュメントを読むのが時間の管理に役立つ」って？他人に時間を管理させるのが効率的ってこと？5分で読めるのに10分強制されるのはおかしいだろ。自分で好きな時間に読んで、余計な5分を無駄にしない方が効率的だよ。Amazonのやり方って、子供の時間を管理するみたいだね。
＞会議の問題は変わらないって言うけど、ドキュメント必須にすれば主催者が事前に考えるから、議題が明確になって議論を導けるよ。
＞他人に時間管理させるのが効率的って？一緒にドキュメント読むなら、僕らは参加するだけ。事前に読むのは自分でスケジュール調整が必要で、忙しいマネージャーには大変なんだ。「5分で読めるのに10分座らされるのがどう役立つ？」って？僕は実践で問題ないね。余った時間はフィードバック考えたりSlack見たりできるし。
問題を解決するのに人間性を変えようとするなら、それは間違ったやり方だね。
俺がいた会社もこのやり方をしてたけど、他の方法より好きだったな。ふつう会議では口頭かパワーポイントで情報共有するけど、例えばスタンドアップミーティングが各自の進捗報告になっちゃうのは最悪。みんなで書いた資料を会議の最初に数分かけて読む方がずっとマシだよ。あと、資料は5分くらいで読めるし、長いのはめったにないかな。事前読書が理想だけど、一人でも読んでないとダメになるから、メリットよりコストが大きいと思うんだ。
Amazonを真似て特定の会議でやってたけど、普通の会議ではみんな事前に資料を読まなかったんだ。事前読書を勧めると、みんな適当にしか読まないし、マネージャー任せになっちゃうのが問題だね。だから、会議冒頭に10分読書時間を取る方がずっとうまくいくよ。それに、普通の会議でもメインの発表者が背景説明に10分くらい使うんだから、それを冒頭に集約して情報量を増やせるって考え方もあるよね。
＞貴重な会議時間をみんなで資料を読むのに費やすのはもったいない。事前に読めば会議はもっと短くなるはず。
みんな事前に読まないから、資料に書いてあることをまた議論することになって結局時間の無駄なんだよ。
＞事前に読めば会議はもっと短くなるはず。
会議内で読もうが外で読もうが、費やす時間に差はないよ。むしろ会議内で読んだ方が集中できるから、時間の使い方は良くなるはず。それに、十分に事前に用意されてる資料なんて、ごくわずかだろうね。
＞会議内で読もうが外で読もうがかかる時間は同じ。
この点については、俺が返信してるコメントで直接触れてるから読んでみてよ。
事前に読めば会議が短くなるって話だけど、事前に読むのを「宿題」にするか、会議の冒頭に読むのを「会議内作業」とするかの違いだよね。同僚が会議外でどれだけ時間あるか分からないから、会議内作業として強制すれば、みんな資料を読む時間を確保できるし、記憶も新しいはず。準備度合いが不明より、少しくらい準備不足の人がいる方がマシってことだね。
いつ資料を読むのが問題なの？もし会議に時間がかかるなら、もっと時間取ればいいだけじゃない？唯一の欠点は会議の予約が難しくなることだけど、結局全体の時間は変わらないんだから。
これまでに挙げられた理由（読むのが遅い人への配慮など）に加えて、新しい情報は議論する前に一度頭の中で整理する時間があった方が、一部の人にとっては良いってこともあるんだよ。
これって本当の問題じゃないと思うな。エンジニアになるくらい賢い人なら15分で6ページくらい読めるでしょ（読めないならその資料が悪い）。それに、読んで新鮮なうちに議論する方が忘れにくいから、たぶんそっちの方が良いんじゃない？
みんなが同じ認識じゃなかったり、自分のケースが考慮されてないって心配してると、マジで時間無駄にしちゃうよね。
経験上、会議で決まらないことは、もう絶対に進まないんだよな。
技術文書の書き方を学んだら、要約力が爆上がりしたよ。授業では“赤ペンで削る”アプローチ（書いて、消して、書き直す）を強調してて、最小限の言葉で明確に伝えることを学んだ。これは練習でどんどん楽になるし、チームにも共有してるけど、継続的な訓練が大事だよね。
うまくいくプロセスはこれ！
1. 頭の中のものを全部ドキュメントに吐き出す（音声入力で早くするとか）
2. LLMに構造と流れを整理させる。読みやすくするために思考を整理してるだけだから、これは捨ててもいいかも。まだ思考を練ってる段階ね。
3. LLMの出力を出発点にするか、ゼロからアウトラインを書く。それを下書きにする。
4. 簡素化する：言葉を削ったり、難しい言葉を簡単な言葉にしたり。
5. ステップ4を繰り返す。
LLMは思考の垂れ流しと構造化のギャップを埋めてくれる。LLMからの出力は捨てる覚悟も必要だよ。最低30％は削れるし、意図を失わずにどれだけ削れるか驚くよ。
自分で書いたものを編集する過程って、書き出すのと同じくらい大事だよ。そうすることで、性急な結論や考えが足りなかった点、欠陥に気づくんだ。書くことって、実は思考を深めるツールとしてもっと評価されるべきだと思う。これはコードにも言えることで、テストコードを書くことでさえ、メインのコード改善のヒントになることが多い。LLMはそこまで教えてくれないだろうけどね。
展開して、要約して、圧縮して、また展開して、圧縮する。
そしたら誰かが具体的なこと聞いてきて、また展開する。
最終的には、自分のアイデアが満足したらLLMで圧縮するんだよな。
マジで、終わりのないジェットコースターみたいだわ。
良い設計書の書き方に関するヒントをよく見かけるけど、自分の思考を明確にするだけでなく、他者との効果的なコミュニケーションのためにも、それらが重要だってのは同意するよ。でも、こういう投稿には具体的な「良い設計書」の例が足りないことが多いんだよね。多くのドキュメントが社外秘なのは理解できるけど、学習者が参考にできる公開されてる優れた設計書の例ってないのかな？
「でも、こういう投稿には具体的な『良い設計書』の例が足りない」って前のコメントにあったけど、この投稿自体が筆者の設計書作成哲学を実践してるんだよ。最初のヘッダーが「Goal」で、早めに目標を設定することに触れてる時点ではっきりわかるよね。
「良い設計書」の理解は自分の中から育てるべき。たくさんの設計書や記事を読んで、どれが良くてどれが分かりにくかったか、何が原因だったか考えてみよう。常に「この文章は気に入った？」って自分に問いかければ、何が良いのか時間をかけて分かるようになるよ。これは客観的じゃないし好みも違うから、「良い例」のアーカイブは作りにくい。コードと同じで議論になっちゃうからね。でも、みんなが同意できる核となる特性は確かにある。
どこかのコメントでantirezが言ってたんだけど、彼はコードを一行も書く前にプロジェクトの設計書を書いてるらしいよ。彼のGitHubプロジェクトを見たり、「antirez design documents」とか「antirez specification」でググってみるといいよ。
https://github.com/antirez
