en

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
Claude CodeAGENTS.mdRulesContext window
Khối AGENTS.md bên trái có 4 dòng giữ lại và 3 dòng nét đứt đã dời đi, 3 đường nối sang 3 file rule bên phải, file performance.md tô màu accent

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ĐíchNạ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.mdcontent/**, thêm public/robots.txt, components/Seo.jsx, lib/generate-rss.js, lib/translations.js
Hydration #418.claude/rules/frontend.mdcomponents/**, layouts/**, styles/**...
Lệnh GA4, Search Console, PSIdocs/operations.mdkhô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:

yaml
---
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:

md
- **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

bash
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ướcSau
Byte (wc -c)23.55117.282
Ký tự (wc -m, UTF-8)21.06615.562
Dòng (wc -l)258200

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:

ĐụngRule được nạpTổng byte
components/**frontend.md, performance.md, nginx.md10.782
content/**content.md, nginx.md12.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):

diff
-| `.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 đó:

bash
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 →