Progressive disclosure is good for reducing context usage but it also reduces the benefit of token caching. It might be a toss-up, given this research result.

Those are different axes - quality vs money.

Progressive disclosure is invaluable because it reduces context rot. Every single token in context influences future ones and degrades quality.

I'm also not sure how it reduces the benefit of token caching. They're still going to be cached, just later on.

Agree that progressive disclosure is fantastic, but

> (e.g. for DB schema related topics, see such and such a file).

Rather than doing this, put another AGENTS.md file in a DB-related subfolder. It will be automatically pulled into context when the agent reads any files in the file. This is supported out of the box by any agent worth its salt, including OpenCode and CC.

IMO static instructions referring an LLM to other files are an anti-pattern, at least with current models. This is a flaw of the skills spec, which refers to creating a "references" folder and such. I think initial skills demos from Anthropic also showed this. This doesn't work.

This is probably the best comment in the thread. I've totally forgotten about nested AGENTS.md files, gonna try implementation today.

If you have for example a monorepo, then you'll probably want a super lean top-level one - could be <15 lines - and then one per app. In those, only stuff that applies to the app as a whole. Then feature-specific context can be put at the level of the feature - hopefully your codebase is structured by domain rather than layer! The feature-level ones too, IMO, should usually be <15 lines. I just checked one of ours, it's 80 (GPT-5) tokens. It's basically answering potential "is this intentional?" questions - things that an LLM (or fresh human) can't possibly know the answer to because they're product decisions that aren't expressed in code. Tribal knowledge that would be in a doc somewhere. For 99% of decisions it's not needed, but there's that 1% where we've made a choice that goes against the cookie-cutter grain. If we don't put that in an AGENTS file, then every single time it's relevant there's a good chance it will make a wrong assumption. Or sometimes, a certain mechanic is inferable from the code, but it would take 10 different file reads to figure out something that is core to how the feature works, and takes 2 sentences to explain. Then it just saves a whole lot of time.

It does depend on the domain. If you're developing the logic for a game, you'll need more of them and they'll be longer.

Another advantage of this split is that because they're pulled into context at just the right time, the attention layer generally does a better job of putting sufficient importance on it during that part of the task, compared to if it were in the project-level AGENTS file that was loaded at the very top of the conversation.

> This is supported out of the box by any agent worth its salt, including OpenCode and CC.

I thought Claude Code didn't support AGENTS.md? At least according to this open issue[0], it's still unsupported and has to be symlinked to CLAUDE.md to be automatically picked up.

[0] https://github.com/anthropics/claude-code/issues/6235

You're right, for CC it's "nested CLAUDE.md files". The support I meant was about the "automatic inclusion in context upon sibling-or-child file touch" feature, rather than the name of the file.

Fair, I was hoping there was a feature that I was missing. Minor papercut to have to include harness-specific files/symlinks in your repo but it's probably a temporary state until the tools and usage patterns are more settled.

Nah, this is intentional by Anthropic, out of the top 20 coding agents 19 support AGENTS.md (fake numbers but I've seen someone else go through them). It's just a dumb IE6-style strategy.