Câu trả lời ngắn gọn là: code nên là output của contract vì code là lớp triển khai, còn contract mới là nơi mô tả rõ ràng ý định nghiệp vụ, cấu trúc dữ liệu, hành vi hệ thống và các ràng buộc cần được giữ ổn định theo thời gian. Khi đội kỹ thuật dùng code làm nơi giữ sự thật, mọi thay đổi thường diễn ra trực tiếp trên mã nguồn, khó truy vết, khó đồng bộ giữa tài liệu và triển khai, và càng khó đảm bảo rằng những gì đang chạy vẫn đúng với mục tiêu ban đầu.
Trong mô hình Contract Coding, contract đóng vai trò là source of truth. Từ contract, hệ thống có thể sinh ra code, tài liệu, cấu hình, kiểm thử hoặc các artefact liên quan. Điều này khác căn bản với cách làm quen thuộc là sửa thẳng mã nguồn, rồi sau đó mới cố giải thích ngược lại xem hệ thống đang làm gì.
Khác nhau giữa contract-first và sửa thẳng code
Với cách sửa thẳng code, thay đổi thường bắt đầu từ một file cụ thể: controller, service, schema, API handler hoặc prompt nào đó trong quy trình tạo mã. Cách này có thể nhanh ở ngắn hạn, nhưng về dài hạn dễ tạo ra ba vấn đề:
- Ý định nghiệp vụ bị phân tán: logic nằm rải rác ở nhiều nơi, không có một điểm trung tâm để đọc và hiểu.
- Khó truy vết: khi có lỗi hoặc lệch yêu cầu, rất khó biết thay đổi nào đã làm sai khác hệ thống.
- Khó lặp lại: muốn dựng lại cùng một kết quả cho môi trường khác, dự án khác hoặc phiên bản khác thường phải phụ thuộc vào kinh nghiệm của từng cá nhân.
Trong cách tiếp cận contract-first, thay đổi bắt đầu từ contract. Nghĩa là trước khi chạm vào code, đội ngũ xác định rõ:
- Đầu vào là gì
- Đầu ra là gì
- Ràng buộc nào phải được giữ
- Biến thể nào được phép xảy ra
- Tiêu chí chấp nhận là gì
Sau đó, code được sinh ra hoặc cập nhật từ contract theo quy trình có kiểm soát. Vì vậy, code không còn là nơi phát sinh chân lý mới, mà chỉ là bản triển khai nhất quán của chân lý đã được chốt trước đó.
Khi nào contract là nguồn chân lý tốt hơn code hoặc prompt
Code rất giỏi ở việc diễn đạt cách máy thực thi, nhưng không phải lúc nào cũng là nơi tốt nhất để con người đọc ra ý định hệ thống. Prompt cũng hữu ích trong nhiều workflow AI, nhưng prompt thường khó kiểm soát phiên bản, khó chuẩn hóa và dễ thay đổi ngữ nghĩa theo ngữ cảnh.
Contract trở thành nguồn chân lý tốt hơn khi hệ thống cần:
- Tính ổn định: cùng một contract phải cho ra cùng một cấu trúc kết quả theo thời gian.
- Khả năng lặp lại: có thể tái tạo output mà không phụ thuộc vào trí nhớ hoặc thao tác thủ công của từng người.
- Kiểm soát thay đổi: mọi sửa đổi đều diễn ra ở một điểm trung tâm, có thể review, diff và audit.
- Traceability: từ code có thể truy ngược về contract nào đã tạo ra nó, từ đó hiểu được nguyên nhân thay đổi.
- Đồng bộ nhiều artefact: không chỉ code, mà cả tài liệu, test, schema, mapping hoặc cấu hình cũng có thể xuất phát từ cùng một nguồn.
Nói cách khác, nếu đội kỹ thuật muốn hệ thống vận hành theo kiểu compiler-first thay vì edit-first, thì contract là lựa chọn hợp lý hơn code hay prompt đơn lẻ.
Vì sao không nên sửa thẳng code
Khi một dự án bắt đầu cho phép sửa thẳng code như cách chính để thay đổi hệ thống, mã nguồn sẽ dần trở thành nơi chứa cả ý định, ngoại lệ, vá lỗi tình huống và quyết định lịch sử. Từ đó xuất hiện một hiện tượng quen thuộc: ai cũng biết hệ thống đang chạy, nhưng không ai chắc hệ thống nên chạy như thế nào.
Đó là khác biệt rất quan trọng giữa:
- Code as truth: sự thật bị suy luận ngược từ hiện trạng triển khai.
- Contract as truth: sự thật được mô tả trước, rồi triển khai bám theo.
Nếu coi code là sự thật, đội ngũ thường phải đọc nhiều file để hiểu một thay đổi. Nếu coi contract là sự thật, đội ngũ có thể xem một nguồn mô tả rõ ràng, sau đó để hệ thống sinh ra phần triển khai tương ứng.
Ví dụ luồng làm việc từ ý định nghiệp vụ đến code đầu ra
Một luồng contract-first điển hình có thể diễn ra như sau:
- Xác định ý định nghiệp vụ: ví dụ cần tạo một quy trình xử lý đơn hàng với trạng thái, điều kiện chuyển bước và dữ liệu bắt buộc.
- Viết contract: mô tả cấu trúc đầu vào, đầu ra, quy tắc hợp lệ, ràng buộc và hành vi mong muốn.
- Review contract: kiểm tra contract đã phản ánh đúng yêu cầu nghiệp vụ, naming, cấu trúc và tiêu chí chấp nhận hay chưa.
- Biên dịch hoặc sinh code: hệ thống như Midi Coder dùng contract làm đầu vào để tạo code, artifact liên quan và các điểm tích hợp cần thiết.
- Kiểm thử theo contract: xác nhận code đầu ra vẫn tuân thủ đúng đặc tả.
- Khi cần thay đổi: chỉnh contract trước, rồi tái sinh output thay vì sửa tay trực tiếp trên mã nguồn.
Điểm quan trọng nhất của quy trình này là: mọi thay đổi đều có đường đi rõ ràng từ ý định đến triển khai. Đây chính là nền tảng của traceability.
Lợi ích về độ ổn định, khả năng lặp lại và kiểm soát thay đổi
1. Độ ổn định cao hơn
Khi output được sinh từ contract, đội kỹ thuật giảm đáng kể các khác biệt phát sinh từ thao tác thủ công. Cùng một contract sẽ dẫn tới cùng một logic sinh code theo quy tắc nhất quán hơn.
2. Dễ lặp lại
Nếu cần tái tạo module ở môi trường khác, phiên bản khác hoặc cho khách hàng khác, đội ngũ không phải nhớ lại đã từng chỉnh những file nào. Chỉ cần dùng lại contract và quy trình biên dịch tương ứng.
3. Kiểm soát thay đổi tốt hơn
Thay vì review hàng loạt chỉnh sửa rải rác trong code, đội ngũ có thể review thay đổi ngay từ contract. Điều này giúp tập trung vào bản chất thay đổi thay vì chìm trong chi tiết triển khai.
4. Tăng khả năng audit và traceability
Khi có sự cố, câu hỏi không chỉ là “ai sửa file nào” mà còn là “contract nào đã dẫn đến thay đổi này”. Đây là mức truy vết có giá trị cao hơn cho cả kỹ thuật lẫn vận hành.
5. Giảm phụ thuộc cá nhân
Khi tri thức hệ thống nằm trong contract thay vì chỉ nằm trong đầu một vài lập trình viên, việc bàn giao, mở rộng đội ngũ và vận hành lâu dài sẽ dễ hơn nhiều.
Điểm dễ hiểu sai khi mới nghe về Contract Coding
Một số người nghe khái niệm này thường hiểu sai theo vài hướng:
- “Contract là tài liệu đẹp hơn spec”: không chỉ là tài liệu. Contract phải đủ cấu trúc để máy có thể dùng làm đầu vào sinh output.
- “Vẫn có thể sửa tay code rồi đồng bộ lại sau”: nếu cho phép sửa thẳng code thường xuyên, code sẽ lại trở thành nguồn chân lý ngầm và phá vỡ mô hình contract-first.
- “Contract làm chậm tiến độ”: thực tế, contract có thể tốn thêm kỷ luật ở đầu quy trình nhưng bù lại giảm rất mạnh chi phí sửa sai, chi phí đồng bộ và chi phí bảo trì về sau.
- “Prompt cũng đủ rồi, không cần contract”: prompt mạnh ở khả năng gợi sinh linh hoạt, nhưng contract mạnh ở tính chuẩn hóa, khả năng kiểm soát và tái lập kết quả.
Vì vậy, bản chất của Contract Coding không phải là thêm một lớp tài liệu, mà là đổi vị trí của sự thật: từ mã nguồn sang contract, từ chỉnh tay sang biên dịch, từ cảm tính sang quy trình có thể kiểm soát.
Midi Coder phù hợp nhất để thử ở đâu trước
Nếu mới bắt đầu, Midi Coder phù hợp nhất ở những nơi mà đội ngũ đang gặp ít nhất một trong các vấn đề sau:
- Cùng một mẫu chức năng phải làm lặp lại nhiều lần
- Dự án có nhiều module giống nhau nhưng khó giữ đồng nhất
- Đội ngũ muốn tăng tốc mà vẫn giữ khả năng review và traceability
- Quy trình hiện tại đang phụ thuộc vào việc sửa tay code quá nhiều
- Cần một nền tảng software factory nơi contract là đầu vào và code là đầu ra
Những case thử đầu tiên thường phù hợp là CRUD có quy tắc rõ ràng, API contract ổn định, workflow nội bộ có nhiều bước lặp hoặc các module có cấu trúc tương đối chuẩn hóa. Đây là môi trường lý tưởng để thấy rõ giá trị của cách làm compiler-first và nguyên tắc không sửa thẳng code.
Kết luận
Code chỉ nên là output của contract vì code là lớp thực thi, không nên là nơi giữ sự thật về ý định hệ thống. Khi contract trở thành source of truth, đội kỹ thuật có thể kiểm soát thay đổi tốt hơn, truy vết rõ hơn, tái tạo output đáng tin cậy hơn và giảm rủi ro lệch giữa nghiệp vụ với triển khai. Với Midi Coder, đây không chỉ là một triết lý phát triển phần mềm mà là cách xây dựng một quy trình contract-first thực dụng, nơi code được sinh ra có kiểm soát thay vì bị chỉnh sửa thủ công như nguồn chân lý cuối cùng.
