Codebase Onboarding

Goal: give the user an accurate mental model fast, grounded in real files — not a generic description of the framework.

1. Survey (cheap, broad)

Run scripts/project_map.sh from the repo root. It prints the tree (ignoring vendor dirs), manifests, scripts, and largest source files.

Then read, in order: README*, package.json / pyproject.toml, CLAUDE.md / AGENTS.md / CONTRIBUTING.md if present, .env.example, docker-compose.yml, CI config (.github/workflows/).

2. Identify the shape

Decide what kind of project it is from evidence:

• Framework: Next.js (app/ or pages/), Vite/React, Express/Fastify/NestJS, FastAPI, Django (manage.py, settings.py), Flask, CLI tool, library, monorepo (turbo.json, pnpm-workspace.yaml, nx.json).
• Entry points: main/bin in package.json, src/index.ts, server.ts, main.py, app.py, manage.py, __main__.py.
• Data layer: Prisma/Drizzle/TypeORM/Mongoose, SQLAlchemy/Django ORM, migration folders.
• External services: env vars and SDK imports.

3. Trace one real flow end to end

Pick the most central feature (or the one the user cares about) and follow it: route/handler → service/business logic → data access → response. Name the actual files and functions. One concrete trace teaches more than ten folder descriptions.