# Onboard New Hires With an AI That Knows Your Runbooks

A new hire's first week is a list of questions. How do we deploy. Why is the payments service set up like that. Who owns the search cluster. What do we do when the nightly job fails. Every answer lives in someone's head, so they ask that someone. Onboarding a new engineer means turning a senior one into a help desk.

Their AI can't help, because it starts from zero. It knows the language and the framework. It knows nothing about your team: your runbooks, your decisions, the reasons behind how things are set up. So the most useful assistant they have is useless for exactly the questions onboarding is made of.

It doesn't have to be. Put your team's runbooks and decisions in a shared knowledge base, connect it to Claude and ChatGPT with a [built-in MCP server](/docs/what-is-mcp), and a new hire's own assistant can answer from how your team actually works, from their first day.

## Where onboarding knowledge actually lives

Not in the onboarding doc. That was written once, for the last hire, and it's already wrong in three places.

It lives in a wiki page nobody updated, a pinned Slack message, a diagram from a planning meeting, and the two engineers who have been here longest. New hires reconstruct it by interrupting people. Seniors answer the same questions every few months. The knowledge never gets written down because writing it down never pays off, until you realize it's the same fifteen questions every single time.

Those fifteen answers are your onboarding. Write them down once, somewhere an AI can read them, and a lot of those questions go to an assistant instead of a person.

## What to put in the shared base

Aim for the questions a new hire actually asks in week one.

- **Runbooks.** Deploys, releases, on-call, what to do when the common things break.
- **Decisions.** Why the architecture is the way it is, what was tried and rejected, so a new hire understands the reasons instead of just the shape.
- **Ownership.** Who owns which service, who is backup, who to escalate to.
- **The unwritten stuff.** The conventions, gotchas, and "we don't do it that way anymore" that usually take months to absorb.

Give each folder [team AI instructions](/docs/ai-instructions), and an assistant working in those folders follows your conventions, the new hire's included.

## How the first week changes

The new hire connects their own [Claude](/docs/claude) or [ChatGPT](/docs/chatgpt) to the team knowledge base. Now the assistant they already use can answer the onboarding questions.

They ask how deploys work and get your actual runbook, not a generic guess. They ask why payments uses event sourcing and get the decision and its reasoning. They ask who owns search and get a name. The senior engineer who used to field all of this gets their afternoon back, and the new hire ramps by asking questions freely instead of rationing them to avoid being a bother.

The base stays current on its own terms, too. Because the team's AI can read it whenever someone asks, keeping a runbook accurate pays off immediately, not eventually. A wiki that gets read is a wiki that gets maintained.

## Setting it up

1. Create a team and folders for runbooks, decisions, and ownership. The [set up your team](/docs/set-up-a-team) guide is the quickstart.
2. Write down the fifteen questions every new hire asks. That is the first version of your onboarding base.
3. Add each new hire as a member. They connect their own AI; [per-folder roles](/docs/teams-and-sharing) keep them scoped to what they should see.

Seats are per person, and a team is free for its first 25 team notes, so you can stand this up before you spend anything. The [team billing](/docs/team-billing) page has the details.

## The point

Onboarding is slow because the knowledge is trapped in people. A new hire's AI could answer most of their week-one questions, if only it could read your runbooks.

So let it. Give your team a [shared knowledge base every assistant can read](/blog/team-knowledge-base-for-claude-and-chatgpt), and see [Hjarni for engineering managers](/use-cases/engineering-managers) for how the rest of the team puts it to work.

Write it down once. Every new hire's AI can read it.