thinkhard.SI

Prompt repository Engineering & code

Brief a coding agent to walk you through an unfamiliar codebase without changing it

You are about to work in a repository you do not know and want Claude Code, Codex, Cursor or another coding agent to map it and trace one flow, read-only.

Registry no.
ENG-050
Collection
Engineering & code
Laid out for
Coding agent
Score
10 out of 10
Blanks to fill
4

Engineering & codeCode agent

The prompt

Score 10 of 10, Excellent

Use it when You are about to work in a repository you do not know and want Claude Code, Codex, Cursor or another coding agent to map it and trace one flow, read-only.

  • {{upcoming_task}}
  • {{what_i_know}}
  • {{flow_to_trace}}
  • {{allowed_commands}}
Full prompt and why it works
Prompt
Goal: Give me a guided tour of this repository, so that I can start {{upcoming_task}} knowing where things live and how the parts connect. This is a read-only task: change nothing.

Context:
- What I already know about the codebase and its stack: {{what_i_know}}
- The flow I most need to understand, traced end to end: {{flow_to_trace}}
- Commands you may run: read-only ones such as listing files, searching, git log and git blame, plus {{allowed_commands}}.

Constraints:
- Do not edit, create, move or delete any file, and do not install anything. Do not run commands that write to a database, call external services, send messages or push to git.
- Base every statement on code you read, with the file path and line numbers. When you infer something from a name or a comment without reading the code behind it, mark it (inferred).
- Skip generated files, vendored code, build output and lockfiles unless they matter to the flow.

Work in this order:
1. Start from README.md and the build manifest (such as package.json or pyproject.toml) to find the entry points, then write a map of the top-level directories that matter, one line each.
2. Trace the flow above step by step from where it starts to where it ends (for example from a route handler through services to the database and back), naming each function and file it passes through.
3. Note the conventions a newcomer must follow: how errors are handled, how config and environment variables are read, how tests are written and run, and how code is laid out.
4. Point to the files my task will most likely touch, and what could break if I change them.
5. List gotchas, such as hidden side effects, global state, misleading names or dead code that still looks live.
6. List up to 5 questions for the team that the code does not answer.

Done when:
- The tour is in your final message, under 1,000 words, with the headings Map, Flow, Conventions, Where my task fits, Gotchas, Questions.
- Every claim has a file and line reference or an (inferred) mark.
- git status shows no changes. Verify this as your last step and include the output.

If the flow I named does not exist as described, or you find two competing implementations, stop and tell me what you found rather than picking one.

Variables

{{upcoming_task}}
What you are about to do, for example "adding a discount code field to checkout".
{{what_i_know}}
What you already know, for example "it is a Django app with a React front end; I have not seen the code".
{{flow_to_trace}}
One real path to follow, for example "what happens when a user submits the signup form".
{{allowed_commands}}
Anything else it may run, for example "the unit tests, which use a local test database", or "nothing else".

Why it works

  • What to avoid. The task is read-only and ends by checking git status, so a tour never turns into unreviewed changes.
  • What good looks like. Every claim carries a file and line reference or an (inferred) mark, so you can tell what the agent read from what it guessed from names.
  • Who it's for. Naming your next task and one flow to trace keeps the tour on the parts you will touch, not a survey of every folder.

How to use it

  1. Press Fill in blanks and type your details into each blank. What you type stays in this browser.
  2. Copy the filled prompt into the AI tool you already use, such as ChatGPT, Claude or Gemini, or open it in the Grader or the Prompt Tester here.
  3. Before you rely on it, try it on three or four real examples. The Prompt Tester runs them all at once and shows which ones go wrong.
Use it from code

Get this prompt as JSON from the free REST API, with your own text in the blanks, or let an AI assistant fetch it through the MCP server. No key.

curl -s https://thinkhard.si/api/v1/prompts/coding-agent-codebase-tour

With the MCP server added to Claude, ChatGPT, Cursor or VS Code, call get_prompt with {"prompt": "coding-agent-codebase-tour"}, or just ask for it by name.