Xây dựng quy trình kỹ thuật tiết chế và xác minh hiệu quả cho Agent lập trình với lean-mode

lean-mode là gì?

lean-mode là một SKILL.md dành cho Agent lập trình. Mục tiêu của nó không phải là “càng ít mã càng tốt”, mà là cung cấp cho Agent các tiêu chí rõ ràng để trả lời hai câu hỏi kỹ thuật:

1. Một đoạn mã có vẻ an toàn có đáng để viết hay không, chẳng hạn như kiểm tra, try/catch, lớp trừu tượng, logic dự phòng hoặc một hệ thống con bảo mật bổ sung.
2. Vì sao quá trình build và kiểm thử hiện tại chậm, cũng như làm thế nào để rút ngắn vòng lặp xác minh kém hiệu quả xuống phạm vi hợp lý.

Tệp kỹ năng nằm tại skills/lean-mode/SKILL.md, sử dụng frontmatter tiêu chuẩn gồm name, description và nội dung Markdown. Tệp này không phụ thuộc vào một host cụ thể; mọi Agent hỗ trợ quy ước SKILL.md đều có thể sử dụng.

Các vấn đề cốt lõi cần giải quyết

Trong những phiên lập trình kéo dài, mô hình dễ xuất hiện hai xu hướng mang tính hệ thống: lập trình phòng thủ quá mức và vòng lặp xác minh kém hiệu quả.

Lập trình phòng thủ quá mức

Các biểu hiện phổ biến gồm lặp lại việc kiểm tra giá trị null trên dữ liệu nội bộ đáng tin cậy, dùng bắt ngoại lệ để che giấu nguyên nhân gốc, tạo lớp trừu tượng quá sớm cho một triển khai duy nhất, và liên tục thêm logic dự phòng khi chưa xác định được nguồn gốc vấn đề. Bề ngoài, mã có vẻ “an toàn” hơn, nhưng thực tế có thể làm tăng chi phí bảo trì và biến một lỗi rõ ràng thành giá trị lỗi khó truy vết.

Vòng lặp xác minh kém hiệu quả

Các biểu hiện phổ biến gồm thường xuyên chạy build đầy đủ, lặp lại clean, tắt tiến trình thường trú, lần nào cũng chạy toàn bộ kiểm thử và để các lệnh rõ ràng đã bị treo chờ trong thời gian dài. lean-mode dùng sáu nhóm quy tắc về tái sử dụng tiến trình, thực thi tăng dần, kiểm soát phạm vi, thứ tự thực thi, tần suất gọi và quản lý thời gian chờ để hạn chế các hành vi này.

Dữ liệu định lượng trong README đến từ một phiên làm việc kéo dài duy nhất trên một dự án Java và Gradle khoảng 20k dòng, chỉ nhằm cho thấy vấn đề thực sự tồn tại, không nên được xem là tiêu chuẩn ngành áp dụng cho mọi mô hình hoặc dự án.

Năng lực chính

• Chỉ kiểm tra một lần tại ranh giới tin cậy: yêu cầu trước tiên trả lời “null này xuất phát từ đâu”, nhằm tránh việc dữ liệu đáng tin cậy vẫn bị kiểm tra lặp lại qua nhiều tầng sau khi đã vào hệ thống.
• Không nuốt nguyên nhân gốc: cảnh giác với việc sau catch trả về null, false, tập hợp rỗng hoặc giá trị 0, vì chúng có thể biến một ngoại lệ rõ ràng thành lỗi khó định vị hơn.
• Hạn chế trừu tượng hóa sớm: một lớp trừu tượng chỉ có một triển khai và được tạo ra chỉ để có thể thay thế trong tương lai chưa chắc đã hình thành ranh giới mở rộng thực sự ổn định.
• Ưu tiên sửa nguyên nhân gốc: thêm logic dự phòng thường cho thấy nguyên nhân gốc chưa được giải quyết hoàn toàn. Khi thực sự cần dự phòng, phải nêu rõ vấn đề thuộc về đâu, điều kiện xóa là gì và căn cứ đã được xác minh.
• Để quy mô thay đổi tương xứng với thay đổi hành vi: khi thêm hơn 50 dòng mã, trước tiên phải báo cáo tổng số dòng, số dòng dành cho kiểm tra và dự phòng, cũng như cái giá thực tế của việc không viết chúng.
• Trả lời ba câu hỏi trước khi viết mã phòng thủ: vấn đề có thực sự xảy ra không, người dùng sẽ chịu ảnh hưởng gì khi nó xảy ra, và cái giá của việc không viết là gì. Nếu không trả lời được bất kỳ câu hỏi nào, trước tiên không thêm mã.
• Rút ngắn vòng lặp xác minh: bao quát tư duy xác minh tối thiểu cho bảy loại hệ thống build gồm Gradle, Maven, Go, Node và TypeScript, Rust, Python và .NET.
• Cho phép kết luận “không cần thay đổi”: mục tiêu là giải quyết vấn đề, không phải ép buộc tạo ra mã, đồng thời không tự tiện gia cố các khu vực người dùng chưa yêu cầu.
• Cung cấp quy trình kiểm tra mã hiện có đã phòng thủ quá mức: trước tiên định lượng mật độ, sau đó kiểm tra các tệp nghiêm trọng nhất, lần lượt quyết định xóa, chuyển lên hoặc giữ lại, rồi gửi bảng kết quả cho người dùng trước khi sửa.

Đối với mã phòng thủ, kỹ năng cung cấp các ví dụ phản diện bằng Java, Go, TypeScript và Python, giúp Agent nhận diện những vấn đề cùng loại ẩn sau các cú pháp khác nhau.

Cài đặt lean-mode

Cách một: Tải từ URL

Nếu host hỗ trợ nhập kỹ năng từ URL, chẳng hạn trang kỹ năng của Vantaloom, bạn có thể dán trực tiếp địa chỉ kho lưu trữ. Host sẽ tìm thấy tệp kỹ năng trong skills/lean-mode/.

https://github.com/Timefiles404/lean-mode-skill

Cách hai: Sao chép vào workspace

Trước tiên clone kho lưu trữ, sau đó sao chép thư mục kỹ năng vào vị trí mà host quy định. Khi sử dụng quy ước workspace của Vantaloom, hãy chạy:

git clone https://github.com/Timefiles404/lean-mode-skill.git
cp -r lean-mode-skill/skills/lean-mode <workspace-của-bạn>/.vantaloom/skills/

Nếu host sử dụng thư mục kỹ năng theo phong cách Claude, hãy sao chép vào .claude/skills/:

cp -r lean-mode-skill/skills/lean-mode <workspace-của-bạn>/.claude/skills/

Cách ba: Tạo kỹ năng thủ công

Tạo một kỹ năng mới trong host, sau đó dán toàn bộ nội dung skills/lean-mode/SKILL.md trong kho lưu trữ vào đó. Không được bỏ sót frontmatter ở đầu tệp, vì host dựa vào description trong đó để quyết định khi nào tải kỹ năng.

Quy trình sử dụng cơ bản

Sau khi cài đặt, lean-mode chủ yếu dựa vào mô tả kỹ năng để được đưa vào ngữ cảnh khi cần. Kỹ năng nên được kích hoạt khi Agent chuẩn bị thêm kiểm tra, bắt ngoại lệ, lớp trừu tượng, logic dự phòng hoặc hệ thống con bảo mật bổ sung, hoặc khi đã thực hiện nhiều lần build và kiểm thử trong một vòng làm việc.

Tình huống một: Đánh giá có cần thêm kiểm tra hay không

1. Trước tiên xác định nguồn dữ liệu, kiểm tra xem dữ liệu có đến từ đầu vào bên ngoài, ranh giới API hay nguồn không đáng tin cậy khác không.
2. Kiểm tra xem cùng một ràng buộc đã được xác minh tại ranh giới tin cậy hay chưa.
3. Trả lời vấn đề có thực sự xảy ra không, người dùng sẽ chịu ảnh hưởng gì và cái giá của việc không viết kiểm tra là gì.
4. Nếu dữ liệu đã đáng tin cậy sau khi vào bên trong, không tiếp tục thêm lặp lại cùng loại kiểm tra thời gian chạy qua nhiều tầng.

Ví dụ, khi Agent muốn lặp lại Objects.requireNonNull trong nhiều phương thức nội bộ, không nên thêm chỉ vì tham số “về lý thuyết có thể là null”, mà phải truy vết nguồn null thực tế trước và xác định xem việc xác minh đã hoàn tất ở ranh giới hay chưa.

Tình huống hai: Xử lý ngoại lệ

Khi Agent chuẩn bị bắt ngoại lệ rồi trả về giá trị mặc định, trước tiên phải xác nhận cách xử lý này có che giấu nguyên nhân gốc hay không. Các mẫu sau cần được đặc biệt xem xét:

catch (...) {
    return false;
}

Trọng tâm không phải là cấm mọi việc bắt ngoại lệ, mà là tránh biến một lỗi có thể định vị thành false, null, kết quả rỗng hoặc giá trị 0 thiếu ngữ cảnh. Nếu nghiệp vụ thực sự cần hạ cấp, vẫn phải đánh giá theo các điều kiện ngoại lệ trong kỹ năng.

Tình huống ba: Đánh giá lớp trừu tượng

Nếu một interface hiện chỉ có một triển khai và lý do duy nhất để tạo ra nó là “có thể sẽ thay thế trong tương lai”, Agent nên tạm dừng và kiểm tra ranh giới thay đổi thực sự. lean-mode không phủ nhận việc trừu tượng hóa, mà phản đối việc tạo lớp trung gian quá sớm khi chưa có nhu cầu hiện tại và ranh giới ổn định.

Tình huống bốn: Rút ngắn build và kiểm thử

1. Ưu tiên tái sử dụng tiến trình build hiện có, tránh khởi động lạnh lặp lại khi không cần thiết.
2. Giữ lại sản phẩm build tăng dần, không chạy clean theo thói quen.
3. Trước tiên chạy lệnh tối thiểu: chỉ biên dịch, chỉ kiểm tra module liên quan hoặc chỉ chạy một bài kiểm thử.
4. Sau khi xác minh tối thiểu thành công, từng bước mở rộng sang kiểm thử module hoặc toàn bộ kiểm thử.
5. Kiểm soát tần suất gọi lặp lại, tránh chạy cùng một lệnh nhiều lần khi mã không thay đổi.
6. Đặt thời gian chờ hợp lý cho các lệnh có thể bị treo, sau khi thất bại hãy phân tích nguyên nhân gốc đầu tiên.

Phần nội dung kỹ năng đầy đủ trong README đưa ra vòng lặp xác minh tối thiểu “chỉ chạy lệnh này” cho bảy hệ thống build. Khi sử dụng thực tế, nên thay các ví dụ đó bằng những lệnh thực có thể chạy trực tiếp trong dự án.

Kiểm tra mã đã phòng thủ quá mức

lean-mode đi kèm quy trình kiểm tra “định lượng trước, xóa sau”, phù hợp với các dự án đã tích lũy nhiều logic kiểm tra, dự phòng hoặc nuốt ngoại lệ.

1. Tìm kiếm và định lượng: dùng các mẫu tìm kiếm trong phụ lục theo từng ngôn ngữ để thống kê số lượng và mật độ của các mẫu liên quan.
2. Thu hẹp phạm vi kiểm tra: chỉ xem 5 tệp tập trung nhiều vấn đề nhất, tránh kiểm tra toàn bộ kho ngay từ đầu.
3. Phân loại từng mục: đánh dấu mỗi logic là “xóa”, “chuyển lên” hoặc “giữ”. “Chuyển lên” thường có nghĩa là tập trung kiểm tra tại ranh giới tin cậy thực sự.
4. Báo cáo trước, sửa sau: trước tiên gửi bảng kiểm tra cho người dùng lựa chọn, không tự ý xóa quy mô lớn khi chưa được xác nhận.
5. Xác minh theo từng đợt: sau khi sửa, dùng phạm vi build và kiểm thử tối thiểu để xác minh, rồi mở rộng phạm vi dựa trên kết quả.

Quy trình này nhấn mạnh khả năng quan sát, lựa chọn và quay lui, thay vì biến việc “giảm mã phòng thủ” thành một đợt tái cấu trúc lớn khác không được kiểm soát.

Tùy chỉnh SKILL.md

Bản thân SKILL.md là Markdown và có thể chỉnh sửa trực tiếp. Ba kiểu tùy chỉnh sau mang lại nhiều giá trị nhất.

Thay thế lệnh xác minh của dự án

Thay các lệnh chung trong phần bảy bằng những lệnh “chỉ biên dịch” và “chỉ chạy một bài kiểm thử” có thể thực thi thực tế trong dự án hiện tại. Một lệnh có thể sao chép và chạy trực tiếp thường ràng buộc hành vi của Agent tốt hơn các nguyên tắc trừu tượng.

Điều chỉnh mẫu tìm kiếm

Sửa các quy tắc tìm kiếm trong phụ lục theo phong cách mã của dự án. Ví dụ, một dự án Java có thể dùng Guava Preconditions, hoặc chủ yếu dùng Objects.requireNonNull. Mẫu tìm kiếm phải phù hợp với mã thực tế.

Điều chỉnh mật độ tham khảo

Kỹ năng dùng việc xuất hiện một kiểm tra trong mỗi 200 đến 500 dòng làm tham khảo kinh nghiệm, nhưng đây không phải tiêu chuẩn chung. Mật độ kiểm tra hợp lý của parser, ranh giới giao thức và CRUD nghiệp vụ khác nhau; cần điều chỉnh theo rủi ro lĩnh vực và nguồn dữ liệu.

Khuyến nghị sử dụng nâng cao

• Giữ cả các trường hợp ngoại lệ trong ngữ cảnh: các tiêu chí trong kỹ năng là quy tắc mang tính kinh nghiệm, không phải định lý. Không chỉ giữ lại những khẩu hiệu đơn giản như “đừng kiểm tra” hoặc “đừng catch”.
• Yêu cầu Agent báo cáo cấu thành thay đổi: khi thêm hơn 50 dòng, yêu cầu Agent nêu rõ tổng số dòng, số dòng kiểm tra và dự phòng, cũng như cái giá của việc không triển khai các logic đó.
• Mở rộng phạm vi xác minh theo từng cấp: bắt đầu từ tệp liên quan, một bài kiểm thử hoặc một module, sau đó mới chuyển sang phạm vi kiểm thử lớn hơn, tránh kích hoạt build đầy đủ sau mỗi thay đổi.
• Dùng bằng chứng để giải thích logic dự phòng: khi bắt buộc phải giữ logic dự phòng, hãy ghi lại nguồn vấn đề cụ thể, kết quả xác minh và điều kiện xóa trong tương lai; không dùng những nhận định không thể kiểm chứng như “một số môi trường có thể gặp lỗi”.
• Coi “không sửa đổi” là một kết quả hợp lệ: nếu vấn đề đã được logic hiện có giải quyết, hoặc mã mới không mang lại lợi ích rõ ràng, Agent nên được phép nói thẳng rằng không cần thay đổi.

Giới hạn năng lực và thành phần bổ sung tùy chọn

lean-mode thay đổi xu hướng của mô hình, không thay đổi năng lực của mô hình. Nó không thể buộc mô hình ngừng viết một loại mã nhất định, mà chỉ đưa các tiêu chí vào ngữ cảnh đúng thời điểm, vì vậy có hiệu quả nhưng không phải một sự đảm bảo.

Nó cũng không phải trình phân tích tĩnh và sẽ không tự động đọc hoặc quét mã. Việc kiểm tra trong phụ lục yêu cầu Agent tự chạy các lệnh tìm kiếm tương ứng rồi đưa ra đánh giá dựa trên kết quả.

Plugin cùng tên tùy chọn của Vantaloom sẽ liên tục đưa các quy tắc rút gọn vào ngữ cảnh động ở mỗi vòng, đồng thời cung cấp chú thích cuối cho kết quả công cụ và công cụ lean_review. Plugin phụ trách nhắc nhở liên tục, còn kỹ năng cung cấp đầy đủ tiêu chí. Ngay cả khi không cài plugin, kỹ năng này vẫn có thể hoạt động độc lập.

Có thể xem kho dự án tại lean-mode-skill trên GitHub, theo giấy phép MIT.

Kết luận

Giá trị của lean-mode không nằm ở việc máy móc giảm số dòng mã, mà ở việc giúp mỗi kiểm tra, xử lý ngoại lệ, lớp trừu tượng, logic dự phòng và lệnh xác minh đều có thể giải thích được lý do. Sau khi cài đặt, kết hợp tùy chỉnh theo lệnh thực tế, mẫu tìm kiếm và mật độ rủi ro của dự án sẽ giúp Agent lập trình tập trung hơn vào nguyên nhân gốc, đồng thời xây dựng một vòng phản hồi kỹ thuật ngắn hơn và đáng tin cậy hơn.