Context management
Use progressive disclosure to make the entry document a table of contents, then keep building layered indexes so it gets revealed a piece at a time. As OpenAI says in this article, AGENTS.md/CLAUDE.md should be a map, not a comprehensive manual. The context window is only part of it. What matters is attention. Context that runs too long only rots and scatters attention, and ends up less effective than a finely scoped one.
We tried the “one large AGENTS.md(opens in a new window)” approach. Predictably, it failed:
- Context is a scarce resource. A huge instruction file crowds out the task, the code and the relevant docs, so the agent either misses the critical constraints or starts optimizing for the wrong ones.
- Too much guidance stops working. When everything is “important”, nothing is. The agent ends up pattern matching locally instead of navigating deliberately.
- It rots immediately. A sprawling manual turns into a graveyard of stale rules. The agent can’t tell what still holds, and once humans stop maintaining it, the file quietly becomes an attractive source of trouble.
- It’s hard to verify. A single blob doesn’t suit mechanical checks (coverage, freshness, ownership, cross-links), so drift is unavoidable.
Funny to say, but the old line holds: having all of it equals having none of it. Building a portable docs/ is the right way to go, the same constraint as SKLIIS.md, where the entry file shouldn’t run past five hundred lines and can be shorter still.
Translation note. I wrote this in Chinese. This English version is an LLM translation, so the wording is not mine even though the thinking is. Original: 上下文管理.