Xây dựng Claude Code Mods: tạo xác nhận trước khi AI chỉnh sửa file quan trọng

Claude Code Mods là gì?

Mod là một plugin có mã JavaScript hoặc TypeScript, đăng ký các bộ xử lý sự kiện gọi là hook. Một hook có thể phản ứng với một lượt gọi công cụ (tool call), một prompt được gửi đi, hoặc một cập nhật giao diện. Bạn tải và quản lý mod thông qua hệ thống plugin của Claude Code.

Tính năng này được Anthropic giới thiệu vào ngày 1/10/2026. Một vài ví dụ hữu ích: một bảng hiển thị các thay đổi file gần đây, một lệnh báo cáo tiến độ tác vụ, hoặc một câu hỏi xác nhận trước khi thực hiện một chỉnh sửa cụ thể. Quy trình tạo mod cho phép bạn yêu cầu Claude tự viết code dựa trên mô tả bạn đưa ra. 

Trong bài hướng dẫn này, bạn sẽ xây dựng một mod nhỏ, yêu cầu xác nhận trước khi Claude chỉnh sửa một file tên release-settings.json. Bạn sẽ thử một lượt chỉnh sửa bình thường, từ chối một thay đổi cài đặt, rồi phê duyệt nó và kiểm tra lại file đã lưu.

Khi nào nên dùng mod, khi nào nên dùng cách khác?

Claude Code có nhiều cách tùy chỉnh khác nhau, và mod chỉ là một trong số đó. Dưới đây là bảng giúp bạn chọn đúng công cụ:

Trong nhiều trường hợp, một permission rule đơn giản đã đủ đáp ứng nhu cầu của bạn. Bài hướng dẫn này chọn dùng mod vì bạn cần tự thiết kế câu hỏi xác nhận và xem trước nội dung thay đổi được đề xuất.

Cần chuẩn bị gì trước khi bắt đầu?

• Claude Code phiên bản v2.1.287 trở lên. Nên dùng v2.1.289 trở lên cho bài hướng dẫn này, vì bản phát hành ngày 3/10 đã sửa một số lỗi liên quan đến quyền hạn và việc tải mod.
• Một terminal (ứng dụng dòng lệnh) để chạy Claude Code.
• Một thư mục trống và một trình soạn thảo văn bản để kiểm tra file.

Kiểm tra phiên bản bằng lệnh:

claude --version

Nếu cài đặt theo cách gốc, cập nhật bằng lệnh claude update. Nếu dùng phương thức cài đặt khác, hãy làm theo hướng dẫn thiết lập Claude Code tương ứng.

Terminal và tab Code trên ứng dụng Desktop hỗ trợ giao diện mod. Các bề mặt khác có giới hạn nhất định, nên hãy làm theo hướng dẫn terminal này trước, rồi mới điều chỉnh cho phù hợp với môi trường bạn thường dùng.

Mod này KHÔNG kiểm soát những gì?

Đây là điểm cực kỳ quan trọng cần hiểu rõ trước khi triển khai. Mod mẫu trong bài này chỉ theo dõi hai công cụ có sẵn là Edit và Write cho một tên file duy nhất. Nó không kiểm tra:

• Lệnh Bash, PowerShell, NotebookEdit, hay các công cụ MCP.
• Các thao tác ghi file từ một chương trình khác.
• Các liên kết tượng trưng (symbolic link) hoặc tên file khác có thể trỏ tới cùng một file vật lý.

Hãy coi đây là một công cụ hỗ trợ xem xét, không phải một lớp bảo mật toàn diện. Luôn giữ bản sao lưu, kiểm tra kỹ các thay đổi, và dùng quyền file phù hợp hoặc môi trường cô lập cho những công việc cần mức độ bảo vệ cao hơn. Tài liệu bảo mật plugin của Anthropic nêu rõ: mod có quyền truy cập máy tính tương đương với chính Claude Code.

Với một quy tắc cố định đơn giản, như hỏi trước khi chỉnh sửa một đường dẫn duy nhất, hãy cân nhắc dùng permission rule thông thường trước. Chỉ dùng mod tùy chỉnh khi việc xem xét cần thêm chi tiết hoặc logic phức tạp hơn.

Hướng dẫn từng bước xây dựng mod review-before-edit

Bước 1: Tạo một dự án thực hành nhỏ

Tạo một thư mục mới tên claude-mod-practice. Mở nó trong trình soạn thảo và tạo hai file sau.

File README.md:

# Dự án demo

Thư mục này chứa các cài đặt giả định cho bài hướng dẫn Claude Code.

File release-settings.json:

{

" environment ": "demo" ,

" checkoutEnabled ": false

}

Cài đặt này không liên quan đến bất kỳ hệ thống checkout hay website thật nào. Nó chỉ cho bạn một giá trị cụ thể để kiểm tra trước và sau khi chỉnh sửa.

Mở terminal trong thư mục này và chạy:

claude

Xem lời nhắc về độ tin cậy không gian làm việc (workspace trust prompt). Giữ nguyên các kiểm tra quyền hạn thông thường của Claude Code đang được bật, và không đưa các file hoặc dịch vụ kết nối không liên quan vào bài thực hành này.

Bước 2: Yêu cầu Claude viết mod

Tại dấu nhắc Claude Code, gõ:

/plugin-authoring

Lệnh này sẽ tải hướng dẫn tạo plugin tích hợp sẵn của Anthropic. Sau đó, dán yêu cầu sau. Yêu cầu này đòi hỏi tạo file mã nguồn và bài kiểm thử trước khi mod thực sự chạy:

Hãy xây dựng một mod Claude Code tên review-before-edit cho thư mục thực hành này. Dùng hướng dẫn plugin-authoring và API được hỗ trợ bởi phiên bản tôi đang dùng.

Lưu plugin vào. /review-before-edit. Chỉ tạo file mã nguồn và bài kiểm thử. Không cài đặt, không bật hot reload, không thay đổi quyền hạn, không tải nó lên. Không chỉnh sửa README.md hay release-settings.json trong khi xây dựng mod.

Hành vi mong muốn:

- Xử lý sự kiện tool.call cho hai công cụ có sẵn Edit và Write.

- Kiểm tra tên file cuối cùng trong file_path. Khớp với release-settings.json không phân biệt hoa thường, kể cả đường dẫn dùng dấu phân tách kiểu Windows.

- Để nguyên các tên file khác cho các kiểm tra công cụ và quyền hạn thông thường xử lý.

- Với file khớp điều kiện, hiển thị tên công cụ, đường dẫn, và một bản xem trước ngắn gọn về nội dung chỉnh sửa được đề xuất. Ghi rõ nhãn nếu bản xem trước bị cắt bớt.

- Hỏi thông qua $.ui.ask với các lựa chọn theo đúng thứ tự sau:

"Giữ nguyên file, không thay đổi" và "Cho phép chỉnh sửa này".

- Chỉ tiếp tục bằng next(e) khi câu trả lời chính xác là "Cho phép chỉnh sửa này". Giữ nguyên đầu vào gốc của công cụ và mọi kiểm tra quyền hạn thông thường.

- Từ chối nếu câu hỏi bị bỏ qua, không hiển thị được, hoặc trả về bất kỳ câu trả lời nào khác. Yêu cầu Claude dừng lại, thay vì thử một công cụ hoặc đường dẫn khác.

- Thêm một bộ xử lý. catch trả về từ chối nếu handler này gặp lỗi.

- Hỏi lại với mỗi lượt chỉnh sửa khớp điều kiện. Không bao giờ lưu lại một sự phê duyệt áp dụng chung cho mọi lần sau.

Giữ mod nhỏ gọn. Không gọi mạng, không chạy tiến trình con, không gọi thêm mô hình, không truy cập trực tiếp hệ thống file, không thêm dependency mới.

Thêm bài kiểm thử cho các trường hợp: chỉnh sửa được cho phép, chỉnh sửa bị từ chối, thay thế bằng Write, các file khác, yêu cầu lặp lại, và trường hợp bị từ chối quyền hạn ở bước sau. Giải thích cách chạy các bài kiểm thử bằng lệnh claude plugin test. Hiển thị tất cả các file và lệnh tải chính xác. Liệt kê các công cụ và đường dẫn mà ví dụ này chưa bao quát.

Lưu ý quan trọng: hãy đọc kỹ mã nguồn trước khi tải nó lên. Yêu cầu Claude giải thích bất kỳ đoạn code nào bạn chưa hiểu rõ. Nhờ một lập trình viên có kinh nghiệm xem lại khi cần thiết.

Cấu trúc file mod thường sẽ gồm: một mô tả plugin, một file trỏ tới mã nguồn, và mã nguồn thực tế. Các bài kiểm thử có thể nằm trong một thư mục riêng:

review-before-edit/

.claude-plugin/

plugin.json

hooks/

hooks.json

register.js

tests/

review-before-edit.test.ts

Claude có thể chọn đặt tên register.ts thay vì register.js, miễn là tên file khớp với những gì khai báo trong hooks.json.

Bước 3: Kiểm tra file trước khi tải lên

Mod chạy với quyền truy cập rộng vào máy tính của bạn. Chúng có thể truy cập file, khởi chạy tiến trình, hoặc gửi yêu cầu mạng thông qua API của mod. Hãy luôn xem xét kỹ những gì bạn cài đặt, kể cả khi chính Claude là người viết ra nó, và tuân theo mọi quy định kiểm soát mod của tổ chức bạn nếu có. Hướng dẫn bảo mật plugin của Anthropic khuyến nghị coi mọi plugin đã cài đặt như mã nguồn đáng tin cậy - nghĩa là bạn cần tự kiểm chứng trước khi tin tưởng nó.

Mở một terminal thứ hai, với claude-mod-practice là thư mục làm việc, và chạy lần lượt hai lệnh sau:

claude plugin validate. /review-before-edit

claude plugin test. /review-before-edit

Lệnh validate sẽ kiểm tra gói plugin và liệt kê các mục hooks: và calls: mà không thực sự chạy mod. Hãy xem kỹ danh mục khả năng (capability inventory) và mọi cảnh báo được hiển thị. Lưu ý: việc kiểm tra thành công không chứng minh được mã nguồn an toàn tuyệt đối - đây chỉ là một bước sàng lọc ban đầu.

Lệnh test sẽ chạy thử mod với các sự kiện giả lập, không cần phiên làm việc với mô hình, không cần đăng nhập, không cần kết nối mạng. Hãy xác nhận các bài kiểm thử thực sự đã chạy và đạt kết quả như mong đợi. Yêu cầu Claude sửa lại nếu có bài kiểm thử thất bại hoặc bộ chạy thử không tìm thấy bài kiểm thử nào.

Với ví dụ này, mã nguồn cần xử lý sự kiện tool.call và đặt câu hỏi xác nhận thông qua ui.ask. Nếu phát hiện truy cập file bất thường, gọi mạng, khởi chạy tiến trình, hoặc ghi đè quyền hạn không mong muốn, hãy yêu cầu giải thích rõ ràng trước khi tiếp tục.

Bước 4: Tải mod cho một phiên làm việc

Đóng phiên Claude Code đầu tiên của bạn. Từ cùng thư mục thực hành, bắt đầu một phiên mới với lệnh:

claude --plugin-dir. /review-before-edit

Lệnh này tải plugin cục bộ cho đúng một phiên làm việc, cho phép bạn thử nghiệm mã nguồn trước khi quyết định cài đặt lâu dài.

Bên trong Claude Code, chạy lệnh /plugin và kiểm tra tab Installed để xem review-before-edit đã xuất hiện chưa. Nếu mod chưa được tải, hãy dừng lại và kiểm tra lại các bước trước.

Bước 5: Thử một chỉnh sửa bình thường, rồi từ chối một thay đổi cài đặt

Đầu tiên, yêu cầu:

Dùng công cụ Edit để thêm câu này vào README.md:

"Dự án này chỉ dùng để thực hành."

Giữ nguyên release-settings.json, không thay đổi.

Mod không nên thêm câu hỏi tùy chỉnh nào cho file này. Claude Code vẫn có thể hiển thị lời nhắc quyền hạn thông thường. Hãy kiểm tra lại file README đã lưu trong trình soạn thảo của bạn.

Tiếp theo, yêu cầu:

Dùng công cụ Edit để đổi checkoutEnabled từ false thành true trong

release-settings.json. Giữ nguyên environment là demo. Dừng lại nếu

tôi từ chối. Không dùng shell, công cụ khác, hay đường dẫn khác để

thực hiện thay đổi này.

Hãy tìm câu hỏi xác nhận tùy chỉnh, hiển thị tên file và nội dung thay đổi được đề xuất. Chọn "Giữ nguyên file, không thay đổi".

Mở lại file release-settings.json trong trình soạn thảo. Giá trị checkoutEnabled vẫn phải là false. Lưu ý quan trọng: việc Claude thông báo rằng nó đã dừng lại chỉ là một phần của việc kiểm tra. File đã lưu mới là bằng chứng thực sự.

Nếu file đã bị thay đổi, hãy dừng ngay bài thực hành. Vô hiệu hóa mod và điều tra lại lượt gọi công cụ cùng mã nguồn đã tải trước khi tiếp tục.

Bước 6: Phê duyệt thay đổi và kiểm tra lại kết quả

Lặp lại đúng yêu cầu thay đổi cài đặt như trên. Lần này, chọn "Cho phép chỉnh sửa này".

Một lời nhắc quyền hạn thông thường của Claude Code có thể xuất hiện tiếp theo. Việc mod phê duyệt chỉ cho phép lượt gọi công cụ này tiếp tục đi qua các bước kiểm tra hiện có, nó không loại bỏ các bước kiểm tra đó.

Khi chỉnh sửa hoàn tất, mở lại file. Nội dung phải là:

{

" environment ": "demo",
" checkoutEnabled ": true

}

Yêu cầu Claude đổi giá trị trở lại false. Câu hỏi xác nhận tùy chỉnh phải xuất hiện lại một lần nữa - mỗi lượt phê duyệt chỉ áp dụng cho đúng một lượt gọi công cụ.

Bảng kiểm tra trước khi quyết định giữ lại mod

Đây là các kết quả mong đợi cho ví dụ cụ thể này. Hãy tự chạy lại các phép thử trên phiên bản bạn đã cài đặt và tự kiểm tra file để xác nhận.

Cách giữ lại, vô hiệu hóa, hoặc gỡ bỏ mod

• Để giữ lại: giữ nguyên thư mục review-before-edit đã kiểm tra. Tải lại nó bằng --plugin-dir mỗi khi bắt đầu một phiên làm việc mới. Chỉ giữ một bản sao hoạt động trong khi thử nghiệm các thay đổi.
• Lưu ý đặc biệt: các mod mà Claude tự tạo trong thư mục mod của phiên làm việc ( ~/.claude/dev-mods/<session-id>/ ) có vòng đời khác biệt - hãy sao chép chúng sang một thư mục lâu dài trước khi dựa vào chúng ở các phiên làm việc sau này.
• Để dừng ví dụ cục bộ này: thoát phiên làm việc và khởi động lại Claude mà không kèm --plugin-dir.
• Với một plugin đã cài đặt chính thức: dùng trình quản lý plugin, mở /plugin → Installed để vô hiệu hóa hoặc gỡ cài đặt.
• Để xử lý sự cố: lệnh claude --safe-mode khởi động một phiên làm việc không có các mod do người dùng cài đặt cùng các tùy chỉnh khác - điều này cũng loại bỏ bước kiểm tra xác nhận của mod này. Hãy dùng chế độ này trong thư mục thực hành, rồi khôi phục lại thiết lập bình thường của bạn sau đó.

Câu hỏi thường gặp

Mod trong Claude Code là gì?

• Mod là một plugin có mã JavaScript hoặc TypeScript, đăng ký các bộ xử lý sự kiện (hook) phản ứng với lượt gọi công cụ, prompt được gửi đi, hoặc cập nhật giao diện. Bạn tải và quản lý mod thông qua hệ thống plugin của Claude Code.

Mod khác gì so với permission rule thông thường?

• Permission rule phù hợp với các quy tắc cố định đơn giản, ví dụ hỏi trước khi chỉnh sửa một đường dẫn file cụ thể. Mod phù hợp khi bạn cần thêm hộp thoại xác nhận tùy chỉnh, bảng giao diện riêng, hoặc logic xử lý sự kiện phức tạp hơn mức permission rule có thể đáp ứng.

Mod này có an toàn tuyệt đối không?

• Mod có quyền truy cập máy tính tương đương với chính Claude Code, và ví dụ trong bài chỉ theo dõi hai công cụ cụ thể cho một tên file duy nhất. Nó không kiểm soát được Bash, PowerShell, công cụ MCP, hay các liên kết tượng trưng trỏ tới cùng file. Hãy coi đây là công cụ hỗ trợ xem xét, không phải lớp bảo mật toàn diện.

Làm sao biết mod thực sự hoạt động đúng?

• Hãy luôn kiểm tra lại nội dung file thực tế sau mỗi lần thử nghiệm, chứ không chỉ tin vào thông báo của Claude rằng nó đã dừng lại hay đã thực hiện thay đổi. File đã lưu mới là bằng chứng xác thực.

Cần phiên bản Claude Code nào để dùng mod?

• Cần v2.1.287 trở lên, khuyến nghị dùng v2.1.289 trở lên vì bản phát hành ngày 3/10/2026 đã sửa một số lỗi liên quan tới quyền hạn và việc tải mod.

Tính năng mod của Claude Code nói chung còn khá mới, được Anthropic giới thiệu từ ngày 1/10/2026, nên cú pháp API, cấu trúc file và các lệnh liên quan có thể tiếp tục thay đổi trong các bản phát hành sau. Thế cho nên là trước khi triển khai mod vào môi trường làm việc thực tế, đặc biệt là với các file hoặc hệ thống quan trọng, bạn hãy luôn đọc kỹ mã nguồn, chạy đầy đủ các bài kiểm thử, và đối chiếu với tài liệu bảo mật plugin chính thức của Anthropic.