Onboarding new developers with AI: from weeks to days

Traditional developer onboarding looks like this: read the wiki (outdated), go through the README (incomplete), find a mentor (busy), and in two weeks you might start being productive. Often longer.

With AI tools like Claude Code and Cursor, this speeds up dramatically. A newcomer can ask the code directly — 'How does authorization work in this project?' — and get a contextually relevant answer in seconds. Not from a 2023 wiki, but from the current code.

What AI can do during onboarding

• Explain project architecture from actual code
• Find where things happen ('where are payments processed?')
• Describe data flow from request to response
• Show examples of how the team handles typical problems
• Explain what a specific function or module does
• Generate an overview map of the project

# Prompts for onboarding a new person:

# Day 1 — understanding the project
"Read CLAUDE.md and README. Then explain:
1. What this project does
2. The tech stack
3. How to run it locally
4. Main modules and what each does"

# Day 2 — understanding architecture
"Draw the data flow for [main feature].
From HTTP request to database and back.
Mention all middleware and service layers."

# Day 3 — first task
"Look at this bug report: [description].
Find relevant code, explain the cause,
and suggest a fix. Write a test."

Claude Code in the terminal answers questions about the current code — not outdated documentation. Cursor Chat does the same in the editor. Both read your project and answer in context.

What AI cannot do during onboarding

Explain WHY the team chose a certain approach. Who owns which part. What the unwritten conventions are ('we never do this on Friday'). What the team's rollback policy is. For that you still need a mentor.

Result: the mentor handles only the interesting stuff, not file navigation. The newcomer is less dependent and more self-sufficient. Both are happier.

How to prepare your project for AI onboarding

1. Add CLAUDE.md to the project

CLAUDE.md at the project root is persistent context for AI agents — but also excellent documentation for new people. Stack, build commands, conventions, key decisions. AI reads it on every run, so the newcomer gets consistent information.

2. Structure README for machine reading

Add sections: Quick Start (how to run), Architecture (main modules), Key Files (where to look first), Contacts (who owns what). AI reads the README and the newcomer gets a personalized project guide.

# README.md — onboarding-ready structure

## Quick Start
npm install && npm run dev  # localhost:3000

## Architecture
- src/services/ — business logic
- src/api/ — REST endpoints
- src/models/ — Prisma schema and types

## Key Files (start here)
- src/services/auth.ts — authentication and JWT
- src/services/billing.ts — payments and subscriptions
- src/api/middleware.ts — request pipeline

## Owners
- Auth: @jan
- Billing: @petra
- Infrastructure: @martin

3. Create an onboarding checklist

A simple task list for the first week. AI helps with every item — the newcomer uses AI to understand code instead of waiting for a mentor.

• Day 1: Get the project running locally, review README and CLAUDE.md with AI
• Day 2: Understand the main architecture — ask AI about data flow
• Day 3: Review the last 3-5 PRs — understand team conventions
• Day 4: Fix a simple bug with AI help — full cycle from understanding to merge
• Day 5: Do a code review of a colleague's PR with AI — learn what the team expects

Real results

Teams I work with report 40-60% reduction in onboarding time after introducing AI-supported onboarding. A new person is productive in 5-7 days instead of 2-3 weeks. The mentor spends 2-3 hours with the newcomer instead of 2-3 days.

The best onboarding is one where the newcomer can answer 80% of their questions themselves. AI makes this possible — and the mentor can focus on the 20% that AI can't handle.

The investment in preparing your project for AI onboarding (CLAUDE.md, structured README) pays off with every new team member. And a bonus: it improves work for existing team members too.