Project Onboarding Briefing

Explore a codebase and deliver a structured onboarding briefing directly in the conversation. The goal is to take a developer from "never seen this repo" to "knows enough to be dangerous" in a single session. No files are written to the project.

The target audience is an experienced engineer who is smart but has zero context on this specific project. Brief them like a knowledgeable colleague would: direct, specific, and focused on what they actually need to start contributing.

Workflow

Follow these two phases in order. Don't start briefing before you've finished exploring.

Phase 1: Explore the Codebase

Start by running the metadata gathering script for a quick orientation:

bash scripts/gather_metadata.sh [project_root]

If the script isn't available (e.g. running outside Claude Code), gather the same information manually using Bash, Glob, and Grep.

Then dig into the actual code. Read key files, don't just look at directory listings. Your goal is to answer these questions:

Project Identity

• What does this project do? Who is it for?
• What is the business domain?
• Is there a README, wiki, or any existing documentation?

Architecture

• What's the architectural pattern? (monolith, microservices, serverless, modular, etc.)
• What are the major components/modules and their responsibilities?
• How do they communicate? (HTTP, gRPC, message queue, direct import, etc.)
• Where is the entry point? (main function, index file, app bootstrap)

Data

• What database(s) are used? Where are the models/schemas defined?
• What are the core entities and their relationships?
• Are there migrations? Where do they live?

External Integrations

• What third-party APIs or services does this project talk to?
• Where are API clients or SDK wrappers defined?
• What authentication methods are used? (OAuth, API keys, JWT, etc.)

Development Workflow

• How do you run the project locally?
• What test framework is used? Where do tests live? How do you run them?
• What's the branch/PR strategy? (look at git history, branch names, CI config)
• What linting/formatting tools are configured?
• How does deployment work? (check CI/CD config files)

Conventions & Patterns

• What naming conventions are used for files, functions, variables?
• What patterns recur? (dependency injection, repository pattern, hooks, middleware, etc.)
• Are there shared utilities or helper modules?

Where to look (in priority order):

1. README.md and any existing docs/ folder
2. Entry points: main.go, index.ts, App.kt, main.py, etc.
3. Package manifest: package.json, go.mod, build.gradle.kts, Cargo.toml
4. Configuration files: tsconfig.json, .env.example, docker-compose.yml
5. CI/CD config: .github/workflows/, .gitlab-ci.yml, azure-pipelines.yml
6. Database: migrations/, models/, schema/, prisma/, drizzle/, etc.
7. API layer: routes/, handlers/, controllers/, api/, graphql/
8. Core business logic: services/, domain/, core/, lib/
9. Test files: patterns like .test., .spec., *_test.go, *Test.kt

Skim entry points, route definitions, database models, and a few representative service files to understand the patterns in use.

Phase 2: Deliver the Briefing

Present the briefing directly in the conversation using the structure in references/briefing-structure.md. Adapt to the project — skip sections that don't apply, go deeper on areas that are complex or unusual.

Briefing rules:

• Be specific. Reference actual file paths, actual command names, actual URLs.
• Don't guess. If you can't determine something from the code, say so. It's better to say "I couldn't find how auth works — you'll want to ask the team about that" than to speculate.
• Don't pad. If a section has nothing useful, skip it.
• Use tables for structured info (tech stack, env vars, scripts, integrations).
• Include ASCII diagrams for architecture and data flow where they help.
• Keep the tone direct and practical. No marketing language, no filler.
• Reference file paths relative to the project root so the developer can jump straight to the relevant code.

After the briefing, offer to go deeper. The developer might want to drill into a specific component, trace a particular data flow, or understand a pattern they didn't expect. The briefing is the starting point, not the end of the conversation.

Important

• Do NOT create any files in the project. The briefing lives in the conversation only.
• Do NOT include sensitive values (API keys, passwords, tokens) in the briefing, even if found in config files.
• If the project has good existing documentation, summarize it and point the developer to it rather than repeating everything.
• If you can't access certain parts of the codebase (private packages, external services), call that out so the developer knows what gaps to fill by asking the team.