Kiểm Soát @mention Và Đánh Giá Plugin Độc Lập Trong Claude Code 2.1.299

Thông tin bài viết gốc & Loại nội dung

Tác giả: kai_kou
Tiêu đề gốc: Claude Code 2.1.299入門、@参照の展開停止とplugin evalのAgent除外を実測
Nguồn: Qiita (Công bố ngày 17/10/2026 - Qiita ID: fddc22860db626d4d672)
Loại nội dung: Trích đoạn ngắn nguyên văn đối chiếu kết hợp với bài đọc tiếng Nhật do ban biên tập xây dựng chi tiết theo mạch thực nghiệm kỹ thuật của tác giả.

Hero image là sơ đồ khái niệm SVG 1200×675 do BrSE.vn tự vẽ, phát hành theo giấy phép CC0 1.0. Alt của ảnh là tiêu đề bài viết. Minh họa cơ chế kiểm soát mở rộng tệp và tối ưu chi phí token khi đánh giá plugin.

Mục tiêu học tập

Kiến thức công nghệ: Hiểu rõ cơ chế mở rộng (expansion) của ký tự @ khi tham chiếu tệp trong các công cụ hỗ trợ lập trình AI, cách sử dụng biến môi trường CLAUDE_CODE_DISABLE_FILE_MENTIONS để bảo vệ mã nguồn nhạy cảm, và kỹ thuật dùng claude plugin eval --disallow-tools để đo lường hiệu năng của plugin mà không bị can thiệp bởi sub-agent.
Năng lực tiếng Nhật: Nâng cao khả năng đọc hiểu các tài liệu benchmark, phân tích tỷ lệ phần trăm (〜割, 〜%の減少), cách lập luận đối chiếu hai luồng quan sát (向きの違う2つの観測) và các mẫu ngữ pháp N2/N3 chỉ sự tương phản hoặc bổ sung.

Key Takeaways

Nguy cơ tiềm ẩn từ cú pháp @: Mặc định khi gõ @filename, toàn bộ nội dung của tệp sẽ được nhồi thẳng vào ngữ cảnh hội thoại ngay lúc đó. Nếu chỉ định nhầm các tệp bí mật (như .env.local), dữ liệu nhạy cảm sẽ bị lưu vĩnh viễn trong bản ghi transcript phiên làm việc.
Cơ chế chuyển giao quyền đọc: Thiết lập CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 không làm tệp bị “vô hình”, mà chuyển đổi hành vi: thay vì nhồi văn bản tự động, Claude Code chỉ nhận được chuỗi đường dẫn, buộc mô hình phải gọi công cụ Read nếu thực sự cần đọc. Nhờ vậy, thao tác này sẽ đi qua bộ lọc kiểm tra quyền hạn permissions.deny.
Đánh giá plugin độc lập và tiết kiệm chi phí: Sử dụng --disallow-tools loại trừ sub-agent giúp đo lường năng lực thuần túy của plugin, đồng thời giảm khoảng 42% chi phí tiêu hao token trong các thử nghiệm thực tế.

Nội dung Bài học & Đọc hiểu Nhật – Việt

Phần 1: Kiểm chứng việc ngăn chặn tự động mở rộng nội dung tệp với biến môi trường

(第1部：環境変数によるファイル展開停止の実測検証)

Đoạn trích nguyên văn / 原文引用

チャット欄らんで @config/.env.local のようにファイルを指さしたとき、その中身なかみがどの時点じてんでモデルに渡わたっているかを意識いしきしたことはあるでしょうか。@ メンションは手軽てがるなぶん、指さした時点じてんでファイルの全文ぜんぶんが会話かいわに入はいります。読よませるつもりのなかった行ぎょうまで文脈ぶんみゃくに載のり、セッションの記録きろくにも残のこります。

Bản dịch tiếng Việt tương ứng

Khi bạn trỏ tới một tệp trong khung trò chuyện, chẳng hạn như @config/.env.local, bạn đã bao giờ ý thức được nội dung của tệp đó được chuyển giao cho mô hình ngôn ngữ tại thời điểm nào chưa? Mặc dù tính năng @mention rất tiện lợi, nhưng tại đúng thời điểm bạn trỏ vào, toàn văn tệp sẽ lập tức bị nạp thẳng vào hội thoại. Ngay cả những dòng bạn hoàn toàn không có chủ đích cho mô hình đọc cũng bị đưa vào ngữ cảnh và lưu lại trong bản ghi phiên làm việc.

Đoạn đọc mở rộng biên soạn / 解説読解文

CLAUDE_CODE_DISABLE_FILE_MENTIONS を有効化ゆうこうかすると、モデルにはファイルのパスのみが伝達でんたつされます。これにより、モデルが実際じっさいに情報じょうほうを必要ひつようとする場合ばあいにのみ、ツール経由けいゆでアクセスが要求ようきゅうされ、事前じぜんに定義ていぎした権限けんげんチェックを確実かくじつに通とおすことが可能かのうになります。

Bản dịch đoạn đọc mở rộng

Khi kích hoạt CLAUDE_CODE_DISABLE_FILE_MENTIONS, hệ thống chỉ truyền đường dẫn của tệp tới mô hình. Nhờ đó, chỉ khi mô hình thực sự cần dữ liệu, nó mới phát sinh yêu cầu truy cập qua công cụ, cho phép kiểm tra một cách chắc chắn các quy tắc phân quyền đã được định nghĩa trước.

Giải thích kỹ thuật: Tác giả kiểm tra bằng lệnh claude -p kết hợp với tệp dummy. Khi chưa bật biến môi trường, toàn bộ các dòng bí mật xuất hiện ngay trong prompt payload ban đầu. Khi bật cờ, mô hình chỉ nhận chuỗi ký tự tên tệp và phải chủ động gọi Read, từ đó kích hoạt bộ lọc quyền hạn.

Phần 2: Đánh giá Plugin độc lập với cờ –disallow-tools

(第2部：–disallow-tools によるプラグイン単体評価とトークン削減)

Đoạn trích nguyên văn / 原文引用

プラグインの性能せいのうを測はかりたいのに、サブエージェントが勝手かってに動うごいて問題もんだいを解といてしまっては、プラグイン単体たんたいの実力じつりょくがわかりません。claude plugin eval --disallow-tools Agent を指定していすることで、エージェントへの委譲いじょうを遮断しゃだんし、プラグインの純粋じゅんすいな振ふる舞まいを採点さいてんできます。また、検証けんしょうでのトークン費用ひようも約やく4割わり減少げんしょうしました。

Bản dịch tiếng Việt tương ứng

Khi bạn muốn đo lường hiệu năng của một plugin mà sub-agent lại tự ý can thiệp giải quyết bài toán thì ta không thể nào nhận biết được thực lực độc lập của plugin đó. Bằng cách khai báo claude plugin eval --disallow-tools Agent, bạn sẽ chặn đứng việc ủy quyền cho agent ngoài, từ đó chấm điểm được hành vi thuần túy của plugin. Ngoài ra, chi phí token tiêu tốn trong quá trình thử nghiệm cũng giảm đi khoảng 40%.

Giải thích kỹ thuật: Trong bài kiểm tra với 7 bộ đề benchmark chuyển đổi dữ liệu, cờ --disallow-tools Agent giúp giảm số lượng token tiêu thụ từ 142.000 xuống còn 82.500 token (giảm khoảng 42%), đồng thời loại bỏ các hành vi sinh prompt phụ ngầm.

Ví dụ Lệnh Thực thi Thực tế & Giới hạn Áp dụng

Dưới đây là các lệnh thiết lập trong môi trường làm việc của kỹ sư:

# Ngăn chặn việc tự động bung nội dung tệp khi gõ @
export CLAUDE_CODE_DISABLE_FILE_MENTIONS=1

# Kiểm tra đánh giá plugin mà không cho phép phân nhánh sang sub-agent
claude plugin eval --disallow-tools Agent --prompt "Tạo bộ chuyển đổi JSON sang CSV chuẩn"

Giới hạn kỹ thuật cần ghi nhớ:

Biến môi trường CLAUDE_CODE_DISABLE_FILE_MENTIONS chỉ có tác dụng khi đặt ở cấp độ Shell của người dùng hoặc cấu hình quản lý tập trung (Managed Settings). Việc khai báo nó trong tệp .claude/settings.json ở cấp độ thư mục dự án sẽ bị bỏ qua để tránh việc mã nguồn dự án can thiệp vào chính sách của lập trình viên.

6. Học tiếng Nhật qua chủ đề — 技術日本語を学ぶ

6.1. Sổ tay thuật ngữ Kiểm soát Tệp và Đánh giá Plugin

Bảng tổng hợp các thuật ngữ chuyên ngành về kiểm soát ngữ cảnh tệp, đánh giá công cụ và đo lường benchmark AI:

Thuật ngữ Nhật	Furigana	Hán Việt	Nghĩa tiếng Việt / English	Câu ví dụ Nhật	Dịch nghĩa
展開	てんかい	Triển Khai	Mở rộng nội dung, bung tệp (Expansion)	マクロの展開てんかいを制限せいげんする。	Hạn chế việc tự động bung nội dung macro.
手軽	てがる	Thủ Khinh	Tiện lợi, dễ dàng sử dụng	手軽てがるなコマンドだがリスクもある。	Lệnh tiện lợi nhưng vẫn tiềm ẩn rủi ro.
振る舞い	ふるまい	Chấn Vũ	Hành vi của phần mềm (Behavior)	新機能しんきのうの振ふる舞まいを検証けんしょうする。	Kiểm chứng hành vi thực tế của tính năng mới.
採点	さいてん	Thải Điểm	Chấm điểm, đánh giá chuẩn (Scoring)	CIでの自動じどう採点さいてん基準きじゅんを設もうける。	Thiết lập tiêu chuẩn chấm điểm tự động trong CI.
単体	たんたい	Đơn Thể	Độc lập, đơn lẻ (Stand-alone / Unit)	プラグイン単体たんたいでのテストを実行じっこうする。	Thực hiện kiểm thử độc lập đối với plugin.
減少	げんしょう	Giảm Thiểu	Suy giảm, sụt giảm số lượng	トークン消費量しょうひりょうが大幅おおはばに減少げんしょうした。	Lượng token tiêu thụ đã giảm rõ rệt.
伝達	でんたつ	Truyền Đạt	Truyền đạt, chuyển giao thông tin	ファイルのパスのみがモデルに伝達でんたつされる。	Chỉ có đường dẫn tệp được chuyển giao cho model.
除外	じょがい	Trừ Ngoại	Loại trừ, bài trừ thành phần	サブエージェントの呼出よびだしを除外じょがいする。	Loại trừ việc gọi các sub-agent.
維持	いじ	Duy Trì	Duy trì, bảo toàn trạng thái	安全あんぜんな開発かいはつ体制たいせいを維持いじする。	Duy trì cơ chế phát triển an toàn.
偶発的	ぐうはつてき	Ngẫu Phát Tính	Ngẫu nhiên, bất ngờ (Accidental)	機密情報きみつじょうほうの偶発的ぐうはつてきな漏洩ろうえいを防ふせぐ。	Ngăn chặn việc rò rỉ thông tin mật một cách ngẫu nhiên.
実測	じっそく	Thực Trắc	Đo lường thực tế, benchmark	ベンチマークを実測じっそくしてデータを集あつめる。	Đo lường thực tế benchmark để thu thập dữ liệu.

Tra cứu Kanji trong bài

展 (TRIỂN) · 開 (KHAI)
手 (THỦ) · 軽 (KHINH)
振 (CHẤN) · 舞 (VŨ)
採 (THẢI) · 点 (ĐIỂM)
単 (ĐƠN) · 体 (THỂ)
減 (GIẢM) · 少 (THIỂU)
伝 (TRUYỀN) · 達 (ĐẠT)
除 (TRỪ) · 外 (NGOẠI)
維 (DUY) · 持 (TRÌ)
偶 (NGẪU) · 発 (PHÁT) · 的 (TÍNH)
実 (THỰC) · 測 (TRẮC)

6.2. Ngữ pháp và mẫu diễn đạt trọng tâm

Bảng tổng hợp các cấu trúc ngữ pháp dùng trong tài liệu benchmark và phân tích quy trình AI:

Mẫu	Ý nghĩa	Ví dụ
〜た上で	Sau khi hoàn tất A mới thực hiện B	動作確認どうさかくにんを完了かんりょうした上うえで、デプロイする。
〜に伴い	Cùng với, đi kèm theo biến đổi của A	バージョンアップに伴ともない、新機能しんきのうが追加ついかされた。
〜だけでなく	Không những… mà còn…	プラグイン単体たんたいだけでなく、CI連携れんけいも検証けんしょうする。

Chi tiết từng mẫu ngữ pháp:

〜た上で (N3): Sau khi hoàn tất hành động A thì mới tiến hành B
- Cấu trúc: Động từ thể Ta (た) + 上で / 名詞 + の上で
- Ý nghĩa & sắc thái: Nhấn mạnh tính tuần tự chặt chẽ trong quy trình kỹ thuật; hành động A là bước tiền đề bắt buộc phải xong thì mới chuyển sang B.
- Ví dụ 1: 開発環境かいはつかんきょうでの動作確認どうさかくにんを完了かんりょうした上うえで、本番ほんばん環境かんきょうへのデプロイを実施じっしいたします。(Sau khi hoàn tất kiểm tra trên môi trường dev, chúng tôi mới triển khai lên production.)
- Ví dụ 2: 仕様しようをご確認かくにんいただいた上うえで、見積みつもりを提出ていしゅついたします。(Sau khi quý khách đã xác nhận đặc tả, chúng tôi mới nộp bản báo giá.)
- Lỗi thường gặp: Tránh nhầm với 〜てから (đơn thuần là thứ tự thời gian thông thường, không nhấn mạnh điều kiện tiền đề).
〜に伴い (N2): Cùng với sự thay đổi của A, B cũng biến đổi theo
- Cấu trúc: Danh từ / Động từ thể từ điển + に伴い / に伴って
- Ý nghĩa & sắc thái: Diễn tả hai sự biến đổi diễn ra đồng thời, sự việc A là nguyên nhân hoặc bối cảnh dẫn tới sự thay đổi B.
- Ví dụ 1: AIモデルのアップデートに伴ともない、トークン消費量しょうひりょうの削減さくげんが確認かくにんされた。(Đi đôi với việc nâng cấp model AI, lượng token tiêu thụ cũng được ghi nhận giảm xuống.)
- Ví dụ 2: システムの拡張かくちょうに伴ともなって、セキュリティ要件ようけんの見直みなおしが必要ひつようとなる。(Cùng với sự mở rộng hệ thống, việc rà soát yêu cầu an ninh là điều cần thiết.)
〜だけでなく (N3): Không những… mà còn…
- Cấu trúc: Thể thông thường (Danh từ / Tính từ / Động từ) + だけでなく
- Ý nghĩa & sắc thái: Bổ sung thêm một yếu tố quan trọng thứ hai ngoài yếu tố đã được đề cập trước đó.
- Ví dụ 1: プラグインの機能性きのうせいだけでなく、API利用りよう費用ひようも評価ひょうか対象たいしょうとする。(Không chỉ đánh giá tính năng của plugin mà chi phí sử dụng API cũng là đối tượng thẩm định.)
- Ví dụ 2: 単語たんごの意味いみだけでなく、実務じつむでの使つかい分わけを理解りかいする。(Không chỉ hiểu nghĩa của từ vựng mà còn nắm vững cách phân biệt trong thực tế.)

7. Thực hành vai trò BrSE — 現場で伝える

7.1. Câu hỏi Luyện Đọc hiểu Tiếng Nhật (リーディング問題)

Câu 1 (Nguyên nhân): 通常の @ メンション機能がセキュリティ上のリスクになり得るのはなぜか？

A. メンションを使うとネットワーク接続が切断されるから。
B. 指した時点でファイル全文が会話の文脈に入り、意図しない機密行までセッションログに残るから。
C. ファイルの拡張子が自動的に書き換えられてしまうから。
D. モデルが強制的にシャットダウンするから。

Đáp án đúng: B
Giải thích tiếng Việt: Văn bản Phần 1 giải thích rõ khi gõ @, toàn bộ văn bản tệp được tải thẳng vào hội thoại và lưu vào transcript, gây nguy cơ rò rỉ các dòng bí mật không định chia sẻ.

Câu 2 (Cơ chế): CLAUDE_CODE_DISABLE_FILE_MENTIONS を設定すると何が起きるか？

A. ファイル自体が完全に削除される。
B. モデルに中身ではなくパスのみが渡り、中身を読むには権限ルールを経由するツール呼び出しが必要になる。
C. チャット欄で @ 記号の入力が物理的に禁止される。
D. すべてのプラグインが無効化される。

Đáp án đúng: B
Giải thích tiếng Việt: Cài đặt biến môi trường sẽ chặn việc tự động bung nội dung, chỉ chuyển đường dẫn tệp cho mô hình, đưa thao tác đọc vào tầm kiểm soát của các quy tắc phân quyền.

Câu 3 (Hiệu quả): plugin eval で --disallow-tools Agent を指定した際のメリットとして筆者が挙げているものはどれか？

A. プラグインのソースコードが自動で暗号化される。
B. サブエージェントへの依存を排してプラグイン単体の挙動を測れ、トークン費用も約4割削減できた。
C. 評価実行の速度が100倍になる。
D. APIの利用料金が完全無料になる。

Đáp án đúng: B
Giải thích tiếng Việt: Phần 2 nêu rõ hai lợi ích: đánh giá khách quan năng lực độc lập của plugin và cắt giảm khoảng 42% chi phí token do không kích hoạt sub-agent ngầm.

7.2. Bài luyện Viết & Báo cáo Dành cho BrSE

Đề bài: Hãy soạn thảo một báo cáo ngắn (3-4 câu) giải thích với khách hàng Nhật Bản lý do nhóm phát triển thiết lập biến môi trường CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 trên máy trạm của các lập trình viên nhằm đáp ứng tiêu chuẩn bảo mật dự án.

Mẫu câu trả lời tham khảo (参考回答例)

Mẫu báo cáo kỹ thuật chuẩn / 技術報告文例

貴社きしゃプロジェクトのセキュリティ要件ようけんに基もとづき、開発者かいはつしゃ端末たんまつにおける機密情報きみつじょうほうの偶発的ぐうはつてきな漏洩ろうえいを防ふせぐ対策たいさくを講こうじました。
具体手ぐたいてきには、CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 を設定せっていし、@参照さんしょう時じにファイル全文ぜんぶんがAIコンテキストに自動じどう展開てんかいされるのを無効化むこうかしております。
これにより、すべてのファイルアクセスが事前じぜんの権限けんげんチェックを経由けいゆするようになり、安全あんぜんな開発かいはつ体制たいせいを維持いじできております。

Nguồn tham khảo và phạm vi xác minh

kai_kou, Claude Code 2.1.299入門、@参照の展開停止とplugin evalのAgent除外を実測: Bài viết gốc thực nghiệm công bố ngày 17/10/2026.
Anthropic Official Documentation, Claude Code CLI Release Notes & Environment Variables: Đặc tả biến môi trường và công cụ plugin evaluation.