# /map: give Claude a one-page map of your project so it searches less

> Source: <https://gist.github.com/conradcaffier03/e3d6fd365f58694b0a11a682b07894cb>
> Published: 2026-10-11 12:02:34+00:00

Every Claude Code session starts with an empty memory of your files. Claude does **not** reread your whole
project at the start. It loads your CLAUDE.md, then searches and opens files when a task needs them.
That search is what you pay for, again in every new session.

A map is one short file that says what lives where. Claude reads it at the start and goes to the right file faster.

**My test (11 Oct 2026):** an open-source online store (78 files), 3 everyday tasks, each run twice with and without a map.
Same answers, all correct. With the map: **24% fewer tool calls, 21% fewer input tokens processed, 9% faster.**
Best task: 1 search instead of 2, 34% fewer tokens. The dollar cost only dropped 2 to 10%,
because Claude Code already caches repeated context cheaply. No 70% here.

Save the `map` skill (`SKILL.md` in this gist) as:

```
~/.claude/skills/map/SKILL.md
```

Use `.claude/skills/map/SKILL.md` inside a project instead if only that project should have it.

Open Claude Code in your project folder and type:

```
/map
```

Claude writes `MAP.md` (40 to 80 lines: what the project is, folders, key files, where to change things,
which settings exist) and adds this line to your `CLAUDE.md`:

```
Project map: @MAP.md. Check it before searching. If it is wrong, fix MAP.md in the same task.
```

The `@` makes Claude Code load the map at the start of every session.

Start a new session and run `/context`. Your `CLAUDE.md` should be listed under **Memory files**.
Then ask something like "where do I change X?" and watch: Claude should open the right file with fewer searches.

Run `/map` again after you add, move or delete folders or important files. It updates the map instead of rewriting it.

- **Small projects don't need it.** Under ~30 files, Claude finds things fast anyway.
- **It costs a little every session.** My map was about 1,900 tokens, loaded each time. It pays off when tasks would
otherwise need several searches.
- **A wrong map is worse than none.** That's why the CLAUDE.md line tells Claude to fix it when it's off.
- **Making the map costs once.** About $0.27 and 24 seconds in my test.
- **Bigger wins usually come from elsewhere:** specific prompts ("fix the bug in auth.ts"),`/clear` between unrelated tasks,
and fewer always-loaded skills and MCP servers. In my setup, ~91,000 tokens were loaded before Claude opened a single file.

Sources: code.claude.com/docs/en/memory (what loads at start, `@` imports), /context-window (what loads before you type),
/costs (a project-overview skill saves exploring). Numbers are from one project on one machine: mine.

— Conrad · @buildwith.conrad