---
name: codebase-onboarding-guide
description: "Gives a new engineer a first-week path through a codebase: how to run it, where things live, how to change it safely and who to ask. Use when a new engineer joins a project and needs a guide to running, navigating and safely changing its codebase in the first week. Do not use for generating API reference docs or explaining a single function. Related topics: coding, education."
---

# Codebase Onboarding Guide

Gives a new engineer a first-week path through a codebase: how to run it, where things live, how to change it safely and who to ask.

## When to use

Use this skill when a new engineer joins a project and needs a guide to running, navigating and safely changing its codebase in the first week. Do not use it for generating API reference docs or explaining a single function.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write the day-one setup with exact commands, a success check for each and the likely failure points.
3. Map each main folder with one sentence on its role and trace one request through the layers.
4. Explain how to make a safe first change: where the test goes, how to run it, how review and release work.
5. Collect domain terms and team conventions a newcomer will meet in the first week.
6. Propose three starter tasks of rising difficulty with who to ask, and mark every gap as to be filled by the team.

## Inputs

- **Project name and purpose** (longer free text)
- **Tech stack** (free text, e.g. "Languages and frameworks and datastores")
- **Repository layout** (longer free text)
- **Setup steps as known today** (longer free text)
- **Testing and release process** (longer free text)
- **Team conventions** (longer free text)
- **Experience of the reader** (choose one: Junior, Mid level, Senior new to the stack)

## Output

An onboarding guide organised by day, with a setup section, a folder map, a first-change walkthrough, a glossary, three starter tasks and a list of contacts.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Codebase Onboarding Guide

Write an onboarding guide for new engineers on this codebase.

- Project name and purpose: {{Project name and purpose}}
- Tech stack: {{Tech stack}}
- Repository layout: {{Repository layout}}
- Setup steps as known today: {{Setup steps as known today}}
- Testing and release process: {{Testing and release process}}
- Team conventions: {{Team conventions}}
- Experience of the reader: {{Experience of the reader}}

Organise the guide as a first week. Day one: get it running locally, with exact commands, the checks that confirm success, and the three setup problems most likely to appear. Then a map of the codebase: for each main folder, one sentence on what lives there and what not to touch lightly, plus how a request or user action travels through the layers. Describe how to make a safe first change: where to write the test, how to run only it, how review works and how it ships. List the vocabulary and domain terms a newcomer will hear. Finish with a ladder of three starter tasks of rising difficulty and the people or channels to ask for each kind of help. Mark any gap in the input as "to be filled by the team" instead of guessing.

## Pitfalls

- Guessing commands that were not supplied, which sends a newcomer down a failing setup on day one.
- Listing every folder equally, when the useful guide highlights the few places most changes happen.
- Skipping how code ships, so the first merged change stalls at an unknown release step.