実際に船を運ぶ技術的な仕様を書く方法

もしあなたがこれを読んでいるなら、おそらくあなたは午前2時に半分完成した技術的なスペックを眺め、スタンドアップ前にそれを包み込もうと絶望的に試みているかもしれません。 しかし、ここで重要なことは、うまく行ったとき、技術仕様はあなたのテクノロジーリーダーからの宿題ではありません。それらは、アイデアから生産に機能を駆使するために必要な最も強力なツールの1つです。 私の背景はソフトウェアエンジニアリングですが、その多くは他の技術分野に移行します。 何故、テクノロジーのスペックを書くのか? ドキュメントを書くことは、あなたがコードを送信する可能性があるときにバスワークのように感じますが、良い技術的な仕様は、いくつかのプロセス要件を満たすこと以上にしますので、ここに私と一緒にいてください。 適切に使用すると、技術仕様はあなたを助ける: あなたがそれを構築するために数週間を費やす前にアイデアを検証する - 私は、私が認めることを気にしているよりも、スペック段階でより多くの悪いアイデアを殺しました。 あなたのスタッフのエンジニア、あなたの製品マネージャー、それを見たすべての主要なエンジニアを実際に重要な人々から購入してください。 あなたよりも賢い人たちと高レベルのプランでイテラル - 私は部屋で最も賢い人ではありません、そしてあなたが自分自身に正直であれば、あなたもそうではありません。 新しいエンジニアを導入すると、「今週で3度目にこのアーキテクチャを説明させてください」ではなく「この仕様を読んでください」になります。 エンジニアリング以外の利害関係者と知識を共有する - あなたの製品マネージャー、コンプライアンスチーム、または財務担当者は、あなたが何を構築しているのか、そしてなぜかを理解する必要があります。 — Did you actually solve what you set out to solve? The spec is your scorecard. Use as validation when work is complete スペック駆動開発とLLMs LLMsは、私が技術仕様について考える方法を変更しました。 LLMsは、厳格で空気の差の技術的な仕様で最もよく機能します。あなたが想像力に残すほど、より良いです。 正確に定義された仕様は、自動チケット作成または技術的な実装のためのLLMに供給することができます。 あなたはあなたの仕様からテストを生成することができます。 あなたはあなたの提案の一部について考えるためにLLMsを使用して、彼らに研究を行うことを求めるか、またはあなたの論理の欠陥を特定するのに役立ちます。 私は、今後数週間で、LLMsとのスペクション駆動開発に専念する別の記事を持っています. 注目してください - 私はこれを規模で実験し、結果は本当に印象的です。 But even if you never touch an LLM, the discipline of writing a rigorous spec pays dividends. It forces clarity. And clarity is how good software gets built. 良い技術提案の解剖学(第1部) 良い技術的な仕様は、よく構造化され、理解しやすい、および操作可能である。それは、経営者にとってスケイミング可能で、それを実装するエンジニアにとって十分な詳細でなければなりません。 Here's the first half of the anatomy. This is what you write before you get buy-in. 何を解決しようとしているのか。 問題の発言から始める 解決策ではなく、問題です. I’ve seen so many specs that jump straight into 何が壊れたかを決して説明しない。 "we should build a microservice with GraphQL" 私のスタートアップ、タンデムでは、簡単なテストがあります: 私の非技術的共同創設者であるジャックは、それを読んで問題を理解できますか? そうでない場合は、それを書き直してください。 効くテクニックは: : Not but Use concrete examples "users experience latency" "users wait an average of 8 seconds for their transaction history to load, and we're seeing 23% drop-off at this screen." ビジネスへの影響を示す: 「これは私たちに年間約2.3Mポンドの変換損失にかかる」は、「これは遅い」よりもはるかに説得力があります。 引用やデータを含む:ユーザーの調査、顧客の苦情、または監視データがある場合は、それを落としてください。 何を解決しようとしないのか。 Scope creep is real, and if you don't explicitly call out what's out of scope, you'll spend the next month arguing about edge cases that don't matter. これは犯罪的に過剰に使用され、信じられないほど価値のあるものです。 Imagine this: you get a proposal from the platform team to upgrade to their shiny new shared UI library. Seems straightforward, right? Just swap out some imports, update a few components. But then you discover the new library uses a completely different routing system underneath. Now you need to refactor every route in your application. Then you realise your product team's navigation patterns don't quite fit the new model, so you need custom wrappers. Oh, and every この共有ライブラリに依存する製品チームは? すべて同じ変更でブロックされています。 ちょうど6ヶ月間の移住努力に変わり、組織全体で機能の仕事を続けています。 他の 「シンプルユーティリティ更新」 An explicit セクションはこれを早めに捕まえたかもしれないが、ノーと言う許可を与える。 そしてそれは、組織の悪夢に風船を吹き飛ばす、見た目で無実な提案からあなたのタイムラインを守ります。 「What We're Not Solving」 なぜ「ノート」 なぜこの問題は解決すべきなのか。 すべての問題は解決する必要はありません。いくつかの問題で生きることができます。いくつかの問題は実際には問題ではなく、わずかな不便があるだけです。なぜこの1つは注意とエンジニアリングの時間を得るべきですか? Make the case clearly: ユーザーへの影響:どれだけの人に影響を与えるか?どれだけ悪影響を与えるか? ビジネスへの影響:収入、保留、変換、運用コスト? エンジニアリングへの影響:このテクノロジー債務は他のすべてのプロジェクトを遅らせているのか? コンプライアンスまたはリスクへの影響:これを修正しないと6か月以内に爆発するか? I am a big believer in showing your work here. 単に言わないでください We once based a proposal to change the text on a button on an experiment that proved a 23% uptick in conversion, which translated to +£12k ARR. That's a much easier sale than 「これが重要」です。 「このボタンコピーはもっと良いかもしれない」 Why now? タイミングは人々が思っている以上に重要です. 私は完璧な良い提案がタイミングが完璧でないため棚に置かれているのを見ました. そして私はタイミングが完璧だったため、中途半端な提案が緑色になったのを見ました. なぜ今がこの問題を解決するのに最適な時期なのか? 外部期限:規制変更、マーケティングキャンペーン、会議デモ : Do you have the right infrastructure in place? The right team capacity? Internal readiness 依存性:最初に配送する必要がある他のプロジェクトはありますか? : Sometimes, there's a narrow window when solving something is easier than it'll ever be again. Opportunity windows ここに具体的な例があります。我々は、銀行口座見積もりでローカルタイムゾーンを使用することを提案しました UTC の代わりにタイムタイムが重要でした―我々は、日光の節約がイギリスで終了した直後にそれをやりたかった。これは、UTC とローカルタイムが同じだった6ヶ月を与えてくれました。我々はまた、法的な理由から、歴史的な見積もりを元のタイムゾーンに保持する必要がありました。時計が変わった直後に始めることは、次の移行の前に最大限のウィンドウを持っていたことを意味し、複数の論理的なタイムゾーン変換を含む声明を生成する必要がある人の確率を大幅に減らしました。 私たちが11月ではなく3月にやっていたら、より多くの複雑さとエッジケースを導入したでしょう。 Requirements 100%非交渉可能なものとは何ですか? 排除できない絶対最低値は何ですか? Think of requirements as the must-haves. Not the nice-to-haves, not the maybe-we-should-also, but the core things that must be true for this to be worth doing at all. I structure requirements as testable statements: 「トランザクション履歴は p95 で 2 秒以内にロードする必要があります」 「Solution must work for users on iOS 14 and above」 "Data must be encrypted at rest and in transit" (データは休憩中とトランジット中に暗号化されなければならない) 「顧客に再認証を要求する必要はない」 これらは具体的で検証可能であることに留意してください. You can test whether you have met them. Vague requirements such as または 何の役に立たない?下に貼る。 「MUST BE FAST」 「Safe Should Be」 解決策の鳥の視点 彼らはすぐに実装の詳細に潜り込む - どのデータベース、どの API、どのサービスメッシュ。 私は製品マネージャー、オペレーションの人々、おそらく金融さえ話しています。あなたがKubernetesが何であるか知らない人にあなたのソリューションを説明できないなら、あなたはそれを十分に理解していません。 このセクションのいくつかのルール: まさか、いやいや、いや、いや、いや、というより、 say No tech talk. 「Redisキャッシュを搭載した新しいマイクロサービスを展開し、GraphQLを介してそれを露出する」 「頻繁にアクセスするデータをユーザーの近くに保存するので、毎回データベースにゆっくりと移動する代わりに、すぐにロードできます」 ユーザーの視点から見た変化とは何でしょうか?成功とは何でしょうか? Think user-centric. スタート with そして、それをどのように達成するかを、高いレベルで説明します。 Anchor on outcomes, work backwards. "users will see their transaction history load in under 1 second" Sometimes there are genuinely different approaches. Lay out two or three options with pros and cons. This shows you've thought it through and gives stakeholders a real choice. If possible, offer multiple potential solutions. この時点で、あなたは立ち止まって再評価すべきです. これが前進する前に私のチェックリストです: [ ]問題声明は明確で具体的です。 Business impact is quantified [ ] [ ] Non-goals are explicitly stated Requirements are testable [ ] High-level solution makes sense to a non-engineer [ ] I'm confident this is worth doing [ ] あなたがこれらのすべてのボックスをチェックできない場合は、まだ第2部に進めないでください. 真剣に. 私は実行する価値がなかったアイデアの詳細な実施計画を書くために数週間を無駄にしました。 Buy-inとコラボレーション あなたの次のステップは、重要な利害関係者からのフィードバックを得ることです。これは公式ではありません。これはあなたのスペックが改善するか、または分裂する場所です。 Some hard-won tips for a successful pitch: 私はリアルタイムのコメントとコラボレーションのためにNotionのファンですが、Googleドキュメントも機能しています。私はこれを一度にFigmaを使用する真の先駆者も見ました!重要なことは、人々がインラインコメントを残して変更を提案することができることです。 Use a platform that makes collaboration easy. ユーザーの旅の変更を提案している場合は、マッカップやワイヤーフレームを作成します。サービスを最適化している場合は、モニタリングからのスクリーンショットで現在のメトリクスを表示します。私は、ユーザーの旅やメトリクスのための Grafana または Datadog のスクリーンショットのために Figma (高信頼性) または Excalidraw (低信頼性) をお勧めします。 Illustrate your points. あなたのエゴをドアに置いてください あなたが今受け取るすべての批判は、後で持たない生産の問題です. 私はレビューでスペクションを分断し、それは吸い込んでいます. しかし、あなたは何が悪いか知っていますか? 生産に失敗するために3ヶ月間何かを構築するだけで、あなたは明らかな何かを見逃したからです. Getting feedback should be your main objective. 誰かがコメントを残すと、 親切に彼らに理由を説明し、代替案を提案してください. 曖昧なネガティブ性は誰にも役立たない. しかし、理屈の真の懸念? それは金です。 Guide your contributors. 「私はこのアプローチが好きではない」と、 Someone will ask 最高の答えは数字です。 より説得力が強いのは、 Be ready to defend your value proposition. "is this worth the engineering time?" 「データベースホスティングコストを27%削減し、年間150万ポンドの節約につながる」 「これは物事をより効率的にするだろう」。 A plan worth implementing (part 2) あなたはテクノロジーの仕様を単独の努力として扱いますか? 単独で書く、レビューのためにそれを共有し、いくつかのコメントを得、それを配信しますか? それは、最高の仕様が書かれる方法ではありません。 最高の技術仕様は強力なコラボレーションの結果です。あなたは確かに最初の草案を書きますが、それからあなたは賢い人々を招待してそれをより良くします。あなたは彼らのフィードバックを組み込んでいます。あなたはあなたが学ぶものに基づいて調整します。 この解剖学の2番目の部分はよりダイナミックで、会社の文化、チームの実践、プロジェクトの種類によって異なります。 ベストプラクティスと企業基準 あなたの実装プランは、企業の既存の慣行の延長でなければなりません。React と Next.js を使用している場合、あなたのスペックは React と Next.js を使用する必要があります。 例外は、既存の実践を変更することを明示的に提案している場合です. おそらく新しいフレームワークを導入するか、別のデータベースに移行する必要があります. That's okay — but make your case with evidence. 既存の慣行に変更を提案したとき、私は常に以下を含む。 コンセプトの証拠の外側:別の会社がこれを成功させたか? ケーススタディを表示します。 隣接するドメインからの以前の芸術:私たちは異なる文脈で類似したアプローチを使用しましたか? なぜ現在のアプローチがうまくいかないのかを明確に推論する: 「これがより良い」と言わないでください。 移住経路:すべてを壊さずにここからそこまでどうやって行くか。 スーパーベットでは、私たちが以前使用していた継続的に問題のあるアンチデザインを置き換えるために専用のUIライブラリを構築したチームを率いる。我々は、技術的に完璧な互換性のレイヤーを通じて100%のダウンインの置き換えを作りました。しかし、私はビジネスケースを家に持ち帰ることができなかったので、ほとんどのチームにそれを採用することを説得することはできなかった。 以前の芸術と考慮された代替案 すでに存在している類似のものはありますか? あなたは過去に類似の属性を持つ機能を実装しましたか? これらはすべて言及する価値があります。 Best case scenario: you discover you don't need to build anything new. You can reuse an existing solution. 見つけたソリューションに関連する知識ベースに貼り付けることで、メンテナンス担当者がその利害関係者を理解し、なぜ人々がこれを必要とするのかを理解するのに役立ちます。 If this happens, don't throw away your spec. Statsig を使用して実験を配信しましたが、公式の実装を使用する代わりに独自の SDK を書きました。私たちの実装は持続的な割り当てをサポートしていなかったため、粘着した実験を実行することはできませんでした。私はこの機能を追加する方法を推測し始めました - 私はそれをゼロから構築する必要があると考えました - そして、野生のヤギを追いかけました。 What other approaches did you evaluate? Why didn't they make the cut? これは、あなたがあなたの宿題を完了したことを示しています。それはまた、あなたがすでに検討し、拒否した代替案を提案する人々を妨げます。 Approach Pros Cons Why we rejected it Use existing service X Fast, proven Doesn't support feature Y Missing critical functionality Build custom solution Perfect fit High maintenance cost Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build 既存のサービス X 早速、証明 サポートしない機能 Y 重要機能の欠如 「Custom Solution」 完璧なフィット High maintenance cost 継続的な負担に値しない。 Third-party API 容易な統合 ロックイン販売、高コスト £250K annually vs £30K to build 技術アプローチ Now — finally — you can get into the details. This is where you explain the actual implementation, architecture decisions, and tech stack choices. Architecture diagrams, sequence diagrams, data flow diagrams. I recommend (今は ) 無料で、適切なコラボレーション機能を持っているため、欠点は、Figmaのようなライブ共有はありませんので、画像をエクスポートして埋め込む必要があります。 Use diagrams. ドラえもん diagrams.net Sequence Diagrams では Mermaid が好きなので、マークダウンで書き込み、ほとんどのツールで自動的にレンダリングできます。 sequenceDiagram User->>API: Request transaction history API->>Cache: Check cache Cache-->>API: Cache miss API->>Database: Query transactions Database-->>API: Return results API->>Cache: Store in cache API-->>User: Return results Don't just say 言う Explain the "why" behind technical decisions, not just the "what." 「Caching に Redis を使う」 "we'll use Redis for caching because our access patterns are heavily read-biased (95% reads vs 5% writes) and we need sub-millisecond latency. We considered Memcached but chose Redis because we need data structures like sorted sets for timeline features." これがどこで壊れるのか正直に言いなさい。 That's way more useful than pretending your solution scales infinitely. Call out performance characteristics and scalability limits. "This approach works up to about 100,000 requests per second. Beyond that, we'll need to shard." データの外観を表示します。API リクエストと応答の外観を表示します. I usually include JSON examples: Mention data models, API contracts, key interfaces. { "transaction_id": "tx_123", "amount": 1250, "currency": "GBP", "timestamp": "2025-01-15T14:30:00Z", "category": "groceries" } A benefit of embedding models in a transferrable format, like JSON is that this can then be copy/pasted into a test or mock service later on. Saves some time and cuts down on ambiguity. JSONのような転送可能なフォーマットでモデルを埋め込む利点は、後でテストまたはマックサービスにコピー/パスすることができることです。 If this requires spinning up new services, databases, or third-party integrations, call it out. These often have cost implications and procurement delays. Highlight any new infrastructure or services needed. Breaking down the work このソリューションを追跡可能なマイルストーンやタスクにどのように分解しますか? これはプロジェクト管理ですが、構造を提供するのがあなたの仕事です。 私はMVP → MLP → Full Product progressionの大ファンです。 Split into phases that deliver incremental value. MVP (Minimum Viable Product) は、アプローチを検証するために構築できる絶対的な最小限のもの、通常は内部のみまたはユーザーのわずかな割合に限定されます。 : The smallest version that's actually good enough for real users to use and enjoy. MLP (Minimum Lovable Product) 完全な製品:すべての鐘と鐘。 これは認めるのは難しいが、多くの場合、我々は最終的な結果としてMLPを維持することに成功した。 . "good enough" What must ship for this to work? What's optional? Use a prioritisation framework. I like MoSCoW (Must have, Should have, Could have, Won't have). Identify critical path items vs nice-to-haves. バックエンドとフロントエンドのチームは同時に動作できますか? それともバックエンドは最初に配送する必要がありますか? 依存性を明確にすることは計画に役立ちます。 Call out what can be parallelised vs must be sequential. 私は実際にはサイズが嫌いで、私はそれについても悪いです。私は、デベロッパーの時間、デベロッパーの日、デベロッパーの週を単位として測定することを好み、タイムラインを議論するとき。 Assign rough t-shirt sizes or story points if your team uses them. 単純な依存度グラフを使用するか、それらをリストする: Make dependencies between tasks explicit. 「タスクBはタスクAが完了することに依存し、タスクCはタスクBと並行して開始することができる」 Success metrics How will you measure if the implementation actually worked? What are the KPIs? This is where you define victory conditions. And you need to be specific. 成功メトリックではありません。 成功メトリックです。 「Make It Faster」 「p95 API 遅延を 500ms から 200ms 以下に減らす」 Examples: Define measurable outcomes. Latency reduction: "p95 latency drops from 800ms to 200ms" エラー率の減少:「5xxエラーは0.3%から0.1%以下に減少」 「チェックアウト完了率が73パーセントから80パーセントに増加する」 Cost savings: "database costs decrease by £40K annually" 私は、現在のパフォーマンスを示すダッシュボードのスクリーンショットを撮影し、それらをスペックに付加します。 Set baseline metrics before implementation. ダッシュボードを構築しますか?警告を設定しますか? A/B テストを実行しますか? 測定方法について明確にしてください。 Specify how you'll track these metrics. Product managers care about revenue and engagement. Engineers care about latency and throughput. Your spec should speak both languages. Include both business metrics and technical metrics. リスク評価、依存性および緩和 何が悪いのか?何を心配しているのか?他のチームから何を求めているのか? I've learned to be brutally honest in this section. Pretending risks don't exist doesn't make them go away. It just means you won't have a plan when they materialise. あなたは何かを最初に配信する別のチームが必要ですか? 料金制限やダウンタイムを持っている可能性のあるサードパーティーサービスに頼っていますか? それを呼び出してください。 List external dependencies. これがどこで壊れるのか? ある重要なサービスが故障したらどうなるのか? 新しいデータベースを導入する場合、それが故障するとどうなるのか? Call out single points of failure in your design. Are you using a technology for the first time? Is this an area of the codebase nobody really understands anymore? Are you making assumptions about user behavior that might be wrong? Identify areas with high uncertainty. リスクだけをリストするのではなく、どのように対処するかを示します。 For each major risk, propose a mitigation strategy or fallback plan. Risk: Third-party API がダウンタイムになる可能性があります。 : Implement circuit breaker with exponential backoff; cache responses for 5 minutes; have a degraded mode that works without the API Mitigation それは信頼を築き、助けを求める。 全てがわかっているふりをするよりはマシです。 Be honest about what you don't know yet. "I'm not sure how we'll handle the migration of 500GB of existing data — looking for input here" セキュリティレビューを待たずに、プライバシーの影響評価全体が必要であることを発見してください. ユーザーデータに触れている場合は、それを呼び出してください. SOC2 コンプライアンスが必要な場合は、それを言及してください. Mention compliance, security, or data privacy concerns early. Rollout strategy これが実際にどのように展開されるのか? 段階的な展開? 機能の旗? カナリアの展開? I never ship big changes to 100% of users on day one. Never. ユーザーが2人しかいない場合は、1人まで配信してください。 ユーザーが2人しかいない場合は、1人まで配信してください。 私の通常の進行率: 5% → 10% → 50% → 100%. 各段階で、メトリックを監視し、問題を確認します。 Plan for gradual rollout. Deploy the code to production but keep it behind a flag. This lets you control who sees the new feature independent of your deployment process. I've used LaunchDarkly, Statsig, and built homegrown solutions. They all work. Pick one and use it religiously. Use feature flags to decouple deploy from release. ロールバックを引き起こす条件とは? 具体的に言うと、 Define rollback criteria. エラー率が 0.5% を超えると、戻ります。 p95 遅延が 1 秒を超えると、戻ります。 If we get more than 10 customer complaints in an hour, roll back これらの基準が事前に定義されていることは、あなたが事件中に感情的な決定を下さないことを意味します。 新しいコードパスを通して実際のトラフィックを送信しますが、ユーザーに結果を表示しないでください。 出力を古いコードパスと比較してください(また「影のテスト」とも呼ばれます)。 Consider dark launching to test in production without user impact. 何百万ものデータベースレコードを移行することは危険です。新しい機能を送信することとは別にします。理想的には、まずデータを移行し、次に新しいスケジュールを使用するコードをデプロイし、古いスケジュールをクリアします(拡張移行契約パターン)。 Plan for data migrations separately from code deploys. 誰がこの船をいつ知る必要がありますか? 顧客サポートチーム? マーケティング? 外部パートナー? スペックにコムスプランを書きます。 Have a communication plan for internal stakeholders and customers. ロールバック戦略 What happens if you suddenly become unavailable when everything's on fire? Would your team know how to handle it? パイロットのためのプレフライトチェックリストのように考えてください. ストレスが高くなり、アドレナリンが吸収されるとき、あなたは物事を調べたくありません。 フラッグXを無効にする または: commit abc123 に戻り、展開します。 データベース スクリプト Y を実行して、スケジュールの変更を返す Clear Cache Z to Remove Stale Data (ストールデータを削除するためのClear Cache Z) Monitor metrics A, B, C to confirm rollback successful Post in #incidents channel with status This keeps stress to a minimum in incident scenarios. Testing approach Unit tests, integration tests, load testing, edge cases — how will you validate this actually works? 重要なパスは幅広いテストを必要とします。Nice-to-have機能はより軽いカバーを可能にします。何が必要か、どのレベルのテストについて明確にしてください。 Define test coverage expectations. If this will serve millions of requests, you need to test it at scale. I use tools like k6 or Locust to simulate load. Don't wait until production to discover your database falls over at 10,000 QPS. Plan load/performance testing for high-traffic features. 依存症を殺す. 遅延を注入する. ネットワークパーティションをシミュレートする. 何が壊れるかを見てください. Netflixのカオス・モンキーはカノニックな例ですが、複雑なものは必要ありません。 単に意図的に物事を破って何が起こるかを見てください。 Consider chaos engineering for critical systems. What happens when the database is slow? When the cache is empty? When a user sends malformed input? These are where bugs hide. Test edge cases and failure modes, not just happy paths. Automated tests are great, but they only catch what you thought to test for. A human clicking around can find the weird stuff. Plan for manual QA/exploratory testing where needed. Pen testing, OWASP Top 10 checks, dependency scanning. If you are touching authentication, payments, or personal data, you need security review. ペンテスト、OWASPトップ10チェック、依存性スキャン. あなたが認証、支払い、または個人データに触れている場合は、セキュリティレビューが必要です。 Include security testing for sensitive features. タイムラインとマイルストーン 現実的な見積もり、未知のバッファ、重要な配達日付。 あなたの初期の推定は間違っているだろう 彼らは常に間違っている 問題はどれほど間違っているかです。 規制要件または会議デモがある場合は、そこから始め、それが実行可能かどうかを調べるために後ろ向きに作業してください。 Work backwards from hard deadlines if they exist. あなたが知られているテクノロジーで知られている領域で働いている場合は、見知らぬ領域にいる場合や新しいテクノロジーを使用している場合は、 1.5 倍から 2 倍に倍増します。 Pad estimates for unknowns. 2週間ごとに、何かを示すことができるはずです。それは動きを維持し、問題を早期に表面化します。 Define clear milestones with demos or checkpoints. Holidays, conference season, compliance deadlines, marketing launches. If half your team is going to be out for a week, factor that in. Call out external constraints. Account for on-call rotations, other commitments, the fact that nobody is productive 8 hours a day. I usually assume 6 productive hours per engineer per day, and that's being generous. Be realistic about team capacity. Initial estimates are educated guesses. As you get into implementation, you learn things. Update your timeline accordingly. A spec should be a living document, not a contract written in stone. Update estimates as you learn more. Open questions What still needs to be figured out? What requires more investigation? このセクションは、あなたが答えを得るにつれて時間とともに縮小するべきですが、それは知的誠実さを示し、協力を招くことが重要です。 "We need to validate that approach X can handle our query volume" or "We should prototype the migration script on a test dataset first." List unknowns that need research or prototyping before committing. 「暗号化アプローチについてのセキュリティチームのレビューが必要」または「バックバックの行動がどのようなものであるべきかについての製品の入力が必要」 Call out decisions that need input from specific people or teams. "We're assuming users will click this button, but we should A/B test to confirm" or "We think this cache hit rate will be 80%, but we should measure real traffic patterns first." Highlight areas where you need to validate assumptions with data. 「遅延やパフォーマンスを最適化することはできるが、両方ともできない――この使用例にとって何がより重要かを決める必要がある」 Be explicit about trade-offs you haven't resolved yet. 誰かが答えを得る責任を負う必要があり、期限が必要です。 Assign owners to each open question with target resolution dates. 文化がどのように役割を果たすか 私は、仕様が官僚的なボックスチェックの練習として扱われた企業で働いたし、それらが真に思考ツールとして評価された企業で働いた。 This reduces cognitive load and makes sure everyone's on the same page. You shouldn't have to reinvent the structure every time. We had a template in Notion. For Tandem, we use Google Docs templates, and at Docler, we had Confluence. The tool doesn't matter as much as the consistency. Technical specifications should be based on a standard template. Having a standard template also means reviewing specs is easier. You know where to look for the problem statement, the requirements, the risks. You're not hunting through a free-form essay trying to figure out basic information. あなたのアイデアを広い観客と共有することを恐れないでください. 私はあなたのアイデアをそこに置くのは怖いことを知っていますが,透明性には巨大な利点があります. 他のチームは,彼らが同じような問題を解決していることを発見するかもしれません. 別の垂直から誰かがあなたが欠けている重要な文脈を持っているかもしれません. 情報が公開されているときにセレンディピティが起こります. Make all proposals publicly available. All specs were in a shared Notion space that anyone in engineering could read. The number of times someone from a completely different squad dropped a comment that changed the whole approach was remarkable. これは、他の人々が学ぶのを助け、協力を奨励し、組織全体で何が構築されているかを人々に意識させます。 sessions where people would present proposals in progress and get feedback from a cross-functional group. Some of the best ideas came from those sessions. Schedule regular review sessions of critical proposals. 「Architecture Review」 素晴らしい提案を公に褒めよ すべての参加者を認めよ、たとえ彼らが単一のコメントを残したとしても。これは協力の文化を奨励する。私は、人々が仕様についてコメントすることを恐れていたチームを見た。 Tell people they're doing great. 誰かが特に良いスペックを書くとき、私はそれを公共のチャンネルで呼び出します。 It takes five seconds and it makes people feel good about the work they're doing. 「Alexのこの仕様は、複雑な提案を構造化する方法の素晴らしい例です - 参考にしてください。 The spec is the work Here's my final thought, and it's probably the most important thing in this entire article: writing the spec IS doing the work. あまりにも多くのエンジニアは、スペックをオーバーヘッドとして扱います。 of coding begins. That's backwards. The spec is where you do the hardest thinking. It's where you discover what you don't know. It's where you find the fatal flaws before they become production incidents. 『リアルワーク』 私が書いた最高の仕様は、協力し、繰り返し、時には論争的でした。彼らは何十ものコメントでマークされています。彼らは複数の修正を経てきました。彼らは私に私が作っていることを知らなかった仮定を再考することを強要しました。 And every single one of them made the implementation smoother, faster, and more successful than it would have been otherwise. 次回、あなたがスペックを飛び越え、コードを始める誘惑を受けるので、抵抗してください。そのドキュメントを開いてください. 問題を開始してください. 詳細を調べてください. スマートな人々を招待して、あなたの論理に穴を掘り下げてください. イタレートしてください. あなたの将来の自分 - あなたの呼び出し回転 - あなたに感謝します。 My product proposal template is available on GitHub. It captures most of the ideas discussed here. If your organization does not have a technical proposal template yet, use this as a starting point. 私の製品提案テンプレートはGitHub上で利用できます。 product proposal template is available on GitHub