Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

You get: A research summary

More like this

Ready to use: no blanks to fill in.

The prompt

codebase-tour-for-a-specific-task.md
You are a staff engineer onboarding me to a codebase I do not know. First ask me two short questions: what is the task I need to do, and what do you have access to (the repo, pasted files, or a file tree)? Wait for my answers. Then explore only what matters for that task and ignore the rest. Rules: base every claim on files you actually read and name them; mark anything inferred as an assumption; prefer the real request or data path over generic architecture descriptions; stop at the depth needed for the task. Output format: 1) Task restated in one sentence. 2) Architecture in five sentences or fewer. 3) Key files table with path, role, and why it matters for this task. 4) Data flow as a numbered list from entry point to storage or output. 5) Where to start: the first file to open and the first change to try. 6) Risks and gotchas, such as shared code, config, or missing tests. 7) Open questions to ask a teammate. The tour is good if I could start the task within ten minutes.

Example output

AI-written example

1) Task restated
Add per-email and per-IP rate limiting to POST /auth/password-reset so it allows no more than 5 requests per hour.

2) Architecture
This is a TypeScript Express API (src/) with routes, controllers, and services layered in that order. Postgres is accessed through Prisma, and Redis is used for sessions and a job queue. Middleware is registered globally in src/app.ts and per route in src/routes/. Email is sent by a BullMQ worker, not inline. Config is read from environment variables through src/config/env.ts.

3) Key files

PathRoleWhy it matters
src/routes/auth.routes.tsDeclares auth routesWhere the middleware gets attached
src/controllers/passwordReset.controller.tsValidates the body and calls the serviceShows the current error response shape
src/services/passwordReset.service.tsCreates the token and enqueues the emailThe business logic you must not break
src/middleware/rateLimit.tsExisting limiter, used only on /auth/loginTemplate to copy or extend
src/lib/redis.tsShared Redis clientBacking store for the limiter
src/config/env.tsEnv parsing with zodAdd new limit settings here
tests/auth/login.rateLimit.test.tsExisting limiter testPattern for your tests

4) Data flow

  1. POST /auth/password-reset arrives at app.ts, which runs the global JSON parser and request-ID middleware.
  2. auth.routes.ts routes it to passwordReset.controller.ts (no route-level middleware today).
  3. The controller validates { email } with zod.
  4. passwordReset.service.ts looks up the user through Prisma.
  5. It writes a hashed token to the PasswordResetToken table.
  6. It enqueues an send-reset-email job in BullMQ.
  7. The controller returns 202 with a generic message, whether or not the user exists.

5) Where to start
Open src/middleware/rateLimit.ts. The first change to try is to export a second limiter instance built from the existing factory, keyed on req.body.email plus req.ip, with a limit of 5 per 3600s. Then add it to the route in auth.routes.ts and copy the login test to confirm the 6th request returns 429.

6) Risks and gotchas

  • rateLimit.ts is shared with login. Changing the factory's signature will break that route, so add options rather than editing defaults.
  • The body is only parsed globally. Confirm the limiter runs after express.json(), or the email key will be undefined (assumption: the order in app.ts is correct).
  • The endpoint deliberately returns the same response for unknown users. The 429 must not reveal whether an email exists, so use the same key logic for all emails.
  • If the app runs behind a proxy, req.ip may be the proxy's address. I did not find trust proxy set in app.ts (assumption: production uses a load balancer).
  • There are no tests for the password reset flow itself, only for login limiting.

7) Open questions for a teammate

  • Should the limit be configurable per environment, or fixed?
  • Is there a standard 429 body or Retry-After header that clients already expect?
  • Does production sit behind a proxy or CDN, and who owns that setting?
  • Do we want a metric or alert when limits trigger?
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Use when joining an unfamiliar repo with a concrete task. Run it in a tool that can read your repo, or paste the file tree and the files you suspect are relevant.

Questions about this prompt

More in Coding

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Architecture Decision Record for a Technology Choice

Compares realistic options against your constraints and produces a decision record. The record has a weighted comparison, risks, a reversal plan, and a recommendation the team can approve or challenge.

Pull Request Review with Merge Recommendation

Reviews a diff against your standards and returns a merge, merge-with-changes, or do-not-merge recommendation. Findings are ranked by severity, with evidence, suggested fixes, and open questions.

Root Cause Analysis from Stack Trace and Logs

Turns an error report, stack trace, and logs into ranked root-cause hypotheses. Includes the cheapest checks to confirm each one, a fix proposal, and a regression test plan.

Unit Test Plan and Test Code for an Existing Function

Builds a behavior-based test matrix for a function or module and then generates test code in your framework. Covers edge cases, failures, and mocking boundaries, with coverage gaps stated honestly.

Explain This Error with Ranked Causes

Explains an error and stack trace in plain words, ranks the three most likely causes and gives a confirming check for each.

Regex with Match and Non-Match Test Strings

Writes a regex for your pattern, explains each part and provides 8 strings that should match and 8 that should not.

SQL Query from Schema and Question

Writes a SQL query that answers your question from your schema, explains each clause and suggests indexes worth adding.

Cursor .mdc Rules to Portable AGENTS.md Converter

Converts your pasted Cursor .mdc rules into a single AGENTS.md that Codex, Copilot and Gemini CLI can read, plus a table of what does not carry over.

Explain a Codebase Folder to a New Developer on Their First Day

Produces an onboarding guide for one folder of a codebase: what it does, how data moves through it, the files to read first and the traps a new developer should avoid.

90-Day Lifecycle Marketing Diagnostic and Experiment Roadmap for Onboarding and Retention

Diagnoses drop-off across the customer lifecycle from your funnel data and produces a prioritized 90-day plan of messages, triggers, and experiments with metrics so teams can decide where to invest first.