You hand Claude Code a ticket: build the confirmation modal for the delete-account flow. Straightforward work. Two minutes of thinking, maybe fifty lines of code.

Before it writes any of them, the agent goes spelunking through your repo.

It opens package.json. It finds @acme/ui. It globs the dist directory and sees forty-odd files. It reads the barrel export to figure out what the library actually ships. Then it starts opening component files, one by one, trying to piece together a mental model of a system you spent eighteen months building. Eventually it picks something, writes the feature, and hands you a PR.

That PR uses the wrong component.

This is the shape of almost every agent session that touches an unfamiliar design system. I want to walk through exactly what's happening — and why the agent, despite doing reasonable work, is nearly guaranteed to arrive at a guess.

The walkthrough

Here's a realistic trace. The agent has Read, Glob, and Grep. It has the ticket. It has no prior knowledge of your library.

Step 1. It reads package.json and spots @acme/ui in the dependencies.

Step 2. It globs node_modules/@acme/ui/dist — or src/ui/, depending on where your library lives — and gets back a list of forty files. That list is now in the context window.

Step 3. It reads the barrel index.ts to learn what's exported. Good instinct. This is how a new engineer would orient themselves too.

Step 4. The barrel reveals a problem. The library exports Dialog, Modal, AlertDialog, and ConfirmDialog. Four things that all sound like they might do what the ticket asks for.

Step 5. The agent opens all four files. It reads the props. It reads the TypeScript signatures. It notices that Dialog is the lowest-level primitive, Modal wraps Dialog with a portal, AlertDialog adds a specific focus-trap behavior, and ConfirmDialog is a convenience wrapper with an opinionated button layout.

Step 6. If you have Storybook stories colocated with your components — and if the agent happens to find them — it reads a few of those too. Another five to ten files worth of context.

Step 7. It picks one. Usually Dialog, because it's the most generic and has the cleanest props. Or ConfirmDialog, because the name matches the ticket.

Your team's convention is AlertDialog for destructive actions. The reviewer asks for changes. The next ticket starts from scratch.

The part nobody talks about

Here's what I want to draw your attention to, because it's the step the "just give the agent better tools" crowd keeps missing.

After step 5, the agent knows the props of every dialog in the library. It knows their file paths, their export names, their type signatures, their internal composition. It has read the code thoroughly.

It still doesn't know which one to pick.

Because the thing that makes AlertDialog the right answer for destructive actions isn't in AlertDialog.tsx. It isn't in the barrel export. It isn't in the TypeScript. It's in a Figma frame somewhere, or a sentence in a Notion doc, or the design system lead's head, or a convention that emerged organically from three PRs eighteen months ago and became tribal knowledge.

The agent can read every file in your repo and still not find it — because the file doesn't exist.

More tool calls don't fix this. A better prompt doesn't fix this. A more thorough AGENTS.md helps a little, until your library has sixty components and the rules file becomes its own context-window problem. The ceiling is set by what's in the files, and what's in the files isn't enough.

This is why the session ends in a guess. Not because the agent is lazy. Because it's searching a corpus that doesn't contain the answer.

Three things going wrong at once

It's worth naming each one, because they compound.

The context window is full of the wrong thing. By the time the agent is ready to write the feature, most of its context is component source code. Everything downstream — the plan, the implementation, the self-review — happens with a working memory that's mostly noise. You're paying tokens to degrade the output.

The information isn't there to find. What a component looks like when rendered, when to use it, which of four near-synonyms the team prefers — none of that is reliably encoded in the source. The agent is excavating a site that doesn't contain the artifact.

It happens every session. Agents don't remember across tasks. The next ticket that touches @acme/ui starts the same archaeology from the same blank slate. Multiply by every engineer, every day.

You end up with a workflow where most of the agent's effort on design-system work goes into rediscovering the design system, and the actual feature gets built with whatever context window is left over.

This is a retrieval problem

Notice what changed when I described the problem that way. It stopped being about the agent and started being about the index.

The agent is doing fine. Reading files and pattern-matching on names is the right strategy when the filesystem is all you have. The failure isn't in the search; it's in the corpus. If you want the agent to pick the right component on the first try, you need an index that contains the information the filesystem doesn't — appearance, intent, convention, the relationships between components that only become visible when you've seen the whole library at once.

We built Loracle because we kept watching this exact session play out.

The CLI points at your running Storybook and renders every story. It captures the rendered appearance of each component, the args and controls that define its variants, the docs and usage examples from your MDX, and the structural relationships across the library. That catalog gets published to Loracle and exposed to your agent over MCP.

Back to the ticket. With Loracle wired in, the session looks different:

get_components({
  intent: "confirmation dialog for a destructive action"
})

One call. The response names AlertDialog — and more importantly, it returns the exact props and values that produce a destructive confirmation: which variant to set, what to pass for the action button, which slot holds the description. Not a link to the docs. Not a generic usage example. The specific configuration that achieves the result the agent was asked for. The agent writes the feature. The PR uses the component the team was going to ask for anyway.

The reason one call is enough isn't magic, and it isn't a clever prompt. It's that the index contains what the filesystem doesn't. Rendered appearance, captured from the real Storybook. Usage patterns, captured from stories written by people who know the library — which means Loracle knows not just that AlertDialog exists, but what props and values produce a destructive confirmation, a permission prompt, or an unsaved-changes warning. Cross-component context, captured because the whole library was indexed together. The agent stops guessing because it stops being asked to guess.

The job the agent was hired to do

Your agent's job is to build the feature. Not to rediscover your design system every morning, not to read forty files to answer a question the files can't answer, not to ship PRs that get bounced because a naming collision sent it down the wrong path.

Give it an index that knows the answer. Let it ask.

Docs →