Audit file cấu hình agent là quy trình rà soát, đo lường và loại bỏ các chỉ dẫn lỗi thời trong các file hướng dẫn như CLAUDE.md hoặc AGENTS.md nhằm duy trì hiệu năng suy luận và sự chuẩn xác của mô hình.
Khi xây dựng các AI coding agent trong môi trường thực tế, việc kiểm toán này là một kỷ luật kỹ thuật bắt buộc chứ không phải lựa chọn hình thức. Các tệp chỉ dẫn tĩnh luôn có xu hướng tích tụ quy tắc cũ, phình to theo thời gian và biến thành những kho dữ liệu quá tải. Sự phình to này trực tiếp làm tăng chi phí token ở mỗi lượt giao tiếp, gia tăng độ trễ suy luận, đồng thời làm suy giảm khả năng tuân thủ của mô hình do hiện tượng suy hao ngữ cảnh (context rot).
File cấu hình agent không được thiết kế để làm một ngân hàng kiến thức vĩnh cửu, mà là một bản hướng dẫn ra quyết định ngắn gọn có "hạn sử dụng". Khi mô hình ngôn ngữ lớn (LLM) nền tảng được nâng cấp hoặc khung thực thi (harness) xung quanh agent được mở rộng thêm công cụ, các chỉ dẫn thủ công từng viết cho phiên bản cũ sẽ nhanh chóng trở nên lỗi thời, gây nhiễu loạn logic và làm sụt giảm chất lượng đầu ra.
File cấu hình agent không phải là kho lưu trữ vĩnh cửu, mà là bản hướng dẫn ra quyết định ngắn hạn cần được cắt tỉa liên tục.
Để giữ cho hệ thống agent hoạt động ở hiệu năng đỉnh cao, kỹ sư cần loại bỏ tâm lý tích trữ cấu hình do thói quen hay nỗi sợ mơ hồ về việc giảm chất lượng. Mọi dòng quy tắc, lệnh hay kỹ năng (skill) phải liên tục tự chứng minh giá trị kỹ thuật của mình thông qua quy trình kiểm toán, tái cấu trúc và thử nghiệm gỡ bỏ nghiêm ngặt.
Vì sao file cấu hình AI Agent luôn có xu hướng phình to và suy hao?
Hiện tượng phình to cấu hình (configuration bloat) xuất phát từ thói quen phản ứng thụ động của lập trình viên: mỗi khi agent xử lý sai một tác vụ, đi lệch khỏi quy chuẩn hoặc gặp lỗi biên dịch, họ lại thêm một quy tắc mới vào CLAUDE.md hoặc AGENTS.md. Qua nhiều tuần phát triển, tệp hướng dẫn quyết định tinh gọn ban đầu bị biến thành một "ngân hàng kiến thức" quá tải. Tệp cấu hình phình to từ ngưỡng tối ưu dưới 200 dòng lên hàng trăm, thậm chí hàng nghìn dòng, nhồi nhét các ví dụ quá dài, các mô tả kiến trúc lặp lại thông tin đã có sẵn trong README.md hay package.json, cùng hàng loạt quy tắc mang tính phòng thủ ngẫu nhiên.
Tất cả chỉ dẫn cấu hình đều có "hạn sử dụng" (half-life) gắn liền với vòng đời của mô hình và harness. Các mô hình LLM thế hệ mới liên tục cải thiện khả năng suy luận tự nhiên, trong khi các khung thực thi ngày càng cung cấp công cụ tự động chính xác hơn. Những chỉ dẫn gượng ép từng giúp mô hình đời cũ không mắc lỗi lại trở thành rào cản làm triệt tiêu tính linh hoạt của mô hình đời mới. Minh chứng thực tế từ Anthropic cho thấy khi chuyển giao sang dòng mô hình Claude 5, đội ngũ kỹ thuật đã cắt bỏ hơn 80% dung lượng system prompt của Claude Code mà không làm giảm bất kỳ điểm số nào trên các bài đánh giá lập trình nội bộ.
Dưới góc độ kiến trúc Transformer, mọi token đưa vào ngữ cảnh đều tiêu tốn một phần "ngân sách chú ý" (attention budget) hữu hạn của mô hình. Cơ chế Self-Attention tính toán mối tương tác giữa tất cả các cặp token theo độ phức tạp O(n²). Khi số lượng token trong ngữ cảnh tăng lên, khả năng bắt cặp chính xác giữa các mối liên hệ xa bị pha loãng. Hiện tượng này không chỉ đến từ độ dài chuỗi mà còn xuất phát từ hạn chế của kỹ thuật nội suy mã hóa vị trí (position encoding interpolation) và sự lệch pha với phân phối dữ liệu huấn luyện ban đầu (vốn ưu tiên các chuỗi ngắn hơn). Việc mở rộng context window không hề xóa bỏ context rot, mà tạo ra một độ dốc suy giảm hiệu năng: mô hình vẫn phản hồi nhưng độ chính xác trong việc truy xuất chi tiết tinh vi và suy luận chuỗi dài bị sụt giảm nghiêm trọng.
Bằng chứng thực nghiệm: Context file và skill thực sự giúp được gì?
Dữ liệu thực nghiệm từ ba công trình nghiên cứu độc lập năm 2026 đã chứng minh ranh giới rõ ràng về năng lực của các tệp ngữ cảnh và kỹ năng đối với agent lập trình. Nghiên cứu của Prakhar Khatri trên 288 lượt chạy cho 17 tác vụ thực tế với Claude Code và Codex chỉ ra rằng việc nạp các tệp ngữ cảnh tĩnh như CLAUDE.md hay AGENTS.md không mang lại cải thiện định lượng nào đối với tính đúng đắn (correctness) của mã nguồn. Phân tích nguyên nhân thất bại cho thấy agent thường vấp ngã ở tư duy triển khai (implementation judgment, bao gồm thiết kế tính năng, lựa chọn pattern kiến trúc và nối logic chính xác), chứ không phải do thiếu thông tin mô tả dự án dạng văn bản.
Kết quả này hoàn toàn tương thích với nghiên cứu của Brian Sam-Bodden trên SWE-bench Verified khi đánh giá tín hiệu mà agent thực sự cần để hành động. Nghiên cứu khẳng định mã nguồn thực tế chứa tín hiệu chính xác nhất: các bản tóm tắt bằng ngôn ngữ tự nhiên chỉ trả lời được 4/45 câu hỏi hành vi mã nguồn, trong khi việc truy vấn trực tiếp mã nguồn giải quyết được 27/45 câu hỏi. Hơn nữa, việc nén ngữ cảnh tập trung vào cấu trúc mã nguồn cho phép giảm dung lượng từ 94K token xuống 19K token cho mỗi sự cố mà vẫn duy trì tỷ lệ giải quyết thành công tương đương. Cả hai nghiên cứu cùng đi đến một kết luận kiến trúc: tệp ngữ cảnh không thể dạy agent tư duy lập trình, và lập trình viên nên hướng agent trực tiếp vào mã nguồn cùng quy trình thực thi thay vì bắt mô hình đọc các bản tóm tắt văn xuôi.
Dù không cải thiện tư duy triển khai, tệp ngữ cảnh vẫn giữ vai trò định hình quy trình thao tác. Trong thử nghiệm của Khatri, khi file cấu hình đưa ra cảnh báo rằng toàn bộ bộ test chạy rất chậm, Claude Code đã linh hoạt chuyển sang chạy các bộ test mục tiêu (targeted tests), giúp tiết kiệm đáng kể thời gian và ngân sách token. Ở khía cạnh đóng gói kỹ năng, nghiên cứu của Shuyan Huang và cộng sự trên 206 phiên làm việc của 13 lập trình viên cho thấy các kỹ năng cá nhân hóa (personalized skills) rút ra từ lịch sử thao tác của một cá nhân chỉ mang lại cải thiện nhỏ và thiếu ổn định. Ngược lại, các skill dùng chung (generic skills) tổng hợp quy chuẩn kỹ thuật diện rộng và chứa nhiều ví dụ cụ thể lại mang lại hiệu quả cao hơn hẳn.
4 mùi cấu hình phổ biến nhất làm suy giảm hiệu năng của agent
Khảo sát thực nghiệm trên 100 kho mã nguồn mở của Santos và cộng sự (2026) cho thấy đa số các file cấu hình agent thực tế đều vướng phải ít nhất một lỗi thiết kế nghiêm trọng (Configuration Smells). Việc nhận diện các smell này là bước đầu tiên để tiến hành dọn dẹp hệ thống:
- Lint Leakage (Rò rỉ quy tắc Lint - xuất hiện ở 62% file): Đưa các quy định định dạng mã nguồn, khoảng trắng, dấu chấm phẩy hay quy tắc linter vào file cấu hình ngôn ngữ tự nhiên. Đây là các kiểm tra mà bộ linter tự động có thể bắt và sửa chữa triệt để thông qua công cụ. Việc bắt LLM đọc và tuân thủ các quy tắc này bằng văn bản gây lãng phí ngân sách chú ý vô ích.
- Context Bloat (Phình to ngữ cảnh - xuất hiện ở 42% file): Nhồi nhét quá nhiều mô tả kiến trúc tổng quan, danh sách phụ thuộc, ví dụ dài dòng hoặc thông tin lặp lại từ
README.mdvàpackage.json. Lỗi này làm file vượt xa ngưỡng khuyến nghị 200 dòng của Anthropic, tốn chi phí token ở mọi phiên làm việc và làm suy hao khả năng tập trung của mô hình. - Skill Leakage (Rò rỉ kỹ năng - xuất hiện ở 35% file): Đưa các quy trình thực thi nhiều bước (như quy trình triển khai, các bước chuyển đổi cơ sở dữ liệu) vào file cấu hình tĩnh tải tự động. Các quy trình này lẽ ra phải được đóng gói thành Skill để chỉ tải vào ngữ cảnh khi thực sự được kích hoạt.
- Conflicting Instructions (Chỉ dẫn xung đột): Sự hiện diện của các quy tắc mâu thuẫn giữa file root
CLAUDE.md, các file chỉ dẫn con ở các thư mục nhánh, hoặc file memory tự động. Phân tích của Santos và cộng sự chỉ ra rằng mùi này cực kỳ phổ biến và thường xuyên đồng xuất hiện cùng Context Bloat và Skill Leakage trong các cây cấu hình đa tệp, khiến agent chọn quy tắc ngẫu nhiên.
| Mùi cấu hình (Configuration Smell) | Tỷ lệ xuất hiện / Tần suất | Tác hại kỹ thuật |
|---|---|---|
| Lint Leakage | 62% file | Lãng phí token ngữ cảnh cho các quy tắc định dạng mà linter tự động có thể xử lý triệt để. |
| Context Bloat | 42% file | Kéo dài thời gian suy luận, tăng chi phí token và tạo ra độ dốc suy giảm hiệu năng (context rot). |
| Skill Leakage | 35% file | Nạp bắt buộc các quy trình nhiều bước không liên quan vào ngữ cảnh ở mọi lượt giao tiếp. |
| Conflicting Instructions | Tần suất cao (đồng xuất hiện cùng Bloat & Skill Leakage) | Gây nhiễu loạn logic ra quyết định, khiến agent xử lý không nhất quán hoặc bỏ qua quy tắc hoàn toàn. |
Quy trình kiểm toán thực tế: doctor prompt-audit, dọn dẹp memory và bài test gỡ bỏ
Để duy trì hiệu năng agent ở trạng thái tinh gọn, bạn nên thực thi quy trình kiểm toán kỹ thuật định kỳ theo chu kỳ 2–4 tuần:
Sử dụng công cụ kiểm toán tự động trong REPL: Trong môi trường Claude Code (yêu cầu từ bản v2.1.283), bạn cần phân biệt rõ hai không gian lệnh. Lệnh /doctor prompt-audit được gõ trực tiếp bên trong phiên tương tác REPL của Claude Code để phân tích CLAUDE.md, AGENTS.md, các quy tắc trong .claude/rules/ và skill nhằm phát hiện chỉ dẫn viết cho mô hình cũ, lệnh không tồn tại hoặc mâu thuẫn cấu hình. Điều này hoàn toàn khác với lệnh claude doctor chạy ngoài terminal shell (Zsh/Bash), vốn chỉ kiểm tra chẩn đoán môi trường cài đặt hệ thống.
Quản lý cơ chế Auto Memory: Hệ thống tự động ghi nhớ của Claude Code hoạt động theo kiến trúc chỉ mục: tệp MEMORY.md đóng vai trò làm index (giới hạn nạp 200 dòng đầu tiên hoặc 25KB) trỏ đến các file chủ đề riêng lẻ (user_role.md, feedback_testing.md). Khi MEMORY.md vượt quá giới hạn 200 dòng hoặc 25KB, hệ thống sẽ cảnh báo yêu cầu viết lại, và toàn bộ nội dung phía sau ngưỡng này sẽ bị cắt bỏ âm thầm trong phiên làm việc tiếp theo. Do đó, việc dùng lệnh /memory trong REPL để chủ động dọn dẹp và xóa bỏ các ghi chú đã cũ là một bắt buộc chức năng để ngăn ngừa mất mát ngữ cảnh.
Bài test gỡ bỏ (Ablation / Removal Test): Tạm thời vô hiệu hóa toàn bộ skill hoặc di chuyển file CLAUDE.md ra khỏi dự án. Cho agent thực hiện công việc hoàn toàn bằng mô hình thô và khung thực thi. Thử nghiệm này giúp bạn đánh giá khách quan xem chất lượng thực tế có bị sụt giảm hay không, từ đó kiên quyết xóa bỏ những chỉ dẫn vốn chỉ tồn tại do cảm tính.
Minh họa phân tách không gian thực thi lệnh kiểm toán:
# 1. Thực thi trong Terminal Shell (Zsh/Bash) - Chẩn đoán môi trường cài đặt
$ claude doctor
# 2. Thực thi bên trong phiên tương tác Claude Code REPL - Kiểm toán cấu hình & bộ nhớ
> /doctor prompt-audit
> /memory
> /contextChiến lược tái cấu trúc: Chuyển chỉ dẫn từ văn bản sang hook, path-scoped rules và test
Khi tiến hành tái cấu trúc file cấu hình, bạn cần áp dụng ba nguyên tắc phân tách trách nhiệm kỹ thuật:
Thắt chặt quy tắc bằng Hook thay vì văn bản: Chuyển các quy tắc "bắt buộc tuyệt đối" (như phải chạy linter trước khi commit, cấm push trực tiếp lên branch main) sang PreToolUse hook hoặc cấu hình phân quyền (permissions.deny). Mô hình ngôn ngữ coi các tệp CLAUDE.md là văn bản định hướng ngữ cảnh chứ không phải lớp thực thi cấu hình cứng. Lớp thực thi cứng phải do harness đảm nhiệm.
Phân giải phạm vi bằng .claude/rules/ (Path-scoped rules): Đưa các chỉ dẫn chuyên biệt vào thư mục .claude/rules/ và sử dụng YAML frontmatter với trường paths. Các chỉ dẫn này chỉ được tải vào ngữ cảnh khi agent mở hoặc đọc các file khớp với mẫu glob (ví dụ src/api/**/*.ts), giúp tiết kiệm không gian ngữ cảnh cho các phần khác của dự án.
Đóng gói quy trình thành Skill và tối ưu Context Budget: Đưa các quy trình thực thi nhiều bước vào file SKILL.md nằm trong .claude/skills/. Mặc định, tên và mô tả của tất cả các skill sẽ tiêu tốn từ ngân sách 1% của context window (skill listing budget). Nếu một skill chỉ dùng cho quy trình kích hoạt thủ công (như deploy hay migrate), hãy thiết lập disable-model-invocation: true. Cấu hình này sẽ loại bỏ hoàn toàn phần mô tả của skill khỏi prompt khởi động, giải phóng dung lượng token cho mọi lượt giao tiếp trong phiên.
Ví dụ về cấu hình path-scoped rule đặt tại .claude/rules/api-validation.md:
---
paths:
- "src/api/**/*.ts"
---
# Quy tắc phát triển API
- Mọi API handler phải thực hiện xác thực đầu vào bằng schema Zod
- Sử dụng cấu trúc phản hồi lỗi chuẩn theo định dạng dự án
- Bổ sung comment OpenAPI cho các endpoint mớiHãy để mỗi dòng chỉ dẫn tự chứng minh giá trị
Trong kỹ thuật hệ thống AI hiện đại, ngữ cảnh là một tài nguyên hữu hạn và đắt đỏ. Việc duy trì một file cấu hình cồng cềnh không giúp agent trở nên thông minh hơn, mà chỉ làm gia tăng chi phí, kéo dài độ trễ và làm suy hao khả năng tập trung suy luận của mô hình.
Với tư duy của một kỹ sư hệ thống, bạn hãy dừng việc lưu giữ cấu hình do thói quen hay nỗi sợ mơ hồ. Mọi dòng quy tắc, lệnh hay skill xuất hiện trong repository phải liên tục tự chứng minh giá trị qua các đợt kiểm toán định kỳ. Hãy bắt đầu ngay hôm nay bằng việc chạy lệnh kiểm toán và cắt tỉa các file CLAUDE.md và AGENTS.md trong dự án của bạn về dưới ngưỡng 200 dòng.
Tài liệu tham khảo
- Audit your Agent files — Addy Osmani
- Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents — Santos et al. (arXiv:2606.15828)
- Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories — Prakhar Khatri (arXiv:2607.27250)
- Do Personalized Skills Help Coding Agents? An Empirical Study of Developer Interaction Histories — Shuyan Huang et al. (arXiv:2608.10319)
- What Context Does a Coding Agent Actually Need to Act? — Brian Sam-Bodden (arXiv:2607.09691)
- Claude Code: How Claude remembers your project — Anthropic
- Claude Code: Extend Claude with skills — Anthropic
- Effective Context Engineering for AI Agents — Anthropic