blog
Trim AGENTS.md under 20k chars: move area traps to .claude/rules
This repo cut AGENTS.md from 21,066 to 15,562 characters in 1 commit without changing any rule text. Area-specific traps moved to .claude/rules with paths, loaded only when the work touches those files, and the move has costs.
- Published
This repo cut AGENTS.md from 21,066 to 15,562 characters in 1 commit without changing any rule text. The cut part was not deleted: it moved to .claude/rules/*.md files with paths:, so it enters context only when a session touches the code area the trap is about.
Why trim AGENTS.md: a long rules file costs context on every turn
The first line of CLAUDE.md is @AGENTS.md, so the whole file lands in context when a session opens, even when I only fix a sentence in a blog post. The PSI performance traps, the hydration trap and the deploy commands all sit in the same place.
The first price is money. The subagent post measured that a subagent re-reads its whole startup context every turn, and the part read from cache costs 0.1 times the input price. That is below the base price, but multiplied by the number of turns, a file unrelated to the current job still adds up.
The second price is adherence. The Claude Code docs say: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Another principle in this repo points the same way, in the place where CLAUDE.md explains why TDD is turned off: a rule that gets ignored teaches that the rest of the file is optional. There is no measurement of adherence before and after this commit, so this part rests on the docs, not on my own numbers.
Move 4 groups of traps verbatim into rules and docs
The commit message says "Move verbatim, no rule text changed". A trap that only matters in 1 code area goes into a rule with that area's paths:. Something you look up like a command, not a rule, goes into docs/.
| Trap group | Destination | Loads when touching |
|---|---|---|
| PSI: critical CSS, fonts and Lantern, first screen, images | .claude/rules/performance.md (new file) | components/**, styles/**, pages/_document.js, lib/image-loader.js... |
| SEO build: og:image, sitemap, robots.txt, RSS; bilingual conventions; keywords | .claude/rules/content.md | content/**, plus public/robots.txt, components/Seo.jsx, lib/generate-rss.js, lib/translations.js |
| Hydration #418 | .claude/rules/frontend.md | components/**, layouts/**, styles/**... |
| GA4, Search Console, PSI commands | docs/operations.md | nothing auto-loads it, you open the file |
The og:image trap mentions components/Seo.jsx, a file outside content/, so the paths: of content.md was extended with that file. Frontmatter of the new rule:
---
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 keeps exactly 1 pointer line per group, so a reader or an agent without the paths: mechanism knows where to look:
- **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`.
Measure with commands: 23,551 down to 17,282 bytes
git show b89dd27:AGENTS.md | wc -c # after the trim
git show b89dd27^:AGENTS.md | wc -c # right before the trim
The first command prints 17282 and the second prints 23551. Reading from git keeps the numbers stable when AGENTS.md changes later. To count characters use wc -m with a UTF-8 locale, for example git show b89dd27:AGENTS.md | LC_ALL=en_US.UTF-8 wc -m. In a shell with no locale set, wc -m counts bytes: my first measurement printed 17282 in both character columns.
| Before | After | |
|---|---|---|
Bytes (wc -c) | 23,551 | 17,282 |
Characters (wc -m, UTF-8) | 21,066 | 15,562 |
Lines (wc -l) | 258 | 200 |
Vietnamese diacritics make bytes larger than characters. Counted either way, the file was over 20k before and is under 20k after.
What path-scoped rules cost
Overlapping areas. A file that belongs to several rules loads all of them:
| Touching | Rules loaded | Total bytes |
|---|---|---|
components/** | frontend.md, performance.md, nginx.md | 10,782 |
content/** | content.md, nginx.md | 12,444 |
nginx.md appears in both rows, although AGENTS.md says it describes an old nginx setup and is kept for reference only. That is cleanup still to do. The byte counts come from commit e2560bc, using git show e2560bc:.claude/rules/<name>.md | wc -c.
Agents without paths:. The "Rule nạp theo vùng code" table (rules loaded by code area) lives in CLAUDE.md, in the part only Claude Code can use. AGENTS.md is the shared file for Claude Code, Codex and Gemini, and its own review section asks Codex to review the output after the work is done. Codex reads AGENTS.md, sees only the pointer line, and sees none of the traps unless it opens the file itself.
2 copies of the same path list. The commit that moved the traps changed the paths: of content.md. The table in CLAUDE.md was out of sync with the frontmatter for 2 minutes 21 seconds, until the next commit fixed it (diff shortened):
-| `.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`, ... |
The table is for quick reading and the frontmatter is what takes effect, so every paths: edit has to update the table too.
A verbatim move leaves repetition. content.md now has 2 passages about bilingual posts: the "Song ngữ" section and the bullet that moved in. Verbatim is safe, but it is not the tightened version.
Old references. The commit also fixed 2 skills that pointed at AGENTS.md §4. When you move a section, look for what points into it:
git grep -n "AGENTS.md. §"
What is still open after this commit
The 20k mark is this repo's own. The docs say under 200 lines per CLAUDE.md file, while after the trim AGENTS.md has 200 lines and CLAUDE.md has 80, so by the letter of the docs it is not there yet.
What remains: drop the paths: of nginx.md or remove the file, measure adherence before and after with a fixed task, and, if going further, merge the 2 bilingual passages in content.md.
Related posts
all posts →- A hard source gate for agent-written posts: check:sources blocks the buildWhen an agent writes posts, numbers that were right at writing time still drift or get invented. check:sources fails prebuild when a post has no .sources.yml sidecar or has data-shaped numbers it never declared. How it runs, and 4 gaps it misses.read more →
- A Fable 5.2 prompt template for agent teams: measure on your own logs before copyingA "Coding Agent Team" Fable 5.2 prompt template went around on X, and about 80% of it already existed in my setup. I measured the rest against real ledgers and reports before deciding, and the worst bug I found sat in a pricing table, not in the prompt.read more →
- Scheduled jobs that alert through Telegram: why the most important message gets lost silentlyI audited my launchd jobs and my ops tool against 6 agent-automation principles from Anthropic and found the same bug in every script: the send function always succeeds, then state moves forward even though the message never arrived. Here is the fix, how to test the failure branch, and a heartbeat to know a job is still running.read more →
- Claude Code subagent cost: cut 40-78% per implementer callA Claude Code subagent loads tens of thousands of tokens of rules and skills at every start, then repeats them over dozens of turns. I measured it from transcripts, replaced it with a dedicated agent, and compared 3 real subagent-driven-development runs.read more →