Khi vận hành theo hướng contract-first với Midi Coder, hai bước dễ bị xem như thủ tục nhưng thực ra quyết định chất lượng toàn bộ luồng làm việc là Generate Contracts và Lock Contract. Nếu generate quá mơ hồ, đội triển khai sẽ hiểu khác nhau. Nếu lock không chặt, thay đổi ngoài luồng sẽ len vào trong lúc code, khiến phạm vi trôi dần, khó review và khó truy vết.
Một mạch vận hành chuẩn thường đi theo thứ tự: kết nối repo, cấu hình BYOK, index codebase, rewrite brief, lock brief, generate contract, lock contract, rồi mới chuyển contract sang IR, mã giả, kế hoạch vá và áp dụng thay đổi. Nhìn bề ngoài đây là nhiều bước, nhưng thực tế hai điểm sống còn nhất là lúc hệ thống tạo ra bản cam kết thực thi và lúc con người xác nhận khóa phạm vi đó.
1. Generate Contracts là bước chuyển từ ý định sang cam kết có cấu trúc
Brief ban đầu thường chứa mục tiêu kinh doanh, kỳ vọng người dùng và một số ràng buộc kỹ thuật. Nhưng brief không phải lúc nào cũng đủ chặt để triển khai. Generate Contracts có nhiệm vụ biến brief thành một mô tả có cấu trúc hơn: phạm vi thay đổi, module liên quan, điều kiện chấp nhận, ràng buộc không được phá vỡ và giả định đang sử dụng.
Điểm quan trọng của bước này không phải là viết ra càng nhiều càng tốt, mà là viết đúng những gì cần thực thi. Một contract tốt giúp trả lời các câu hỏi sau:
- Phần nào của hệ thống sẽ bị tác động?
- Phần nào tuyệt đối không được thay đổi?
- Tiêu chí hoàn thành là gì?
- Đầu vào, đầu ra và rủi ro nằm ở đâu?
- Có phụ thuộc vào branch, commit, issue hay merge request nào không?
Với Midi Coder, giá trị của contract coding nằm ở việc mọi bước sau đó đều bám theo hợp đồng này. Nếu contract đủ rõ, IR và mã giả sẽ bám sát. Kế hoạch vá cũng sẽ nhỏ gọn hơn. Review về sau vì thế ít tranh cãi hơn.
2. Lock Contract là bước giữ phạm vi không trôi
Nếu Generate Contracts tạo ra điểm tựa, thì Lock Contract là cơ chế giữ cho điểm tựa đó không bị xê dịch. Đây là khác biệt rất lớn giữa một software factory có kỷ luật và một quy trình làm việc dựa vào ngẫu hứng.
Khi contract đã được lock, đội ngũ có một mốc kiểm soát rõ ràng: mọi thay đổi vượt ra ngoài contract phải quay lại bước cập nhật brief hoặc tạo contract mới. Cơ chế này giúp ngăn tình trạng “tiện tay sửa thêm”, “đang làm luôn phần kế bên” hoặc “thấy bug nhỏ nên vá luôn”. Dù các thay đổi ngoài luồng có vẻ vô hại, chúng thường làm mất traceability và khiến việc đối chiếu giữa yêu cầu, mã nguồn và kết quả review trở nên khó khăn.
Lock contract đặc biệt quan trọng trong môi trường GitLab, nơi mỗi thay đổi cần gắn được với branch, merge request và bối cảnh review cụ thể. Khi contract bị mở quá lâu hoặc bị chỉnh liên tục trong lúc triển khai, khả năng truy vết từ repo đến merge sẽ suy giảm đáng kể.
3. Quy trình chuẩn từ repo đến merge
- Kết nối repo: hệ thống cần nhìn đúng codebase và lịch sử thay đổi liên quan.
- BYOK: thiết lập khóa và môi trường vận hành để kiểm soát bảo mật, quyền truy cập và chi phí xử lý.
- Index: tạo ngữ cảnh làm việc từ cấu trúc repo, module, dependency và bề mặt ảnh hưởng.
- Rewrite brief: chuẩn hóa yêu cầu để loại bỏ phần mơ hồ, thiếu điều kiện hoặc trùng lặp.
- Lock brief: xác nhận brief đủ ổn định để đi tiếp sang contract.
- Generate contract: chuyển brief thành hợp đồng thực thi có cấu trúc.
- Lock contract: đóng phạm vi thực hiện để mọi bước sau bám theo cùng một chuẩn.
- Contract sang IR và mã giả: diễn dịch hợp đồng sang dạng trung gian và hướng cài đặt cụ thể hơn.
- Kế hoạch vá và áp dụng thay đổi: chia patch, tạo thay đổi nhỏ, kiểm tra tác động và chuẩn bị merge.
Trong chuỗi này, con người không cần can thiệp quá nhiều ở mọi điểm. Con người nên tập trung vào những điểm có tính quyết định: xác nhận brief, xác nhận contract và duyệt những ngoại lệ. Hệ thống nên gánh phần còn lại như index, phân tích tác động, tạo IR, mã giả và đề xuất patch.
4. Điểm kiểm soát của con người và điểm kiểm soát của hệ thống
Một lỗi phổ biến là để con người nhảy vào quá sớm ở phần vi mô, nhưng lại bỏ qua các điểm khóa ở mức phạm vi. Cách hợp lý hơn là phân vai như sau:
- Con người kiểm soát: mục tiêu nghiệp vụ, giới hạn phạm vi, tiêu chí hoàn thành, quyết định có lock hay không, quyết định khi nào cần mở contract mới.
- Hệ thống kiểm soát: truy xuất ngữ cảnh từ repo, liên kết với GitLab, phát hiện vùng ảnh hưởng, chuyển contract sang IR, sinh mã giả, gợi ý patch và kiểm tra nhất quán.
Phân vai như vậy giúp giảm thời gian tranh luận ở các chi tiết nhỏ nhưng vẫn giữ được trách nhiệm ở các điểm chốt. Midi Coder mạnh nhất khi con người ra quyết định ở đúng điểm khóa, còn hệ thống đảm nhận phần lặp lại và cần tính nhất quán cao.
5. Cách giảm sửa ngoài luồng để giữ traceability
Muốn giữ traceability, đội ngũ cần xem contract là vật tham chiếu chính thức chứ không phải tài liệu tham khảo. Một số nguyên tắc đơn giản nhưng hiệu quả gồm:
- Mỗi merge request chỉ bám một contract chính.
- Nếu phát sinh thay đổi vượt phạm vi, không chèn thẳng vào patch hiện tại.
- Tạo contract mới cho thay đổi mới, kể cả khi nó có vẻ nhỏ.
- Gắn rõ contract với branch, commit và merge request liên quan.
- Tránh “gom tiện” nhiều mục tiêu vào một version.
Khi làm đúng, đội review sẽ đọc được đường đi rõ ràng: brief nào sinh ra contract nào, contract nào tạo ra patch nào, patch nào đi vào merge nào. Đây là nền tảng của contract coding có kỷ luật.
6. Một version nên được cắt nhỏ ra sao
Một version tốt không nên ôm quá nhiều thay đổi cùng lúc. Ví dụ, thay vì tạo một version lớn cho cả việc sửa API, cập nhật UI, tối ưu logging và đổi cấu trúc test, nên cắt thành các contract nhỏ hơn:
- Contract 1: thêm trường mới vào API và cập nhật validation.
- Contract 2: cập nhật giao diện hiển thị trường mới.
- Contract 3: bổ sung test cho luồng dữ liệu mới.
- Contract 4: tối ưu logging nếu thực sự cần và có thể review độc lập.
Cách cắt nhỏ này làm giảm quá tải nhận thức, giúp review nhanh hơn và giảm nguy cơ một thay đổi phụ làm chậm toàn bộ merge. Trong GitLab, điều đó còn giúp lịch sử merge sạch hơn, dễ rollback hơn và dễ đối chiếu hơn.
7. Vì sao hai bước này là sống còn nhất
Nói ngắn gọn, Generate Contracts quyết định đội ngũ có đang hiểu đúng việc cần làm hay không, còn Lock Contract quyết định đội ngũ có giữ được sự nhất quán tới lúc merge hay không. Một bên tạo ra cấu trúc. Bên kia bảo vệ cấu trúc đó khỏi bị xói mòn trong quá trình triển khai.
Nếu thiếu một trong hai, quy trình sẽ trượt khỏi mô hình contract-first. Khi đó, software factory không còn vận hành theo chuẩn hóa và truy vết nữa, mà quay lại kiểu làm việc phụ thuộc vào trí nhớ, trao đổi miệng và những chỉnh sửa khó kiểm soát.
Một quy trình tốt không làm giảm tốc độ; nó giảm bất ngờ. Khi generate đủ rõ và lock đủ chặt, merge sẽ ít rework hơn, review đỡ tranh cãi hơn và nhóm có thể mở rộng quy mô mà không đánh đổi khả năng kiểm soát.
