blog
Cắt AGENTS.md xuống dưới 20k ký tự: bẫy theo vùng code chuyển sang .claude/rules
AGENTS.md của repo này giảm từ 21.066 xuống 15.562 ký tự trong 1 commit, không sửa chữ luật nào. Bẫy theo vùng code dời sang .claude/rules có paths, chỉ nạp khi đụng đúng file, kèm cái giá phải trả.
- Ngày đăng
AGENTS.md của repo này giảm từ 21.066 xuống 15.562 ký tự trong 1 commit, không sửa chữ luật nào. Phần bị cắt không bị xoá: nó dời sang .claude/rules/*.md có paths:, nên chỉ vào context khi phiên đụng đúng vùng code mà cái bẫy đó nói tới.
Vì sao cắt AGENTS.md: file luật dài tốn context mỗi turn
Dòng đầu của CLAUDE.md là @AGENTS.md, nên cả file vào context ngay khi mở phiên, kể cả lúc tôi chỉ sửa một câu trong bài blog. Bẫy performance của PSI, bẫy hydration và lệnh deploy nằm chung một chỗ.
Giá thứ nhất là tiền. Bài về subagent đo được rằng mỗi turn subagent đọc lại toàn bộ context khởi động, và phần đọc từ cache tính 0,1 lần giá input. Rẻ hơn giá gốc, nhưng nhân với số turn thì một file không liên quan tới việc đang làm vẫn tốn.
Giá thứ hai là độ tuân theo. Docs Claude Code ghi: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Một nguyên tắc khác của repo này đi cùng hướng, ở chỗ CLAUDE.md giải thích vì sao tắt TDD: một luật bị phớt lờ dạy rằng phần còn lại của file cũng tuỳ chọn. Chưa có số đo mức tuân thủ trước và sau commit này, nên phần này dựa vào docs, không dựa vào số đo.
Dời nguyên văn 4 nhóm bẫy sang rule và docs
Message của commit ghi "Move verbatim, no rule text changed". Bẫy nào chỉ đúng khi đụng một vùng code thì vào rule có paths: của vùng đó. Thứ cần tra lệnh chứ không phải luật thì vào docs/.
| Nhóm bẫy | Đích | Nạp khi |
|---|---|---|
| PSI: critical CSS, font và Lantern, màn hình đầu, ảnh | .claude/rules/performance.md (file mới) | đụng components/**, styles/**, pages/_document.js, lib/image-loader.js... |
| SEO build: og:image, sitemap, robots.txt, RSS; quy ước song ngữ; từ khoá | .claude/rules/content.md | content/**, thêm public/robots.txt, components/Seo.jsx, lib/generate-rss.js, lib/translations.js |
| Hydration #418 | .claude/rules/frontend.md | components/**, layouts/**, styles/**... |
| Lệnh GA4, Search Console, PSI | docs/operations.md | không tự nạp, chỉ khi mở file |
Bẫy og:image nhắc tới components/Seo.jsx, một file nằm ngoài content/, nên paths: của content.md được mở rộng thêm file đó. Frontmatter của rule mới:
---
paths: ["components/**", "layouts/**", "styles/**", "pages/_app.js", "pages/_document.js", "next.config.js", "lib/image-loader.js", "scripts/inline-critical-css.js", "scripts/resize-screenshots.js", "public/screenshots/**"]
---
AGENTS.md giữ đúng 1 dòng trỏ cho mỗi nhóm, để người đọc và agent không có cơ chế paths: biết là có chỗ để tra:
- **Bẫy hiệu năng PSI** (critical CSS, font và Lantern, màn hình đầu không chờ JS, ảnh và static
export): `.claude/rules/performance.md`.
Đo bằng lệnh: từ 23.551 xuống 17.282 byte
git show b89dd27:AGENTS.md | wc -c # sau khi cắt
git show b89dd27^:AGENTS.md | wc -c # ngay trước khi cắt
Lệnh đầu in 17282, lệnh sau in 23551. Đọc từ git thì số không trôi khi AGENTS.md đổi tiếp. Đếm ký tự thì dùng wc -m với locale UTF-8, ví dụ git show b89dd27:AGENTS.md | LC_ALL=en_US.UTF-8 wc -m. Shell không đặt locale thì wc -m đếm byte: lần đầu tôi đo ra 17282 ở cả hai cột.
| Trước | Sau | |
|---|---|---|
Byte (wc -c) | 23.551 | 17.282 |
Ký tự (wc -m, UTF-8) | 21.066 | 15.562 |
Dòng (wc -l) | 258 | 200 |
Tiếng Việt có dấu nên byte lớn hơn ký tự. Đếm kiểu nào thì trước vẫn vượt 20k và sau vẫn dưới 20k.
Cái giá của rule nạp theo vùng
Vùng chồng nhau. Một file thuộc nhiều rule thì nạp cả đống:
| Đụng | Rule được nạp | Tổng byte |
|---|---|---|
components/** | frontend.md, performance.md, nginx.md | 10.782 |
content/** | content.md, nginx.md | 12.444 |
nginx.md có mặt ở cả hai dòng, dù AGENTS.md ghi nó mô tả cấu hình nginx cũ và chỉ còn để tham khảo. Đó là phần chưa dọn. Số byte đo ở commit e2560bc bằng git show e2560bc:.claude/rules/<tên>.md | wc -c.
Agent không có paths:. Bảng "Rule nạp theo vùng code" nằm trong CLAUDE.md, phần chỉ Claude Code dùng được. AGENTS.md là file chung cho Claude Code, Codex và Gemini, và mục review của chính file đó yêu cầu Codex review lại output sau khi xong việc. Codex đọc AGENTS.md, chỉ thấy dòng trỏ, và không thấy bẫy nào nếu không tự mở file.
2 bản của cùng một danh sách path. Commit dời bẫy đổi paths: của content.md. Bảng trong CLAUDE.md lệch với frontmatter 2 phút 21 giây, cho tới khi commit sau sửa (diff rút gọn):
-| `.claude/rules/content.md` | `content/**`, `scripts/**`, `public/covers/**` |
+| `.claude/rules/content.md` | `content/**`, `scripts/**`, `public/covers/**`, `public/robots.txt`, ... |
+| `.claude/rules/performance.md` | `components/**`, `layouts/**`, `styles/**`, `pages/_app.js`, ... |
Bảng chỉ để người đọc nhanh, frontmatter mới là thứ có hiệu lực, nên mỗi lần sửa paths: phải sửa luôn bảng.
Dời nguyên văn để lại chỗ lặp. content.md giờ có 2 đoạn nói về bài song ngữ: mục "Song ngữ" và bullet vừa dời vào. Nguyên văn thì an toàn, nhưng chưa phải bản gọn.
Tham chiếu cũ. Commit sửa luôn 2 skill vì chúng trỏ tới AGENTS.md §4. Dời mục nào thì tìm những chỗ trỏ vào mục đó:
git grep -n "AGENTS.md. §"
Việc chưa làm sau commit này
Mốc 20k là mốc của repo này. Docs nói dưới 200 dòng mỗi file CLAUDE.md, trong khi sau commit cắt AGENTS.md có 200 dòng và CLAUDE.md có 80 dòng, nên theo chữ của docs vẫn chưa đạt.
Việc còn lại: bỏ paths: của nginx.md hoặc gỡ file, đo mức tuân thủ trước và sau bằng task cố định, và nếu cần đi tiếp thì gộp 2 đoạn song ngữ trong content.md.
Bài viết liên quan
tất cả bài viết →- Gate nguồn cứng check:sources: chặn build khi bài có số chưa khai nguồnAgent viết bài thì số đúng lúc viết vẫn trôi hoặc bị bịa. check:sources chặn prebuild khi bài thiếu sidecar .sources.yml hoặc còn số dạng dữ liệu chưa khai. Cách nó chạy và 4 chỗ nó không bắt được.đọc tiếp →
- Template Fable 5.2 cho agent team: đo trên log của mình trước khi chép promptMột template prompt "Coding Agent Team" cho Fable 5.2 lan truyền trên X, khoảng 80% đã có sẵn trong setup của tôi. Phần còn lại tôi đo bằng ledger và report thật rồi mới quyết, và lỗi đáng sợ nhất tìm được lại nằm ở bảng giá, không ở prompt.đọc tiếp →
- Job định kỳ báo qua Telegram: vì sao tin quan trọng nhất lại mất im lặngSoát lại các job launchd và công cụ điều hành của mình theo 6 nguyên tắc tự động hoá agent của Anthropic, tôi thấy cùng một lỗi lặp ở mọi script: hàm gửi tin luôn trả thành công, rồi trạng thái tiến lên dù tin chưa tới. Đây là cách sửa, cách test nhánh lỗi, và heartbeat để biết job còn chạy.đọc tiếp →
- Tối ưu subagent Claude Code: cắt 40-78% chi phí mỗi lượt gọi implementerSubagent đắt vì mỗi lần khởi động nạp hàng chục nghìn token luật và skill, rồi lặp lại qua hàng chục turn. Tôi đo bằng transcript, thay bằng agent riêng, rồi đối chiếu qua 3 lượt chạy subagent-driven-development thật.đọc tiếp →