Wavi Books · Kỹ nghệ phần mềm & Clean Code

Code quality là gì? AI viết code nhanh, technical debt cũng có thể tăng nhanh hơn

Nguyễn Minh Trí · Biên tập chuyên môn Wavi Books

Hiểu code quality, reliability, maintainability và cách đặt quality gate để AI coding agent không biến tốc độ viết code thành technical debt khó kiểm soát.

## Một pull request 2.000 dòng được tạo trong 15 phút — nhanh, nhưng ai sẽ hiểu nó sau ba tháng?

AI coding agent có thể dựng API, viết migration, thêm test và sửa tài liệu trong thời gian một developer mới chỉ đọc xong ticket. Nhìn vào pull request, mọi thứ có vẻ ổn: tên biến rõ, comment đầy đủ, test xanh. Vấn đề chỉ lộ ra khi feature thứ hai xuất hiện. Một rule nghiệp vụ bị chép sang ba service, retry tạo giao dịch trùng, exception bị nuốt để test đi qua và không ai biết đoạn abstraction đẹp mắt kia đang bảo vệ điều gì.

Tốc độ tạo code đã tăng, nhưng năng lực hiểu và chịu trách nhiệm của team không tự động tăng theo. Nếu quy trình kiểm soát chất lượng vẫn được thiết kế cho thời kỳ một người viết vài chục dòng mỗi ngày, AI không xóa technical debt. Nó giúp ta sản xuất technical debt với tốc độ và độ trơn tru cao hơn.

GitHub đưa Code Quality vào trạng thái phát hành chính thức ngày 20/07/2026. Thông điệp đáng chú ý không nằm ở một nút autofix mới. Nó nằm ở bài toán mà các team đang gặp: lượng code được AI hỗ trợ tăng nhanh, nên chất lượng phải được kiểm tra như một phần của luồng pull request — không phải đợi đến đợt ‘dọn nợ kỹ thuật’ cuối quý.

## Code quality là gì?

Code quality không phải việc code trông gọn hay tuân thủ một formatter. Một codebase có chất lượng phải làm đúng điều được thiết kế, xử lý ngoại lệ có thể dự đoán, và đủ dễ hiểu để người khác sửa mà không tạo thêm lỗi. Hai trục dễ dùng nhất là reliability và maintainability.

**Reliability — độ tin cậy** — hỏi liệu phần mềm có hoạt động đúng và ổn định trong cả luồng bình thường lẫn edge case hay không. Lỗi race condition, xử lý exception thiếu an toàn, sai logic, timeout không có chiến lược và hiệu năng sụt khi tải tăng đều thuộc nhóm này.

**Maintainability — khả năng bảo trì** — hỏi một người khác có thể hiểu, thay đổi và mở rộng code với mức rủi ro hợp lý hay không. Duplicate code, hàm quá phức tạp, naming mâu thuẫn, dead code, dependency rối và module không có ranh giới rõ đều làm chi phí thay đổi tăng dần.

Hai trục này liên quan nhưng không đồng nhất. Một đoạn code có thể chạy đúng hôm nay nhưng khó sửa đến mức feature sau gây lỗi. Ngược lại, code nhìn rất sạch vẫn có thể sai nghiệp vụ. Vì vậy, quality gate không thể chỉ gồm lint và coverage.

## Vì sao code do AI tạo dễ đánh lừa người review?

Code tệ do người mới viết thường có dấu hiệu dễ thấy: naming lộn xộn, style không nhất quán, thiếu test. Code do model mạnh tạo ra có thể ‘đúng hình thức’ hơn. Nó dùng pattern quen thuộc, chia file đẹp và viết lời giải thích tự tin. Chính sự trôi chảy này khiến reviewer dễ hạ cảnh giác.

AI không sống cùng lịch sử của hệ thống. Nó có thể đọc repository nhưng không mặc nhiên biết vì sao team từng bỏ một cache, vì sao một cột database tưởng thừa vẫn phải giữ, hay khách hàng nào phụ thuộc vào hành vi không được ghi trong tài liệu. Nếu ngữ cảnh thiếu, agent sẽ tối ưu cho phương án hợp lý chung — không phải sự thật riêng của sản phẩm.

Một rủi ro khác là độ lớn thay đổi. Khi chi phí tạo code gần như bằng không, agent dễ mở rộng phạm vi: refactor thêm module bên cạnh, đổi abstraction, nâng dependency và tạo helper dùng chung. Mỗi thay đổi có vẻ hợp lý riêng lẻ; tổng hợp lại thành một pull request mà con người không còn review nổi.

## Technical debt không phải mọi đoạn code xấu

Technical debt là chi phí tương lai phát sinh từ quyết định kỹ thuật hiện tại. Có khoản nợ được chấp nhận có chủ đích: ra mắt bản thử nghiệm với một implementation đơn giản, ghi rõ giới hạn và kế hoạch thay thế. Có khoản nợ vô tình: team không nhận ra giả định sai, không biết luồng phụ thuộc hoặc tin một bản sửa tự động mà không kiểm chứng.

Điểm nguy hiểm không phải luôn là số dòng code. Đó là phần kiến thức bị mất. Một workaround có comment về nguyên nhân, issue theo dõi và test khóa hành vi có thể an toàn hơn một abstraction ‘sạch’ nhưng không ai biết nó tồn tại để bảo vệ điều gì.

Khi dùng AI, hãy theo dõi debt ở ba lớp: code có khó hiểu không; kiến trúc có tăng coupling không; và vận hành có thêm trạng thái mà team không quan sát được không. Chỉ quét static analysis sẽ bỏ sót hai lớp sau.

## Quality gate nên chặn điều gì trước khi merge?

### 1. Chặn lỗi có mức ảnh hưởng cao, không chặn mọi sở thích

Bắt đầu với correctness, concurrency, unsafe error handling, dữ liệu nhạy cảm và regression. Nếu ngày đầu ruleset chặn hàng trăm cảnh báo style, developer sẽ học cách phớt lờ công cụ. Signal ít nhưng đáng tin tạo thói quen tốt hơn một dashboard đỏ kín.

### 2. Không để coverage trở thành con số trang trí

Coverage cho biết dòng nào đã chạy qua test, không chứng minh assertion đúng hoặc edge case đã được kiểm tra. Một agent có thể đẩy coverage lên bằng test gọi hàm nhưng không kiểm tra kết quả. Gate nên nhìn cả mức coverage tối thiểu, mức giảm so với trước và chất lượng các tình huống quan trọng.

### 3. Giới hạn kích thước và phạm vi pull request

Một PR nhỏ giúp con người hiểu thay đổi, đối chiếu với spec và rollback dễ hơn. Nếu agent tạo ra 2.000 dòng, hãy yêu cầu tách theo migration, domain logic, API, UI và observability. Tốc độ của agent không phải lý do để chuyển chi phí sang reviewer.

### 4. Mọi autofix vẫn cần người sở hữu quyết định

Autofix là đề xuất, không phải phán quyết. Reviewer phải hiểu finding, xem bản sửa có thay đổi hành vi hay không và chạy lại kiểm thử liên quan. Với concurrency, transaction, authentication và authorization, một thay đổi nhỏ về cấu trúc có thể tạo tác động lớn.

### 5. Buộc thay đổi có bằng chứng vận hành

Với code production, test xanh chưa đủ. Hãy hỏi log nào sẽ giúp chẩn đoán, metric nào báo regression, alert nào cần thay đổi và rollback diễn ra thế nào. Reliability không kết thúc ở nút Merge.

## Một ví dụ: hàm retry nhìn sạch nhưng tạo đơn hàng trùng

Giả sử agent thấy request thanh toán có thể timeout và thêm vòng lặp retry ba lần. Code ngắn, có exponential backoff và test mô phỏng hai lần timeout. Static analysis không báo lỗi. Coverage tăng.

Nhưng nếu server đã xử lý thanh toán trước khi response bị mất, request thứ hai có thể trừ tiền lần nữa. Vấn đề không nằm ở cú pháp retry mà ở tính chất nghiệp vụ: thao tác có idempotent hay không. Bản sửa đúng cần idempotency key, lưu kết quả theo ý định thanh toán, xử lý cùng key khác payload, đối soát trạng thái không chắc chắn và metric cho conflict/pending.

Đây là lý do code quality phải nối với spec và system design. Công cụ có thể tìm nhiều vấn đề trong code; con người vẫn phải xác nhận hành vi có đúng với thế giới thật hay không.

## Lộ trình 30 ngày để đưa quality gate vào team

**Tuần 1 — đo, chưa chặn:** chạy phân tích trên một nhóm repository đại diện. Phân loại finding theo severity, tỷ lệ false positive và vùng code thường thay đổi. Đừng lấy điểm tổng hợp làm KPI cá nhân.

**Tuần 2 — xử lý nợ mới trước:** chỉ gate các pull request tạo thêm lỗi reliability/maintainability mức cao. Existing debt được đưa vào backlog theo rủi ro thay vì bắt team dọn sạch trong một sprint.

**Tuần 3 — nối coverage và ownership:** hiển thị coverage ngay trên PR, đặt ngưỡng không được giảm cho module quan trọng, và gắn CODEOWNERS cho các vùng nhạy cảm. AI có thể đề xuất bản sửa; owner chịu trách nhiệm quyết định.

**Tuần 4 — đo kết quả thật:** theo dõi finding được xử lý trước merge, thời gian review, tỷ lệ PR phải rollback, lỗi production và thời gian sửa. Nếu cảnh báo tăng nhưng incident không giảm, ruleset đang tạo tiếng ồn chứ chưa tạo chất lượng.

## Những chỉ số không nên dùng một mình

Số finding thấp không đồng nghĩa codebase tốt nếu rule chưa phủ đúng ngôn ngữ hoặc repository quan trọng chưa bật quét. Coverage cao không đảm bảo test có ý nghĩa. Số dòng code do AI tạo càng không phải productivity nếu review và sửa lỗi chiếm nhiều thời gian hơn.

Một bộ chỉ số cân bằng nên có lead time, change failure rate, rollback, lỗi lọt production, thời gian khôi phục, finding mới theo severity, tỷ lệ finding xử lý trước merge và thời gian con người dành cho review. Mục tiêu không phải tạo dashboard đẹp. Mục tiêu là thay đổi nhanh mà không làm hệ thống khó thay đổi hơn vào tháng sau.

## AI làm tăng giá trị của Clean Code — không làm nó lỗi thời

Khi code trở nên rẻ để tạo, khả năng đọc, đánh giá và xóa code trở nên đắt giá hơn. Developer không còn chỉ được đo bằng lượng code tự tay viết. Họ cần thiết kế ranh giới, đưa ngữ cảnh đúng cho agent, nhận ra phương án nghe hợp lý nhưng sai hệ thống, và chịu trách nhiệm cho điều được merge.

[Clean Code, 2nd Edition bản tiếng Việt](/sach/clean-code-robert-c-martin-2026) giúp người đọc xây nền tảng về naming, hàm, cấu trúc, lỗi và khả năng bảo trì. [The Clean Coder bản tiếng Việt](/sach/the-clean-coder-robert-c-martin-2026) đi vào phần trách nhiệm nghề nghiệp: cam kết, chất lượng và cách làm việc dưới áp lực. Với hệ thống phân tán, [Building Microservices, 2nd Edition bản tiếng Việt](/sach/building-microservices-sam-newman-2026) giúp nối chất lượng code với ranh giới dịch vụ và vận hành.

Wavi Books phụ trách biên phiên dịch, dữ liệu sản phẩm và nội dung chuyên môn cho sách lập trình tiếng Việt. 89ebook là đối tác thương mại độc quyền phân phối sách tiếng Việt của Wavi Books tại Việt Nam trong thời điểm hiện tại. AI có thể giúp team tạo thay đổi nhanh hơn. Việc thay đổi đó có đáng tin và còn sửa được sau này hay không vẫn là trách nhiệm của con người.