Injecting a Repo Map into the Agent

Agents often burn early turns on directory wandering and wrong-package guesses. A repo map is not a chat backup; it is a short terrain sketch—packages, entrypoints, ownership boundaries, and do-not-touch zones—that you inject at session start. Cursor’s Instant Grep and Explore subagent are tools for finding symbols and strings. The map is a human-agreed (or script-drafted) summary of where to start reading.

This post covers only which files · auto-generation · stale maps. System / user / project rule hierarchy and conflict priority belong to prompt-layers. Do not paste a novel map into an Always Rule; keep a short map file + an inject path. No pricing, plans, or token counts.

Which files?

One-line answer: Keep one short map file at an agreed path (e.g. docs/REPO_MAP.md, .agent/repo-map.md), and put only “read this path first” in AGENTS.md or a Project Rule. Omit full tree dumps, secrets, and generated noise.

Include vs omit:

IncludeOmit
Package/app boundaries (apps/, packages/, firmware vs host)Full dumps of node_modules/, build/, .git/
Entrypoints and one-line build/test commandsFull README / design-doc paste
Touch / do-not-touch boundaries.env values, tokens, secret URLs
Short ownership / on-call / ticket prefixesPer-file hashes and line counts
Updated stamp + tip commit/branchDeleted paths marked as “current”

Minimum schema (copy-paste):

# Repo map — <repo-slug>
Updated: <ISO date> · tip: <short sha or branch>

## Layout
- `apps/web` — Next UI; entry `apps/web/src/app`
- `packages/api` — HTTP; entry `packages/api/src/main.ts`
- `firmware/` — device; do not edit from host PRs

## Commands (cwd = repo root)
- web test: `pnpm --filter web test`
- api test: `pnpm --filter api test`

## Boundaries
- Touch: `packages/api/src/**` for API changes
- Do not touch: `firmware/**` unless ticket says so
- Secrets: never paste; names/paths only

## Inject
- Agent: read this file first (or `@docs/REPO_MAP.md`)
- Not a substitute for Instant Grep / Explore on symbols

Injection options (pick one as a team):

  1. Chat @docs/REPO_MAP.md — this task only; map is long or changes often
  2. One “read first” line in AGENTS.md — repo default; aligns with prompt-layers Project row
  3. Intelligent / globs Rule — attach the map only for apps/** work (do not put the full text in Always)
  4. Path only in a subagent brief — parent passes the path, not the whole map (subagent-brief)

Boundary vs prompt-layers: that post is where rules live (Team / Project / User / turn); this section is what the codebase terrain summary is and how you inject it. The map is a context artifact, not a rule policy.

How do you auto-generate?

One-line answer: Script a draft → humans review boundaries and commands → regenerate on structural change via CI/hooks. Dumping raw find/tree into an Always Rule is nearly forbidden.

Practical pipeline:

  1. Draft — depth-limited tree, or extract workspace package names / CMake targets / Yocto layers only
  2. Human sections — Boundaries · Commands · Do not touch (automation cannot invent these well)
  3. Stamp — Updated + tip SHA; one “map updated” line in the PR
  4. Separate from search tools — Instant Grep finds symbols/regex; Explore keeps broad search summaries out of the main context. The map narrows where to look first. It does not replace the Instant Grep index.

Generator sketch (conceptual):

# draft only — review before commit
{
  echo "# Repo map (DRAFT)"
  echo "Updated: $(date -Iseconds) · tip: $(git rev-parse --short HEAD)"
  echo
  echo "## Layout (depth 3, generated)"
  # prefer: workspace package names, not every file
  find apps packages -maxdepth 2 -type d 2>/dev/null | sort
} > docs/REPO_MAP.draft.md
# copy Boundaries/Commands from the previous map by hand

Automation alone leaves deleted packages, moved entrypoints, and forbidden paths. Treat output as draft; Boundaries review before merge is required.

What about stale maps?

One-line answer: A stale map is worse than no map. Update it in the same PR as structural changes, and tell the agent: if map and tree disagree, trust the tree and fix the map.

Stale signals:

  • Tip SHA is weeks old while apps/ was split and the map still shows a monolith
  • Map says entry src/index.ts but disk has src/main.ts
  • Deleted packages/legacy still listed under Touch
  • Full map pasted into Always Rules, fighting length limits (prompt-layers “too long”)

Refresh / retire rules:

EventAction
Package add / move / deleteUpdate Layout + Boundaries together
Build/test command changePatch Commands only
Large renameRegenerate map + human review
Map exceeds ~200 linesSplit: root summary + short per-package maps
UnsureStop injecting; verify with Explore/Grep, then fix the map

Agent one-liner (in the map or AGENTS.md):

If REPO_MAP.md disagrees with the tree, trust the tree.
Update the map (or open a follow-up) before large edits.
Do not invent packages that are not on disk.

Verification checklist (session start / structure PR):

[ ] Updated / tip is after the latest structural change?
[ ] Layout paths exist on disk?
[ ] Commands run from repo-root cwd?
[ ] Do-not-touch still valid?
[ ] No secrets / .env bodies?
[ ] Full map text not pasted into Always Rules? (path pointer OK)

FAQ

How is this different from prompt-layers?

That post is Team / Project / User / turn rule hierarchy and conflict priority. This post is the repo terrain summary (repo map): files, inject, generate, retire. “Read the map” in AGENTS.md is a prompt-layers Project placement; designing the map body is this axis.

Aren’t Instant Grep and Explore enough?

Search and broad exploration are strong. They do not know forbidden boundaries, agreed entrypoints, or team command conventions. The map is the starting point; Grep/Explore lock symbols and evidence. Use both.

Should the map be committed to git?

Commit docs/REPO_MAP.md when layout, commands, and boundaries are shared. Local-only drafts can live under gitignored .agent/. Check for secrets before commit.

What if the map eats the context window?

Keep the root to Layout · Boundaries · Commands only; put domain detail in short per-package maps or @ attach when needed. Do not put the full text in Always Rules.

Sources