Tại sao bạn nên viết Technical Spec trước khi Code (và cách viết)

Bạn nhận một ticket: “Thêm tính năng Chat vào App”. Bạn nhảy vào code luôn. 3 ngày sau: Bạn nhận ra mình quên mất việc lưu tin nhắn offline. 5 ngày sau: Backend bảo API không hỗ trợ WebSocket như bạn nghĩ. 2 tuần sau: Phải đập đi làm lại vì architecture không scale.

Tất cả có thể tránh được nếu bạn dành 1 ngày đầu tiên để viết Technical Spec (hoặc Design Doc, RFC).

Technical Spec là gì?

Nó là bản thiết kế trên giấy (hoặc Google Doc) của tính năng bạn sắp làm. Nó trả lời câu hỏi “Làm THẾ NÀO” (How) trước khi bạn thực sự làm nó.

Tại sao Dev ghét viết Spec?

• “Mất thời gian.”
• “Code là chân lý, cần gì document.”
• “Requirement thay đổi liên tục mà.”

Nhưng thực tế: Viết Spec rẻ hơn viết Code. Sửa một dòng trong document mất 1 phút. Sửa một kiến trúc sai trong code mất 1 tuần.

Cấu trúc một Technical Spec chuẩn (Template đơn giản)

Đừng viết dài dòng như văn tế. Hãy ngắn gọn, súc tích.

1. Overview (Tổng quan)

• Problem: Tại sao chúng ta làm cái này? (Vd: User cần support nhanh hơn qua chat).
• Goal: Mục tiêu là gì? (Vd: Chat realtime, latency < 200ms).

2. Proposed Solution (Giải pháp đề xuất)

• Architecture: Vẽ sơ đồ đơn giản (Client <-> WS Server <-> Redis <-> DB).
• Database Schema: Table messages có cột gì? Index ra sao?
• API Interface: POST /api/messages, WS /chat.
  • Tip: Viết JSON response mẫu ra đây.

3. Edge Cases (Quan trọng nhất)

Đây là nơi bạn tỏa sáng. Hãy liệt kê những trường hợp “khó”:

• Mất mạng thì sao? Có lưu local không?
• Gửi tin nhắn 10MB thì sao?
• Spam tin nhắn liên tục thì chặn thế nào?

4. Alternatives Considered (Các phương án đã loại trừ)

• “Tại sao dùng Redis Pub/Sub mà không dùng Kafka?”
• “Tại sao dùng WebSocket mà không dùng Long-polling?”
• Chứng minh bạn đã suy nghĩ thấu đáo.

Quy trình áp dụng

1. Viết Spec (Draft).
2. Gửi cho Team Lead hoặc đồng nghiệp review (Design Review).
3. Nhận feedback (“Ê, schema này không query được tin nhắn cũ đâu”).
4. Sửa Spec.
5. Code.

Lúc này, việc Code chỉ là “typing” (gõ lại) những gì đã thống nhất. Không còn bất ngờ, không còn block.

Hãy thử viết Spec cho task tiếp theo của bạn (dù nhỏ). Bạn sẽ thấy mình code nhanh hơn và tự tin hơn hẳn.