Home/ Part VI — Practical Vibe Coding Workflows (The Stuff You'll Actually Use Daily)/18. Vibe Coding for Existing Codebases/18.1 "Repo tour" prompts that work

18.1 "Repo tour" prompts that work

Overview and links for this section of the guide.

On this page

Goal: orient fast without dumping the whole repo

A “repo tour” is how you bootstrap a shared mental model with the assistant. The goal is not to read every file. The goal is to identify:

  • what the system does,
  • where the entrypoints are,
  • where the important modules live,
  • what the risky areas are,
  • how to run tests and reproduce behavior.
Repo tours reduce context needs

Once you have a map, you can paste only relevant slices for later tasks. Without a map, you paste random files and the model guesses.

What to provide (minimal context pack)

Start with a minimal pack:

  • README: how to run/test
  • file tree: top-level and key directories
  • entrypoint files: main modules, server startup, CLI entry
  • package/build config: package.json, pyproject.toml, etc. (only if relevant)
  • constraints: language/runtime, “diff-only,” “no new deps,” files in scope (if already decided)

If the repo is huge, provide a shallow file tree first. Then drill down.

Don’t paste the entire repo

Flooding context increases confusion and reduces accuracy. Start with a map and a few key files.

The questions you want answered

A good repo tour answers:

  • Entrypoints: how does the app start?
  • Core modules: what are the main subsystems?
  • Data flow: where does data enter, transform, and exit?
  • Dependencies: what major libraries/frameworks are used?
  • Testing: how do we run tests? where are they?
  • Risk zones: where are the brittle or complex parts?
  • Change strategy: what’s a safe “first small change” pattern?

Copy-paste “repo tour” prompts

Prompt A: repo tour output

I need a repo tour. Do not propose code changes yet.

Context:
- README: (paste)
- File tree: (paste)
- Entrypoints/config files: (paste the minimal set)

Output:
1) 10–20 bullet summary of what the repo does.
2) List entrypoints and how to run the app locally.
3) List test commands and where tests live.
4) Provide a file map: 1–2 sentences per important directory/module.
5) Identify the 3–7 riskiest areas (why risky).
6) List questions/unknowns that block confident changes.

Prompt B: request a deeper slice

Based on the repo tour, tell me the minimum additional files you need to understand Module X.
List file paths only and explain why each is needed.
Stop after the list.
Ask for the “minimum additional files”

This is a context discipline trick: you make the model justify why it needs more context. That keeps iterations tight.

What a good repo tour output looks like

A good tour is structured and actionable:

  • clear entrypoint commands you can run,
  • a module map you can reference later,
  • risk zones that match real complexity,
  • explicit unknowns and questions instead of guessing.

If the tour is vague or wrong, it’s usually missing key files or you provided too much noise.

Common mistakes (and fixes)

Mistake: pasting too much

Fix: start with file tree + entrypoints + README. Add slices incrementally.

Mistake: asking for changes during the tour

Fix: separate understanding from changing. First tour/map, then plan, then diff-only changes.

Mistake: not asking for run/test commands

Fix: always demand verification instructions. Otherwise you’re building on vibes.

Where to go next