EP 05

Without a Map, You Get Lost

May 2026·5 min read·#architecture#documentation#design-system

When the component count hit sixteen, something shifted.

"I built this. And I don't know it anymore."

What happens when a project grows

In EP 04, I talked about context.md — how thinking changes the document first, and only then do you call Claude Code.

But that wasn't enough on its own.

context.md is about what to build. As the project grows, a different question emerges: where to fix it.

Say a bug shows up in the chat UI. Is it in the mobile app? The API server? Pepper Core? Without knowing that, you can't give Claude Code a useful starting point. "Fix the bug" with no context is an invitation for Claude Code to start opening the wrong files.

That's why I made PEPPER_MAP.

PEPPER_MAP — a nervous system diagram

C01 through C16. Sixteen components, each with a name, key file paths, and dependency relationships.

| C01 | LLM Router          | packages/llm/src/router.ts         |
| C05 | Pepper Core         | apps/core/src/index.ts             |
| C06 | Triage Engine       | apps/core/src/triage.ts            |
| C13 | Realtime Layer      | apps/mobile/src/components/...     |

When a new session starts, hand this map to Claude Code and it knows exactly where to look. "Realtime messages not coming through" → C13 first. "Pepper response is slow" → C01 and C05.

One rule holds everything together: when you modify a component, update PEPPER_MAP at the same time. A map that lags behind the code is useless.

UI Spec — context.md for screens

Same logic, different problem.

Every time I asked Claude Code to build a screen, it came out slightly different. Buttons a different shade, font sizes off, inconsistent spacing. I couldn't explain "use burgundy for buttons, cream for backgrounds" every single time.

The UI spec locks down the entire design system.

--cream:        #F5F0E8   app background
--burgundy:     #7A1E2E   buttons, active state
--warm-black:   #1A1714   body text

Color tokens, bubble border-radius, tab bar structure, avatar sizes — all of it. Hand Claude Code this document and the same design comes out every time. Context drift happens in UI too. I didn't know that until I experienced it.

The principle from EP 04 — document before code — expanded into two more documents here. A system map, and a visual blueprint.

Next is where things got genuinely hard.

Next→EP 06·Connected But Nothing's Coming Through