Signal

The INDEX.md Pattern - Structure a Vault So an Agent Navigates It Fast

3 min read

TL;DR

An agent does not think in categories the way you do. A vault organized by content type (articles, research, assets) forces the agent to search everywhere every time, opening wrong and archived files before finding the current one. Reorganizing by concern, numbering folders for read order, and dropping an INDEX.md map at the root of each major folder took the slowest task from 2 minutes to 26 seconds with no change to the model. The scaffolding around the agent does more work than the agent’s own capability.

The fix (three rules that work together)

  1. INDEX.md at the root of each MAJOR folder. A map listing every subfolder and canonical file, plus a short “where to start” section. The agent reads it first and knows what it is working with before touching anything, a soft approval gate. Keep it lean: only subfolders and canonical files plus a few starting points (about 20 lines). Listing every file (40 lines) is its own overhead; too short (15 lines) and the agent still asks questions.
  2. One concern per folder, not one content type. Brand work stays with brand work, strategy with strategy, so the agent never crosses boundaries chasing context that does not belong there.
  3. Number folders and files for explicit read order. 01. is read before 02., so the agent does not guess or rely on alphabetical sorting. Numbers only need to be directional, not perfect.

Put archived material in its own NN.Archived/ folder and tell the agent in the INDEX.md not to look there unless you ask for historical context. That separation is what keeps active folders fast.

Diagnostic test (five minutes)

  1. Pick the three tasks your agent handles most often. Time each and count how many files it opens before the right one, plus how often it picks wrong or stops to ask.
  2. Any task over 30 seconds, or opening 3+ wrong files, points to a broken folder behind it.
  3. Fix the single worst offender: write an INDEX.md for that folder, re-run the task. Under 30 seconds means it worked. Apply the pattern to the next broken folder.

Failure modes to avoid

  • INDEX.md in every subfolder. Too many maps and the agent reads indexes instead of working. Keep them only at major folders with enough subfolders to need one.
  • Building structure before the agent shows confusion. Add structure only when the agent gets lost, and only enough to fix that specific problem. Smallest interface that works.
  • Nesting structure inside structure. Depth is the enemy of fast lookup. A five-level hierarchy forces the agent to parse multiple indexes and numbering sequences. Collapse back to flat subfolders.
  • Over-numbering. Past 10 to 12 items at one level, numbers become arbitrary. Keep top-level categories below that threshold.
  • Renaming folders. Any INDEX.md reference to the old name breaks. Set names once and leave them; a slightly awkward name is cheaper than a broken reference.
  • Sync drift. If a stale copy of a file lingers on another device or server, the agent loads it as the source of truth. A sync problem, but it surfaces inside the folder system.

Best fit: content-heavy and planning-heavy workflows. Pure code or data-heavy setups may need different principles.

Key quotes

The structure around your agent does more work than the agent’s own capability.

Capability is cheap when the scaffolding around it is broken. Build the scaffolding, and the capability takes care of itself.

Depth is the enemy of fast file lookup, and most reorganizations add depth thinking it is precision.

ai-second-brain-obsidian · claude-workflows-that-run-unattended

Graph View

Backlinks