The one test that decides whether a line earns a place in an always-loaded instruction file.
Why this, for you: this is the principle behind your skill's CE-4 check, and the
single most common source of instruction-file bloat. It governs every line you write in a CLAUDE.md /
AGENTS.md — priorities #1, #2 and #3 at once. We'll sharpen CE-4 with it afterwards.
Instruction files load on every interaction — every line is a recurring tax paid before
the agent reads a single file of the actual task. So inclusion is a resource-allocation decision, not a documentation one.
The test for inclusion: can the agent discover this itself with its read / grep / glob tools?
If yes, it does not belong in the instruction file — let the agent find it. Only
non-discoverable context earns a place.
+20%
A controlled eval found human-authored context files raise inference cost over 20% when they
include structural overviews — with no improvement in task success. Agents given high-level
structure explore more broadly, not more precisely
(Gloaguen et al., "Evaluating AGENTS.md," 2026).
The two buckets
✗ Discoverable — leave it out
Directory trees, file structure
API signatures, function params
Dependency versions (lockfiles)
Code conventions visible in any file
Config (tsconfig, .eslintrc)
Test patterns readable from tests
✓ Non-discoverable — earns its place
Why this approach beat alternatives
Constraints & gotchas not in code
Domain rules / business terminology
Conventions present but never stated
Out-of-band integrations
The audit-log side-effect you must trigger
The failure mode with discoverable content isn't just cost — it's a second source of truth that goes
stale. A directory tree in the file is wrong within a sprint; the agent then follows the stale description
instead of the real codebase. Worse, per the Instruction Compliance Ceiling: aggregate instruction load —
not file count — drives degradation, so every discoverable line you add makes the agent less likely to
follow your real rules.
The pointer is the escape hatch
Discoverable content that benefits from direction doesn't need duplication — it needs a pointer. A path,
not a copy:
- ## Project Structure- src/api (handlers) · src/repos (db layer) · src/services …- getUserById(id: string): Promise<User> # drifts the moment code changes+ Use the repository pattern in `src/repos/`. # a pointer — the agent reads the rest# keep the architectural *why* the agent can't infer:+ The `*Service` suffix is reserved for classes that make outbound HTTP calls.
↪ Your win: run the three-question filter on every line
Can the agent discover this by reading the codebase?
If yes → delete it (add a pointer if direction helps).
If no → keep it. Decisions, constraints, domain context survive the filter.
Litmus: "Would this line still be true and useful if the codebase changed next week?" Non-discoverable context survives a refactor; a directory tree doesn't.
When it backfires — the filter assumes the agent has exploration tools and a stable tree.
A tool-less agent makes structure non-discoverable to it; in a giant monorepo a scoped pointer
(see services/payments/) beats forcing broad traversal; in a high-churn repo, keep any structural
pointer in a separate, frequently-updated file so the main instruction file stays stable.
Retrieval practice — recall, don't peek
Question 1The inclusion test asks whether the agent can…
Question 2Which belongs in the codebase, not the instruction file?
Question 3Which earns a place in the instruction file?
Question 4Adding a structural overview to a context file tends to…
Question 5 · spaced recall from Lesson 04About to run a 30-file exploration you won't need again. Best move?
Ask me anything. Want to run the three-question filter against your real content/CLAUDE.md
and see how much is discoverable? Curious where claudeMdExcludes fits for monorepos, or how this connects
to the Instruction Compliance Ceiling? Say so — then we sharpen CE-4 in the skill together.