Remote Frog

Ever notice your AI agent giving weird answers or making silly mistakes? It might be drowning in too much context. Like that kid/friend who asks for advice but dumps their entire past month story first—you end up more confused than helpful.

TL;DR

Don’t bury your agent under the whole enclyclopedia. Let the agent find and use strictly what it needs, to avoid getting distracted. The pattern for progressive disclosure in mcd files is simple:

1. One lightweight index file (alwaysApply: true) with commands, structure, and pointers
2. Specialized files (alwaysApply: false) with detailed rules, loaded via globs
3. Start monolithic, split when you feel the pain

Progressive disclosure is a design principle where you show AI agents only the information they need at a given moment, revealing details as they become relevant. In Cursor’s rules system, this means structuring your .cursor/rules/ files so that lightweight, essential rules are always loaded, while detailed documentation loads on demand—say, only when working with specific file types.

The Problem: Context Overload

When you have a large codebase (multiple projects, SQL transformations, complex schemas…), loading all documentation into every AI conversation wastes tokens. And no matter if this sounds counterintuitive, too much context can actually backfire. It slows the model down, buries key details in noise, and forces the model to guess what matters. Conclusion: A short, focused question with just the relevant info usually gets a better answer than a long, vague one with everything attached “just in case.”

Example: An agent working on a simple SQL query change doesn’t need detailed schema annotation syntax—unless there’s a schema change. In a bank, an agent discovering the best investment product for a client type don’t likely need to take into account mortgages information.

The Solution: Smart Rule Loading

The key behind progressive disclosure in rules are index files that act as navigation aids, to organize and slice documentation dumps. Your always-loaded index should answer three questions:

• “What can I do here?” (commands)
• “What are the critical rules?” (style, conventions)
• “Where do I find details?” (pointers to specialized files)

Everything else goes in specialized files with appropriate globs.

My approach: start with a monolithic rule file. Ask Cursor to split it when you start suspecting agents are getting information they don’t need for their current task. You’ll feel it… or you can even ask the AI. Don’t discard asking.

A Real-World Example

Here’s how progressive disclosure works in practice. Let’s say you have a data transformation project with Scala code, SQL, and schema definitions. Your .cursor/rules/ structure might look like this:

Always Loaded (Index File)

--- 
description: Project system index - Points to specialized rules globs: myproject/**/* 
alwaysApply: true 
--- 

# My Project System 

⚠️ **This file is an index. Core rules have been split for efficiency.** 

## Quick Reference 

**Detailed documentation** (loaded on-demand): 

- **Schemas & Annotations**: `.cursor/rules/myproject.schemas.mdc` 
- **Testing**: `.cursor/rules/myproject.testing.mdc` 
- **Transformations**: `.cursor/rules/myproject.transformations.mdc` 

--- 

## Essential Quick Commands 
```
...
``` 

## File Structure 
``` 
myproject/ 
├── schema/ # Schema definitions 
├── src/main/ 
│ ├── transforms/ # Data transformations 
│ └── validations/ # Validation rules 
└── src/test/ 
└── specs/ # Test specifications 
``` 

## Code Style Rules 

**ASCII-only in code files:** 
- NEVER use non-ASCII characters (→, •, é, ñ, etc.) in code files
- Non-ASCII allowed ONLY in `.md` documentation
- Use ASCII alternatives: `->` instead of `→`, `-` instead of `•` --- 

For detailed information, Cursor will automatically load the relevant specialized rule file based on the files you're working with.

Size: small. Just enough to get started.

Loaded On-Demand (Specialized Files)

--- 
description: Schema definitions and annotations (on-demand)
globs: 
     - myproject/**/schema/*.avdl 
     - myproject/**/*.avdl 
alwaysApply: false 

--- 
# Schema Definitions 
## Core Concept Each `record` defines a table... 
[detailed schema documentation here - could be 100+/200+ lines]

And you’ll also need the corresponding files for:

• .cursor/rules/myproject.testing.mdc — test syntax, validation rules (~160 lines)
• .cursor/rules/myproject.transformations.mdc — patterns, partitioning strategies (~90 lines)

All with alwaysApply: false and the adequate globs.

How It Works in Practice

Using the last example where I’ve applied progressive disclosure:

Before (monolithic):

• I had a 400+ line rule file, always loaded, regardless of task
• I use a multi-agent setup, where every agent saw schema annotation details when writing SQL / agent sees transformation partitioning rules when writing tests

After applying progressive disclosure, I had 4 files:

├── myproject.mdc (59 lines, always loaded) 
├── myproject.schemas.mdc (104 lines, schema files only) 
├── myproject.testing.mdc (156 lines, testing only) 
└── myproject.transformations.mdc (93 lines, SQL only)

The math:

• Instead of always loading everything (400 lines)
• Agent editing SQL? Load ~152 lines (index + transformations)
• Editing schema? Load ~163 lines (index + schemas)
• Editing tests? Load ~215 lines (index + testing)

Personal Rules, Same Pattern

This approach isn’t limited to shared project rules. I use the same structure in my .cursor/local/rules/ directory for personal workflows. For example, say I have a PR documentation file that one of my multi-agents (the documenter) uses to create concise but complete PR descriptions that writes into a local/docs folder :

--- 
description: PR summary and documentation formatting
globs: 
     - myproject/**/*.md 
     - myproject/.cursor/local/docs/**/* 
alwaysApply: false 
---

The idea is this file only loads when needed. The agent gets exactly what it needs to write good PR descriptions, just when it needs it and without carrying the weight of schema syntax or test patterns it’ll never use.

Why This Matters

1. Faster responses — Less context = faster token processing
2. You don’t run out of tokens 😅 Remember, all these tokens are used on each request in the chat window. You’re multiplying savings by the number of questions!
3. More relevant guidance — Agent sees rules for the task at hand, not everything
4. Easier maintenance — Update schema rules without touching test rules
5. Better organization — Clear separation
6. Scalable — Add new rule files without bloating the always-loaded index

RECAP/Corollary

Progressive disclosure is really about respect—for the AI’s attention (yes, that’s a thing now), for your token budget, and for your own sanity when maintaining rules. Start simple. Split when it hurts. Trust the globs.

And if you’re wondering whether this is overkill for your project… it probably isn’t. The moment you catch yourself thinking “why is the agent suggesting test patterns when I’m just fixing a typo in SQL?”—that’s your signal.