Làm thế nào để viết các thông số kỹ thuật thực sự tàu

Nếu bạn đang đọc điều này, rất có thể bạn đã nhìn vào một thông số kỹ thuật bán hoàn thành vào lúc 2 giờ sáng, cố gắng tuyệt vọng để đóng gói nó lên trước khi đứng. Nhưng đây là điều: khi được thực hiện tốt, các thông số kỹ thuật không phải là bài tập về công nghệ của bạn.Họ là một trong những công cụ mạnh mẽ nhất mà bạn cần để thúc đẩy các tính năng từ ý tưởng đến sản xuất.Tôi sẽ cho bạn thấy cách tôi tiếp cận viết chúng, dựa trên kinh nghiệm của tôi tại Monzo và bài học mà tôi đã học được từ các kỹ sư tại AWS, Google và Meta. nền tảng của tôi là kỹ thuật phần mềm, nhưng rất nhiều điều này chuyển sang các ngành kỹ thuật khác. Tại sao lại viết Tech Specs? Viết tài liệu cảm thấy giống như buswork khi bạn có thể đang vận chuyển mã. nhưng giữ với tôi ở đây, bởi vì một thông số kỹ thuật tốt làm nhiều hơn là đáp ứng một số yêu cầu quy trình. Khi sử dụng tốt, các thông số kỹ thuật sẽ giúp bạn: Xác nhận ý tưởng trước khi bạn lãng phí hàng tuần xây dựng nó - Tôi đã giết nhiều ý tưởng tồi tệ hơn trong giai đoạn spec hơn tôi quan tâm để thừa nhận. Nhận mua từ những người thực sự quan trọng - kỹ sư nhân viên của bạn, quản lý sản phẩm của bạn, kỹ sư chính đó đã nhìn thấy tất cả mọi thứ. Lặp lại kế hoạch cấp cao với những người thông minh hơn bạn - tôi không phải là người thông minh nhất trong phòng, và nếu bạn trung thực với chính mình, bạn cũng không. Chia sẻ kiến thức với nhóm của bạn - Đăng ký các kỹ sư mới trở thành "đọc thông số kỹ thuật này" thay vì "cho tôi giải thích kiến trúc này lần thứ ba trong tuần này." Chia sẻ kiến thức với các bên liên quan bên ngoài kỹ thuật - Người quản lý sản phẩm, nhóm tuân thủ hoặc người tài chính của bạn cần hiểu những gì bạn đang xây dựng và tại sao. — Did you actually solve what you set out to solve? The spec is your scorecard. Use as validation when work is complete Phát triển Spec-Driven và LLMs LLMs đã thay đổi cách tôi nghĩ về các thông số kỹ thuật. Các LLM làm việc tốt nhất với các thông số kỹ thuật nghiêm ngặt, không khí. Bạn càng ít để lại cho trí tưởng tượng, tốt hơn. Một thông số kỹ thuật được xác định rõ ràng có thể được đưa vào một LLM để tạo vé tự động hoặc thậm chí thực hiện kỹ thuật. Bạn có thể tạo ra các bài kiểm tra từ các thông số kỹ thuật của bạn. Bạn có thể sử dụng LLM để suy nghĩ về các phần của đề xuất của bạn, yêu cầu họ thực hiện nghiên cứu, hoặc thậm chí giúp xác định những thiếu sót trong logic của bạn. Tôi có một bài viết khác sẽ đến trong vài tuần tới dành riêng cho sự phát triển dựa trên spec với LLMs. Hãy theo dõi nó - tôi đã thử nghiệm với điều này ở quy mô lớn và kết quả thực sự ấn tượng. Nhưng ngay cả khi bạn không bao giờ chạm vào một LLM, kỷ luật viết một spec nghiêm ngặt trả cổ tức. Anatomy of a Good Technical Proposal (Phần 1) Một thông số kỹ thuật tốt được cấu trúc tốt, dễ hiểu và có thể thực hiện được. Nó nên dễ dàng cho các giám đốc điều hành và đủ chi tiết cho kỹ sư thực hiện nó. Đó là một đường dây hẹp để đi bộ, nhưng tôi đã tìm thấy một mô hình hoạt động. Đây là nửa đầu của giải phẫu.Đây là những gì bạn viết trước khi bạn nhận được mua. Bạn đang cố gắng giải quyết điều gì? Bắt đầu với tuyên bố vấn đề.Không phải giải pháp - vấn đề.Tôi đã thấy rất nhiều thông số kỹ thuật nhảy thẳng vào Không bao giờ giải thích những gì đã bị hỏng. "Chúng ta nên xây dựng một dịch vụ vi mô với GraphQL" Tại startup của tôi, Tandem, tôi có một bài kiểm tra đơn giản: Jack, đồng sáng lập phi kỹ thuật của tôi có thể hiểu được vấn đề, chỉ bằng cách đọc nó không? Một số kỹ thuật làm việc: Sử dụng các ví dụ cụ thể: Không phải "người dùng trải nghiệm độ trễ" mà là "người dùng chờ trung bình 8 giây để lịch sử giao dịch của họ tải, và chúng tôi đang thấy 23% giảm trên màn hình này." Hiển thị tác động kinh doanh: "Điều này tốn chúng tôi khoảng £2.3M hàng năm trong chuyển đổi bị mất" là nhiều thuyết phục hơn so với "điều này là chậm." Bao gồm các trích dẫn hoặc dữ liệu: Nếu bạn có nghiên cứu người dùng, khiếu nại của khách hàng hoặc dữ liệu giám sát, hãy bỏ nó vào. Bạn không cố gắng giải quyết điều gì? Scope creep là thật, và nếu bạn không rõ ràng gọi ra những gì nằm ngoài phạm vi, bạn sẽ dành tháng tiếp theo tranh luận về các trường hợp cạnh không quan trọng. Hãy tưởng tượng điều này: bạn nhận được một đề xuất từ nhóm nền tảng để nâng cấp lên thư viện UI chia sẻ mới rực rỡ của họ. Có vẻ đơn giản, đúng không? Chỉ cần trao đổi một số nhập khẩu, cập nhật một vài thành phần. Nhưng sau đó bạn phát hiện ra thư viện mới sử dụng một hệ thống định tuyến hoàn toàn khác bên dưới. Bây giờ bạn cần phải tái tạo mọi tuyến đường trong ứng dụng của bạn. Sau đó bạn nhận ra các mô hình điều hướng của nhóm sản phẩm của bạn không hoàn toàn phù hợp với mô hình mới, vì vậy bạn cần bao bì tùy chỉnh. nhóm sản phẩm phụ thuộc vào thư viện được chia sẻ này? Tất cả chúng đều bị chặn trên cùng một thay đổi. just turned into a six-month migration effort that's holding up feature work across the entire organisation. khác "Cập nhật tiện ích đơn giản" một cách rõ ràng section could have caught this early. It gives you permission to say no. It keeps the culture of Và nó bảo vệ dòng thời gian của bạn khỏi những gợi ý dường như vô tội mà bong bóng thành cơn ác mộng tổ chức. "Những gì chúng tôi không giải quyết" Tại sao lại là “notism” Tại sao vấn đề này phải được giải quyết? Không phải tất cả các vấn đề cần phải được giải quyết. Một số có thể sống với các giải pháp. Một số không thực sự là vấn đề, chỉ là những bất tiện nhỏ. Tại sao điều này nên nhận được sự chú ý và thời gian kỹ thuật? Hãy làm cho trường hợp rõ ràng: Ảnh hưởng đến người dùng: Điều này ảnh hưởng đến bao nhiêu người? Ảnh hưởng đến kinh doanh: Doanh thu, giữ lại, chuyển đổi, chi phí hoạt động? Ảnh hưởng đến kỹ thuật: Liệu nợ công nghệ này có làm chậm mọi dự án khác? Ảnh hưởng đến tuân thủ hoặc rủi ro: Điều này sẽ bùng nổ trong sáu tháng nếu chúng ta không sửa chữa nó? Tôi là một tín đồ lớn trong việc hiển thị công việc của bạn ở đây. Đừng chỉ nói Chúng tôi đã từng dựa trên một đề xuất thay đổi văn bản trên một nút trên một thí nghiệm chứng minh sự gia tăng chuyển đổi 23%, dẫn đến +£12k ARR. “Điều này rất quan trọng.” "Bản sao chép nút này có thể tốt hơn." Tại sao bây giờ? Thời gian quan trọng hơn mọi người nghĩ.Tôi đã thấy các đề xuất hoàn toàn tốt bị bỏ qua bởi vì đó không phải là thời điểm thích hợp.Và tôi đã thấy các đề xuất trung bình trở nên màu xanh lá cây bởi vì thời gian hoàn hảo. Tại sao bây giờ là thời điểm tốt nhất để giải quyết vấn đề này? Thời hạn bên ngoài: Thay đổi quy định, chiến dịch tiếp thị, bản demo hội nghị Sẵn sàng nội bộ: Bạn có cơ sở hạ tầng phù hợp? khả năng đội ngũ phù hợp? Tùy thuộc: Có những dự án khác cần phải vận chuyển trước không? : Sometimes, there's a narrow window when solving something is easier than it'll ever be again. Opportunity windows Dưới đây là một ví dụ cụ thể. Chúng tôi đã đề xuất sử dụng múi giờ địa phương trên báo cáo tài khoản ngân hàng thay vì UTC. Thời gian là quan trọng - chúng tôi muốn làm điều đó ngay sau khi tiết kiệm ánh sáng ban ngày kết thúc ở Anh. Điều đó cho chúng tôi sáu tháng khi UTC và giờ địa phương là như nhau. Chúng tôi cũng phải giữ các báo cáo lịch sử trong múi giờ ban đầu của họ vì lý do pháp lý. Bắt đầu ngay sau khi đồng hồ thay đổi có nghĩa là chúng tôi có cửa sổ tối đa trước khi chuyển đổi tiếp theo, điều này làm giảm đáng kể khả năng ai đó cần tạo ra một báo cáo với nhiều chuyển đổi múi giờ hợp lý. Nếu chúng tôi đã làm điều đó vào tháng 3 thay vì tháng 11, chúng tôi sẽ giới thiệu nhiều trường hợp phức tạp và cạnh tranh hơn. thời gian không chỉ quan trọng - đó là sự khác biệt giữa một cuộc di cư sạch sẽ và một cơn ác mộng. Requirements Những gì là 100% không thể thương lượng? những gì là tối thiểu tuyệt đối không thể loại trừ? Hãy nghĩ về các yêu cầu như là những điều cần thiết.Không phải là những điều tốt đẹp để có, không phải là những điều có thể chúng ta nên làm, mà là những điều cốt lõi phải đúng để điều này có giá trị thực hiện. I cấu trúc yêu cầu như các tuyên bố có thể kiểm tra: "Transaction history must load in under 2 seconds at p95" Giải pháp phải hoạt động cho người dùng trên iOS 14 trở lên "Dữ liệu phải được mã hóa trong thời gian nghỉ ngơi và trong quá cảnh" "Không yêu cầu bất kỳ khách hàng nào phải xác thực lại" Lưu ý rằng những yêu cầu này là cụ thể và có thể xác minh được. Bạn có thể kiểm tra xem bạn có đáp ứng được chúng hay không. hoặc Không cần thiết, hãy nhấn chúng xuống. "must be fast" “Phải an toàn” Cái nhìn của chim về giải pháp Họ ngay lập tức đi sâu vào các chi tiết triển khai - cơ sở dữ liệu nào, API nào, mạng lưới dịch vụ nào. Quan điểm của con chim nên dễ hiểu đối với các bên liên quan phi kỹ thuật.Tôi đang nói về các nhà quản lý sản phẩm, người vận hành, thậm chí cả tài chính.Nếu bạn không thể giải thích giải pháp của mình cho ai đó không biết Kubernetes là gì, bạn không hiểu nó đủ tốt. Một số quy tắc cho phần này: Thật sự, không phải bây giờ, thay vì say No tech talk. “Chúng tôi sẽ triển khai một microservice mới với bộ nhớ cache Redis và phơi bày nó thông qua GraphQL.” "Chúng tôi sẽ lưu trữ dữ liệu truy cập thường xuyên gần hơn với người dùng để nó tải ngay lập tức thay vì thực hiện một chuyến đi chậm đến cơ sở dữ liệu mỗi lần." Điều gì thay đổi từ quan điểm của người dùng? thành công trông như thế nào đối với họ? Think user-centric. Bắt đầu với và sau đó giải thích ở cấp độ cao làm thế nào bạn sẽ đạt được điều đó. Anchor on outcomes, work backwards. "Người dùng sẽ thấy lịch sử giao dịch của họ tải dưới 1 giây" Đôi khi có những cách tiếp cận thực sự khác nhau. Đặt ra hai hoặc ba lựa chọn với ưu và nhược điểm. Điều này cho thấy bạn đã suy nghĩ qua và cho các bên liên quan một sự lựa chọn thực sự. If possible, offer multiple potential solutions. Tại thời điểm này, bạn nên dừng lại và đánh giá lại.Đây là danh sách kiểm tra của tôi trước khi tiến lên: [ ]Tuyên bố vấn đề rõ ràng và cụ thể Business impact is quantified [ ] [ ]Không mục tiêu được nêu rõ ràng [ ]Yêu cầu có thể kiểm tra [ ] Giải pháp cấp cao có ý nghĩa đối với một người không phải là kỹ sư [ ]Tôi tin rằng điều này đáng để làm If you can't check all these boxes, don't proceed to part 2 yet. Seriously. I've wasted weeks writing detailed implementation plans for ideas that weren't actually worth doing. Nhận buy-in và hợp tác Bước tiếp theo của bạn là nhận phản hồi từ các bên liên quan chính. Đây không phải là một thủ tục. Đây là nơi thông số kỹ thuật của bạn trở nên tốt hơn hoặc rơi ra. Một số mẹo chiến thắng khó khăn cho một pitch thành công: Tôi là một fan hâm mộ của Notion vì bình luận thời gian thực và cộng tác, nhưng Google Docs cũng hoạt động. tôi thậm chí đã thấy một số người tiên phong thực sự sử dụng Figma cho lần này! Điều quan trọng là mọi người có thể để lại bình luận trong dòng và đề xuất thay đổi. Tránh PDF hoặc tài liệu Word đính kèm với email - bạn muốn đây là một tài liệu sống. Use a platform that makes collaboration easy. Nếu bạn đang đề xuất thay đổi cho hành trình người dùng, hãy tạo mockups hoặc wireframes.Nếu bạn đang tối ưu hóa một dịch vụ, hãy hiển thị số liệu hiện tại với ảnh chụp màn hình từ giám sát của bạn.Tôi khuyên bạn nên Figma (độ tin cậy cao) hoặc Excalidraw (độ tin cậy thấp) cho hành trình người dùng và ảnh chụp màn hình từ Grafana hoặc Datadog để đo lường. Illustrate your points. Để lại bản ngã của bạn ở cửa. Mọi lời chỉ trích bạn nhận được bây giờ là một vấn đề sản xuất bạn sẽ không có sau này. Tôi đã có các thông số kỹ thuật bị xé xé ra trong đánh giá, và nó hút. Nhưng bạn biết điều gì tồi tệ hơn? Xây dựng một cái gì đó trong ba tháng chỉ để có nó thất bại trong sản xuất bởi vì bạn đã bỏ lỡ một cái gì đó rõ ràng. Getting feedback should be your main objective. Nếu ai đó để lại một bình luận như kindly ask them to explain why and suggest an alternative. Vague negativity doesn't help anyone. But genuine concerns with reasoning? That's gold. Guide your contributors. “Tôi không thích cách tiếp cận này,” Ai đó sẽ hỏi Bạn cần một câu trả lời.Các câu trả lời tốt nhất có số. Rất nhiều thuyết phục hơn Be ready to defend your value proposition. "is this worth the engineering time?" Điều này có thể dẫn đến giảm 27% chi phí lưu trữ cơ sở dữ liệu, dẫn đến tiết kiệm hàng năm 1,5 triệu bảng Anh. “Điều này sẽ làm cho mọi thứ hiệu quả hơn.” A plan worth implementing (part 2) Bạn có xử lý các thông số kỹ thuật như một nỗ lực solo? Viết nó một mình, chia sẻ nó để xem xét, nhận được một số ý kiến, gửi nó? Đó không phải là cách các thông số kỹ thuật tốt nhất được viết. Các thông số kỹ thuật tốt nhất là kết quả của sự hợp tác mạnh mẽ. Bạn viết bản phác thảo đầu tiên, chắc chắn. Nhưng sau đó bạn mời những người thông minh để làm cho nó tốt hơn. Bạn kết hợp phản hồi của họ. Bạn điều chỉnh dựa trên những gì bạn học. Các thông số kỹ thuật phát triển. Phần thứ hai của giải phẫu là năng động hơn. nó thay đổi tùy thuộc vào văn hóa công ty của bạn, thực tiễn của nhóm của bạn, và loại dự án. Thực tiễn tốt nhất và tiêu chuẩn của công ty Your implementation plan should be an extension of your company's established practices. If you're using React and Next.js for web frontends, your spec should use React and Next.js. If your company has a standard CI/CD pipeline, use that. The exception is when you're explicitly proposing to change an established practice. Maybe you want to introduce a new framework or migrate to a different database. That's fine — but make your case with evidence. Khi tôi đề xuất thay đổi các thực tiễn đã được thiết lập, tôi luôn bao gồm: : Has another company done this successfully? Show case studies. Outside proof of concept : Have we used similar approaches in different contexts? Prior art from adjacent domains Lý luận rõ ràng về lý do tại sao cách tiếp cận hiện tại không hoạt động: Đừng chỉ nói "điều này tốt hơn." Con đường di cư: Làm thế nào chúng ta có thể đi từ đây đến đó mà không phá vỡ mọi thứ? Tại Superbet, tôi đã dẫn dắt một đội ngũ xây dựng một thư viện UI chuyên dụng để thay thế thiết kế Ant liên tục có vấn đề mà chúng tôi đã sử dụng trước đây. Chúng tôi đã làm cho nó một sự thay thế giảm giá 100% thông qua lớp tương thích - hoàn hảo về mặt kỹ thuật. Nhưng tôi vẫn không thuyết phục hầu hết các đội áp dụng nó, bởi vì tôi không thể lái xe trường hợp kinh doanh về nhà. Đó là bài học ở đây: thay thế công nghệ đã thành lập là khó khăn ngay cả khi giải pháp của bạn là khách quan tốt hơn. Bạn cần các con số, các nghiên cứu trường hợp, con đường di chuyển. Nghệ thuật trước và các lựa chọn thay thế được xem xét Is there something similar that already exists? Have you implemented features with similar attributes in the past? All of this is worth mentioning. Kịch bản trường hợp tốt nhất: bạn khám phá ra rằng bạn không cần phải xây dựng bất cứ điều gì mới. Kết nối nó với cơ sở kiến thức liên quan đến giải pháp bạn tìm thấy. Nó giúp các nhà duy trì hiểu những người liên quan của họ là ai và tại sao mọi người cần điều này.Nếu họ muốn đặt mặt trời, chuyển quyền sở hữu hoặc sửa đổi phần mềm của họ, họ sẽ biết ai để nói chuyện. If this happens, don't throw away your spec. Chúng tôi đã sử dụng Statsig để vận chuyển các thí nghiệm, nhưng chúng tôi đã viết SDK của riêng mình trên đó thay vì sử dụng chính thức. Việc triển khai của chúng tôi không hỗ trợ phân bổ vĩnh viễn, có nghĩa là chúng tôi không thể chạy các thí nghiệm dính. Tôi bắt đầu suy đoán làm thế nào để thêm tính năng này - nghĩ rằng tôi cần phải xây dựng nó từ đầu - và đi trên một chút săn bắn dê hoang dã. Sau đó, tôi tìm thấy một dịch vụ cụ thể về miền hiện có đã giải quyết sự kiên trì cho một trường hợp sử dụng khác. What other approaches did you evaluate? Why didn't they make the cut? This shows you've done your homework. It also prevents people from suggesting alternatives you've already considered and rejected. I usually include a short table: 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 Sử dụng dịch vụ hiện có X Nhanh chóng, chứng minh Doesn't support feature Y Thiếu chức năng quan trọng Xây dựng custom solution Perfect fit High maintenance cost Không xứng đáng với gánh nặng liên tục API bên thứ ba Integration dễ dàng Nhà cung cấp lock-in, chi phí cao £250K hàng năm vs £30K để xây dựng Cách tiếp cận kỹ thuật Bây giờ - cuối cùng - bạn có thể đi sâu vào các chi tiết.Đây là nơi bạn giải thích việc thực hiện thực tế, các quyết định kiến trúc và lựa chọn công nghệ. Kiến trúc sơ đồ, sơ đồ chuỗi, sơ đồ lưu lượng dữ liệu. tôi khuyên bạn nên (Bây giờ ) because it's free and has decent collaboration features. The disadvantage is there's no live sharing like Figma, so you'll need to export and embed images. Use diagrams. Draw.io diagrams.net Đối với sơ đồ chuỗi, tôi thích Mermaid bởi vì bạn có thể viết chúng trong đánh dấu và chúng hiển thị tự động trong hầu hết các công cụ. 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 Đừng chỉ nói nói Explain the "why" behind technical decisions, not just the "what." "we'll use Redis for caching." "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." Hãy thành thật về nơi điều này sẽ phá vỡ. Đó là cách hữu ích hơn là giả vờ quy mô giải pháp của bạn vô hạn. 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." Show what the data looks like. Show what the API requests and responses look like. 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. 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. 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 Làm thế nào bạn phân hủy giải pháp này thành các cột mốc và nhiệm vụ có thể được theo dõi? Đây là quản lý dự án, nhưng đó là công việc của bạn để cung cấp cấu trúc. Ship something usable early. I'm a big fan of the MVP → MLP → Full Product progression: Split into phases that deliver incremental value. MVP (Minimum Viable Product): Điều tuyệt đối nhỏ nhất bạn có thể xây dựng để xác nhận cách tiếp cận.Thường chỉ nội bộ hoặc giới hạn ở một tỷ lệ nhỏ người dùng. : The smallest version that's actually good enough for real users to use and enjoy. MLP (Minimum Lovable Product) : All the bells and whistles. Full Product Don't try to ship everything at once. This is tough to admit, but in many cases, we ended up keeping the MLP as the end-result, because it was . "good enough" Những gì phải vận chuyển để điều này hoạt động? Những gì là tùy chọn? Sử dụng khung ưu tiên. Tôi thích MoSCoW (Phải có, Nên có, Có thể có, Sẽ không có). Identify critical path items vs nice-to-haves. Các nhóm backend và frontend có thể làm việc cùng một lúc không? Hoặc backend cần phải vận chuyển trước? Làm cho sự phụ thuộc rõ ràng giúp với lập kế hoạch. Call out what can be parallelised vs must be sequential. Tôi thực sự ghét kích thước và tôi cũng không thích nó. Tôi thích các giờ phát triển, ngày phát triển, tuần phát triển như các đơn vị đo lường, khi thảo luận về thời gian. Nếu bạn không chắc chắn, hãy lên một phép đo, ví dụ: không chắc chắn nếu 3 hoặc 4 ngày phát triển? sử dụng 1 tuần phát triển. Assign rough t-shirt sizes or story points if your team uses them. Sử dụng biểu đồ phụ thuộc đơn giản hoặc chỉ liệt kê chúng: Make dependencies between tasks explicit. Task B phụ thuộc vào việc Task A hoàn thành.Task C có thể bắt đầu song song với Task B. Metrics thành công How will you measure if the implementation actually worked? What are the KPIs? Đây là nơi bạn xác định các điều kiện chiến thắng và bạn cần phải cụ thể. is not a success metric. Đó là một métic thành công. "Make it faster" "Giảm độ trễ API p95 từ 500ms xuống dưới 200ms" Examples: Define measurable outcomes. Latency reduction: "p95 latency drops from 800ms to 200ms" Tỷ lệ lỗi giảm: "Lỗi 5xx giảm từ 0,3% xuống dưới 0,1%" Cải thiện chuyển đổi: "tỷ lệ hoàn thành kiểm tra tăng từ 73% lên 80%" Tiết kiệm chi phí: "chi phí cơ sở dữ liệu giảm 40.000 bảng mỗi năm" Tôi chụp ảnh màn hình của bảng điều khiển hiển thị hiệu suất hiện tại và đính kèm chúng vào thông số kỹ thuật. Set baseline metrics before implementation. Will you build a dashboard? Set up alerts? Run an A/B test? Be explicit about measurement methodology. Specify how you'll track these metrics. Các nhà quản lý sản phẩm quan tâm đến doanh thu và sự tham gia. Các kỹ sư quan tâm đến độ trễ và thông lượng. spec của bạn nên nói cả hai ngôn ngữ. Include both business metrics and technical metrics. Đánh giá rủi ro, phụ thuộc và giảm thiểu Điều gì có thể xảy ra? điều gì khiến bạn lo lắng? điều gì bạn cần từ các đội khác? 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. Bạn có cần một nhóm khác để gửi thứ gì đó trước không? Bạn có dựa vào một dịch vụ của bên thứ ba có thể có giới hạn tỷ lệ hoặc thời gian ngừng hoạt động không? Gọi nó ra. List external dependencies. Điều này có thể xảy ra ở đâu? Điều gì xảy ra nếu một dịch vụ quan trọng đó thất bại? Nếu bạn đang giới thiệu một cơ sở dữ liệu mới, điều gì xảy ra nếu nó thất bại? 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. Đừng chỉ liệt kê các rủi ro - cho thấy cách bạn sẽ xử lý chúng. For each major risk, propose a mitigation strategy or fallback plan. Rủi ro: API của bên thứ ba có thể có thời gian ngừng hoạt động Giảm thiểu: Thực hiện phanh mạch với phản hồi tích cực; lưu trữ phản hồi trong 5 phút; có chế độ giảm thiểu hoạt động mà không cần API Điều này xây dựng niềm tin và mời gọi sự giúp đỡ. tốt hơn là giả vờ rằng bạn đã tìm ra tất cả. Be honest about what you don't know yet. "Tôi không chắc chắn làm thế nào chúng tôi sẽ xử lý việc di chuyển 500GB dữ liệu hiện có - tìm kiếm đầu vào ở đây" Đừng chờ đợi cho đến khi đánh giá bảo mật để tìm ra bạn cần một đánh giá tác động toàn bộ bảo mật.Nếu bạn đang chạm vào dữ liệu người dùng, hãy gọi nó ra.Nếu điều này cần tuân thủ SOC2, hãy đề cập đến nó. Mention compliance, security, or data privacy concerns early. Rollout strategy Làm thế nào điều này thực sự sẽ được triển khai? triển khai giai đoạn? lá cờ tính năng? triển khai Canary? Tôi không bao giờ gửi những thay đổi lớn cho 100% người dùng trong ngày đầu tiên. Nếu bạn chỉ có hai người dùng, hãy gửi đến chỉ một người. Nếu bạn chỉ có hai người dùng, hãy gửi đến chỉ một người. Tiến trình thông thường của tôi: 5% → 10% → 50% → 100%. Ở mỗi giai đoạn, bạn theo dõi các số liệu và theo dõi các vấn đề. Plan for gradual rollout. Phát triển mã để sản xuất nhưng giữ nó đằng sau một lá cờ. Điều này cho phép bạn kiểm soát ai nhìn thấy tính năng mới độc lập với quá trình triển khai của bạn. Tôi đã sử dụng LaunchDarkly, Statsig, và xây dựng các giải pháp tự chế. Tất cả chúng đều hoạt động. Chọn một và sử dụng nó một cách tôn giáo. Use feature flags to decouple deploy from release. Những điều kiện nào kích hoạt một rollback? Hãy cụ thể: Define rollback criteria. Nếu tỷ lệ lỗi vượt quá 0,5%, cuộn trở lại Nếu độ trễ p95 vượt quá 1 giây, cuộn lại If we get more than 10 customer complaints in an hour, roll back Having these criteria defined in advance means you won't be making emotional decisions during an incident. Gửi lưu lượng truy cập thực tế thông qua con đường mã mới nhưng không hiển thị cho người dùng kết quả. So sánh đầu ra với con đường mã cũ (còn được gọi là: kiểm tra bóng tối). Điều này làm sạch lỗi trước khi người dùng nhìn thấy chúng. Consider dark launching to test in production without user impact. Di chuyển hàng triệu bản ghi cơ sở dữ liệu là rủi ro. Làm điều đó tách biệt với việc gửi các tính năng mới. Lý tưởng nhất, di chuyển dữ liệu đầu tiên, sau đó triển khai mã sử dụng sơ đồ mới, sau đó làm sạch sơ đồ cũ (chế độ mở rộng-di chuyển-thỏa thuận mô hình). Plan for data migrations separately from code deploys. Ai cần biết khi nào tàu này? nhóm hỗ trợ khách hàng? tiếp thị? đối tác bên ngoài? Viết kế hoạch comms vào thông số kỹ thuật. Have a communication plan for internal stakeholders and customers. Chiến lược Rollback What happens if you suddenly become unavailable when everything's on fire? Would your team know how to handle it? Think of it like a preflight checklist for pilots. When stress is high and adrenaline is pumping, you don't want to be figuring things out. You want a list you can follow mechanically: Tắt tính năng Cờ X Or: roll back to commit abc123 and deploy Run database script Y to revert schema changes Clear cache Z to remove stale data Monitor metrics A, B, C để xác nhận rollback thành công Bài đăng trong #incidents channel with status This keeps stress to a minimum in incident scenarios. Testing approach Thử nghiệm đơn vị, thử nghiệm tích hợp, thử nghiệm tải, trường hợp cạnh - làm thế nào bạn sẽ xác nhận điều này thực sự hoạt động? Critical paths need extensive tests. Nice-to-have features can have lighter coverage. Be explicit about what needs what level of testing. 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. Kill dependencies. Inject latency. Simulate network partitions. See what breaks. Netflix's Chaos Monkey is the canonical example, but you don't need anything that sophisticated. Just deliberately break things and see what happens. 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. Kiểm tra tự động là tuyệt vời, nhưng họ chỉ bắt những gì bạn nghĩ để kiểm tra. một nhấp chuột của con người xung quanh có thể tìm thấy những thứ kỳ lạ. Plan for manual QA/exploratory testing where needed. Pen testing, OWASP Top 10 checks, dependency scanning. If you're touching authentication, payments, or personal data, you need security review. Include security testing for sensitive features. Timeline and milestones Ước tính thực tế, đệm cho những người chưa biết, ngày giao hàng quan trọng. Here's an uncomfortable truth: your initial estimates will be wrong. They're always wrong. The question is how wrong. Nếu có một yêu cầu quy định hoặc một bản demo hội nghị, hãy bắt đầu ở đó và làm việc ngược lại để tìm hiểu xem nó có khả thi hay không. Work backwards from hard deadlines if they exist. If you're working in familiar territory with known tech, multiply estimates by 1.2x. If you're in unfamiliar territory or using new technology, multiply by 1.5x to 2x. I know it feels excessive, but I've never regretted padding estimates and I've always regretted being too optimistic. Pad estimates for unknowns. Mỗi hai tuần, bạn nên có thể cho thấy một cái gì đó. nó giữ đà và bề mặt các vấn đề sớm. 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. Tôi thường cho rằng 6 giờ sản xuất cho mỗi kỹ sư mỗi ngày, và đó là hào phóng. Be realistic about team capacity. Các ước tính ban đầu là những phỏng đoán được giáo dục. Khi bạn đi vào thực hiện, bạn học được mọi thứ. Cập nhật thời gian của bạn phù hợp. Một thông số kỹ thuật nên là một tài liệu sống, không phải là một hợp đồng được viết bằng đá. Update estimates as you learn more. Câu hỏi mở Cần tìm hiểu thêm điều gì? cần tìm hiểu thêm điều gì? This section should shrink over time as you get answers, but it's crucial to have it. It shows intellectual honesty and invites collaboration. "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. "Need security team review on encryption approach" or "Need product input on what the fallback behavior should be." Call out decisions that need input from specific people or teams. "Chúng tôi cho rằng người dùng sẽ nhấp vào nút này, nhưng chúng tôi nên kiểm tra A / B để xác nhận" hoặc "Chúng tôi nghĩ tỷ lệ hit bộ nhớ cache này sẽ là 80%, nhưng chúng tôi nên đo lường mô hình lưu lượng truy cập thực sự trước". Highlight areas where you need to validate assumptions with data. "Chúng tôi có thể tối ưu hóa cho độ trễ hoặc thông lượng nhưng không phải cả hai - cần phải quyết định điều gì quan trọng hơn cho trường hợp sử dụng này." Be explicit about trade-offs you haven't resolved yet. Don't let open questions languish. Someone needs to be responsible for getting an answer, and there needs to be a deadline. Assign owners to each open question with target resolution dates. How culture plays a role Tôi đã làm việc tại các công ty nơi các thông số kỹ thuật được xử lý như các bài tập kiểm tra hộp quan liêu, và tôi đã làm việc tại các công ty nơi chúng được đánh giá cao như các công cụ suy nghĩ. Điều này làm giảm tải trọng nhận thức và đảm bảo mọi người đều ở cùng một trang. Bạn không nên phải tái tạo cấu trúc mỗi lần. Chúng tôi có một mẫu trong Notion. Đối với Tandem, chúng tôi sử dụng mẫu Google Docs, và tại Docler, chúng tôi có Confluence. Công cụ không quan trọng nhiều như sự nhất quán. Technical specifications should be based on a standard template. Có một mẫu tiêu chuẩn cũng có nghĩa là xem xét các thông số kỹ thuật là dễ dàng hơn. Bạn biết nơi để tìm kiếm các tuyên bố vấn đề, các yêu cầu, rủi ro. Bạn không săn lùng thông qua một bài luận miễn phí cố gắng tìm ra thông tin cơ bản. Don't be afraid to share yours with a broader audience. I know it's scary putting your ideas out there, but transparency has massive benefits. Other teams might discover they're solving similar problems. Someone from a different vertical might have crucial context you're missing. Serendipity happens when information is public. Make all proposals publicly available. Tất cả các thông số kỹ thuật đều nằm trong một không gian Notion được chia sẻ mà bất cứ ai trong lĩnh vực kỹ thuật đều có thể đọc được.Số lần ai đó từ một đội ngũ hoàn toàn khác bỏ ra một bình luận thay đổi toàn bộ cách tiếp cận là đáng chú ý. This serves multiple purposes: it helps others learn, it encourages collaboration, it makes people aware of what's being built across the organisation. We had monthly 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” Tôn vinh các đề xuất tuyệt vời công khai. Nhận thức tất cả những người tham gia, ngay cả khi họ chỉ để lại một bình luận duy nhất. Điều này khuyến khích một nền văn hóa hợp tác. Tôi đã thấy các nhóm nơi mọi người sợ bình luận về các thông số kỹ thuật vì họ nghĩ rằng họ sẽ được coi là những kẻ cản trở. Đó là chất độc. Bạn muốn mọi người cảm thấy rằng đầu vào của họ được đánh giá cao, ngay cả khi đó là phản hồi quan trọng. Tell people they're doing great. When someone writes a particularly good spec, I call it out in a public channel. It takes five seconds and it makes people feel good about the work they're doing. "Các thông số kỹ thuật này từ Alex là một ví dụ tuyệt vời về cách cấu trúc một đề xuất phức tạp - kiểm tra nó để tham khảo." Spec là công việc Here's my final thought, and it's probably the most important thing in this entire article: writing the spec IS doing the work. Quá nhiều kỹ sư đối xử với spec như là overhead trước khi Đó là sự trở lại.Spec là nơi bạn suy nghĩ khó khăn nhất.Đó là nơi bạn khám phá ra những gì bạn không biết.Đó là nơi bạn tìm thấy những khiếm khuyết chết người trước khi chúng trở thành sự cố sản xuất. “Công việc thực sự” The best specs I've written have been collaborative, iterative, and occasionally contentious. They've been marked up with dozens of comments. They've gone through multiple revisions. They've forced me to reconsider assumptions I didn't even know I was making. And every single one of them made the implementation smoother, faster, and more successful than it would have been otherwise. So the next time you're tempted to skip the spec and just start coding, resist. Open up that document. Start with the problem. Work through the details. Invite smart people to poke holes in your logic. Iterate. Bản thân tương lai của bạn - và sự quay theo cuộc gọi của bạn - sẽ cảm ơn bạn. Mẫu đề xuất sản phẩm của tôi có sẵn trên GitHub. Nó ghi lại hầu hết các ý tưởng được thảo luận ở đây.Nếu tổ chức của bạn chưa có mẫu đề xuất kỹ thuật, hãy sử dụng nó như một điểm khởi đầu. product proposal template is available on GitHub