Trong cách làm contract-first, câu hỏi tưởng nhỏ nhưng ảnh hưởng lớn đến chất lượng đầu ra là: nên sửa contract trực tiếp, hay chỉ comment để hệ thống sửa giúp? Nếu chọn sai, contract rất dễ biến thành một lớp giấy tờ đứng ngoài quá trình thi công. Nếu chọn đúng, contract trở thành điểm tựa để software factory vận hành ổn định, có traceability và giảm tranh cãi giữa người định nghĩa nghiệp vụ với người triển khai.
Với Midi Coder, contract không chỉ là mô tả ý tưởng. Nó là đầu vào có cấu trúc cho nhiều lớp xử lý: sinh schema, kiểm tra rule, ghép workflow contract, ràng buộc RBAC contract và xuất API contract. Vì vậy, quyết định sửa trực tiếp hay comment nên dựa trên loại thay đổi, mức độ chắc chắn của người sửa và rủi ro phá vỡ các lớp contract liên quan.
1. Hiểu đúng các lớp contract cốt lõi
Trước khi bàn về cách sửa, cần phân biệt rõ contract nào đang bị tác động. Một thay đổi nhỏ ở câu chữ có thể vô hại ở lớp mô tả, nhưng rất nguy hiểm nếu đụng đến cấu trúc đầu vào hay quyền truy cập.
- Domain contract: định nghĩa thực thể, thuộc tính, quan hệ, thuật ngữ nghiệp vụ.
- App contract: mô tả phạm vi ứng dụng, module, hành vi người dùng ở mức sản phẩm.
- Rule contract: quy tắc kiểm tra, điều kiện hợp lệ, công thức, trạng thái.
- Workflow contract: luồng chuyển bước, ai làm gì, điều kiện chuyển trạng thái.
- Policy contract: chính sách kiểm soát, ràng buộc vận hành, ngoại lệ.
- API contract: input, output, mã lỗi, định dạng trao đổi giữa hệ thống.
- RBAC contract: vai trò, quyền, phạm vi truy cập, điều kiện cấp quyền.
Một thay đổi càng gần phần cấu trúc thi công như schema, workflow, RBAC hay API thì càng cần kỷ luật cao hơn khi sửa. Đây là lý do không phải yêu cầu nào cũng nên xử lý bằng một câu comment tự nhiên.
2. Khi nào nên sửa contract trực tiếp
Sửa trực tiếp phù hợp khi người chỉnh sửa đã biết rõ đích cần ra, hiểu phạm vi tác động và có trách nhiệm khóa yêu cầu đủ chặt để hệ thống có thể thi công ngay.
Nên sửa trực tiếp khi:
- Thay đổi mang tính quyết định cấu trúc: thêm trường, đổi kiểu dữ liệu, đổi tên trạng thái, đổi rule, đổi quyền, đổi endpoint.
- Yêu cầu đã được chốt: không còn ở giai đoạn thảo luận, mà cần chuyển thành DSL contract rõ ràng.
- Cần giảm diễn giải: thay vì comment kiểu “chỗ này chắc nên có thêm điều kiện”, hãy viết hẳn điều kiện vào contract.
- Người sửa hiểu cú pháp và hệ quả: biết thay đổi này sẽ ảnh hưởng đến workflow contract, RBAC contract hay API contract nào.
- Cần tối ưu traceability ở mức bản ghi chính thức: thay đổi phải xuất hiện ngay trong nội dung contract để ai đọc cũng thấy trạng thái hiện hành.
Nói ngắn gọn: nếu bạn đang thay đổi sự thật nghiệp vụ hoặc cấu trúc triển khai, hãy sửa trực tiếp.
Lợi ích của sửa trực tiếp
- Giảm khoảng cách giữa ý định và đặc tả thi công.
- Hệ thống đọc được đầu vào rõ ràng hơn, ít phải suy đoán.
- Tạo một nguồn chân lý duy nhất cho team và cho máy.
- Giảm rủi ro comment đúng nhưng contract chính vẫn sai hoặc đã cũ.
3. Khi nào nên comment để hệ thống sửa
Comment không phải cách làm yếu hơn. Nó phù hợp khi mục tiêu là điều chỉnh có hướng dẫn chứ chưa phải chốt cấu trúc cuối cùng. Trong nhiều tình huống, comment giúp an toàn hơn sửa tay, nhất là với người nắm nghiệp vụ nhưng không quen DSL contract.
Nên comment khi:
- Bạn biết vấn đề nhưng chưa biết biểu diễn tối ưu trong DSL.
- Cần yêu cầu hệ thống tái cấu trúc: ví dụ tách rule, chuẩn hóa naming, gom field, sắp xếp lại module.
- Muốn giữ tính traceability của ý định sửa: comment thể hiện rõ lý do, bối cảnh và mục tiêu thay đổi.
- Thay đổi còn đang tranh luận: cần ghi chú phương án và để hệ thống đề xuất bản sửa an toàn hơn.
- Người góp ý không nên chạm trực tiếp vào phần nhạy cảm như API contract, RBAC contract hoặc workflow contract đã liên kết nhiều nơi.
Một comment tốt không viết mơ hồ kiểu “sửa lại cho hợp lý”. Nó nên nêu rõ: vấn đề ở đâu, muốn đầu ra thế nào, phần nào không được thay đổi và lý do nghiệp vụ đằng sau.
Ví dụ comment tốt
“Ở bước duyệt đơn, cần tách quyền xem và quyền phê duyệt. Vai trò kế toán chỉ được xem hóa đơn của đơn vị mình, không được đổi trạng thái. Giữ nguyên các trạng thái hiện tại, chỉ chỉnh RBAC contract và workflow contract liên quan.”
Comment như vậy đủ ngữ cảnh để hệ thống sửa đúng mà vẫn tránh đụng lan sang phần không cần thiết.
4. Cách chọn nhanh: trực tiếp hay comment
- Sửa trực tiếp nếu thay đổi là quyết định cuối cùng, có cấu trúc rõ và bạn biết chính xác phải viết gì.
- Comment nếu thay đổi là định hướng, cần diễn giải thêm, hoặc bạn muốn hệ thống tự đề xuất cách biểu diễn tốt hơn.
- Sửa trực tiếp cho các mục khóa như schema, rule, enum, state, endpoint, permission.
- Comment cho các yêu cầu tối ưu diễn đạt, tái cấu trúc, làm rõ ngoại lệ, chỉnh mức bao phủ.
Một nguyên tắc thực dụng là: cái gì cần máy thi công ngay thì sửa trực tiếp; cái gì cần máy hiểu ý rồi đề xuất lại thì comment.
5. Khóa phạm vi và ngôn ngữ để contract dùng được cho thi công
Nhiều contract thất bại không phải vì thiếu thông tin, mà vì dùng sai cấp độ ngôn ngữ. Contract tốt phải khóa phạm vi đủ chặt để hệ thống thi công được, nhưng không sa vào kể chuyện dài dòng.
Nên khóa phạm vi bằng:
- Đối tượng cụ thể: field nào, role nào, bước nào, endpoint nào.
- Ràng buộc rõ: bắt buộc, tùy chọn, duy nhất, không được null, chỉ đọc.
- Điều kiện áp dụng: áp dụng ở trạng thái nào, cho vai trò nào, trong ngữ cảnh nào.
- Biên không làm: phần nào giữ nguyên, phần nào chưa xử lý ở vòng này.
Nên khóa ngôn ngữ bằng:
- Dùng danh từ nghiệp vụ nhất quán với domain contract.
- Tránh từ mơ hồ như “hợp lý”, “linh hoạt”, “tối ưu”, “nhanh”.
- Tách mô tả nghiệp vụ khỏi quyết định kỹ thuật nếu chưa cần.
- Ưu tiên câu ngắn, một ý một dòng với phần có thể chuyển thành schema.
Đây là bản chất của DSL contract: ngôn ngữ có kiểm soát, đủ gần nghiệp vụ để người dùng hiểu, nhưng đủ chặt để software factory xử lý.
6. Phần nào nên viết ngắn, phần nào bắt buộc phải rõ và có cấu trúc
Có thể viết ngắn:
- Mục tiêu màn hình hoặc module.
- Mô tả bối cảnh kinh doanh đã quen thuộc.
- Ghi chú UX không ảnh hưởng logic lõi.
Bắt buộc phải rõ và có cấu trúc:
- Schema dữ liệu: tên trường, kiểu, ràng buộc, quan hệ.
- Rule: điều kiện, công thức, thông báo lỗi, thứ tự kiểm tra nếu quan trọng.
- Workflow: trạng thái, tác nhân, điều kiện chuyển bước, hậu quả sau chuyển.
- RBAC: vai trò, hành động được phép, phạm vi dữ liệu, ngoại lệ.
- API contract: request, response, mã lỗi, điều kiện gọi.
Nếu các phần trên chỉ được mô tả bằng văn xuôi, đầu ra rất dễ lệch. Máy không giỏi đoán ngầm như con người. Contract càng gần thi công, cấu trúc càng quan trọng hơn văn vẻ.
7. Lỗi thường gặp
- Ôm hết mọi thứ vào một contract: domain, rule, UI, vận hành, ngoại lệ đều dồn chung khiến không ai biết phần nào là chuẩn thi công.
- Bám sát code quá mức: contract biến thành bản sao implementation, mất vai trò định hướng thiết kế.
- Comment mơ hồ: nêu cảm giác nhưng không nêu thay đổi mong muốn.
- Sửa trực tiếp khi chưa hiểu tác động liên đới: đặc biệt nguy hiểm với workflow contract, RBAC contract và API contract.
- Thiếu traceability: sửa xong không rõ vì sao sửa, ai yêu cầu và thay đổi này giải quyết vấn đề nào.
Traceability không nhất thiết nằm hết trong một trường riêng. Nó đến từ cách bạn sửa có chủ đích: nội dung chính xác trong contract, comment rõ lý do và lịch sử thay đổi đủ đọc lại.
8. Ví dụ: một contract tốt và một contract tệ khác nhau ở đâu
Contract tệ
“Đơn hàng cần duyệt linh hoạt hơn. Người quản lý có thể xử lý tùy trường hợp. Nếu thiếu thông tin thì báo lỗi phù hợp.”
Vấn đề: không rõ “linh hoạt hơn” là gì, ai là “người quản lý”, xử lý được hành động nào, “tùy trường hợp” là điều kiện nào, “báo lỗi phù hợp” là lỗi gì.
Contract tốt
“Workflow contract của Đơn hàng có 4 trạng thái: draft, submitted, approved, rejected. Chỉ vai trò sales_manager được chuyển submitted sang approved hoặc rejected. Vai trò sales chỉ được tạo và gửi submitted cho các đơn do mình phụ trách. Nếu tổng tiền vượt 100 triệu thì bắt buộc trường approval_note không được rỗng trước khi approved. API contract trả lỗi 422 với mã ORDER_APPROVAL_NOTE_REQUIRED khi vi phạm.”
Điểm khác biệt là contract tốt khóa rõ trạng thái, vai trò, điều kiện, dữ liệu bắt buộc và hành vi API. Đây là loại nội dung nên sửa trực tiếp, không nên chỉ để ở mức comment.
9. Gợi ý quy trình làm việc thực dụng
- Xác định thay đổi thuộc lớp nào: domain, rule, workflow, policy, RBAC hay API.
- Nếu là thay đổi cấu trúc đã chốt, sửa trực tiếp vào contract tương ứng.
- Nếu là yêu cầu điều chỉnh nhưng chưa rõ cách biểu diễn, comment bằng ngôn ngữ có ràng buộc.
- Yêu cầu hệ thống phản hồi lại phần đã sửa để kiểm tra traceability.
- Chỉ chốt thi công khi contract chính đã phản ánh trạng thái mới, không dựa vào comment rời rạc.
Kết luận
Sửa contract trực tiếp hay comment để hệ thống sửa không phải lựa chọn cảm tính. Hãy nhìn vào mức độ chốt của yêu cầu, độ nhạy của lớp contract bị tác động và khả năng biểu diễn chính xác bằng DSL contract. Trong môi trường contract coding, mục tiêu không phải viết nhiều hơn, mà là viết đúng chỗ, đúng mức cấu trúc và đúng thời điểm. Một contract tốt là contract khiến code đầu ra ít bất ngờ hơn.
