Rewrite Brief và Lock Brief khác nhau ở điểm nào trong quy trình Midi Coder?

Trong quy trình Midi Coder, câu hỏi “Rewrite Brief và Lock Brief khác nhau ở điểm nào?” không chỉ là khác nhau về tên gọi, mà là khác nhau về vai trò vận hành. Nếu làm đúng, đây là mạch chạy giúp đội ngũ đi từ repo đến merge với ít bất ngờ hơn, ít rework hơn và giữ được khả năng truy vết xuyên suốt.

Ở góc nhìn thực tế, Rewrite Brief là bước viết lại yêu cầu cho rõ ràng, có cấu trúc và bám sát ngữ cảnh kỹ thuật sau khi đã kết nối repo, cấu hình BYOK và index codebase. Còn Lock Brief là bước chốt bản brief đó thành một mốc tham chiếu ổn định để từ đây hệ thống mới generate contract và tiến tới lock contract. Nói ngắn gọn: Rewrite Brief là bước làm rõ, Lock Brief là bước đóng băng phạm vi đã được chấp nhận.

Chuỗi bước chuẩn trong Midi Coder

Một luồng vận hành điển hình thường diễn ra theo thứ tự sau:

• Kết nối repo, thường qua GitLab hoặc nền tảng tương đương.
• Thiết lập BYOK để hệ thống chạy trong phạm vi khóa và chính sách được phép.
• Index codebase để hiểu cấu trúc mã, file liên quan, dependency và bối cảnh thay đổi.
• Rewrite Brief để chuẩn hóa yêu cầu theo cách máy và người cùng đọc được.
• Lock Brief để chốt bản mô tả công việc đã thống nhất.
• Generate Contract từ brief đã khóa.
• Lock Contract để đóng băng cam kết triển khai trước khi sinh IR, mã giả và kế hoạch vá.

Chuỗi này phản ánh tư duy contract-first và contract coding: không nhảy thẳng vào sửa code, mà đi qua các lớp diễn giải và chốt điều kiện để giảm sai lệch giữa ý định ban đầu và thay đổi thực tế.

Rewrite Brief là gì?

Rewrite Brief là bước biến một yêu cầu ban đầu, vốn thường rời rạc hoặc mang ngôn ngữ nghiệp vụ, thành một brief có cấu trúc, rõ mục tiêu và đủ ngữ cảnh để kỹ thuật có thể hành động. Ở giai đoạn này, hệ thống tận dụng thông tin từ repo đã index để làm rõ:

• Phạm vi thay đổi là ở module, service, job hay interface nào.
• Hành vi hiện tại của hệ thống là gì.
• Hành vi mong muốn sau thay đổi là gì.
• Ràng buộc về API, dữ liệu, quyền truy cập, logging, test và compatibility.
• Điểm mơ hồ nào cần hỏi lại con người trước khi triển khai.

Rewrite Brief vì vậy mang tính khám phá và chuẩn hóa. Nó vẫn có thể được chỉnh sửa, bổ sung và viết lại nhiều lần cho đến khi cả người phụ trách nghiệp vụ lẫn người phụ trách kỹ thuật thấy rằng brief đã đủ rõ để chốt.

Lock Brief là gì?

Lock Brief là bước chuyển từ trạng thái “đang làm rõ” sang trạng thái “đã chấp nhận làm mốc”. Khi brief bị khóa, hệ thống và con người cùng thừa nhận rằng đây là phiên bản mô tả công việc dùng làm nền để tạo contract. Từ thời điểm này, mọi thay đổi lớn nên quay lại tạo một vòng brief mới hoặc version mới, thay vì lén sửa ngoài luồng.

Điểm quan trọng của Lock Brief là khả năng truy vết. Nếu không có bước khóa, đội ngũ rất dễ rơi vào tình huống:

• Người yêu cầu hiểu một đằng, người triển khai hiểu một nẻo.
• Contract sinh ra từ một brief đã bị thay đổi miệng ở nơi khác.
• Review không biết nên đối chiếu với yêu cầu nào.
• Merge xong mới phát hiện có phần “tưởng là đã thống nhất” nhưng không hề được ghi nhận.

Vì thế, Lock Brief không nhằm làm quy trình cứng nhắc, mà nhằm tạo ra một mốc ổn định để software factory vận hành nhất quán.

Khác nhau cốt lõi giữa Rewrite Brief và Lock Brief

• Mục tiêu: Rewrite Brief để làm rõ; Lock Brief để chốt.
• Tính linh hoạt: Rewrite Brief còn mở cho chỉnh sửa; Lock Brief là trạng thái đóng băng.
• Vai trò trong quy trình: Rewrite Brief là bước chuẩn hóa đầu vào; Lock Brief là điều kiện tiền đề để generate contract.
• Giá trị đối với traceability: Rewrite Brief giúp diễn đạt đúng; Lock Brief giúp đối chiếu được về sau.
• Ảnh hưởng đến triển khai: Rewrite Brief định hình hiểu biết; Lock Brief định hình cam kết triển khai.

Từ brief đã khóa đến contract, IR và kế hoạch vá

Sau khi Lock Brief, hệ thống có thể generate contract. Contract mô tả cụ thể hơn về phạm vi, đầu ra, ranh giới thay đổi, điều kiện chấp nhận và những phần không làm. Khi contract tiếp tục được rà soát và Lock Contract, pipeline mới có nền đủ chắc để sinh các lớp kỹ thuật như:

• IR hoặc biểu diễn trung gian để hệ thống lập luận nhất quán.
• Mã giả hoặc plan để mô tả cách sửa trước khi chạm vào file thực.
• Kế hoạch vá theo file, theo module, theo từng commit hoặc từng merge request.
• Áp dụng thay đổi có kiểm soát để giảm lan rộng ngoài phạm vi.

Sự khác biệt giữa Lock Brief và Lock Contract cũng cần nhìn rõ: brief là mô tả bài toán đã được hiểu đúng, còn contract là cam kết kỹ thuật được đặc tả đủ chi tiết để thực thi. Brief trả lời “chúng ta đang giải quyết chuyện gì”; contract trả lời “chúng ta sẽ sửa như thế nào, trong ranh giới nào”.

Điểm kiểm soát của con người và của hệ thống nằm ở đâu?

Một quy trình tốt không loại con người ra khỏi vòng lặp, mà đặt con người ở đúng điểm quyết định.

Con người nên kiểm soát

• Mục tiêu nghiệp vụ và ưu tiên thay đổi.
• Các giả định có thể gây ảnh hưởng đến user, dữ liệu hoặc compliance.
• Quyết định chốt Rewrite Brief thành Lock Brief.
• Quyết định chốt Contract thành Lock Contract.
• Review cuối cùng trước merge khi có rủi ro hệ thống hoặc sản phẩm.

Hệ thống nên kiểm soát

• Index repo, truy xuất ngữ cảnh và xác định file liên quan.
• Chuẩn hóa brief, generate contract và sinh kế hoạch kỹ thuật.
• Kiểm tra tính nhất quán giữa brief, contract và patch.
• Ghi nhận traceability theo từng version, từng thay đổi và từng mốc khóa.
• Hạn chế thao tác vượt khỏi phạm vi đã khóa.

Khi ranh giới này rõ ràng, Midi Coder phát huy tốt ở vai trò contract-first: con người chốt ý định, hệ thống thực thi trong khung đã chốt.

Làm sao giảm sửa ngoài luồng để giữ khả năng truy vết?

Sửa ngoài luồng thường xuất hiện khi đội ngũ nóng ruột, muốn “tiện tay sửa luôn” một số chỗ chưa nằm trong brief hoặc contract. Điều này làm traceability suy yếu rất nhanh. Để tránh tình trạng đó, nên áp dụng vài nguyên tắc đơn giản:

• Mọi thay đổi đáng kể đều phải gắn với một brief hoặc contract đã khóa.
• Nếu phát sinh yêu cầu mới, mở version mới thay vì nhét thêm vào version đang review.
• Giới hạn patch theo phạm vi file và mục tiêu đã chốt.
• Review theo đối chiếu: brief đã khóa, contract đã khóa và diff thực tế có ăn khớp không.
• Dùng GitLab merge request như điểm hiển thị cuối, nhưng coi nguồn sự thật vận hành nằm ở chain brief-contract-patch.

Khi làm vậy, mỗi commit và mỗi merge đều trả lời được câu hỏi: thay đổi này bắt nguồn từ yêu cầu nào, được chấp thuận ở mốc nào và có nằm trong cam kết đã khóa hay không.

Một version nên cắt nhỏ như thế nào để không quá tải?

Một lỗi phổ biến là gom quá nhiều ý vào cùng một version. Ví dụ, thay vì mở một version khổng lồ cho cả việc sửa API, tối ưu query, đổi log format và chỉnh quyền truy cập, nên tách theo đơn vị có thể review và rollback được.

Một cách cắt nhỏ hợp lý là:

• Version 1: chỉnh input validation ở endpoint A.
• Version 2: cập nhật mapping và xử lý lỗi của service liên quan.
• Version 3: bổ sung test và logging đúng theo contract.
• Version 4: tối ưu truy vấn nếu thật sự cần và có benchmark đi kèm.

Cách cắt này giúp mỗi Rewrite Brief ngắn hơn, mỗi Lock Brief rõ hơn và mỗi contract ít mơ hồ hơn. Khi đó review cũng dễ hơn vì người duyệt không phải xử lý một gói thay đổi vượt quá khả năng nắm bắt trong một lần đọc.

Khi nào cần quay lại Rewrite Brief?

Nếu trong lúc generate contract hoặc chuẩn bị lock contract mà xuất hiện một trong các tín hiệu sau, nên quay lại Rewrite Brief thay vì cố đi tiếp:

• Phạm vi phát sinh thêm module mới ngoài dự kiến.
• Có mâu thuẫn giữa yêu cầu nghiệp vụ và cấu trúc code hiện tại.
• Cần thay đổi schema, interface công khai hoặc hành vi có tác động rộng.
• Không còn chắc rằng patch có thể giữ đúng ranh giới ban đầu.

Quay lại sớm giúp tiết kiệm hơn nhiều so với việc lock contract sai rồi phải gỡ trong giai đoạn review hoặc sau merge.

Kết luận

Rewrite Brief và Lock Brief không phải hai bước trùng nhau. Rewrite Brief là bước diễn giải và làm rõ yêu cầu dựa trên repo, BYOK, index và ngữ cảnh kỹ thuật. Lock Brief là bước chốt bản hiểu đó thành mốc chuẩn để sinh contract và tiếp tục tới lock contract. Trong mô hình contract coding của Midi Coder, sự phân tách này là nền tảng để giữ traceability, giảm sửa ngoài luồng và giúp hành trình từ repo đến merge trên GitLab trở nên kiểm soát hơn.

Một quy trình tốt không làm đội ngũ chậm đi; nó làm cho mỗi thay đổi ít bất ngờ hơn. Và đó chính là khác biệt lớn nhất giữa việc chỉ viết code và việc vận hành một software factory có khả năng truy vết từ đầu đến cuối.