vi

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
Claude CodeAGENTS.mdRulesContext window
An AGENTS.md block on the left with 4 solid lines kept and 3 dashed lines moved out, 3 connectors to 3 rule files on the right, the performance.md file filled with the accent color

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 groupDestinationLoads 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.mdcontent/**, plus public/robots.txt, components/Seo.jsx, lib/generate-rss.js, lib/translations.js
Hydration #418.claude/rules/frontend.mdcomponents/**, layouts/**, styles/**...
GA4, Search Console, PSI commandsdocs/operations.mdnothing 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:

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 keeps exactly 1 pointer line per group, so a reader or an agent without the paths: mechanism knows where to look:

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`.

Measure with commands: 23,551 down to 17,282 bytes

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

BeforeAfter
Bytes (wc -c)23,55117,282
Characters (wc -m, UTF-8)21,06615,562
Lines (wc -l)258200

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:

TouchingRules loadedTotal bytes
components/**frontend.md, performance.md, nginx.md10,782
content/**content.md, nginx.md12,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):

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`, ... |

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:

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